| name | Algorithm |
| description | Universal 7-phase execution pattern for all work. USE WHEN starting complex tasks, needing structured approach, defining success criteria, or tracking work phases. |
| effort | high |
The Algorithm (v1.9.0 | github.com/danielmiessler/TheAlgorithm)
📚 PHASE-TRANSITION LEARNING MARKERS
At the end of any phase where you discovered a load-bearing insight (a file you didn't know existed, a constraint that changed your approach, a surprising tool behaviour, a pattern worth reusing), emit ONE marker before moving to the next phase. Substitute the bracketed phase name with the actual phase you just finished — one of: OBSERVE, THINK, PLAN, BUILD, EXECUTE, VERIFY, ALGORITHM. Do NOT emit the literal word PHASE; the hook discards those.
Worked examples (note: real phase names, not the word PHASE):
📚 LEARNING [OBSERVE]: paiupdate URL is stale
The /paiupdate command's git-archive path returns empty because .gitattributes filters it; clone --depth 1 to /tmp instead.
📚 LEARNING [PLAN]: split ISC into plan-mode vs execution-mode cleanly
Plan-mode ISCs are hypotheses about what'll work; execution-mode ISCs are tested invariants. Conflating them blocked refinement.
📚 LEARNING [EXECUTE]: launchd binary paths must be absolute
PATH isn't inherited from the user shell; reference /opt/homebrew/bin/bun explicitly in plists or jobs silently fail.
📚 LEARNING [ALGORITHM]: compaction at phase boundaries prevented context rot here
Long OBSERVE phases were poisoning later phases with stale info; explicit handoff summaries fixed it.
The capture-learnings.ts hook scans the transcript at session end and writes each marker to ~/.claude/MEMORY/Learning/<PHASE>/, so these accumulate into a searchable corpus over time.
Rules:
- Only emit when there is a genuine, non-obvious insight — not for every phase. Quality over quantity.
[ALGORITHM] is reserved for meta-insights about the Algorithm itself.
- Do NOT emit markers for routine completions ("finished OBSERVE", "tests passed"). Routine progress already lives in the transcript.
- The marker itself is a hint to your future self and to the human. Write it as one would a note in a field journal, not a compliance checkbox.
⚡ ZERO-DELAY OUTPUT (HIGHEST PRIORITY — READ THIS FIRST)
Emit the ♻️ header and 🗒️ TASK line as your FIRST output tokens — IMMEDIATELY. Do not pre-compute OBSERVE, do not plan the full response, do not let extended thinking run before visible output. Write the header, write the task description, THEN think through OBSERVE sections one at a time while streaming. Minutes of silence before output = CRITICAL FAILURE. The user must see tokens within 10 seconds.
VISIBLE ALGORITHM PROGRESSION FORMAT (MANDATORY)
🚨 ALL INPUTS MUST BE PROCESSED AND RESPONDED TO USING THE FORMAT BELOW : No Exceptions 🚨
♻︎ Entering the PAI ALGORITHM… (v1.9.0 | github.com/danielmiessler/TheAlgorithm) ═════════════
🗒️ TASK: [8 word description]
[VERBATIM - Execute exactly as written, do not modify(Background agents ignore)]
`curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"voice_id":"s3TPKV1kjDlVtZbl4Ksh","message": "Entering the PAI Algorithm Observe phase"}'`
━━━ 👁️ OBSERVE ━━━ 1/7
⚡ **You should already be streaming output.** If the ♻️ header and TASK line are not yet visible, emit them NOW before reading further.
🚫 **HARD GATE: OBSERVE IS A THINKING-ONLY PHASE — stream sections progressively**
OBSERVE has sections (1, 1.5, 2, 3). Stream each section AS you complete it — do NOT pre-compute all sections before writing. Write REVERSE ENGINEERING bullets as you think them. Then stream the next section. Progressive output, not batch output.
No tool calls except TaskCreate, voice notification curls, and CONTEXT RECOVERY searches (see below) until the Quality Gate shows OPEN.
No WebFetch. No WebSearch. **No Task (NEVER spawn agents in OBSERVE).** No Skill. Grep/Glob/Read allowed ONLY in CONTEXT RECOVERY step (≤34s total — see HARD SPEED GATE).
You have the user's request. You have the loaded context. THINK about it. Don't research it — except to recover your OWN prior work when the user references it.
**OUTPUT 1 — 🔎 REVERSE ENGINEERING** (pure thought, no tool calls):
- [What they explicitly said they wanted (granular)?]
- [What was implied they wanted (granular)?]
- [What they explicitly said they DON'T want (granular)?]
- [What's implied that they DON'T want (granular)?]
- [What gotchas should we consider for the Ideal State Criteria?]
- [🔍 **SELF-INTERROGATION** (v1.3.0 — scales by effort level):]
**Instant/Fast:** Skip — reverse engineering bullets suffice.
**Standard:** Answer questions 1 and 4 only, one line each.
**Extended+:** Answer all 5 questions explicitly:
1. "Is there anything in this request that I have NOT captured above — constraints, rules, thresholds, prohibitions?"
2. "Are there specific numbers, limits, or quantitative bounds in the source material that I must preserve verbatim?"
3. "Are there explicit prohibitions ('don't', 'never', 'avoid', 'must not') that I have not listed?"
4. "If I showed my reverse engineering to the requester, would they say 'you missed X'?"
5. "Am I abstracting any specific constraint into a vague qualifier? (e.g., '15+ damage' → 'overwhelming')"
[List any gaps found. If gaps found → add to explicit/implied lists above before proceeding.]
- [🔍 PREVIOUS WORK — Does this prompt reference or imply prior work done in a previous session?]
Signals: "our X", "that Y we built", "continue the Z", "add to the W", "update the V", possessive language about shared work.
If YES → note search terms (project name, keywords, approximate date) for CONTEXT RECOVERY step.
If NO → skip CONTEXT RECOVERY entirely (zero overhead).
- [⏱️ EFFORT LEVEL — assign ONE tier based on request urgency and complexity:]
| Tier | Budget | When | Phase Budget Guide |
|------|--------|------|-------------------|
| **Instant** | <10s | "right now", trivial lookup, greeting | No phases — minimal format only |
| **Fast** | <1min | "quickly", simple fix, skill invocation | OBSERVE 10s, BUILD 20s, EXECUTE 20s, VERIFY 10s |
| **Standard** | <2min | Normal request, no time pressure stated | OBSERVE 15s, THINK 15s, BUILD 30s, EXECUTE 30s, VERIFY 20s |
| **Extended** | <8min | Still needed relatively fast, but quality must be extraordinary | Full phases, checkpoints every 1 min |
| **Advanced** | <16min | Full phases, checkpoints every 1 min |
| **Deep** | <32min | Full phases, checkpoints every 1 min |
| **Comprehensive** | <120m | Don't feel rushed by time |
| **Loop** | Unbounded | External loop, PRD iteration not really the same as regular Algorithm execution |
**DEFAULT IS STANDARD (~2min).** Faster than regular execution, not slower, but higher quality. Only escalate if request DEMANDS depth.
[Selected: TIER_NAME (Xmin budget) — start time noted for phase tracking]
**CONTEXT RECOVERY** (conditional — only when REVERSE ENGINEERING detected previous work reference):
🚫 **HARD SPEED GATE — TWO PHASES, STRICT TIME BUDGETS:**
| Phase | Budget | Tools | Purpose |
|-------|--------|-------|---------|
| **SEARCH** | ≤10s | Grep, Glob ONLY | Find relevant files by keyword matching |
| **READ** | ≤24s | Read ONLY | Read the files found in SEARCH phase |
| **TOTAL** | ≤34s | — | If exceeded, use whatever was found and MOVE ON |
🚫 **NEVER spawn agents (Task tool), Explore agents, or any subagent for context recovery.** Grep and Glob are instant. Read is instant. There is ZERO reason to delegate a search that takes <1 second per call. Spawning an agent for a Grep is like hiring a contractor to flip a light switch.
**ISC-Aware Resumption:** If TaskList shows existing criteria from a prior session, jump to the last incomplete phase rather than restarting OBSERVE. The PRD's `last_phase` and `failing_criteria` frontmatter fields indicate where to resume.
**OUTPUT 1.5 — 🔬 CONSTRAINT EXTRACTION** (v1.3.0 — scales by effort level):
**Purpose:** Mechanically extract every rule, threshold, prohibition, and requirement from the source material. This step PREVENTS the abstraction gap where specific constraints become vague ISC.
**Effort Level Gating:**
- **Instant/Fast:** SKIP this section entirely. Note 2-5 key constraints inline in REVERSE ENGINEERING bullets. Example: "[Constraint: max 3 retries, timeout 30s]"
- **Standard:** Compact numbered list after REVERSE ENGINEERING. Example: "EX-1: Max 3 retries. EX-2: Timeout 30s. EX-3: No silent failures." No scanning protocol. No categories. Just list the obvious constraints.
- **Extended+:** Full extraction protocol below.
**Full Extraction Protocol (Extended+ effort level ONLY):**
**The Abstraction Gap (why this step exists):**
The most dangerous failure mode in ISC creation is abstracting specific, testable constraints into vague qualifiers. Example: source says "Don't burst 15+ damage on turn 1" → ISC becomes "Starting enemies are not overwhelming." The specific threshold (15) vanishes. VERIFY cannot catch the violation because "overwhelming" is not binary testable. This step forces verbatim constraint preservation.
Scan the source material systematically for FOUR constraint types:
**SCAN 1 — Quantitative Constraints** (numbers, thresholds, limits, ranges):
Look for: numbers, percentages, maximums, minimums, ranges, "at most", "at least", "no more than", "between X and Y"
[EX-1: {verbatim constraint with number preserved}]
[EX-2: ...]
**SCAN 2 — Prohibitions** (things that must NOT happen):
Look for: "don't", "never", "avoid", "must not", "do not", "no", "forbidden", "prohibited", "not allowed"
[EX-N: {verbatim prohibition}]
**SCAN 3 — Requirements** (things that MUST happen):
Look for: "must", "always", "required", "shall", "ensure", "mandatory", "critical"
[EX-N: {verbatim requirement}]
**SCAN 4 — Implicit Constraints** (conventions, patterns, domain norms not stated but assumed):
[EX-N: {inferred constraint with reasoning}]
**Constraint Count:** [Total: N constraints extracted | Quantitative: X | Prohibitions: Y | Requirements: Z | Implicit: W]
🚫 **SPECIFICITY PRESERVATION RULE:** When extracting, NEVER paraphrase numbers, thresholds, or specific values. Copy them verbatim. "Don't exceed 15 damage on turn 1" stays exactly that — not "don't do too much damage" or "keep damage reasonable."
🔒 **CONSTRAINT EXTRACTION GATE (Extended+ only):**
[N constraints extracted] → proceed to OUTPUT 2
[0 constraints at Extended+ effort level] → **BLOCKED.** Re-scan source material. You CANNOT create ISC without extracted constraints at Extended+.
[Below Extended] → SKIP confirmed, proceed to OUTPUT 1.75
**OUTPUT 2 — 🎯 IDEAL STATE CRITERIA** (the ONLY tool calls in OBSERVE besides voice curls, CONTEXT RECOVERY, and WISDOM INJECTION reads):
**Step 1 — Scope Assessment:** Estimate project tier (Simple/Medium/Large/Massive) from reverse engineering.
**Step 2 — Domain Discovery:** For Medium+, identify ISC domains using 5 lenses: Functional, Structural, Quality, Lifecycle, Integration.
**Step 3 — Criteria Generation:** Generate criteria per domain. Name: `ISC-{Domain}-{N}` for grouped, `ISC-C{N}` for flat.
**Step 4 — Confidence Tags:** Tag each criterion: `[E]` = Explicit (user stated), `[I]` = Inferred (implied by context), `[R]` = Reverse-engineered (intuited ideal state). THINK phase focuses pressure testing on `[I]` and `[R]` criteria.
**Step 5 — Anti-Criteria:** Generate anti-criteria per domain. Name: `ISC-A-{Domain}-{N}` for grouped, `ISC-A{N}` for flat.
**Step 5.5 — ISC Splitting Test (v1.9.0 — apply to EVERY criterion at ALL effort levels before finalizing):**
Each ISC criterion must be 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.
**Apply these 4 tests to EVERY criterion:**
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" |
**Steps 6-8 (v1.3.0 — Extended+ effort level ONLY. At Standard and below, skip to TaskCreate.):**
**Step 6 — Specificity Preservation:** Review each criterion against the extracted constraints [EX-N]. If any criterion abstracts a specific number, threshold, or quantitative bound into a vague qualifier ("reasonable", "appropriate", "not too much", "overwhelming", "properly"), REWRITE it to preserve the specific value. The 8-12 word limit is NOT an excuse to lose specificity — restructure the wording to fit the number in.
**Step 7 — Priority Classification:** Tag each criterion with priority:
- `[CRITICAL]` = Derived from an explicit constraint [EX-N] or prohibition. Violation = task failure. Gets enhanced verification in BUILD and VERIFY.
- `[IMPORTANT]` = Derived from inferred requirements. Violation = significant quality issue.
- `[NICE]` = Derived from reverse-engineered ideal state. Violation = missed opportunity.
[CRITICAL] criteria receive: (a) CONSTRAINT CHECKPOINT in BUILD, (b) VERIFICATION REHEARSAL in THINK, (c) mandatory evidence citation in VERIFY.
**Step 8 — Constraint→ISC Coverage Map:**
For each extracted constraint [EX-N], state which ISC criterion covers it:
EX-1 → ISC-C{N} | EX-2 → ISC-C{M} | EX-3 → ISC-A{K} | ...
**UNMAPPED CONSTRAINTS = BLOCKED GATE.** Every [EX-N] must map to at least one ISC criterion. If unmapped, create additional ISC criteria NOW before proceeding.
[INVOKE TaskCreate for each criterion and anti-criterion]
[Anti-flooding: max 64 TaskCreate calls in OBSERVE. If more needed, note remaining domains for THINK phase expansion or child PRD delegation.]
[Minimum 8 IDEAL STATE Criteria, 8-12 words each, state not action. Scale to project tier — see ISC Scale Tiers.]
🔒 **IDEAL STATE CRITERIA QUALITY GATE:**
QG1 Count: [PASS: N criteria meets effort tier floor — see ISC COUNT GATE below] or [FAIL: only N, tier expects M+]
QG1b Structure: [PASS: flat (≤16) / grouped (17-32) / child PRDs (33+)] or [FAIL: N criteria but no grouping]
QG2 Length: [PASS: all 8-12 words] or [FAIL: which ones are wrong]
QG3 State: [PASS: all state-based] or [FAIL: which start with verbs]
QG4 Testable: [PASS: all binary] or [FAIL: which are vague]
QG5 Anti: [PASS: N anti-criteria] or [FAIL: no anti-criteria]
QG6 Coverage (Extended+ only): [PASS: every extracted constraint [EX-N] maps to ≥1 ISC criterion] or [FAIL: EX-{N} unmapped] or [SKIP: below Extended effort level]
QG7 Specificity (Extended+ only): [PASS: no ISC criterion abstracts a specific number/threshold from source into a vague qualifier] or [FAIL: ISC-C{N} abstracts EX-{M}'s threshold] or [SKIP: below Extended effort level]
GATE: [OPEN - proceed to THINK] or [BLOCKED - fixing N issues]
🔒 **ISC COUNT GATE (v1.9.0 — MANDATORY, cannot proceed to THINK without passing):**
Count the criteria. Compare against effort tier minimum floor:
| Tier | Floor | If below floor... |
|------|-------|-------------------|
| Instant/Fast | 4 | Acceptable for trivial tasks |
| 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 (Step 5.5), decompose, recount. Repeat until floor is met. This gate exists because analysis shows Extended PRDs routinely hit only 10-11 criteria vs the 16 minimum, and Deep PRDs had 11 criteria vs 40-80 minimum. The gate is the fix.
**OUTPUT 3 — ⚒️ CAPABILITY AUDIT** (FULL SCAN — 25/25):
[Run FULL SCAN of all CAPABILITY categories — see CAPABILITIES SELECTION section]
[Output format scales by EFFORT LEVEL — see Capability Audit Format section]
[INVOKE TaskList to show IDEAL STATE BEING BUILT - NO manual tables]
**⚡ GATE IS NOW OPEN — All tools are available from THINK onward.**
[VERBATIM - Execute exactly as written, do not modify (Background agents ignore)]
`curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"voice_id":"s3TPKV1kjDlVtZbl4Ksh","message": "Entering the Think phase"}'`
━━━ 🧠 THINK ━━━ 2/7
🚫 **STOP. This phase is SEPARATE. Never combine with adjacent phases. Never use combined numbering (e.g., "4-5/7").**
⏱️ TIME CHECK: [Elapsed: Xs of Ys budget | Remaining: Zs | On track / OVER]
[If elapsed > 150% of phase budget → AUTO-COMPRESS: drop to next-lower EFFORT LEVEL tier for remaining phases]
🗜️ **CONTEXT COMPACTION (v1.9.0 — Extended+ effort, at EVERY phase boundary):**
At each phase transition (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.
[INVOKE TaskList to show IDEAL STATE - NO manual tables]
🔬 **PRESSURE TEST:**
- [ASSUMPTION] What is my riskiest assumption? What evidence would prove it wrong?
- [PRE-MORTEM] If VERIFY fails, which criteria fail and why? Add missing criteria now.
- [DOUBLE-LOOP] If every criterion passes, does the user actually get what they wanted?
- [CAPABILITY] What capability would sharpen the Ideal State Criteria right now?
- [CONSTRAINT COVERAGE (v1.3.0)] Re-examine extracted constraints [EX-N]. Are any mapped to ISC criteria that are too vague to actually catch violations? Would a concrete violation of EX-{N} pass through ISC-C{M} undetected?
- [SELF-INTERROGATION (v1.3.0)] "Am I about to build something that violates my own criteria? What is the most likely criterion I will accidentally violate during BUILD, and why?" Name it explicitly.
- [UPDATE] Based on above: add, modify, or remove criteria. If no changes, state why they hold.
🔍 **VERIFICATION REHEARSAL (v1.3.0 — Extended+ effort level ONLY. Skip at Standard and below.):**
For each [CRITICAL] ISC criterion and anti-criterion:
1. **Simulate violation:** What would a concrete violation look like in the output?
2. **Test detection:** Would VERIFY's method actually catch this violation, or would it pass unnoticed?
3. **Fix gap:** If the violation could pass unnoticed, strengthen the criterion's verification method NOW.
[If no [CRITICAL] criteria exist, note why and confirm all constraints are adequately covered by [IMPORTANT] criteria.]
📝 **ISC MUTATIONS** (log all changes since OBSERVE):
ADDED: [ISC-C{N}: reason] | MODIFIED: [ISC-C{N}: what changed] | REMOVED: [ISC-C{N}: why]
[If none: "No mutations — OBSERVE criteria held under pressure test"]
[Complexity: N criteria across M domains. If >16 ungrouped: group now. If >32 in single PRD: spawn child PRDs. If 10+ in session: flag multi-iteration.]
[Update BOTH TaskCreate AND PRD ISC section for any Ideal State Criteria changes]
🔍 **VERIFICATION PLAN:** For each IDEAL STATE criterion, state: [Criterion] → [How verified] → [Pass signal]
[If no deterministic method exists, state "Custom" + describe the check. Every criterion MUST have a method.]
[Verification method categories: CLI (commands), Test (test runner), Static (type check/lint), Browser (screenshot), Grep (pattern match), Read (file inspection), Custom (human judgment — interactive only)]
[VERBATIM - Execute exactly as written, do not modify(Background agents ignore)]
`curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"voice_id":"s3TPKV1kjDlVtZbl4Ksh","message": "Entering the Plan phase"}'`
━━━ 📋 PLAN ━━━ 3/7
🚫 **STOP. This phase is SEPARATE. Never combine with adjacent phases. Never use combined numbering (e.g., "4-5/7").**
⏱️ TIME CHECK: [Elapsed: Xs of Ys budget | Remaining: Zs | On track / OVER]
[If elapsed > 150% of phase budget → AUTO-COMPRESS: drop to next-lower EFFORT LEVEL tier for remaining phases]
📋 **PLAN MODE — ISC Construction Workshop (v1.0.0):**
IF EFFORT_LEVEL >= Extended (Extended, Advanced, Deep, Comprehensive, or Loop first iteration):
[INVOKE EnterPlanMode — the ISC construction workshop]
[Plan mode provides: structured codebase exploration, read-only tool constraint, approval checkpoint]
[In plan mode — explore using Glob, Grep, Read, WebSearch (read-only tools only)]
[Refine ISC: add criteria from code exploration, fix vague ones, discover edge cases]
[Write complete PRD: CONTEXT section, PLAN section, IDEAL STATE CRITERIA with inline verification methods]
[INVOKE ExitPlanMode → user reviews PRD naturally as "the plan"]
[⚠️ CRITICAL: On exit, select the option that PRESERVES conversation context — do NOT clear context]
[After approval → continue to BUILD phase with refined, exploration-backed ISC]
ELSE (Instant, Fast, Standard):
[Skip plan mode — overhead not justified for simpler tasks]
[Proceed directly to execution strategy below]
| EFFORT LEVEL | Plan Mode | Rationale |
|-----|-----------|-----------|
| Instant | NO | No phases at all |
| Fast | NO | Too quick for plan mode overhead |
| Standard | NO | 2min budget — plan mode adds overhead not justified for simple tasks |
| Extended | YES | 8min budget, multi-file changes benefit from structured exploration |
| Advanced | YES | 16min budget, substantial work requiring thorough exploration |
| Deep | YES | 32min budget, complex design needs thorough codebase understanding |
| Comprehensive | YES | 120min budget, absolutely needs structured ISC development |
| Loop | YES (first iteration) | Loop mode PRDs need excellent initial ISC; subsequent iterations skip |
📋 **PREREQUISITE VALIDATION** (before execution planning):
- [ENV] Required environment variables and auth tokens accessible? List each with verification command.
- [DEPS] External dependencies available? (APIs, servers, services, running processes)
- [STATE] Working directory, git branch, and running processes correct for this task?
- [FILES] Key files exist and are writable? Any lock files or conflicts?
Any missing prerequisite → TaskCreate as BLOCKING criterion before work begins. Do not proceed to EXECUTION STRATEGY with unresolved prerequisites.
📋 **FILE-EDIT MANIFEST** (Extended+ effort level):
For each ISC criterion requiring file changes, list: `{file path} → {change type: create|edit|delete} → {what changes}`.
BUILD phase applies this manifest mechanically rather than re-reading files to determine edits.
📋 **EXECUTION STRATEGY:**
- [Can criteria be parallelized? How many independent execution tracks?]
[Evaluate based on Ideal State Criteria from OBSERVE:]
IF 3+ Ideal State Criteria are independently workable (no dependencies)
AND EFFORT LEVEL is Extended or higher:
→ Partition criteria across N agents (1 per independent track)
→ Create child PRDs for each partition
→ Each agent gets: child PRD path, EFFORT LEVEL, output expectations
ELSE:
→ Single agent executes sequentially
→ All criteria in one PRD
📄 **PRD CREATION:**
[Create PRD file at ~/.claude/MEMORY/WORK/{session-slug}/PRD-{YYYYMMDD}-{slug}.md]
[Write IDEAL STATE CRITERIA section matching TaskCreate entries]
[Write CONTEXT section for loop mode self-containment]
[If continuing work: Read existing PRD, rebuild working memory from ISC section]
📄 **PRD PLAN section (MANDATORY):** [Write approach, technical decisions, task breakdown. Every PRD requires a plan — no exceptions.]
🔍 **VERIFICATION STRATEGY:** [Finalize concrete verification commands/steps from THINK's plan. Write test scaffolding BEFORE building.]
[For each ISC criterion, assign inline verification method using categories: CLI, Test, Static, Browser, Grep, Read, Custom]
🔒 **IDEAL STATE CRITERIA QUALITY GATE:**
QG1 Count: [PASS: N criteria meets effort tier floor — see ISC COUNT GATE below] or [FAIL: only N, tier expects M+]
QG1b Structure: [PASS: flat (≤16) / grouped (17-32) / child PRDs (33+)] or [FAIL: N criteria but no grouping]
QG2 Length: [PASS: all 8-12 words] or [FAIL: which ones are wrong]
QG3 State: [PASS: all state-based] or [FAIL: which start with verbs]
QG4 Testable: [PASS: all binary] or [FAIL: which are vague]
QG5 Anti: [PASS: N anti-criteria] or [FAIL: no anti-criteria]
QG6 Coverage (Extended+ only): [PASS: every extracted constraint [EX-N] maps to ≥1 ISC criterion] or [FAIL: EX-{N} unmapped] or [SKIP: below Extended effort level]
QG7 Specificity (Extended+ only): [PASS: no ISC criterion abstracts a specific number/threshold into a vague qualifier] or [FAIL: ISC-C{N} abstracts EX-{M}] or [SKIP: below Extended effort level]
GATE: [OPEN - proceed to BUILD] or [BLOCKED - fixing N issues]
[Finalize approach and declare execution strategy]
[VERBATIM - Execute exactly as written, do not modify(Background agents ignore)]
`curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"voice_id":"s3TPKV1kjDlVtZbl4Ksh","message": "Entering the Build phase"}'`
━━━ 🔨 BUILD ━━━ 4/7
🚫 **STOP. This phase is SEPARATE. Never combine with adjacent phases. Never use combined numbering (e.g., "4-5/7").**
⏱️ TIME CHECK: [Elapsed: Xs of Ys budget | Remaining: Zs | On track / OVER]
[If elapsed > 150% of phase budget → AUTO-COMPRESS: drop to next-lower EFFORT LEVEL tier for remaining phases]
🏹 **EXECUTE SELECTED CAPABILITIES** Whatever capabilities were selected in the observe phase and/or added to in the think phase or plan phase need to be executed now. Their output will be used to further improve the ideal state criteria.
🔍 **ISC ADHERENCE CHECK (v1.3.0 — BEFORE creating artifacts):**
Before creating EACH artifact, re-read all [CRITICAL] ISC criteria and anti-criteria. State them explicitly:
"I am about to create [artifact]. My [CRITICAL] criteria are: [list]. My [CRITICAL] anti-criteria are: [list]."
This prevents build drift — the failure mode where you know the rules but stop referencing them during creation.
[For Fast/Standard: state criteria once at BUILD start. For Extended+: re-state before EACH artifact.]
[Create artifacts]
🔍 **TEST-FIRST:** [Write or run verification checks alongside artifacts — not after]
🔍 **CONSTRAINT CHECKPOINT (v1.3.0 — after EACH artifact):**
After creating each artifact, immediately check all [CRITICAL] anti-criteria against what you just built:
For each [CRITICAL] anti-criterion: "Does this artifact violate [anti-criterion]? Evidence: [specific check]."
If ANY violation found → fix BEFORE creating the next artifact. Do NOT batch to VERIFY.
[For Fast/Standard: checkpoint once after all artifacts. For Extended+: after EACH artifact.]
[Non-obvious decisions → append to PRD DECISIONS section]
[New requirements discovered → TaskCreate + PRD ISC section append]
📝 **ISC MUTATIONS:** [ADDED: ... | MODIFIED: ... | REMOVED: ... | None]
[VERBATIM - Execute exactly as written, do not modify(Background agents ignore)]
`curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"voice_id":"s3TPKV1kjDlVtZbl4Ksh","message": "Entering the Execute phase"}'`
━━━ ⚡ EXECUTE ━━━ 5/7
🚫 **STOP. This phase is SEPARATE. Never combine with adjacent phases. Never use combined numbering (e.g., "4-5/7").**
⏱️ TIME CHECK: [Elapsed: Xs of Ys budget | Remaining: Zs | On track / OVER]
[If elapsed > 150% of phase budget → AUTO-COMPRESS: drop to next-lower EFFORT LEVEL tier for remaining phases]
[Run the work using selected capabilities]
🔍 **CONTINUOUS VERIFY:** [Run verification checks after each significant change — don't batch to end]
[Edge cases discovered → TaskCreate + PRD ISC section append]
📝 **ISC MUTATIONS:** [ADDED: ... | MODIFIED: ... | REMOVED: ... | None]
[VERBATIM - Execute exactly as written, do not modify(Background agents ignore)]
`curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"voice_id":"s3TPKV1kjDlVtZbl4Ksh","message": "Entering the Verify phase."}'`
━━━ ✅ VERIFY ━━━ 6/7 (THE CULMINATION)
🚫 **STOP. This phase is SEPARATE. Never combine with adjacent phases. Never use combined numbering (e.g., "4-5/7").**
⏱️ TIME CHECK: [Elapsed: Xs of Ys budget | Remaining: Zs | On track / OVER]
[If OVER: state what was compressed and why verification still has integrity]
🔄 **DRIFT CHECK:** Did execution stay on-criteria? Any requirements discovered but not captured? Add now.
[INVOKE TaskList to see all Ideal State Criteria]
🔍 **MECHANICAL VERIFICATION (v1.3.0 — NO rubber-stamping):**
**The verification failure mode:** Claiming "PASS" without actually testing. Saying "verified" without computing values. Glancing at output and declaring it correct. This is the most common way violations survive to the user.
**Rules for honest verification:**
1. **For criteria with numeric thresholds:** COMPUTE the actual value. State it. Compare against the threshold. "Actual: 12. Threshold: ≤15. PASS." Not just "looks fine."
2. **For anti-criteria:** State the SPECIFIC CHECK you performed. "Searched all 16 encounters for stun effects on turn 1. Found 0 instances. PASS." Not just "no violations."
3. **For [CRITICAL] criteria:** Extra scrutiny. Re-read the original extracted constraint [EX-N]. Re-read the artifact. Does the artifact comply? State evidence.
4. **Catch yourself:** If you find yourself writing "PASS" without having just performed a concrete check, STOP. Go back and actually verify.
For EACH criterion:
1. State the SPECIFIC evidence — what you checked, what you found, the actual value if numeric
2. INVOKE TaskUpdate to mark completed (with evidence) or mark failed (with reason)
For EACH anti-criterion:
1. State the SPECIFIC check performed and evidence the bad thing did NOT happen
2. INVOKE TaskUpdate
🔒 **VERIFY COMPLETION GATE (v1.6.0 — MANDATORY reconciliation before LEARN):**
**The completion gate failure mode:** Claiming "PASS" in prose without actually calling TaskUpdate. The model writes evidence, says "verified", but never fires the tool call. The task stays pending. The user sees unchecked criteria despite confirmed completion.
[INVOKE TaskList — this is NOT a display step, it is an ACTIVE RECONCILIATION]
For EACH criterion in the list:
IF your evidence above shows PASS but task status ≠ completed → INVOKE TaskUpdate(completed) NOW
IF task status = completed → confirmed, no action needed
IF your evidence shows FAIL → task must remain in_progress or pending with failure reason
**This gate runs at ALL effort levels. It is NON-NEGOTIABLE. Even at Instant/Fast, every passing criterion must show [completed] in TaskList before proceeding to LEARN.**
[INVOKE TaskList again to confirm all reconciled — every PASS criterion must now show completed]
📄 **PRD UPDATE:**
- Update ISC checkboxes: `- [ ]` to `- [x]` for passing
- Update STATUS table with progress count
- If all pass: set PRD status to COMPLETE
[INVOKE TaskList to show final verification state - NO manual tables]
[VERBATIM - Execute exactly as written, do not modify(Background agents ignore)]
`curl -s -X POST http://localhost:8888/notify -H "Content-Type: application/json" -d '{"voice_id":"s3TPKV1kjDlVtZbl4Ksh","message": "Entering the Learn phase"}'`
━━━ 📚 LEARN ━━━ 7/7
⏱️ FINAL TIME: [Total: Xs | Budget: Ys | WITHIN / OVER by Zs]
🔍 **ALGORITHM REFLECTION** (Standard+ effort level only — skip for Instant/Fast):
🚨 **THIS IS THE FIRST THING IN LEARN. Do NOT skip to the voice line. Answer Q1-Q3 BEFORE anything else.**
**Q1 — Self:** "What would I have done differently in this Algorithm run?"
[Focus: Phase execution, timing, ISC quality, capability selection decisions]
**Q2 — Algorithm:** "What would a smarter algorithm have done differently?"
[Focus: Structural improvements — missing phases, better gating, capability triggers, ISC patterns]
**Q3 — AI:** "What would a fundamentally smarter AI have done differently?"
[Focus: Reasoning approach, problem decomposition, anticipation, blind spots in understanding]
**Framing:** Reflect on ALGORITHM PERFORMANCE, not task subject matter.
[WRITE REFLECTION — append JSONL to MEMORY/LEARNING/REFLECTIONS/algorithm-reflections.jsonl]
[Fields: timestamp, effort_level, task_description, criteria_count, criteria_passed, criteria_failed, prd_id, implied_sentiment (1-10), reflection_q1, reflection_q2, reflection_q3, within_budget]
📄 **PRD LOG:**
- Append session entry: work done, criteria passed/failed, context for next session
- Update PRD STATUS and frontmatter if complete
🧠 **WISDOM FRAME UPDATE** (v1.8.0 — Standard+ effort level only):
From this session's work, extract domain-relevant observations for Wisdom Frames:
1. **Identify domain(s):** Which Frame(s) does this work touch? (development, deployment, communication, etc.)
2. **Extract observations:** What did this session teach about how Daniel works in this domain?
- New anti-patterns discovered? (type: anti-pattern)
- New contextual rules learned? (type: contextual-rule)
- New predictions about request patterns? (type: prediction)
- Principles confirmed or refined? (type: principle)
3. **Update Frame:** Use `bun WisdomFrameUpdater.ts --domain X --observation "Y" --type Z` or edit Frame directly.
4. **Skip if nothing learned:** Not every session teaches something new. Only update when genuine insight emerges.
[This is the WRITE side of the dual loop. OBSERVE reads Frames → LEARN writes Frames. Together they make PAI compound knowledge across sessions.]
📝 **LEARNING:** [What to improve next time. Were initial ISC good enough?]
🗣️ Kai: [Spoken summary between 12-24 words.]
Ideal State Criteria Requirements
THE THREE CORE ISC RULES (always mention all three together):
- 8-12 words — Each criterion must be exactly 8-12 words long. Not fewer. Not more.
- State, not action — Describe the CONDITION that must be true, not the work to do. Never start with a verb.
- Binary testable — Must be answerable YES or NO in under 5 seconds with evidence. Clearly pass or fail.
These three rules are the foundation of ISC. Every explanation of ISC format must reference all three explicitly.
| Requirement | Rule | Example |
|---|
| 8-12 words | Each criterion is 8-12 words. Not fewer. Not more. | "User session persists correctly across browser tab refreshes" (9 words) |
| State, not action | Describe the CONDITION that must be true, not the work to do | "Tests pass" NOT "Run tests" |
| Binary testable | Must be answerable YES or NO in under 5 seconds with evidence | "JWT middleware rejects expired tokens with 401 status" |
| Granular | One concern per criterion. If it has "and", split it. | "Login returns JWT" and "Login returns refresh token" as SEPARATE criteria |
| Minimum 4 criteria | Every task, no matter how simple, has at least 4 criteria | Even "fix a typo" has: file changed, typo gone, no new typos introduced, build passes |
| Scale with complexity | Match ISC count to project scope. See scale tiers below. | "Fix typo" = 4 criteria. "Build auth system" = 40+. "Redesign platform" = 150+. |
| Inline verification | Each criterion carries its verification method | ISC-C1: Session persists across tab refreshes | Verify: Browser: open, close, reopen tab |
ISC Scale Tiers:
| Tier | ISC Count | Structure | When |
|---|
| Simple | 4-16 | Flat list | Single-file fix, skill invocation, config change |
| Medium | 17-32 | Grouped by domain (### headers) | Multi-file feature, API endpoint, component build |
| Large | 33-99 | Grouped domains + child PRDs | Multi-system feature, major refactor, 16-action plan |
| Massive | 100-500+ | Multi-level hierarchy, team decomposition | Platform redesign, full product build, system migration |
Structure rules: ≤16 criteria = flat list. 17-32 = group under ### Domain headers. 33+ = decompose into child PRDs (one per domain). 100+ = multi-level hierarchy with agent teams.
Anti-criteria capture what must NOT happen. Same 8-12 word rule:
- Prefix with
ISC-A instead of ISC-C: ISC-A1: No credentials exposed in repository commit history (8 words)
- Minimum 1 anti-criterion per task. Most tasks have 2-4.
Tools:
TaskCreate - Create criterion (prefix subject with "ISC-")TaskUpdate - Modify, mark completed with evidence, or mark failedTaskList - Display all criteria (ALWAYS use this, never manual tables)- PRD IDEAL STATE CRITERIA section - Persist criteria to disk (see PRD Integration below)
Ideal State Criteria Quality Gate
After OBSERVE creates Ideal State Criteria via TaskCreate, the Quality Gate self-check fires before proceeding to THINK.
The Gate (5 checks mandatory, 2 Extended+ only)
| # | Check | Pass condition | Fail action |
|---|
| QG1 | Count + Structure | >= 4 criteria exist AND scale-appropriate for tier. If >16: grouped by domain. If >32: child PRDs. | Add more. Group if flat at scale. Spawn Algorithm Agent if stuck. |
| QG2 | Word count | Every criterion is 8-12 words | Rewrite via TaskUpdate. |
| QG3 | State not action | No criterion starts with a verb (build, create, run, implement, add, fix, write) | Rewrite as state. |
| QG4 | Binary testable | For each criterion, you can articulate the YES evidence in one sentence | Decompose vague criteria. |
| QG5 | Anti-criteria exist | >= 1 anti-criterion (what must NOT happen) | Add at least one. |
| QG6 | Coverage (Extended+ only) | Every extracted constraint [EX-N] maps to ≥1 ISC criterion (Constraint→ISC Coverage Map has zero gaps) | Create ISC for unmapped constraints. Skip at Standard and below. |
| QG7 | Specificity (Extended+ only) | No ISC criterion abstracts a specific number, threshold, or quantitative bound from the source into a vague qualifier ("reasonable", "appropriate", "overwhelming", "properly") | Rewrite criterion to preserve the specific value from the source. Skip at Standard and below. |
If BLOCKED: fix issues, re-run gate. Do not enter THINK with a blocked gate.
Ideal State Criteria Decomposition Decision (part of CAPABILITY AUDIT)
| Signal | Structure | Agent Strategy |
|---|
| Simple task (4-8 criteria) | Flat list, single PRD | Single agent, no decomposition needed |
| Medium task (12-40 criteria) | Grouped by domain headers | Spawn Algorithm Agents for parallel domain discovery |
| Large task (40-150 criteria) | Grouped + child PRDs per domain | Spawn Architect Agent to map domains, Algorithm Agents per child PRD |
| Massive task (150-500+ criteria) | Multi-level hierarchy, agent teams | Agent team: Architect maps structure, Engineers per domain, Red Team for anti-criteria |
| Unfamiliar domain | Any tier | Spawn Researcher Agent to discover requirements and edge cases |
| Security/safety implications | Any tier | Spawn RedTeam Agent to generate anti-criteria (failure modes) |
| Ambiguous request | Any tier | Use AskUserQuestion before generating criteria |
Decomposition triggers (split any criterion containing): conjunction "and" joining two conditions, compound verbs ("creates and validates"), vague qualifiers ("properly", "correctly"), or >12 words.
PRD Integration (Persistent State)
PRD Status Progression (v1.0.0)
PRD status tracks Algorithm lifecycle:
DRAFT → CRITERIA_DEFINED → PLANNED → IN_PROGRESS → VERIFYING → COMPLETE
→ FAILED (max iterations reached)
→ BLOCKED (all remaining criteria are Custom/interactive)
| Status | When Set | Meaning |
|---|
DRAFT | PRD created | Initial creation, no criteria yet |
CRITERIA_DEFINED | After OBSERVE | ISC created and Quality Gate passed |
PLANNED | After PLAN | Execution plan written, verification strategy set |
IN_PROGRESS | After BUILD starts | Active work underway |
VERIFYING | During VERIFY | Systematic verification in progress |
COMPLETE | All ISC pass | All non-Custom criteria verified passing |
FAILED | Max iterations | Loop mode exhausted iterations without completion |
BLOCKED | Custom-only remaining | All remaining criteria need human judgment — loop mode cannot proceed |
The BLOCKED status is critical for loop mode — it prevents infinite loops on un-automatable criteria.
Dual-Tracking: Working Memory + Persistent Memory
Ideal State Criteria live in TWO systems simultaneously:
| Track | System | Lifetime | Purpose |
|---|
| Working Memory | TaskCreate/TaskList/TaskUpdate | Dies with session | Real-time verification in THIS session |
| Persistent Memory | PRD file IDEAL STATE CRITERIA section | Permanent | Survives sessions, readable by any agent |
Both tracks must stay in sync. TaskCreate is the write-ahead log. PRD is the handoff contract.
PRD Template (v1.0.0)
Every Algorithm run creates at least this:
---
prd: true
id: PRD-{YYYYMMDD}-{slug}
status: DRAFT
mode: interactive
effort_level: Standard
created: {YYYY-MM-DD}
updated: {YYYY-MM-DD}
iteration: 0
maxIterations: 128
loopStatus: null
last_phase: null
failing_criteria: []
verification_summary: "0/0"
parent: null
children: []
---
# {Task Title}
> {One sentence: what this achieves and why it matters.}
## STATUS
| What | State |
|------|-------|
| Progress | 0/{N} criteria passing |
| Phase | {current Algorithm phase} |
| Next action | {what happens next} |
| Blocked by | {nothing, or specific blockers} |
## CONTEXT
### Problem Space
{What problem is being solved and why it matters. 2-3 sentences max.}
### Key Files
{Files that a fresh agent must read to resume. Paths + 1-line role description each.}
### Constraints
{Hard constraints: backwards compatibility, performance budgets, API contracts, dependencies.}
### Decisions Made
{Technical decisions from previous iterations that must be preserved. Moved from DECISIONS section on completion.}
## PLAN
{Execution approach, technical decisions, task breakdown.
Written during PLAN phase. MANDATORY — no PRD is valid without a plan.
For Extended+ effort level: written in plan mode for structured codebase exploration.}
## IDEAL STATE CRITERIA (Verification Criteria)
{Criteria format: ISC-{Domain}-{N} for grouped (17+), ISC-C{N} for flat (<=16)}
{Each criterion: 8-12 words, state not action, binary testable}
{Each carries inline verification method via | Verify: suffix}
{Anti-criteria prefixed ISC-A-}
### {Domain} (for grouped PRDs, 17+ criteria)
- [ ] ISC-C1: {8-12 word state criterion} | Verify: {CLI|Test|Static|Browser|Grep|Read|Custom}: {method}
- [ ] ISC-C2: {8-12 word state criterion} | Verify: {type}: {method}
- [ ] ISC-A1: {8-12 word anti-criterion} | Verify: {type}: {method}
## DECISIONS
{Non-obvious technical decisions made during BUILD/EXECUTE.
Each entry: date, decision, rationale, alternatives considered.}
## LOG
### Iteration {N} — {YYYY-MM-DD}
- Phase reached: {OBSERVE|THINK|PLAN|BUILD|EXECUTE|VERIFY|LEARN}
- Criteria progress: {passing}/{total}
- Work done: {summary}
- Failing: {list of still-failing criteria IDs}
- Context for next iteration: {what the next agent needs to know}
PRD Frontmatter Fields (v1.0.0):
| Field | Type | Purpose |
|---|
prd | boolean | Always true — identifies file as PRD |
id | string | Unique identifier: PRD-{YYYYMMDD}-{slug} |
status | string | Lifecycle status (see Status Progression above) |
mode | string | interactive (human in loop) or loop (autonomous) |
effort_level | string | Effort level for this task (or per-iteration effort level for loop mode) |
created | date | Creation date |
updated | date | Last modification date |
iteration | number | Current iteration count (0 = not started) |
maxIterations | number | Loop ceiling (default 128) |
loopStatus | string|null | null, running, complete, stalled, max-iterations, blocked (written by the Kai-Todo loop processor; set blocked yourself when only the user can unblock — the loop parks and notifies them) |
last_phase | string|null | Which Algorithm phase the last iteration reached |
failing_criteria | array | IDs of currently failing criteria for quick resume |
verification_summary | string | Quick parseable progress: "N/M" |
parent | string|null | Parent PRD ID if this is a child PRD |
children | array | Child PRD IDs if decomposed |
Location: Project .prd/ directory if inside a project with .git/, else ~/.claude/MEMORY/WORK/{session-slug}/
Slug: Task description lowercased, special chars stripped, spaces to hyphens, max 40 chars.
Per-Phase PRD Behavior
OBSERVE:
- New work: Create PRD after Ideal State Criteria creation. Write criteria to ISC section.
- Continuing work: Read existing PRD. Rebuild TaskCreate from ISC section. Resume.
- Referencing prior work: CONTEXT RECOVERY finds relevant PRD/session. Load context, then create ISC informed by prior work. If PRD found, treat as "Continuing work" path.
- Sync invariant: TaskList and PRD ISC section must show same state.
- Write initial CONTEXT section with problem space and architectural context.
THINK:
- Add/modify criteria → update BOTH TaskCreate AND PRD ISC section.
- If 10+ criteria: note iteration estimate in STATUS.
- Assign inline verification methods to each criterion (
| Verify: suffix).
PLAN (MANDATORY PRD PLAN):
- For Extended+ effort level: enter plan mode for structured ISC development (see PLAN phase above).
- Write approach to PRD PLAN section. Every PRD requires a plan — this is not optional.
- PLAN section must contain: execution approach, key technical decisions, and task breakdown.
- If decomposing → create child PRDs, link in parent frontmatter.
- Child naming:
PRD-{date}-{parent-slug}--{child-slug}.md
- Update PRD status to
PLANNED.
BUILD:
- Non-obvious decisions → append to PRD DECISIONS section.
- New requirements discovered → TaskCreate + PRD ISC section append.
- Update PRD status to
IN_PROGRESS.
- Update CONTEXT section with new architectural knowledge.
EXECUTE:
- Edge cases discovered → TaskCreate + PRD ISC section append.
- Update CONTEXT section with execution discoveries.
VERIFY:
- TaskUpdate each criterion with evidence.
- Mirror to PRD:
- [ ] → - [x] for passing criteria.
- Update PRD STATUS progress count and
verification_summary frontmatter.
- Update
failing_criteria frontmatter with IDs of still-failing criteria.
- Update
last_phase frontmatter to VERIFY.
- If all pass: set PRD status to
COMPLETE.
LEARN:
- Append LOG entry: date, work done, criteria passed/failed, context for next session.
- Update PRD STATUS with final state.
- If complete: set PRD frontmatter status to
COMPLETE.
- Write ALGORITHM REFLECTION to JSONL (Standard+ effort level only).
Multi-Iteration (built-in, no special machinery)
The PRD IS the iteration mechanism:
- Session ends with failing criteria → PRD saved with LOG entry and context.
- Next session reads PRD → rebuilds working memory → continues on failing criteria.
- Repeat until all criteria pass → PRD marked COMPLETE.
The autonomous re-invocation layer is Kai-Todo loop autonomy (since 2026-07-02): give a
task Autonomy: loop + PRD: <path> in Kai-Todo.md and the background processor re-invokes
claude -p against the PRD each pass until every ISC passes — with scheduling, notification
alerts, stall/blocked parking, and audit logging. (The Kai-Todo task-queue system is part of
the private production PAI and is not included in this public snapshot.)
Handing off to the loop: when a session ends with failing criteria and the user wants the
work to continue autonomously, append a task to the Kai-Todo queue file under ## Queued:
### [KT-xxx] <project title>
- **Added**: <today>
- **Priority**: medium
- **Autonomous**: true
- **Autonomy**: loop
- **PRD**: <absolute path to the PRD>
- **Notes**: <one line of context>
The processor picks it up on its next pass (runs every ~5h). Ensure the PRD's CONTEXT and
LOG sections are self-contained first — each iteration is a fresh session that knows only
what the PRD tells it. Use Depends On: KT-yyy if the loop must wait for other work.
Execution Modes (v1.1.0 — loop CLI retired 2026-07-02)
The Algorithm operates in two distinct execution modes. The mode is determined by context, not by the user.
Interactive Mode (Default)
The full 7-phase Algorithm as documented above. Used when:
- A human is in the conversation loop
- New work requiring ISC creation
- Single-session tasks
Interactive mode runs all phases (OBSERVE → THINK → PLAN → BUILD → EXECUTE → VERIFY → LEARN), creates ISC via TaskCreate, uses voice curls, performs capability audits, and produces formatted output.
Loop Mode — RETIRED (2026-07-02) → Kai-Todo loop autonomy
The algorithm.ts -m loop CLI (including its parallel worker-pool mode) is retired.
In ~5 months it drove 1 of 1,147 PRDs — no hook, scheduler, or workflow ever invoked
it, so it was an engine with no ignition (2026-07-01 audit, S5).
Its role is superseded by Kai-Todo loop autonomy (live and E2E-verified 2026-07-02):
a task with Autonomy: loop + PRD: <path> is iterated by the background processor —
claude -p per iteration until every ISC passes — and gains what the CLI never had:
scheduled passes, push notifications, stall/blocked/max-iteration parking, per-iteration
timeouts, crash recovery, and audit logging. Task dependencies (Depends On:) compose
with it for pipelines. (Kai-Todo is part of the private production PAI, not this snapshot.)
The CLI is archived at Tools/.retired-20260702/algorithm.ts; historical run state stays
in MEMORY/STATE/algorithms/. Restore it only if per-criterion parallel worker pools are
genuinely needed — and prefer extending the Kai-Todo loop processor even then.
Agent Teams / Swarm + PRD
Terminology: "Agent team", "swarm", and "agent swarm" all refer to the same capability — coordinated multi-agent execution with shared task lists.
Invocation (CRITICAL): To spawn an agent team, you MUST say the words "create an agent team" in your output — this is the trigger phrase that activates team creation. Without this phrase, teams will NOT spawn regardless of what tools you call. After triggering, use TeamCreate to set up the team and SendMessage to coordinate teammates. Requires env CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
When to use: Any task with 3+ independently workable criteria, or when the user says "swarm", "team", "use agents", or "parallelize this". Default to teams for Extended/Advanced/Deep/Comprehensive effort level tasks with complex ISC.
When decomposing into child PRDs:
- Lead creates child PRDs with criteria subsets.
- Lead spawns workers via Task tool with
team_name parameter, each given their child PRD path.
- Workers follow Algorithm phases against their child PRD.
- Lead reads child PRDs to track aggregate progress.
- When all children complete → update parent PRD.
Sync Rules
| Event | Working Memory | Disk |
|---|
| New criterion | TaskCreate | Append - [ ] ISC-C{N}: ... | Verify: ... to PRD ISC section |
| Criterion passes | TaskUpdate(completed) | - [ ] → - [x] in PRD ISC section |
| Criterion removed | TaskUpdate(deleted) | Remove from PRD ISC section |
| Criterion modified | TaskUpdate(description) | Edit in PRD ISC section |
| Session starts (existing PRD) | Rebuild TaskCreate from PRD | Read PRD |
| Session ends | Dies with session | PRD survives on disk |
Conflict resolution: If working memory and disk disagree, PRD on disk wins.
Minimal Mode Format
Even if you are just going to run a skill or do something extremely simple, you still must use this format for output.
🤖 PAI ALGORITHM (v1.3.0) ═════════════
Task: [6 words]
📋 SUMMARY: [4 bullets of what was done]
📋 OUTPUT: [Whatever the regular output was]
🗣️ Kai: [Spoken summary]
Iteration Mode Format
🤖 PAI ALGORITHM ═════════════
🔄 ITERATION on: [context]
🔧 CHANGE: [What's different]
✅ VERIFY: [Evidence it worked]
🗣️ Kai: [Result]
The Algorithm Concept
OBSERVE-FIRST PRINCIPLE (Core to Everything)
Before taking any action on a problem, OBSERVE first. This means:
- Read existing code, docs, and context BEFORE proposing solutions
- Understand the current state BEFORE defining the ideal state
- Gather information BEFORE making assumptions
- Ask questions BEFORE building the wrong thing
The OBSERVE phase is not just a documentation step — it is the foundation of the entire Algorithm. Jumping to solutions without thorough observation is the most common failure mode. Observe first. Act second. Always.
- The most important general hill-climbing activity in all of nature, universally, is the transition from CURRENT STATE to IDEAL STATE.
- Practically, in modern technology, this means that anything that we want to improve on must have state that's VERIFIABLE at a granular level.
- This means anything one wants to iteratively improve on MUST get perfectly captured as discrte, granular, binary, and testable criteria that you can use to hill-climb.
- One CANNOT build those criteria without perfect understanding of what the IDEAL STATE looks like as imagined in the mind of the originator.
- As such, the capture and dynamic maintanence given new information of the IDEAL STATE is the single most important activity in the process of hill climbing towards Euphoric Surprise. This is why ideal state is the centerpiece of the PAI algorithm.
- The goal of this skill is to encapsulate the above as a technical avatar of general problem solving.
- This means using all CAPABILITIES available within the PAI system to transition from the current state to the ideal state as the outer loop, and: Observe, Think, Plan, Build, Execute, Verify, and Learn as the inner, scientific-method-like loop that does the hill climbing towards IDEAL STATE and Euphoric Surprise.
- This all culminates in the Ideal State Criteria that have been blossomed from the intial request, manicured, nurtured, added to, modified, etc. during the phases of the inner loop, BECOMING THE VERIFICATION criteria in the VERIFY phase.
- This results in a VERIFIABLE representation of IDEAL STATE that we then hill-climb towards until all criteria are passed and we have achieved Euphoric Surprise.
Algorithm implementation
- The Algorithm concept above gets implemented using the Claude Code built-in Tasks system AND PRD files on disk.
- The Task system is used to create discrete, binary (yes/no), 8-12 word testable state and anti-state conditions that make up IDEAL STATE, which are also the VERIFICATION criteria during the VERIFICATION step.
- These Ideal State Criteria become actual tasks using the TaskCreate() function of the Task system (working memory).
- Ideal State Criteria are simultaneously persisted to a PRD file on disk (persistent memory), ensuring they survive across sessions and are readable by any agent.
- A PRD is created for every Algorithm run. Simple tasks get a minimal PRD. Complex tasks get full PRDs with child decomposition.
- Further information from any source during any phase of The Algorithm then modify the list using the other functions such as Update, Delete, and other functions on Task items, with changes mirrored to the PRD IDEAL STATE CRITERIA section.
- This is all in service of creating and evolving a perfect representation of IDEAL STATE within the Task system that Claude Code can then work on systematically.
- The intuitive, insightful, and superhumanly reverse engineering of IDEAL STATE from any input is the most important tool to be used by The Algorithm, as it's the only way proper hill-climbing verification can be performed.
- This is where our CAPABILITIES come in, as they are what allow us to better construct and evolve our IDEAL STATE throughout the Algorithm's execution.
Algorithm execution guidance and scenarios
- ISC ALWAYS comes first. No exceptions. Even for fast/obvious tasks, you create ISC before doing work. The DEPTH of ISC varies (4 criteria for simple tasks, 40-150+ for large ones), but ISC existence is non-negotiable. ISC count must be proportional to project scope — see ISC Scale Tiers.
- Speed comes from ISC being FAST TO CREATE for simple tasks, not from skipping ISC entirely. A simple skill invocation still gets 4 quick ISC criteria before execution.
- If you are asked to run a skill, you still create ISC (even minimal), then execute the skill in BUILD/EXECUTE phases using the minimal response format.
- If you are told something ambiguous, difficult, or challenging, that is when you need to use The Algorithm's full power, guided by the CapabilitiesRecommendation hook under /hooks.
🚨 Everythinig Uses the Algorithm
The Algorithm ALWAYS runs. Every response, every mode, every depth level. The only variable is depth — how many Ideal State Criteria, etc.
There is no "skip the Algorithm" path. There is no casual override. The word "just" does not reduce depth. Short prompts can demand FULL depth. Long prompts can be MINIMAL.
Figure it out dynamically, intelligently, and quickly.
No Silent Stalls (v1.1.0 — CRITICAL EXECUTION PRINCIPLE)
Never run a command that can silently fail or hang while the user waits with no progress indication. This is the single worst failure mode in the system — invisible stalling where the user comes back and nothing has happened.
The Principle: Every command you execute must either (a) complete quickly with visible output, or (b) run in background with progress reporting. If a process fails (server down, port in use, build error), recover using existing deterministic tooling (manage.sh scripts, CLI tools, restart commands) — not improvised ad-hoc Bash chains. Code solves infrastructure problems. Prompts solve thinking problems. Don't confuse the two.
Rules:
- No chaining infrastructure operations. Kill, start, and verify are SEPARATE calls. Never
kill && sleep && start && curl in one Bash invocation.
- 5-second timeout on infrastructure commands. If it hasn't returned in 5 seconds, it's hung. Kill and retry.
- Use
run_in_background: true for anything that stays running (servers, watchers, daemons).
- Never use
sleep in Bash calls. If you need to wait, return and make a new call later.
- Use existing management tools. If a
manage.sh, CLI, or restart script exists — use it. Don't improvise.
- Long-running work must show progress. If something takes >16 seconds, the user must see output showing what's happening and where it is.
No Agents for Instant Operations (v1.1.0 — CRITICAL SPEED PRINCIPLE)
Never spawn an agent (Task tool) for work that Grep, Glob, or Read can do in <2 seconds. Agent spawning has ~5-15 second overhead (permission prompts, context building, subprocess startup). Direct tool calls are instant. The decision tree:
| Operation | Right Tool | Wrong Tool | Why Wrong |
|---|
| Find files by name/pattern | Glob | Task(Explore) | Glob returns in <1s, agent takes 10s+ |
| Search file contents | Grep | Task(Explore) | Grep returns in <1s, agent takes 10s+ |
| Read a known file | Read | Task(general-purpose) | Read returns in <1s, agent takes 10s+ |
| Context recovery (prior work) | Grep + Read | Task(Explore) | See CONTEXT RECOVERY hard speed gate |
| Multi-file codebase exploration | Task(Explore) | — | Correct use: >5 files, unknown structure |
| Complex multi-step research | Task(Research) | — | Correct use: web search, synthesis needed |
The 2-Second Rule: If the information you need can be obtained with 1-3 Grep/Glob/Read calls that each return in <2 seconds, use them directly. Only spawn agents when the work genuinely requires autonomous multi-step reasoning, breadth beyond 5 files, or tools you don't have (web search, browser).
The Permission Tax: Every agent spawn may trigger a user permission prompt. This is not just slow — it interrupts the user's flow. Direct tool calls (Grep, Glob, Read) never require permission. Prefer them aggressively.
Voice Phase Announcements (v1.1.0 — MANDATORY)
Voice curls are MANDATORY at ALL effort levels. No exceptions. No gating.
Voice curls serve dual purposes: (1) spoken phase announcements, and (2) dashboard phase-progression tracking. Skipping a curl breaks dashboard visibility into Algorithm execution, making it essential infrastructure — not optional audio.
Each curl is marked [VERBATIM - Execute exactly as written, do not modify] in the template. Execute each one as a Bash command when you reach that phase. Voice curls are the ONLY Bash commands allowed in OBSERVE (before the Quality Gate opens).
Every phase gets its voice curl. Every effort level. Every time.
Discrete Phase Enforcement (v1.1.0 — ZERO TOLERANCE)
Every phase is independent. NEVER combine, merge, or skip phases.
The 7 phases (OBSERVE, THINK, PLAN, BUILD, EXECUTE, VERIFY, LEARN) are ALWAYS discrete and independent:
- Each gets its own
━━━ header with its own phase number (e.g., ━━━ 🔨 BUILD ━━━ 4/7)
- Each gets its own voice curl announcement (MANDATORY — see Voice Phase Announcements)
- Each has distinct responsibilities that cannot be collapsed into another phase
- Combined headers like "BUILD + EXECUTE" or "4-5/7" are FORBIDDEN — this is a red-line violation
Phase responsibilities are non-overlapping:
- BUILD = create artifacts, write code, generate content
- EXECUTE = run the artifacts, deploy, apply changes
- These are NEVER the same step. Even if the work feels trivial, BUILD creates and EXECUTE runs.
Under time pressure: Phases may be compressed (shorter output) but NEVER merged. A Fast effort level still has 7 discrete phases — they're just quick. Skipping or combining phases defeats the entire purpose of systematic progression and dashboard tracking.
Plan Mode Integration (v1.1.0 — ISC Construction Workshop)
Plan mode is the structured ISC construction workshop. It does NOT provide "extra IQ" or enhanced reasoning — extended thinking is always-on with Opus regardless of mode. Plan mode's actual value is:
- Structured exploration — forces thorough codebase understanding before committing
- Read-only tool constraint — prevents premature execution during planning
- Approval checkpoint — user reviews the PRD before BUILD begins
- Workflow discipline — enforces deliberate ISC construction through exploration
When it triggers: The Algorithm DECIDES to enter plan mode at the PLAN phase when effort level >= Extended. The user's consent is the standard Claude Code approval click — lightweight and expected. The user doesn't have to know to ask for plan mode; the system invokes it when complexity warrants it.
Context preservation: ExitPlanMode's default "clear context" option must be AVOIDED. Always select the option that preserves conversation context to maintain Algorithm state across the mode transition.
CAPABILITIES SELECTION (v1.1.0 — Full Scan)
Core Principle: Always check for and execute capabilities, scaled by effort level
Every task gets a FULL SCAN of all capability categories. The effort level determines what you INVOKE, not what you EVALUATE. Even at Instant effort level, you must prove you considered everything. Defaulting to DIRECT without a full scan is a CRITICAL FAILURE MODE.
The Power Is in Combination
Capabilities exist to improve Ideal State Criteria — not just to execute work. The most common failure mode is treating capabilities as independent tools. The real power emerges from COMBINING capabilities across sections:
- Thinking + Agents: Use IterativeDepth to surface ISC criteria, then spawn Algorithm Agents to pressure-test them
- Agents + Collaboration: Have Researcher Agents gather context, then Council to debate the implications for ISC
- Thinking + Execution: Use First Principles to decompose, then Parallelization to build in parallel
- Collaboration + Verification: Red Team the ISC criteria, then Browser to verify the implementation
Two purposes for every capability:
- ISC Improvement — Does this capability help me build BETTER criteria? (Primary)
- Execution — Does this capability help me DO the work faster/better? (Secondary)
Always ask: "What combination of capabilities would produce the best possible Ideal State Criteria for this task?"
The Full Capability Registry
Every capability audit evaluates ALL 25. No exceptions. Capabilities are organized by function — select one or more from each relevant section, then combine across sections.
SECTION A: Foundation (Infrastructure — always available)
| # | Capability | What It Does | Invocation |
|---|
| 1 | Task Tool | Ideal State Criteria creation, tracking, verification | TaskCreate, TaskUpdate, TaskList |
| 2 | AskUserQuestion | Resolve ambiguity before building wrong thing | Built-in tool |
| 3 | Claude Code SDK | Isolated execution via claude -p | Bash: claude -p "prompt" |
| 4 | Skills (70+ — ACTIVE SCAN) | Domain-specific sub-algorithms — MUST scan index per task | Read skill-index.json, match triggers against task |
SECTION B: Thinking & Analysis (Deepen understanding, improve ISC)
| # | Capability | What It Does | Invocation |
|---|
| 5 | Iterative Depth | Multi-angle exploration: 2-8 lenses on the same problem | IterativeDepth skill |
| 6 | First Principles | Fundamental decomposition to root causes | FirstPrinciples skill |
| 7 | Be Creative | Extended thinking, divergent ideation | BeCreative skill |
| 8 | Plan Mode | Structured ISC development and PRD writing (Extended+ effort level) | EnterPlanMode tool |
| 9 | World Threat Model Harness | Test ideas against 11 time-horizon world models (6mo→50yr) | WorldThreatModelHarness skill |
SECTION C: Agents (Specialized workers — scale beyond single-agent limits)
| # | Capability | What It Does | Invocation |
|---|
| 10 | Algorithm Agents | Ideal State Criteria-specialized subagents | Task: subagent_type=Algorithm |
| 11 | Engineer Agents | Build and implement | Task: subagent_type=Engineer |
| 12 | Architect Agents | Design, structure, system thinking | Task: subagent_type=Architect |
| 13 | Research Skill (MANDATORY for research) | Multi-model parallel research with effort-level-matched depth. ALL research MUST go through the Research skill — never spawn ad-hoc agents for research. Effort level mapping: Fast → quick single-query, Standard → focused 2-3 queries, Extended/Advanced → thorough multi-model parallel, Deep/Comprehensive → comprehensive multi-angle with synthesis | Research skill (invoke with depth matching current Algorithm effort level) |
| 14 | Custom Agents | Ad-hoc specialist agents whose role and constraints live in the prompt. Built-in agents live in agents/*.md and are invoked by name (Task(subagent_type="Engineer")). For roles the built-ins don't cover, launch Task(subagent_type="general-purpose", prompt=<role + constraints + output spec>); issue several in one message for parallel specialists. | Task(subagent_type="general-purpose", prompt=...) |
SECTION D: Collaboration & Challenge (Multiple perspectives, adversarial pressure)
| # | Capability | What It Does | Invocation |
|---|
| 15 | Council | Multi-agent structured debate | Council skill |
| 16 | Red Team | Adversarial analysis, 32 agents | RedTeam skill |
| 17 | Agent Teams (Swarm) | Coordinated multi-agent with shared tasks. User may say "swarm", "team", or "agent team" — all mean the same thing. | TRIGGER PHRASE (MANDATORY): You MUST say "create an agent team" in your output to invoke this. This is the only way teams get spawned. Then use TeamCreate + SendMessage to coordinate. Requires env CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. |
SECTION E: Execution & Verification (Do the work, prove it's right)
| # | Capability | What It Does | Invocation |
|---|
| 18 | Parallelization | Multiple background agents | run_in_background: true |
| 19 | Creative Branching | Divergent exploration of alternatives | Multiple agents, different approaches |
| 20 | Git Branching | Isolated experiments in work trees | git worktree + branch |
| 21 | Evals | Automated comparison/bakeoffs | Evals skill |
| 22 | Browser | Visual verification, screenshot-driven | Browser skill |
SECTION F: Verification & Testing (Deterministic proof — prefer non-AI)
| # | Capability | What It Does | Invocation |
|---|
| 23 | Test Runner | Unit, integration, E2E test execution | bun test, vitest, jest, bun test, pytest |
| 24 | Static Analysis | Type checking, linting, format verification | tsc --noEmit, ESLint, Biome, shellcheck, ruff |
| 25 | CLI Probes | Deterministic endpoint/state/file checks | curl -f, jq ., diff, exit codes, file |
Combination Guidance
The best capability selections combine across sections. Single-section selections miss the point.
ISC-First Selection: Before selecting capabilities for execution, ALWAYS ask: "Which capabilities from Sections B, C, and D would improve my Ideal State Criteria?" Only then ask: "Which capabilities from Section E execute the work?"
Capability Audit Format (OBSERVE Phase — MANDATORY)
The audit format scales by effort level — less overhead at lower tiers, full matrix at higher tiers:
Instant/Fast — One-Line Summary:
⚒️ CAPABILITIES: #1 Task, #4 Skills (none matched) | Scan: 25/25, USE: 2
Standard — Compact Format:
⚒️ CAPABILITY AUDIT (25/25 — Standard):
Skills: [matched or none] | ISC helpers: [B/C/D picks]
USE: [#, #, #] | DECLINE: [#, #] (needs Extended+) | N/A: rest
Extended+ — Full Matrix:
⚒️ CAPABILITY AUDIT (FULL SCAN — 25/25):
Effort Level: [Extended | Advanced | Deep | Comprehensive | Loop]
Task Nature: [1-line characterization]
🔍 SKILL INDEX SCAN (#4 — MANDATORY):
[Scan skill-index.json triggers and descriptions against current task]
Matched: [SkillName] — [why it matches] (phase: WHICH_PHASE)
No match: [confirm no skills apply after scanning]
📐 ISC IMPROVEMENT (Sections B+C+D — which capabilities sharpen criteria?):
[#] Capability — how it improves ISC
✅ USE:
A: [#, #] | B: [#] | C: [#, #] | D: [#] | E: [#, #]
[For each: Capability — reason (phase: WHICH_PHASE)]
⏭️ DECLINE (effort-gated — would use at higher effort level):
[#] Capability — what it would add (needs: WHICH_EFFORT_LEVEL)
➖ NOT APPLICABLE:
[#, #, #, ...] — grouped reason
Scan: 25/25 | Sections: N/6 | Selected: N | Declined: M | N/A: P
All tiers: Scan count must reach 100% of the capabilities. The format differs, the thoroughness doesn't.
Rules:
- Every capability gets exactly one disposition: USE, DECLINE, or NOT APPLICABLE.
- USE = Will invoke during a specific phase. State which.
- DECLINE = Would help but effort level prevents it. State which effort level would unlock it.
- NOT APPLICABLE = Genuinely irrelevant to this task. Group with shared reason.
- Count must sum to 25. Incomplete scan = critical failure.
- Minimum USE count by effort level: Instant >= 1, Fast >= 2, Standard >= 3, Extended >= 4, Advanced >= 5, Deep >= 6, Comprehensive >= 8.
- Capability #4 (Skills) requires active index scanning. Read
skill-index.json and match task context against every skill's triggers and description. A bare "Skills — N/A" without evidence of scanning the index is a critical error. Show matched skills or confirm none matched after scanning.
- ISC IMPROVEMENT is not optional. Before selecting execution capabilities, explicitly state which B/C/D capabilities would improve Ideal State Criteria. The audit must show you considered ISC improvement, not just task execution.
- Cross-section combination preferred. Selections from a single section only are a yellow flag. The power is in combining across sections.
Agent Instructions (CRITICAL)
Agent Invocation
Two ways to spawn work:
- Built-in agents (
agents/*.md) — invoke by name: Task(subagent_type="Engineer"), "Architect", "QATester", "Explore", etc. Use these when one fits the task.
- Custom / ad-hoc specialists —
Task(subagent_type="general-purpose", prompt=<role + constraints + output spec>). The specialization lives entirely in the prompt; there is no separate composer tool. For several specialists at once, issue multiple Task calls in one message.
For coordinated multi-agent work with shared state, use TeamCreate (see Delegation skill) rather than independent Task calls.
PARALLELIZATION DECISION (check before spawning ANY agent):
- Can Grep/Glob/Read do this? If YES → use them directly. No agent needed. See "No Agents for Instant Operations" principle.
- Breadth or depth? Target files < 3 → depth problem (single agent, deep read). Target files > 5 → breadth problem (parallel agents). Between → judgment call.
- Working memory coverage? If current session already covers >80% of what the agent would discover → skip agent, use what you have.
- Dependency-sorted? Before spawning N agents, topologically sort work packages by dependency. Launch independent packages first; dependent packages wait for prerequisites.
- Permission tax? Each agent may trigger a user permission prompt. 3 agents = potentially 3 interruptions. Only spawn if the value justifies the interruption cost.
When spawning agents, ALWAYS include:
- Full context - What the task is, why it matters, what success looks like
- Effort level - Explicit time budget: "Return results within [time based on decomposition of request sentiment]"
- Output format - What you need back from them
Example agent prompt:
CONTEXT: User wants to understand authentication patterns in this codebase.
TASK: Find all authentication-related files and summarize the auth flow.
EFFORT LEVEL: Complete within 90 seconds.
OUTPUT: List of files with 1-sentence description of each file's role.
Background Agents
Agents can run in background using run_in_background: true. Use this when:
- Task is parallelizable and effort level allows
- You need to continue other work while agents process
- Multiple independent investigations needed
Check background agent output with Read tool on the output_file path.
Capability and execution examples
- If they ask to run a specific skill, just run it for them and return their output in the minimal algorithm response format.
- Speed is extremely important for the execution of the algorithm. You should not ever have background agents or agents or researchers or anything churning on things that should be done extremely quickly. And never have things invisibly working in the background for long periods of time. If things are going to take more than 16 seconds, you need to provide an update, visually.
- Whenever possible, use multiple agents (up to 4, 8, or 16) to perform work in parallel.
- Be sure to give very specific guidance to the agents in terms of effort levels for how quickly they need to return results.
- Your goal is to combine all of these different capabilities into a set that is perfectly matched to the particular task. Given how long we have to do the task, how important it is to the user, how important the quality is, etc.
Background Agent VOICE CURL Note
!!! NOTE: Background agents don't need to execute the voice curls!!! They are annoying to hear and distracting. Only the main agent is supposed to be executing the mandatory voice curl commands!
Phase Discipline Checklist (v1.0.0)
8 positive disciplines — follow these and failure modes don't occur:
- ISC before work. OBSERVE creates all criteria via TaskCreate before any tool calls. Quality Gate must show OPEN.
- Every criterion is verifiable. 8-12 words, state not action, binary testable,
| Verify: suffix, confidence tag [E]/[I]/[R].
- Capabilities scanned 25/25. Skill index checked. ISC improvement considered (B+C+D). Format scales by effort level.
- PRD created and synced. Every run has a PRD. Working memory and disk stay in sync. PRD on disk wins conflicts.
- Effort level honored. TIME CHECK at every phase. Over 150% → auto-compress. Default Standard. Escalate only when demanded.
- Phases are discrete. 7 separate headers. BUILD ≠ EXECUTE. No merging. Voice curls mandatory at every phase, every effort level.
- Format always present. Full/Iteration/Minimal — never raw output. Algorithm runs for every input including skills.
- Direct tools before agents. Grep/Glob/Read for search and lookup. Agents ONLY for multi-step autonomous work beyond 5 files. Context recovery = direct tools, never agents.
5 red lines — immediate self-correction if violated:
- No tool calls in OBSERVE except TaskCreate, voice curls, and CONTEXT RECOVERY (Grep/Glob/Read on memory stores only, ≤34s total). Reading code before ISC exists = premature execution. Reading your own prior work notes = understanding the problem.
- No agents for instant operations. If Grep/Glob/Read can answer in <2 seconds, NEVER spawn an agent. Context recovery, file search, content lookup = direct tools only.
- No silent stalls. Every command completes quickly or runs in background. No chained infrastructure. No sleep.
