@vpxa/kb 0.1.13 → 0.1.16

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

@@ -0,0 +1,50 @@
+# Architect-Reviewer — Shared Base Instructions
+
+> 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
+2. **Analyze** — `analyze_structure`, `analyze_dependencies`, `blast_radius`
+3. **Evaluate** — Check all dimensions below
+4. **Report** — Structured findings with verdict
+5. **Persist** — `remember` findings
+
+## 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
+

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

@@ -0,0 +1,88 @@
+# 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.**
+
+## Invocation Mode Detection
+
+You may be invoked in two modes:
+1. **Direct** — you have full KB tool access. Execute KB Recall normally.
+2. **Sub-agent** (via Orchestrator) — you may have limited MCP tool access.
+   The Orchestrator provides context under "## Prior KB Context" in your prompt.
+   If present, skip KB Recall and use the provided context instead.
+
+**Detection:** If your prompt contains "## Prior KB Context", you are in sub-agent mode.
+
+---
+
+## 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.
+
+---
+
+## KB Recall (BLOCKING — Before ANY Code Change)
+
+1. **Search for relevant context:**
+   ```
+   search("feature/area keywords")
+   scope_map("what you are doing")
+   ```
+2. **Check for existing patterns** — reuse established conventions
+3. **Read design decisions** that constrain your implementation
+4. **If KB has no hits**, proceed but **remember your findings at the end**
+
+**Proceed only after KB search is complete.**
+
+---
+
+## Tool Preference (BLOCKING — Use KB Tools Over Native Tools)
+
+KB tools return **AST-analyzed structured data** — 10x fewer tokens than raw file reads. **Always prefer KB tools:**
+
+| Instead of... | Use KB Tool |
+|---------------|-------------|
+| `read_file` (full file) | `file_summary` — exports, imports, call edges, 10x fewer tokens |
+| `read_file` (section) | `compact({ path, query })` — server-side extract, 5-20x reduction |
+| `grep_search` / `textSearch` | `search` — semantic + keyword hybrid |
+| `grep_search` for symbol | `symbol` — definition + references with scope context |
+| Multiple `read_file` | `digest` — compressed multi-source summary |
+| Manual code tracing | `trace` — AST call-graph traversal |
+| Line counting | `measure` — lines, complexity, cognitive complexity |
+
+**Only use `read_file` as a last resort** when you need exact line content for editing.
+
+---
+
+## KB Learn (After Completing Work)
+
+Before returning your handoff, persist discoveries to KB:
+- Architecture insights → `remember({ title, content, category: "patterns" })`
+- Non-obvious solutions → `remember({ title, content, category: "troubleshooting" })`
+- Key decisions made → `remember({ title, content, category: "decisions" })`
+- Outdated KB entries → `update(path, content, reason)`
+
+---
+
+## 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>
+```
+

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

@@ -0,0 +1,54 @@
+# Code-Reviewer — Shared Base Instructions
+
+> 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
+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` any new patterns or issues
+
+## 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
+

package/scaffold/general/agents/_shared/decision-protocol.md

@@ -0,0 +1,27 @@
+# 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
+

package/scaffold/general/agents/_shared/forge-protocol.md

@@ -0,0 +1,46 @@
+# FORGE Protocol — Quality Overlay
+
+> Follow the FORGE (Fact-Oriented Reasoning with Graduated Evidence) protocol for all code generation and modification tasks.
+
+## KB 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).
+

package/scaffold/general/agents/_shared/researcher-base.md

@@ -0,0 +1,61 @@
+# 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.**
+
+## Research Methodology
+
+### Phase 1: KB Recall (BLOCKING)
+```
+search("task keywords")
+scope_map("what you need to investigate")
+```
+
+### Phase 2: Exploration
+- Use `find`, `symbol`, `trace` for code exploration
+- 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: Persist
+`remember` key findings for future recall.
+
+---
+
+## 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 KB tools) → Execute KB Recall normally
+- **Sub-agent** (prompt has "## Prior KB Context") → Skip KB Recall, use provided context
+
+---
+
+## Context Efficiency
+
+- **Prefer `file_summary` over `read_file`** for understanding structure
+- **Prefer `compact` over full reads** when you need specific sections
+- **Use `digest`** when synthesizing from 3+ sources
+- **Use `stratum_card`** for files you'll reference repeatedly
+

package/scaffold/general/agents/templates/adr-template.md

@@ -0,0 +1,27 @@
+# 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/general/agents/templates/execution-state.md

@@ -0,0 +1,25 @@
+# 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 |
+|-------|----------|----------|

package/scaffold/general/prompts/ask.prompt.md

@@ -0,0 +1,20 @@
+---
+description: "Quick research question — find answer using KB + web search"
+agent: "Researcher-Alpha"
+tools:
+  - knowledge-base/search
+  - knowledge-base/web_search
+  - knowledge-base/web_fetch
+  - knowledge-base/compact
+  - knowledge-base/file_summary
+  - knowledge-base/remember
+---
+
+## Quick Research
+
+1. **KB Recall** — Search knowledge base for existing answers
+2. **Web Search** — If KB has no relevant results, search the web
+3. **Synthesize** — Combine findings into a clear, concise answer
+4. **Remember** — If the answer is broadly useful, persist it to KB
+
+**Always cite sources** — KB entries, file paths, or URLs.

package/scaffold/general/prompts/debug.prompt.md

@@ -0,0 +1,25 @@
+---
+description: "Systematic error diagnosis: reproduce → trace → diagnose → fix → verify"
+agent: "Debugger"
+tools:
+  - knowledge-base/search
+  - knowledge-base/symbol
+  - knowledge-base/trace
+  - knowledge-base/blast_radius
+  - knowledge-base/check
+  - knowledge-base/test_run
+  - knowledge-base/parse_output
+  - knowledge-base/compact
+  - knowledge-base/remember
+---
+
+## Debug Workflow
+
+1. **Parse Error** — Use `parse_output` on the error message/stack trace
+2. **KB Recall** — Search for known issues matching this pattern
+3. **Reproduce** — Run the failing command/test to confirm
+4. **Trace** — Use `symbol` and `trace` to follow the call chain
+5. **Diagnose** — Form hypothesis, gather evidence
+6. **Fix** — Implement minimal fix
+7. **Verify** — `check` + `test_run` to confirm fix and no regressions
+8. **Remember** — Persist the fix with category `troubleshooting`

package/scaffold/general/prompts/design.prompt.md

@@ -0,0 +1,22 @@
+---
+description: "Collaborative design session — explore ideas, refine requirements, produce a design spec"
+agent: "Orchestrator"
+tools:
+  - knowledge-base/search
+  - knowledge-base/scope_map
+  - knowledge-base/file_summary
+  - knowledge-base/compact
+  - knowledge-base/remember
+  - knowledge-base/forge_classify
+---
+
+## Design Session
+
+Enter Phase 0 (Design Gate) directly — the user is requesting a design session.
+
+1. **Invoke the brainstorming skill** — interactive design dialogue with user
+2. Follow the skill's full process (auto-selects Simple or Advanced mode)
+3. If Advanced Mode, use Decision Protocol for unresolved technical choices
+4. Terminal state: brainstorming skill invokes writing-plans skill
+
+**🛑 HARD GATE** — Do NOT skip brainstorming. Do NOT write code. Design first.

package/scaffold/general/prompts/implement.prompt.md

@@ -0,0 +1,26 @@
+---
+description: "Full lifecycle implementation: plan → build → review → commit"
+agent: "Orchestrator"
+tools:
+  - knowledge-base/search
+  - knowledge-base/scope_map
+  - knowledge-base/forge_ground
+  - knowledge-base/check
+  - knowledge-base/test_run
+  - knowledge-base/blast_radius
+  - knowledge-base/remember
+  - knowledge-base/audit
+---
+
+## Implementation Pipeline
+
+Follow the Orchestrator's full workflow:
+
+1. **Phase 0: Design Gate** — Orchestrator checks if design is needed. Creative/additive work triggers brainstorming first. Use `/design` if you want to start with design explicitly.
+2. **Phase 1: Planning** — Research, draft plan, present to user for approval
+3. **Phase 2: Implementation** — Execute phases in parallel batches
+4. **Phase 3: Completion** — Final review, docs, persist learnings
+
+**🛑 MANDATORY STOPS** — After plan, after each batch, after completion.
+
+Refer to the Orchestrator agent's full instructions for the detailed workflow.

package/scaffold/general/prompts/plan.prompt.md

@@ -0,0 +1,24 @@
+---
+description: "Create a detailed TDD implementation plan without executing it"
+agent: "Planner"
+tools:
+  - knowledge-base/search
+  - knowledge-base/scope_map
+  - knowledge-base/forge_ground
+  - knowledge-base/forge_classify
+  - knowledge-base/file_summary
+  - knowledge-base/analyze_structure
+  - knowledge-base/analyze_dependencies
+  - knowledge-base/remember
+---
+
+## Planning Workflow
+
+1. **KB Recall** — Search for past plans, architecture decisions
+2. **FORGE Ground** — Classify tier, scope map, seed unknowns
+3. **Research** — Explore codebase, understand subsystems
+4. **Draft Plan** — 3-10 phases with agent assignments, TDD steps
+5. **Dependency Graph** — Group into parallel batches
+6. **Present** — Show plan with open questions
+
+**🛑 MANDATORY STOP** — Wait for user approval. Do NOT implement.

package/scaffold/general/prompts/review.prompt.md

@@ -0,0 +1,31 @@
+---
+description: "Dual-model code + architecture review pipeline"
+agent: "Orchestrator"
+tools:
+  - knowledge-base/search
+  - knowledge-base/blast_radius
+  - knowledge-base/check
+  - knowledge-base/test_run
+  - knowledge-base/analyze_dependencies
+  - knowledge-base/remember
+---
+
+## Review Pipeline
+
+### Step 1: Scope
+Identify changed files and their blast radius.
+
+### Step 2: Code Review (parallel)
+Launch Code-Reviewer-Alpha and Code-Reviewer-Beta on the same changeset.
+
+### Step 3: Architecture Review (if needed)
+If changes cross service boundaries or modify interfaces, launch Architect-Reviewer-Alpha and Architect-Reviewer-Beta.
+
+### Step 4: Synthesis
+Merge findings from both reviewers:
+- **Agreements**: Both found same issue → HIGH confidence
+- **Unique findings**: One found, other didn't → verify
+- **Disagreements**: Contradicting verdicts → present both to user
+
+### Step 5: Report
+Present unified review with: verdict, findings by severity, recommended actions.

package/scaffold/generate.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Scaffold generator — reads definitions, picks adapter, writes files.
+ *
+ * Usage:
+ *   node scaffold/generate.mjs                  # Default: all adapters
+ *   node scaffold/generate.mjs --ide copilot    # Copilot only
+ *   node scaffold/generate.mjs --ide claude-code # Claude Code only [stub]
+ *
+ * Architecture:
+ *   definitions/  — IDE-agnostic data (agents, models, tools, prompts, hooks, plugins)
+ *   adapters/     — IDE-specific generators (copilot, claude-code)
+ *   {ide}/        — Generated output (what `kb init` copies into workspaces)
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { generateClaudeCode } from './adapters/claude-code.mjs';
+import { generateCopilot } from './adapters/copilot.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const ADAPTERS = {
+  copilot: { generate: generateCopilot, outDir: 'copilot' },
+  'claude-code': { generate: generateClaudeCode, outDir: 'claude-code' },
+};
+
+// ─── Parse args ───────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const ideIdx = args.indexOf('--ide');
+const targetIde = ideIdx >= 0 ? args[ideIdx + 1] : null;
+
+const idesToRun = targetIde ? [targetIde] : Object.keys(ADAPTERS);
+
+// ─── Generate ─────────────────────────────────────────────────────────────
+
+for (const ide of idesToRun) {
+  const adapter = ADAPTERS[ide];
+  if (!adapter) {
+    console.error(`Unknown IDE: ${ide}. Available: ${Object.keys(ADAPTERS).join(', ')}`);
+    process.exit(1);
+  }
+
+  const outDir = resolve(__dirname, adapter.outDir);
+
+  // Clean output directory for a fresh generation
+  if (existsSync(outDir)) {
+    rmSync(outDir, { recursive: true });
+  }
+
+  console.log(`\n─── Generating ${ide} scaffold ───`);
+
+  const files = adapter.generate();
+
+  if (files.length === 0) {
+    console.log(`  (stub — no files generated)`);
+    continue;
+  }
+
+  let count = 0;
+  for (const { path, content } of files) {
+    const fullPath = resolve(outDir, path);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, content, 'utf-8');
+    console.log(`  ${path}`);
+    count++;
+  }
+
+  console.log(`  → ${count} files written to scaffold/${adapter.outDir}/`);
+}
+
+console.log('\nDone!');