@vpxa/aikit 0.1.1 → 0.1.2

package/scaffold/README.md

@@ -1,192 +1,192 @@
-# Scaffold System — Contributor Guide
-
-> **⚠️ GOLDEN RULE: Never edit files in `scaffold/general/` or `scaffold/claude-code/` directly.**
-> They are **generated output** and will be overwritten by `generate.mjs`.
-> Always edit the **source files** in `scaffold/definitions/`.
-
-## Architecture
-
-```
-scaffold/
-├── definitions/          ← SOURCE OF TRUTH (edit here)
-│   ├── agents.mjs        Agent metadata (name, description, model, tools, category)
-│   ├── bodies.mjs        Agent body text (mode instructions per agent)
-│   ├── models.mjs        Available models per IDE
-│   ├── protocols.mjs     Shared protocol files (_shared/*.md) + templates
-│   ├── tools.mjs         Tool capability → IDE tool mappings
-│   ├── prompts.mjs       Prompt file content
-│   ├── hooks.mjs         Hook definitions
-│   └── plugins.mjs       Plugin definitions
-│
-├── adapters/             ← IDE-specific generators
-│   ├── copilot.mjs       GitHub Copilot adapter (active — generates ~32 files)
-│   └── claude-code.mjs   Claude Code adapter (stub — no output yet)
-│
-├── generate.mjs          ← BUILD SCRIPT (run after any change)
-│
-├── general/              ← GENERATED OUTPUT for Copilot (DO NOT EDIT)
-│   ├── agents/
-│   │   ├── _shared/      Protocol files (from PROTOCOLS in protocols.mjs)
-│   │   ├── templates/    Template files (from TEMPLATES in protocols.mjs)
-│   │   └── *.agent.md    Agent files (from AGENT_BODIES in bodies.mjs)
-│   └── prompts/          Prompt files (from PROMPTS in prompts.mjs)
-│
-└── claude-code/          ← GENERATED OUTPUT for Claude Code (stub, DO NOT EDIT)
-```
-
-### Data Flow
-
-```
-definitions/*.mjs  →  generate.mjs  →  scaffold/general/  →  aikit init  →  .github/ (user project)
-    (source)          (build script)    (generated output)    (deploy)     (user workspace)
-```
-
-## How to Make Changes
-
-### Step 1: Edit Source Files
-
-| What you want to change | Edit this file |
-|--------------------------|---------------|
-| An agent's body/instructions | `definitions/bodies.mjs` → `AGENT_BODIES[agentName]` |
-| Shared rules for code agents | `definitions/protocols.mjs` → `PROTOCOLS['code-agent-base']` |
-| Shared rules for researchers | `definitions/protocols.mjs` → `PROTOCOLS['researcher-base']` |
-| Agent metadata (model, tools) | `definitions/agents.mjs` → `AGENTS[agentName]` |
-| Available models | `definitions/models.mjs` |
-| Tool mappings | `definitions/tools.mjs` |
-| Prompt files | `definitions/prompts.mjs` |
-
-### Step 2: Regenerate Output
-
-```bash
-node scaffold/generate.mjs
-```
-
-This will:
-1. Clean `general/agents/` and `general/prompts/` directories
-2. Regenerate all files from definitions via the copilot adapter
-3. Print every file written (expect ~32 files)
-
-To generate for a specific IDE only:
-```bash
-node scaffold/generate.mjs --ide copilot
-node scaffold/generate.mjs --ide claude-code
-```
-
-### Step 3: Verify
-
-```bash
-# Syntax check the source file you edited
-node -c scaffold/definitions/bodies.mjs
-node -c scaffold/definitions/protocols.mjs
-
-# Verify your changes appear in generated output
-# (use grep/Select-String for key phrases)
-grep -r "your key phrase" scaffold/general/agents/
-```
-
-### Step 4: Commit Both Source AND Generated
-
-Always commit the definition source files AND the regenerated output together.
-The generated files are checked into git so `aikit init` can deploy them without
-running the generator.
-
-## Source File Details
-
-### bodies.mjs
-
-Contains `AGENT_BODIES` — an object mapping agent names to their body text.
-
-- Most values are **template literal strings** (`` `...` ``)
-- The **Orchestrator** body is a **function** `(agentTable) => string` because it
-  dynamically includes the agent roster table
-- Backticks inside content must be escaped: `` \` ``
-
-```js
-export const AGENT_BODIES = {
-  Orchestrator: (agentTable) => `# Orchestrator\n${agentTable}\n...`,
-  Implementer: `# Implementer\n...`,
-  Debugger:    `# Debugger\n...`,
-  // ...
-};
-```
-
-### protocols.mjs
-
-Contains `PROTOCOLS` and `TEMPLATES` — objects mapping names to markdown content.
-
-- Each `PROTOCOLS` key becomes a file in `_shared/`:
-  - `'code-agent-base'` → `agents/_shared/code-agent-base.md`
-  - `'researcher-base'` → `agents/_shared/researcher-base.md`
-  - `'decision-protocol'` → `agents/_shared/decision-protocol.md`
-  - etc.
-- Each `TEMPLATES` key becomes a file in `templates/`
-- All values are template literals — escape backticks as `` \` ``
-
-**Protocol → Agent mapping:**
-
-| Protocol | Used by |
-|----------|---------|
-| `code-agent-base` | Implementer, Frontend, Refactor, Debugger |
-| `researcher-base` | Researcher-Alpha/Beta/Gamma/Delta |
-| `code-reviewer-base` | Code-Reviewer-Alpha/Beta |
-| `architect-reviewer-base` | Architect-Reviewer-Alpha/Beta |
-| `decision-protocol` | Referenced by Orchestrator workflow |
-| `forge-protocol` | Referenced by code-agent-base |
-
-### agents.mjs
-
-Defines every agent's metadata:
-- `description`, `argumentHint` — displayed in the agent picker
-- `model` — which LLM model to use
-- `tools` — abstract capability list (mapped to IDE-specific tools by the adapter)
-- `category` — orchestration, implementation, diagnostics, research, review, etc.
-- `sharedBase` — for variant agents (e.g., Researcher-Alpha uses `researcher-base`)
-
-## How Users Receive Changes
-
-When users run `aikit init`, the scaffold files are deployed to their `.github/` directory.
-
-### First Install (Legacy Path)
-
-`copyDirectoryRecursive()` — copies all scaffold files, **skips existing** files.
-No tracking, no merging.
-
-### Updates (Smart Path)
-
-`smartCopyScaffold()` — manifest-based with `.aikit-scaffold.json`:
-
-| File Status | Strategy | Behavior |
-|-------------|----------|----------|
-| `new` (not in manifest, not on disk) | deploy | Copy file, record hash |
-| `new` (not in manifest, exists on disk) | record | Record hash only (preserve user edits) |
-| `outdated` (source hash changed) | `merge-frontmatter` | **Agent files**: update body, union tools, keep user's model choice |
-| `outdated` (source hash changed) | `overwrite` | **Protocol/shared files**: replace entirely |
-| `current` (unchanged) | skip | No action |
-
-The update strategy is determined by `getUpdateStrategy(relPath)` based on the file path.
-
-**Key implication**: When you update an agent body in `bodies.mjs`, existing users will
-get the updated body text while preserving their custom model choice and any extra tools
-they added. Protocol files (`_shared/*.md`) are fully replaced.
-
-## Common Mistakes
-
-| Mistake | Why it's wrong | What to do instead |
-|---------|---------------|-------------------|
-| Editing `.agent.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `bodies.mjs` for agent bodies |
-| Editing `_shared/*.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `protocols.mjs` PROTOCOLS constant |
-| Forgetting to run `generate.mjs` | Generated files will be stale, `aikit init` deploys stale files | Always run after editing definitions |
-| Committing only source OR only generated | Source and output will be out of sync | Commit both together |
-| Unescaped backticks in template literals | JS syntax error in definitions | Use `` \` `` inside template literal strings |
-
-## PR Checklist
-
-- [ ] Changes made in `scaffold/definitions/*.mjs` (NOT in generated output)
-- [ ] `node -c scaffold/definitions/<changed-file>.mjs` passes (syntax check)
-- [ ] `node scaffold/generate.mjs` runs without errors
-- [ ] Generated output contains expected changes (verified with grep)
-- [ ] Both source and generated files included in commit
-- [ ] If adding a new agent: entry in `agents.mjs` + body in `bodies.mjs`
-- [ ] If adding a new protocol: entry in `protocols.mjs` + reference in relevant agent bodies
-- [ ] If adding a new file type: check `getUpdateStrategy()` returns correct merge strategy
-- [ ] Consider impact on existing user installations (will merge preserve their customizations?)
+# Scaffold System — Contributor Guide
+
+> **⚠️ GOLDEN RULE: Never edit files in `scaffold/general/` or `scaffold/claude-code/` directly.**
+> They are **generated output** and will be overwritten by `generate.mjs`.
+> Always edit the **source files** in `scaffold/definitions/`.
+
+## Architecture
+
+```
+scaffold/
+├── definitions/          ← SOURCE OF TRUTH (edit here)
+│   ├── agents.mjs        Agent metadata (name, description, model, tools, category)
+│   ├── bodies.mjs        Agent body text (mode instructions per agent)
+│   ├── models.mjs        Available models per IDE
+│   ├── protocols.mjs     Shared protocol files (_shared/*.md) + templates
+│   ├── tools.mjs         Tool capability → IDE tool mappings
+│   ├── prompts.mjs       Prompt file content
+│   ├── hooks.mjs         Hook definitions
+│   └── plugins.mjs       Plugin definitions
+│
+├── adapters/             ← IDE-specific generators
+│   ├── copilot.mjs       GitHub Copilot adapter (active — generates ~32 files)
+│   └── claude-code.mjs   Claude Code adapter (stub — no output yet)
+│
+├── generate.mjs          ← BUILD SCRIPT (run after any change)
+│
+├── general/              ← GENERATED OUTPUT for Copilot (DO NOT EDIT)
+│   ├── agents/
+│   │   ├── _shared/      Protocol files (from PROTOCOLS in protocols.mjs)
+│   │   ├── templates/    Template files (from TEMPLATES in protocols.mjs)
+│   │   └── *.agent.md    Agent files (from AGENT_BODIES in bodies.mjs)
+│   └── prompts/          Prompt files (from PROMPTS in prompts.mjs)
+│
+└── claude-code/          ← GENERATED OUTPUT for Claude Code (stub, DO NOT EDIT)
+```
+
+### Data Flow
+
+```
+definitions/*.mjs  →  generate.mjs  →  scaffold/general/  →  aikit init  →  .github/ (user project)
+    (source)          (build script)    (generated output)    (deploy)     (user workspace)
+```
+
+## How to Make Changes
+
+### Step 1: Edit Source Files
+
+| What you want to change | Edit this file |
+|--------------------------|---------------|
+| An agent's body/instructions | `definitions/bodies.mjs` → `AGENT_BODIES[agentName]` |
+| Shared rules for code agents | `definitions/protocols.mjs` → `PROTOCOLS['code-agent-base']` |
+| Shared rules for researchers | `definitions/protocols.mjs` → `PROTOCOLS['researcher-base']` |
+| Agent metadata (model, tools) | `definitions/agents.mjs` → `AGENTS[agentName]` |
+| Available models | `definitions/models.mjs` |
+| Tool mappings | `definitions/tools.mjs` |
+| Prompt files | `definitions/prompts.mjs` |
+
+### Step 2: Regenerate Output
+
+```bash
+node scaffold/generate.mjs
+```
+
+This will:
+1. Clean `general/agents/` and `general/prompts/` directories
+2. Regenerate all files from definitions via the copilot adapter
+3. Print every file written (expect ~32 files)
+
+To generate for a specific IDE only:
+```bash
+node scaffold/generate.mjs --ide copilot
+node scaffold/generate.mjs --ide claude-code
+```
+
+### Step 3: Verify
+
+```bash
+# Syntax check the source file you edited
+node -c scaffold/definitions/bodies.mjs
+node -c scaffold/definitions/protocols.mjs
+
+# Verify your changes appear in generated output
+# (use grep/Select-String for key phrases)
+grep -r "your key phrase" scaffold/general/agents/
+```
+
+### Step 4: Commit Both Source AND Generated
+
+Always commit the definition source files AND the regenerated output together.
+The generated files are checked into git so `aikit init` can deploy them without
+running the generator.
+
+## Source File Details
+
+### bodies.mjs
+
+Contains `AGENT_BODIES` — an object mapping agent names to their body text.
+
+- Most values are **template literal strings** (`` `...` ``)
+- The **Orchestrator** body is a **function** `(agentTable) => string` because it
+  dynamically includes the agent roster table
+- Backticks inside content must be escaped: `` \` ``
+
+```js
+export const AGENT_BODIES = {
+  Orchestrator: (agentTable) => `# Orchestrator\n${agentTable}\n...`,
+  Implementer: `# Implementer\n...`,
+  Debugger:    `# Debugger\n...`,
+  // ...
+};
+```
+
+### protocols.mjs
+
+Contains `PROTOCOLS` and `TEMPLATES` — objects mapping names to markdown content.
+
+- Each `PROTOCOLS` key becomes a file in `_shared/`:
+  - `'code-agent-base'` → `agents/_shared/code-agent-base.md`
+  - `'researcher-base'` → `agents/_shared/researcher-base.md`
+  - `'decision-protocol'` → `agents/_shared/decision-protocol.md`
+  - etc.
+- Each `TEMPLATES` key becomes a file in `templates/`
+- All values are template literals — escape backticks as `` \` ``
+
+**Protocol → Agent mapping:**
+
+| Protocol | Used by |
+|----------|---------|
+| `code-agent-base` | Implementer, Frontend, Refactor, Debugger |
+| `researcher-base` | Researcher-Alpha/Beta/Gamma/Delta |
+| `code-reviewer-base` | Code-Reviewer-Alpha/Beta |
+| `architect-reviewer-base` | Architect-Reviewer-Alpha/Beta |
+| `decision-protocol` | Referenced by Orchestrator workflow |
+| `forge-protocol` | Referenced by code-agent-base |
+
+### agents.mjs
+
+Defines every agent's metadata:
+- `description`, `argumentHint` — displayed in the agent picker
+- `model` — which LLM model to use
+- `tools` — abstract capability list (mapped to IDE-specific tools by the adapter)
+- `category` — orchestration, implementation, diagnostics, research, review, etc.
+- `sharedBase` — for variant agents (e.g., Researcher-Alpha uses `researcher-base`)
+
+## How Users Receive Changes
+
+When users run `aikit init`, the scaffold files are deployed to their `.github/` directory.
+
+### First Install (Legacy Path)
+
+`copyDirectoryRecursive()` — copies all scaffold files, **skips existing** files.
+No tracking, no merging.
+
+### Updates (Smart Path)
+
+`smartCopyScaffold()` — manifest-based with `.aikit-scaffold.json`:
+
+| File Status | Strategy | Behavior |
+|-------------|----------|----------|
+| `new` (not in manifest, not on disk) | deploy | Copy file, record hash |
+| `new` (not in manifest, exists on disk) | record | Record hash only (preserve user edits) |
+| `outdated` (source hash changed) | `merge-frontmatter` | **Agent files**: update body, union tools, keep user's model choice |
+| `outdated` (source hash changed) | `overwrite` | **Protocol/shared files**: replace entirely |
+| `current` (unchanged) | skip | No action |
+
+The update strategy is determined by `getUpdateStrategy(relPath)` based on the file path.
+
+**Key implication**: When you update an agent body in `bodies.mjs`, existing users will
+get the updated body text while preserving their custom model choice and any extra tools
+they added. Protocol files (`_shared/*.md`) are fully replaced.
+
+## Common Mistakes
+
+| Mistake | Why it's wrong | What to do instead |
+|---------|---------------|-------------------|
+| Editing `.agent.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `bodies.mjs` for agent bodies |
+| Editing `_shared/*.md` in `general/agents/` | Will be overwritten by `generate.mjs` | Edit `protocols.mjs` PROTOCOLS constant |
+| Forgetting to run `generate.mjs` | Generated files will be stale, `aikit init` deploys stale files | Always run after editing definitions |
+| Committing only source OR only generated | Source and output will be out of sync | Commit both together |
+| Unescaped backticks in template literals | JS syntax error in definitions | Use `` \` `` inside template literal strings |
+
+## PR Checklist
+
+- [ ] Changes made in `scaffold/definitions/*.mjs` (NOT in generated output)
+- [ ] `node -c scaffold/definitions/<changed-file>.mjs` passes (syntax check)
+- [ ] `node scaffold/generate.mjs` runs without errors
+- [ ] Generated output contains expected changes (verified with grep)
+- [ ] Both source and generated files included in commit
+- [ ] If adding a new agent: entry in `agents.mjs` + body in `bodies.mjs`
+- [ ] If adding a new protocol: entry in `protocols.mjs` + reference in relevant agent bodies
+- [ ] If adding a new file type: check `getUpdateStrategy()` returns correct merge strategy
+- [ ] Consider impact on existing user installations (will merge preserve their customizations?)

package/scaffold/definitions/bodies.mjs

@@ -117,7 +117,7 @@ Batch 2 (after batch 1):
 2. **Break tasks small** — 1-3 files per dispatch, clear scope, clear acceptance criteria
 3. **Maximize parallelism** — independent tasks MUST run as parallel \`runSubagent\` calls in the SAME function block. Sequential dispatch of parallelizable tasks is a protocol violation.
 4. **Fresh context per subagent** — paste relevant code, don't reference conversation history
-5. **Search KB before planning** — check past decisions with \`search()\`
+5. **Search AI Kit before planning** — check past decisions with \`search()\`
 6. **Route correctly** — brainstorming for design, decision protocol for tech choices
 7. **Never proceed without user approval** at 🛑 stops
 8. **Max 2 retries** then escalate to user
@@ -182,7 +182,7 @@ At session start, check for an active flow:
 | \`flow_status\` | Check current execution state |
 | \`flow_reset\` | Clear flow state to start over |`,
 
-  Planner: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Planner: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 **Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
@@ -199,7 +199,7 @@ At session start, check for an active flow:
 
 ## Planning Workflow
 
-1. **KB Recall** — Search for past plans, architecture decisions, known patterns. Check \`list()\` for stored knowledge.
+1. **AI Kit Recall** — Search for past plans, architecture decisions, known patterns. Check \`list()\` for stored knowledge.
 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
@@ -252,7 +252,7 @@ At session start, check for an active flow:
 | \`adr-skill\` | When the plan involves non-trivial technical decisions — create executable ADRs |
 | \`session-handoff\` | When context window is filling up, planning session ending, or major milestone completed |`,
 
-  Implementer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Implementer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 **Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
@@ -269,13 +269,13 @@ At session start, check for an active flow:
 
 - **Test-first always** — No implementation without a failing test
 - **Minimal code** — Don't build what isn't asked for
-- **Follow existing patterns** — Search KB for conventions before creating new ones
+- **Follow existing patterns** — Search AI Kit for conventions before creating new ones
 - **Never modify tests to make them pass** — Fix the implementation instead
 - **Run \`check\` after every change** — Catch errors early
 - **Loop-break** — If the same test fails 3 times with the same error after your fixes, STOP. Re-read the error from scratch, check your assumptions with \`trace\` or \`symbol\`, and try a fundamentally different approach. Do not attempt a 4th fix in the same direction
 - **Think-first for complex tasks** — If a task involves 3+ files or non-obvious logic, outline your approach before writing code. Check existing patterns with \`search\` first. Design, then implement`,
 
-  Frontend: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Frontend: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 **Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
@@ -294,13 +294,13 @@ At session start, check for an active flow:
 - **Responsive by default** — Mobile-first, test all breakpoints
 - **Test-first** — Component tests before implementation`,
 
-  Debugger: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Debugger: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 **Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
 ## Debugging Protocol
 
-1. **KB Recall** — Search for known issues matching this error pattern
+1. **AI Kit Recall** — Search for known issues matching this error pattern
 2. **Reproduce** — Confirm the error, use \`parse_output\` on stack traces and build errors for structured analysis
 3. **Verify targets exist** — Before tracing, confirm the files and functions mentioned in the error actually exist. Use \`find\` or \`symbol\` to verify paths and signatures. **Never trace into a file you haven't confirmed exists**
 4. **Trace** — \`symbol\`, \`trace\`, follow call chains backwards
@@ -318,13 +318,13 @@ At session start, check for an active flow:
 - **Verify before asserting** — Don't claim a function has a certain signature without checking via \`symbol\`. Don't reference a config option without confirming it exists in the codebase
 - **Break debug loops** — If you apply a fix, test, and get the same error 3 times: your hypothesis is wrong. STOP, discard your current theory, re-examine the error output and trace from a different entry point. Return \`ESCALATE\` if a fresh approach also fails`,
 
-  Refactor: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Refactor: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 **Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
 ## Refactoring Protocol
 
-1. **KB Recall** — Search for established patterns and conventions
+1. **AI Kit Recall** — Search for established patterns and conventions
 2. **Analyze** — \`analyze_structure\`, \`analyze_patterns\`, \`dead_symbols\`
 3. **Ensure test coverage** — Run existing tests, add coverage for untested paths
 4. **Refactor in small steps** — Each step must keep tests green
@@ -344,7 +344,7 @@ At session start, check for an active flow:
 |-------|--------------|
 | \`lesson-learned\` | After completing a refactor — extract principles from the before/after diff |`,
 
-  Security: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Security: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 **Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
@@ -359,7 +359,7 @@ At session start, check for an active flow:
 
 ## Security Review Protocol
 
-1. **KB Recall** — \`search("security findings <area>")\` + \`list()\` for past security decisions and known issues
+1. **AI Kit Recall** — \`search("security findings <area>")\` + \`list()\` for past security decisions and known issues
 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
@@ -389,7 +389,7 @@ At session start, check for an active flow:
 1. **[SEVERITY]** Title — Description, file:line, remediation
 \`\`\``,
 
-  Documenter: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Documenter: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 **Read _shared/code-agent-base.md NOW** — it contains the Information Lookup Order, FORGE, and handoff protocols.
 
@@ -404,7 +404,7 @@ At session start, check for an active flow:
 
 ## Documentation Protocol
 
-1. **KB Recall** — \`search("documentation <area>")\` + \`list()\` for existing docs, conventions, architecture decisions
+1. **AI Kit Recall** — \`search("documentation <area>")\` + \`list()\` for existing docs, conventions, architecture decisions
 2. **Analyze** — \`analyze_structure\`, \`analyze_entry_points\`, \`file_summary\`
 3. **Draft** — Write documentation following project conventions
 4. **Cross-reference** — Link to related docs, ensure consistency
@@ -432,7 +432,7 @@ At session start, check for an active flow:
 | \`c4-architecture\` | When documenting system architecture — generate C4 Mermaid diagrams |
 | \`adr-skill\` | When documenting architecture decisions — create or update ADRs |`,
 
-  Explorer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and KB protocol.
+  Explorer: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
 ## MANDATORY FIRST ACTION
 
@@ -448,7 +448,7 @@ At session start, check for an active flow:
 
 ## Exploration Protocol
 
-1. **KB Recall** — \`search\` for existing analysis on this area
+1. **AI Kit 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. **Compress** — Use \`compact\` for targeted file sections, \`digest\` when synthesizing 3+ sources, \`stratum_card\` for files you'll reference repeatedly

package/scaffold/definitions/plugins.mjs

@@ -11,7 +11,7 @@
 
 export const PLUGINS = {
   aikit: {
-    description: 'KB search, analysis, memory, and developer tools',
+    description: 'AI Kit search, analysis, memory, and developer tools',
     source: 'scaffold/general/skills/aikit/SKILL.md',
     required: true,
   },

package/scaffold/definitions/prompts.mjs

@@ -10,17 +10,17 @@
 
 export const PROMPTS = {
   ask: {
-    description: 'Quick research question — find answer using KB + web search',
+    description: 'Quick research question — find answer using AI Kit + web search',
     agent: 'Researcher-Alpha',
     tools: ['search', 'web_search', 'web_fetch', 'compact', 'file_summary', 'remember'],
     content: `## Quick Research
 
-1. **KB Recall** — Search knowledge base for existing answers
-2. **Web Search** — If KB has no relevant results, search the web
+1. **AI Kit Recall** — Search knowledge base for existing answers
+2. **Web Search** — If AI Kit 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.`,
+**Always cite sources** — AI Kit entries, file paths, or URLs.`,
   },
 
   debug: {
@@ -40,7 +40,7 @@ export const PROMPTS = {
     content: `## Debug Workflow
 
 1. **Parse Error** — Use \`parse_output\` on the error message/stack trace
-2. **KB Recall** — Search for known issues matching this pattern
+2. **AI Kit 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
@@ -91,7 +91,7 @@ Refer to the Orchestrator agent's full instructions for the detailed workflow.`,
     ],
     content: `## Planning Workflow
 
-1. **KB Recall** — Search for past plans, architecture decisions
+1. **AI Kit 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

package/scaffold/definitions/protocols.mjs

@@ -14,12 +14,12 @@ export const PROTOCOLS = {
 ## Invocation Mode Detection
 
 You may be invoked in two modes:
-1. **Direct** — you have full KB tool access. Follow the **Information Lookup Order** below.
+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 KB Context" in your prompt.
-   If present, skip KB Recall and use the provided context instead.
+   The Orchestrator provides context under "## Prior AI Kit Context" in your prompt.
+   If present, skip AI Kit Recall and use the provided context instead.
 
-**Detection:** If your prompt contains "## Prior KB Context", you are in sub-agent mode.
+**Detection:** If your prompt contains "## Prior AI Kit Context", you are in sub-agent mode.
 
 ---
 
@@ -82,7 +82,7 @@ list()                     // see all stored knowledge entries
 
 ### Step 4: Tool Discovery
 
-If unsure which KB tool to use → run \`guide({ topic: "what you need" })\` for recommendations.
+If unsure which AI Kit tool to use → run \`guide({ topic: "what you need" })\` for recommendations.
 
 ## FORGE Protocol (Quality Gate)
 
@@ -176,7 +176,7 @@ remember({
 
 **If you complete a task without remembering anything, you likely missed something.** Review what you learned.
 
-For outdated KB entries → \`update(path, content, reason)\`
+For outdated AI Kit entries → \`update(path, content, reason)\`
 
 ---
 
@@ -287,7 +287,7 @@ Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code
 
 ## Research Methodology
 
-### Phase 1: KB Recall (BLOCKING)
+### Phase 1: AI Kit Recall (BLOCKING)
 \`\`\`
 search("task keywords")
 scope_map("what you need to investigate")
@@ -358,8 +358,8 @@ When invoked for a decision analysis, you receive a specific question. You MUST:
 
 ## Invocation Mode Detection
 
-- **Direct** (has KB tools) → Follow the **Information Lookup Order** from code-agent-base
-- **Sub-agent** (prompt has "## Prior KB Context") → Skip KB Recall, use provided context
+- **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
 
 ---
 
@@ -387,7 +387,7 @@ Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code
 
 ## Review Workflow
 
-1. **KB Recall** — \`search("conventions relevant-area")\` + \`list()\` for past review findings, patterns
+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
@@ -452,7 +452,7 @@ Follow the **MANDATORY FIRST ACTION** and **Information Lookup Order** from code
 
 ## Review Workflow
 
-1. **KB Recall** — \`search("architecture decisions boundaries")\` + \`list()\` for past ADRs, patterns
+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
@@ -529,7 +529,7 @@ Trigger the decision protocol when there is an **unresolved non-trivial technica
 
 > Follow the FORGE (Fact-Oriented Reasoning with Graduated Evidence) protocol for all code generation and modification tasks.
 
-## KB Tools for FORGE
+## AI Kit Tools for FORGE
 
 | Tool | Purpose | When |
 |------|---------|------|