@vpxa/aikit 0.1.77 → 0.1.79

package/scaffold/definitions/protocols.mjs

@@ -1,863 +0,0 @@
-/**
- * Shared protocol content — base instructions referenced by multiple agents.
- *
- * Keys map to filenames: 'code-agent-base' → '_shared/code-agent-base.md'
- * Content is IDE-agnostic markdown, but adapters may wrap it differently.
- */
-
-export const PROTOCOLS = {
-  '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.**
-
-
-## 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:
-
-| Client | Tool naming pattern | Example |
-|--------|-------------------|---------|
-| VS Code Copilot | \`mcp_<serverName>_<tool>\` | \`mcp_aikit_status\` |
-| Claude Code | \`mcp__<serverName>__<tool>\` | \`mcp__aikit__status\` |
-| Other MCP clients | \`<serverName>_<tool>\` or bare \`<tool>\` | \`aikit_status\` or \`status\` |
-
-The server name is typically \`aikit\` or \`kb\` — check your MCP configuration.
-
-**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" })\`).
-
----
-
-## 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" in your prompt.
-   If present, skip AI Kit Recall and use the provided context instead.
-  **Visual Output:** When running as a sub-agent, do NOT use the \`present\` tool (output won't reach the user).
-  Instead, include structured data (tables, findings, metrics) as formatted text in your final response.
-  The Orchestrator will re-present relevant content to the user.
-
-**Detection:** If your prompt contains "## Prior AI Kit Context", you are in sub-agent mode.
-
----
-
-## 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.
-
----
-
-## Session Protocol
-
-### Start (do ALL)
-
-\`\`\`
-flow_status({})                                                # Check/resume active flow FIRST
-# If flow active → flow_read_instruction({ step }) → follow step instructions
-status({})                                                     # Check AI Kit health + onboard state
-# If onboard not run → onboard({ path: "." })                 # First-time codebase analysis
-flow_list({})                                                  # See available flows
-# Select flow based on task → flow_start({ flow: "<name>" })  # Start flow if appropriate
-list()                                                         # See stored knowledge
-search({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work
-\`\`\`
-
-### End (MUST do)
-
-\`\`\`
-session_digest({ persist: true })                              # Auto-capture session activity
-remember({ title: "Session checkpoint: <topic>", content: "<what was done, decisions made, next steps>", category: "conventions" })
-\`\`\`
-
-## MCP Tool Categories
-
-| Category | Tools | Purpose |
-|----------|-------|---------|
-| Code Navigation | \`graph\`, \`symbol\`, \`trace\` | Module relationships, symbol resolution, call chains — **start here for code understanding** |
-| Search & Discovery | \`search\`, \`find\`, \`scope_map\`, \`lookup\`, \`dead_symbols\` | Hybrid search, file patterns, reading plans |
-| Context Compression | \`file_summary\`, \`compact\`, \`digest\`, \`stratum_card\` | Reduce tokens — never raw-read to understand |
-| Code Analysis | \`analyze_structure\`, \`analyze_dependencies\`, \`analyze_patterns\`, \`analyze_entry_points\`, \`analyze_diagram\`, \`measure\` | Structure, deps, patterns, diagrams, complexity |
-| Flows | \`flow_list\`, \`flow_info\`, \`flow_start\`, \`flow_step\`, \`flow_status\`, \`flow_read_instruction\`, \`flow_reset\` | Structured multi-step workflows |
-| Meta-Tools | \`list_tools\`, \`describe_tool\`, \`search_tools\` | Discover active tools, get metadata, search by keyword — reduces token overhead |
-| Session | \`session_digest\`, \`stash\`, \`checkpoint\`, \`restore\`, \`replay\` | Session activity digest, key-value store, save/restore points, audit trail |
-
----
-
-## 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.**
-   - **\`present\`** — Rich content rendering (dashboards, tables, charts, timelines). **Required when producing visual output for the user.**
-
-> If no additional skills are listed for your agent, rely on AI Kit tools and onboard artifacts.
-
----
-
-## 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\`.
-
-### Step 1: Onboard Artifacts (pre-analyzed, fastest)
-
-| Need to understand... | Read this artifact |
-|---|---|
-| Project overview, tech stack | \`synthesis-guide.md\` |
-| File tree, module purposes | \`structure.md\` |
-| Import graph, dependencies | \`dependencies.md\` |
-| Exported functions, classes | \`symbols.md\` |
-| Function signatures, JSDoc, decorators | \`api-surface.md\` |
-| Interface/type/enum definitions | \`type-inventory.md\` |
-| Architecture patterns, conventions | \`patterns.md\` |
-| CLI bins, route handlers, main exports | \`entry-points.md\` |
-| C4 architecture diagram | \`diagram.md\` |
-| Module graph with key symbols | \`code-map.md\` |
-
-### Step 2: Curated Knowledge (past decisions, remembered patterns, auto-knowledge)
-
-Auto-knowledge captures facts automatically from tool outputs (conventions, errors, test results, research).
-Search it alongside manual knowledge:
-
-\`\`\`
-search("your keywords")    // searches curated + indexed content (includes auto-knowledge)
-search("error patterns")   // find auto-captured error patterns for current tools
-list({ category: "conventions" })  // see detected project conventions
-scope_map("what you need") // generates a reading plan
-list()                     // see all stored knowledge entries
-\`\`\`
-
-### 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 |
-| \`find({ pattern })\` | Locate files by name/glob |
-| \`symbol({ name })\` | Find symbol definition + references |
-| \`trace({ symbol, direction })\` | Follow call graph forward/backward |
-| \`compact({ path, query })\` | Read specific section of a file |
-| \`read_file\` | **ONLY** when you need exact lines for a pending edit |
-
-### Step 4: Tool Discovery
-
-If unsure which AI Kit tool to use → run \`guide({ topic: "what you need" })\` for recommendations.
-
----
-
-## PROHIBITED: Native File Reading Tools
-
-**\`read_file\` / \`read_file_raw\` MUST NOT be used to understand code.** They waste tokens and miss structural information that AI Kit tools provide.
-
-| ❌ NEVER do this | ✅ Do this instead | Why |
-|---|---|---|
-| \`read_file\` to understand a file | \`file_summary({ path })\` | Structure, exports, imports, call edges — **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 })\` | Compresses multiple files into token-budgeted summary |
-| \`grep_search\` / \`textSearch\` | \`search({ query })\` | Hybrid search across all indexed + curated content |
-| \`grep_search\` for a symbol | \`symbol({ name })\` | Definition + references with scope context |
-| Manual code tracing | \`trace({ start, direction })\` | AST call-graph traversal |
-| Manual import/dependency tracing | \`graph({ action: 'neighbors' })\` | Module import graph with cross-package edges |
-| Line counting / \`wc\` | \`measure({ path })\` | Lines, functions, cognitive complexity |
-| \`fetch_webpage\` | \`web_fetch({ urls })\` | Readability extract + token budget |
-| Web research / browsing | \`web_search({ queries })\` | Structured web results without browser |
-
-**The ONLY acceptable use of \`read_file\`:** Reading exact lines immediately before an edit operation (e.g., to verify the \`old_str\` for a replacement). Even then, use \`file_summary\` first to identify which lines to read.
-
-> **Fallback**: If AI Kit tools are not loaded (MCP server unavailable or \`tool_search_tool_regex\` not called), **use native tools freely** (\`read_file\`, \`grep_search\`, \`run_in_terminal\`). Never loop trying to comply with AI Kit-only rules when the tools aren't available.
-
-## 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, run \`evidence_map(gate, task_id)\` to check gate status.
-5. Use \`stratum_card\` for quick file context instead of reading full files. Use \`digest\` to compress accumulated context.
-
----
-
-## Loop Detection & Breaking
-
-Track repeated failures. If the same approach fails, **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\` |
-
-**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.
-
----
-
-## Hallucination Self-Check
-
-**Verify before asserting.** Never claim something exists or works without evidence.
-
-| 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 |
-
-**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.**
-
----
-
-## 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
-
----
-
-## MANDATORY: Memory Persistence Before Completing
-
-**Before finishing ANY task**, you MUST call \`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
-
-**How to remember:**
-\`\`\`
-remember({
-  title: "Short descriptive title",
-  content: "Detailed finding with context",
-  category: "patterns" | "conventions" | "decisions" | "troubleshooting"
-})
-\`\`\`
-
-**Examples:**
-- \`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" })\`
-- \`remember({ title: "Build requires Node 20+", content: "Uses Web Crypto API — Node 18 fails silently on crypto.subtle calls.", category: "conventions" })\`
-- \`remember({ title: "Decision: LanceDB over Chroma for vector store", content: "LanceDB is embedded (no Docker), supports WASM, better for user-level MCP.", category: "decisions" })\`
-
-**If you complete a task without remembering anything, you likely missed something.** Review what you learned.
-
-For outdated AI Kit entries → \`update(path, content, reason)\`
-
----
-
-## Context Efficiency
-
-**Prefer AI Kit over \`read_file\` to understand code** (if tools are loaded). Use the AI Kit compression tools:
-- **\`file_summary({ path })\`** — Structure, exports, imports (~50 tokens vs ~1000+ for read_file)
-- **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction)
-- **\`digest({ sources })\`** — Compress 3+ files into a single token-budgeted summary
-- **\`stratum_card({ files, query })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
-
-**Session phases** — structure your work to minimize context bloat:
-
-| Phase | What to do | Compress after? |
-|-------|-----------|----------------|
-| **Understand** | Search KB, read summaries, trace symbols | Yes — \`digest\` findings before planning |
-| **Plan** | Design approach, identify files to change | Yes — \`stash\` the plan, compact analysis |
-| **Execute** | Make changes, one sub-task at a time | Yes — compact between independent sub-tasks |
-| **Verify** | \`check\` + \`test_run\` + \`blast_radius\` | — |
-
-**Rules:**
-- **Never compact mid-operation** — finish the current sub-task first
-- **Recycle context to files** — save analysis results via \`stash\` or \`remember\`, not just in conversation
-- **Decompose monolithic work** — break into independent chunks, pass results via artifact files between sub-tasks
-- **One-shot sub-tasks** — for self-contained changes, provide all context upfront to avoid back-and-forth
-
----
-
-## Quality Verification
-
-For non-trivial tasks, **think before you implement**.
-
-**Think-first protocol:**
-1. Read existing code patterns in the area you're changing
-2. Design your approach (outline, pseudo-code, or mental model) before writing code
-3. Check: does your design match existing conventions? Use \`search\` for patterns
-4. Implement
-5. Verify: \`check\` + \`test_run\`
-
-**Quality dimensions** — verify each before returning handoff:
-
-| Dimension | Check |
-|-----------|-------|
-| **Correctness** | Does it do what was asked? Tests pass? |
-| **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? |
-
-**Explicit DON'Ts:**
-- Don't implement the first idea without considering alternatives for complex tasks
-- Don't skip verification — "it should work" is not evidence
-- Don't add features, refactor, or "improve" code beyond what was asked
-
----
-
-## User Interaction Rules
-
-When you need user input or need to explain something before asking:
-
-| Situation | Method | Details |
-|-----------|--------|---------|
-| Simple explanation + question | **Elicitation** | Text-only explanation, then ask via elicitation fields |
-| Rich content explanation + question | **\`present\` (mode: html)** + **Elicitation** | Use \`present({ format: "html" })\` for rich visual explanation (tables, charts, diagrams), then use elicitation for user input |
-| Complex visual explanation | **\`present\` (mode: browser)** | Use \`present({ format: "browser" })\` for full HTML dashboard. Confirmation/selection can be handled via browser actions, but for other user input fall back to elicitation |
-| **CLI mode** (any rich content) | **\`present\` (mode: browser)** | In CLI/terminal mode, **always use \`format: "browser"\`**. The \`html\` format's UIResource is invisible in terminal — only markdown fallback text renders. The \`browser\` format auto-opens the system browser. |
-
-**Rules:**
-- **Never dump long tables or complex visuals as plain text** — use \`present\` to render them properly
-- **Confirmation selections** (yes/no, pick from list) can be handled inside browser mode via actions
-- **Free-form text input** always goes through elicitation, even when using \`present\` for the explanation
-- **Prefer the simplest method** that adequately conveys the information
-- **CLI mode override:** When running in terminal (not VS Code chat), always use \`format: "browser"\` for any rich content
-
----
-
-## Handoff Format
-
-Always return this structure when invoked as a sub-agent:
-
-\`\`\`markdown
-<handoff>
-  <status>SUCCESS | PARTIAL | FAILED | ESCALATE</status>
-  <summary>{1 sentence summary}</summary>
-  <artifacts>
-    - Created: {files}
-    - Modified: {files}
-    - Deleted: {files}
-  </artifacts>
-  <context>{what the next agent needs to know}</context>
-  <blockers>{any blocking issues}</blockers>
-</handoff>
-\`\`\`
-`,
-
-  '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.**
-
-
-## MANDATORY FIRST ACTION
-
-Follow the **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.
-
----
-
-## Research Methodology
-
-### Phase 1: AI Kit Recall (BLOCKING)
-\`\`\`
-search("task keywords")
-scope_map("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_structure\`, \`analyze_dependencies\` for package-level understanding
-- Use \`web_search\`, \`web_fetch\` for external documentation
-
-### 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
-
-### Phase 4: Report
-Return structured findings. Always include:
-1. **Summary** — 1-3 sentence overview
-2. **Key Findings** — Bullet list of important discoveries
-3. **Files Examined** — Paths with brief purpose notes
-4. **Recommendation** — Your suggested approach with reasoning
-5. **Trade-offs** — Pros and cons of alternatives
-6. **Risks** — What could go wrong
-
-### Phase 5: MANDATORY — Persist Discoveries
-
-**Before returning your report**, you MUST call \`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
-
-\`\`\`
-remember({
-  title: "Short descriptive title",
-  content: "Detailed finding with context",
-  category: "patterns" | "conventions" | "decisions" | "troubleshooting"
-})
-\`\`\`
-
-**If you complete research without remembering anything, you wasted tokens.** Your research should enrich the knowledge base 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.
-
----
-
-## 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
-
----
-
-## Invocation Mode Detection
-
-- **Direct** (has AI Kit tools) → Follow the **Information Lookup Order** from code-agent-base
-- **Sub-agent** (prompt has "## Prior AI Kit Context") → Skip AI Kit Recall, use provided context
-
----
-
-## Context Efficiency
-
-- **NEVER use \`read_file\` to understand code** — use AI Kit compression tools instead
-- **\`file_summary\`** for structure (exports, imports, call edges — 10x fewer tokens)
-- **\`compact\`** for specific sections (5-20x token reduction vs read_file)
-- **\`digest\`** when synthesizing from 3+ sources
-- **\`stratum_card\`** for files you'll reference repeatedly
-- **\`read_file\` is ONLY acceptable** when you need exact lines for a pending edit operation
-
-## 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
-3. \`lane({ action:'create', name:'approach-b' })\` — second isolate
-4. Apply approach B mentally; 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.**
-
-
-## MANDATORY FIRST ACTION
-
-Follow the **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
-
----
-
-## Review Workflow
-
-1. **AI Kit Recall** — \`search("conventions relevant-area")\` + \`list()\` for past review findings, 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** — \`remember({ title: "Review: <finding>", content: "<details>", category: "patterns" })\` for any new patterns, anti-patterns, or recurring issues found
-
-## Review Dimensions
-
-| Dimension | What to Check |
-|-----------|---------------|
-| **Correctness** | Logic errors, off-by-one, null handling, async/await |
-| **Security** | OWASP Top 10, input validation, secrets exposure |
-| **Performance** | N+1 queries, unnecessary allocations, missing caching |
-| **Maintainability** | Naming, complexity, DRY, single responsibility |
-| **Testing** | Coverage for new/changed logic, edge cases |
-| **Patterns** | Consistency with existing codebase conventions |
-| **Types** | Proper typing, no \`any\`, generics where useful |
-
-## Output Format
-
-\`\`\`markdown
-## Code Review: {scope}
-**Verdict: APPROVED | NEEDS_REVISION | FAILED**
-**Severity: {count by level}**
-
-### Findings
-1. **[SEVERITY]** {file}:{line} — Description and fix
-
-### Summary
-{Overall assessment, key concerns}
-\`\`\`
-
-## Severity Levels
-
-- **CRITICAL** — Correctness bug that will cause runtime failure
-- **HIGH** — Security issue or major design flaw
-- **MEDIUM** — Code quality concern that should be fixed
-- **LOW** — Style/naming suggestion
-
-## Rules
-
-- **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
-
-## Evidence Citation Protocol (tier-aware)
-
-The 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.
-
-| Tier | Your responsibility |
-|------|---------------------|
-| Floor    | Free-form findings with \`file.ts#Lxx\` citations. No \`evidence_map\` calls required. |
-| 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. |
-| 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'\`. |
-
-**Every response MUST include:**
-- \`**FORGE Task ID:** <task_id>\` (passed in by Orchestrator, or state "not provided")
-- \`**Tier applied:** Floor | Standard | Critical\`
-- \`**Findings:** <list>\` with \`file:line\` receipts
-- Verdict: \`APPROVED\` | \`CHANGES_REQUESTED\` | \`BLOCKED\`
-
-Do NOT:
-- Create a new \`evidence_map\` (the Orchestrator already did)
-- Run \`evidence_map({action:'gate'})\` yourself — the Orchestrator owns the gate
-- Duplicate findings into the map that weren't CRITICAL/HIGH
-`,
-
-  '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.**
-
-
-## MANDATORY FIRST ACTION
-
-Follow the **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
-
----
-
-## Review Workflow
-
-1. **AI Kit Recall** — \`search("architecture decisions boundaries")\` + \`list()\` for past ADRs, patterns
-2. **Analyze** — \`analyze_structure\`, \`analyze_dependencies\`, \`blast_radius\`
-3. **Evaluate** — Check all dimensions below
-4. **Report** — Structured findings with verdict
-5. **Persist** — \`remember({ title: "Architecture: <finding>", content: "<details>", category: "decisions" })\` for any structural findings, boundary violations, or design insights
-
-## Review Dimensions
-
-| Dimension | What to Check |
-|-----------|---------------|
-| **Dependency Direction** | Dependencies flow inward (domain ← services ← infra) |
-| **Boundary Respect** | No cross-cutting between unrelated packages |
-| **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) |
-| **Testability** | Dependencies injectable, side effects isolated |
-
-## Output Format
-
-\`\`\`markdown
-## Architecture Review: {scope}
-**Verdict: APPROVED | NEEDS_CHANGES | BLOCKED**
-
-### Boundary Analysis
-{dependency direction, package boundaries}
-
-### Pattern Compliance
-{consistency with existing patterns}
-
-### Findings
-1. **[SEVERITY]** {description} — Impact and recommendation
-
-### Summary
-{Overall structural assessment}
-\`\`\`
-
-## Rules
-
-- **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
-
-## Evidence Citation Protocol (tier-aware)
-
-The 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.
-
-| Tier | Your responsibility |
-|------|---------------------|
-| Floor    | Free-form findings with \`file.ts#Lxx\` citations. No \`evidence_map\` calls required. |
-| 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. |
-| 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'\`. |
-
-**Every response MUST include:**
-- \`**FORGE Task ID:** <task_id>\` (passed in by Orchestrator, or state "not provided")
-- \`**Tier applied:** Floor | Standard | Critical\`
-- \`**Findings:** <list>\` with \`file:line\` receipts
-- Verdict: \`APPROVED\` | \`CHANGES_REQUESTED\` | \`BLOCKED\`
-
-Do NOT:
-- Create a new \`evidence_map\` (the Orchestrator already did)
-- Run \`evidence_map({action:'gate'})\` yourself — the Orchestrator owns the gate
-- Duplicate findings into the map that weren't CRITICAL/HIGH
-
-## Graph-Assisted Layer Verification
-
-For each significantly changed module (from \`blast_radius\` or changed_files input):
-
-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.
-`,
-
-  '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.
-
-## How It Works
-
-The Orchestrator launches ALL available Researcher variants **in parallel** with the same question. Each returns an independent recommendation. The Orchestrator synthesizes results and presents the agreement/disagreement breakdown to the user.
-
-## When to Use (Auto-Trigger Rules)
-
-Trigger the decision protocol when there is an **unresolved non-trivial technical decision** 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.
-
-## Key Rules
-
-- Always launch in **parallel**, minimum 4 variants
-- Use exact case-sensitive agent names — never rename or alias
-- Never make a non-trivial technical decision without multi-model analysis
-- **Produce an ADR** after every decision resolution
-- \`remember\` the decision for future recall
-`,
-
-  'forge-protocol': `# FORGE Protocol — Quality Overlay
-
-> Follow the FORGE (Fact-Oriented Reasoning with Graduated Evidence) protocol for all code generation and modification tasks.
-
-## AI Kit Tools for FORGE
-
-| Tool | Purpose | When |
-|------|---------|------|
-| \`forge_ground\` | Execute entire Ground phase — classify tier, scope map, unknowns, constraints | Start of every Standard/Critical task |
-| \`forge_classify\` | Classify tier only (Floor/Standard/Critical) | Quick classification |
-| \`evidence_map\` | CRUD + Gate evaluation for Evidence Map | Track claims during Build |
-| \`stratum_card\` | Generate T1/T2 context cards from files | Replace full file reads |
-| \`digest\` | Compress N text sources into budget | Compress accumulated context |
-
-## Tier Classification
-
-- **Floor**: Single file, no unknowns, no schema change, blast_radius ≤ 2. → Skip Phase 3.
-- **Standard**: Default for multi-file or non-trivial tasks.
-- **Critical**: blast_radius > 5, cross-service boundary, schema change, or security code.
-
-When uncertain, round up.
-
-## 4-Phase Flow
-
-### Phase 1 — Ground
-Read files, blast radius, classify tier, build Typed Unknown Queue, 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.
-
-### Phase 4 — Gate
-Binary YIELD/HOLD. Contract-type unknowns → **HARD BLOCK**. Non-contract → 1 retry, then FORCED DELIVERY with annotation.
-
-## Evidence Map
-
-\`\`\`
-evidence_map({ action: "create", task_id: "my-task", tier: "standard" })
-evidence_map({ action: "add", task_id: "my-task", claim: "API contract unchanged", status: "V", receipt: "search → types.ts#L42" })
-evidence_map({ action: "gate", task_id: "my-task" })  → YIELD / HOLD / HARD_BLOCK
-\`\`\`
-
-Status values: **V** (Verified + receipt), **A** (Assumed + reasoning), **U** (Unresolved).
-
-## Safety Gates (Standard+ only)
-
-Three mandatory checks before YIELD:
-
-| Gate | Rule | Failure |
-|------|------|---------|
-| **Provenance** | Every verified claim (V) has a non-empty receipt | HOLD — missing evidence trail |
-| **Commitment** | Every commitment-tagged entry is verified | HOLD — unconfirmed promises |
-| **Coverage** | No coverage-tagged entry is unresolved (U) | HOLD — dropped requirements |
-
-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.
-
-## Score-Driven Iteration
-
-For quality-sensitive tasks, use the execute→score→fix→re-score pattern:
-
-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({ key: "iteration-N", value: { score, issues } })
-
-Agents iterate until quality threshold is met, with diminishing returns tracked via stash.
-
-## Example Evidence Map (Standard Tier)
-
-\`\`\`
-evidence_map({ action: "create", task_id: "add-user-api", tier: "standard" })
-evidence_map({ action: "add", ..., claim: "User schema matches existing patterns", status: "V", receipt: "search → models/user.ts#L12", safety_gate: "provenance" })
-evidence_map({ action: "add", ..., claim: "API route follows REST conventions", status: "V", receipt: "compact → routes/index.ts confirms RESTful pattern" })
-evidence_map({ action: "add", ..., claim: "Input validation covers edge cases", status: "V", receipt: "test_run → 8/8 pass", safety_gate: "coverage" })
-evidence_map({ action: "add", ..., claim: "No breaking changes to existing API", status: "V", receipt: "blast_radius → 0 affected", safety_gate: "commitment" })
-evidence_map({ action: "gate", task_id: "add-user-api" })  → YIELD ✅
-\`\`\`
-
-## Quick Start
-
-1. **Every task**: \`forge_classify({ task: "description", files: ["path"], root_path: "." })\`
-2. **Floor**: Just implement — no evidence map needed
-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
-`,
-};
-
-// ─── Templates ──────────────────────────────────────────────────────────────
-// Keys map to filenames under agents/templates/
-
-export const TEMPLATES = {
-  'execution-state': `# Execution State: {Task Title}
-
-**Status:** PLANNING | IN_PROGRESS | REVIEW | COMPLETED | BLOCKED
-**Started:** {timestamp}
-**Plan:** {link to plan file}
-
-## Phases
-
-| # | Title | Agent | Status | Batch |
-|---|-------|-------|--------|-------|
-
-## Current Batch
-
-**Batch {N}:** {phases in this batch}
-**Status:** IMPLEMENTING | REVIEWING | APPROVED
-
-## Decisions Log
-
-| Decision | Rationale | ADR |
-|----------|-----------|-----|
-
-## Blockers
-
-| Issue | Severity | Assigned |
-|-------|----------|----------|
-`,
-
-  'adr-template': `# DR-NNN: {Short Title}
-
-**Status:** Proposed | Accepted | Rejected | Deprecated | Superseded
-**Date:** YYYY-MM-DD
-**Participants:** {which Researcher variants participated}
-
-## Context
-{What is the issue? Why are we making this decision?}
-{If superseding, link: "Supersedes DR-NNN."}
-
-## Decision
-{What was decided and why — 2-5 sentences max}
-
-## Decision Analysis Summary
-| Model | Recommendation | Key Reasoning |
-|-------|---------------|---------------|
-
-**Agreements:** {what 3+ models agreed on}
-**Disagreements:** {where they diverged}
-
-## Consequences
-**Positive:** {benefits}
-**Negative:** {trade-offs accepted}
-**Risks:** {what could go wrong, and any mitigations}
-
-## Alternatives Considered
-{Other approaches evaluated and why they were rejected — keeps the "why not" alongside the "why"}
-`,
-};