@vpxa/aikit 0.1.1

package/scaffold/definitions/hooks.mjs

@@ -0,0 +1,43 @@
+/**
+ * Hook definitions — lifecycle events that agents can respond to.
+ *
+ * Not all IDEs support hooks natively:
+ *   - Copilot: No native hook support (hooks are documented in instructions only)
+ *   - Claude Code: Maps to hooks config in settings.json
+ *   - Claude Code: Supports hooks via settings.json
+ *
+ * Each adapter decides how to surface these:
+ *   - Copilot adapter: Embeds as rules in copilot-instructions.md
+ *   - Claude Code adapter: Generates hooks config [future]
+ */
+
+export const HOOKS = {
+  sessionStart: {
+    description: 'Run at the start of every agent session',
+    actions: ['status({})', 'list()', 'search({ query: "SESSION CHECKPOINT", origin: "curated" })'],
+    rationale: 'Resume prior work, load existing knowledge',
+  },
+
+  sessionEnd: {
+    description: 'Run at the end of every agent session',
+    actions: [
+      'remember({ title: "Session checkpoint: <topic>", content: "<decisions, next steps>", category: "conventions" })',
+    ],
+    rationale: 'Persist decisions for future sessions',
+  },
+
+  beforeCodeChange: {
+    description: 'Run before modifying any code',
+    actions: [
+      'search({ query: "<what you are changing>" })',
+      'scope_map({ task: "<description>" })',
+    ],
+    rationale: 'Check for prior decisions and understand impact',
+  },
+
+  beforeCommit: {
+    description: 'Run before committing changes',
+    actions: ['check({})', 'test_run({})', 'blast_radius({ changed_files: ["..."] })'],
+    rationale: 'Validate changes before they enter version control',
+  },
+};

package/scaffold/definitions/models.mjs

@@ -0,0 +1,56 @@
+/**
+ * Centralized model assignments — THE SINGLE FILE to update when models change.
+ *
+ * Keys are agent names (stable, model-agnostic).
+ * Values are model strings in the format expected by the target IDE.
+ * Each IDE adapter may interpret or transform these values.
+ *
+ * Naming convention for variants: {Role}-Alpha, {Role}-Beta, {Role}-Gamma, {Role}-Delta
+ * These are abstract labels — the actual model behind each is defined HERE.
+ */
+
+export const MODELS = {
+  // ─── Single-role agents ───────────────────────────────────────────────
+  Orchestrator: 'Claude Opus 4.6',
+  Planner: 'Claude Opus 4.6',
+  Implementer: 'GPT-5.4',
+  Frontend: 'Gemini 3.1 Pro (Preview)',
+  Debugger: 'Claude Opus 4.6',
+  Refactor: 'GPT-5.4',
+  Security: 'Claude Opus 4.6',
+  Documenter: 'GPT-5.4',
+  Explorer: 'Gemini 3 Flash (Preview)',
+
+  // ─── Researcher variants (4 models for multi-model decision protocol) ────────────
+  'Researcher-Alpha': 'Claude Opus 4.6',
+  'Researcher-Beta': 'Claude Sonnet 4.6',
+  'Researcher-Gamma': 'GPT-5.4',
+  'Researcher-Delta': 'Gemini 3.1 Pro (Preview)',
+
+  // ─── Code-Reviewer variants (2 models for dual review) ───────────────
+  'Code-Reviewer-Alpha': 'GPT-5.4',
+  'Code-Reviewer-Beta': 'Claude Opus 4.6',
+
+  // ─── Architect-Reviewer variants (2 models for dual review) ──────────
+  'Architect-Reviewer-Alpha': 'GPT-5.4',
+  'Architect-Reviewer-Beta': 'Claude Opus 4.6',
+};
+
+/**
+ * Variant group definitions — maps role to variant suffixes.
+ * Used by adapters to know which agents are variants of the same role.
+ */
+export const VARIANT_GROUPS = {
+  Researcher: ['Alpha', 'Beta', 'Gamma', 'Delta'],
+  'Code-Reviewer': ['Alpha', 'Beta'],
+  'Architect-Reviewer': ['Alpha', 'Beta'],
+};
+
+/**
+ * Primary variant per role — the "default" one for single-agent invocation.
+ */
+export const PRIMARY_VARIANT = {
+  Researcher: 'Alpha',
+  'Code-Reviewer': 'Alpha',
+  'Architect-Reviewer': 'Alpha',
+};

package/scaffold/definitions/plugins.mjs

@@ -0,0 +1,38 @@
+/**
+ * Plugin/skill definitions — packages of domain knowledge for agents.
+ *
+ * Copilot: .github/skills/{name}/SKILL.md
+ * Claude Code: Maps to tool_use permissions and MCP config
+ * Claude Code: Referenced via CLAUDE.md or MCP
+ *
+ * Skills are NOT generated — they live in scaffold/general/skills/.
+ * This file defines WHICH skills to copy and their metadata.
+ */
+
+export const PLUGINS = {
+  aikit: {
+    description: 'KB search, analysis, memory, and developer tools',
+    source: 'scaffold/general/skills/aikit/SKILL.md',
+    required: true,
+  },
+
+  brainstorming: {
+    description: 'Brainstorming & design exploration workflow',
+    source: 'scaffold/general/skills/brainstorming/SKILL.md',
+    required: true,
+  },
+
+  'multi-agents-development': {
+    description:
+      'Multi-agent orchestration, task decomposition, parallel dispatch, and review pipeline patterns',
+    source: 'scaffold/general/skills/multi-agents-development/SKILL.md',
+    required: true,
+    sidecars: [
+      'scaffold/general/skills/multi-agents-development/implementer-prompt.md',
+      'scaffold/general/skills/multi-agents-development/spec-review-prompt.md',
+      'scaffold/general/skills/multi-agents-development/code-quality-review-prompt.md',
+      'scaffold/general/skills/multi-agents-development/architecture-review-prompt.md',
+      'scaffold/general/skills/multi-agents-development/parallel-dispatch-example.md',
+    ],
+  },
+};

package/scaffold/definitions/prompts.mjs

@@ -0,0 +1,145 @@
+/**
+ * Prompt/command definitions — IDE-agnostic workflow triggers.
+ *
+ * Copilot: .prompt.md files in .github/prompts/
+ * Claude Code: Maps to CLAUDE.md slash commands
+ * Claude Code: Slash commands
+ *
+ * Each prompt defines: description, target agent, required tools, and content.
+ */
+
+export const PROMPTS = {
+  ask: {
+    description: 'Quick research question — find answer using KB + 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
+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.`,
+  },
+
+  debug: {
+    description: 'Systematic error diagnosis: reproduce → trace → diagnose → fix → verify',
+    agent: 'Debugger',
+    tools: [
+      'search',
+      'symbol',
+      'trace',
+      'blast_radius',
+      'check',
+      'test_run',
+      'parse_output',
+      'compact',
+      'remember',
+    ],
+    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
+3. **Reproduce** — Run the failing command/test to confirm
+4. **Trace** — Use \`symbol\` and \`trace\` to follow the call chain
+5. **Diagnose** — Form hypothesis, gather evidence
+6. **Fix** — Implement minimal fix
+7. **Verify** — \`check\` + \`test_run\` to confirm fix and no regressions
+8. **Remember** — Persist the fix with category \`troubleshooting\``,
+  },
+
+  implement: {
+    description: 'Full lifecycle implementation: plan → build → review → commit',
+    agent: 'Orchestrator',
+    tools: [
+      'search',
+      'scope_map',
+      'forge_ground',
+      'check',
+      'test_run',
+      'blast_radius',
+      'remember',
+      'audit',
+    ],
+    content: `## Implementation Pipeline
+
+Follow the Orchestrator's full workflow:
+
+1. **Phase 0: Design Gate** — Orchestrator checks if design is needed. Creative/additive work triggers brainstorming first. Use \`/design\` if you want to start with design explicitly.
+2. **Phase 1: Planning** — Research, draft plan, present to user for approval
+3. **Phase 2: Implementation** — Execute phases in parallel batches
+4. **Phase 3: Completion** — Final review, docs, persist learnings
+
+**🛑 MANDATORY STOPS** — After plan, after each batch, after completion.
+
+Refer to the Orchestrator agent's full instructions for the detailed workflow.`,
+  },
+
+  plan: {
+    description: 'Create a detailed TDD implementation plan without executing it',
+    agent: 'Planner',
+    tools: [
+      'search',
+      'scope_map',
+      'forge_ground',
+      'forge_classify',
+      'file_summary',
+      'analyze_structure',
+      'analyze_dependencies',
+      'remember',
+    ],
+    content: `## Planning Workflow
+
+1. **KB Recall** — Search for past plans, architecture decisions
+2. **FORGE Ground** — Classify tier, scope map, seed unknowns
+3. **Research** — Explore codebase, understand subsystems
+4. **Draft Plan** — 3-10 phases with agent assignments, TDD steps
+5. **Dependency Graph** — Group into parallel batches
+6. **Present** — Show plan with open questions
+
+**🛑 MANDATORY STOP** — Wait for user approval. Do NOT implement.`,
+  },
+
+  design: {
+    description:
+      'Collaborative design session — explore ideas, refine requirements, produce a design spec',
+    agent: 'Orchestrator',
+    tools: ['search', 'scope_map', 'file_summary', 'compact', 'remember', 'forge_classify'],
+    content: `## Design Session
+
+Enter Phase 0 (Design Gate) directly — the user is requesting a design session.
+
+1. **Invoke the brainstorming skill** — interactive design dialogue with user
+2. Follow the skill's full process (auto-selects Simple or Advanced mode)
+3. If Advanced Mode, use Decision Protocol for unresolved technical choices
+4. Terminal state: brainstorming skill invokes writing-plans skill
+
+**🛑 HARD GATE** — Do NOT skip brainstorming. Do NOT write code. Design first.`,
+  },
+
+  review: {
+    description: 'Dual-model code + architecture review pipeline',
+    agent: 'Orchestrator',
+    tools: ['search', 'blast_radius', 'check', 'test_run', 'analyze_dependencies', 'remember'],
+    content: `## Review Pipeline
+
+### Step 1: Scope
+Identify changed files and their blast radius.
+
+### Step 2: Code Review (parallel)
+Launch Code-Reviewer-Alpha and Code-Reviewer-Beta on the same changeset.
+
+### Step 3: Architecture Review (if needed)
+If changes cross service boundaries or modify interfaces, launch Architect-Reviewer-Alpha and Architect-Reviewer-Beta.
+
+### Step 4: Synthesis
+Merge findings from both reviewers:
+- **Agreements**: Both found same issue → HIGH confidence
+- **Unique findings**: One found, other didn't → verify
+- **Disagreements**: Contradicting verdicts → present both to user
+
+### Step 5: Report
+Present unified review with: verdict, findings by severity, recommended actions.`,
+  },
+};