@vpxa/aikit 0.1.308 → 0.1.310

package/scaffold/INSTRUCTIONS.md

@@ -0,0 +1,273 @@
+# Scaffold Instruction Authoring Guide
+
+This folder is the source of truth for generated agent, skill, prompt, hook, and flow instructions. Future edits must improve instruction adherence, platform parity, and token efficiency without removing behavior that makes agents safer or smarter.
+
+Use this guide when changing source instructions in `scaffold/definitions/`, adapters in `scaffold/adapters/`, or generated previews from `node scaffold/generate.mjs`.
+
+## Source Of Truth Map
+
+| Need | Edit |
+| --- | --- |
+| Agent roster, routing metadata, models, skills | [definitions/agents.mjs](definitions/agents.mjs) |
+| Agent body text and mode behavior | [definitions/bodies.mjs](definitions/bodies.mjs) |
+| Shared agent kernels and long protocols | [definitions/protocols.mjs](definitions/protocols.mjs) |
+| Global policies and generated instruction sections | [definitions/policies.mjs](definitions/policies.mjs) |
+| Skill `SKILL.md`, refs, assets, scripts | [definitions/skills/](definitions/skills/) |
+| Prompt templates | [definitions/prompts.mjs](definitions/prompts.mjs) |
+| Platform-specific output shape | [adapters/](adapters/) |
+| Generated preview/output | [_preview/](_preview/) and generated platform folders |
+
+Never treat generated platform files as source. Change definitions/adapters, then regenerate.
+
+## Prime Rules
+
+1. Optimize for adherence, not raw brevity. Short text that loses a gate, protocol, or routing cue is worse.
+2. Compress protocols; do not amputate them. Replace repeated prose with one canonical kernel, coverage map, or progressive reference.
+3. Keep one source of truth per concept. Metadata routes agents/skills; bodies describe behavior; protocols hold reusable operating rules.
+4. Preserve cross-platform parity. Copilot, Codex, Claude Code, Gemini, OpenCode, Zed, IntelliJ, Hermes, and Hermes-agent may format differently, but must carry equivalent semantics.
+5. Make subagents robust with fresh context. Every subagent must know scope, boundaries, output shape, validation duty, and whether it can edit files.
+6. Prefer progressive disclosure. Put hot-path rules in `SKILL.md` or agent body; put deep procedures in refs/scripts/assets.
+7. Reduce `HARD`, `MUST`, and repeated warnings. Use priority only for true gates. Too many absolute rules blur attention.
+8. Preserve exact technical terms. Do not shorten tool names, protocol names, file paths, model names, or error strings.
+
+## Agent Authoring
+
+### Orchestrator
+
+Orchestrator is usually the main agent. It plans, decomposes, dispatches, gates quality, coordinates review, presents outcomes, and protects user intent.
+
+Keep Orchestrator strong on:
+
+- No direct implementation unless explicitly scoped as trivial.
+- Task decomposition with clear ownership, success criteria, and validation.
+- Subagent dispatch envelopes that include task id, scope, constraints, expected output, tool/skill needs, and communication style.
+- Protocol coverage for conversation compression, decision protocol, FORGE quality gates, thinking principles, multi-agent development, presentation, session handoff, and lesson capture.
+- User style propagation. If user activates terse/caveman style or another response style, Orchestrator must embed it in subagent instructions and tell subagents to follow it unless safety clarity needs full prose.
+
+Do not remove Orchestrator protocols only because they cost tokens. If a long protocol is not on the hot path, replace it with a compact coverage map plus reference, not deletion.
+
+### Planner
+
+Planner may run as main agent or subagent. It produces plans, tests, specs, and sequencing. It should not implement unless an explicit flow step says so.
+
+Keep Planner aligned with Orchestrator:
+
+- Accept Orchestrator handoff fields and preserve task id/evidence.
+- Produce actionable steps, validation gates, dependencies, and risk notes.
+- Avoid flow advancement when acting as a subagent unless explicitly authorized.
+
+### Implementation Agents
+
+Implementer, Frontend, Refactor, Debugger, Security, and Documenter often run as subagents. They still need direct-run behavior for users who invoke them alone.
+
+Each implementation agent should state:
+
+- Primary job and non-goals.
+- Whether it may edit files.
+- Which skills to load from metadata.
+- Validation expected before final response.
+- Output shape for main-agent mode and subagent mode.
+- Stop condition when scope is unclear or unsafe.
+
+Do not duplicate full skill tables inside bodies. `definitions/agents.mjs` owns skill routing. Body text may mention critical skill categories only when behavior depends on them.
+
+### Research And Review Agents
+
+Researchers and reviewers must be independent enough to disagree with plans.
+
+Keep:
+
+- Evidence-first output.
+- Assumptions separated from verified claims.
+- No implementation unless explicitly requested.
+- Clear severity/risk ranking for review agents.
+- Complementary lenses across Alpha/Beta variants.
+
+## Skill Authoring
+
+Skills are progressive instructions. `SKILL.md` should be concise enough to load often, but complete enough to route work safely.
+
+Each skill should include:
+
+- When to use it and when not to use it.
+- Required setup or tool preference.
+- Minimal workflow.
+- Output or handoff shape.
+- Validation or quality bar.
+- References/scripts/assets to load only when needed.
+
+Use refs/assets/scripts for detail. Do not delete them for token savings if they support rare but important paths. Token efficiency comes from loading them conditionally.
+
+When adding or renaming a skill:
+
+1. Add or update the module under [definitions/skills/](definitions/skills/).
+2. Export it from [definitions/skills/index.mjs](definitions/skills/index.mjs).
+3. Add metadata references in [definitions/agents.mjs](definitions/agents.mjs) only for agents that should actually load it.
+4. Regenerate and verify generated skill files across relevant platforms.
+
+## Prompt Authoring
+
+Prompts should launch work, not duplicate entire agents.
+
+Good prompts include:
+
+- Goal.
+- Scope and constraints.
+- Required agent/skill/tool path.
+- Acceptance criteria.
+- Validation command or evidence requirement.
+- Output shape.
+
+Avoid:
+
+- Repeating full Orchestrator or protocol bodies.
+- Platform-specific assumptions unless prompt is platform-specific.
+- Open-ended "do your best" wording without success criteria.
+
+## Skill Reference Pattern
+
+Skills follow the [Anthropic skills specification](https://github.com/anthropics/skills/tree/main/skills/skill-creator):
+
+```
+skill-name/
+  SKILL.md              ← main skill body (hot-path instructions)
+  references/           ← deep-dive details, examples, schemas (loaded conditionally)
+  scripts/              ← executable scripts
+  assets/               ← templates, images, static files
+```
+
+In the scaffold system, each skill is a `.mjs` file that exports an array of `{ file, content }` objects:
+
+```js
+export default [
+  { file: 'SKILL.md', content: '...main body...' },
+  { file: 'references/deep-dive.md', content: '...detailed reference...' },
+  { file: 'scripts/helper.mjs', content: '...executable...' },
+];
+```
+
+The `file` field is relative to the skill's output directory. The scaffold `generateSkills` adapter reads these arrays and writes the actual files.
+
+### When to put content in references vs SKILL.md
+
+| Content type | Where | Why |
+|---|---|---|
+| Trigger rules, core workflow, quality bar, output shape | `SKILL.md` | Hot-path — loaded every time the skill is activated |
+| Full examples, detailed step-by-step, format catalogs, schemas | `references/*.md` | Progressive disclosure — loaded only when needed |
+| Executable helpers, transforms, generators | `scripts/*.mjs` | Run, not read |
+| Templates, images, static data | `assets/` | Referenced, not inlined |
+
+### Rules
+
+- `SKILL.md` should be concise enough to load often, complete enough to route work safely.
+- Move deep procedures to refs; do not delete them. Token efficiency comes from loading them conditionally.
+- Protocol refs in `scaffold/definitions/refs/` may use dual exports: a named `const` for inlining into `protocols.mjs` + a `default` array for file generation.
+- Never create hand-written `.md` reference files — `.mjs` is the source of truth.
+
+## Protocol And Kernel Authoring
+
+Shared protocols exist because repeated body text drifts. Keep reusable behavior in [definitions/protocols.mjs](definitions/protocols.mjs).
+
+Use:
+
+- Shared base kernels for generic subagent behavior.
+- Compact role kernels for code, research, review, architecture, docs, and diagnostics.
+- Coverage maps for long protocols that must remain active but do not need full in-body repetition.
+- Full protocol text where generated platform root docs or adapters need it.
+
+Before removing any `sharedProtocols` entry, prove one of these:
+
+- Same protocol is still included by platform-level instructions.
+- Same behavior is represented in a compact coverage map and tested.
+- Protocol is obsolete and no agent relies on it.
+
+If proof is missing, do not remove it.
+
+## Platform Adapter Rules
+
+Adapters may emit different file layouts, but semantic coverage must match.
+
+Watch these risks:
+
+- Copilot may inline shared protocols and generated agent files.
+- Zed, IntelliJ, Hermes, and prompt-style adapters can under-generate bodies if they skip `AGENT_BODIES`.
+- Hermes-agent and Copilot should not emit unused `_shared` files unless generated files reference them.
+- Skill assets may be embedded or copied depending on platform; verify final `SKILL.md` still points to working refs/assets/scripts.
+
+Adapter changes need cross-platform checks, not only Copilot checks.
+
+## Verification Checklist
+
+Run only the commands needed for the change size, but do not skip parity checks after instruction architecture changes.
+
+```bash
+node scaffold/generate.mjs
+```
+
+For instruction source syntax:
+
+```bash
+node -e "import('./scaffold/definitions/agents.mjs')"
+node -e "import('./scaffold/definitions/bodies.mjs')"
+node -e "import('./scaffold/definitions/protocols.mjs')"
+node -e "import('./scaffold/definitions/prompts.mjs')"
+```
+
+For project validation:
+
+```bash
+node scripts/build.mjs
+npx tsc --noEmit
+npx biome check .
+```
+
+Prefer AI Kit wrappers when available:
+
+- `check({})` for typecheck and lint.
+- `test_run({})` for tests.
+- `blast_radius({ changed_files })` for impact.
+- `reindex({})` after source changes that affect indexed knowledge.
+
+Note: root Vitest config may exclude `scaffold/__tests__`. If scaffold tests do not run through `test_run`, use direct Node assertions or update test config intentionally.
+
+## Quality Review Questions
+
+Ask these before finalizing:
+
+- Does each agent know what to do, when to stop, and what output to return?
+- Can each subagent complete its task with only a dispatch envelope and local instructions?
+- Did optimization remove duplication without removing protocol coverage?
+- Are skills routed through metadata instead of duplicated in prose?
+- Are long details progressively disclosed through refs/assets/scripts?
+- Do all platform outputs carry equivalent agent bodies, protocols, skills, and prompts?
+- Did generated files change only because definitions/adapters changed?
+- Is every changed line tied to user value?
+
+## Common Failure Modes
+
+- Optimizing Copilot only and forgetting other platforms.
+- Removing `sharedProtocols` because body text got shorter, then losing FORGE/decision/compression behavior.
+- Adding local skill tables to agent bodies instead of updating metadata.
+- Creating many `HARD RULE` lines until none stand out.
+- Editing generated output and losing changes on next generate.
+- Forgetting to regenerate after changing definitions.
+- Deleting refs/assets/scripts that are rarely loaded but important when triggered.
+- Letting subagent templates grow into long checklists that lose tail instructions.
+
+## Terse Style Propagation
+
+When user requests terse/caveman communication, preserve technical substance and remove filler. Orchestrator must pass the style rule to subagents and require final outputs to follow it.
+
+Safe compression:
+
+- Drop filler, pleasantries, hedging, articles, and repeated setup.
+- Use fragments and short synonyms where meaning is clear.
+- Keep code blocks, tool names, protocol names, file paths, errors, security warnings, irreversible confirmations, and multi-step safety sequences exact.
+
+Pattern:
+
+```text
+[thing] [action] [reason]. [next step].
+```
+
+Do not apply style compression where ambiguity could cause unsafe action or incorrect implementation.

package/scaffold/dist/adapters/copilot.mjs

@@ -44,7 +44,7 @@ ${y()}
 
 ## Multi-Model Pattern
 
-Variant agents (Researcher-Alpha/Beta/Gamma/Delta, Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta) share the same methodology via files in \`_shared/\`. They differ only in which LLM model backs them — enabling multi-model decision analysis and dual-review workflows.
+Variant agents (Researcher-Alpha/Beta/Gamma/Delta, Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta) share the same inlined methodology. They differ only in which LLM model backs them — enabling multi-model decision analysis and dual-review workflows.
 
 **Agent names are model-agnostic.** The backing model can vary by platform in \`scaffold/definitions/models.mjs\` without renaming any agent files.
 
@@ -53,13 +53,6 @@ Variant agents (Researcher-Alpha/Beta/Gamma/Delta, Code-Reviewer-Alpha/Beta, Arc
 \`\`\`
 agents/
   {Name}.agent.md          — Agent definition (YAML frontmatter + instructions)
-  _shared/                  — Shared protocols referenced by multiple agents
-    code-agent-base.md      — Base for all code-modifying agents
-    researcher-base.md      — Base for all Researcher variants
-    code-reviewer-base.md   — Base for all Code-Reviewer variants
-    architect-reviewer-base.md — Base for all Architect-Reviewer variants
-    decision-protocol.md    — Multi-model decision protocol rules
-    forge-protocol.md       — FORGE quality gate protocol
   templates/
     execution-state.md      — Orchestrator state tracking template
     adr-template.md         — Architecture Decision Record template
@@ -74,4 +67,4 @@ cd knowledge-base
 node scaffold/generate.mjs
 \`\`\`
 `}function w(){return[`# aikit — Copilot Instructions`,``,"This file is generated from `scaffold/definitions/`. Do not edit directly.",``,o,``,`## Tool Routing Rules`,``,`These rules are enforced by AI Kit compliance checking. Violations are flagged in reports and reduce your compliance score.`,``,p(),``,a,``].join(`
-`)}function T(){let t=[];if(f().length===0)throw Error(`Executable hooks are not configured.`);t.push({path:`copilot-instructions.md`,content:w()});for(let[r,i]of Object.entries(e))if(i.variants)for(let e of n[r]||[])t.push({path:`agents/${r}-${e}.agent.md`,content:b(r,e,i)});else t.push({path:`agents/${r}.agent.md`,content:x(r,i)});for(let[e,n]of Object.entries(s))t.push({path:`agents/_shared/${e}.md`,content:`${n}\n`});for(let[e,n]of Object.entries(c))t.push({path:`agents/templates/${e}.md`,content:`${n}\n`});t.push({path:`agents/README.md`,content:C()});for(let[e,n]of Object.entries(i))t.push({path:`prompts/aikit-${e}.prompt.md`,content:S(e,n)});let r=d(`copilot`,`~/.copilot/hooks/scripts`);return t.push(...r.map(e=>({path:`hooks/${e.path}`,content:e.content}))),t}export{T as generateCopilot};
+`)}function T(){let t=[];if(f().length===0)throw Error(`Executable hooks are not configured.`);t.push({path:`copilot-instructions.md`,content:w()});for(let[r,i]of Object.entries(e))if(i.variants)for(let e of n[r]||[])t.push({path:`agents/${r}-${e}.agent.md`,content:b(r,e,i)});else t.push({path:`agents/${r}.agent.md`,content:x(r,i)});for(let[e,n]of Object.entries(c))t.push({path:`agents/templates/${e}.md`,content:`${n}\n`});t.push({path:`agents/README.md`,content:C()});for(let[e,n]of Object.entries(i))t.push({path:`prompts/aikit-${e}.prompt.md`,content:S(e,n)});let r=d(`copilot`,`~/.copilot/hooks/scripts`);return t.push(...r.map(e=>({path:`hooks/${e.path}`,content:e.content}))),t}export{T as generateCopilot};

package/scaffold/dist/adapters/hermes-agent.mjs

@@ -44,7 +44,7 @@ ${b()}
 
 ## Multi-Model Pattern
 
-Variant agents (Researcher-Alpha/Beta/Gamma/Delta, Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta) share the same methodology via files in \`_shared/\`. They differ only in which LLM model backs them — enabling multi-model decision analysis and dual-review workflows.
+Variant agents (Researcher-Alpha/Beta/Gamma/Delta, Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta) share the same inlined methodology. They differ only in which LLM model backs them — enabling multi-model decision analysis and dual-review workflows.
 
 ## Tools
 
@@ -53,4 +53,4 @@ plus AI Kit MCP tools (\`mcp_aikit_search\`, \`mcp_aikit_knowledge\`, etc.) for
 
 See \`AGENTS.md\` (in Hermes config directory) for complete tool usage guidance.
 `}function T(){return[`# aikit — Hermes Agent Instructions`,``,"This file is generated from `scaffold/definitions/`. Do not edit directly.",``,o,``,`## Tool Routing Rules`,``,`Hermes provides native tools (terminal, read_file, write_file, patch, search_files, delegate_task, etc.)`,`plus AI Kit MCP tools (mcp_aikit_*) for code analysis, memory, and context compression.`,``,`### When to Use AI Kit Tools`,``,`| Instead of | Use AI Kit Tool | Why |`,`|-----------|----------------|-----|`,"| `grep` / `rg` | `mcp_aikit_search` or `mcp_aikit_find` | Hybrid search across all indexed content |","| `cat` for understanding | `mcp_aikit_file_summary` or `mcp_aikit_compact` | 10x fewer tokens than raw file reads |","| Running tests in terminal | `mcp_aikit_test_run` | Structured output — no shell needed |","| `tsc` / `biome` in terminal | `mcp_aikit_check` | Typecheck + lint combined |","| Web search | `mcp_aikit_web_search` | Fans out to multiple keyless providers |",``,p(),``,a,``].join(`
-`)}function E(){let t=[];if(f().length===0)throw Error(`Executable hooks are not configured.`);t.push({path:`hermes-instructions.md`,content:T()});for(let[r,i]of Object.entries(e))if(i.variants)for(let e of n[r]||[])t.push({path:`agents/${r}-${e}.agent.md`,content:x(r,e,i)});else t.push({path:`agents/${r}.agent.md`,content:S(r,i)});for(let[e,n]of Object.entries(s))t.push({path:`agents/_shared/${e}.md`,content:`${h(n)}\n`});for(let[e,n]of Object.entries(c))t.push({path:`agents/templates/${e}.md`,content:`${n}\n`});t.push({path:`agents/README.md`,content:w()});for(let[e,n]of Object.entries(i))t.push({path:`prompts/aikit-${e}.prompt.md`,content:C(e,n)});let r=d(`hermes`,`~/.hermes/hooks/scripts`);return t.push(...r.map(e=>({path:`hooks/${e.path}`,content:e.content}))),t}export{E as generateHermesAgent};
+`)}function E(){let t=[];if(f().length===0)throw Error(`Executable hooks are not configured.`);t.push({path:`hermes-instructions.md`,content:T()});for(let[r,i]of Object.entries(e))if(i.variants)for(let e of n[r]||[])t.push({path:`agents/${r}-${e}.agent.md`,content:x(r,e,i)});else t.push({path:`agents/${r}.agent.md`,content:S(r,i)});for(let[e,n]of Object.entries(c))t.push({path:`agents/templates/${e}.md`,content:`${n}\n`});t.push({path:`agents/README.md`,content:w()});for(let[e,n]of Object.entries(i))t.push({path:`prompts/aikit-${e}.prompt.md`,content:C(e,n)});let r=d(`hermes`,`~/.hermes/hooks/scripts`);return t.push(...r.map(e=>({path:`hooks/${e.path}`,content:e.content}))),t}export{E as generateHermesAgent};

package/scaffold/dist/adapters/hermes.mjs

@@ -1,4 +1,8 @@
-import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{PROMPTS as r}from"../definitions/prompts.mjs";import"../definitions/protocols.mjs";import{buildAgentTable as i,buildHooksSection as a,buildPromptSections as o}from"./_shared.mjs";const s=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
-`);[`## Flows`,``,"This project uses aikit's pluggable flow system. Use `flow({ action: 'status' })` to check if a flow is active.",`If dispatched as part of a flow, your work contributes to the current step. Do NOT advance or manage the flow — the Orchestrator handles flow lifecycle.`].join(`
-`);function c(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function l(){return[`# AI Kit — Hermes Agent Instructions`,``,"This project uses **AI Kit** (`@vpxa/aikit`), a local-first MCP server that provides search,",`code analysis, persistent memory, context compression, and guided development flows.`,``,`The AI Kit MCP server is registered in your Hermes config and its 64 tools are available`,"as `mcp_aikit_*` tool calls in every conversation.",``,`## MCP Server`,``,"Server name: `aikit`","Configured via `hermes mcp add` (user-level). Tools are auto-discovered at session start.",``,`## Skills-First Rule`,``,`**Before starting ANY task, check available skills.** If a skill matches your task domain`,`— load it first. Skills contain domain-specific patterns, templates, and constraints.`,``,`## Available Tools (64)`,``,`AI Kit provides tools across the following categories:`,``,`| Category | Tools |`,`|----------|-------|`,"| **Search & Discovery** | `search`, `find`, `symbol`, `trace`, `lookup`, `scope_map`, `file_summary`, `dead_symbols` |","| **Code Analysis** | `analyze`, `blast_radius`, `audit`, `graph`, `health`, `check` |","| **Context Compression** | `compact`, `digest`, `stratum_card` |","| **Memory & Knowledge** | `knowledge`, `remember`, `read`, `update`, `forget`, `list`, `stash` |","| **FORGE Quality Gates** | `forge_classify`, `forge_ground`, `evidence_map`, `compliance_score` |","| **Development Workflows** | `flow`, `onboard`, `reindex`, `status`, `guide`, `config` |","| **Testing & Build** | `test_run`, `parse_output`, `check`, `eval` |","| **Code Manipulation** | `rename`, `codemod`, `data_transform`, `diff_parse`, `git_context`, `replay` |","| **Web & HTTP** | `web_search`, `web_fetch`, `http` |","| **Present & Visualize** | `present`, `signal`, `session_digest` |","| **Sandbox & Process** | `process`, `watch`, `workset`, `lane`, `queue`, `restore`, `delegate` |","| **Utilities** | `encode`, `regex_test`, `measure`, `changelog`, `schema_validate`, `env`, `time` |","| **Browser** | `browser` |",``,`## Important: Prefer AI Kit Tools Over Generic Shell Commands`,``,`When working in this project, use AI Kit MCP tools instead of generic alternatives:`,``,`| Instead of | Use AI Kit Tool | Why |`,`|-----------|----------------|-----|`,"| `grep` / `rg` | `mcp_aikit_search` or `mcp_aikit_find` | Hybrid search (vector + keyword + BM25) across all indexed content |","| `read_file` for understanding | `mcp_aikit_file_summary` or `mcp_aikit_compact` | Structure, exports, imports — 10x fewer tokens than raw file reads |","| `cd` + `ls` | `mcp_aikit_analyze` | Structural analysis with tree views |","| Running tests in terminal | `mcp_aikit_test_run` | Structured test output — no shell needed |","| `tsc` / `biome` in terminal | `mcp_aikit_check` | Typecheck + lint combined |","| Web search | `mcp_aikit_web_search` | Fans out to multiple keyless providers |",``,`## Agents`,``,i(e),``,`## Orchestrator Protocol`,``,`The Orchestrator agent coordinates all other agents. It decomposes complex tasks,`,`dispatches sub-agents, and enforces FORGE quality gates before completion.`,``,`Key behaviors:`,`- **Skills-first**: Check skills before any task`,`- **Parallel dispatch**: Independent sub-tasks run concurrently`,`- **Multi-model research**: 4 Researcher variants analyze decisions from different perspectives`,`- **Dual review**: Code and architecture reviewed from two model perspectives`,`- **FORGE gating**: Tiered quality control (Floor/Standard/Critical)`,``,`## Prompts`,``,o(r),``,s,``,`## Session Protocol`,``,a(n),``].join(`
-`)}function u(){let t=[{path:`AGENTS.md`,content:l()}],n=[];for(let[t,r]of Object.entries(e))if(c(t,n),r.variants)for(let[e,n]of Object.entries(r.variants))`${t}${e}`;return t}export{u as generateHermes};
+import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{HOOKS as n}from"../definitions/hooks.mjs";import{PROMPTS as r}from"../definitions/prompts.mjs";import{PROTOCOLS as i}from"../definitions/protocols.mjs";import{buildAgentTable as a,buildCompactAgentTable as o,buildHooksSection as s,buildPromptSections as c,buildSkillsSection as l,lowerFirst as u}from"./_shared.mjs";const d=[`## Flows`,``,"This project uses aikit's pluggable flow system. Check flow status with the `flow` MCP tool.","If a flow is active, follow the current step's skill instructions. Advance with `flow({ action: 'step', advance: 'next' })`.","Use `flow({ action: 'list' })` to see available flows and `flow({ action: 'start', name, topic })` to begin one."].join(`
+`),f=[`## Flows`,``,"This project uses aikit's pluggable flow system. Use `flow({ action: 'status' })` to check if a flow is active.",`If dispatched as part of a flow, your work contributes to the current step. Do NOT advance or manage the flow — the Orchestrator handles flow lifecycle.`].join(`
+`);function p(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function m(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&i[e.sharedBase]&&t.push(i[e.sharedBase]);for(let n of e.sharedProtocols||[])i[n]&&t.push(i[n]);return t}function h(){let t=a(e),i=o(e),l=c(r),u=[];for(let[t,n]of Object.entries(e)){let e=p(t,i);if(n.variants){for(let[r,i]of Object.entries(n.variants)){let a=`${t}-${r}`;u.push(g(a,{...n,description:i.description||n.description,identity:i.identity,bodyAddendum:i.bodyAddendum},e))}continue}u.push(g(t,n,e))}return[`# AI Kit — Hermes Agent Instructions`,``,"This project uses **AI Kit** (`@vpxa/aikit`), a local-first MCP server that provides search,",`code analysis, persistent memory, context compression, and guided development flows.`,``,`The AI Kit MCP server is registered in your Hermes config and its 64 tools are available`,"as `mcp_aikit_*` tool calls in every conversation.",``,`## MCP Server`,``,"Server name: `aikit`","Configured via `hermes mcp add` (user-level). Tools are auto-discovered at session start.",``,`## Skills-First Rule`,``,`**Before starting ANY task, check available skills.** If a skill matches your task domain`,`— load it first. Skills contain domain-specific patterns, templates, and constraints.`,``,`## Available Tools (64)`,``,`AI Kit provides tools across the following categories:`,``,`| Category | Tools |`,`|----------|-------|`,"| **Search & Discovery** | `search`, `find`, `symbol`, `trace`, `lookup`, `scope_map`, `file_summary`, `dead_symbols` |","| **Code Analysis** | `analyze`, `blast_radius`, `audit`, `graph`, `health`, `check` |","| **Context Compression** | `compact`, `digest`, `stratum_card` |","| **Memory & Knowledge** | `knowledge`, `remember`, `read`, `update`, `forget`, `list`, `stash` |","| **FORGE Quality Gates** | `forge_classify`, `forge_ground`, `evidence_map`, `compliance_score` |","| **Development Workflows** | `flow`, `onboard`, `reindex`, `status`, `guide`, `config` |","| **Testing & Build** | `test_run`, `parse_output`, `check`, `eval` |","| **Code Manipulation** | `rename`, `codemod`, `data_transform`, `diff_parse`, `git_context`, `replay` |","| **Web & HTTP** | `web_search`, `web_fetch`, `http` |","| **Present & Visualize** | `present`, `signal`, `session_digest` |","| **Sandbox & Process** | `process`, `watch`, `workset`, `lane`, `queue`, `restore`, `delegate` |","| **Utilities** | `encode`, `regex_test`, `measure`, `changelog`, `schema_validate`, `env`, `time` |","| **Browser** | `browser` |",``,`## Important: Prefer AI Kit Tools Over Generic Shell Commands`,``,`When working in this project, use AI Kit MCP tools instead of generic alternatives:`,``,`| Instead of | Use AI Kit Tool | Why |`,`|-----------|----------------|-----|`,"| `grep` / `rg` | `mcp_aikit_search` or `mcp_aikit_find` | Hybrid search (vector + keyword + BM25) across all indexed content |","| `read_file` for understanding | `mcp_aikit_file_summary` or `mcp_aikit_compact` | Structure, exports, imports — 10x fewer tokens than raw file reads |","| `cd` + `ls` | `mcp_aikit_analyze` | Structural analysis with tree views |","| Running tests in terminal | `mcp_aikit_test_run` | Structured test output — no shell needed |","| `tsc` / `biome` in terminal | `mcp_aikit_check` | Typecheck + lint combined |","| Web search | `mcp_aikit_web_search` | Fans out to multiple keyless providers |",``,`## Agents`,``,t,``,`## Agent Instructions`,``,u.join(`
+`),``,`## Prompts`,``,l,``,d,``,`## Session Protocol`,``,s(n),``].join(`
+`)}function g(e,t,n){let r=m(t),i=l(t.skills),a=e===`Orchestrator`?d:f,o=[n,...r,t.bodyAddendum,i,a].filter(Boolean).join(`
+
+`).trim();return[`## ${e} - ${t.title||e}`,``,`> ${t.description}`,``,t.identity?`You are the **${e}**${t.identity}`:`You are the **${e}**, ${u(t.description)}.`,...o?[``,o]:[],``].join(`
+`)}function _(){return[{path:`AGENTS.md`,content:h()}]}export{_ as generateHermes};

package/scaffold/dist/adapters/intellij.mjs

@@ -1,3 +1,7 @@
-import{AGENTS as e}from"../definitions/agents.mjs";import{MCP_SERVER_ENTRY as t,SERVER_NAME as n}from"../definitions/mcp.mjs";import{PROMPTS as r}from"../definitions/prompts.mjs";import{buildMcpConfigJson as i,buildPromptFile as a,lowerFirst as o}from"./_shared.mjs";function s(e){return e?.length?[`## Skills`,``,`| Skill | When to load |`,`|-------|--------------|`,...e.map(([e,t])=>`| ${e} | ${t} |`),``]:[]}function c(e,t,n,r,i){let a=[`# ${e} - ${t||e}`,``,`> ${n}`,``,`You are the **${e}**, ${o(n)}.`,``];return i&&a.push(i.trim(),``),a.push(...s(r)),a.join(`
-`)}function l(){let o=[];o.push({path:`mcp.json`,content:`${i({serverName:n,mcpEntry:t,configKey:`mcpServers`})}\n`});for(let[e,t]of Object.entries(r))o.push({path:`.aiassistant/prompts/aikit-${e}.md`,content:a({title:`aikit ${e}`,content:[`> ${t.description}`,``,t.content.trim(),``].join(`
-`)})});for(let[t,n]of Object.entries(e)){if(n.variants){for(let[e,r]of Object.entries(n.variants)){let i=`${t}-${e}`,a=r.description||n.description;o.push({path:`.aiassistant/prompts/agent-${i}.md`,content:c(i,n.title,a,n.skills,r.bodyAddendum)})}continue}o.push({path:`.aiassistant/prompts/agent-${t}.md`,content:c(t,n.title,n.description,n.skills)})}return o}export{l as generateIntelliJ};
+import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{MCP_SERVER_ENTRY as n,SERVER_NAME as r}from"../definitions/mcp.mjs";import{PROMPTS as i}from"../definitions/prompts.mjs";import{PROTOCOLS as a}from"../definitions/protocols.mjs";import{buildCompactAgentTable as o,buildMcpConfigJson as s,buildPromptFile as c,lowerFirst as l}from"./_shared.mjs";function u(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function d(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&a[e.sharedBase]&&t.push(a[e.sharedBase]);for(let n of e.sharedProtocols||[])a[n]&&t.push(a[n]);return t}function f(e){return e?.length?[`## Skills`,``,`| Skill | When to load |`,`|-------|--------------|`,...e.map(([e,t])=>`| ${e} | ${t} |`),``]:[]}function p(e,t,n,r,i){let a=[`# ${e} - ${t||e}`,``,`> ${n}`,``,`You are the **${e}**, ${l(n)}.`,``];return i&&a.push(i.trim(),``),a.push(...f(r)),a.join(`
+`)}function m(){let t=[];t.push({path:`mcp.json`,content:`${s({serverName:r,mcpEntry:n,configKey:`mcpServers`})}\n`});for(let[e,n]of Object.entries(i))t.push({path:`.aiassistant/prompts/aikit-${e}.md`,content:c({title:`aikit ${e}`,content:[`> ${n.description}`,``,n.content.trim(),``].join(`
+`)})});let a=o(e);for(let[n,r]of Object.entries(e)){let e=u(n,a),i=d(r);if(r.variants){for(let[a,o]of Object.entries(r.variants)){let s=`${n}-${a}`,c=o.description||r.description,l=[e,...i,o.bodyAddendum].filter(Boolean).join(`
+
+`);t.push({path:`.aiassistant/prompts/agent-${s}.md`,content:p(s,r.title,c,r.skills,l)})}continue}let o=[e,...i,r.bodyAddendum].filter(Boolean).join(`
+
+`);t.push({path:`.aiassistant/prompts/agent-${n}.md`,content:p(n,r.title,r.description,r.skills,o)})}return t}export{m as generateIntelliJ};

package/scaffold/dist/adapters/skills.mjs

@@ -1 +1,3 @@
-import{SKILLS as e}from"../definitions/skills/index.mjs";import{ALL_BLOCK_DOCS as t,BLOCK_DOCS_BY_SKILL as n,BLOCK_TYPE_LIST as r}from"../generated/block-docs.mjs";const i={bySkill:n,all:t,typeList:r};function a(){let t=[];for(let[n,r]of Object.entries(e)){let e=typeof r==`function`?r({blockDocs:i}):r;for(let{file:r,content:i}of e)t.push({path:`${n}/${r}`,content:i})}return t}export{a as generateSkills};
+import{execSync as e}from"node:child_process";import{existsSync as t,readFileSync as n,statSync as r}from"node:fs";import{dirname as i,join as a,resolve as o}from"node:path";import{fileURLToPath as s}from"node:url";import{SKILLS as c}from"../definitions/skills/index.mjs";import{ALL_BLOCK_DOCS as l,BLOCK_DOCS_BY_SKILL as u,BLOCK_TYPE_LIST as d}from"../generated/block-docs.mjs";const f=i(s(import.meta.url)),p=t(a(f,`..`,`..`,`packages`))?o(f,`..`,`..`):o(f,`..`,`..`,`..`),m=a(p,`packages`,`viewers`,`dist`),h=a(p,`packages`,`viewers`),g={"c4-architecture":[`c4-viewer.html`,`canvas.html`],docs:[`canvas.html`,`tour-viewer.html`]},_={bySkill:u,all:l,typeList:d};function v(){let n=a(m,`c4-viewer.html`);if(t(n)){let e=r(n).mtimeMs,i=[`c4-viewer.html`,`tour-viewer.html`,`index.html`].map(e=>a(h,e)).filter(e=>t(e)).map(e=>r(e).mtimeMs);if(Math.max(...i,0)<=e)return}try{process.stderr.write(`Building viewer assets (packages/viewers/)...
+`),e(`pnpm build`,{cwd:h,stdio:`inherit`})}catch{process.stderr.write(`Warning: could not build viewer assets. Viewer HTML files will be missing from skill output.
+`)}}function y(){let e=[],r=!1;for(let[i,o]of Object.entries(c)){let s=typeof o==`function`?o({blockDocs:_}):o;for(let{file:t,content:n}of s)e.push({path:`${i}/${t}`,content:n});let c=g[i];if(c){r||=(v(),!0);for(let r of c){let o=a(m,r);t(o)&&e.push({path:`${i}/assets/${r}`,content:n(o,`utf8`)})}}}return e}export{y as generateSkills};

package/scaffold/dist/adapters/zed.mjs

@@ -1,2 +1,6 @@
-import{AGENTS as e}from"../definitions/agents.mjs";import{MCP_SERVER_ENTRY as t,SERVER_NAME as n}from"../definitions/mcp.mjs";import{PROMPTS as r}from"../definitions/prompts.mjs";import{buildAgentPrompt as i,buildMcpConfigJson as a,buildPromptFile as o}from"./_shared.mjs";function s(){let s=[];s.push({path:`.zed/settings.json`,content:`${a({serverName:n,mcpEntry:t,configKey:`context_servers`})}\n`});for(let[e,t]of Object.entries(r))s.push({path:`.zed/prompts/aikit-${e}.md`,content:o({title:`aikit ${e}`,content:[`> ${t.description}`,``,t.content.trim(),``].join(`
-`)})});for(let[t,n]of Object.entries(e)){let e=n.title||t;if(n.variants){for(let[r,a]of Object.entries(n.variants)){let o=`${t}-${r}`,c=a.description||n.description;s.push({path:`.zed/prompts/agent-${o}.md`,content:i({name:o,title:e,description:c,skills:n.skills,bodyAddendum:a.bodyAddendum})})}continue}s.push({path:`.zed/prompts/agent-${t}.md`,content:i({name:t,title:e,description:n.description,skills:n.skills})})}return s}export{s as generateZed};
+import{AGENTS as e}from"../definitions/agents.mjs";import{AGENT_BODIES as t}from"../definitions/bodies.mjs";import{MCP_SERVER_ENTRY as n,SERVER_NAME as r}from"../definitions/mcp.mjs";import{PROMPTS as i}from"../definitions/prompts.mjs";import{PROTOCOLS as a}from"../definitions/protocols.mjs";import{buildAgentPrompt as o,buildCompactAgentTable as s,buildMcpConfigJson as c,buildPromptFile as l}from"./_shared.mjs";function u(e,n){let r=t[e];return typeof r==`function`?r(n):r||``}function d(e){let t=[];e.extraBody&&t.push(e.extraBody),e.sharedBase&&a[e.sharedBase]&&t.push(a[e.sharedBase]);for(let n of e.sharedProtocols||[])a[n]&&t.push(a[n]);return t}function f(){let t=[];t.push({path:`.zed/settings.json`,content:`${c({serverName:r,mcpEntry:n,configKey:`context_servers`})}\n`});for(let[e,n]of Object.entries(i))t.push({path:`.zed/prompts/aikit-${e}.md`,content:l({title:`aikit ${e}`,content:[`> ${n.description}`,``,n.content.trim(),``].join(`
+`)})});let a=s(e);for(let[n,r]of Object.entries(e)){let e=r.title||n,i=u(n,a),s=d(r);if(r.variants){for(let[a,c]of Object.entries(r.variants)){let l=`${n}-${a}`,u=c.description||r.description,d=[i,...s,c.bodyAddendum].filter(Boolean).join(`
+
+`);t.push({path:`.zed/prompts/agent-${l}.md`,content:o({name:l,title:e,description:u,skills:r.skills,bodyAddendum:d})})}continue}let c=[i,...s,r.bodyAddendum].filter(Boolean).join(`
+
+`);t.push({path:`.zed/prompts/agent-${n}.md`,content:o({name:n,title:e,description:r.description,skills:r.skills,bodyAddendum:c})})}return t}export{f as generateZed};

package/scaffold/dist/definitions/agents.mjs

@@ -24,6 +24,6 @@ ${l}
 ${e(a)}
 
 ${o}
-${s}`}}const i={Orchestrator:{title:`The Master Conductor`,description:`Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit`,argumentHint:null,toolRole:`orchestrator`,sharedBase:null,sharedProtocols:[`conversation-compression`,`decision-protocol`,`forge-protocol`,`thinking-principles`],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit recall, flow status, search, and ctx ref reuse`]]},Planner:{title:`The Strategic Architect`,description:`Autonomous planner that researches codebases and writes comprehensive TDD implementation plans`,compactRole:`TDD implementation plans`,argumentHint:null,toolRole:`planner`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`planning-principles`],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit reading plans, recall, and compressed context reuse`]]},Implementer:{title:`The Code Builder`,description:`Persistent implementation agent that writes code following TDD practices until all tasks are complete`,compactRole:`New features, wire up, build`,argumentHint:`Implementation task, feature, or phase from plan`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`]]},Frontend:{title:`The UI Specialist`,description:`UI/UX specialist for React, styling, responsive design, and frontend implementation`,compactRole:`UI/UX, React, styling, responsive`,argumentHint:`UI component, styling task, or frontend feature`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`react`,`When building React components — hooks, patterns, Server Components`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`frontend-design`,`When implementing UI/UX — design systems, accessibility, responsive patterns`]]},Refactor:{title:`The Code Sculptor`,description:`Code refactoring specialist that improves structure, readability, and maintainability`,compactRole:`Cleanup, simplify, DRY, extract`,argumentHint:`Code, component, or pattern to refactor`,toolRole:`refactor`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Debugger:{title:`The Problem Solver`,description:`Expert debugger that diagnoses issues, traces errors, and provides solutions using AI Kit traces and compressed context before raw file reads`,compactRole:`Bug diagnosis, error tracing`,argumentHint:`Error message, stack trace, or description of issue`,toolRole:`debugger`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`]]},Security:{title:`The Vulnerability Hunter`,description:`Security specialist that analyzes code for vulnerabilities and compliance`,compactRole:`Vulnerability analysis, auth hardening`,argumentHint:`Code, feature, or component to security review`,toolRole:`security`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing code — security patterns, type safety`]]},Documenter:{title:`The Knowledge Keeper`,description:`Documentation specialist that creates and maintains comprehensive project documentation`,compactRole:`Project documentation`,argumentHint:`Component, API, feature, or area to document`,toolRole:`documenter`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`documentation-principles`],category:`documentation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`present`,`When presenting documentation previews or architecture visuals to the user`],[`docs`,`When creating or updating project documentation — docs/ convention, architecture blueprints, Diátaxis framework`]]},Explorer:{title:`The Rapid Scout`,description:`Rapid codebase exploration to find files, usages, dependencies, and structural context`,compactRole:`Rapid codebase navigation`,argumentHint:`Find files, usages, and context related to: {topic or goal}`,toolRole:`explorer`,sharedBase:null,sharedProtocols:[`thinking-principles`],category:`exploration`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Researcher:{title:`The Context Gatherer`,description:`Deep analysis, architecture review, and multi-model decision protocol participant`,compactRole:`Multi-model deep research`,argumentHint:`Research question, problem statement, or subsystem to investigate`,toolRole:`researcher`,sharedBase:`researcher-base`,sharedProtocols:[`thinking-principles`],category:`research`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`lesson-learned`,`When analyzing past changes to extract engineering principles`],[`c4-architecture`,`When researching system architecture — produce C4 diagrams`],[`adr-skill`,`When the research involves a technical decision — draft an ADR`]],variants:{Alpha:n({description:`Primary deep research agent — also serves as default Researcher`,lensName:`Contrarian`,lensDescription:`deep research`,lensPrompt:`actively look for flaws, fatal assumptions, and hidden risks in every approach. The best ideas survive adversarial pressure.`,identityIntro:`, the primary deep research agent. During multi-model decision sessions, you provide deep reasoning and nuanced system design.`,requiredOutputSection:`Depth Analysis`,requiredOutputItems:[`Deep-dive into ONE chosen subsystem (most structurally central to the question)`,`Full evidence chain: file:line citations for every structural claim`,"At least 2 `compact`/`file_summary` extracts woven into the narrative"],focusAreas:[`For every proposed approach, actively seek the fatal flaw or hidden assumption`,`Ask: "Under what conditions does this approach fail catastrophically?"`,`Prefer uncomfortable truths over comfortable consensus`],variantSummary:`You are the DEFAULT researcher. When the Orchestrator needs breadth + depth, they
+${s}`}}const i={Orchestrator:{title:`The Master Conductor`,description:`Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit`,argumentHint:null,toolRole:`orchestrator`,sharedBase:null,sharedProtocols:[],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit recall, flow status, search, and ctx ref reuse`],[`multi-agents-development`,`Before delegation — decomposition, dispatch envelope, review pipeline`],[`present`,`For plans, reviews, evidence maps, approvals, and non-tiny user output`],[`brainstorming`,`For design forks, trade-offs, or creative requirements`],[`requirements-clarity`,`For vague, large, or cross-team requirements before planning`],[`c4-architecture`,`For architecture diagrams, boundary questions, or structure docs`],[`adr-skill`,`For non-trivial technical decisions and ADR lifecycle`],[`docs`,`For docs-sync, durable docs, PRDs, tours, and architecture docs`],[`lesson-learned`,`After implementation/review work — persist reusable engineering lessons`],[`session-handoff`,`When context pressure rises or work must pause/resume`],[`repo-access`,`For private/self-hosted repo access failures`],[`browser-use`,`For browser auth, JS-rendered pages, visual verification, web automation`]]},Planner:{title:`The Strategic Architect`,description:`Autonomous planner that researches codebases and writes comprehensive TDD implementation plans`,compactRole:`TDD implementation plans`,argumentHint:null,toolRole:`planner`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`planning-principles`],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit reading plans, recall, and compressed context reuse`],[`multi-agents-development`,`For decomposition, dependency batches, and dispatch envelopes`],[`brainstorming`,`For new feature/behavior planning and design alternatives`],[`requirements-clarity`,`For vague or large requirements before planning`],[`present`,`For plan, dependency graph, risk matrix, and approval display`],[`c4-architecture`,`For architecture changes and C4 diagrams`],[`adr-skill`,`For non-trivial technical decisions and ADRs`],[`session-handoff`,`For context pressure or session end`],[`repo-access`,`For private or self-hosted repo access`],[`browser-use`,`For auth recovery or browser workflows`]]},Implementer:{title:`The Code Builder`,description:`Persistent implementation agent that writes code following TDD practices until all tasks are complete`,compactRole:`New features, wire up, build`,argumentHint:`Implementation task, feature, or phase from plan`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`react`,`When implementing React components, hooks, or pages`],[`lesson-learned`,`After completing non-obvious implementation work`]]},Frontend:{title:`The UI Specialist`,description:`UI/UX specialist for React, styling, responsive design, and frontend implementation`,compactRole:`UI/UX, React, styling, responsive`,argumentHint:`UI component, styling task, or frontend feature`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`react`,`When building React components — hooks, patterns, Server Components`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`frontend-design`,`When implementing UI/UX — design systems, accessibility, responsive patterns`],[`browser-use`,`When visual/browser verification is needed`],[`lesson-learned`,`After completing non-obvious frontend implementation work`]]},Refactor:{title:`The Code Sculptor`,description:`Code refactoring specialist that improves structure, readability, and maintainability`,compactRole:`Cleanup, simplify, DRY, extract`,argumentHint:`Code, component, or pattern to refactor`,toolRole:`refactor`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When refactoring TypeScript code — type patterns, generics, utility types`],[`lesson-learned`,`After completing refactor — extract principles from before/after diff`]]},Debugger:{title:`The Problem Solver`,description:`Expert debugger that diagnoses issues, traces errors, and provides solutions using AI Kit traces and compressed context before raw file reads`,compactRole:`Bug diagnosis, error tracing`,argumentHint:`Error message, stack trace, or description of issue`,toolRole:`debugger`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`browser-use`,`For browser/UI reproduction loops and JS-rendered failures`],[`repo-access`,`When debugging depends on private or enterprise repo access`],[`lesson-learned`,`After a non-obvious root cause or fix`]]},Security:{title:`The Vulnerability Hunter`,description:`Security specialist that analyzes code for vulnerabilities and compliance`,compactRole:`Vulnerability analysis, auth hardening`,argumentHint:`Code, feature, or component to security review`,toolRole:`security`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing code — security patterns, type safety`],[`repo-access`,`When security review requires private/enterprise repo access`],[`browser-use`,`When reviewing browser auth, sessions, cookies, or web security flows`]]},Documenter:{title:`The Knowledge Keeper`,description:`Documentation specialist that creates and maintains comprehensive project documentation`,compactRole:`Project documentation`,argumentHint:`Component, API, feature, or area to document`,toolRole:`documenter`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`documentation-principles`],category:`documentation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`docs`,`When creating or updating project documentation — docs/ convention, architecture blueprints, Diátaxis framework`],[`present`,`When presenting documentation previews or architecture visuals to the user`],[`c4-architecture`,`When documenting architecture, containers, components, or deployment`],[`adr-skill`,`When docs involve technical decisions or ADR updates`],[`typescript`,`When documenting TypeScript APIs, public types, or generated docs`],[`session-handoff`,`When docs work spans sessions or context pressure rises`]]},Explorer:{title:`The Rapid Scout`,description:`Rapid codebase exploration to find files, usages, dependencies, and structural context`,compactRole:`Rapid codebase navigation`,argumentHint:`Find files, usages, and context related to: {topic or goal}`,toolRole:`explorer`,sharedBase:null,sharedProtocols:[`thinking-principles`],category:`exploration`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Researcher:{title:`The Context Gatherer`,description:`Deep analysis, architecture review, and multi-model decision protocol participant`,compactRole:`Multi-model deep research`,argumentHint:`Research question, problem statement, or subsystem to investigate`,toolRole:`researcher`,sharedBase:`researcher-base`,sharedProtocols:[`thinking-principles`],category:`research`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`lesson-learned`,`When analyzing past changes to extract engineering principles`],[`c4-architecture`,`When researching system architecture — produce C4 diagrams`],[`adr-skill`,`When the research involves a technical decision — draft an ADR`],[`repo-access`,`When research needs private or enterprise repository access`],[`browser-use`,`When web research needs login, JS rendering, or browser automation`]],variants:{Alpha:n({description:`Primary deep research agent — also serves as default Researcher`,lensName:`Contrarian`,lensDescription:`deep research`,lensPrompt:`actively look for flaws, fatal assumptions, and hidden risks in every approach. The best ideas survive adversarial pressure.`,identityIntro:`, the primary deep research agent. During multi-model decision sessions, you provide deep reasoning and nuanced system design.`,requiredOutputSection:`Depth Analysis`,requiredOutputItems:[`Deep-dive into ONE chosen subsystem (most structurally central to the question)`,`Full evidence chain: file:line citations for every structural claim`,"At least 2 `compact`/`file_summary` extracts woven into the narrative"],focusAreas:[`For every proposed approach, actively seek the fatal flaw or hidden assumption`,`Ask: "Under what conditions does this approach fail catastrophically?"`,`Prefer uncomfortable truths over comfortable consensus`],variantSummary:`You are the DEFAULT researcher. When the Orchestrator needs breadth + depth, they
 dispatch you alone. Your lens: thorough, evidence-first, exhaustive + contrarian.`}),Beta:n({description:`Research variant — pragmatic analysis with focus on trade-offs and edge cases`,lensName:`First Principles`,lensDescription:`pragmatic analysis`,lensPrompt:`strip away assumptions, decompose to ground truths, and rebuild reasoning from scratch.`,identityIntro:`, a variant of the Researcher agent optimized for **pragmatic analysis**. Focus on trade-offs, edge cases, and practical constraints. Challenge assumptions and highlight risks the primary researcher may overlook.`,requiredOutputSection:`Failure Modes & Counter-Evidence`,requiredOutputItems:[`At least 3 adversarial claims challenging your own primary finding`,`For each counter-claim: the condition under which it would be TRUE, and the
-  evidence (file:line or search receipt) that currently falsifies it`,"Any unresolved counter-evidence flagged as `⚠ UNRESOLVED`"],focusAreas:[`Strip every assumption: "Is this truly required, or just inherited convention?"`,`Decompose to ground truths, then rebuild the reasoning from scratch`,`If the current approach exists only because "that's how it's always been done", flag it`],variantSummary:"Your lens: pragmatic skepticism + first principles. Mark competing claims as `A` (Assumed)\nby default; challenge before promoting to `V`."}),Gamma:n({description:`Research variant — broad pattern matching across domains and technologies`,lensName:`Expansionist`,lensDescription:`cross-domain pattern matching`,lensPrompt:`look for the bigger opportunity, find what's undervalued, and identify patterns others dismiss.`,identityIntro:`, a variant of the Researcher agent optimized for **cross-domain pattern matching**. Draw connections from other domains, frameworks, and industries. Bring breadth where Alpha brings depth.`,requiredOutputSection:`Cross-Domain Analogies`,requiredOutputItems:[`At least 2 patterns from other tools/frameworks/domains that apply to the question`,"For each: the external source (cite via `web_search` or `web_fetch` receipt) and\n  how it maps to our codebase",`One "missing pattern we should adopt" recommendation`],focusAreas:[`Ask: "What's the bigger opportunity everyone else is ignoring?"`,`Seek undervalued approaches and non-obvious connections across domains`,`Challenge narrow framing: "Is this really just an X problem, or is it also a Y problem?"`],variantSummary:"Your lens: cross-domain pattern matching + expansionist. Weight `web_search` + `web_fetch`\nhigher than peers. Assume the LLM's training data is stale — verify with fresh searches."}),Delta:n({description:`Research variant — implementation feasibility and performance implications`,lensName:`Executor`,lensDescription:`implementation feasibility`,lensPrompt:`focus on what can actually be built, the fastest path to value, and real-world constraints.`,identityIntro:`, a variant of the Researcher agent optimized for **implementation feasibility**. Focus on performance implications, scaling concerns, and concrete implementation paths. Ground theoretical proposals in practical reality.`,requiredOutputSection:`Implementation Cost & Feasibility`,requiredOutputItems:["Complexity snapshot: you MUST call `measure({ path })` on any file ≥ 50 LOC in the\n  target subsystem at least once and quote the `cognitiveComplexity` result","Blast radius estimate: `blast_radius({ changed_files })` on the proposed edits",`Time/risk table: | Change | Lines | Risk | Effort |`,`Feasibility verdict: SAFE / RISKY / INFEASIBLE with one-line justification`],focusAreas:[`Ask: "Can this actually be built? What's the fastest path to a working version?"`,`Ground every proposal in concrete effort: lines of code, files changed, risk`,`Reject elegant theory that can't survive contact with the codebase`],variantSummary:'Your lens: implementation feasibility + executor. Prefer `measure` + `blast_radius` +\n`analyze({ items: [{aspect: "patterns", ...}] })` over abstract reasoning.'})}},"Code-Reviewer":{title:`The Quality Guardian`,description:`Code review specialist analyzing code for quality, security, performance, and maintainability`,compactRole:`Dual-perspective code review`,argumentHint:`File path, PR, or code to review`,toolRole:`reviewer`,sharedBase:`code-reviewer-base`,sharedProtocols:[`thinking-principles`,`review-principles`],category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing TypeScript code — type patterns, best practices`]],variants:{Alpha:r({roleName:`Code-Reviewer`,description:`Primary code reviewer`,lensName:`Compliance & Red-Team`,lensDescription:`compliance and red-teaming`,lensPrompt:`you hunt for correctness bugs, security holes, and contract violations that will break in production.`,identityIntro:`, the primary Code-Reviewer agent.`,focusAreas:[`**Correctness** — Logic errors, race conditions, null/undefined paths, off-by-one`,`**Security** — OWASP Top 10, input validation, secrets, injection vectors`,`**Contract compliance** — Does this honor its type signatures, API contracts, and invariants?`,`**Error handling** — What happens on the unhappy path? Missing try/catch, swallowed errors`],instinct:`Your instinct: "How does this break?" Think like an attacker and a pessimist.`,closing:`When in doubt, flag it — false positives are cheaper than missed bugs in production.`}),Beta:r({roleName:`Code-Reviewer`,description:`Code reviewer variant — different LLM perspective for dual review`,lensName:`Quality & Engineering Excellence`,lensDescription:`quality and engineering excellence`,lensPrompt:`you focus on maintainability, performance, testing, and whether the code will age well.`,identityIntro:`, the secondary Code-Reviewer agent.`,focusAreas:[`**Maintainability** — Naming clarity, single responsibility, cognitive complexity, DRY`,`**Performance** — N+1 queries, unnecessary allocations, missing caching, O(n²) where O(n) suffices`,`**Testing** — Coverage for new/changed logic, edge cases, test readability`,`**Patterns** — Consistency with existing codebase conventions, idiomatic usage`],instinct:`Your instinct: "Will a new team member understand this in 6 months?" Think like a mentor.`,closing:`Prefer actionable suggestions over vague concerns. Show the better version when possible.`})}},"Architect-Reviewer":{title:`The Structural Guardian`,description:`Reviews architecture for pattern adherence, SOLID compliance, dependency direction, and structural integrity`,compactRole:`Architecture review`,argumentHint:`Files, PR, or subsystem to architecture-review`,toolRole:`reviewer`,sharedBase:`architect-reviewer-base`,sharedProtocols:[`thinking-principles`,`review-principles`],category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`c4-architecture`,`When reviewing architectural diagrams or boundary changes`],[`adr-skill`,`When the review involves architecture decisions — reference or create ADRs`]],extraBody:`You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.`,variants:{Alpha:r({roleName:`Architect-Reviewer`,description:`Primary architecture reviewer`,lensName:`Structural Prosecutor`,lensDescription:`structural prosecution`,lensPrompt:`you challenge architectural choices, find boundary violations, and test whether the design survives growth.`,identityIntro:`, the primary Architect-Reviewer agent.`,focusHeading:`Your primary focus areas:`,focusAreas:[`**Boundary violations** — Does this cross package/module boundaries it shouldn't?`,`**Dependency direction** — Are dependencies flowing inward? Any layer leakage?`,`**Hidden coupling** — Shared mutable state, implicit contracts, temporal coupling`,`**Scalability stress** — What breaks at 10x load, 10x data, 10x features?`],instinct:`Your instinct: "This design will fail when..." Challenge every architectural assumption.`,closing:`If a boundary is crossed, require justification or block.`}),Beta:r({roleName:`Architect-Reviewer`,description:`Architecture reviewer variant — different LLM perspective for dual review`,lensName:`Pragmatic Defense`,lensDescription:`pragmatic defense`,lensPrompt:`you evaluate whether the architecture is proportional to the problem, and defend reasonable trade-offs.`,identityIntro:`, the secondary Architect-Reviewer agent.`,focusHeading:`Your primary focus areas:`,focusAreas:[`**Proportionality** — Is the architecture proportional to the problem? Over-engineering is a defect.`,`**Trade-off validity** — Are the trade-offs explicitly acknowledged and reasonable?`,`**Migration path** — Can this evolve without a rewrite? Is there a clear upgrade path?`,`**Team ergonomics** — Can the team actually maintain this? Does it match their skills?`],instinct:`Your instinct: "Is this the simplest architecture that solves the actual problem?"`,closing:`Push back on unnecessary complexity. Defend working solutions against premature abstraction.`})}}};export{i as AGENTS};
+  evidence (file:line or search receipt) that currently falsifies it`,"Any unresolved counter-evidence flagged as `⚠ UNRESOLVED`"],focusAreas:[`Strip every assumption: "Is this truly required, or just inherited convention?"`,`Decompose to ground truths, then rebuild the reasoning from scratch`,`If the current approach exists only because "that's how it's always been done", flag it`],variantSummary:"Your lens: pragmatic skepticism + first principles. Mark competing claims as `A` (Assumed)\nby default; challenge before promoting to `V`."}),Gamma:n({description:`Research variant — broad pattern matching across domains and technologies`,lensName:`Expansionist`,lensDescription:`cross-domain pattern matching`,lensPrompt:`look for the bigger opportunity, find what's undervalued, and identify patterns others dismiss.`,identityIntro:`, a variant of the Researcher agent optimized for **cross-domain pattern matching**. Draw connections from other domains, frameworks, and industries. Bring breadth where Alpha brings depth.`,requiredOutputSection:`Cross-Domain Analogies`,requiredOutputItems:[`At least 2 patterns from other tools/frameworks/domains that apply to the question`,"For each: the external source (cite via `web_search` or `web_fetch` receipt) and\n  how it maps to our codebase",`One "missing pattern we should adopt" recommendation`],focusAreas:[`Ask: "What's the bigger opportunity everyone else is ignoring?"`,`Seek undervalued approaches and non-obvious connections across domains`,`Challenge narrow framing: "Is this really just an X problem, or is it also a Y problem?"`],variantSummary:"Your lens: cross-domain pattern matching + expansionist. Weight `web_search` + `web_fetch`\nhigher than peers. Assume the LLM's training data is stale — verify with fresh searches."}),Delta:n({description:`Research variant — implementation feasibility and performance implications`,lensName:`Executor`,lensDescription:`implementation feasibility`,lensPrompt:`focus on what can actually be built, the fastest path to value, and real-world constraints.`,identityIntro:`, a variant of the Researcher agent optimized for **implementation feasibility**. Focus on performance implications, scaling concerns, and concrete implementation paths. Ground theoretical proposals in practical reality.`,requiredOutputSection:`Implementation Cost & Feasibility`,requiredOutputItems:["Complexity snapshot: you MUST call `measure({ path })` on any file ≥ 50 LOC in the\n  target subsystem at least once and quote the `cognitiveComplexity` result","Blast radius estimate: `blast_radius({ changed_files })` on the proposed edits",`Time/risk table: | Change | Lines | Risk | Effort |`,`Feasibility verdict: SAFE / RISKY / INFEASIBLE with one-line justification`],focusAreas:[`Ask: "Can this actually be built? What's the fastest path to a working version?"`,`Ground every proposal in concrete effort: lines of code, files changed, risk`,`Reject elegant theory that can't survive contact with the codebase`],variantSummary:'Your lens: implementation feasibility + executor. Prefer `measure` + `blast_radius` +\n`analyze({ items: [{aspect: "patterns", ...}] })` over abstract reasoning.'})}},"Code-Reviewer":{title:`The Quality Guardian`,description:`Code review specialist analyzing code for quality, security, performance, and maintainability`,compactRole:`Dual-perspective code review`,argumentHint:`File path, PR, or code to review`,toolRole:`reviewer`,sharedBase:`code-reviewer-base`,sharedProtocols:[`thinking-principles`,`review-principles`],category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing TypeScript code — type patterns, best practices`],[`lesson-learned`,`When review exposes a reusable engineering lesson`]],variants:{Alpha:r({roleName:`Code-Reviewer`,description:`Primary code reviewer`,lensName:`Compliance & Red-Team`,lensDescription:`compliance and red-teaming`,lensPrompt:`you hunt for correctness bugs, security holes, and contract violations that will break in production.`,identityIntro:`, the primary Code-Reviewer agent.`,focusAreas:[`**Correctness** — Logic errors, race conditions, null/undefined paths, off-by-one`,`**Security** — OWASP Top 10, input validation, secrets, injection vectors`,`**Contract compliance** — Does this honor its type signatures, API contracts, and invariants?`,`**Error handling** — What happens on the unhappy path? Missing try/catch, swallowed errors`],instinct:`Your instinct: "How does this break?" Think like an attacker and a pessimist.`,closing:`When in doubt, flag it — false positives are cheaper than missed bugs in production.`}),Beta:r({roleName:`Code-Reviewer`,description:`Code reviewer variant — different LLM perspective for dual review`,lensName:`Quality & Engineering Excellence`,lensDescription:`quality and engineering excellence`,lensPrompt:`you focus on maintainability, performance, testing, and whether the code will age well.`,identityIntro:`, the secondary Code-Reviewer agent.`,focusAreas:[`**Maintainability** — Naming clarity, single responsibility, cognitive complexity, DRY`,`**Performance** — N+1 queries, unnecessary allocations, missing caching, O(n²) where O(n) suffices`,`**Testing** — Coverage for new/changed logic, edge cases, test readability`,`**Patterns** — Consistency with existing codebase conventions, idiomatic usage`],instinct:`Your instinct: "Will a new team member understand this in 6 months?" Think like a mentor.`,closing:`Prefer actionable suggestions over vague concerns. Show the better version when possible.`})}},"Architect-Reviewer":{title:`The Structural Guardian`,description:`Reviews architecture for pattern adherence, SOLID compliance, dependency direction, and structural integrity`,compactRole:`Architecture review`,argumentHint:`Files, PR, or subsystem to architecture-review`,toolRole:`reviewer`,sharedBase:`architect-reviewer-base`,sharedProtocols:[`thinking-principles`,`review-principles`],category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`c4-architecture`,`When reviewing architectural diagrams or boundary changes`],[`adr-skill`,`When the review involves architecture decisions — reference or create ADRs`],[`docs`,`When architecture review should update durable documentation`]],extraBody:`You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.`,variants:{Alpha:r({roleName:`Architect-Reviewer`,description:`Primary architecture reviewer`,lensName:`Structural Prosecutor`,lensDescription:`structural prosecution`,lensPrompt:`you challenge architectural choices, find boundary violations, and test whether the design survives growth.`,identityIntro:`, the primary Architect-Reviewer agent.`,focusHeading:`Your primary focus areas:`,focusAreas:[`**Boundary violations** — Does this cross package/module boundaries it shouldn't?`,`**Dependency direction** — Are dependencies flowing inward? Any layer leakage?`,`**Hidden coupling** — Shared mutable state, implicit contracts, temporal coupling`,`**Scalability stress** — What breaks at 10x load, 10x data, 10x features?`],instinct:`Your instinct: "This design will fail when..." Challenge every architectural assumption.`,closing:`If a boundary is crossed, require justification or block.`}),Beta:r({roleName:`Architect-Reviewer`,description:`Architecture reviewer variant — different LLM perspective for dual review`,lensName:`Pragmatic Defense`,lensDescription:`pragmatic defense`,lensPrompt:`you evaluate whether the architecture is proportional to the problem, and defend reasonable trade-offs.`,identityIntro:`, the secondary Architect-Reviewer agent.`,focusHeading:`Your primary focus areas:`,focusAreas:[`**Proportionality** — Is the architecture proportional to the problem? Over-engineering is a defect.`,`**Trade-off validity** — Are the trade-offs explicitly acknowledged and reasonable?`,`**Migration path** — Can this evolve without a rewrite? Is there a clear upgrade path?`,`**Team ergonomics** — Can the team actually maintain this? Does it match their skills?`],instinct:`Your instinct: "Is this the simplest architecture that solves the actual problem?"`,closing:`Push back on unnecessary complexity. Defend working solutions against premature abstraction.`})}}};export{i as AGENTS};