@vpxa/aikit 0.1.214 → 0.1.216

package/scaffold/dist/definitions/protocols.mjs

@@ -3,176 +3,125 @@ function e(e){return`
 
 When dispatched as a subagent within an active flow:
 
-1. **Withdraw context first** — before any search or file reads:
+1. **HARD RULE — Withdraw context FIRST:**
    \`\`\`
-  knowledge({ action: 'withdraw', scope: 'flow', profile: '${e}', budget: 6000 })
+   knowledge({ action: 'withdraw', scope: 'flow', profile: '${e}', budget: 6000 })
    \`\`\`
-   This returns pre-analyzed context from prior agents.
-
-2. **Use returned context** — do NOT re-search or re-read files already covered
-3. **\`read_file\` ONLY** for exact lines needed for editing
-4. **Deposit new discoveries:**
+  Reuse withdrawn context before re-calling \`compact\`, \`file_summary\`, \`stratum_card\`, \`scope_map\`, \`blast_radius\`, or \`search\`.
+2. Missing in withdrawn context → call tool once. Present → reuse.
+3. **\`read_file\` ONLY** for exact edit lines.
+4. Deposit new discoveries:
    \`\`\`
    knowledge({ action: 'remember', scope: 'flow', title: '<discovery>', content: '<details>', category: 'context' })
    \`\`\`
 
 ${e===`<PROFILE>`?`**Profile:** Check your role → implementer | documenter | reviewer | researcher | debugger`:`**Profile:** \`${e}\``}
 
----`}function t(){return"\n## Evidence Citation Protocol (tier-aware)\n\n**Standalone mode:** If no FORGE task_id was provided in your dispatch prompt, skip `evidence_map` calls entirely — provide free-form findings with `file:line` citations only.\n\nThe Orchestrator runs `forge_classify` before dispatching you, and runs the final `evidence_map({ action: 'gate', task_id })` after you respond. **Do not create your own task_id or run the gate** — feed into the Orchestrator's existing evidence map.\n\n| Tier | Your responsibility |\n|------|---------------------|\n| Floor | Free-form findings with `file.ts#Lxx` citations. No `evidence_map` calls required. |\n| Standard | For every CRITICAL or HIGH finding: `evidence_map({action:'add', task_id, claim, status:'V', receipt:'file.ts#Lxx'})`. Max 2-4 adds to keep signal high. |\n| Critical | Structured claims for all CRITICAL/HIGH findings (2-4 Verified + receipts) AND tag contract/security claims with `safety_gate:'commitment'` or `safety_gate:'provenance'`. |\n\n**Every response MUST include:**\n- `**FORGE Task ID:** <task_id>` (passed in by Orchestrator, or state \"not provided\")\n- `**Tier applied:** Floor | Standard | Critical`\n- `**Findings:** <list>` with `file:line` receipts\n- Verdict: `APPROVED` | `CHANGES_REQUESTED` | `BLOCKED`\n\nDo NOT:\n- Create a new `evidence_map` (the Orchestrator already did)\n- Run `evidence_map({action:'gate'})` yourself — the Orchestrator owns the gate\n- Duplicate findings into the map that weren't CRITICAL/HIGH"}function n(...e){return e.filter(Boolean).join(`
+---`}function t(){return"\n## Evidence Citation Protocol (tier-aware)\n\nNo FORGE `task_id` → skip `evidence_map`; use `file:line` citations only.\nDo not create your own `task_id` or run the gate.\n\n| Tier | Your responsibility |\n|------|---------------------|\n| Floor | Findings with `file.ts#Lxx` citations. No `evidence_map`. |\n| Standard | Add 2-4 CRITICAL/HIGH findings with receipts. |\n| Critical | Add all CRITICAL/HIGH findings; tag contract/security claims with `safety_gate`. |\n\n**Every response MUST include:**\n- `**FORGE Task ID:** <task_id>` (passed in by Orchestrator, or state \"not provided\")\n- `**Tier applied:** Floor | Standard | Critical`\n- `**Findings:** <list>` with `file:line` receipts\n- Verdict: `APPROVED` | `CHANGES_REQUESTED` | `BLOCKED`\n\nDo NOT create a new `evidence_map`, run `evidence_map({action:'gate'})`, or add non-critical noise."}function n(...e){return e.filter(Boolean).join(`
 
 `)}function r({title:e=`Knowledge Recall`,intro:t,commands:r,followUp:i}={}){return n(`## Pre-Task: ${e} (MANDATORY)`,t,["```",...(Array.isArray(r)?r:[r]).filter(Boolean),"```"].join(`
-`),i)}function i(){return n(`## Post-Task: Capture Lesson`,"**HARD RULE:** Before reporting DONE status, load the `lesson-learned` skill and extract 1-2 engineering lessons from the changes made. Skip ONLY if changes are pure config/formatting with no logic modified.",'Quick lesson capture (when full skill feels heavy):\n```\nknowledge({ action: "lesson", subAction: "create", context: "<what situation you faced>", insight: "<what principle the solution demonstrates>", evidence: "<file:line or commit that proves it>", confidence: 65 })\n```','**Confirm/Contradict (if pre-task recalled relevant lessons):**\n- Lesson proved correct → `knowledge({ action: "lesson", subAction: "confirm", id: "<recalled-lesson-path>" })`\n- Lesson was wrong/outdated → `knowledge({ action: "lesson", subAction: "contradict", id: "<recalled-lesson-path>", evidence: "<what actually happened>" })`','```\n// Periodic maintenance (suggest every ~5 sessions):\n// knowledge({ action: "lesson", subAction: "prune" })   // archive stale\n// knowledge({ action: "lesson", subAction: "group" })   // organize similar\n// knowledge({ action: "lesson", subAction: "promote" }) // share universal (user-level only)\n```')}const a={"code-agent-base":`# Code Agent — Shared Base Instructions
+`),i)}function i(){return n(`## Post-Task: Capture Lesson`,`**HARD RULE:** Before DONE, capture 1-2 lessons unless change is pure config/formatting.`,'Quick capture:\n```\nknowledge({ action: "lesson", subAction: "create", context: "<what situation you faced>", insight: "<what principle the solution demonstrates>", evidence: "<file:line or commit that proves it>", confidence: 65 })\n```',"If recalled lesson was confirmed/invalid, use `confirm` or `contradict`.")}const a={"code-agent-base":`# Code Agent — Shared Base Instructions
 
-> This file contains shared protocols for all code-modifying agents (Implementer, Frontend, Refactor, Debugger). Each agent's definition file contains only its unique identity, constraints, and workflow. **Do not duplicate this content in agent files.**
+> Shared protocol for code-writing agents. Agent-specific files should not duplicate it.
 
 ## Invocation Mode Detection
 
-You may be invoked in two modes:
-1. **Direct** — you have full AI Kit tool access. Follow the **Information Lookup Order** below.
-2. **Sub-agent** (via Orchestrator) — you may have limited MCP tool access.
-  The Orchestrator provides context under "## Prior AI Kit Context" or "### Current Code Context" in your prompt.
-   If present, skip AI Kit Recall and use the provided context instead.
-  **Visual Output:** When running as a sub-agent, return structured data (tables, findings, metrics) as formatted text in your final response.
-  The Orchestrator will re-present relevant content to the user.
+Two modes:
+1. **Direct** — full AI Kit access. Follow **Information Lookup Order**.
+2. **Sub-agent** — limited tools possible. If prompt includes "## Prior AI Kit Context" or "### Current Code Context", use that context and do not re-read it.
 
-**Detection:** If your prompt contains "## Prior AI Kit Context" OR "### Current Code Context" OR was dispatched via \`runSubagent\`, you are in sub-agent mode. When in sub-agent mode, use provided context — do NOT re-read files already given in your prompt.
+**Detection:** "## Prior AI Kit Context" OR "### Current Code Context" OR \`runSubagent\` → sub-agent mode. Return structured text only.
 
 ---
 
 ## MANDATORY FIRST ACTION — AI Kit Initialization
 
-**Before ANY other work**, check the AI Kit index:
-
-1. Run \`status({})\` — check **Onboard Status** and note the **Onboard Directory** path
-2. If onboard shows ❌:
-   - Run \`onboard({ path: "." })\` — \`path\` is the codebase root to analyze
-   - Artifacts are written to the **Onboard Directory** automatically (the server resolves the correct location for workspace or user-level mode — you don't need to specify \`out_dir\`)
-   - Wait for completion (~30s) — the result shows the output directory path
-   - Do NOT proceed with any other work until onboard finishes
-3. If onboard shows ✅:
-   - Proceed to **Information Lookup Order** below
-
-**This is non-negotiable.** Without onboarding, you waste 10-50x tokens on blind exploration.
+Before other work:
+1. Run \`status({})\`. Record **Onboard Directory**.
+2. If onboard is ❌, run \`onboard({ path: "." })\` and wait.
+3. If onboard is ✅, continue.
 
 ---
 
 ## AI Kit Tool Discipline
 
-Use AI Kit retrieval and compression tools first. Prefer reusable compressed context over raw reads, and only drop to native tools when precision for an edit or tool fallback requires it.
+Use AI Kit retrieval/compression first. Native tools are fallback only.
 
 | NEVER use this | USE THIS instead | Why |
 |---|---|---|
-| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports — 10x fewer tokens |
-| \`read_file\` to find specific code | \`compact({ path, query })\` | Server-side read + semantic extract — 5-20x reduction |
-| Multiple \`read_file\` calls | \`digest({ sources, query: "<task description>" })\` | Compresses multiple files into token-budgeted summary |
-| \`grep_search\` / \`semantic_search\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
-| \`grep_search\` for a symbol name | \`symbol({ name })\` | Definition + references with scope and call context |
-| \`run_in_terminal\` for tsc/lint | \`check({})\` | Typecheck + lint combined, summary output |
-| \`run_in_terminal\` for test | \`test_run({})\` | Run tests with structured output |
-| Editing without reading | \`file_summary\` then targeted \`read_file\` | Prevents wrong-position edits |
-| \`get_changed_files\` | \`run_in_terminal\` with \`git diff <specific-file>\` | Returns ALL uncommitted diffs (100K+ tokens). Target specific files instead |
-| \`run_in_terminal\` for code edits (node -e, scripts, PowerShell -replace, WriteAllText) | \`replace_string_in_file\` | Terminal-based editing wastes tokens on script creation, execution output, and verification loops. Use editor tools directly. |
+| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure first |
+| \`read_file\` to find code | \`compact({ path, query })\` | Focused extract |
+| Multiple \`read_file\` calls | \`digest({ sources, query: "<task description>" })\` | Compress multi-file context |
+| \`grep_search\` / \`semantic_search\` | \`search({ query })\` | Indexed search |
+| \`grep_search\` for a symbol | \`symbol({ name })\` | Def + refs |
+| \`run_in_terminal\` for tsc/lint | \`check({})\` | Narrow validation |
+| \`run_in_terminal\` for test | \`test_run({})\` | Structured tests |
+| Editing without reading | \`file_summary\` then targeted \`read_file\` | Safer edits |
+| \`get_changed_files\` | \`run_in_terminal\` with \`git diff <specific-file>\` | Diff only target file |
+| \`run_in_terminal\` for code edits | \`replace_string_in_file\` | Avoid shell-edit loops |
 
-> **Path Note:** \`compact({path})\` and \`file_summary({path})\` accept ANY absolute path — not just indexed workspace files. They read the file directly from disk. Use them freely for cross-workspace and cross-repository file access without needing to index the target workspace first.
+> **Path Note:** \`compact({path})\` and \`file_summary({path})\` accept any absolute path.
 
-**\`read_file\` is ONLY acceptable when you need exact line content FOR EDITING (before \`replace_string_in_file\`).**
-
-For edits, first understand structure with \`file_summary\` or \`compact\`, then use targeted \`read_file\` only for the exact region.
-Never patch from search snippets or assumptions alone.
+**\`read_file\` is ONLY for exact edit lines.** Use \`file_summary\` or \`compact\` first.
 
 ## compact() Failure Recovery
 
-If \`compact()\` returns <200 bytes or empty content, the file is NOT indexed. Follow this fallback:
-
-1. **Do NOT retry** compact on the same file — it will fail again
-2. **Use \`read_file\`** with a LARGE range (e.g., \`startLine: 1, endLine: 9999\`) — NEVER chunk into small ranges
-3. **Use \`stash()\`** to cache findings from unindexed files — context pressure causes re-reads
-4. **Check \`status()\`** to see which paths are indexed before calling compact
-
-**Anti-patterns to avoid:**
-- Retrying compact 3x on same unindexed file (wastes 3 tool calls)
-- Falling back to read_file in small chunks (10-50 lines) — each chunk costs ~3K prompt tokens in overhead
-- Re-reading the same file later because you forgot the content — use stash() to cache
-
-*Why:* these tools reduce token cost, shrink duplicate reads, and lower the odds of wrong-file or wrong-position edits while preserving reusable context.
+\`compact()\` <200 bytes or empty usually means unindexed file:
+1. Do not retry.
+2. Use one large \`read_file\` range.
+3. Cache findings with \`stash()\`.
+4. Check \`status()\` before another \`compact\`.
 
 ---
 
 ## Context Caching (MANDATORY for multi-step tasks)
 
-After your first \`file_summary\` or \`compact\` call on a file, cache the result:
+After first \`file_summary\` or \`compact\` on a file, cache it:
 \`\`\`
 stash({ action: 'set', key: 'ctx:<filename>', value: '<summary result>' })
 \`\`\`
 
-Before reading the same file again, check the cache:
+Before reading same file again, check cache:
 \`\`\`
 stash({ action: 'get', key: 'ctx:<filename>' })
 \`\`\`
 
-If cached → use it. If not → call \`file_summary\`/\`compact\` and cache.
-**NEVER \`read_file\` the same file twice** without checking stash first.
+If cached → reuse. If not → fetch and cache. Never \`read_file\` same file twice without checking \`stash\`.
 
 ---
 
 ## Access Failure Detection
 
-When \`web_fetch\` or \`http\` tool calls fail with access issues, detect and report back immediately.
+When \`web_fetch\` or \`http\` hits access issues, report immediately.
 
 **Detection signals:**
 - \`web_fetch\` returns HTML containing: \`login\`, \`sign in\`, \`sign-in\`, \`saml\`, \`sso\`, \`captcha\`, \`verify\`, \`cloudflare\`, \`challenge\`
 - \`http\` returns status 401, 403, or 407
 - \`web_fetch\` returns a redirect to a different domain (SSO redirect)
 
-**Action:** Report \`NEEDS_CONTEXT\` with:
-- The failing URL
-- The detection signal (which keyword/status code triggered it)
-- Brief quote of the response (first 200 chars of HTML body, or status code)
-
-Do NOT attempt to fix access issues yourself — the Orchestrator handles browser escalation.
+**Action:** Report \`NEEDS_CONTEXT\` with URL, trigger, and short quote/status. Do not self-escalate.
 
 ## Present + Browser Coordination
 
-When \`present()\` uses browser transport (returns a URL like \`http://localhost:PORT/...\`):
-- The system default browser opens for user viewing
-- If you need to **programmatically observe** the content, open it in the controlled browser: \`browser({ action: 'open', url: '<present-url>', mode: 'ui' })\`
-- This is primarily used by the Orchestrator for interactive surfaces with \`actions\`
+When \`present()\` opens browser transport, default browser handles user view. Open in controlled browser only if you must inspect it programmatically.
 
 
 ## Domain Skills
 
-Your agent file lists domain-specific skills in the **Skills** section. Load them as needed:
-
-1. Check if the current task matches a listed skill trigger
-2. If yes → load the skill file before starting implementation
-3. The following skills are **foundational** — always loaded, do not re-load:
-   - **\`aikit\`** — AI Kit MCP tool reference, search strategies, compression workflows, session protocol. **Required for all tool usage.**
-
-> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
+Check agent **Skills**. If task matches, load that skill first.
+**\`aikit\`** is foundational; do not re-load it.
 
 ## Skills NOT Permitted for Code Agents
 
-The following skills are for **planning/orchestration phase only**. Do NOT load them:
-
-| Skill | Why not |
-|-------|---------|
-| \`brainstorming\` | Design exploration is done BEFORE you are dispatched. Your job is to implement the design, not create one. |
-| \`requirements-clarity\` | Requirements are clarified during planning. You receive clear scope. |
-| \`multi-agents-development\` | Only the Orchestrator dispatches agents. |
-| \`c4-architecture\` | Architecture diagrams are created during planning, not implementation. |
-| \`adr-skill\` | Decisions are recorded by Orchestrator/Planner, not implementers. |
-| \`present\` | Subagents cannot render visual content to users. Return structured text instead. |
-
-If you're uncertain about requirements or design, return status \`NEEDS_CONTEXT\` to the Orchestrator — do NOT load a planning skill to figure it out yourself.
+Planning-only skills: \`brainstorming\`, \`requirements-clarity\`, \`multi-agents-development\`, \`c4-architecture\`, \`adr-skill\`, \`present\`.
+If reqs/design are unclear, return \`NEEDS_CONTEXT\`.
 
 ---
 
 ## Information Lookup Order (MANDATORY)
 
-Always follow this order when you need to understand something. **Never skip to step 3 without checking steps 1-2 first.**
-
-> **How to read artifacts:** Use \`compact({ path: "<dir>/<file>" })\` where \`<dir>\` is the **Onboard Directory** from \`status({})\`.
-> \`compact()\` reads a file and extracts relevant content — **5-20x fewer tokens** than \`read_file\`.
+Follow this order. Do not skip to step 3 before checking steps 1-2.
+Use \`compact({ path: "<dir>/<file>" })\` for onboard artifacts.
 
 ### Step 1: Onboard Artifacts (pre-analyzed, fastest)
 
@@ -191,13 +140,7 @@ Always follow this order when you need to understand something. **Never skip to
 
 ### Step 2: Knowledge Recall (MANDATORY before implementation)
 
-**STOP. Before writing any code, check what has already been decided.**
-
-Past decisions, conventions, and patterns are stored in curated knowledge. Auto-knowledge captures facts automatically from tool outputs (conventions, errors, test results, research). Use \`search()\` with specific keywords to surface these — they are indexed alongside manually curated entries. You MUST search before implementing:
-
-- If running as a sub-agent, start with \`knowledge({ action: "withdraw", scope: "flow", profile: "<your-role>", budget: 6000 })\` to pull prior compressed context.
-- Before re-running \`file_summary\`, \`compact\`, \`stratum_card\`, \`search\`, or \`blast_radius\`, check existing flow context first and reuse it when it is sufficient.
-- Reuse existing stash/checkpoint/workset context when present before creating new compressed artifacts.
+Before writing code, check prior decisions and flow context.
 
 \`\`\`
 search({ query: "<feature/area keywords>", limit: 5 })  // check past decisions + auto-knowledge
@@ -224,22 +167,30 @@ knowledge({ action: "withdraw", scope: "flow", profile: "<your-role>", budget: 6
 \`\`\`
 
 **Rules:**
-- **ALWAYS scope recalls** — NEVER call \`list-lessons\` without \`topic\`, NEVER call \`search\` without specific keywords. Unfiltered recall wastes tokens and returns noise.
-- If results exist → **READ them and FOLLOW** established patterns. Do not silently override.
-- If results conflict with the current task → **surface the conflict** to the user/orchestrator.
-- If flow-context search results already contain enough detail → **use them directly** instead of re-running the original tool.
-- If no results → proceed, but **persist your decisions with \`knowledge({ action: "remember", ... })\`** afterward for future recall.
-- Never assume "there's nothing stored" — always search first.
-- **Limit results** — Use \`limit: 3-5\` for search, \`minConfidence: 70\` for lessons. Only high-confidence knowledge deserves token budget.
+- Scope recalls.
+- Results exist → follow them or surface conflict.
+- Reuse flow/stash/checkpoint/workset context before re-running tools.
+- No results → proceed, then persist decisions.
+
+#### Role-Specific Auto-Knowledge Recall
+
+Use targeted searches before expensive work:
+
+| Your Role | Before doing... | Search for auto-knowledge first |
+|-----------|-----------------|--------------------------------|
+| Debugger | Retrying failed tool | \`search({ query: "<tool-name> error", content_type: "curated-knowledge", limit: 3 })\` |
+| Implementer / Frontend | Creating tests | \`search({ query: "testing convention naming", content_type: "curated-knowledge", limit: 3 })\` |
+| Researcher | Fetching web docs | \`search({ query: "<domain-or-topic>", content_type: "curated-knowledge", limit: 3 })\` |
+| Any agent | Expensive analysis | Check withdrawn flow-context + \`stash\` first |
 
 ### Step 3: Real-time Exploration (only if steps 1-2 don't cover it)
 
 | Tool | Use for |
 |---|---|
-| \`graph({ action: 'neighbors', node_id })\` | Traverse module import graph — cross-package dependencies, who-imports-whom |
+| \`graph({ action: 'neighbors', node_id })\` | Module relationships |
 | \`find({ pattern })\` | Locate files by name/glob |
-| \`symbol({ name })\` | Find symbol definition + references |
-| \`trace({ start, direction })\` | Follow call graph forward/backward |
+| \`symbol({ name })\` | Definition + refs |
+| \`trace({ start, direction })\` | Call/data flow |
 | \`compact({ path, query })\` | Read specific section of a file |
 | \`read_file\` | **ONLY** when you need exact lines for a pending edit |
 
@@ -251,45 +202,41 @@ If unsure which AI Kit tool to use → run \`guide({ goal: "what you need" })\`
 
 ## FORGE Protocol (Quality Gate)
 
-**Quick reference:**
-1. If the Orchestrator provided FORGE tier in your prompt, use it. Otherwise, run \`forge_classify\` to determine tier.
-2. **Floor tier** → implement directly, no evidence map needed.
-3. **Standard/Critical tier** → Use \`evidence_map\` to track each critical-path claim as V/A/U during your work.
-4. After implementation, add final evidence entries. The Orchestrator will run the gate.
-5. Use \`stratum_card\` for quick file context instead of reading full files. Use \`digest\` to compress accumulated context.
+1. Use Orchestrator-provided FORGE tier or run \`forge_classify\`.
+2. Floor → implement directly.
+3. Standard/Critical → track key claims in \`evidence_map\`.
+4. Orchestrator owns the final gate.
 
 ---
 
 ## Loop Detection & Tooling Failure Modes
 
-Track repeated failures. If the same approach fails, **stop and change strategy**.
+Repeated failure → stop and change strategy.
 
 | Signal | Action |
 |--------|--------|
-| Same error appears **3 times** after attempted fixes | **STOP** — do not attempt a 4th fix with the same approach |
-| Same test fails with identical output after code change | Step back — re-read the error, check assumptions, try a fundamentally different approach |
-| Fix→test→same error cycle | The fix is wrong. Re-diagnose from scratch — \`trace\` the actual execution path |
-| \`read_file\`→edit→same state | File may not be saved, wrong file, or edit didn't match. Verify with \`check\` |
+| Same error **3 times** | Stop. New approach. |
+| Same test output after change | Re-read error. Change approach. |
+| Fix→test→same error | Re-diagnose with \`trace\`. |
+| \`read_file\`→edit→same state | Verify file/position with \`check\`. |
 
 **Escalation ladder:**
-1. **Strike 1-2** — Retry with adjustments, verify assumptions
-2. **Strike 3** — Stop current approach entirely. Re-read error output. Try alternative strategy
-3. **Still stuck** — Return \`ESCALATE\` status in handoff. Include: what was tried, what failed, your hypothesis for why
-
-**Never brute-force.** If you catch yourself making the same type of edit repeatedly, you are in a loop.
+1. Strikes 1-2 → retry with changed assumptions.
+2. Strike 3 → stop current approach.
+3. Still stuck → return \`ESCALATE\` with what was tried and why it failed.
 
 ### Tooling failure exits
 | Signal | Stop condition | Exit action |
 |--------|---------------|-------------|
-| \`evidence_map\` returns HOLD | Insufficient evidence for FORGE gate | Surface concrete gaps to user — do not retry |
-| Sub-agent returns BLOCKED | Subagent cannot proceed | Read its message, escalate to user with options |
-| \`onboard\` reports stale index (>7 days) | Index is stale | Run \`reindex({})\` ONCE; if still stale, surface to user |
-| \`check\` or \`test_run\` fails 3x identical | Same failure mode repeating | STOP — surface to user with full output, do not retry |
-| \`compact\` returns < 50% reduction | Compression ineffective | Use \`file_summary\` or \`stratum_card\` instead |
+| \`evidence_map\` returns HOLD | Missing evidence | Surface gaps |
+| Sub-agent returns BLOCKED | Cannot proceed | Escalate |
+| \`onboard\` reports stale index (>7 days) | Index stale | Run \`reindex({})\` once |
+| \`check\` or \`test_run\` fails 3x identical | Same failure | Stop and surface output |
+| \`compact\` returns < 50% reduction | Poor compression | Use \`file_summary\` or \`stratum_card\` |
 
 ## Sub-agent Context Budget
 
-When dispatching subagents, choose tier based on task complexity:
+Choose tier by task size:
 
 | Tier | Budget | Tools | Use For |
 |------|--------|-------|---------|
@@ -303,59 +250,38 @@ Always tell the subagent: profile, tier, and what they should NOT do.
 
 ## Hallucination Self-Check
 
-**Verify before asserting.** Never claim something exists or works without evidence.
+Verify before asserting.
 
 | Before you... | First verify with... |
 |---------------|---------------------|
-| Reference a file path | \`find({ pattern })\` or \`file_summary({ path })\` — confirm it exists |
-| Call a function/method | \`symbol({ name })\` — confirm its signature and location |
-| Claim a dependency is available | \`search({ query: "package-name" })\` or check \`package.json\` / imports |
-| Assert a fix works | \`check({})\` + \`test_run({})\` — run actual validation |
-| Describe existing behavior | \`compact({ path, query })\` — read the actual code, don't assume |
+| Reference a file path | \`find({ pattern })\` or \`file_summary({ path })\` |
+| Call a function/method | \`symbol({ name })\` |
+| Claim a dependency exists | \`search({ query: "package-name" })\` or check \`package.json\` |
+| Assert a fix works | \`check({})\` + \`test_run({})\` |
+| Describe behavior | \`compact({ path, query })\` |
 
-**Red flags you may be hallucinating:**
-- You "remember" a file path but haven't verified it this session
-- You assume an API signature without checking the source
-- You claim tests pass without running them
-- You reference a config option that "should exist"
-
-**Rule: If you haven't verified it with a tool in this session, treat it as unverified.**
+**Rule:** Not verified this session → unverified.
 
 ---
 
 ## Ambiguity Resolution Protocol
 
-When a task admits ≥2 valid interpretations:
-1. **Name** each interpretation in one sentence.
-2. **Identify** which assumption causes the most harm if wrong (irreversibility, blast radius, user surprise).
-3. **Ask** ONE question — the one that disambiguates the highest-harm assumption.
-
-Do NOT silently pick. Do NOT ask multiple questions if one is sufficient.
+If ≥2 valid interpretations:
+1. Name them.
+2. Pick highest-harm assumption.
+3. Ask one disambiguating question.
 
 ## Scope Guard
 
-Before making changes, establish expected scope. Flag deviations early.
-
-- **Before starting**: Note how many files you expect to modify (from the task/plan)
-- **During work**: If you're about to modify **2x more files** than expected, **STOP and reassess**
-  - Is the scope creeping? Should this be split into separate tasks?
-  - Is the approach wrong? A simpler approach might touch fewer files
-- **Before large refactors**: Confirm scope with user or Orchestrator before proceeding
-- **Git safety**: For risky multi-file changes, recommend \`git stash\` or working branch first
+Set expected file count before changes. If scope doubles, stop and reassess.
 
 ---
 
 ## MANDATORY: Memory Persistence Before Completing
 
-**Before finishing ANY task**, you MUST call \`knowledge({ action: "remember", ... })\` if ANY of these apply:
-
-- ✅ You discovered how something works that wasn't in onboard artifacts
-- ✅ You made an architecture or design decision
-- ✅ You found a non-obvious solution, workaround, or debugging technique
-- ✅ You identified a pattern, convention, or project-specific gotcha
-- ✅ You encountered and resolved an error that others might hit
+Before finishing, call \`knowledge({ action: "remember", ... })\` if you discovered a non-obvious pattern, decision, workaround, or gotcha.
 
-**How to persist knowledge:**
+How to persist knowledge:
 \`\`\`
 knowledge({
   action: "remember",
@@ -365,70 +291,38 @@ knowledge({
 })
 \`\`\`
 
-**Examples:**
-- \`knowledge({ action: "remember", title: "Auth uses JWT refresh tokens with 15min expiry", content: "Access tokens expire in 15 min, refresh in 7 days. Middleware at src/auth/guard.ts validates.", category: "patterns" })\`
-- \`knowledge({ action: "remember", title: "Build requires Node 20+", content: "Uses Web Crypto API — Node 18 fails silently on crypto.subtle calls.", category: "conventions" })\`
-- \`knowledge({ action: "remember", title: "Decision: LanceDB over Chroma for vector store", content: "LanceDB is embedded (no Docker), supports WASM, better for user-level MCP.", category: "decisions" })\`
-- For repeatable insights, create a lesson: \`knowledge({ action: "lesson", sub_action: "create", title: "<lesson>", content: "<details>", category: "patterns" })\`
-
-**If you complete a task without remembering anything, you likely missed something.** Review what you learned.
-
-For outdated AI Kit entries → \`knowledge({ action: "update", path, content, reason })\`
+For outdated entries → \`knowledge({ action: "update", path, content, reason })\`.
 
 ---
 
 ## Guidelines
 
-Behavioral guidelines to reduce common LLM coding mistakes. Apply when writing, reviewing, or refactoring code.
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+Use these rules when writing, reviewing, or refactoring.
 
 ### 1. Think Before Coding
 
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-- State assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them — don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-- Read existing code patterns in the area you're changing before designing your approach.
+- State assumptions.
+- Multiple interpretations → surface them.
+- Simpler path exists → say so.
+- Unclear → stop and ask.
+- Read nearby patterns first.
 
 ### 2. Simplicity First
 
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+- Minimum code that solves the task.
+- No speculative abstractions, flexibility, or impossible-scenario handling.
+- If 200 lines could be 50, rewrite it.
 
 ### 3. Surgical Changes
 
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it — don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
+- Touch only required lines.
+- Match existing style.
+- Remove only dead code you create.
+- Every changed line should trace to request.
 
 ### 4. Goal-Driven Execution
 
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
+Define success criteria and verify them.
 
 For multi-step tasks, state a brief plan:
 \`\`\`
@@ -437,8 +331,6 @@ For multi-step tasks, state a brief plan:
 3. [Step] → verify: [check]
 \`\`\`
 
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
 ### 5. Quality Dimensions
 
 Verify each before returning handoff:
@@ -449,36 +341,34 @@ Verify each before returning handoff:
 | **Standards** | Follows project conventions? Lint-clean? |
 | **Architecture** | Fits existing patterns? No unnecessary coupling? |
 | **Robustness** | Handles edge cases? No obvious failure modes? |
-| **Maintainability** | Clear naming? Minimal complexity? Would another developer understand it? |
+| **Maintainability** | Clear naming? Minimal complexity? Understandable to another developer? |
 
 ### 6. Test-Driven Development
 
-**Vertical slices, NOT horizontal layers.**
-
-- Write ONE test → make it pass → repeat. Never write a batch of tests then implement all at once.
-- **Tracer bullet first** — get one thin slice working end-to-end before broadening. Proves architecture before investing in breadth.
-- Tests verify **behavior through public interfaces**, not implementation details. If refactoring internals breaks tests, those tests are wrong.
-- When adding a feature: write the test for the simplest case FIRST, get green, then add the next case.
+- Vertical slices, not horizontal layers.
+- One test → make it pass → repeat.
+- Start with tracer bullet.
+- Test public behavior, not implementation detail.
 
 ---
 
 ## User Interaction Rules
 
-When you need user input or need to explain something before asking:
+**Presentation Priority (HARD RULE — applies to ALL output):**
 
-| Situation | Method | Details |
-|-----------|--------|---------|
-| Simple explanation + question | **Elicitation** | Text-only explanation, then ask via elicitation fields |
-| Rich content explanation + question | **Structured text + Elicitation** | Explain with concise markdown/plain text, then ask via elicitation fields |
-| Complex visual explanation | **Structured text + Elicitation** | Summarize the important comparisons or findings in text for the Orchestrator to render later if needed |
-| **CLI mode** (any rich content) | **Structured text + Elicitation** | Keep output text-only; user-facing rendering belongs to the Orchestrator or another non-code agent |
+| Priority | Transport | When to use | Example |
+|----------|-----------|-------------|---------|
+| **1st — Interactive** | Browser (\`present\` with \`actions[]\` or template) | Plans, decisions needing approval, comparisons, status boards, any data >3 rows | \`present({ ..., template: "task-plan@1", actions: [...] })\` |
+| **2nd — Inline Visual** | MCP App (\`present\` without actions) | Reports, summaries, diagrams, progress updates, any structured content | \`present({ ..., blocks: [...] })\` |
+| **3rd — Plain Text** | Markdown in chat | Short confirmations (≤3 sentences), simple questions, status one-liners | "Done. 3 files updated." |
 
 **Rules:**
-- **Use concise structured text** for tables, findings, and comparisons that the Orchestrator can render later if needed
-- **Confirmation selections** should use elicitation choices when available
-- **Free-form text input** always goes through elicitation
-- **Prefer the simplest method** that adequately conveys the information
-- **Keep code-agent output text-only** for both direct and sub-agent execution
+- NEVER use plain text when data fits a \`present\` template or has >3 structured items
+- NEVER render tables as markdown when \`present\` can show them interactively
+- Use registered templates when data matches: \`task-plan@1\`, \`report@1\`, \`status-board@1\`, \`timeline@1\`, \`kanban@1\`, \`data-table@1\`, \`checklist@1\`
+- Add \`actions[]\` when user input/approval is needed (triggers browser transport automatically)
+- Elicitation fields for free-form text input alongside any \`present\` call
+- Code-agent subagents: text-only output (Orchestrator renders visually on their behalf)
 
 ${e(`<PROFILE>`)}
 
@@ -502,8 +392,7 @@ Always return this structure when invoked as a sub-agent:
 
   ## AI Kit MCP Tool Naming Convention
 
-  All tool references in these instructions use **short names** (e.g. \`status\`, \`compact\`, \`search\`).
-  At runtime, these are MCP tools exposed by the AI Kit server. Depending on your IDE/client, the actual tool name will be prefixed:
+  Tool references use short names (e.g. \`status\`, \`compact\`, \`search\`). Runtime names are usually prefixed:
 
   | Client | Tool naming pattern | Example |
   |--------|-------------------|---------|
@@ -511,24 +400,22 @@ Always return this structure when invoked as a sub-agent:
   | Claude Code | \`mcp__<serverName>__<tool>\` | \`mcp__aikit__status\` |
   | Other MCP clients | \`<serverName>_<tool>\` or bare \`<tool>\` | \`aikit_status\` or \`status\` |
 
-  The server name is \`aikit\` — check your MCP configuration if tools aren't found.
-
-  **When these instructions say** \`status({})\` **→ call the MCP tool whose name ends with** \`_status\` **and pass** \`{}\` **as arguments.**
-
-  If tools are deferred/lazy-loaded, load them first (e.g. in VS Code Copilot: \`tool_search_tool_regex({ pattern: "aikit" })\`).
+  Server name is \`aikit\`.
+  **When these instructions say** \`status({})\` **→ call the tool whose name ends with** \`_status\`.
+  If tools are deferred/lazy-loaded, load them first (for example \`tool_search_tool_regex({ pattern: "aikit" })\`).
 `,"researcher-base":`# Researcher — Shared Base Instructions
 
-> Shared methodology for all Researcher variants. Each variant's definition contains only its unique identity and model assignment. **Do not duplicate.**
+> Shared methodology for Researcher variants. Do not duplicate it in variant files.
 
 
 ## MANDATORY FIRST ACTION
 
-Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+Follow **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
 1. Run \`status({})\` — check Onboard Status and note the **Onboard Directory** path
 2. If onboard shows ❌ → Run \`onboard({ path: '.' })\` and wait for completion
 3. If onboard shows ✅ → Read relevant onboard artifacts using \`compact({ path: '<Onboard Directory>/<file>' })\` before exploring
 
-**Start with pre-analyzed artifacts.** They cover 80%+ of common research needs.
+Start with pre-analyzed artifacts.
 
 ${e(`researcher`)}
 
@@ -541,20 +428,16 @@ scope_map({ task: "what you need to investigate" })
 \`\`\`
 
 ### Phase 2: Exploration
-- Use \`graph\`, \`symbol\`, \`trace\`, \`find\`
-for code exploration (graph FIRST for module relationships)
-- Use \`graph({ action: 'neighbors' })\` to understand cross-module dependencies before diving into symbol details
-- Use \`file_summary\`, \`compact\` for efficient file reading
-- Use \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "dependencies", ... })\` for package-level understanding
-- Use \`web_search\`, \`web_fetch\` for external documentation
+- Use \`graph\`, \`symbol\`, \`trace\`, \`find\` for code exploration.
+- Use \`file_summary\` and \`compact\` for reading.
+- Use \`analyze\` for package-level structure/deps.
+- Use \`web_search\` and \`web_fetch\` for external docs.
 
 ### Phase 3: Synthesis
-- Combine findings from multiple sources using \`digest\`
-- Create \`stratum_card\` for key files that will be referenced later
-- Build a coherent picture of the subsystem
+- Use \`digest\` and \`stratum_card\` to compress findings.
 
 ### Phase 4: Report
-Return structured findings. Always include:
+Return structured findings. Include:
 1. **Summary** — 1-3 sentence overview
 2. **Key Findings** — Bullet list of important discoveries
 3. **Files Examined** — Paths with brief purpose notes
@@ -564,11 +447,7 @@ Return structured findings. Always include:
 
 ### Phase 5: MANDATORY — Persist Discoveries
 
-**Before returning your report**, you MUST call \`knowledge({ action: "remember", ... })\` for:
-- ✅ Architecture insights not already in onboard artifacts
-- ✅ Non-obvious findings, gotchas, or edge cases
-- ✅ Trade-off analysis and recommendations made
-- ✅ External knowledge gathered from web_search/web_fetch
+Before returning, call \`knowledge({ action: "remember", ... })\` for non-obvious findings, decisions, gotchas, or external research worth keeping.
 
 \`\`\`
 knowledge({
@@ -579,30 +458,24 @@ knowledge({
 })
 \`\`\`
 
-**If you complete research without persisting anything, you wasted tokens.** Your research should enrich the AI Kit knowledge store for future sessions.
-
 ---
 
 ## FORGE-Aware Research
 
-When investigating tasks that involve code changes (architecture decisions, design analysis, subsystem investigation):
-
-1. **Classify** — Run \`forge_classify({ task, files, root_path })\` to determine the complexity tier
-2. **Track findings** (Standard+) — Use \`evidence_map\` to record critical findings as verified claims with receipts
-3. **Flag risks** — If research reveals security, contract, or cross-boundary concerns, note the FORGE tier upgrade implications
-4. **Report tier recommendation** — Include FORGE tier and triggers in your research report
-
-This ensures the Orchestrator and Planner have tier context when planning implementation.
+For code-change research:
+1. Run \`forge_classify({ task, files, root_path })\`.
+2. Standard+ → record key findings in \`evidence_map\`.
+3. Report tier/risk implications.
 
 ---
 
 ## Multi-Model Decision Context
 
-When invoked for a decision analysis, you receive a specific question. You MUST:
-1. **Commit to a recommendation** — do not hedge with "it depends"
-2. **Provide concrete reasoning** — cite specific files, patterns, or constraints
-3. **Acknowledge trade-offs** — show you considered alternatives
-4. **State your confidence level** — high/medium/low with reasoning
+When invoked for decision analysis, you receive a specific question. You MUST:
+1. Commit to a recommendation.
+2. Cite concrete evidence.
+3. Acknowledge trade-offs.
+4. State confidence.
 
 ---
 
@@ -614,25 +487,25 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Context Efficiency
 
-> **Reminder:** Apply Context Efficiency rules — prefer compact/digest/file_summary over raw read_file. See \`code-agent-base\` for full table.
+> Prefer \`compact\`/\`digest\`/\`file_summary\` over raw \`read_file\`.
 
 ## Parallel Exploration via \`lane\`
 
 For questions that require trying approach A vs approach B in isolation:
 1. \`lane({ action:'create', name:'approach-a' })\` — isolated file copies
-2. Apply approach A mentally; record observations
+2. Evaluate approach A; record observations
 3. \`lane({ action:'create', name:'approach-b' })\` — second isolate
-4. Apply approach B mentally; record observations
+4. Evaluate approach B; record observations
 5. \`lane({ action:'diff', names:['approach-a','approach-b'] })\` — compare
 6. Include the diff summary in your output; do NOT merge lanes back (read-only role)
 `,"code-reviewer-base":`# Code-Reviewer — Shared Base Instructions
 
-> Shared methodology for all Code-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
+> Shared methodology for Code-Reviewer variants. Do not duplicate.
 
 
 ## MANDATORY FIRST ACTION
 
-Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+Follow **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
 1. Run \`status({})\` — check Onboard Status and note the **Onboard Directory** path
 2. If onboard shows ❌ → Run \`onboard({ path: '.' })\` and wait for completion
 3. If onboard shows ✅ → Read relevant onboard artifacts using \`compact({ path: '<Onboard Directory>/<file>' })\` — especially \`patterns.md\` and \`api-surface.md\` for review context
@@ -641,13 +514,13 @@ ${e(`reviewer`)}
 
 ## Review Workflow
 
-1. **AI Kit Recall** — \`search({ query: "conventions relevant-area" })\` + \`knowledge({ action: "list" })\` for past review findings and patterns
-2. **Blast Radius** — \`blast_radius\` on changed files to understand impact
-3. **FORGE Classify** — \`forge_classify\` to determine review depth
-4. **Review** — Evaluate against all dimensions below
-5. **Validate** — Run \`check\` (typecheck + lint) and \`test_run\`
-6. **Report** — Structured findings with verdict
-7. **Persist** — \`knowledge({ action: "remember", title: 'Review: <finding>', content: "<details>", category: "patterns" })\` for any new patterns, anti-patterns, or recurring issues found
+1. Recall patterns.
+2. Run \`blast_radius\`.
+3. Run \`forge_classify\`.
+4. Review dimensions below.
+5. Validate with \`check\` and \`test_run\`.
+6. Report.
+7. Persist recurring findings.
 
 ## Review Dimensions
 
@@ -687,17 +560,17 @@ ${e(`reviewer`)}
 - **APPROVED** requires zero CRITICAL/HIGH findings
 - **NEEDS_REVISION** for any HIGH finding
 - **FAILED** for any CRITICAL finding
-- Always check for **test coverage** on new/changed code
+- Check test coverage on changed code
 
 ${t()}
 `,"architect-reviewer-base":`# Architect-Reviewer — Shared Base Instructions
 
-> Shared methodology for all Architect-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
+> Shared methodology for Architect-Reviewer variants. Do not duplicate.
 
 
 ## MANDATORY FIRST ACTION
 
-Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
+Follow **MANDATORY FIRST ACTION** and **Information Lookup Order** from code-agent-base:
 1. Run \`status({})\` — check Onboard Status and note the **Onboard Directory** path
 2. If onboard shows ❌ → Run \`onboard({ path: '.' })\` and wait for completion
 3. If onboard shows ✅ → Read relevant onboard artifacts using \`compact({ path: '<Onboard Directory>/<file>' })\` — especially \`structure.md\`, \`dependencies.md\`, and \`diagram.md\` for architecture context
@@ -706,11 +579,11 @@ ${e(`reviewer`)}
 
 ## Review Workflow
 
-1. **AI Kit Recall** — \`search({ query: "architecture decisions boundaries" })\` + \`knowledge({ action: "list" })\` for past ADRs and patterns
-2. **Analyze** — \`analyze({ aspect: "structure", ... })\`, \`analyze({ aspect: "dependencies", ... })\`, \`blast_radius\`
-3. **Evaluate** — Check all dimensions below
-4. **Report** — Structured findings with verdict
-5. **Persist** — \`knowledge({ action: "remember", title: 'Architecture: <finding>', content: "<details>", category: "decisions" })\` for any structural findings, boundary violations, or design insights
+1. Recall architecture patterns.
+2. Analyze structure/deps and blast radius.
+3. Evaluate dimensions below.
+4. Report.
+5. Persist structural findings.
 
 ## Review Dimensions
 
@@ -721,7 +594,7 @@ ${e(`reviewer`)}
 | **SOLID Compliance** | Single responsibility, dependency inversion |
 | **Pattern Adherence** | Consistent with established patterns in codebase |
 | **Interface Stability** | Public APIs don't break existing consumers |
-| **Scalability** | Design handles growth (more data, more users, more features) |
+| **Scalability** | Design handles growth (data, users, features) |
 | **Testability** | Dependencies injectable, side effects isolated |
 
 ## Output Format
@@ -748,39 +621,29 @@ ${e(`reviewer`)}
 - **APPROVED** — No structural issues
 - **NEEDS_CHANGES** — Fixable structural issues
 - **BLOCKED** — Fundamental design flaw requiring rethink
-- Always validate **dependency direction** — inner layers must not depend on outer
+- Validate dependency direction
 
 ${t()}
 
 ## Graph-Assisted Layer Verification
 
-For each significantly changed module (from \`blast_radius\` or changed_files input):
+For each significantly changed module:
 
 1. **Discover node**: \`graph({action:'find_nodes', name_pattern:'<module-path>'})\` → get node_id
-2. **Incoming dependencies** (who depends on this?):
-  \`graph({action:'neighbors', node_id, direction:'incoming'})\`
-  — flag any caller that violates layering rules (e.g. a \`core/\` module that gets imported by \`infra/\`)
-3. **Outgoing dependencies** (what does it depend on?):
-  \`graph({action:'neighbors', node_id, direction:'outgoing'})\`
-  — flag any target that violates direction (e.g. domain importing from infra)
-4. **Isolation check** (modules that should NOT be connected):
-  \`graph({action:'depth_traverse', node_id, max_depth:3})\`
-  — verify no path reaches modules in forbidden directories
-
-Cite each layer violation as a CRITICAL finding with \`file:line\` receipt, and add it
-to the Evidence Map per the tier protocol above.
-
-**Do NOT use \`shortest_path\`** — that action does not exist. Use \`depth_traverse\`
-or repeated \`neighbors\` calls.
+2. **Incoming deps**: \`graph({action:'neighbors', node_id, direction:'incoming'})\`
+3. **Outgoing deps**: \`graph({action:'neighbors', node_id, direction:'outgoing'})\`
+4. **Isolation**: \`graph({action:'depth_traverse', node_id, max_depth:3})\`
+
+Cite layer violations with \`file:line\` receipts. Do not use \`shortest_path\`.
 `,"decision-protocol":`# Multi-Model Decision Protocol
 
-The Orchestrator uses **multi-model decision analysis** to resolve non-trivial technical choices. This is the autonomous decision-making process — distinct from the interactive brainstorming skill.
+Use for non-trivial technical decisions with multiple viable approaches.
 
 ## How It Works (3 Phases)
 
 ### Phase 1 — Independent Research (parallel)
 
-Dispatch ALL available Researcher variants **in parallel** via \`runSubagent\` — one call per variant, same question, simultaneous. Each returns an independent recommendation grounded in their thinking style:
+Dispatch Researcher variants in parallel via \`runSubagent\`.
 
 **IMPORTANT: Include these instructions in every researcher dispatch prompt:**
 - "You are running as a subagent. Do NOT use the \`present\` tool — return all analysis as plain text."
@@ -796,9 +659,9 @@ Dispatch ALL available Researcher variants **in parallel** via \`runSubagent\`
 ### Phase 2 — Peer Review (parallel)
 
 After all researchers return:
-1. **Compress** each response to its core argument (≤ 200 words) — \`stash\` full responses if needed later
-2. **Anonymize** as Perspective A / B / C / D (strip agent names)
-3. Dispatch **second parallel batch** of review sub-agents with compressed versions via \`runSubagent\`:
+1. Compress each response to ≤ 200 words.
+2. Anonymize as Perspective A / B / C / D.
+3. Dispatch second parallel review batch via \`runSubagent\`.
 
 **Peer Review Prompt Template:**
 \`\`\`
@@ -822,11 +685,11 @@ Evaluate ALL perspectives. Your review MUST include:
 4. **Your verdict** — which approach to adopt (may combine elements)
 \`\`\`
 
-Use the same 4 Researcher variants for peer review — each model reviews from its own thinking style, catching different blind spots.
+Use same 4 Researcher variants for peer review — each style catches different blind spots.
 
 ### Phase 3 — Synthesis & Verdict
 
-The Orchestrator synthesizes BOTH layers (original research + peer reviews) into a structured verdict.
+Synthesize original research + peer review into one verdict.
 
 **Verdict Format (MANDATORY):**
 
@@ -847,7 +710,7 @@ The Orchestrator synthesizes BOTH layers (original research + peer reviews) into
 \`\`\`
 
 Then:
-1. **Present** the verdict using \`present\` with browser transport. MANDATORY block types:
+1. **Present** the verdict using \`present\` with browser transport. Required block types:
    - "Where They Agree" -> \`{ "type": "list", "value": ["point 1", "point 2"] }\` — NEVER code block with JSON array
    - "Where They Clash" -> \`{ "type": "table", "value": { "headers": ["Dimension", "Alpha", "Delta"], "rows": [...] } }\`
    - "Blind Spots" -> \`{ "type": "markdown", "value": "..." }\` with **bold** key insight
@@ -858,27 +721,24 @@ Then:
 
 ## When to Use (Auto-Trigger Rules)
 
-Trigger the decision protocol when there is an **unresolved non-trivial technical decision** after requirements are understood:
+Trigger for unresolved non-trivial technical decisions after requirements are understood:
 - Architecture or infrastructure decisions with multiple viable approaches
 - Data model, schema, or storage strategy choices
 - Technology or library selection
 - Trade-offs where the "right" answer isn't obvious
 - When a sub-agent returns a recommendation that has alternatives
 
-**Do NOT use for:** Requirements discovery, user intent clarification, or feature scoping — those belong to the brainstorming skill.
+Do not use for requirements discovery or feature scoping.
 
 ## Key Rules
 
-- **\`runSubagent\` is ALWAYS available** — it is a core tool in every environment (VS Code, CLI, Copilot Chat). NEVER claim it is unavailable. NEVER simulate researchers inline by "applying lenses yourself." If you cannot call \`runSubagent\`, you have a tool-loading issue — retry or escalate, do NOT degrade to single-agent inline simulation.
-- **No \`present\` in subagents** — always include "Do NOT use the \`present\` tool — return all analysis as plain text" in every researcher dispatch prompt. Subagent visual outputs are invisible to the user.
-- Always launch in **parallel** — 4 variants for Critical, 2 (Alpha + Delta) for Standard per tier gate
-- Use exact case-sensitive agent names — never rename or alias
-- **Anonymize** researcher outputs before peer review (A/B/C/D, not agent names)
-- Peer review is a SEPARATE parallel batch — never skip it
-- Never make a non-trivial technical decision without multi-model analysis
-- Always present the verdict visually using \`present\`
-- **Produce an ADR** after every decision resolution
-- \`knowledge({ action: "remember", ... })\` the decision for future recall
+- \`runSubagent\` is required. Do not simulate researchers inline.
+- No \`present\` in subagents.
+- Launch in parallel.
+- Use exact agent names.
+- Anonymize before peer review.
+- Peer review is separate.
+- Persist decision and produce ADR.
 
 ## Tier Shortcuts
 
@@ -892,7 +752,7 @@ Trigger the decision protocol when there is an **unresolved non-trivial technica
 - Skip the Decision Protocol entirely — decide inline or with 1 researcher max
 `,"forge-protocol":`# FORGE Protocol — Quality Overlay
 
-> Follow the FORGE (Fact-Oriented Reasoning with Graduated Evidence) protocol for all code generation and modification tasks.
+> Use FORGE for code generation and modification tasks.
 
 ## AI Kit Tools for FORGE
 
@@ -915,13 +775,13 @@ When uncertain, round up.
 ## 4-Phase Flow
 
 ### Phase 1 — Ground
-Read files, blast radius, classify tier, build Typed Unknown Queue, load constraints.
+Read files, blast radius, classify tier, load constraints.
 
 ### Phase 2 — Build
 Generate with evidence anchoring. Route typed unknowns mid-generation.
 
 ### Phase 3 — Break (Standard+ only, skip for Floor)
-One adversarial round. Check error paths, edge cases, blast radius, convention violations.
+One adversarial round: error paths, edge cases, blast radius, conventions.
 
 ### Phase 4 — Gate
 Binary YIELD/HOLD. Contract-type unknowns → **HARD BLOCK**. Non-contract → 1 retry, then FORCED DELIVERY with annotation.
@@ -938,7 +798,7 @@ Status values: **V** (Verified + receipt), **A** (Assumed + reasoning), **U** (U
 
 ## Safety Gates (Standard+ only)
 
-Three mandatory checks before YIELD:
+Three checks before YIELD:
 
 | Gate | Rule | Failure |
 |------|------|---------|
@@ -948,19 +808,17 @@ Three mandatory checks before YIELD:
 
 Tag entries: \`evidence_map({ action: "add", ..., safety_gate: "provenance" })\`
 
-Safety gates are evaluated automatically during \`evidence_map({ action: "gate" })\`. Failures produce HOLD — fixable in one retry.
+\`evidence_map({ action: "gate" })\` evaluates these automatically.
 
 ## Score-Driven Iteration
 
-For quality-sensitive tasks, use the execute→score→fix→re-score pattern:
+Use execute → score → fix → re-score:
 
 1. Execute task (Build phase)
 2. Score: check({}) + test_run({}) + evidence_map({ action: "gate" })
 3. If gate != YIELD → fix issues → re-score (max 3 iterations)
 4. Track progress: stash({ action: "set", key: "iteration-N", value: JSON.stringify({ score, issues }) })
 
-Agents iterate until quality threshold is met, with diminishing returns tracked via stash.
-
 ## Example Evidence Map (Standard Tier)
 
 \`\`\`
@@ -979,6 +837,45 @@ evidence_map({ action: "gate", task_id: "add-user-api" })  → YIELD ✅
 3. **Standard**: \`evidence_map create\` → add 3-8 claims during work → \`evidence_map gate\`
 4. **Critical**: Full 4-phase flow with comprehensive evidence
 5. **After gate**: YIELD = done, HOLD = fix + re-gate, HARD_BLOCK = escalate
+`,"review-principles":`## Review Principles
+
+- Read full context before judging. Understand why code is structured this way.
+- Judge by codebase conventions, not personal taste. Conformance > preference.
+`,"planning-principles":`## Planning Principles
+
+- Read exports, callers, and utilities before planning changes.
+- Use model for judgment calls only. If code or tools can answer, they answer.
+`,"documentation-principles":`## Documentation Principles
+
+- Minimum docs that explain the concept. Nothing speculative.
+- Only update what changed. Don’t rewrite adjacent docs.
+- Match existing documentation style and structure.
+`,"thinking-principles":`# Thinking Principles
+
+> Operating constraints for analysis, review, and orchestration roles.
+
+- **Think before acting.** State assumptions. Ask rather than guess. Push back when simpler approach exists.
+- **Goal-driven.** Define success criteria before starting. Loop until verified.
+- **Token budgets are binding.** Per-task: 4,000 tokens. Per-session: 30,000 tokens. Surface breaches; do not silently overrun.
+- **Surface conflicts.** If two patterns contradict, pick one (more recent / more tested). Explain why. Flag the other.
+- **Checkpoint.** After every significant step, summarize what was done, what’s verified, what’s left.
+- **Fail loud.** “Completed” is wrong if anything was skipped. Default to surfacing uncertainty.
+`,"engineering-principles":`# Engineering Principles
+
+> Operating constraints for code-writing agents. Violating these is a defect.
+
+1. **Think before acting.** State assumptions. Ask rather than guess. Push back when simpler approach exists.
+2. **Read before writing.** Never generate from imagination. Verify types, signatures, and patterns from codebase. Every claim about existing code must have a tool receipt.
+3. **Goal-driven.** Define success criteria before starting. Loop until \`check({})\` + \`test_run({})\` confirm correctness.
+4. **Minimal footprint.** Change only what’s necessary. No drive-by refactors, no speculative helpers, no “while I’m here” additions.
+5. **Finish what you start.** Partial work is worse than no work. If blocked, surface blocker with evidence—don’t leave half-done code.
+6. **No dead code.** Don’t comment out old code, don’t leave unused imports/variables, don’t add TODO placeholders without evidence they’re needed.
+7. **Match the codebase.** Adopt existing naming, structure, error handling, and formatting conventions. When in doubt, copy a nearby example.
+8. **Verify, then declare.** “Done” means: compiles (\`check\`), tests pass (\`test_run\`), no regressions. Anything less is “in progress.”
+9. **Surface conflicts.** If two patterns contradict, pick one (more recent / more tested). Explain why. Flag the other.
+10. **Token budgets are binding.** Per-task: 4,000 tokens. Per-session: 30,000 tokens. Surface breaches; do not silently overrun.
+11. **Checkpoint.** After every significant step, summarize what was done, what’s verified, what’s left.
+12. **Fail loud.** “Completed” is wrong if tests were skipped. Default to surfacing uncertainty over false confidence.
 `},o={"execution-state":`# Execution State: {Task Title}
 
 **Status:** PLANNING | IN_PROGRESS | REVIEW | COMPLETED | BLOCKED