@vpxa/aikit 0.1.73 → 0.1.75

package/scaffold/definitions/agents.mjs

@@ -1,266 +0,0 @@
-/**
- * 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',
-      },
-    },
-  },
-};

package/scaffold/definitions/hooks.mjs

@@ -1,43 +0,0 @@
-/**
- * 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

@@ -1,84 +0,0 @@
-/**
- * Centralized model assignments — THE SINGLE FILE to update when models change.
- *
- * Keys are agent names (stable, model-agnostic).
- * COPILOT_MODELS keeps the full fallback list in Copilot format.
- * CLAUDE_MODELS maps each agent to its primary model as a single plain string.
- *
- * Naming convention for variants: {Role}-Alpha, {Role}-Beta, {Role}-Gamma, {Role}-Delta
- * These are abstract labels — the actual model behind each is defined HERE.
- *
- * NOTE (Experimental): VS Code supports a model array syntax (e.g. [model1, model2])
- * for agent files, but it requires an experiment flag to be enabled. Until the flag
- * is generally available, adapters should emit only the first (primary) model as a
- * plain string. The full fallback arrays are retained here so adapters can switch to
- * array output when the flag is GA.
- */
-
-export const COPILOT_MODELS = {
-  // ─── Single-role agents ───────────────────────────────────────────────
-  Orchestrator: ['Claude Opus 4.6 (copilot)', 'GPT-5.4 (copilot)', 'Auto (copilot)'],
-  Planner: ['Claude Opus 4.6 (copilot)', 'GPT-5.4 (copilot)', 'Auto (copilot)'],
-  Implementer: [
-    'GPT-5.4 (copilot)',
-    'Gemini 3.1 Pro (Preview) (copilot)',
-    'GPT-5.3-Codex (copilot)',
-    'Auto (copilot)',
-  ],
-  Frontend: [
-    'Gemini 3.1 Pro (Preview) (copilot)',
-    'GPT-5.4 (copilot)',
-    'GPT-5.3-Codex (copilot)',
-    'Auto (copilot)',
-  ],
-  Debugger: [
-    'Claude Opus 4.6 (copilot)',
-    'GPT-5.4 (copilot)',
-    'GPT-5.3-Codex (copilot)',
-    'Auto (copilot)',
-  ],
-  Refactor: ['GPT-5.4 (copilot)', 'GPT-5.3-Codex (copilot)', 'Auto (copilot)'],
-  Security: ['Claude Opus 4.6 (copilot)', 'GPT-5.4 (copilot)', 'Auto (copilot)'],
-  Documenter: ['GPT-5.4 (copilot)', 'Gemini 3.1 Pro (Preview) (copilot)', 'Auto (copilot)'],
-  Explorer: ['Gemini 3 Flash (Preview) (copilot)', 'Claude Haiku 4.5 (copilot)', 'Auto (copilot)'],
-
-  // ─── Researcher variants (4 models for multi-model decision protocol) ────────────
-  'Researcher-Alpha': ['Claude Opus 4.6 (copilot)', 'Auto (copilot)'],
-  'Researcher-Beta': ['Claude Sonnet 4.6 (copilot)', 'Auto (copilot)'],
-  'Researcher-Gamma': ['GPT-5.4 (copilot)', 'Auto (copilot)'],
-  'Researcher-Delta': ['Gemini 3.1 Pro (Preview) (copilot)', 'Auto (copilot)'],
-
-  // ─── Code-Reviewer variants (2 models for dual review) ───────────────
-  'Code-Reviewer-Alpha': ['GPT-5.4 (copilot)', 'Auto (copilot)'],
-  'Code-Reviewer-Beta': ['Claude Opus 4.6 (copilot)', 'Auto (copilot)'],
-
-  // ─── Architect-Reviewer variants (2 models for dual review) ──────────
-  'Architect-Reviewer-Alpha': ['GPT-5.4 (copilot)', 'Auto (copilot)'],
-  'Architect-Reviewer-Beta': ['Claude Opus 4.6 (copilot)', 'Auto (copilot)'],
-};
-
-export const CLAUDE_MODELS = Object.fromEntries(
-  Object.entries(COPILOT_MODELS).map(([agentName, models]) => {
-    const primaryModel = Array.isArray(models) ? models[0] : models;
-    return [agentName, primaryModel?.replace(/ \(copilot\)$/, '') || 'Auto'];
-  }),
-);
-
-/**
- * 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

@@ -1,147 +0,0 @@
-/**
- * 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: 'AI Kit 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,
-    sidecars: ['scaffold/general/skills/brainstorming/spec-document-reviewer-prompt.md'],
-  },
-
-  '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',
-    ],
-  },
-
-  'adr-skill': {
-    description:
-      'Architecture Decision Records — create, maintain, and review ADRs for significant technical decisions',
-    source: 'scaffold/general/skills/adr-skill/SKILL.md',
-    required: true,
-    sidecars: [
-      'scaffold/general/skills/adr-skill/assets/templates/adr-madr.md',
-      'scaffold/general/skills/adr-skill/assets/templates/adr-readme.md',
-      'scaffold/general/skills/adr-skill/assets/templates/adr-simple.md',
-      'scaffold/general/skills/adr-skill/references/adr-conventions.md',
-      'scaffold/general/skills/adr-skill/references/examples.md',
-      'scaffold/general/skills/adr-skill/references/review-checklist.md',
-      'scaffold/general/skills/adr-skill/references/template-variants.md',
-      'scaffold/general/skills/adr-skill/scripts/bootstrap_adr.js',
-      'scaffold/general/skills/adr-skill/scripts/new_adr.js',
-      'scaffold/general/skills/adr-skill/scripts/set_adr_status.js',
-    ],
-  },
-
-  'c4-architecture': {
-    description:
-      'C4 model architecture diagrams using Mermaid — system context, container, component, and deployment views',
-    source: 'scaffold/general/skills/c4-architecture/SKILL.md',
-    required: true,
-    sidecars: [
-      'scaffold/general/skills/c4-architecture/references/advanced-patterns.md',
-      'scaffold/general/skills/c4-architecture/references/c4-syntax.md',
-      'scaffold/general/skills/c4-architecture/references/common-mistakes.md',
-    ],
-  },
-
-  'frontend-design': {
-    description:
-      'Frontend design system — visual design thinking, typography, color, layout, motion, accessibility, and anti-pattern detection',
-    source: 'scaffold/general/skills/frontend-design/SKILL.md',
-    required: false,
-  },
-
-  'lesson-learned': {
-    description: 'Extract engineering lessons from recent code changes via git history analysis',
-    source: 'scaffold/general/skills/lesson-learned/SKILL.md',
-    required: true,
-    sidecars: [
-      'scaffold/general/skills/lesson-learned/references/anti-patterns.md',
-      'scaffold/general/skills/lesson-learned/references/se-principles.md',
-    ],
-  },
-
-  present: {
-    description:
-      'Rich interactive dashboards, charts, tables, timelines, and data visualizations via the present MCP tool',
-    source: 'scaffold/general/skills/present/SKILL.md',
-    required: true,
-  },
-
-  react: {
-    description:
-      'React development patterns — component architecture, React 19 APIs, Server Components, TypeScript integration',
-    source: 'scaffold/general/skills/react/SKILL.md',
-    required: false,
-  },
-
-  'requirements-clarity': {
-    description:
-      'Clarify ambiguous requirements through focused dialogue — score 0-100 until ≥90 before implementation',
-    source: 'scaffold/general/skills/requirements-clarity/SKILL.md',
-    required: true,
-  },
-
-  'session-handoff': {
-    description:
-      'Comprehensive handoff documents for seamless AI agent session transfers and context preservation',
-    source: 'scaffold/general/skills/session-handoff/SKILL.md',
-    required: true,
-    sidecars: [
-      'scaffold/general/skills/session-handoff/references/handoff-template.md',
-      'scaffold/general/skills/session-handoff/references/resume-checklist.md',
-      'scaffold/general/skills/session-handoff/scripts/check_staleness.js',
-      'scaffold/general/skills/session-handoff/scripts/create_handoff.js',
-      'scaffold/general/skills/session-handoff/scripts/list_handoffs.js',
-      'scaffold/general/skills/session-handoff/scripts/validate_handoff.js',
-    ],
-  },
-
-  typescript: {
-    description:
-      'TypeScript development patterns — type system, compiler config, advanced types, async patterns, module organization',
-    source: 'scaffold/general/skills/typescript/SKILL.md',
-    required: false,
-  },
-  docs: {
-    description:
-      'Living documentation management — Diátaxis framework, docs/ convention, staleness detection, integration with adr-skill and c4-architecture',
-    source: 'scaffold/general/skills/docs/SKILL.md',
-    required: true,
-  },
-
-  'repo-access': {
-    description:
-      'Progressive repository access recovery for private and enterprise git repos — strategy ladder from HTTPS to SSH to CLI OAuth to PAT to local clone',
-    source: 'scaffold/general/skills/repo-access/SKILL.md',
-    required: true,
-    sidecars: [
-      'scaffold/general/skills/repo-access/references/platform-matrix.md',
-      'scaffold/general/skills/repo-access/references/error-patterns.md',
-    ],
-  },
-};