@vpxa/kb 0.1.12 → 0.1.15

package/scaffold/definitions/protocols.mjs

@@ -0,0 +1,322 @@
+/**
+ * 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.**
+
+## 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.**
+
+---
+
+## 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>
+\`\`\`
+`,
+
+  '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.**
+
+## 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
+`,
+
+  '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.**
+
+## 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
+`,
+
+  '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.**
+
+## 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
+`,
+
+  '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.
+
+## 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/definitions/tools.mjs

@@ -0,0 +1,176 @@
+/**
+ * Tool lists by agent role category.
+ *
+ * `kb` — Knowledge-base MCP tools (IDE-agnostic, same across all adapters).
+ * `ide` — IDE-native tool permissions, keyed by role. Each IDE adapter
+ *          maps these to its own format (e.g., Copilot tool identifiers).
+ *
+ * When KB adds/removes a tool, update `kb` here — all agents pick it up.
+ */
+
+export const KB_TOOLS = [
+  'analyze_dependencies',
+  'analyze_diagram',
+  'analyze_entry_points',
+  'analyze_patterns',
+  'analyze_structure',
+  'analyze_symbols',
+  'audit',
+  'batch',
+  'blast_radius',
+  'changelog',
+  'check',
+  'checkpoint',
+  'codemod',
+  'compact',
+  'data_transform',
+  'dead_symbols',
+  'delegate',
+  'diff_parse',
+  'digest',
+  'encode',
+  'env',
+  'eval',
+  'evidence_map',
+  'file_summary',
+  'find',
+  'forge_classify',
+  'forge_ground',
+  'forget',
+  'git_context',
+  'graph',
+  'guide',
+  'health',
+  'http',
+  'lane',
+  'list',
+  'lookup',
+  'measure',
+  'onboard',
+  'parse_output',
+  'process',
+  'produce_knowledge',
+  'queue',
+  'read',
+  'regex_test',
+  'reindex',
+  'remember',
+  'rename',
+  'replay',
+  'schema_validate',
+  'scope_map',
+  'search',
+  'snippet',
+  'stash',
+  'status',
+  'stratum_card',
+  'symbol',
+  'test_run',
+  'time',
+  'trace',
+  'update',
+  'watch',
+  'web_fetch',
+  'web_search',
+  'workset',
+];
+
+/**
+ * IDE-native tool categories by role.
+ * These are abstract capability names — each IDE adapter maps them to concrete tool IDs.
+ *
+ * Categories:
+ *   terminal    — run commands
+ *   problems    — read diagnostics
+ *   readFile    — read file contents
+ *   lastCommand — read terminal output
+ *   subagent    — invoke other agents
+ *   createFile  — create new files
+ *   editFiles   — edit existing files
+ *   search      — search codebase (code, text, usages, changes)
+ *   web         — web fetch, web search, GitHub
+ *   todo        — manage task lists
+ *   memory      — persistent memory (VS Code)
+ *   runCommand  — run VS Code commands
+ *   switchAgent — switch to another agent
+ *   killTerminal — kill a terminal
+ *   createTask  — create and run tasks
+ *   terminalSel — read terminal selection
+ *   fileSearch  — search by filename
+ *   listDir     — list directory
+ *   textSearch  — text search
+ *   searchResults — get search results
+ */
+export const IDE_CAPABILITIES = {
+  orchestrator: [
+    'memory',
+    'runCommand',
+    'switchAgent',
+    'killTerminal',
+    'createTask',
+    'terminal',
+    'terminalSel',
+    'lastCommand',
+    'problems',
+    'readFile',
+    'subagent',
+    'createFile',
+    'editFiles',
+    'search',
+    'web',
+    'todo',
+    'searchResults',
+    'textSearch',
+  ],
+  researcher: ['terminal', 'problems', 'readFile', 'lastCommand', 'subagent', 'search', 'web'],
+  reviewer: ['terminal', 'problems', 'readFile', 'lastCommand', 'subagent', 'search', 'web'],
+  codeAgent: [
+    'createTask',
+    'terminal',
+    'problems',
+    'readFile',
+    'lastCommand',
+    'subagent',
+    'createFile',
+    'editFiles',
+    'search',
+    'todo',
+  ],
+  debugger: [
+    'terminal',
+    'problems',
+    'readFile',
+    'terminalSel',
+    'lastCommand',
+    'subagent',
+    'createFile',
+    'editFiles',
+    'search',
+  ],
+  refactor: ['terminal', 'problems', 'readFile', 'lastCommand', 'subagent', 'editFiles', 'search'],
+  explorer: ['problems', 'readFile', 'search', 'fileSearch', 'listDir', 'textSearch'],
+  planner: [
+    'terminal',
+    'problems',
+    'readFile',
+    'lastCommand',
+    'subagent',
+    'createFile',
+    'editFiles',
+    'search',
+    'web',
+    'todo',
+  ],
+  security: ['terminal', 'problems', 'readFile', 'subagent', 'search', 'web'],
+  documenter: [
+    'terminal',
+    'problems',
+    'readFile',
+    'lastCommand',
+    'subagent',
+    'createFile',
+    'editFiles',
+    'search',
+    'web',
+  ],
+};

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!');