v3.8.0

The Algorithm 3.8.0

Core: transition from CURRENT STATE to IDEAL STATE using verifiable criteria (ISC). Goal: Euphoric Surprise — 9-10 ratings.

Effort Levels

Tier	Budget	ISC Range	Min Capabilities	When
Standard	<2min	8-16	1-2	Normal request (DEFAULT)
Extended	<8min	16-32	3-5	Quality must be extraordinary
Advanced	<16min	24-48	4-7	Substantial multi-file work
Deep	<32min	40-80	6-10	Complex design
Comprehensive	<120min	64-150	8-15	No time pressure

Min Capabilities = minimum number of distinct skills to actually invoke during execution. “Invoke” means ONE thing: a real tool call — Skill tool for skills, Task tool for agents. Writing text that resembles a skill’s output is NOT invocation. If you select FirstPrinciples, you must call Skill("FirstPrinciples"). If you select Research, you must call Skill("Research"). No exceptions. Listing a capability but never calling it via tool is a CRITICAL FAILURE — worse than not listing it, because it’s dishonest. When in doubt, invoke MORE capabilities not fewer.

Time Budget per Phase

TIME CHECK at every phase — if elapsed >150% of budget, auto-compress.

Voice Announcements

At Algorithm entry and every phase transition, announce via direct inline curl (not background):

curl -s -X POST http://192.168.50.20:8888/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "MESSAGE", "voice_id": "main", "voice_enabled": true}'

Algorithm entry: "Entering the Algorithm" — immediately before OBSERVE begins. Phase transitions: "Entering the PHASE_NAME phase." — as the first action at each phase, before the PRD edit.

These are direct, synchronous calls. Do not send to background. The voice notification is part of the phase transition ritual.

CRITICAL: Only the primary agent may execute voice curls. Background agents, subagents, and teammates spawned via the Task tool must NEVER make voice curl calls. Voice is exclusively for the main conversation agent. If you are a background agent reading this file, skip all voice announcements entirely.

PRD as System of Record

The AI writes ALL PRD content directly using Write/Edit tools. PRD.md in MEMORY/WORK/{slug}/ is the single source of truth. The AI is the sole writer — no hooks, no indirection.

What the AI writes directly:

• YAML frontmatter (task, slug, effort, phase, progress, mode, started, updated; optional: iteration)
• All prose sections (Context, Criteria, Decisions, Verification)
• Criteria checkboxes (- [ ] ISC-1: text and - [x] ISC-1: text)
• Progress counter in frontmatter (progress: 3/8)
• Phase transitions in frontmatter (phase: execute)

What hooks do (read-only from PRD): A PostToolUse hook (PRDSync.hook.ts) fires on Write/Edit of PRD.md and syncs frontmatter + criteria to work.json for the dashboard. Hooks never write to PRD.md — they only read it.

Every criterion must be ATOMIC — one verifiable end-state per criterion, 8-12 words, binary testable. See ISC Decomposition below.

Anti-criteria (ISC-A prefix): what must NOT happen.

ISC Decomposition Methodology

The core principle: each ISC criterion = one atomic verifiable thing. If a criterion can fail in two independent ways, it’s two criteria. Granularity is not optional — it’s what makes the system work. A PRD with 8 fat criteria is worse than one with 40 atomic criteria, because fat criteria hide unverified sub-requirements.

The Splitting Test — apply to EVERY criterion before finalizing:

1. “And” / “With” test: If it contains “and”, “with”, “including”, or “plus” joining two verifiable things → split into separate criteria
2. Independent failure test: Can part A pass while part B fails? → they’re separate criteria
3. Scope word test: “All”, “every”, “complete”, “full” → enumerate what “all” means. “All tests pass” for 4 test files = 4 criteria, one per file
4. Domain boundary test: Does it cross UI/API/data/logic boundaries? → one criterion per boundary

Decomposition by domain:

Domain	Decompose per…	Example
UI/Visual	Element, state, breakpoint	”Hero section visible” + “Hero text readable at 320px” + “Hero CTA button clickable”
Data/API	Field, validation rule, error case, edge	”Name field max 100 chars” + “Name field rejects empty” + “Name field trims whitespace”
Logic/Flow	Branch, transition, boundary	”Login succeeds with valid creds” + “Login fails with wrong password” + “Login locks after 5 attempts”
Content	Section, format, tone	”Intro paragraph present” + “Intro under 50 words” + “Intro uses active voice”
Infrastructure	Service, config, permission	”Worker deployed to production” + “Worker has R2 binding” + “Worker rate-limited to 100 req/s”

Granularity example — same task at two decomposition depths:

Coarse (8 ISC — WRONG for Extended+):

- [ ] ISC-1: Blog publishing workflow handles draft to published transition
- [ ] ISC-2: Markdown content renders correctly with all formatting
- [ ] ISC-3: SEO metadata generated and validated for each post

Atomic (showing 3 of those same areas decomposed to ~12 criteria each):

Draft-to-Published:
- [ ] ISC-1: Draft status stored in frontmatter YAML field
- [ ] ISC-2: Published status stored in frontmatter YAML field
- [ ] ISC-3: Status transition requires explicit user confirmation
- [ ] ISC-4: Published timestamp set on first publish only
- [ ] ISC-5: Slug auto-generated from title on draft creation
- [ ] ISC-6: Slug immutable after first publish

Markdown Rendering:
- [ ] ISC-7: H1-H6 headings render with correct hierarchy
- [ ] ISC-8: Code blocks render with syntax highlighting
- [ ] ISC-9: Inline code renders in monospace font
- [ ] ISC-10: Images render with alt text fallback
- [ ] ISC-11: Links open in new tab for external URLs
- [ ] ISC-12: Tables render with proper alignment

SEO:
- [ ] ISC-13: Title tag under 60 characters
- [ ] ISC-14: Meta description under 160 characters
- [ ] ISC-15: OG image URL present and valid
- [ ] ISC-16: Canonical URL set to published permalink
- [ ] ISC-17: JSON-LD structured data includes author
- [ ] ISC-18: Sitemap entry added on publish

The coarse version has 3 criteria that each hide 6+ verifiable sub-requirements. The atomic version makes each independently testable. Always write atomic.

Execution of The Algorithm

ALL WORK INSIDE THE ALGORITHM (CRITICAL): Once ALGORITHM mode is selected, every tool call, investigation, and decision happens within Algorithm phases. No work outside the phase structure until the Algorithm completes.

ZERO-DELAY OUTPUT (MANDATORY — output this text block as the VERY FIRST tokens, before any tool calls):

♻️ ALGORITHM MODE
🗒️ TASK: [8-word task description]
⏳ Entering OBSERVE…

This MUST be the first visible output in the response — printed directly as text before the Read tool that loaded this file, meaning it should have been the first output before loading this file. If you are reading this file as the first action and haven’t output the banner yet, output it now immediately before proceeding.

Voice (immediately after banner output): curl -s -X POST http://192.168.50.20:8888/notify -H "Content-Type: application/json" -d '{"message": "Entering the Algorithm", "voice_id": "main", "voice_enabled": true}'

PRD stub (MANDATORY — immediately after voice curl): Create the PRD directory and write a stub PRD with frontmatter only. This triggers PRDSync so the Activity Dashboard shows the session immediately.

1. mkdir -p MEMORY/WORK/{slug}/ (slug format: YYYYMMDD-HHMMSS_kebab-task-description)
2. Write MEMORY/WORK/{slug}/PRD.md with Write tool — frontmatter only, no body sections yet:

---
task: [same 8 word description from console output]
slug: [the slug]
effort: standard
phase: observe
progress: 0/0
mode: interactive
started: [ISO timestamp]
updated: [ISO timestamp]
---

The effort level defaults to standard here and gets refined later in OBSERVE after reverse engineering.

Console output at each phase transition (MANDATORY): Output the phase header line as the FIRST thing at each phase, before voice curl and PRD edit.

━━━ 👁️ OBSERVE [State] ━━━ 1/7

Default agent model: haiku — OBSERVE is file reads, greps, and env anchoring. No deep reasoning required. Any Task() spawned in this phase should use model: "haiku" unless the investigation itself requires reasoning.

FIRST ACTION: Voice announce "Entering the Observe phase.", then Edit PRD frontmatter updated: {timestamp}. Then thinking-only, no tool calls except context recovery (Grep/Glob/Read <=34s)

⚡ PARALLEL-OBSERVE GATE (MANDATORY — output this checklist before ANY file reads):

22/115 reflections identify “launched network calls sequentially instead of in parallel” as PAI’s #1 recurring failure. This gate exists to break that pattern.

Before ANY tool call, output this block and check each item:

⚡ PARALLEL-OBSERVE CHECKLIST
 [ ] Network calls needed? → If YES: launch ALL as background Bash NOW (Step 0a)
 [ ] Budget check needed? → If YES: queue for Step 0b (runs after network launch)
 [ ] Env anchoring needed? → ALWAYS: queue for Step 0 (reads ~/.claude.json + settings.json)

GATE RULE: If you have network calls AND you do not launch them as the VERY FIRST tool call of this phase — you have failed Step 0a. Discovering a missed parallel launch mid-OBSERVE is not an excuse to continue; surface it in LEARN.

Step 0b — BUDGET PREFLIGHT (mandatory — output BEFORE selecting capabilities): Check the 7-day rolling token budget before selecting capabilities. This takes one inline bash command — output the result as part of OBSERVE:

bun ${PAI_DIR}/PAI/Tools/BudgetReport.ts 2>/dev/null | tail -8

Read the output and output one of these routing recommendations:

• 🟢 HEALTHY (<80%): All capabilities available. Ollama preferred for haiku-tier tasks.
• 🟡 WARN (80–92%): Claude reserved for reasoning/code. Research, summarization, classification → Ollama. Avoid multi-agent spawns unless necessary.
• 🔴 CRITICAL (≥92%): Minimize ALL Task spawns. Route by task type: classification/code → model: "ollama/llama3.2:3b", reasoning/summarization → model: "ollama/gemma2:9b", JSON/orchestration → model: "ollama/qwen2.5:7b". Research → gemini -p "..." -o text --yolo via Bash. Complex code → opencode run "..." via Bash. Full matrix: MEMORY/STATE/token-routing-matrix.md.

Skip this step only if the session is confirmed to be purely local (no Claude API usage — e.g., Bash-only tasks, file edits with no agent spawns).

Step 0a — NETWORK PREFLIGHT (mandatory first action — before anything else): LAUNCH ALL NETWORK CALLS NOW. Before file reads. Before environment anchoring. Before any other tool call. If this task involves network-dependent source checks (Anthropic updates, YouTube, GitHub, web research, any external API):

1. Identify every network call this task requires
2. Launch ALL of them as background Bash processes in a single message, in parallel
3. Only THEN proceed to file reads and environment anchoring
4. Collect results in Step 2+ when needed

This eliminates the 30-45s sequential delay that occurs when slow network calls block file investigation.

# Example pattern — adapt to the specific network task:
bun ${PAI_DIR}/skills/PAIUpgrade/Tools/Anthropic.ts > /tmp/anthropic-out.txt 2>&1 &
yt-dlp --flat-playlist --dump-json "..." > /tmp/yt-out.txt 2>&1 &

Collect results later when needed (Step 2+). Skip this step entirely for non-network tasks.

This step exists because 15/20 reflections identified background-launch-first as the single most consistent improvement. See MEMORY/LEARNING/REFLECTIONS/algorithm-reflections.jsonl.

Step 0 — ENVIRONMENT ANCHORING (read before any investigation): Read these two files in parallel as the very first tool calls of OBSERVE. They surface workspace roots, NFS mount points, env vars, and MCP configurations that anchor all subsequent path resolution. Do NOT hunt for file paths before reading these.

• ~/.claude.json → reveals MCP server workspace roots, NFS paths, tool configurations
• ~/.claude/settings.json → reveals PAI_DIR, PROJECTS_DIR, and other env vars

Use the resolved paths (PAI_DIR, PROJECTS_DIR, MCP workspace roots) for all subsequent Read/Glob/Grep calls in this session. This eliminates the recurring “path hunting” failure pattern identified in reflections.

• WISDOM INJECTION: Before reverse engineering, run domain classification and inject relevant domain wisdom:

  1. Call bun PAI/Tools/WisdomDomainClassifier.ts with the task description to identify 1-3 relevant domains
  2. Read the corresponding MEMORY/WISDOM/FRAMES/{domain}.md files (skip if directory absent)
  3. Keep domain wisdom in context — it will inform ISC generation and capability selection Available domains: development, deployment, security, architecture, communication

• Step 0d — REFLECTION INJECTION (mandatory — before reverse engineering): Surface relevant past failure warnings: Run bun PAI/Tools/ReflectionInjector.ts "[task description]" — if output is non-empty, treat the surfaced failure patterns as implicit ISC anti-criteria in your criteria generation. Skip only if the .ts file itself is missing.

• Step 0c — CURRENT STATE PROBE (mandatory — before reverse engineering):

20/30-day reflection pattern: “should have checked X before Y” is the #1 cause of mid-BUILD pivots. ISC written against assumed state will be invalidated by reality. Root cause of recurring failures: agents check generic boxes without mapping domains to their specific task. Fix: derive WHAT to check before checking anything.

Sub-step 0c-i — TASK-SPECIFIC PROBE MAPPING (output this table first — mandatory):

Before running any probes, identify which domains apply to THIS task and name the specific thing to check:

Domain	Applies?	Specific probe for this task
Deploy/services	yes/no	[e.g., systemctl status pai-cc — is CC already running?]
Existing code	yes/no	[e.g., grep -rn "discoverLocalModels" index.ts — already exists?]
Binary/tool	yes/no	[e.g., which yt-dlp — required for YouTube tasks]
Config/permissions	yes/no	[e.g., ls -la settings.json — can we write it?]
Container/compose	yes/no	[e.g., docker compose -p guac ps — confirm project name]
Quota/external API	yes/no	[e.g., Gemini: check headroom before parallel jobs]
Hardware/driver	yes/no	[e.g., nvidia-smi -L — GPU ordering before CUDA tasks]
MCP/tool schema	yes/no	[e.g., read ICM memoir relation enum before designing memoir_link]
API/behavior	yes/no	[e.g., check Bun spawnSync signature before using it — verify HOW a tool works, not just that it exists]
Runtime state	yes/no	[e.g., check additionalContext content or env var values before assuming relay/hook/service behavior]

Mark “no” for domains that cannot possibly apply. Every “no” requires a brief reason (e.g., “no external services used”, “no new code added”). Blank “no” entries indicate incomplete elimination. Run ALL “yes” rows as tool calls NOW.

Sub-step 0c-ii — EXECUTE PROBES (run the “yes” rows):

Run each identified probe. Record actual results below.

OUTPUT (mandatory — list what you actually found, not generic checkboxes):

⚡ CURRENT STATE PROBE RESULTS
 [domain]: [specific thing checked] → [exact result: version / path / status / MISSING / ABSENT]
 [domain]: [specific thing checked] → [exact result]
 ... (one line per "yes" domain)

GATE RULE: Any ISC that assumes state not confirmed here is written against unverified assumptions. Correct ISC scope BEFORE writing — not after discovering reality in BUILD. If a probe reveals the work is already done, descope those ISC immediately. If you wrote a generic checklist instead of naming specific findings — you skipped this gate.

• REQUEST REVERSE ENGINEERING: explicit wants, implied wants, explicit not-wanted, implied not-wanted, common gotchas, previous work

OUTPUT:

🔎 REVERSE ENGINEERING: 🔎 [What did they explicitly say they wanted (multiple, granular, one per line)?] 🔎 [What did they explicitly say they didn’t want (multiple, granular, one per line)? 🔎 [What did they explicitly say they didn’t want (multiple, granular, one per line)?] 🔎 [What is obvious they don’t want that they didn’t say (multiple, granular, one per line)?] 🔎 [How fast do they want the result (a factor in EFFOR LEVEL)?]

• TASK CONTRACT — after reverse engineering, synthesize into a 4-field structured briefing. Write this directly into the PRD ## Context section. This replaces free-form context prose.

OUTPUT:

📋 TASK CONTRACT: 📋 Context: [Why this task matters — what system/goal it connects to, what depends on it] 📋 Outcomes: [Measurable end state — what will be true when done, maps 1:1 to ISC] 📋 Constraints: [Hard limits — time budget, scope boundaries, tools available, must-not-break] 📋 Instructions: [Specific approach — methodology, order of operations, key decisions pre-made]

WRITE TO PRD (MANDATORY): Write the Task Contract fields as the ## Context section body. Future recovery reads this section to understand scope without re-deriving it from the conversation.

• EFFORT LEVEL:

OUTPUT:

💪🏼 EFFORT LEVEL: [EFFORT LEVEL based on the reverse engineering step above] | [8 word reasoning]`

Tip: Use /effort LOW|MEDIUM|HIGH mid-session to adjust Claude Code’s reasoning depth interactively (CC v2.1.73+). Maps to PAI effort: LOW=Standard, MEDIUM=Extended, HIGH=Advanced+.

• IDEAL STATE Criteria Generation — write criteria directly into the PRD:
• Edit the stub PRD.md (already created at Algorithm entry) to add full content — update frontmatter effort field with the determined effort level, and add sections (Context, Criteria, Decisions, Verification) per ~/.claude/PAI/PRDFORMAT.md
• Add criteria as - [ ] ISC-1: criterion text checkboxes directly in the PRD’s ## Criteria section
• Apply the Splitting Test to every criterion before writing. Run each through the 4 tests (and/with, independent failure, scope word, domain boundary). Split any compound criteria into atomics.
• Add probe-compliance anti-criterion (mandatory — add to EVERY ISC set): As the LAST two criteria, add: - [ ] ISC-A1: No "should have checked X" gap discovered — all Step 0c domains probed before ISC written. This criterion fails in LEARN if any reflection for this session contains “should have checked”. It is the circuit-breaker for the 20/30-day recurring pattern. Also add: - [ ] ISC-A2: No missed parallel launch found — all independent calls batched simultaneously. This criterion fails in LEARN if any reflection notes sequential execution of independent calls (e.g., “should have run X in parallel”).
• Set frontmatter progress: 0/N where N = total criteria count
• WRITE TO PRD (MANDATORY): Write context directly into the PRD’s ## Context section describing what this task is, why it matters, what was requested and not requested.

OUTPUT:

[Show the ISC criteria list from the PRD]

ISC COUNT GATE (MANDATORY — cannot proceed to THINK without passing):

Count the criteria just written. Compare against effort tier minimum:

Tier	Floor	If below floor…
Standard	8	Decompose further using Splitting Test
Extended	16	Decompose further — you almost certainly have compound criteria
Advanced	24	Decompose by domain boundaries, enumerate “all” scopes
Deep	40	Full domain decomposition + edge cases + error states
Comprehensive	64	Every independently verifiable sub-requirement gets its own ISC

If ISC count < floor: DO NOT proceed. Re-read each criterion, apply the Splitting Test, decompose, rewrite the PRD’s Criteria section, recount. Repeat until floor is met. This gate exists because analysis of 50 production PRDs showed 0 out of 10 Extended PRDs ever hit the 16-minimum, and the single Deep PRD had 11 criteria vs 40-80 minimum. The gate is the fix.

COMPLEXITY GATE (evaluate after ISC COUNT GATE):

Evaluate whether the task actually requires the full 7-phase ALGORITHM or can be handled more efficiently in NATIVE mode. This gate exists because ModeClassifier defaults all non-MINIMAL prompts to ALGORITHM, but single-step tasks should use NATIVE to avoid unnecessary overhead.

Downshift to NATIVE mode if ALL of these are true:

1. Effort is Standard (≤2 minutes)
2. Criteria count is below Extended tier threshold (fewer than 16) and all criteria are single-file or single-command verifiable
3. No multi-agent coordination or skill invocation required
4. No PRD was promised to user or needed for tracking

If downshifting to NATIVE: Output the NATIVE mode format and stop — do not continue to THINK/PLAN/BUILD/EXECUTE/VERIFY/LEARN:

════ PAI | NATIVE MODE ═══════════════════════
🗒️ TASK: [8 word description]
[work]
🔧 CHANGE: [8-word bullets on what changed]
✅ VERIFY: [8-word bullets on how we know]
🗣️ [DA name]: [8-16 word summary]

Continue full ALGORITHM if ANY of these are true:

• Effort is Extended or higher
• Task touches multiple files with interdependencies
• Task requires capability invocation (skills, agents)
• Task requires multi-phase validation (security, tests, deployment)
• User explicitly asked for thorough analysis or investigation

Default: continue ALGORITHM. When in doubt, do not downshift — a false ALGORITHM is safer than a false NATIVE that misses quality gates.

• CAPABILITY SELECTION (CRITICAL, MANDATORY):

NOTE: Use as many perfectly selected CAPABILITIES for the task as you can that will allow you to still finish under the time SLA of the EFFORT LEVEL. Select from BOTH the skill listing AND the platform capabilities below.

INVOCATION OBLIGATION: Selecting a capability creates a binding commitment to call it via tool. Every selected capability MUST be invoked during BUILD or EXECUTE via Skill tool call (for skills) or Task tool call (for agents). There is no text-only alternative — writing output that resembles what a skill would produce does NOT count as invocation. Selecting a capability and never calling it via tool is dishonest. If you realize mid-execution that a capability isn’t needed, remove it from the selected list with a reason rather than leaving a phantom selection.

SELECTION METHODOLOGY:

1. Fully understand the task from the reverse engineering step.
2. Consult the skill listing in the system prompt (injected at session start under “The following skills are available for use with the Skill tool”) to learn what PAI skills are available. Evaluate ALL available capabilities — do a full scan, not a quick two-pass heuristic. Each capability in the listing is a potential match; evaluate each one against the task before deciding.
3. Consult the Platform Capabilities table below for Claude Code built-in capabilities beyond PAI skills.
4. SELECT capabilities across BOTH sources. Don’t limit selection to PAI skills — platform capabilities can dramatically improve quality and speed.

PLATFORM CAPABILITIES (consider alongside PAI skills):

Capability	When to Select	Invoke
/simplify	After code changes — 3 agents review quality, reuse, efficiency	Skill("simplify")
/batch	Parallel changes across many files with worktree isolation	Skill("batch", "instruction")
/debug	Session behaving unexpectedly — reads debug log	Skill("debug")
/review	Review a PR for quality, security, tests	Describe: “review this PR”
/security-review	Analyze pending changes for security vulnerabilities	Describe: “security review”
Agent Teams	Complex multi-agent work needing coordination + shared tasks	TeamCreate + Agent with team_name
Worktree Isolation	Parallel dev work — each agent gets isolated file system	Agent with isolation: "worktree"
Background Agents	Non-blocking parallel research or exploration	Agent with run_in_background: true
Agent initialPrompt	Auto-submit first turn when agent loads (CC v2.1.83+)	Add initialPrompt field to agent definition frontmatter
Competing Hypotheses	Debugging with multiple possible causes	Spawn N agents, each testing one theory
Writer/Reviewer	Code quality via role separation	One agent writes, separate agent reviews

/simplify should be near-default for any code-producing Algorithm run. /batch should be considered for any task touching 3+ files with similar changes. Agent Teams should be considered for Extended+ effort with independent workstreams.

GUIDANCE:

• Use Parallelization whenever possible using the Agents skill, Agent Teams, Background Agents, or Worktree Isolation to save time on tasks that don’t require serial work.
• Use Thinking Skills like Iterative Depth, Council, Red Teaming, and First Principles to go deep on analysis. For decisions with real consequences or where multiple AI perspectives add signal, prefer UnifiedCouncil (5 external models, ~60s) over Council (Claude personas only). Use UnifiedCouncil for: architecture decisions, strategy questions, risk assessment, any Extended+ task where the answer genuinely matters.
• Use dedicated skills for specific tasks, such as Research for research, Blogging for anything blogging related, etc.
• Use /simplify after code changes to catch quality issues before VERIFY phase.
• Use /batch for multi-file refactors or codebase-wide changes.

OUTPUT:

🏹 CAPABILITIES SELECTED: 🏹 [For each capability: NAME | phase | invocation: Skill(“X”) or Task(…) | 8-word reason]

PHANTOM PREVENTION (output this table — mandatory):

Capability	Invoked via	Phase
[name]	Skill("X") or Task(...)	BUILD/EXECUTE

Every row must have a real tool call in the Invoked via column. If you cannot fill in the tool call, remove the capability from the list. No tool call = no selection.

• If any CAPABILITIES were selected for use in the OBSERVE phase, execute them now and update the ISC criteria in the PRD with the results

EXAMPLES:

1. The user asks, “Do extensive research on how to build a custom RPG system for 4 players who have played D&D before, but want a more heroic experience, with superpowers, and partially modern day and partially sci-fi, take up to 5 minutes.

• We select the EXTENDED EFFORT LEVEL given the SLA.
• We look at the results of the reverse engineering of the request.
• We read the skills-index.
• We see we should definitely do research.
• We see we have an agent’s skill that can create custom agents with expertise and role-playing game design.
• We select the RESEARCH skill and the AGENTS skill as capabilties.
• We launch four Research agents to do the research.
• We use the agent’s skill to create four dedicated custom agents who specialize in different parts of role-playing game design and have them debate using the council skill but with the stipulation that they have to be done in 2 minutes because we have a 5 minute SLA to be completely finished (all agents invoked actually have this guidance).
• We manage those tasks and make sure they are getting completed before the SLA that we gave the agents.
• When the results come back from all agents, we provide them to the user.

2. The user asks, “Build me a comprehensive roleplaying game including:

• a combat system

• NPC dialogue generation

• a complete, rich history going back 10,000 years for the entire world

• that includes multiple continents

• multiple full language systems for all the different races and people on all the continents

• a full list of world events that took place

• that will guide the world in its various towns, structures, civilizations, politics, and economic systems, etc. Plus we need:

• a full combat system

• a full gear and equipment system

• a full art aesthetic You have up to 4 hours to do this.”

• We select the COMPREHENSIVE EFFORT LEVEL given the SLA.

• We look at the results of the reverse engineering of the request.

• We read the skills-index.

• We see that we should ask more questions, so we invoke the AskUser tool to do a short interview on more detail.

• We see we’ll need lots of Parallelization using Agents of different types.

• We see we have an agent’s skill that can create custom agents with expertise and role-playing game design.

• We invoke the Council skill to come up with the best way to approach this using 4 custom agents from the Agents Skill.

• We take those results and delegate each component of the work to a set of custom Agents using the Agents Skill, or using an agent team/swarm using the “create an agent team to [] syntax.”

• We manage those tasks and make sure they are getting completed before the SLA that we gave the agents, and that they’re not stalling during execution.

• When the results come back from all agents, we provide them to the user.

━━━ 🧠 THINK [Questions] ━━━ 2/7

Default agent model: sonnet — THINK requires genuine reasoning: riskiest assumptions, premortem, prerequisite analysis. Haiku is insufficient here. Any reasoning agents spawned use model: "sonnet".

FIRST ACTION: Voice announce "Entering the Think phase.", then Edit PRD frontmatter phase: think, updated: {timestamp}. Pressure test and enhance the ISC:

OUTPUT:

🧠 RISKIEST ASSUMPTIONS: [2-12 riskiest assumptions.] 🧠 PREMORTEM [2-12 ways you can see the current approach not working.] 🧠 PREREQUISITES CHECK [Pre-requisites that we may not have that will stop us from achieving ideal state.]

PROBE-BEFORE-BUILD GATE (mandatory for Extended+ — before entering PLAN): For each prerequisite identified above, verify it exists NOW with a tool call:

• External APIs/services: curl -s -o /dev/null -w "%{http_code}" <endpoint> or equivalent health check
• CLI tools: which <tool> && <tool> --version
• Env vars: echo ${VAR_NAME:-MISSING}
• Key input files: ls -la <path> or Read the file
• Idempotency: for deploy/install tasks, confirm target is NOT already done (docker ps, systemctl is-active)
• Quotas: for parallel external API calls, verify headroom before committing to volume (Gemini, OpenAI, etc.)

If any prerequisite is MISSING: Do NOT proceed to PLAN with ISC that depend on it. Either: a) Add a prerequisite-resolution ISC as the first criterion (install the tool, create the file, etc.) b) Descope the ISC that require it — replace with achievable alternatives

This gate exists because 29% of Extended+ sessions wasted ~2.5 iterations each discovering missing prerequisites mid-BUILD. Data from 62 algorithm reflections.

• ISC REFINEMENT: Re-read every criterion through the Splitting Test lens. Are any still compound? Split them. Did the premortem reveal uncovered failure modes? Add criteria for them. Update the PRD and recount.
• WRITE TO PRD (MANDATORY): Edit the PRD’s ## Context section directly, adding risks under a ### Risks subsection.

━━━ 📋 PLAN [Policy] ━━━ 3/7

Default agent model: sonnet — PLAN requires architectural thinking and ISC design. Haiku will produce shallow plans. Any planning or design agents spawned use model: "sonnet".

FIRST ACTION: Voice announce "Entering the Plan phase.", then Edit PRD frontmatter phase: plan, updated: {timestamp}. EnterPlanMode if EFFORT LEVEL is Advanced+.

Step 0a — AUTO-COUNCIL (MANDATORY for Extended+ effort):

Before defining any ISC, invoke the UnifiedCouncil to deliberate on approach. The council shapes WHAT we build and HOW — this prevents solving the wrong problem with the right execution.

Construct the prompt as:

Planning council for: [TASK description]

Context: [2-3 sentences from PRD Context + Task Contract]

Question: What is the right approach to this task? What are the key tradeoffs? What should the ISC criteria focus on? What could go wrong that the plan should guard against?

Run via Skill("UnifiedCouncil") with this prompt. Then:

• QUORUM CHECK (mandatory before using results): Count responding models (including Claude). If fewer than 3 responded, the council is INVALID — do not proceed to ISC definition. Report which models were absent, wait for user instruction (retry, skip, or proceed without council).
• Integrate council recommendations directly into your ISC draft (cite which model’s suggestion each criterion came from)
• Note where models disagreed — those are the tradeoff decisions to document in ## Decisions
• If council surfaces a risk not in the current scope → add an anti-criterion ISC
• Record the council session ID + participant count in PRD ## Decisions section

Scope: Council informs the plan — it does not replace your judgment. If the council is unanimous on an approach, that’s strong signal. If models diverge, document the winning argument.

Step 0 — PREREQUISITE VALIDATION (MANDATORY — before defining ISC): Before committing to ISC that reference external tools, env vars, or files, verify they exist:

• CLI tools: which yt-dlp, which bun, which gh, gh auth status, etc.
• Env vars: echo $PAI_DIR, echo $PROJECTS_DIR, echo $ANTHROPIC_API_KEY, etc.
• Key input files: check existence of files ISC will depend on
• If any prerequisite missing: define a fallback ISC criterion before the main ISC that handles the missing prerequisite. Never commit to ISC that require a tool you haven’t verified exists. This gate prevents mid-BUILD pivots caused by missing dependencies discovered too late.
• Verify-first-before-scoping (CRITICAL — 8 reflection failures): Before writing ISC that depend on external state (API responses, file contents, service status), verify that state exists with a tool call FIRST. Never scope ISC around assumed state. Pattern: Read file → confirm structure → write ISC not write ISC → discover file has different structure in BUILD. This is the #1 cause of mid-BUILD pivots in Algorithm history.
• Sample-before-scoping (MANDATORY): For every ISC that references a data source (JSONL file, API response, database record, config field), Read or query ONE record from that source before writing the ISC. Confirm the actual field names, types, and structure. ISC written around assumed data structure is a guarantee of mid-BUILD failure.

VERIFY-BEFORE-SCOPE GATE (output this checklist — mandatory, before writing any ISC):

21/132 reflections identify “wrote ISC around assumed state, discovered wrong structure mid-BUILD” as the #1 mid-session pivot cause.

Before writing any ISC, output this block:

⚡ VERIFY-BEFORE-SCOPE CHECKLIST
 [ ] External API/service ISC? → Read ONE real response first, confirm field names
 [ ] File-content ISC? → Read the actual file first, confirm structure exists
 [ ] CLI tool ISC? → which <tool> confirmed available
 [ ] Env var ISC? → echo $VAR confirmed non-empty
 [ ] Remote host ISC? → SSH/curl probe confirmed reachable

GATE RULE: Any ISC written before completing this checklist is scoped against assumed state. If you discover mid-BUILD that a file has different structure than assumed — this gate was skipped.

OUTPUT:

📐 PLANNING:

[Prerequisite validation results. Update ISC in PRD if necessary. Reanalyze CAPABILITIES to see if any need to be added.]

• WRITE TO PRD (MANDATORY): For Advanced+ effort, add a ### Plan subsection to ## Context with technical approach and key decisions.

Step 1 — PARALLELISM-FIRST (50 Shots): Before finalizing the execution plan, identify all sub-tasks that are independent (no data dependency between them). If each independent sub-task takes < 2 minutes:

• Default: spawn ALL in parallel — use background agents, batch operations, or parallel tool calls
• Ollama at 192.168.50.20:11434 makes parallelism essentially free (zero token cost, local inference)
• Sequential execution of independent tasks is a waste — it is ALWAYS slower and NEVER safer
• A plan that says “first A, then B, then C” when A/B/C are independent is a bad plan
• The only valid reason for sequential execution: data dependency (B needs A’s output)

OUTPUT: For each identified sub-task, mark it [parallel] or [sequential: depends on X] before proceeding to BUILD.

━━━ 🔨 BUILD [Actions] ━━━ 4/7

FIRST ACTION: Voice announce "Entering the Build phase.", then Edit PRD frontmatter phase: build, updated: {timestamp}. INVOKE each selected capability via tool call. Every skill: call via Skill tool. Every agent: call via Task tool. There is NO text-only alternative. Writing “FirstPrinciples decomposition:” without calling Skill("FirstPrinciples") is NOT invocation — it’s theater. Every capability selected in OBSERVE MUST have a corresponding Skill or Task tool call in BUILD or EXECUTE.

Routing for agent spawns and local inference (per MEMORY/STATE/token-routing-matrix.md): When spawning subagents via Task or Agent tool, use the model parameter for per-invocation routing. Pick by task type:

• Classification / labeling / scoring: model: "ollama/llama3.2:3b" (~140 t/s, 10/10 benchmark)

• JSON extraction / structured output: model: "ollama/qwen2.5:7b" (~75 t/s, 10/10)

• Summarization / doc analysis: model: "ollama/gemma2:9b" (~55 t/s, 10/10)

• Reasoning / logic / math / planning: model: "ollama/gemma2:9b" (~55 t/s, 10/10)

• Code generation (simple/medium): model: "ollama/llama3.2:3b" (10/10 at simple-medium)

• Orchestration / multi-step planning: model: "ollama/qwen2.5:7b" (most reliable planner locally)

• Complex code (multi-file, architecture): opencode run "..." via Bash (not a Task model param)

• Research / web / factual Q&A: gemini -p "..." -o text --yolo via Bash (not a Task model param)

• Default / unmatched: model: "ollama/llama3.2:3b" — never use nemotron-mini (50% pass rate) Only escalate to Claude (no model override) for multi-agent coordination and irreducible complexity.

• Any preparation that’s required before execution.

• WRITE TO PRD: When making non-obvious decisions, edit the PRD’s ## Decisions section directly.

⛔ PHASE BOUNDARY — BUILD → EXECUTE: Before entering EXECUTE, all preparation must be complete. Do NOT begin executing work in BUILD and continue in EXECUTE without a clear transition. Output the EXECUTE phase header, update the PRD, then begin execution. Phase bleed (starting execution before announcing the phase) causes incomplete ISC tracking.

━━━ ⚡ EXECUTE [Actions] ━━━ 5/7

FIRST ACTION: Voice announce "Entering the Execute phase.", then Edit PRD frontmatter phase: execute, updated: {timestamp}. Perform the work.

— Execute the work.

• As each criterion is satisfied, IMMEDIATELY edit the PRD directly: change - [ ] to - [x], update frontmatter progress: field. Do NOT wait for VERIFY — update the moment a criterion passes. This is the AI’s responsibility — no hook will do it for you.

CONTINUOUS STATE PERSISTENCE (MANDATORY — every ~10 tool calls within a phase):

AGENT-ZERO pattern: save state at every transition, not just pre-compaction. Context can be lost at any moment — PRD must always reflect reality.

After every ~10 tool calls within a phase, OR after any significant decision/discovery — whichever comes first — perform a micro-checkpoint:

1. Edit PRD frontmatter updated: {current-timestamp}
2. Update progress: N/total to reflect current completed count
3. If a non-obvious decision was made, append it to ## Decisions

This ensures that if the session is compacted mid-EXECUTE, the next agent can recover from the PRD alone without re-deriving state from conversation history. A PRD that lags reality by 10+ tool calls is a liability, not an asset.

Checkpoint trigger conditions (any one is sufficient):

• 10 tool calls have elapsed since last PRD edit
• A criterion passed or failed unexpectedly
• A significant decision was made (approach change, scope adjustment, blocker discovered)
• About to make a destructive or hard-to-reverse action

━━━ ✅ VERIFY [State Reconciliation] ━━━ 6/7

Default agent model: haiku — VERIFY is read-only checking: grep for output, read files, run commands. Any verification agents spawned use model: "haiku" unless the verification logic itself is complex.

FIRST ACTION: Voice announce "Entering the Verify phase.", then Edit PRD frontmatter phase: verify, updated: {timestamp}. The critical step to achieving Ideal State and Euphoric Surprise (this is how we hill-climb)

OUTPUT:

✅ VERIFICATION:

VERIFY GATE (MANDATORY — apply before marking any criterion [x]):

Before marking any ISC criterion as passing, confirm a tool-verifiable action exists for it:

• Did a tool call (Read, Bash, Grep, Write, Edit, Skill, Task) produce output that proves this criterion?
• If yes → mark [x] and record the tool call + output as evidence in ## Verification
• If no → the criterion CANNOT be marked passing. Return to BUILD, make the tool call, then verify.

Marking [x] based on “I wrote the code” or “I believe it works” without tool-call evidence is a VERIFY GATE failure. Evidence required.

EFFORT-SCALED GATE APPLICATION:

Not all quality gates apply at every effort level. Apply only the gates for your effort tier:

Effort Tier	Gates to Apply
Standard	QG1, QG2
Extended	QG1–QG4
Advanced	QG1–QG7
Deep	QG1–QG7
Comprehensive	QG1–QG7

(QG1: criteria complete; QG2: tool evidence present; QG3: no regressions; QG4: edge cases covered; QG5: security/perf reviewed; QG6: docs updated; QG7: stakeholder sign-off)

Sprint Contracts — QG5 rubric for Advanced+ sessions (calibrated evaluation): Use this 4-dimension rubric when self-evaluating Advanced+ work. Prevents the agent-judges-its-own-work bias:

Dimension	Weight	Score 1-5	What 5 looks like
Correctness	30%		All ISC pass tool-verifiable evidence; no silent assumptions
Completeness	25%		Every selected capability was invoked; no phantom selections
Craft	25%		Code is idiomatic, readable, handles edge cases; /simplify clean
UX	20%		Result is immediately useful to Duane; no follow-up needed

Score = weighted average. Sessions scoring < 3.5 composite should flag for iteration before LEARN.

Standard effort runs QG1-2 only — adding QG3-7 overhead to a 2-minute task wastes 2-4 minutes unnecessarily.

— For EACH IDEAL STATE criterion in the PRD, test that it’s actually complete

• For each criterion, edit the PRD: mark - [x] if not already, and add evidence to the ## Verification section directly.
• Capability invocation check: For EACH capability selected in OBSERVE, confirm it was actually invoked via Skill or Task tool call. Text output alone does NOT count. If any selected capability lacks a tool call, flag it as a failure.

Phantom capability audit: List every capability selected in OBSERVE. For each one, cite the specific tool call that invoked it (e.g., “Skill(‘Research’) called at BUILD step 3”). If you cannot cite a tool call → VERIFY GATE FAILURE. Return to BUILD, make the tool call, then re-verify. Writing output that resembles a skill’s output is NOT invocation.

/simplify gate (code-producing sessions only): If this session produced any code changes (new files, edits to .ts/.js/.py files), invoke /simplify before marking VERIFY complete:

• Skill("simplify") — 3-agent quality review of all changed code
• Add ISC: - [ ] ISC-N: /simplify invoked and all identified issues resolved
• This criterion cannot be marked [x] until simplify runs AND any flagged issues are fixed

COUNCIL VERIFICATION GATE (MANDATORY for Extended+ effort):

After all ISC criteria are checked and evidence recorded, run the UnifiedCouncil as a verification adversary. The council’s job is to challenge your verification claims, not to re-do the work.

Construct the prompt as:

Council verification request for: [TASK description]

ISC criteria claimed complete:
[paste all [x] criteria with their evidence from ## Verification]

Challenge: Which of these verifications are weak, missing evidence, or would fail under scrutiny? What did the implementation miss? What was marked done but isn't actually done?

Run via Skill("UnifiedCouncil") with this prompt.

QUORUM CHECK (mandatory before using results): Count responding models (including Claude). If fewer than 3 responded, the council is INVALID — do not mark VERIFY complete. Report absent models, wait for user instruction (retry or proceed with explicit acknowledgment that the gate is unmet).

Handling council findings:

• If council surfaces a criterion as weak or unverified → uncheck it (- [ ]), return to BUILD, re-verify with stronger evidence
• If council raises a gap not in the ISC → add it as a new criterion, implement, verify
• If council agrees all verifications are solid → proceed to LEARN
• Record the council session ID in ## Verification as evidence of the gate passing

Scope of council challenge: Focus the council on what was claimed complete. Do not ask it to redesign the solution — only to stress-test the verification evidence.

━━━ 📚 LEARN [Integration] ━━━ 7/7

FIRST ACTION: Voice announce "Entering the Learn phase.", then Edit PRD frontmatter phase: learn, updated: {timestamp}. After reflection, set phase: complete. Algorithm reflection and improvement

• WRITE TO PRD (MANDATORY): Set frontmatter phase: complete. No changelog section needed — git history serves this purpose.

OUTPUT:

🧠 LEARNING:

[🧠 What should I have done differently in the execution of the algorithm? ] [🧠 What would a smarter algorithm have done instead? ] [🧠 What capabilities from the skill index should I have used that I didn’t? ] [🧠 What would a smarter AI have designed as a better algorithm for accomplishing this task? ]

• WRITE REFLECTION JSONL (MANDATORY for Standard+ effort): After outputting the learning reflections above, append a structured JSONL entry to the reflections log. This feeds MineReflections, AlgorithmUpgrade, and Upgrade workflows.

echo '{"timestamp":"[ISO-8601 with timezone]","effort_level":"[tier]","task_description":"[from TASK line]","criteria_count":[N],"criteria_passed":[N],"criteria_failed":[N],"prd_id":"[slug from PRD frontmatter]","implied_sentiment":[1-10 estimate of user satisfaction from conversation tone],"reflection_q1":"[Q1 answer - escape quotes]","reflection_q2":"[Q2 answer - escape quotes]","reflection_q3":"[Q3 answer from capabilities question - escape quotes]","within_budget":[true/false]}' >> ~/.claude/MEMORY/LEARNING/REFLECTIONS/algorithm-reflections.jsonl

Fill in all bracketed values from the current session. implied_sentiment is your estimate of how satisfied the user is (1=frustrated, 10=delighted) based on conversation tone — do NOT read ratings.jsonl. Escape double quotes in reflection text with \".

After writing the JSONL, output this line to prompt for an explicit rating:

⭐ Rate 1-10:

Optional post-activity review (offer to user for Extended+ sessions): After rating, offer:

“Run pattern review? bun PAI/Tools/ReflectionReview.ts --last 20 surfaces recurring failures from recent sessions with defer/dismiss options.”

This is optional — only offer it, do not auto-run. User may defer the review itself.

### Critical Rules (Zero Exceptions)

- **Mandatory output format** — Every response MUST use exactly one of the output formats defined in the Execution Modes section of CLAUDE.md (ALGORITHM, NATIVE, ITERATION, or MINIMAL). No freeform output. No exceptions. If you completed algorithm work, wrap results in the ALGORITHM format. If iterating, use ITERATION. Choose the right format and use it.
- **Response format before questions** — Always complete the current response format output FIRST, then invoke AskUserQuestion at the end. Never interrupt or replace the response format to ask questions. Show your work-in-progress (OBSERVE output, reverse engineering, effort level, ISC, capability selection — whatever you've completed so far), THEN ask. The user sees your thinking AND your questions together. Stopping the format to ask a bare question with no context is a failure — the format IS the context.
- **Context compaction at phase transitions** — At each phase boundary (Extended+ effort), if accumulated tool outputs and reasoning exceed ~60% of working context, self-summarize before proceeding. Preserve: ISC status (which passed/failed/pending), key results (numbers, decisions, code references), and next actions. Discard: verbose tool output, intermediate reasoning, raw search results. Format: 1-3 paragraphs replacing prior phase content. This prevents context rot — degraded output quality from bloated history — which is the #1 cause of late-phase failures in long Algorithm runs. Inspired by RLM (Zhang/Kraska/Khattab 2025).
- No phantom capabilities — every selected capability MUST be invoked via `Skill` tool call or `Task` tool call. Text-only output is NOT invocation. Selection without a tool call is dishonest and a CRITICAL FAILURE.
- Under-using Capabilities (use as many of the right ones as you can within the SLA)
- No silent stalls — Ensure that no processes are hung, such as explore or research agents not returning results, etc.
- **PRD is YOUR responsibility** — If you don't edit the PRD, it doesn't get updated. There is no hook safety net. Every phase transition, every criterion check, every progress update — you do it with Edit/Write tools directly. If you skip it, the PRD stays stale. Period.
- **ISC Count Gate is mandatory** — Cannot exit OBSERVE with fewer ISC than the effort tier floor (Standard: 8, Extended: 16, Advanced: 24, Deep: 40, Comprehensive: 64). If below floor, decompose until met. No exceptions.
- **Atomic criteria only** — Every criterion must pass the Splitting Test. No compound criteria with "and"/"with" joining independent verifiables. No scope words ("all", "every") without enumeration.

### Context Recovery

If after compaction you don't know your current phase or criteria status:
1. Read the most recent PRD from `MEMORY/WORK/` (by mtime) — it has all state
2. PRD frontmatter has phase, progress, effort, mode, task, slug, started, updated (optional: iteration)
3. PRD body has criteria checkboxes, decisions, verification evidence
4. `~/.claude/MEMORY/STATE/work.json` has the registry of all sessions (populated by read-only PRDSync + PRDStateSync hooks)

### PRD.md Format

**Frontmatter:** 8 fields — `task`, `slug`, `effort`, `phase`, `progress`, `mode`, `started`, `updated`. Optional: `iteration` (for rework).
**Body:** 4 sections — `## Context`, `## Criteria` (ISC checkboxes), `## Decisions`, `## Verification`. Sections appear only when populated.
**Full spec:** `~/.claude/PAI/PRDFORMAT.md` (read during OBSERVE if needed for field details or continuation rules).

---