@vpxa/aikit 0.1.1

package/scaffold/definitions/tools.mjs

@@ -0,0 +1,229 @@
+/**
+ * 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 KB 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',
+  'data_transform',
+  'dead_symbols',
+  'delegate',
+  'diff_parse',
+  'digest',
+  'encode',
+  'env',
+  'eval',
+  'evidence_map',
+  'file_summary',
+  'find',
+  'forge_classify',
+  'forge_ground',
+  'forget',
+  'git_context',
+  'graph',
+  'guide',
+  'health',
+  'http',
+  'lane',
+  'list',
+  'lookup',
+  'measure',
+  'onboard',
+  'parse_output',
+  'present',
+  'process',
+  'produce_knowledge',
+  'queue',
+  'read',
+  'regex_test',
+  'reindex',
+  'remember',
+  'rename',
+  'replay',
+  'restore',
+  'schema_validate',
+  'scope_map',
+  'search',
+  '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',
+    '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',
+    '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/aikit-advanced/flow.json

@@ -0,0 +1,60 @@
+{
+  "name": "aikit:advanced",
+  "version": "0.1.0",
+  "description": "Full development flow for new features, API design, and architecture changes",
+  "steps": [
+    {
+      "id": "spec",
+      "name": "Specification",
+      "skill": "skills/spec/SKILL.md",
+      "produces": ["spec.md"],
+      "requires": [],
+      "agents": ["Researcher-Alpha"],
+      "description": "Elicit requirements, clarify scope, define acceptance criteria"
+    },
+    {
+      "id": "plan",
+      "name": "Planning",
+      "skill": "skills/plan/SKILL.md",
+      "produces": ["plan.md"],
+      "requires": ["spec.md"],
+      "agents": ["Planner", "Explorer"],
+      "description": "Analyze codebase, design architecture, create implementation plan"
+    },
+    {
+      "id": "task",
+      "name": "Task Breakdown",
+      "skill": "skills/task/SKILL.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",
+      "skill": "skills/execute/SKILL.md",
+      "produces": ["progress.md"],
+      "requires": ["tasks.md"],
+      "agents": ["Orchestrator", "Implementer", "Frontend", "Refactor"],
+      "description": "Implement all tasks, write code, write tests"
+    },
+    {
+      "id": "verify",
+      "name": "Verification",
+      "skill": "skills/verify/SKILL.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/skills/execute/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: execute
+description: Implement all tasks from the task breakdown, dispatching agents in parallel where possible.
+---
+
+# Execution
+
+## Purpose
+
+Execute all tasks from the breakdown, dispatching implementation agents in batches for maximum parallelism while maintaining correctness.
+
+## Inputs
+
+- `.spec/<slug>/tasks.md` — the atomic task list with dependencies and agent assignments
+
+## Process
+
+1. **Load tasks** — Read task graph, dependencies, and parallelism map
+2. **Execute by batch** — For each batch in the parallelism map:
+   a. Dispatch assigned agents in parallel (different files = safe parallelism)
+   b. Each agent receives: task scope, affected files, acceptance criteria, relevant code context via `compact()`/`digest()`
+   c. Wait for all agents in batch to complete
+   d. Run `check({})` + `test_run({})` after each batch
+   e. Fix any failures before proceeding to next batch
+3. **Track progress** — Update task checkboxes as each completes
+4. **Handle failures** — If an agent reports `BLOCKED` or `NEEDS_CONTEXT`:
+   - Max 2 retries per task with refined context
+   - If still blocked, escalate to user
+5. **Final validation** — After all batches: `check({})` + `test_run({})` must pass
+
+## Outputs
+
+Produce `.spec/<slug>/progress.md` with:
+
+```markdown
+# Execution Progress: <feature title>
+
+## Task Status
+- [x] T1.1: <description> — DONE
+- [x] T1.2: <description> — DONE
+- [x] T2.1: <description> — DONE
+- [ ] T2.2: <description> — IN PROGRESS
+...
+
+## Changes Made
+| File | Change | Task |
+|------|--------|------|
+| <file> | <description> | T1.1 |
+| ... | ... | ... |
+
+## Tests Added/Modified
+<list of test files and what they cover>
+
+## Validation
+- check: PASS/FAIL
+- test_run: PASS/FAIL (<N> passed, <M> failed)
+
+## Deviations
+<any changes from the task plan and why>
+
+## Blocked Items
+<items that needed user intervention, if any>
+```
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| **Orchestrator** | Coordinates batch execution, handles failures and retries |
+| **Implementer** | Primary code writer for backend, logic, and infrastructure tasks |
+| **Frontend** | UI/UX implementation for React components, styling, responsive design |
+| **Refactor** | Code cleanup, restructuring, and pattern alignment tasks |
+
+**Parallelism rules**:
+- Read-only agents: unlimited parallelism
+- File-modifying agents: parallel ONLY on completely different files
+- Max 4 concurrent file-modifying agents
+
+## 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 |
+
+### 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
+
+### Orchestrator Dispatch Protocol
+
+Follow the `multi-agents-development` skill patterns for dispatch:
+
+1. **Independence Check** before parallelizing:
+   - Same files? → sequential
+   - Shared mutable state? → sequential
+   - Execution-order dependent? → sequential
+   - Need shared new types? → define contract first, then parallel
+   - All clear? → **parallel dispatch**
+
+2. **Subagent Context Template** (each dispatch includes):
+   - **Scope**: exact files + boundary (do NOT touch)
+   - **Goal**: acceptance criteria, testable
+   - **Arch Context**: actual code snippets via `compact()`/`digest()`
+   - **Constraints**: patterns, conventions, anti-patterns
+   - **Self-Review**: checklist before declaring DONE
+
+3. **Status Protocol**: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`
+4. **Max 2 retries** per task — then escalate to user
+
+## Completion Criteria
+
+- [ ] All tasks marked completed
+- [ ] `check({})` passes
+- [ ] `test_run({})` passes
+- [ ] No blocked items remaining
+- [ ] `.spec/<slug>/progress.md` written

package/scaffold/flows/aikit-advanced/skills/plan/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: plan
+description: Analyze the codebase, design the architecture, and create a detailed implementation plan.
+---
+
+# Planning
+
+## Purpose
+
+Translate the specification into a concrete, phased implementation plan with architecture decisions, file-level scope, and dependency ordering.
+
+## Inputs
+
+- `.spec/<slug>/spec.md` — the validated specification
+
+## Process
+
+1. **Load spec** — Read and internalize all requirements and acceptance criteria
+2. **Codebase analysis** — `scope_map({ task: "<feature>" })` to identify affected subsystems
+3. **Deep dive** — `file_summary()` + `compact()` on each affected module
+4. **Architecture design** — Decide on:
+   - Where new code lives (new files vs extensions)
+   - API surface changes
+   - Data model changes
+   - Integration patterns
+5. **ADR for non-trivial decisions** — Use `adr-skill` for decisions that affect future development
+6. **Phase decomposition** — Break work into 3–10 ordered phases, each independently testable
+7. **Dependency graph** — Map which phases depend on others and which can parallelize
+8. **Risk assessment** — Identify implementation risks per phase
+
+## Outputs
+
+Produce `.spec/<slug>/plan.md` with:
+
+```markdown
+# Implementation Plan: <feature title>
+
+## Architecture Overview
+<high-level design with rationale>
+
+## Affected Modules
+| Module | Changes | Risk |
+|--------|---------|------|
+| <module> | <what changes> | low/medium/high |
+
+## Phases
+### Phase 1: <name>
+- **Files**: <list>
+- **Changes**: <description>
+- **Tests**: <what to test>
+- **Depends on**: none
+- **Parallelizable with**: Phase 2
+
+### Phase 2: <name>
+...
+
+## Architecture Decisions
+- ADR-<N>: <title> — <chosen option and rationale>
+
+## Risks
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| <risk> | low/medium/high | <impact> | <mitigation> |
+```
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| **Planner** | Creates comprehensive TDD implementation plans with phase decomposition |
+| **Explorer** | Rapid codebase exploration for discovery of affected files and dependencies |
+
+Use Explorer for initial breadth (file discovery, dependency tracing), then Planner for depth (phase design, ordering).
+
+## 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 |
+
+### 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
+
+- [ ] All spec requirements have corresponding plan phases
+- [ ] Each phase has explicit file scope and test strategy
+- [ ] Architecture decisions documented with rationale
+- [ ] Dependency graph has no circular dependencies
+- [ ] Risks identified with mitigations
+- [ ] `.spec/<slug>/plan.md` written

package/scaffold/flows/aikit-advanced/skills/spec/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: spec
+description: Elicit requirements, clarify scope, and define acceptance criteria through structured dialogue.
+---
+
+# Specification
+
+## Purpose
+
+Transform a vague or broad feature request into a precise, testable specification through requirements elicitation and stakeholder dialogue.
+
+## Inputs
+
+- User's feature request, issue, or idea
+- Codebase context (accessed via aikit MCP tools)
+
+## Process
+
+1. **Understand intent** — Parse what the user wants and why
+2. **Search for context** — `search()` for related prior decisions, existing patterns, and similar features
+3. **Elicit requirements** — Ask structured questions to clarify:
+   - **Functional**: What must the system do?
+   - **Non-functional**: Performance, security, accessibility constraints
+   - **Scope boundaries**: What is explicitly out of scope?
+   - **Acceptance criteria**: How do we know it's done?
+4. **Score clarity** — Use the `requirements-clarity` skill to score 0–100. Iterate questions until ≥ 90.
+5. **Draft specification** — Write formal spec with all requirements resolved
+
+## Outputs
+
+Produce `.spec/<slug>/spec.md` with:
+
+```markdown
+# Specification: <feature title>
+
+## Summary
+<1-2 sentence description>
+
+## Motivation
+<why this feature is needed>
+
+## Functional Requirements
+1. <requirement with acceptance criterion>
+2. ...
+
+## Non-Functional Requirements
+- Performance: <constraints>
+- Security: <constraints>
+- Accessibility: <constraints>
+
+## Scope
+### In Scope
+- <item>
+
+### Out of Scope
+- <item>
+
+## Acceptance Criteria
+- [ ] <testable criterion>
+- [ ] ...
+
+## Open Questions
+<none — all resolved during elicitation>
+
+## Clarity Score: <N>/100
+```
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| **Researcher-Alpha** | Deep analysis of existing codebase patterns, prior decisions, and technical constraints |
+
+Use the `brainstorming` skill for creative/design exploration before formalizing requirements. Use `requirements-clarity` skill to score and iterate until the spec is unambiguous.
+
+## 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 |
+
+### 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
+
+- [ ] All functional requirements have acceptance criteria
+- [ ] Scope boundaries are explicit
+- [ ] Requirements clarity score ≥ 90
+- [ ] No open questions remain
+- [ ] `.spec/<slug>/spec.md` written