@vpxa/kb 0.1.23 → 0.1.25

package/scaffold/definitions/protocols.mjs

@@ -10,6 +10,7 @@ export const PROTOCOLS = {
 
 > 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.**
 
+
 ## Invocation Mode Detection
 
 You may be invoked in two modes:
@@ -58,6 +59,33 @@ Before returning your handoff, persist discoveries to KB:
 
 ---
 
+## Context Efficiency
+
+Minimize token usage by choosing the right compression tool:
+- **\`compact({ path, query })\`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+- **\`digest({ sources })\`** — Compress 3+ files into a single token-budgeted summary
+- **\`stratum_card({ path })\`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+
+---
+
+## 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 |
+
+**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
+
+---
+
 ## Handoff Format
 
 Always return this structure when invoked as a sub-agent:
@@ -81,6 +109,7 @@ Always return this structure when invoked as a sub-agent:
 
 > Shared methodology for all Researcher variants. Each variant's definition contains only its unique identity and model assignment. **Do not duplicate.**
 
+
 ## Research Methodology
 
 ### Phase 1: KB Recall (BLOCKING)
@@ -114,6 +143,19 @@ Return structured findings. Always include:
 
 ---
 
+## 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:
@@ -143,6 +185,7 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 > Shared methodology for all Code-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
+
 ## Review Workflow
 
 1. **KB Recall** — Search for relevant conventions, past review findings
@@ -198,6 +241,7 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 > Shared methodology for all Architect-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
+
 ## Review Workflow
 
 1. **KB Recall** — Search for architecture decisions, boundary conventions
@@ -318,5 +362,110 @@ evidence_map({ action: "gate", task_id: "my-task" })  → YIELD / HOLD / HARD_BL
 \`\`\`
 
 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"}
 `,
 };

package/scaffold/definitions/tools.mjs

@@ -22,6 +22,7 @@ export const KB_TOOLS = [
   'audit',
   'batch',
   'blast_radius',
+  'brainstorm',
   'changelog',
   'check',
   'checkpoint',
@@ -52,6 +53,7 @@ export const KB_TOOLS = [
   'measure',
   'onboard',
   'parse_output',
+  'present',
   'process',
   'produce_knowledge',
   'queue',
@@ -61,6 +63,7 @@ export const KB_TOOLS = [
   'remember',
   'rename',
   'replay',
+  'restore',
   'schema_validate',
   'scope_map',
   'search',
@@ -125,9 +128,28 @@ export const IDE_CAPABILITIES = {
     'todo',
     'searchResults',
     'textSearch',
+    'browser',
+  ],
+  researcher: [
+    'terminal',
+    'problems',
+    'readFile',
+    'lastCommand',
+    'subagent',
+    'search',
+    'web',
+    'browser',
+  ],
+  reviewer: [
+    'terminal',
+    'problems',
+    'readFile',
+    'lastCommand',
+    'subagent',
+    'search',
+    'web',
+    'browser',
   ],
-  researcher: ['terminal', 'problems', 'readFile', 'lastCommand', 'subagent', 'search', 'web'],
-  reviewer: ['terminal', 'problems', 'readFile', 'lastCommand', 'subagent', 'search', 'web'],
   codeAgent: [
     'createTask',
     'terminal',
@@ -139,6 +161,7 @@ export const IDE_CAPABILITIES = {
     'editFiles',
     'search',
     'todo',
+    'browser',
   ],
   debugger: [
     'terminal',
@@ -150,9 +173,19 @@ export const IDE_CAPABILITIES = {
     'createFile',
     'editFiles',
     'search',
+    'browser',
+  ],
+  refactor: [
+    'terminal',
+    'problems',
+    'readFile',
+    'lastCommand',
+    'subagent',
+    'editFiles',
+    'search',
+    'browser',
   ],
-  refactor: ['terminal', 'problems', 'readFile', 'lastCommand', 'subagent', 'editFiles', 'search'],
-  explorer: ['problems', 'readFile', 'search', 'fileSearch', 'listDir', 'textSearch'],
+  explorer: ['problems', 'readFile', 'search', 'fileSearch', 'listDir', 'textSearch', 'browser'],
   planner: [
     'terminal',
     'problems',
@@ -164,8 +197,9 @@ export const IDE_CAPABILITIES = {
     'search',
     'web',
     'todo',
+    'browser',
   ],
-  security: ['terminal', 'problems', 'readFile', 'subagent', 'search', 'web'],
+  security: ['terminal', 'problems', 'readFile', 'subagent', 'search', 'web', 'browser'],
   documenter: [
     'terminal',
     'problems',
@@ -176,5 +210,6 @@ export const IDE_CAPABILITIES = {
     'editFiles',
     'search',
     'web',
+    'browser',
   ],
 };

package/scaffold/general/agents/Architect-Reviewer-Alpha.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Primary architecture reviewer'
 argument-hint: Files, PR, or subsystem to architecture-review
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: GPT-5.4 (copilot)
 ---
 

package/scaffold/general/agents/Architect-Reviewer-Beta.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Architecture reviewer variant — different LLM perspective for dual review'
 argument-hint: Files, PR, or subsystem to architecture-review
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 

package/scaffold/general/agents/Code-Reviewer-Alpha.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Primary code reviewer'
 argument-hint: File path, PR, or code to review
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: GPT-5.4 (copilot)
 ---
 

package/scaffold/general/agents/Code-Reviewer-Beta.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Code reviewer variant — different LLM perspective for dual review'
 argument-hint: File path, PR, or code to review
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 

package/scaffold/general/agents/Debugger.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Expert debugger that diagnoses issues, traces errors, and provides solutions'
 argument-hint: Error message, stack trace, or description of issue
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalSelection, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalSelection, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, browser/*, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 
@@ -16,7 +16,7 @@ You are the **Debugger**, expert debugger that diagnoses issues, traces errors,
 ## Debugging Protocol
 
 1. **KB Recall** — Search for known issues matching this error pattern
-2. **Reproduce** — Confirm the error, get full stack trace
+2. **Reproduce** — Confirm the error, use `parse_output` on stack traces and build errors for structured analysis
 3. **Trace** — `symbol`, `trace`, follow call chains backwards
 4. **Diagnose** — Form hypothesis, gather evidence, identify root cause
 5. **Fix** — Implement the fix, verify with tests

package/scaffold/general/agents/Documenter.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Documentation specialist that creates and maintains comprehensive project documentation'
 argument-hint: Component, API, feature, or area to document
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: GPT-5.4 (copilot)
 ---
 
@@ -26,7 +26,7 @@ You are the **Documenter**, documentation specialist that creates and maintains
 | README | New package/module | Structure, usage, API |
 | API docs | New/changed endpoints | Request/response, examples |
 | Architecture | Design decisions | Context, decision, consequences |
-| Changelog | After implementation | Keep a Changelog format |
+| Changelog | After implementation | `changelog` tool, Keep a Changelog format |
 
 ## Rules
 

package/scaffold/general/agents/Explorer.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Rapid codebase exploration to find files, usages, dependencies, and structural context'
 argument-hint: Find files, usages, and context related to: {topic or goal}
-tools: [read/problems, read/readFile, search/changes, search/codebase, search/usages, search/fileSearch, search/listDirectory, search/textSearch, knowledge-base/*]
+tools: [read/problems, read/readFile, search/changes, search/codebase, search/usages, search/fileSearch, search/listDirectory, search/textSearch, browser/*, knowledge-base/*]
 model: Gemini 3 Flash (Preview) (copilot)
 ---
 
@@ -16,8 +16,9 @@ You are the **Explorer**, rapid codebase exploration to find files, usages, depe
 1. **KB Recall** — `search` for existing analysis on this area
 2. **Discover** — Use `find`, `symbol`, `scope_map` to locate relevant files
 3. **Analyze** — Use `analyze_structure`, `analyze_dependencies`, `file_summary`
-4. **Map** — Build a picture of the subsystem: files, exports, dependencies, call chains
-5. **Report** — Structured findings with file paths and key observations
+4. **Compress** — Use `compact` for targeted file sections, `digest` when synthesizing 3+ sources, `stratum_card` for files you'll reference repeatedly
+5. **Map** — Build a picture of the subsystem: files, exports, dependencies, call chains
+6. **Report** — Structured findings with file paths and key observations
 
 ## Exploration Modes
 

package/scaffold/general/agents/Frontend.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'UI/UX specialist for React, styling, responsive design, and frontend implementation'
 argument-hint: UI component, styling task, or frontend feature
-tools: [execute/createAndRunTask, execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, todo, knowledge-base/*]
+tools: [execute/createAndRunTask, execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, todo, browser/*, knowledge-base/*]
 model: Gemini 3.1 Pro (Preview) (copilot)
 ---
 

package/scaffold/general/agents/Implementer.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Persistent implementation agent that writes code following TDD practices until all tasks are complete'
 argument-hint: Implementation task, feature, or phase from plan
-tools: [execute/createAndRunTask, execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, todo, knowledge-base/*]
+tools: [execute/createAndRunTask, execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, todo, browser/*, knowledge-base/*]
 model: GPT-5.4 (copilot)
 ---
 

package/scaffold/general/agents/Orchestrator.agent.md

@@ -1,6 +1,6 @@
 ---
 description: 'Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit'
-tools: [vscode/memory, vscode/runCommand, vscode/switchAgent, execute/killTerminal, execute/createAndRunTask, execute/runInTerminal, read/terminalSelection, read/terminalLastCommand, read/problems, read/readFile, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, todo, search/searchResults, search/textSearch, knowledge-base/*]
+tools: [vscode/memory, vscode/runCommand, vscode/switchAgent, execute/killTerminal, execute/createAndRunTask, execute/runInTerminal, read/terminalSelection, read/terminalLastCommand, read/problems, read/readFile, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, todo, search/searchResults, search/textSearch, browser/*, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 
@@ -57,6 +57,21 @@ Before Planning, determine the routing:
 3. **Both?** → Brainstorming skill first. When it reaches unresolved technical choices, escalate those to the decision protocol, then return to the user for design approval.
 4. **Neither?** → Skip to Phase 1: Planning
 
+## FORGE Protocol (Orchestrator Responsibilities)
+
+Before delegating any implementation task:
+
+1. **Classify**: `forge_classify({ task, files, root_path: "." })` to determine tier (Floor/Standard/Critical)
+2. **Delegate with tier**: Pass FORGE tier to sub-agents via context:
+   > **FORGE Context**: Tier = {tier}. {ceremony requirements}.
+   > Evidence map: {taskId}. Safety gates: provenance, commitment, coverage.
+3. **Gate after completion**: Run `evidence_map({ action: "gate", task_id })` — YIELD/HOLD/HARD_BLOCK
+4. **Auto-upgrade**: If unknowns reveal contract/security issues during Build, re-classify before next batch
+
+Integrate into workflow:
+- Phase 1 step 1: After parsing goal, run forge_classify
+- Phase 2: After each batch's code review, evaluate evidence_map gate
+
 ## Multi-Model Decision Protocol
 
 Launch ALL Researcher variants in parallel with identical framing. Each returns: recommendation, reasoning, trade-offs, risks.

package/scaffold/general/agents/Planner.agent.md

@@ -1,6 +1,6 @@
 ---
 description: 'Autonomous planner that researches codebases and writes comprehensive TDD implementation plans'
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, todo, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/createFile, edit/editFiles, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, todo, browser/*, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 
@@ -15,9 +15,11 @@ You are the **Planner**, autonomous planner that researches codebases and writes
 ## Planning Workflow
 
 1. **KB Recall** — Search for past plans, architecture decisions, known patterns
-2. **FORGE Ground** — `forge_ground` to classify tier, scope map, seed unknowns, load constraints
-3. **Research** — Delegate to Explorer and Researcher agents to gather context
-4. **Draft Plan** — Produce a structured plan:
+2. **FORGE Classify** — `forge_classify({ task, files, root_path: "." })` to determine complexity tier
+3. **FORGE Ground** — `forge_ground` to scope map, seed unknowns, load constraints
+4. **Research** — Delegate to Explorer and Researcher agents to gather context
+5. **Auto-upgrade check** — If forge_ground reveals contract-type unknowns or security concerns not caught by initial classify, recommend tier upgrade in plan
+6. **Draft Plan** — Produce a structured plan:
    - 3-10 implementation phases
    - Agent assignments per phase (Implementer, Frontend, Refactor, etc.)
    - TDD steps (write test → fail → implement → pass → lint)
@@ -31,6 +33,11 @@ You are the **Planner**, autonomous planner that researches codebases and writes
 ## Plan: {Title}
 {TL;DR: 1-3 sentences}
 
+### FORGE Assessment
+- **FORGE Tier**: {Floor | Standard | Critical}
+- **Evidence Map entries needed**: {count}
+- **Critical-path claims**: {list}
+
 ### Dependency Graph & Parallel Batches
 | Phase | Depends On | Batch |
 |-------|-----------|-------|

package/scaffold/general/agents/Refactor.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Code refactoring specialist that improves structure, readability, and maintainability'
 argument-hint: Code, component, or pattern to refactor
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/editFiles, search/changes, search/codebase, search/usages, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, edit/editFiles, search/changes, search/codebase, search/usages, browser/*, knowledge-base/*]
 model: GPT-5.4 (copilot)
 ---
 

package/scaffold/general/agents/Researcher-Alpha.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Primary deep research agent — also serves as default Researcher'
 argument-hint: Research question, problem statement, or subsystem to investigate
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 

package/scaffold/general/agents/Researcher-Beta.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Research variant for multi-model decision protocol — different LLM perspective'
 argument-hint: Research question, problem statement, or subsystem to investigate
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: Claude Sonnet 4.6 (copilot)
 ---
 

package/scaffold/general/agents/Researcher-Delta.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Research variant for multi-model decision protocol — different LLM perspective'
 argument-hint: Research question, problem statement, or subsystem to investigate
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: Gemini 3.1 Pro (Preview) (copilot)
 ---
 

package/scaffold/general/agents/Researcher-Gamma.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Research variant for multi-model decision protocol — different LLM perspective'
 argument-hint: Research question, problem statement, or subsystem to investigate
-tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, read/terminalLastCommand, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: GPT-5.4 (copilot)
 ---
 

package/scaffold/general/agents/Security.agent.md

@@ -1,7 +1,7 @@
 ---
 description: 'Security specialist that analyzes code for vulnerabilities and compliance'
 argument-hint: Code, feature, or component to security review
-tools: [execute/runInTerminal, read/problems, read/readFile, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, cai-mcp/webFetch, cai-mcp/webSearch, ms-vscode.vscode-websearchforcopilot/websearch, knowledge-base/*]
+tools: [execute/runInTerminal, read/problems, read/readFile, agent/runSubagent, search/changes, search/codebase, search/usages, web/fetch, web/githubRepo, ms-vscode.vscode-websearchforcopilot/websearch, browser/*, knowledge-base/*]
 model: Claude Opus 4.6 (copilot)
 ---
 
@@ -14,13 +14,15 @@ You are the **Security**, security specialist that analyzes code for vulnerabili
 ## Security Review Protocol
 
 1. **KB Recall** — Search for past security findings and conventions
-2. **OWASP Top 10 Scan** — Check each category systematically
-3. **Dependency Audit** — Check for known CVEs in dependencies
-4. **Secret Detection** — Scan for hardcoded credentials, API keys, tokens
-5. **Auth/AuthZ Review** — Verify access control, session management
-6. **Input Validation** — Check all user inputs for injection vectors
-7. **Report** — Severity-ranked findings with remediation guidance
-8. **Persist** — `remember` findings with category `troubleshooting`
+2. **Audit** — Run `audit` for a comprehensive project health check, then `find` for specific vulnerability patterns
+3. **OWASP Top 10 Scan** — Check each category systematically
+4. **Dependency Audit** — Check for known CVEs in dependencies
+5. **Secret Detection** — Scan for hardcoded credentials, API keys, tokens
+6. **Auth/AuthZ Review** — Verify access control, session management
+7. **Input Validation** — Check all user inputs for injection vectors
+8. **Impact Analysis** — Use `trace` on sensitive functions, `blast_radius` on security-critical files
+9. **Report** — Severity-ranked findings with remediation guidance
+10. **Persist** — `remember` findings with category `troubleshooting`
 
 ## Severity Levels
 

package/scaffold/general/agents/_shared/architect-reviewer-base.md

@@ -2,6 +2,7 @@
 
 > Shared methodology for all Architect-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
+
 ## Review Workflow
 
 1. **KB Recall** — Search for architecture decisions, boundary conventions

package/scaffold/general/agents/_shared/code-agent-base.md

@@ -2,6 +2,7 @@
 
 > 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.**
 
+
 ## Invocation Mode Detection
 
 You may be invoked in two modes:
@@ -50,6 +51,33 @@ Before returning your handoff, persist discoveries to KB:
 
 ---
 
+## Context Efficiency
+
+Minimize token usage by choosing the right compression tool:
+- **`compact({ path, query })`** — Extract relevant sections from a single file (5-20x token reduction vs full read)
+- **`digest({ sources })`** — Compress 3+ files into a single token-budgeted summary
+- **`stratum_card({ path })`** — Generate a reusable T1/T2 context card for files you'll reference repeatedly
+
+---
+
+## 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 |
+
+**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
+
+---
+
 ## Handoff Format
 
 Always return this structure when invoked as a sub-agent:

package/scaffold/general/agents/_shared/code-reviewer-base.md

@@ -2,6 +2,7 @@
 
 > Shared methodology for all Code-Reviewer variants. Each variant's definition contains only identity and model. **Do not duplicate.**
 
+
 ## Review Workflow
 
 1. **KB Recall** — Search for relevant conventions, past review findings