@vpxa/aikit 0.1.73 → 0.1.75

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

@@ -1,51 +0,0 @@
-# aikit:basic — Quick Development Flow
-
-Quick development flow for **bug fixes, small features, and refactoring**.
-
-## Steps
-
-| # | Step | Skill | Produces | Requires | Agents |
-|---|------|-------|----------|----------|--------|
-| 1 | **Design Gate** | `steps/design/README.md` | `design-decisions.md` | — | Researcher-Alpha/Beta/Gamma/Delta |
-| 2 | **Assessment** | `steps/assess/README.md` | `assessment.md` | `design-decisions.md` | Explorer, Researcher-Alpha |
-| 3 | **Implementation** | `steps/implement/README.md` | `progress.md` | `assessment.md` | Implementer, Frontend |
-| 4 | **Verification** | `steps/verify/README.md` | `verify-report.md` | `progress.md` | Code-Reviewer-Alpha, 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
-- **Auto-skips** for bug fixes and refactors (produces a minimal `design-decisions.md` noting it was skipped)
-- For small features: runs quick brainstorming, FORGE classification, and optional decision protocol
-- Read `steps/design/README.md` for the full decision tree
-
-### Step 2: Assessment
-- Explore the codebase to understand scope and impact
-- Use `search`, `scope_map`, `file_summary`, `compact` to gather context
-- Identify the approach and produce `assessment.md`
-
-### Step 3: Implementation
-- Write code following the assessment plan
-- The Orchestrator dispatches Implementer/Frontend agents with specific file scopes
-- Follow TDD practices where applicable
-
-### Step 4: Verification
-- Code review, test execution, security check
-- Run `check({})` + `test_run({})` + `blast_radius({})`
-- Produce `verify-report.md` with findings
-
-## 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-basic/flow.json

@@ -1,45 +0,0 @@
-{
-  "name": "aikit:basic",
-  "version": "0.1.0",
-  "description": "Quick development flow for bug fixes, small features, and refactoring",
-  "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": "Evaluate task type, run brainstorming for features, FORGE classification. Auto-skips for bug fixes and refactors."
-    },
-    {
-      "id": "assess",
-      "name": "Assessment",
-      "instruction": "steps/assess/README.md",
-      "produces": ["assessment.md"],
-      "requires": ["design-decisions.md"],
-      "agents": ["Explorer", "Researcher-Alpha"],
-      "description": "Understand scope, analyze codebase, identify approach"
-    },
-    {
-      "id": "implement",
-      "name": "Implementation",
-      "instruction": "steps/implement/README.md",
-      "produces": ["progress.md"],
-      "requires": ["assessment.md"],
-      "agents": ["Implementer", "Frontend"],
-      "description": "Write code following the assessment plan"
-    },
-    {
-      "id": "verify",
-      "name": "Verification",
-      "instruction": "steps/verify/README.md",
-      "produces": ["verify-report.md"],
-      "requires": ["progress.md"],
-      "agents": ["Code-Reviewer-Alpha", "Security"],
-      "description": "Review code, run tests, validate changes"
-    }
-  ],
-  "artifacts_dir": ".spec",
-  "install": []
-}

package/scaffold/flows/aikit-basic/steps/assess/README.md

@@ -1,109 +0,0 @@
----
-name: assess
-description: Understand scope, analyze the codebase, and identify the implementation approach.
----
-
-# Assessment
-
-## Purpose
-
-Analyze the task requirements and codebase to produce a clear, actionable assessment before any code changes begin.
-
-## Inputs
-
-- User's task description or issue reference
-- Codebase (accessed via aikit MCP tools)
-
-## Prerequisites Check
-
-Before executing this step, verify:
-
-- [ ] Design decisions documented (from the design step)
-- [ ] FORGE classification determined (tier assigned)
-- [ ] If brainstorming was done, session outcomes are recorded
-
-If any prerequisites are missing or incomplete:
-1. Inform the Orchestrator with specifics about what's missing
-2. Recommend `flow_step({ action: 'redo' })` on the **design** step
-3. Do NOT proceed with partial inputs — quality degrades downstream
-
-## Process
-
-1. **Parse the goal** — Extract what needs to change, success criteria, and constraints
-2. **Search for prior work** — `search({ query: "<task keywords>" })` to check for existing decisions or related code
-3. **Map affected scope** — `scope_map({ task: "<description>" })` to identify files and modules involved
-4. **Analyze structure** — `file_summary()` on each affected file; `compact()` for deeper sections
-5. **Identify risks** — Note dependencies, breaking change potential, test coverage gaps
-6. **Draft approach** — Outline the implementation strategy in 3–7 steps
-
-## Outputs
-
-Write `{{artifacts_path}}/assessment.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
-
-Template:
-
-```markdown
-# Assessment: <task title>
-
-## Goal
-<what needs to happen>
-
-## Affected Files
-<list of files with brief reason>
-
-## Approach
-<numbered implementation steps>
-
-## Risks
-<potential issues and mitigations>
-
-## Open Questions
-<anything that needs clarification before proceeding>
-```
-
-## Agents
-
-| Agent | Role |
-|-------|------|
-| **Explorer** | Rapid file discovery, dependency tracing, structural context |
-| **Researcher-Alpha** | Deep analysis of complex logic, prior decisions, architectural implications |
-
-Use Explorer first for breadth, then Researcher-Alpha for depth on complex areas.
-
-## 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 architecture diagrams — system context, container, component, deployment views | When visualizing system structure during assessment |
-| `adr-skill` | Architecture Decision Records — create, review, maintain ADRs | When assessment reveals non-trivial design 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
-
-- [ ] All affected files identified
-- [ ] Implementation approach is concrete (not vague)
-- [ ] Risks documented with mitigations
-- [ ] No unresolved open questions that block implementation
-- [ ] `{{artifacts_path}}/assessment.md` written
-
-## Knowledge Capture
-
-Before completing this step, persist important findings using `remember()`:
-
-- **Codebase discoveries**: File locations, architecture patterns, or dependency relationships found during assessment
-- **Problem diagnosis**: Root cause analysis, contributing factors, and affected components
-- **Scope decisions**: What's in scope, what's explicitly excluded, and why
-
-**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.

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

@@ -1,116 +0,0 @@
-# Design Gate — Basic Flow
-
-Lightweight design gate for bug fixes, small features, and refactoring. Evaluates the task type and determines whether design work is needed before proceeding.
-
-## When This Step Runs
-
-This is the **first step** of the `aikit:basic` flow. It runs before assessment.
-
-## Instructions
-
-### 1. Task Classification
-
-Classify the task into one of these categories:
-
-| Category | Indicators | Action |
-|----------|-----------|--------|
-| **Bug fix** | Error reports, stack traces, regression, "fix", "broken" | → **Auto-skip** to next step |
-| **Refactor** | Code cleanup, rename, restructure, no behavior change | → **Auto-skip** to next step |
-| **Small feature** | New behavior, new endpoint, new component, UI change | → Run **Quick Design** below |
-
-**If the task is a bug fix or refactor**, write `{{artifacts_path}}/design-decisions.md` to disk:
-```markdown
-## Design Decisions
-- **Task type**: Bug fix / Refactor
-- **Design gate**: Auto-skipped — no design work needed
-- **Proceed to**: Assessment
-```
-**You MUST create this file on disk** at the exact `{{artifacts_path}}/design-decisions.md` path — do not just present the content in chat.
-Then report `DONE` to the Orchestrator so the flow advances.
-
-### 2. Quick Design (Small Features Only)
-
-For small features that need minimal design:
-
-1. **FORGE Classify** — Run `forge_classify({ task: "<task description>", files: [<relevant files>] })` to determine complexity tier
-2. **Brainstorming** (if tier ≥ Standard) — Load the `brainstorming` skill and run a focused brainstorming session:
-   - What is the user trying to achieve?
-   - What are the constraints?
-   - What is the simplest approach?
-3. **Decision Protocol** (if technical decisions exist) — Delegate to 2-4 Researcher agents in parallel:
-   - Each researcher evaluates a different approach
-   - Synthesize findings into a recommendation
-4. **Write `{{artifacts_path}}/design-decisions.md`** to disk:
-
-```markdown
-## Design Decisions
-
-### FORGE Assessment
-- **Tier**: {Floor | Standard | Critical}
-- **Rationale**: {why this tier}
-
-### Task Summary
-- **Goal**: {what we're building}
-- **Approach**: {chosen approach}
-- **Key decisions**: {list}
-
-### Constraints
-- {constraint 1}
-- {constraint 2}
-```
-
-### 3. Report to Orchestrator
-
-When complete, report status:
-- `DONE` — design decisions captured, ready for assessment
-- `DONE_WITH_CONCERNS` — design captured but open questions remain (list them)
-
-**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` — Task classification, FORGE tier, key design decisions
-
-## Agents
-
-- `Researcher-Alpha`, `Researcher-Beta`, `Researcher-Gamma`, `Researcher-Delta` — for parallel research during decision protocol
-
-## 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 architecture diagrams — system context, container, component, deployment views | When visualizing system structure during design |
-| `adr-skill` | Architecture Decision Records — create, review, maintain ADRs | When making non-trivial design or technology 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 (for small features)
-- [ ] Key design decisions documented
-
-## 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.

package/scaffold/flows/aikit-basic/steps/implement/README.md

@@ -1,131 +0,0 @@
----
-name: implement
-description: Write code following the assessment plan, using TDD practices where applicable.
----
-
-# Implementation
-
-## Purpose
-
-Execute the implementation plan from the assessment, writing production code and tests.
-
-## Inputs
-
-- `{{artifacts_path}}/assessment.md` — the approach, affected files, and risks
-
-## Prerequisites Check
-
-Before executing this step, verify:
-
-- [ ] Assessment complete and scope approved (from the assess step)
-- [ ] Files-to-modify list is clear and bounded
-- [ ] `check({})` baseline captured (know what currently passes)
-
-If any prerequisites are missing or incomplete:
-1. Inform the Orchestrator with specifics about what's missing
-2. Recommend `flow_step({ action: 'redo' })` on the **assess** step
-3. Do NOT proceed with partial inputs — quality degrades downstream
-
-## Process
-
-1. **Read assessment** — Load `{{artifacts_path}}/assessment.md` and internalize the approach
-2. **Set up tests first** — Where applicable, write failing tests that define success
-3. **Implement changes** — Follow the approach steps sequentially
-   - One logical change per commit-worthy chunk
-   - Stay within the assessed file scope — do not expand without re-assessment
-4. **Run validation** — `check({})` for type/lint errors, `test_run({})` for test results
-5. **Fix issues** — Iterate until `check` and `test_run` pass (max 3 rounds)
-6. **Document progress** — Write progress artifact with what was done and any deviations
-
-## Outputs
-
-Write `{{artifacts_path}}/progress.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
-
-Template:
-
-```markdown
-# Implementation Progress: <task title>
-
-## Changes Made
-<list of files changed with brief description>
-
-## Tests
-<tests added or modified>
-
-## Deviations from Assessment
-<any changes to the original plan and why>
-
-## Validation
-- check: PASS/FAIL
-- test_run: PASS/FAIL (<N> passed, <M> failed)
-
-## Notes
-<anything the reviewer should know>
-```
-
-## Agents
-
-| Agent | Role |
-|-------|------|
-| **Implementer** | Primary code writer — follows TDD, writes production code and tests |
-| **Frontend** | UI/UX specialist — use when changes involve React components, styling, or responsive design |
-
-Dispatch Implementer for backend/logic changes, Frontend for UI changes. Both can run in parallel if working on different files.
-
-## 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 |
-| `session-handoff` | Context preservation for session transfers | When implementation is long-running and context may fill up |
-
-### 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 assessment steps implemented
-- [ ] `check({})` passes (no type/lint errors)
-- [ ] `test_run({})` passes (no test failures)
-- [ ] No files modified outside assessed scope
-- [ ] `{{artifacts_path}}/progress.md` written
-
-## Knowledge Capture
-
-Before completing this step, persist important findings using `remember()`:
-
-- **Implementation decisions**: Why specific approaches were chosen over alternatives
-- **Patterns established**: New conventions or patterns that future code should follow
-- **Gotchas encountered**: Edge cases, workarounds, or non-obvious behaviors discovered during implementation
-
-**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.

package/scaffold/flows/aikit-basic/steps/verify/README.md

@@ -1,123 +0,0 @@
----
-name: verify
-description: Review code changes, run tests, validate correctness and quality.
----
-
-# Verification
-
-## Purpose
-
-Validate that the implementation meets the original requirements, passes all quality gates, and introduces no regressions.
-
-## Inputs
-
-- `{{artifacts_path}}/assessment.md` — original requirements and approach
-- `{{artifacts_path}}/progress.md` — what was implemented and any deviations
-
-## Prerequisites Check
-
-Before executing this step, verify:
-
-- [ ] Implementation complete (from the implement step)
-- [ ] `check({})` + `test_run({})` pass at baseline
-- [ ] Changed files list is available for blast radius analysis
-
-If any prerequisites are missing or incomplete:
-1. Inform the Orchestrator with specifics about what's missing
-2. Recommend `flow_step({ action: 'redo' })` on the **implement** step
-3. Do NOT proceed with partial inputs — quality degrades downstream
-
-## Process
-
-1. **Load context** — Read assessment and progress artifacts
-2. **Code review** — Review all changed files for:
-   - Correctness against requirements
-   - Code quality and adherence to project conventions
-   - Error handling and edge cases
-   - No unnecessary changes (scope creep)
-3. **Run quality gates** — `check({})` + `test_run({})` must pass
-4. **Blast radius** — `blast_radius({ changed_files: [...] })` to assess impact
-5. **Security scan** — Check for OWASP Top 10 issues in changed code
-6. **Write report** — Document findings with PASS/FAIL verdict
-
-## Outputs
-
-Write `{{artifacts_path}}/verify-report.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
-
-Template:
-
-```markdown
-# Verification Report: <task title>
-
-## Verdict: PASS | FAIL
-
-## Quality Gates
-- check: PASS/FAIL
-- test_run: PASS/FAIL (<N> passed, <M> failed)
-- blast_radius: <summary of impact>
-
-## Code Review Findings
-<issues found, if any, with severity>
-
-## Security
-<any security concerns>
-
-## Recommendation
-<APPROVE for commit / REQUEST CHANGES with specific items>
-```
-
-## Agents
-
-| Agent | Role |
-|-------|------|
-| **Code-Reviewer-Alpha** | Primary code reviewer — correctness, quality, conventions |
-| **Security** | Security specialist — vulnerability analysis, OWASP compliance |
-
-Run both in parallel — they review different aspects of the same changes.
-
-## 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 |
-| `lesson-learned` | Extract engineering lessons from completed work via git history | After verification completes — capture principles from what was built |
-| `session-handoff` | Context preservation for session transfers | When verification is the final step and session context should be saved |
-
-### 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
-
-### FORGE Quality Gate
-
-After all reviews complete:
-1. `evidence_map({ action: "gate", task_id: "<slug>" })` → returns YIELD/HOLD/HARD_BLOCK
-2. YIELD → approved, proceed to commit
-3. HOLD → minor issues, fix then re-gate (max 3 rounds)
-4. HARD_BLOCK → critical issues, escalate to user
-
-## Completion Criteria
-
-- [ ] `check({})` passes
-- [ ] `test_run({})` passes
-- [ ] Code review complete with no blocking issues
-- [ ] Security review complete
-- [ ] Blast radius assessed
-- [ ] `{{artifacts_path}}/verify-report.md` written with clear PASS/FAIL verdict
-
-## Knowledge Capture
-
-Before completing this step, persist important findings using `remember()`:
-
-- **Test coverage gaps**: Areas that couldn't be fully tested and why
-- **Quality findings**: Issues found during verification and their resolutions
-- **Session checkpoint**: Summarize what was accomplished, decisions made, and any remaining work
-
-**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.