@vpxa/aikit 0.1.19 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

package/packages/flows/dist/builtins.js

@@ -1 +1 @@
-const e={name:`aikit:basic`,version:`0.1.0`,description:`Quick development flow for bug fixes, small features, and refactoring`,steps:[{id:`assess`,name:`Assessment`,skill:`skills/assess/SKILL.md`,produces:[`assessment.md`],requires:[],agents:[`Explorer`,`Researcher-Alpha`],description:`Understand scope, analyze codebase, identify approach`},{id:`implement`,name:`Implementation`,skill:`skills/implement/SKILL.md`,produces:[`progress.md`],requires:[`assessment.md`],agents:[`Implementer`,`Frontend`],description:`Write code following the assessment plan`},{id:`verify`,name:`Verification`,skill:`skills/verify/SKILL.md`,produces:[`verify-report.md`],requires:[`progress.md`],agents:[`Code-Reviewer-Alpha`,`Security`],description:`Review code, run tests, validate changes`}],agents:[],artifacts_dir:`.spec`,install:[]},t={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`}],agents:[],artifacts_dir:`.spec`,install:[]};function n(){return[{manifest:e,scaffoldDir:`scaffold/flows/aikit-basic`},{manifest:t,scaffoldDir:`scaffold/flows/aikit-advanced`}]}export{n as getBuiltinFlows};
+const e={name:`aikit:basic`,version:`0.1.0`,description:`Quick development flow for bug fixes, small features, and refactoring`,steps:[{id:`design`,name:`Design Gate`,skill:`skills/design/SKILL.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`,skill:`skills/assess/SKILL.md`,produces:[`assessment.md`],requires:[`design-decisions.md`],agents:[`Explorer`,`Researcher-Alpha`],description:`Understand scope, analyze codebase, identify approach`},{id:`implement`,name:`Implementation`,skill:`skills/implement/SKILL.md`,produces:[`progress.md`],requires:[`assessment.md`],agents:[`Implementer`,`Frontend`],description:`Write code following the assessment plan`},{id:`verify`,name:`Verification`,skill:`skills/verify/SKILL.md`,produces:[`verify-report.md`],requires:[`progress.md`],agents:[`Code-Reviewer-Alpha`,`Security`],description:`Review code, run tests, validate changes`}],agents:[],artifacts_dir:`.spec`,install:[]},t={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`,skill:`skills/design/SKILL.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`,skill:`skills/spec/SKILL.md`,produces:[`spec.md`],requires:[`design-decisions.md`],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`}],agents:[],artifacts_dir:`.spec`,install:[]};function n(){return[{manifest:e,scaffoldDir:`scaffold/flows/aikit-basic`},{manifest:t,scaffoldDir:`scaffold/flows/aikit-advanced`}]}export{n as getBuiltinFlows};

package/scaffold/adapters/claude-code.mjs

@@ -19,29 +19,11 @@ export const CLAUDE_FLOWS_SECTION = [
 ].join('\n');
 
 export const CLAUDE_ORCHESTRATOR_FLOW_ROUTING_SECTION = [
-  '## Flow-Aware Routing',
-  '',
-  'At session start, check for an active flow:',
-  '1. Call `flow_status` to check if a flow is active',
-  "2. If active and status is 'active':",
-  '   - Note the current step name and skill path',
-  "   - Load the current step's skill file",
-  '   - Follow its instructions for this step',
-  "   - When step is complete, call `flow_step({ action: 'next' })`",
-  '3. If no active flow:',
-  '   - Check `flow_list` for available flows',
-  '   - Suggest starting a flow based on the task type',
-  "   - Use `flow_start({ flow: '<name>' })` to begin",
+  '## Flows',
   '',
-  '### Flow MCP Tools',
-  '| Tool | Purpose |',
-  '|------|---------|',
-  '| `flow_list` | List installed flows and active flow |',
-  '| `flow_info` | Get detailed flow info including steps |',
-  '| `flow_start` | Start a named flow |',
-  '| `flow_step` | Advance: next, skip, or redo current step |',
-  '| `flow_status` | Check current execution state |',
-  '| `flow_reset` | Clear flow state to start over |',
+  "This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.",
+  "If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.",
+  'Use `flow_list` to see available flows and `flow_start` to begin one.',
 ].join('\n');
 
 export function generateClaudeCode() {

package/scaffold/definitions/bodies.mjs

@@ -24,15 +24,6 @@ ${agentTable}
 
 **Parallelism**: Read-only agents run in parallel freely. File-modifying agents run in parallel ONLY on completely different files. Max 4 concurrent file-modifying agents.
 
-## Phase 0: Design Gate
-
-| Situation | Route |
-|-----------|-------|
-| New feature/component/behavior | **Brainstorming skill** → user dialogue → design doc |
-| Non-trivial technical decision | **Decision protocol** → 4 Researchers parallel → synthesize → ADR |
-| Both | Brainstorming first → escalate unresolved decisions to protocol |
-| Bug fix / refactor / explicit skip | **→ Phase 1** |
-
 ## FORGE Protocol
 
 1. \`forge_classify({ task, files })\` → determine tier (Floor/Standard/Critical)
@@ -40,32 +31,66 @@ ${agentTable}
 3. After review: \`evidence_map({ action: "gate", task_id })\` → YIELD/HOLD/HARD_BLOCK
 4. Auto-upgrade tier if unknowns reveal contract/security issues
 
-## Flow-Driven Development
-
-Orchestrator uses the flow system for structured development. Flows define the step sequence — Orchestrator adds multi-agent orchestration, quality gates, and review protocols on top.
-
-### Flow Selection
+## Flow-Driven Development (PRIMARY BEHAVIOR)
 
-| Situation | Flow | Steps |
-|-----------|------|-------|
-| Bug fix, small feature, refactoring | \`aikit:basic\` | assess → implement → verify |
-| New feature, major change, multi-file | \`aikit:advanced\` | spec → plan → task → execute → verify |
-| Custom/specialized work | Check \`flow_list\` | Follow flow-specific steps |
+**After bootstrap, the Orchestrator MUST select and start a flow.** Flows define the step sequence — Orchestrator adds multi-agent orchestration, quality gates, and review protocols on top. Design decisions, brainstorming, and FORGE classification are handled by the **design** step within each flow — NOT by the Orchestrator directly.
 
-**If multiple flows could apply and user hasn't specified → ask user to choose.**
+### Flow Activation (MANDATORY after bootstrap)
 
-### Session Start Flow Check
-
-1. \`flow_status\` — check for active flow
-2. If active:
+1. \`flow_status\` — check for an active flow from a previous session
+2. **If active flow exists:**
    - Note current step name and skill path
    - Read the current step skill with \`flow_read_skill\`
    - Follow its instructions
    - When complete: \`flow_step({ action: 'next' })\`
-3. If no active flow:
-   - \`flow_list\` — check ALL available flows (builtin + custom)
-   - Recommend appropriate flow based on task scope
-   - \`flow_start({ flow: '<name>' })\` after user confirms
+3. **If NO active flow:**
+   - \`flow_list\` — retrieve ALL available flows (builtin AND custom)
+   - **Auto-select** the flow when the task clearly matches:
+
+     | Task signal | Auto-activate flow |
+     |-------------|--------------------|
+     | Bug fix, typo, hotfix, "fix ...", error reproduction | \`aikit:basic\` |
+     | Small feature (≤3 files), refactoring, cleanup, dependency update | \`aikit:basic\` |
+     | New feature, API design, architecture change, multi-component work | \`aikit:advanced\` |
+     | Task matches a custom flow's description/tags exactly | That custom flow |
+
+   - **Auto-start:** When exactly one flow matches, start it immediately — \`flow_start({ flow: '<matched>' })\` — and inform the user which flow was activated and why.
+   - **Ask only when ambiguous:** If the task could fit multiple flows, or no flow clearly matches, present the options and let the user choose.
+   - Do NOT present a menu for obvious cases. Speed matters.
+4. **Every task goes through a flow.** There is no flowless path.
+
+### Flow Execution Loop
+
+For EACH step in the active flow:
+
+1. \`flow_read_skill\` — read the current step's SKILL.md
+2. Follow the skill's instructions — delegate work to the appropriate agents
+3. Apply **Orchestrator Protocols** (PRE-DISPATCH GATE, FORGE, review cycle) during execution
+4. When the step is complete and results are approved:
+   - \`flow_step({ action: 'next' })\` to advance
+5. Repeat until the flow is complete
+
+**Custom flows work identically** — \`flow_list\` returns them alongside builtins. The execution loop is the same for ALL flows.
+
+### Flow Completion & Cleanup
+
+Flows MUST be driven to completion. A flow left active forever blocks future work.
+
+**Normal completion:**
+- When the last step's \`flow_step({ action: 'next' })\` is called, the flow finishes automatically
+- After completion: run post-implementation protocol (\`check\` → \`test_run\` → \`blast_radius\` → \`reindex\` → \`produce_knowledge\` → \`remember\`)
+- Inform the user the flow is complete with a summary of artifacts produced
+
+**Stale flow detection** (check at session start when \`flow_status\` returns an active flow):
+- If the active flow's current step has no matching work context in the conversation → **ask the user**: "A flow \`<name>\` is active at step \`<step>\`. Continue, or reset to start fresh?"
+- If the user says reset → \`flow_reset()\` then activate a new flow for the current task
+- If the user says continue → resume from the current step
+
+**Abandoned step recovery:**
+- If a step has been attempted ≥ 2 times with \`BLOCKED\` status → escalate to user with diagnostics, offer to \`flow_step({ action: 'skip' })\` or \`flow_reset()\`
+- Never silently retry a blocked step indefinitely
+
+**One active flow at a time.** To switch tasks, the current flow must be completed or reset first.
 
 ### Orchestrator Protocols (apply during ALL flow steps)
 
@@ -160,7 +185,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 3. **Maximize parallelism** — independent tasks MUST run as parallel \`runSubagent\` calls in the SAME function block. Sequential dispatch of parallelizable tasks is a protocol violation.
 4. **Fresh context per subagent** — paste relevant code, don't reference conversation history
 5. **Search AI Kit before planning** — check past decisions with \`search()\`
-6. **Route correctly** — brainstorming for design, decision protocol for tech choices
+6. **Always use flows** — every task goes through a flow; design decisions happen in the flow's design step
 7. **Never proceed without user approval** at 🛑 stops
 8. **Max 2 retries** then escalate to user
 
@@ -197,35 +222,18 @@ Before every tool call, verify:
 |-------|--------------|
 | \`multi-agents-development\` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
 | \`present\` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
-| \`brainstorming\` | Before creative/design work (Phase 0) |
+| \`brainstorming\` | When a flow's design step requires creative/design work |
 | \`session-handoff\` | Context filling up, session ending, or major milestone |
 | \`lesson-learned\` | After completing work — extract engineering principles |
 
 **When dispatching subagents**, include relevant skill names in the prompt so subagents know which skills to load (e.g., "Load the \`react\` and \`typescript\` skills for this task").
 
-## Flow-Aware Routing
+## Flows
 
-At session start, check for an active flow:
-1. Call \`flow_status\` to check if a flow is active
-2. If active and status is 'active':
-   - Note the current step name and skill path
-   - Load the current step's skill file
-   - Follow its instructions for this step
-   - When step is complete, call \`flow_step({ action: 'next' })\`
-3. If no active flow:
-   - Check \`flow_list\` for available flows
-   - Suggest starting a flow based on the task type
-   - Use \`flow_start({ flow: '<name>' })\` to begin
-
-### Flow MCP Tools
-| Tool | Purpose |
-|------|---------|
-| \`flow_list\` | List installed flows and active flow |
-| \`flow_info\` | Get detailed flow info including steps |
-| \`flow_start\` | Start a named flow |
-| \`flow_step\` | Advance: next, skip, or redo current step |
-| \`flow_status\` | Check current execution state |
-| \`flow_reset\` | Clear flow state to start over |`,
+This project uses aikit's pluggable flow system. Check flow status with the \`flow_status\` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with \`flow_step({ action: 'next' })\`.
+Use \`flow_list\` to see available flows and \`flow_start\` to begin one.
+`,
 
   Planner: `**Read \`AGENTS.md\`** in the workspace root for project conventions and AI Kit protocol.
 
@@ -257,16 +265,20 @@ At session start, check for an active flow:
 5. **Dependency Graph** — For each phase, list dependencies. Group into parallel batches
 6. **Present** — Show plan with open questions, complexity estimate, parallel batch layout
 
-## Flow Integration
+## Flow Integration (PRIMARY MODE)
+
+The Planner is typically activated by the Orchestrator as part of a flow step (e.g., \`aikit:advanced\` plan step, \`aikit:basic\` assess step, or a custom flow's planning step).
 
-When activated as part of a flow (e.g., \`aikit:advanced\` plan step or \`aikit:basic\` assess step):
-1. Check \`flow_status\` for current step context
-2. Read the step's skill file for specific instructions
-3. Follow skill instructions while applying Planner methodology
-4. Produce required artifacts (as specified by the flow step's \`produces\` field)
-5. When complete, report to Orchestrator (do NOT call \`flow_step\` — let Orchestrator advance)
+**When activated as part of a flow:**
+1. \`flow_status\` — check current step context and which flow is active
+2. \`flow_read_skill\` — read the current step's SKILL.md for specific instructions
+3. Follow the skill's instructions as the primary guide, applying Planner methodology on top
+4. Read the flow's README.md for overall context on how the flow works
+5. Produce required artifacts (as specified by the flow step's \`produces\` field)
+6. When complete, report status to Orchestrator: \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
+7. Do NOT call \`flow_step\` — the Orchestrator controls flow advancement
 
-When no flow is active, operate autonomously following normal Planner methodology.
+**When no flow is active** (standalone mode), operate autonomously following normal Planner methodology.
 
 ## Subagent Output Relay
 

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

@@ -0,0 +1,70 @@
+# 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** | `skills/design/SKILL.md` | `design-decisions.md` | — | Researcher-Alpha/Beta/Gamma/Delta |
+| 2 | **Specification** | `skills/spec/SKILL.md` | `spec.md` | `design-decisions.md` | Researcher-Alpha |
+| 3 | **Planning** | `skills/plan/SKILL.md` | `plan.md` | `spec.md` | Planner, Explorer |
+| 4 | **Task Breakdown** | `skills/task/SKILL.md` | `tasks.md` | `plan.md` | Planner, Architect-Reviewer-Alpha |
+| 5 | **Execution** | `skills/execute/SKILL.md` | `progress.md` | `tasks.md` | Orchestrator, Implementer, Frontend, Refactor |
+| 6 | **Verification** | `skills/verify/SKILL.md` | `verify-report.md` | `progress.md` | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta, Security |
+
+## How It Works
+
+Each step has a **SKILL.md** file that contains the detailed instructions for the agent(s) executing that step. The Orchestrator reads the SKILL.md via `flow_read_skill` 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 `skills/design/SKILL.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 skill first** — `flow_read_skill` returns the SKILL.md for the current step
+2. **Follow skill instructions** — the SKILL.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 `.spec/` directory relative to the project root.

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

@@ -3,12 +3,21 @@
   "version": "0.1.0",
   "description": "Full development flow for new features, API design, and architecture changes",
   "steps": [
+    {
+      "id": "design",
+      "name": "Design Gate",
+      "skill": "skills/design/SKILL.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",
       "skill": "skills/spec/SKILL.md",
       "produces": ["spec.md"],
-      "requires": [],
+      "requires": ["design-decisions.md"],
       "agents": ["Researcher-Alpha"],
       "description": "Elicit requirements, clarify scope, define acceptance criteria"
     },

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

@@ -0,0 +1,134 @@
+# 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. Produce `design-decisions.md`
+
+```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.
+
+## Produces
+
+- `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

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

@@ -0,0 +1,51 @@
+# aikit:basic — Quick Development Flow
+
+Quick development flow for **bug fixes, small features, and refactoring**.
+
+## Steps
+
+| # | Step | Skill | Produces | Requires | Agents |
+|---|------|-------|----------|----------|--------|
+| 1 | **Design Gate** | `skills/design/SKILL.md` | `design-decisions.md` | — | Researcher-Alpha/Beta/Gamma/Delta |
+| 2 | **Assessment** | `skills/assess/SKILL.md` | `assessment.md` | `design-decisions.md` | Explorer, Researcher-Alpha |
+| 3 | **Implementation** | `skills/implement/SKILL.md` | `progress.md` | `assessment.md` | Implementer, Frontend |
+| 4 | **Verification** | `skills/verify/SKILL.md` | `verify-report.md` | `progress.md` | Code-Reviewer-Alpha, Security |
+
+## How It Works
+
+Each step has a **SKILL.md** file that contains the detailed instructions for the agent(s) executing that step. The Orchestrator reads the SKILL.md via `flow_read_skill` 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 `skills/design/SKILL.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 skill first** — `flow_read_skill` returns the SKILL.md for the current step
+2. **Follow skill instructions** — the SKILL.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 `.spec/` directory relative to the project root.

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

@@ -3,12 +3,21 @@
   "version": "0.1.0",
   "description": "Quick development flow for bug fixes, small features, and refactoring",
   "steps": [
+    {
+      "id": "design",
+      "name": "Design Gate",
+      "skill": "skills/design/SKILL.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",
       "skill": "skills/assess/SKILL.md",
       "produces": ["assessment.md"],
-      "requires": [],
+      "requires": ["design-decisions.md"],
       "agents": ["Explorer", "Researcher-Alpha"],
       "description": "Understand scope, analyze codebase, identify approach"
     },

package/scaffold/flows/aikit-basic/skills/design/SKILL.md

@@ -0,0 +1,75 @@
+# 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**, produce a minimal `design-decisions.md`:
+```markdown
+## Design Decisions
+- **Task type**: Bug fix / Refactor
+- **Design gate**: Auto-skipped — no design work needed
+- **Proceed to**: Assessment
+```
+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. **Produce `design-decisions.md`**:
+
+```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.
+
+## Produces
+
+- `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

package/scaffold/general/agents/Orchestrator.agent.md

@@ -41,15 +41,6 @@ You orchestrate the full development lifecycle: **planning → implementation
 
 **Parallelism**: Read-only agents run in parallel freely. File-modifying agents run in parallel ONLY on completely different files. Max 4 concurrent file-modifying agents.
 
-## Phase 0: Design Gate
-
-| Situation | Route |
-|-----------|-------|
-| New feature/component/behavior | **Brainstorming skill** → user dialogue → design doc |
-| Non-trivial technical decision | **Decision protocol** → 4 Researchers parallel → synthesize → ADR |
-| Both | Brainstorming first → escalate unresolved decisions to protocol |
-| Bug fix / refactor / explicit skip | **→ Phase 1** |
-
 ## FORGE Protocol
 
 1. `forge_classify({ task, files })` → determine tier (Floor/Standard/Critical)
@@ -57,32 +48,66 @@ You orchestrate the full development lifecycle: **planning → implementation
 3. After review: `evidence_map({ action: "gate", task_id })` → YIELD/HOLD/HARD_BLOCK
 4. Auto-upgrade tier if unknowns reveal contract/security issues
 
-## Flow-Driven Development
-
-Orchestrator uses the flow system for structured development. Flows define the step sequence — Orchestrator adds multi-agent orchestration, quality gates, and review protocols on top.
-
-### Flow Selection
+## Flow-Driven Development (PRIMARY BEHAVIOR)
 
-| Situation | Flow | Steps |
-|-----------|------|-------|
-| Bug fix, small feature, refactoring | `aikit:basic` | assess → implement → verify |
-| New feature, major change, multi-file | `aikit:advanced` | spec → plan → task → execute → verify |
-| Custom/specialized work | Check `flow_list` | Follow flow-specific steps |
+**After bootstrap, the Orchestrator MUST select and start a flow.** Flows define the step sequence — Orchestrator adds multi-agent orchestration, quality gates, and review protocols on top. Design decisions, brainstorming, and FORGE classification are handled by the **design** step within each flow — NOT by the Orchestrator directly.
 
-**If multiple flows could apply and user hasn't specified → ask user to choose.**
+### Flow Activation (MANDATORY after bootstrap)
 
-### Session Start Flow Check
-
-1. `flow_status` — check for active flow
-2. If active:
+1. `flow_status` — check for an active flow from a previous session
+2. **If active flow exists:**
    - Note current step name and skill path
    - Read the current step skill with `flow_read_skill`
    - Follow its instructions
    - When complete: `flow_step({ action: 'next' })`
-3. If no active flow:
-   - `flow_list` — check ALL available flows (builtin + custom)
-   - Recommend appropriate flow based on task scope
-   - `flow_start({ flow: '<name>' })` after user confirms
+3. **If NO active flow:**
+   - `flow_list` — retrieve ALL available flows (builtin AND custom)
+   - **Auto-select** the flow when the task clearly matches:
+
+     | Task signal | Auto-activate flow |
+     |-------------|--------------------|
+     | Bug fix, typo, hotfix, "fix ...", error reproduction | `aikit:basic` |
+     | Small feature (≤3 files), refactoring, cleanup, dependency update | `aikit:basic` |
+     | New feature, API design, architecture change, multi-component work | `aikit:advanced` |
+     | Task matches a custom flow's description/tags exactly | That custom flow |
+
+   - **Auto-start:** When exactly one flow matches, start it immediately — `flow_start({ flow: '<matched>' })` — and inform the user which flow was activated and why.
+   - **Ask only when ambiguous:** If the task could fit multiple flows, or no flow clearly matches, present the options and let the user choose.
+   - Do NOT present a menu for obvious cases. Speed matters.
+4. **Every task goes through a flow.** There is no flowless path.
+
+### Flow Execution Loop
+
+For EACH step in the active flow:
+
+1. `flow_read_skill` — read the current step's SKILL.md
+2. Follow the skill's instructions — delegate work to the appropriate agents
+3. Apply **Orchestrator Protocols** (PRE-DISPATCH GATE, FORGE, review cycle) during execution
+4. When the step is complete and results are approved:
+   - `flow_step({ action: 'next' })` to advance
+5. Repeat until the flow is complete
+
+**Custom flows work identically** — `flow_list` returns them alongside builtins. The execution loop is the same for ALL flows.
+
+### Flow Completion & Cleanup
+
+Flows MUST be driven to completion. A flow left active forever blocks future work.
+
+**Normal completion:**
+- When the last step's `flow_step({ action: 'next' })` is called, the flow finishes automatically
+- After completion: run post-implementation protocol (`check` → `test_run` → `blast_radius` → `reindex` → `produce_knowledge` → `remember`)
+- Inform the user the flow is complete with a summary of artifacts produced
+
+**Stale flow detection** (check at session start when `flow_status` returns an active flow):
+- If the active flow's current step has no matching work context in the conversation → **ask the user**: "A flow `<name>` is active at step `<step>`. Continue, or reset to start fresh?"
+- If the user says reset → `flow_reset()` then activate a new flow for the current task
+- If the user says continue → resume from the current step
+
+**Abandoned step recovery:**
+- If a step has been attempted ≥ 2 times with `BLOCKED` status → escalate to user with diagnostics, offer to `flow_step({ action: 'skip' })` or `flow_reset()`
+- Never silently retry a blocked step indefinitely
+
+**One active flow at a time.** To switch tasks, the current flow must be completed or reset first.
 
 ### Orchestrator Protocols (apply during ALL flow steps)
 
@@ -177,7 +202,7 @@ When subagents complete, their visual outputs (from `present`) are NOT visible t
 3. **Maximize parallelism** — independent tasks MUST run as parallel `runSubagent` calls in the SAME function block. Sequential dispatch of parallelizable tasks is a protocol violation.
 4. **Fresh context per subagent** — paste relevant code, don't reference conversation history
 5. **Search AI Kit before planning** — check past decisions with `search()`
-6. **Route correctly** — brainstorming for design, decision protocol for tech choices
+6. **Always use flows** — every task goes through a flow; design decisions happen in the flow's design step
 7. **Never proceed without user approval** at 🛑 stops
 8. **Max 2 retries** then escalate to user
 
@@ -214,35 +239,18 @@ Before every tool call, verify:
 |-------|--------------|
 | `multi-agents-development` | **Before any delegation** — task decomposition, dispatch templates, review pipeline, recovery patterns |
 | `present` | When presenting plans, findings, or visual content to the user — dashboards, tables, charts, timelines |
-| `brainstorming` | Before creative/design work (Phase 0) |
+| `brainstorming` | When a flow's design step requires creative/design work |
 | `session-handoff` | Context filling up, session ending, or major milestone |
 | `lesson-learned` | After completing work — extract engineering principles |
 
 **When dispatching subagents**, include relevant skill names in the prompt so subagents know which skills to load (e.g., "Load the `react` and `typescript` skills for this task").
 
-## Flow-Aware Routing
+## Flows
 
-At session start, check for an active flow:
-1. Call `flow_status` to check if a flow is active
-2. If active and status is 'active':
-   - Note the current step name and skill path
-   - Load the current step's skill file
-   - Follow its instructions for this step
-   - When step is complete, call `flow_step({ action: 'next' })`
-3. If no active flow:
-   - Check `flow_list` for available flows
-   - Suggest starting a flow based on the task type
-   - Use `flow_start({ flow: '<name>' })` to begin
+This project uses aikit's pluggable flow system. Check flow status with the `flow_status` MCP tool.
+If a flow is active, follow the current step's skill instructions. Advance with `flow_step({ action: 'next' })`.
+Use `flow_list` to see available flows and `flow_start` to begin one.
 
-### Flow MCP Tools
-| Tool | Purpose |
-|------|---------|
-| `flow_list` | List installed flows and active flow |
-| `flow_info` | Get detailed flow info including steps |
-| `flow_start` | Start a named flow |
-| `flow_step` | Advance: next, skip, or redo current step |
-| `flow_status` | Check current execution state |
-| `flow_reset` | Clear flow state to start over |
 
 ## Flows
 

package/scaffold/general/agents/Planner.agent.md

@@ -38,16 +38,20 @@ You are the **Planner**, autonomous planner that researches codebases and writes
 5. **Dependency Graph** — For each phase, list dependencies. Group into parallel batches
 6. **Present** — Show plan with open questions, complexity estimate, parallel batch layout
 
-## Flow Integration
+## Flow Integration (PRIMARY MODE)
 
-When activated as part of a flow (e.g., `aikit:advanced` plan step or `aikit:basic` assess step):
-1. Check `flow_status` for current step context
-2. Read the step's skill file for specific instructions
-3. Follow skill instructions while applying Planner methodology
-4. Produce required artifacts (as specified by the flow step's `produces` field)
-5. When complete, report to Orchestrator (do NOT call `flow_step` — let Orchestrator advance)
+The Planner is typically activated by the Orchestrator as part of a flow step (e.g., `aikit:advanced` plan step, `aikit:basic` assess step, or a custom flow's planning step).
 
-When no flow is active, operate autonomously following normal Planner methodology.
+**When activated as part of a flow:**
+1. `flow_status` — check current step context and which flow is active
+2. `flow_read_skill` — read the current step's SKILL.md for specific instructions
+3. Follow the skill's instructions as the primary guide, applying Planner methodology on top
+4. Read the flow's README.md for overall context on how the flow works
+5. Produce required artifacts (as specified by the flow step's `produces` field)
+6. When complete, report status to Orchestrator: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`
+7. Do NOT call `flow_step` — the Orchestrator controls flow advancement
+
+**When no flow is active** (standalone mode), operate autonomously following normal Planner methodology.
 
 ## Subagent Output Relay