@vpxa/aikit 0.1.20 → 0.1.22

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

@@ -6,7 +6,7 @@
     {
       "id": "design",
       "name": "Design Gate",
-      "skill": "skills/design/SKILL.md",
+      "instruction": "steps/design/README.md",
       "produces": ["design-decisions.md"],
       "requires": [],
       "agents": ["Researcher-Alpha", "Researcher-Beta", "Researcher-Gamma", "Researcher-Delta"],
@@ -15,7 +15,7 @@
     {
       "id": "spec",
       "name": "Specification",
-      "skill": "skills/spec/SKILL.md",
+      "instruction": "steps/spec/README.md",
       "produces": ["spec.md"],
       "requires": ["design-decisions.md"],
       "agents": ["Researcher-Alpha"],
@@ -24,7 +24,7 @@
     {
       "id": "plan",
       "name": "Planning",
-      "skill": "skills/plan/SKILL.md",
+      "instruction": "steps/plan/README.md",
       "produces": ["plan.md"],
       "requires": ["spec.md"],
       "agents": ["Planner", "Explorer"],
@@ -33,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"],
@@ -42,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"],
@@ -51,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/{skills/design/SKILL.md → steps/design/README.md}

@@ -132,3 +132,33 @@ After user approves:
 - `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

@@ -6,19 +6,19 @@ Quick development flow for **bug fixes, small features, and refactoring**.
 
 | # | 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 |
+| 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 **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.
+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 `skills/design/SKILL.md` for the full decision tree
+- Read `steps/design/README.md` for the full decision tree
 
 ### Step 2: Assessment
 - Explore the codebase to understand scope and impact
@@ -39,8 +39,8 @@ Each step has a **SKILL.md** file that contains the detailed instructions for th
 
 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
+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

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

@@ -6,7 +6,7 @@
     {
       "id": "design",
       "name": "Design Gate",
-      "skill": "skills/design/SKILL.md",
+      "instruction": "steps/design/README.md",
       "produces": ["design-decisions.md"],
       "requires": [],
       "agents": ["Researcher-Alpha", "Researcher-Beta", "Researcher-Gamma", "Researcher-Delta"],
@@ -15,7 +15,7 @@
     {
       "id": "assess",
       "name": "Assessment",
-      "skill": "skills/assess/SKILL.md",
+      "instruction": "steps/assess/README.md",
       "produces": ["assessment.md"],
       "requires": ["design-decisions.md"],
       "agents": ["Explorer", "Researcher-Alpha"],
@@ -24,7 +24,7 @@
     {
       "id": "implement",
       "name": "Implementation",
-      "skill": "skills/implement/SKILL.md",
+      "instruction": "steps/implement/README.md",
       "produces": ["progress.md"],
       "requires": ["assessment.md"],
       "agents": ["Implementer", "Frontend"],
@@ -33,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.

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

@@ -73,3 +73,35 @@ When complete, report status:
 ## 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
+
+## 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/{skills/implement/SKILL.md → steps/implement/README.md}

@@ -13,6 +13,19 @@ Execute the implementation plan from the assessment, writing production code and
 
 - `.spec/<slug>/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 `.spec/<slug>/assessment.md` and internalize the approach
@@ -67,6 +80,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 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
@@ -103,3 +117,13 @@ Follow the `multi-agents-development` skill patterns for dispatch:
 - [ ] `test_run({})` passes (no test failures)
 - [ ] No files modified outside assessed scope
 - [ ] `.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 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/{skills/verify/SKILL.md → steps/verify/README.md}

@@ -14,6 +14,19 @@ Validate that the implementation meets the original requirements, passes all qua
 - `.spec/<slug>/assessment.md` — original requirements and approach
 - `.spec/<slug>/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
@@ -70,6 +83,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 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
@@ -94,3 +109,13 @@ After all reviews complete:
 - [ ] Security review complete
 - [ ] Blast radius assessed
 - [ ] `.spec/<slug>/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.

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

@@ -56,8 +56,8 @@ You orchestrate the full development lifecycle: **planning → implementation
 
 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`
+   - Note current step name and instruction path
+   - Read the current step instruction with `flow_read_instruction`
    - Follow its instructions
    - When complete: `flow_step({ action: 'next' })`
 3. **If NO active flow:**
@@ -80,8 +80,8 @@ You orchestrate the full development lifecycle: **planning → implementation
 
 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
+1. `flow_read_instruction` — read the current step's README.md
+2. Follow the step'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
@@ -156,7 +156,7 @@ Batch 2 (after batch 1):
 | `flow_step` | Advance: next, skip, or redo current step |
 | `flow_status` | Check current execution state |
 | `flow_reset` | Clear flow state to start over |
-| `flow_read_skill` | Read the skill content for the current step |
+| `flow_read_instruction` | Read the instruction content for the current step |
 
 ## Emergency: STOP → ASSESS → CONTAIN → RECOVER → DOCUMENT
 
@@ -248,7 +248,7 @@ Before every tool call, verify:
 ## Flows
 
 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' })`.
+If a flow is active, follow the current step's instructions. Advance with `flow_step({ action: 'next' })`.
 Use `flow_list` to see available flows and `flow_start` to begin one.
 
 

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

@@ -44,8 +44,8 @@ The Planner is typically activated by the Orchestrator as part of a flow step (e
 
 **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
+2. `flow_read_instruction` — read the current step's README.md for specific instructions
+3. Follow the step'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`

package/scaffold/general/agents/_shared/code-agent-base.md

@@ -60,7 +60,7 @@ You may be invoked in two modes:
 
 ```
 flow_status({})                                                # Check/resume active flow FIRST
-# If flow active → flow_read_skill({ step }) → follow skill instructions
+# If flow active → flow_read_instruction({ step }) → follow step instructions
 status({})                                                     # Check AI Kit health + onboard state
 # If onboard not run → onboard({ path: "." })                 # First-time codebase analysis
 flow_list({})                                                  # See available flows
@@ -73,7 +73,7 @@ search({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior wo
 
 | Category | Tools | Purpose |
 |----------|-------|---------|
-| Flows | `flow_list`, `flow_info`, `flow_start`, `flow_step`, `flow_status`, `flow_read_skill`, `flow_reset` | Structured multi-step workflows |
+| Flows | `flow_list`, `flow_info`, `flow_start`, `flow_step`, `flow_status`, `flow_read_instruction`, `flow_reset` | Structured multi-step workflows |
 
 ---
 

package/scaffold/general/skills/adr-skill/SKILL.md

@@ -262,7 +262,7 @@ Preferred: let `scripts/new_adr.js --update-index` do it. Otherwise:
 When introducing ADRs to a repo that has none:
 
 ```bash
-node /path/to/adr-skill/scripts/bootstrap_adr.js
+node scripts/bootstrap_adr.js
 ```
 
 This creates the directory, an index file, and a filled-out first ADR ("Adopt architecture decision records") with real content explaining why the team is using ADRs. Use `--json` for machine-readable output. Use `--dir` to override the directory name.
@@ -306,20 +306,20 @@ Date prefixes are local to each category. Choose a categorization scheme early (
 
 ### Script Usage
 
-From the target repo root:
+From the directory that contains this skill's `scripts/` folder:
 
 ```bash
 # Simple ADR
-node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed
+node scripts/new_adr.js --title "Choose database" --status proposed
 
 # MADR-style with options
-node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed
+node scripts/new_adr.js --title "Choose database" --template madr --status proposed
 
 # With index update
-node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index
+node scripts/new_adr.js --title "Choose database" --status proposed --update-index
 
 # Bootstrap a new repo
-node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions
+node scripts/bootstrap_adr.js --dir docs/decisions
 ```
 
 Notes: