@vpxa/aikit 0.1.75 → 0.1.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.75",
+  "version": "0.1.76",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",
@@ -36,7 +36,6 @@
     "!scaffold/generate.mjs",
     "!scaffold/adapters/",
     "!scaffold/compiled/",
-    "!scaffold/definitions/",
     "README.md",
     "LICENSE"
   ],

package/scaffold/definitions/agents.mjs

@@ -0,0 +1,266 @@
+/**
+ * Agent definitions — role, description, capabilities, and variant configuration.
+ *
+ * These are IDE-agnostic. Each IDE adapter reads these definitions and
+ * produces its own file format (.agent.md, .mdc, CLAUDE.md sections, etc.).
+ *
+ * `toolRole` maps to a key in tools.mjs IDE_CAPABILITIES.
+ * `variants` (if present) means this role has multiple model variants.
+ * `sharedBase` points to a shared protocol file the agent should reference.
+ */
+
+export const AGENTS = {
+  // ─── Orchestration ────────────────────────────────────────────────────
+
+  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, // Orchestrator has inline instructions
+    sharedProtocols: ['decision-protocol', 'forge-protocol'],
+    category: 'orchestration',
+    skills: [],
+  },
+
+  Planner: {
+    title: 'The Strategic Architect',
+    description:
+      'Autonomous planner that researches codebases and writes comprehensive TDD implementation plans',
+    argumentHint: null,
+    toolRole: 'planner',
+    sharedBase: 'code-agent-base',
+    category: 'orchestration',
+  },
+
+  // ─── Implementation ───────────────────────────────────────────────────
+
+  Implementer: {
+    title: 'The Code Builder',
+    description:
+      'Persistent implementation agent that writes code following TDD practices until all tasks are complete',
+    argumentHint: 'Implementation task, feature, or phase from plan',
+    toolRole: 'codeAgent',
+    sharedBase: 'code-agent-base',
+    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',
+    argumentHint: 'UI component, styling task, or frontend feature',
+    toolRole: 'codeAgent',
+    sharedBase: 'code-agent-base',
+    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',
+    argumentHint: 'Code, component, or pattern to refactor',
+    toolRole: 'refactor',
+    sharedBase: 'code-agent-base',
+    category: 'implementation',
+    skills: [['aikit', '**Always** — AI Kit tool signatures, search, analysis']],
+  },
+
+  // ─── Diagnostics ──────────────────────────────────────────────────────
+
+  Debugger: {
+    title: 'The Problem Solver',
+    description: 'Expert debugger that diagnoses issues, traces errors, and provides solutions',
+    argumentHint: 'Error message, stack trace, or description of issue',
+    toolRole: 'debugger',
+    sharedBase: 'code-agent-base',
+    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',
+    argumentHint: 'Code, feature, or component to security review',
+    toolRole: 'security',
+    sharedBase: 'code-agent-base',
+    category: 'diagnostics',
+    skills: [
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['typescript', 'When reviewing code — security patterns, type safety'],
+    ],
+  },
+
+  // ─── Documentation ────────────────────────────────────────────────────
+
+  Documenter: {
+    title: 'The Knowledge Keeper',
+    description:
+      'Documentation specialist that creates and maintains comprehensive project documentation',
+    argumentHint: 'Component, API, feature, or area to document',
+    toolRole: 'documenter',
+    sharedBase: 'code-agent-base',
+    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',
+    argumentHint: 'Find files, usages, and context related to: {topic or goal}',
+    toolRole: 'explorer',
+    sharedBase: null,
+    category: 'exploration',
+    skills: [['aikit', '**Always** — AI Kit tool signatures, search, analysis']],
+  },
+
+  // ─── Multi-variant roles ──────────────────────────────────────────────
+
+  Researcher: {
+    title: 'The Context Gatherer',
+    description:
+      'Deep analysis, architecture review, and multi-model decision protocol participant',
+    argumentHint: 'Research question, problem statement, or subsystem to investigate',
+    toolRole: 'researcher',
+    sharedBase: 'researcher-base',
+    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 \u2014 produce C4 diagrams'],
+      ['adr-skill', 'When the research involves a technical decision \u2014 draft an ADR'],
+    ],
+    variants: {
+      Alpha: {
+        description: 'Primary deep research agent — also serves as default Researcher',
+        identity:
+          ', the primary deep research agent. During multi-model decision sessions, you provide deep reasoning and nuanced system design.',
+        bodyAddendum: `## Required Output Section — \`## Depth Analysis\`
+
+Your final report MUST contain a \`## Depth Analysis\` section with:
+- 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
+
+You are the DEFAULT researcher. When the Orchestrator needs breadth + depth, they
+dispatch you alone. Your lens: thorough, evidence-first, exhaustive.`,
+      },
+      Beta: {
+        description:
+          'Research variant — pragmatic analysis with focus on trade-offs and edge cases',
+        identity:
+          ', 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.',
+        bodyAddendum: `## Required Output Section — \`## Failure Modes & Counter-Evidence\`
+
+Your final report MUST contain a \`## Failure Modes & Counter-Evidence\` section with:
+- 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\`
+
+Your lens: pragmatic skepticism. Mark competing claims as \`A\` (Assumed) by default;
+challenge before promoting to \`V\`.`,
+      },
+      Gamma: {
+        description: 'Research variant — broad pattern matching across domains and technologies',
+        identity:
+          ', 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.',
+        bodyAddendum: `## Required Output Section — \`## Cross-Domain Analogies\`
+
+Your final report MUST contain a \`## Cross-Domain Analogies\` section with:
+- 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
+  how it maps to our codebase
+- One "missing pattern we should adopt" recommendation
+
+Your lens: cross-domain pattern matching. Weight \`web_search\` + \`web_fetch\` higher
+than peers. Assume the LLM's training data is stale — verify with fresh searches.`,
+      },
+      Delta: {
+        description: 'Research variant — implementation feasibility and performance implications',
+        identity:
+          ', 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.',
+        bodyAddendum: `## Required Output Section — \`## Implementation Cost & Feasibility\`
+
+Your final report MUST contain a \`## Implementation Cost & Feasibility\` section with:
+- Complexity snapshot: you MUST call \`measure({ path })\` on any file ≥ 50 LOC in the
+  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
+
+Your lens: implementation feasibility. Prefer \`measure\` + \`blast_radius\` + \`analyze_patterns\`
+over abstract reasoning.`,
+      },
+    },
+  },
+
+  'Code-Reviewer': {
+    title: 'The Quality Guardian',
+    description:
+      'Code review specialist analyzing code for quality, security, performance, and maintainability',
+    argumentHint: 'File path, PR, or code to review',
+    toolRole: 'reviewer',
+    sharedBase: 'code-reviewer-base',
+    category: 'review',
+    skills: [
+      ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
+      ['typescript', 'When reviewing TypeScript code — type patterns, best practices'],
+    ],
+    variants: {
+      Alpha: { description: 'Primary code reviewer' },
+      Beta: { description: 'Code reviewer variant — different LLM perspective for dual review' },
+    },
+  },
+
+  'Architect-Reviewer': {
+    title: 'The Structural Guardian',
+    description:
+      'Reviews architecture for pattern adherence, SOLID compliance, dependency direction, and structural integrity',
+    argumentHint: 'Files, PR, or subsystem to architecture-review',
+    toolRole: 'reviewer',
+    sharedBase: 'architect-reviewer-base',
+    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 \u2014 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: { description: 'Primary architecture reviewer' },
+      Beta: {
+        description: 'Architecture reviewer variant — different LLM perspective for dual review',
+      },
+    },
+  },
+};