@vpxa/aikit 0.1.19 → 0.1.21

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** | `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 `.spec/` directory relative to the project root.

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

@@ -3,19 +3,28 @@
   "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",
-      "skill": "skills/spec/SKILL.md",
+      "instruction": "steps/spec/README.md",
       "produces": ["spec.md"],
-      "requires": [],
+      "requires": ["design-decisions.md"],
       "agents": ["Researcher-Alpha"],
       "description": "Elicit requirements, clarify scope, define acceptance criteria"
     },
     {
       "id": "plan",
       "name": "Planning",
-      "skill": "skills/plan/SKILL.md",
+      "instruction": "steps/plan/README.md",
       "produces": ["plan.md"],
       "requires": ["spec.md"],
       "agents": ["Planner", "Explorer"],
@@ -24,7 +33,7 @@
     {
       "id": "task",
       "name": "Task Breakdown",
-      "skill": "skills/task/SKILL.md",
+      "instruction": "steps/task/README.md",
       "produces": ["tasks.md"],
       "requires": ["plan.md"],
       "agents": ["Planner", "Architect-Reviewer-Alpha"],
@@ -33,7 +42,7 @@
     {
       "id": "execute",
       "name": "Execution",
-      "skill": "skills/execute/SKILL.md",
+      "instruction": "steps/execute/README.md",
       "produces": ["progress.md"],
       "requires": ["tasks.md"],
       "agents": ["Orchestrator", "Implementer", "Frontend", "Refactor"],
@@ -42,7 +51,7 @@
     {
       "id": "verify",
       "name": "Verification",
-      "skill": "skills/verify/SKILL.md",
+      "instruction": "steps/verify/README.md",
       "produces": ["verify-report.md"],
       "requires": ["progress.md"],
       "agents": [

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

@@ -0,0 +1,164 @@
+# 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
+
+## 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
+
+## 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-advanced/{skills/execute/SKILL.md → steps/execute/README.md}

@@ -5,6 +5,14 @@ description: Implement all tasks from the task breakdown, dispatching agents in
 
 # Execution
 
+## Prerequisites Check
+
+Before starting this step, verify:
+- [ ] Task breakdown approved with valid task graph
+- [ ] `.spec/<slug>/tasks.md` exists with defined batches and dependencies
+
+If prerequisites are NOT met -> **backtrack to task step** (`flow_step({ action: 'redo' })` on previous step)
+
 ## Purpose
 
 Execute all tasks from the breakdown, dispatching implementation agents in batches for maximum parallelism while maintaining correctness.
@@ -86,6 +94,7 @@ Load these skills BEFORE executing this step:
 | `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 long-running execution phases | When execution spans multiple sessions or context is filling |
 
 ### Presentation Rules
 - Use `present` for **any output** that benefits from rich rendering — not limited to dashboards
@@ -122,3 +131,13 @@ Follow the `multi-agents-development` skill patterns for dispatch:
 - [ ] `test_run({})` passes
 - [ ] No blocked items remaining
 - [ ] `.spec/<slug>/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 execution
+
+**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.

package/scaffold/flows/aikit-advanced/{skills/plan/SKILL.md → steps/plan/README.md}

@@ -5,6 +5,14 @@ description: Analyze the codebase, design the architecture, and create a detaile
 
 # Planning
 
+## Prerequisites Check
+
+Before starting this step, verify:
+- [ ] Specification approved with clarity score ≥90
+- [ ] `.spec/<slug>/spec.md` exists and is complete
+
+If prerequisites are NOT met → **backtrack to spec step** (`flow_step({ action: 'redo' })` on previous step)
+
 ## Purpose
 
 Translate the specification into a concrete, phased implementation plan with architecture decisions, file-level scope, and dependency ordering.
@@ -82,6 +90,8 @@ Load these skills BEFORE executing this step:
 | `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 |
+| `adr-skill` | Architecture Decision Records for non-trivial technical decisions | When plan involves architecture choices that need documentation |
+| `c4-architecture` | C4 model diagrams showing system structure changes | When plan modifies system architecture |
 
 ### Presentation Rules
 - Use `present` for **any output** that benefits from rich rendering — not limited to dashboards
@@ -98,3 +108,13 @@ Load these skills BEFORE executing this step:
 - [ ] Dependency graph has no circular dependencies
 - [ ] Risks identified with mitigations
 - [ ] `.spec/<slug>/plan.md` written
+
+## Knowledge Capture
+
+Before completing this step, persist important findings using `remember()`:
+
+- **Task dependencies**: Critical ordering constraints and parallel opportunities
+- **Risk assessment**: Identified risks and mitigation strategies
+- **Resource decisions**: File ownership, module boundaries, and integration points
+
+**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.

package/scaffold/flows/aikit-advanced/{skills/spec/SKILL.md → steps/spec/README.md}

@@ -5,6 +5,14 @@ description: Elicit requirements, clarify scope, and define acceptance criteria
 
 # Specification
 
+## Prerequisites Check
+
+Before starting this step, verify:
+- [ ] Design decisions approved (design-decisions.md exists with user approval)
+- [ ] FORGE tier assigned and documented
+
+If prerequisites are NOT met -> **backtrack to design step** (`flow_step({ action: 'redo' })` on previous step)
+
 ## Purpose
 
 Transform a vague or broad feature request into a precise, testable specification through requirements elicitation and stakeholder dialogue.
@@ -83,6 +91,7 @@ Load these skills BEFORE executing this step:
 | `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 |
+| `requirements-clarity` | Score requirements 0-100, iterate until ≥90 before proceeding | Before writing spec — ensures requirements are clear enough |
 
 ### Presentation Rules
 - Use `present` for **any output** that benefits from rich rendering — not limited to dashboards
@@ -98,3 +107,13 @@ Load these skills BEFORE executing this step:
 - [ ] Requirements clarity score ≥ 90
 - [ ] No open questions remain
 - [ ] `.spec/<slug>/spec.md` written
+
+## Knowledge Capture
+
+Before completing this step, persist important findings using `remember()`:
+
+- **Requirements clarified**: Ambiguities resolved and assumptions validated
+- **Scope boundaries**: What the spec covers and explicit exclusions
+- **Acceptance criteria**: Key testable conditions that define "done"
+
+**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.

package/scaffold/flows/aikit-advanced/{skills/task/SKILL.md → steps/task/README.md}

@@ -5,6 +5,14 @@ description: Break the implementation plan into ordered, atomic tasks with depen
 
 # Task Breakdown
 
+## Prerequisites Check
+
+Before starting this step, verify:
+- [ ] Implementation plan approved
+- [ ] `.spec/<slug>/plan.md` exists with defined phases
+
+If prerequisites are NOT met → **backtrack to plan step** (`flow_step({ action: 'redo' })` on previous step)
+
 ## Purpose
 
 Decompose the implementation plan into small, atomic tasks that agents can execute independently, with clear dependency ordering and acceptance criteria per task.
@@ -97,3 +105,13 @@ Load these skills BEFORE executing this step:
 - [ ] Parallelism opportunities identified
 - [ ] Architect review confirms no integration risks
 - [ ] `.spec/<slug>/tasks.md` written
+
+## Knowledge Capture
+
+Before completing this step, persist important findings using `remember()`:
+
+- **Task decomposition rationale**: Why tasks were split this way and what each accomplishes
+- **Interface contracts**: APIs, types, or data shapes that tasks depend on
+- **Coordination points**: Where tasks interact and handoff requirements
+
+**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call `remember()` now.

package/scaffold/flows/aikit-advanced/{skills/verify/SKILL.md → steps/verify/README.md}

@@ -5,6 +5,15 @@ description: Dual code review, architecture review, security review, and compreh
 
 # Verification (Advanced)
 
+## Prerequisites Check
+
+Before starting this step, verify:
+- [ ] All tasks marked complete in progress tracker
+- [ ] `check({})` and `test_run({})` pass
+- [ ] `.spec/<slug>/progress.md` exists with execution results
+
+If prerequisites are NOT met → **backtrack to execute step** (`flow_step({ action: 'redo' })` on previous step)
+
 ## Purpose
 
 Perform thorough multi-perspective validation of all changes through parallel dual code review, architecture review, and security analysis.
@@ -94,6 +103,8 @@ Load these skills BEFORE executing this step:
 | `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 principles from completed work | After verification — capture lessons from the implementation |
+| `session-handoff` | Context preservation for session continuity | When verification spans sessions or for final handoff documentation |
 
 ### Presentation Rules
 - Use `present` for **any output** that benefits from rich rendering — not limited to dashboards
@@ -120,3 +131,13 @@ After all reviews complete:
 - [ ] All spec acceptance criteria verified
 - [ ] FORGE gate passed (YIELD)
 - [ ] `.spec/<slug>/verify-report.md` written with clear 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.

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** | `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 `.spec/` directory relative to the project root.

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

@@ -3,19 +3,28 @@
   "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",
-      "skill": "skills/assess/SKILL.md",
+      "instruction": "steps/assess/README.md",
       "produces": ["assessment.md"],
-      "requires": [],
+      "requires": ["design-decisions.md"],
       "agents": ["Explorer", "Researcher-Alpha"],
       "description": "Understand scope, analyze codebase, identify approach"
     },
     {
       "id": "implement",
       "name": "Implementation",
-      "skill": "skills/implement/SKILL.md",
+      "instruction": "steps/implement/README.md",
       "produces": ["progress.md"],
       "requires": ["assessment.md"],
       "agents": ["Implementer", "Frontend"],
@@ -24,7 +33,7 @@
     {
       "id": "verify",
       "name": "Verification",
-      "skill": "skills/verify/SKILL.md",
+      "instruction": "steps/verify/README.md",
       "produces": ["verify-report.md"],
       "requires": ["progress.md"],
       "agents": ["Code-Reviewer-Alpha", "Security"],

package/scaffold/flows/aikit-basic/{skills/assess/SKILL.md → steps/assess/README.md}

@@ -14,6 +14,19 @@ Analyze the task requirements and codebase to produce a clear, actionable assess
 - 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
@@ -65,6 +78,8 @@ Load these skills BEFORE executing this step:
 | `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
@@ -80,3 +95,13 @@ Load these skills BEFORE executing this step:
 - [ ] Risks documented with mitigations
 - [ ] No unresolved open questions that block implementation
 - [ ] `.spec/<slug>/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.