@vpxa/aikit 0.1.73 → 0.1.75

package/scaffold/definitions/tools.mjs

@@ -1,250 +0,0 @@
-/**
- * Tool lists by agent role category.
- *
- * `kb` — Knowledge-base MCP tools (IDE-agnostic, same across all adapters).
- * `ide` — IDE-native tool permissions, keyed by role. Each IDE adapter
- *          maps these to its own format (e.g., Copilot tool identifiers).
- *
- * When AI Kit adds/removes a tool, update `kb` here — all agents pick it up.
- *
- * NOTE: The copilot adapter currently uses `aikit/*` wildcard instead
- * of listing individual tools. This array is kept as a reference and for future
- * adapters that may need explicit tool lists (e.g., claude-code).
- */
-
-export const AIKIT_TOOLS = [
-  'analyze_dependencies',
-  'analyze_diagram',
-  'analyze_entry_points',
-  'analyze_patterns',
-  'analyze_structure',
-  'analyze_symbols',
-  'audit',
-  'batch',
-  'blast_radius',
-  'brainstorm',
-  'changelog',
-  'check',
-  'checkpoint',
-  'codemod',
-  'compact',
-  'config',
-  'data_transform',
-  'dead_symbols',
-  'delegate',
-  'describe_tool',
-  'diff_parse',
-  'digest',
-  'encode',
-  'env',
-  'eval',
-  'evidence_map',
-  'file_summary',
-  'find',
-  'flow_add',
-  'flow_info',
-  'flow_list',
-  'flow_read_instruction',
-  'flow_remove',
-  'flow_reset',
-  'flow_start',
-  'flow_status',
-  'flow_step',
-  'flow_update',
-  'forge_classify',
-  'forge_ground',
-  'forget',
-  'git_context',
-  'graph',
-  'guide',
-  'health',
-  'http',
-  'lane',
-  'list',
-  'list_tools',
-  'lookup',
-  'measure',
-  'onboard',
-  'parse_output',
-  'present',
-  'process',
-  'produce_knowledge',
-  'queue',
-  'read',
-  'regex_test',
-  'reindex',
-  'remember',
-  'rename',
-  'replay',
-  'restore',
-  'schema_validate',
-  'scope_map',
-  'search',
-  'search_tools',
-  'session_digest',
-  'snippet',
-  'stash',
-  'status',
-  'stratum_card',
-  'symbol',
-  'test_run',
-  'time',
-  'trace',
-  'update',
-  'watch',
-  'web_fetch',
-  'web_search',
-  'workset',
-];
-
-/**
- * IDE-native tool categories by role.
- * These are abstract capability names — each IDE adapter maps them to concrete tool IDs.
- *
- * Categories:
- *   terminal    — run commands
- *   problems    — read diagnostics
- *   readFile    — read file contents
- *   lastCommand — read terminal output
- *   subagent    — invoke other agents
- *   createFile  — create new files
- *   editFiles   — edit existing files
- *   search      — search codebase (code, text, usages, changes)
- *   web         — web fetch, web search, GitHub
- *   todo        — manage task lists
- *   memory      — persistent memory (VS Code)
- *   runCommand  — run VS Code commands
- *   switchAgent — switch to another agent
- *   killTerminal — kill a terminal
- *   createTask  — create and run tasks
- *   terminalSel — read terminal selection
- *   fileSearch  — search by filename
- *   listDir     — list directory
- *   textSearch  — text search
- *   searchSubagent — search via subagent
- */
-export const IDE_CAPABILITIES = {
-  orchestrator: [
-    'memory',
-    'runCommand',
-    'switchAgent',
-    'newWorkspace',
-    'reviewPlan',
-    'killTerminal',
-    'createTask',
-    'terminal',
-    'terminalSel',
-    'lastCommand',
-    'problems',
-    'readFile',
-    'subagent',
-    'createFile',
-    'editFiles',
-    'rename',
-    'createDirectory',
-    'search',
-    'web',
-    'todo',
-    'searchSubagent',
-    'textSearch',
-    'browser',
-    'askQuestions',
-    'resolveMemoryFileUri',
-  ],
-  researcher: [
-    'terminal',
-    'problems',
-    'readFile',
-    'lastCommand',
-    'subagent',
-    'search',
-    'web',
-    'browser',
-  ],
-  reviewer: [
-    'terminal',
-    'problems',
-    'readFile',
-    'lastCommand',
-    'subagent',
-    'search',
-    'web',
-    'browser',
-  ],
-  codeAgent: [
-    'createTask',
-    'terminal',
-    'problems',
-    'readFile',
-    'lastCommand',
-    'subagent',
-    'createFile',
-    'editFiles',
-    'rename',
-    'createDirectory',
-    'search',
-    'todo',
-    'browser',
-  ],
-  debugger: [
-    'terminal',
-    'problems',
-    'readFile',
-    'terminalSel',
-    'lastCommand',
-    'subagent',
-    'createFile',
-    'editFiles',
-    'search',
-    'browser',
-  ],
-  refactor: [
-    'terminal',
-    'problems',
-    'readFile',
-    'lastCommand',
-    'subagent',
-    'createFile',
-    'editFiles',
-    'rename',
-    'createDirectory',
-    'search',
-    'browser',
-  ],
-  explorer: ['problems', 'readFile', 'search', 'fileSearch', 'listDir', 'textSearch', 'browser'],
-  planner: [
-    'terminal',
-    'problems',
-    'readFile',
-    'reviewPlan',
-    'memory',
-    'askQuestions',
-    'resolveMemoryFileUri',
-    'lastCommand',
-    'subagent',
-    'createFile',
-    'editFiles',
-    'rename',
-    'createDirectory',
-    'search',
-    'web',
-    'todo',
-    'searchSubagent',
-    'browser',
-  ],
-  security: ['terminal', 'problems', 'readFile', 'subagent', 'search', 'web', 'browser'],
-  documenter: [
-    'terminal',
-    'problems',
-    'readFile',
-    'lastCommand',
-    'subagent',
-    'createFile',
-    'editFiles',
-    'rename',
-    'createDirectory',
-    'search',
-    'web',
-    'browser',
-  ],
-};

package/scaffold/flows/_epilogue/steps/docs-sync/README.md

@@ -1,120 +0,0 @@
-# Epilogue: Documentation Sync
-
-> **This is a mandatory epilogue step.** It runs automatically after every flow completes to keep project documentation synchronized with code changes.
-
-## Objective
-
-Review the changes made during this flow and update the `docs/` folder using AI Kit analysis tools — never write docs from scratch when a tool can generate the foundation.
-
-## Prerequisites
-
-Load the `docs` skill before proceeding — it contains the full documentation convention, templates, architecture blueprint workflow, and change-to-doc mapping rules.
-
-## Instructions
-
-### 0. Gather Flow Artifacts
-
-Read all artifacts produced during this flow — they contain design decisions, requirements, and verification results that are the most valuable documentation input.
-
-```
-flow_status()                                           # Get artifactsPath
-find({ pattern: "*.md", path: "{{artifacts_path}}" })   # Discover all flow artifacts
-digest({ sources: [                                     # Compress artifacts for context
-  { path: "<found-artifact-1>" },
-  { path: "<found-artifact-2>" },
-  ...
-]})
-```
-
-Map each discovered artifact to documentation actions using the artifact-to-doc mapping from the `docs` skill. Different flows produce different artifacts — read everything `find()` returns and focus on content that contains decisions, requirements, and verification results.
-
-If no artifacts exist, proceed to Step 1 in source-only mode.
-
-### 1. Assess Changes (tool-driven)
-
-```
-git_context({})                                         # What changed in this flow
-blast_radius({ changed_files: ["<changed-files>"] })    # Impact analysis — which modules affected
-```
-
-Use the output to classify changes:
-
-| Change Signal | Documentation Action |
-|---------------|---------------------|
-| New files in `src/` | Potential new component doc |
-| Modified API surface | Update reference docs |
-| New package or module boundary | Update architecture overview |
-| Architecture decision made | Delegate to `adr-skill` |
-| Test-only or config-only changes | Likely skip |
-
-### 2. Apply the Change-to-Doc Mapping
-
-Follow the decision tree from the `docs` skill to determine which documentation actions are needed.
-
-### 3. Bootstrap `docs/` If Needed (full tool-driven workflow)
-
-If `docs/` doesn't exist, run the **Architecture Blueprint Workflow** from the `docs` skill:
-
-```
-# Step 1: Generate content with AI Kit tools
-produce_knowledge({ path: "." })                        # → Foundation for docs/README.md
-analyze_structure({ path: "." })                        # → docs/architecture/overview.md structure
-analyze_diagram({ path: "." })                          # → docs/architecture/ Mermaid diagrams
-analyze_dependencies({ path: "." })                     # → docs/architecture/overview.md deps section
-analyze_entry_points({ path: "." })                     # → docs/reference/api.md foundation
-analyze_patterns({ path: "." })                         # → docs/architecture/overview.md patterns
-
-# Step 2: Create the docs/ tree from tool outputs
-docs/
-├── README.md              ← From produce_knowledge + project context
-├── architecture/
-│   ├── overview.md        ← From analyze_structure + analyze_dependencies + analyze_diagram
-│   └── components/        ← From analyze_symbols per major component
-├── decisions/
-│   └── index.md           ← ADR log (delegate to adr-skill)
-├── guides/
-│   └── testing.md         ← From analyze_patterns test info
-└── reference/
-    └── api.md             ← From analyze_entry_points
-```
-
-Use the Architecture Blueprint sections from the `docs` skill as the template for each document.
-
-### 4. Update Existing Docs (tool-assisted)
-
-When `docs/` already exists:
-
-```
-compact({ path: "docs/architecture/overview.md", query: "section to update" })  # Read target section
-blast_radius({ changed_files: ["<files>"] })                                     # What's affected
-```
-
-- **Don't rewrite** — update the relevant sections of existing docs
-- **Don't duplicate** — if the information is in code comments or READMEs, reference it
-- Use `compact` to read existing doc sections before editing
-- Use `blast_radius` output to determine which sections need updating
-
-### 5. Delegate When Appropriate
-
-- Architecture decisions → `adr-skill` → `docs/decisions/`
-- Architecture diagrams → `c4-architecture` skill → `docs/architecture/`
-- Full architecture refresh → Run the Architecture Blueprint Workflow from `docs` skill
-
-### 6. Update Index
-
-If documents were added, removed, or renamed, update `docs/README.md` to reflect the current structure.
-
-### 7. Skip If Nothing Changed
-
-If the flow's changes don't warrant doc updates (e.g., pure bug fix with no revelations), report:
-- "No documentation updates needed"
-- Reason: (brief explanation)
-
-## Completion Criteria
-
-- [ ] `git_context` + `blast_radius` used to assess changes
-- [ ] Change-to-doc mapping applied from `docs` skill
-- [ ] `docs/` bootstrapped with tool outputs if it didn't exist
-- [ ] Relevant docs created or updated (or skipped with reason)
-- [ ] `docs/README.md` index is current
-- [ ] No placeholder/empty docs created — all content tool-generated or hand-written with purpose

package/scaffold/flows/aikit-advanced/README.md

@@ -1,70 +0,0 @@
-# aikit:advanced — Full Development Flow
-
-Full development flow for **new features, API design, and architecture changes**.
-
-## Steps
-
-| # | Step | Skill | Produces | Requires | Agents |
-|---|------|-------|----------|----------|--------|
-| 1 | **Design Gate** | `steps/design/README.md` | `design-decisions.md` | — | Researcher-Alpha/Beta/Gamma/Delta |
-| 2 | **Specification** | `steps/spec/README.md` | `spec.md` | `design-decisions.md` | Researcher-Alpha |
-| 3 | **Planning** | `steps/plan/README.md` | `plan.md` | `spec.md` | Planner, Explorer |
-| 4 | **Task Breakdown** | `steps/task/README.md` | `tasks.md` | `plan.md` | Planner, Architect-Reviewer-Alpha |
-| 5 | **Execution** | `steps/execute/README.md` | `progress.md` | `tasks.md` | Orchestrator, Implementer, Frontend, Refactor |
-| 6 | **Verification** | `steps/verify/README.md` | `verify-report.md` | `progress.md` | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta, Security |
-
-## How It Works
-
-Each step has a **README.md** file that contains the detailed instructions for the agent(s) executing that step. The Orchestrator reads the README.md via `flow_read_instruction` and delegates work accordingly.
-
-### Step 1: Design Gate
-- Full brainstorming session for new features and architectural changes
-- FORGE classification (`forge_classify`) + grounding (`forge_ground`) for complex tasks
-- Parallel 4-researcher decision protocol for non-trivial technical decisions
-- ADR generation for critical-tier tasks
-- **Mandatory user stop** before proceeding — design decisions must be approved
-- Read `steps/design/README.md` for the full protocol
-
-### Step 2: Specification
-- Elicit requirements from the user, clarify scope
-- Define acceptance criteria and constraints
-- Build on design decisions from the previous step
-
-### Step 3: Planning
-- Deep codebase analysis using `search`, `scope_map`, `trace`, `analyze_*`
-- Design architecture based on spec and design decisions
-- Create comprehensive implementation plan with file-level changes
-
-### Step 4: Task Breakdown
-- Break the plan into ordered, atomic implementation tasks
-- Define dependencies between tasks
-- Identify parallel batches for multi-agent execution
-- Architecture review of the task structure
-
-### Step 5: Execution
-- Orchestrator dispatches agents in parallel batches per the task breakdown
-- Each agent gets a scoped task (1-3 files) with clear acceptance criteria
-- TDD: write tests first, then implement
-- Per-batch review cycle: Code Review (dual) → Arch Review → Security → Evidence Gate
-
-### Step 6: Verification
-- Dual code review (Code-Reviewer-Alpha + Beta)
-- Architecture review (Architect-Reviewer-Alpha + Beta)
-- Security review
-- Run `check({})` + `test_run({})` + `blast_radius({})`
-- `evidence_map({ action: "gate" })` for final quality gate
-
-## Using Skills Inside Steps
-
-When the Orchestrator activates a step:
-
-1. **Read the instruction first** — `flow_read_instruction` returns the README.md for the current step
-2. **Follow step instructions** — the README.md is the primary guide for what to do
-3. **Delegate to listed agents** — each step lists which agents are appropriate
-4. **Produce the required artifact** — the step's `produces` field specifies what file to create in the artifacts directory
-5. **Check dependencies** — the step's `requires` field lists artifacts from previous steps that must exist
-6. **Report status** — agents report `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED` to the Orchestrator
-
-## Artifacts
-
-All artifacts are stored in the run directory under `.flows/{topic}/`. The template variable `{{artifacts_path}}` resolves to the actual path at runtime.

package/scaffold/flows/aikit-advanced/flow.json

@@ -1,69 +0,0 @@
-{
-  "name": "aikit:advanced",
-  "version": "0.1.0",
-  "description": "Full development flow for new features, API design, and architecture changes",
-  "steps": [
-    {
-      "id": "design",
-      "name": "Design Gate",
-      "instruction": "steps/design/README.md",
-      "produces": ["design-decisions.md"],
-      "requires": [],
-      "agents": ["Researcher-Alpha", "Researcher-Beta", "Researcher-Gamma", "Researcher-Delta"],
-      "description": "Full brainstorming, FORGE classification, decision protocol with parallel research. ADR for critical-tier tasks."
-    },
-    {
-      "id": "spec",
-      "name": "Specification",
-      "instruction": "steps/spec/README.md",
-      "produces": ["spec.md"],
-      "requires": ["design-decisions.md"],
-      "agents": ["Researcher-Alpha"],
-      "description": "Elicit requirements, clarify scope, define acceptance criteria"
-    },
-    {
-      "id": "plan",
-      "name": "Planning",
-      "instruction": "steps/plan/README.md",
-      "produces": ["plan.md"],
-      "requires": ["spec.md"],
-      "agents": ["Planner", "Explorer"],
-      "description": "Analyze codebase, design architecture, create implementation plan"
-    },
-    {
-      "id": "task",
-      "name": "Task Breakdown",
-      "instruction": "steps/task/README.md",
-      "produces": ["tasks.md"],
-      "requires": ["plan.md"],
-      "agents": ["Planner", "Architect-Reviewer-Alpha"],
-      "description": "Break plan into ordered implementation tasks with dependencies"
-    },
-    {
-      "id": "execute",
-      "name": "Execution",
-      "instruction": "steps/execute/README.md",
-      "produces": ["progress.md"],
-      "requires": ["tasks.md"],
-      "agents": ["Orchestrator", "Implementer", "Frontend", "Refactor"],
-      "description": "Implement all tasks, write code, write tests"
-    },
-    {
-      "id": "verify",
-      "name": "Verification",
-      "instruction": "steps/verify/README.md",
-      "produces": ["verify-report.md"],
-      "requires": ["progress.md"],
-      "agents": [
-        "Code-Reviewer-Alpha",
-        "Code-Reviewer-Beta",
-        "Architect-Reviewer-Alpha",
-        "Architect-Reviewer-Beta",
-        "Security"
-      ],
-      "description": "Dual code review, architecture review, security review, test validation"
-    }
-  ],
-  "artifacts_dir": ".spec",
-  "install": []
-}

package/scaffold/flows/aikit-advanced/steps/design/README.md

@@ -1,178 +0,0 @@
-# Design Gate — Advanced Flow
-
-Full design gate for new features, API design, and architecture changes. Runs brainstorming, decision protocol, and FORGE classification before specification begins.
-
-## When This Step Runs
-
-This is the **first step** of the `aikit:advanced` flow. It runs before specification.
-
-## Instructions
-
-### 1. Task Classification
-
-Classify the task:
-
-| Category | Indicators | Action |
-|----------|-----------|--------|
-| **Bug fix** | Error, regression, "fix" — wrong flow, should use `aikit:basic` | → Note mismatch, still run Quick Design |
-| **New feature** | New behavior, new API, new component | → Run **Full Design** below |
-| **Architecture change** | Restructure, migration, new pattern, cross-cutting | → Run **Full Design** with architecture focus |
-
-### 2. FORGE Classification
-
-Run `forge_classify({ task: "<task description>", files: [<relevant files>] })` to determine the complexity tier.
-
-| Tier | Meaning | Design Depth |
-|------|---------|-------------|
-| **Floor** | Low risk, well-understood | Quick brainstorm, 1-2 decisions |
-| **Standard** | Moderate complexity | Full brainstorm, parallel research, decision protocol |
-| **Critical** | High risk, contract/security implications | Deep brainstorm, 4-researcher parallel review, ADR required |
-
-### 3. Brainstorming Session
-
-Load the `brainstorming` skill and conduct a structured brainstorming session:
-
-1. **Intent Discovery** — What is the user trying to achieve? What problem does this solve?
-2. **Constraint Mapping** — Technical constraints, time constraints, compatibility requirements
-3. **Approach Exploration** — Generate 2-4 possible approaches
-4. **Trade-off Analysis** — Compare approaches on: complexity, maintainability, performance, risk
-
-For **Critical** tier tasks, also explore:
-- Security implications
-- Backward compatibility
-- Migration path
-- Rollback strategy
-
-### 4. Decision Protocol (Standard & Critical tiers)
-
-When technical decisions need resolution:
-
-1. **Identify decisions** — List each decision point with 2+ viable options
-2. **Parallel research** — Delegate to Researcher agents (2 for Standard, 4 for Critical):
-   - Researcher-Alpha: Deep analysis of primary approach
-   - Researcher-Beta: Trade-offs and edge cases of alternatives
-   - Researcher-Gamma: Cross-domain patterns and precedents
-   - Researcher-Delta: Feasibility and performance implications
-3. **Synthesize** — Combine researcher findings into a recommendation per decision
-4. **ADR** (Critical tier) — Load `adr-skill` and create an Architecture Decision Record
-
-### 5. FORGE Ground (Standard & Critical tiers)
-
-Run `forge_ground({ task, root_path: "." })` to:
-- Scope the affected files and modules
-- Identify unknowns and risks
-- Load existing constraints and conventions
-
-**Auto-upgrade check**: If `forge_ground` reveals contract-type unknowns or security concerns not caught by initial `forge_classify`, recommend tier upgrade.
-
-### 6. Write `{{artifacts_path}}/design-decisions.md` to disk
-
-**You MUST create this file on disk** using `create_file` or equivalent — do not just present content in chat.
-
-```markdown
-## Design Decisions
-
-### FORGE Assessment
-- **Tier**: {Floor | Standard | Critical}
-- **Rationale**: {why this tier}
-- **Auto-upgrade**: {yes/no — if yes, explain}
-
-### Task Summary
-- **Goal**: {what we're building}
-- **Problem**: {what problem this solves}
-- **Users affected**: {who is impacted}
-
-### Approach
-- **Chosen approach**: {description}
-- **Alternatives considered**: {list with reasons for rejection}
-
-### Key Decisions
-| # | Decision | Choice | Rationale |
-|---|----------|--------|-----------|
-| 1 | {decision} | {choice} | {why} |
-
-### Constraints
-- {constraint 1}
-- {constraint 2}
-
-### Risks
-| Risk | Likelihood | Impact | Mitigation |
-|------|-----------|--------|------------|
-| {risk} | {L/M/H} | {L/M/H} | {mitigation} |
-
-### Open Questions
-- {question 1}
-- {question 2}
-```
-
-### 7. Present to User
-
-Use `present({ format: "html" })` (or `format: "browser"` in CLI mode) to show:
-- Design decisions summary
-- FORGE tier and rationale
-- Key trade-offs
-- Open questions requiring user input
-
-**🛑 MANDATORY STOP** — Wait for user approval of design decisions before proceeding.
-
-### 8. Report to Orchestrator
-
-After user approves:
-- `DONE` — design decisions approved, ready for specification
-- `DONE_WITH_CONCERNS` — approved with caveats (list them)
-- `NEEDS_CONTEXT` — user raised questions that need more research
-
-**Do NOT call `flow_step`** — let the Orchestrator advance the flow.
-
-## Outputs
-
-Write `{{artifacts_path}}/design-decisions.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat. This file is a prerequisite for the next step.
-
-## Produces
-
-- `{{artifacts_path}}/design-decisions.md` — FORGE tier, approach, key decisions, constraints, risks
-
-## Agents
-
-- `Researcher-Alpha` — Deep analysis of primary approach
-- `Researcher-Beta` — Trade-offs and edge cases
-- `Researcher-Gamma` — Cross-domain patterns
-- `Researcher-Delta` — Feasibility and performance
-
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| `aikit` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
-| `present` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| `multi-agents-development` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| `brainstorming` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-| `c4-architecture` | C4 model diagrams showing system structure changes | When visualizing proposed architecture |
-| `adr-skill` | Architecture Decision Records for non-trivial decisions | Critical tier — document architecture decisions |
-
-### Presentation Rules
-- Use `present` for **any output** that benefits from rich rendering — not limited to dashboards
-- Assessments, reports, comparisons, reviews, status boards → `present({ format: "html" })`
-- Tables, charts, progress tracking, code review findings → always present
-- Artifact content and summaries → present with structured layout
-- Only use plain text for brief confirmations and simple questions
-
-## Completion Criteria
-
-- [ ] `{{artifacts_path}}/design-decisions.md` written to disk (NOT just presented in chat)
-- [ ] FORGE tier determined and documented
-- [ ] Brainstorming session completed (for Standard+ tier)
-- [ ] Key design decisions documented with rationale
-- [ ] User approval received (🛑 MANDATORY STOP)
-
-## Knowledge Capture
-
-Before completing this step, persist important findings using `remember()`:
-
-- **Design decisions**: Chosen approach and alternatives considered with trade-offs
-- **Architecture patterns**: New patterns introduced or existing patterns that must be followed
-- **Constraints discovered**: Technical limitations, compatibility requirements, or performance boundaries
-
-**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.