@vpxa/aikit 0.1.209 → 0.1.210

package/scaffold/dist/definitions/flows.mjs

@@ -1,4 +1,53 @@
-const e={_epilogue:[{file:`steps/docs-sync/README.md`,content:`# Epilogue: Documentation Sync
+const e=`### Orchestrator Dispatch Protocol
+
+Follow the \`multi-agents-development\` skill patterns for dispatch:
+
+1. **Independence Check** before parallelizing:
+   - Same files? → sequential
+   - Shared mutable state? → sequential
+   - Execution-order dependent? → sequential
+   - Need shared new types? → define contract first, then parallel
+   - All clear? → **parallel dispatch**
+
+2. **Subagent Context Template** (each dispatch includes):
+   - **Scope**: exact files + boundary (do NOT touch)
+   - **Goal**: acceptance criteria, testable
+   - **Arch Context**: actual code snippets via \`compact()\`/\`digest()\`
+   - **Constraints**: patterns, conventions, anti-patterns
+   - **Self-Review**: checklist before declaring DONE
+
+3. **Status Protocol**: \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
+4. **Max 2 retries** per task — then escalate to user`,t=`### FORGE Quality Gate
+
+After all reviews complete:
+1. \`evidence_map({ action: "gate", task_id: "<slug>" })\` → returns YIELD/HOLD/HARD_BLOCK
+2. YIELD → approved, proceed to commit
+3. HOLD → minor issues, fix then re-gate (max 3 rounds)
+4. HARD_BLOCK → critical issues, escalate to user`;function n(e,t=``,n=``){return`## Foundation Integration
+
+Load these skills BEFORE executing this step:
+
+| Skill | Purpose | When |
+|-------|---------|------|
+| \`aikit\` | Core MCP tools — search, analyze, ${e}, 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 |${t?`\n${t}`:``}
+
+### Presentation Rules
+- Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
+- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
+- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
+- Tables, charts, progress tracking, code review findings → always present
+- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
+- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
+- Only use plain text for brief confirmations and simple questions${n?`\n\n${n}`:``}`}const r=e=>`## Knowledge Capture
+
+Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
+
+${e}
+
+**Every step produces knowledge worth preserving.** If you discovered something that would help a future session, call \`knowledge({ action: "remember", ... })\` now.`,i={_epilogue:[{file:`steps/docs-sync/README.md`,content:`# Epilogue: Documentation Sync
 
 > **This is a mandatory epilogue step.** It runs automatically after every flow completes to keep project documentation synchronized with code changes.
 
@@ -327,27 +376,7 @@ Write \`{{artifacts_path}}/design-decisions.md\` to disk. **You MUST create this
 - \`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, knowledge, 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({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
+${n(`knowledge`,"| `c4-architecture` | C4 model diagrams showing system structure changes | When visualizing proposed architecture |\n| `adr-skill` | Architecture Decision Records for non-trivial decisions | Critical tier — document architecture decisions |")}
 
 ## Completion Criteria
 
@@ -357,15 +386,9 @@ Load these skills BEFORE executing this step:
 - [ ] Key design decisions documented with rationale
 - [ ] User approval received (🛑 MANDATORY STOP)
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Design decisions**: Chosen approach and alternatives considered with trade-offs
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Constraints discovered**: Technical limitations, compatibility requirements, or performance boundaries`)}
 `},{file:`steps/execute/README.md`,content:`---
 name: execute
 description: Implement all tasks from the task breakdown, dispatching agents in parallel where possible.
@@ -466,47 +489,7 @@ Template:
 - File-modifying agents: parallel ONLY on completely different files
 - Max 4 concurrent file-modifying agents
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, knowledge, validate | Always (auto-loaded) |
-| \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-| \`session-handoff\` | Context preservation for 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
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
-
-### Orchestrator Dispatch Protocol
-
-Follow the \`multi-agents-development\` skill patterns for dispatch:
-
-1. **Independence Check** before parallelizing:
-   - Same files? → sequential
-   - Shared mutable state? → sequential
-   - Execution-order dependent? → sequential
-   - Need shared new types? → define contract first, then parallel
-   - All clear? → **parallel dispatch**
-
-2. **Subagent Context Template** (each dispatch includes):
-   - **Scope**: exact files + boundary (do NOT touch)
-   - **Goal**: acceptance criteria, testable
-   - **Arch Context**: actual code snippets via \`compact()\`/\`digest()\`
-   - **Constraints**: patterns, conventions, anti-patterns
-   - **Self-Review**: checklist before declaring DONE
-
-3. **Status Protocol**: \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
-4. **Max 2 retries** per task — then escalate to user
+${n(`knowledge`,"| `session-handoff` | Context preservation for long-running execution phases | When execution spans multiple sessions or context is filling |",e)}
 
 ## Completion Criteria
 
@@ -516,15 +499,9 @@ Follow the \`multi-agents-development\` skill patterns for dispatch:
 - [ ] No blocked items remaining
 - [ ] \`{{artifacts_path}}/progress.md\` written
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Implementation decisions**: Why specific approaches were chosen over alternatives
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Gotchas encountered**: Edge cases, workarounds, or non-obvious behaviors discovered during execution`)}
 `},{file:`steps/plan/README.md`,content:`---
 name: plan
 description: Analyze the codebase, design the architecture, and create a detailed implementation plan.
@@ -620,27 +597,7 @@ Template:
 
 The Planner agent (\`Planner.agent.md\`) owns the \`{{artifacts_path}}/plan.md\` artifact. Pass it the spec content, Explorer findings, and artifacts path as context.
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, knowledge, 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 |
-| \`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
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
+${n(`knowledge`,"| `adr-skill` | Architecture Decision Records for non-trivial technical decisions | When plan involves architecture choices that need documentation |\n| `c4-architecture` | C4 model diagrams showing system structure changes | When plan modifies system architecture |")}
 
 ## Completion Criteria
 
@@ -651,15 +608,9 @@ Load these skills BEFORE executing this step:
 - [ ] Risks identified with mitigations
 - [ ] \`{{artifacts_path}}/plan.md\` written
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Task dependencies**: Critical ordering constraints and parallel opportunities
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Resource decisions**: File ownership, module boundaries, and integration points`)}
 `},{file:`steps/spec/README.md`,content:`---
 name: spec
 description: Elicit requirements, clarify scope, and define acceptance criteria through structured dialogue.
@@ -781,26 +732,7 @@ Key Clarifications:
 
 Use the \`brainstorming\` skill for creative/design exploration before formalizing requirements. Use \`requirements-clarity\` skill to score and iterate until the spec is unambiguous.
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
-| \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-| \`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
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
+${n(`remember`,"| `requirements-clarity` | Score requirements 0-100, iterate until ≥90 before proceeding | Before writing spec — ensures requirements are clear enough |")}
 
 ## Completion Criteria
 
@@ -810,15 +742,9 @@ Load these skills BEFORE executing this step:
 - [ ] No open questions remain
 - [ ] \`{{artifacts_path}}/spec.md\` written
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Requirements clarified**: Ambiguities resolved and assumptions validated
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Acceptance criteria**: Key testable conditions that define "done"`)}
 `},{file:`steps/task/README.md`,content:`---
 name: task
 description: Break the implementation plan into ordered, atomic tasks with dependencies and agent assignments.
@@ -917,25 +843,7 @@ Use the template-driven graph for the dependency view; if you add supporting sum
 
 Planner does the decomposition, then Architect-Reviewer validates the task graph.
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
-| \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-
-### Presentation Rules
-- Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
+${n(`remember`)}
 
 ## Completion Criteria
 
@@ -946,15 +854,9 @@ Load these skills BEFORE executing this step:
 - [ ] Architect review confirms no integration risks
 - [ ] \`{{artifacts_path}}/tasks.md\` written
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Task decomposition rationale**: Why tasks were split this way and what each accomplishes
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Coordination points**: Where tasks interact and handoff requirements`)}
 `},{file:`steps/verify/README.md`,content:`---
 name: verify
 description: Dual code review, architecture review, security review, and comprehensive test validation.
@@ -1062,35 +964,7 @@ APPROVE | REQUEST CHANGES
 
 **Parallelism**: All 5 reviewers can run in parallel — they are read-only.
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
-| \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-| \`lesson-learned\` | Extract engineering 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
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
-
-### FORGE Quality Gate
-
-After all reviews complete:
-1. \`evidence_map({ action: "gate", task_id: "<slug>" })\` → returns YIELD/HOLD/HARD_BLOCK
-2. YIELD → approved, proceed to commit
-3. HOLD → minor issues, fix then re-gate (max 3 rounds)
-4. HARD_BLOCK → critical issues, escalate to user
+${n(`remember`,"| `lesson-learned` | Extract engineering principles from completed work | After verification — capture lessons from the implementation |\n| `session-handoff` | Context preservation for session continuity | When verification spans sessions or for final handoff documentation |",t)}
 
 ## Completion Criteria
 
@@ -1103,15 +977,9 @@ After all reviews complete:
 - [ ] FORGE gate passed (YIELD)
 - [ ] \`{{artifacts_path}}/verify-report.md\` written with clear verdict
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Test coverage gaps**: Areas that couldn't be fully tested and why
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Session checkpoint**: Summarize what was accomplished, decisions made, and any remaining work`)}
 `}],"aikit-basic":[{file:`README.md`,content:"# aikit:basic — Quick Development Flow\n\nQuick development flow for **bug fixes, small features, and refactoring**.\n\n## Steps\n\n| # | Step | Skill | Produces | Requires | Agents |\n|---|------|-------|----------|----------|--------|\n| 1 | **Design Gate** | `steps/design/README.md` | `design-decisions.md` | — | Researcher-Alpha/Beta/Gamma/Delta |\n| 2 | **Assessment** | `steps/assess/README.md` | `assessment.md` | `design-decisions.md` | Explorer, Researcher-Alpha |\n| 3 | **Implementation** | `steps/implement/README.md` | `progress.md` | `assessment.md` | Implementer, Frontend |\n| 4 | **Verification** | `steps/verify/README.md` | `verify-report.md` | `progress.md` | Code-Reviewer-Alpha, Security |\n\n## How It Works\n\nEach 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({ action: 'read' })` and delegates work accordingly.\n\n### Step 1: Design Gate\n- **Auto-skips** for bug fixes and refactors (produces a minimal `design-decisions.md` noting it was skipped)\n- For small features: runs quick brainstorming, FORGE classification, and optional decision protocol (see Orchestrator's inlined Multi-Model Decision Protocol for the full 3-phase process)\n- Read `steps/design/README.md` for the full decision tree\n\n### Step 2: Assessment\n- Explore the codebase to understand scope and impact\n- Use `search`, `scope_map`, `file_summary`, `compact` to gather context\n- Identify the approach and produce `assessment.md`\n\n### Step 3: Implementation\n- Write code following the assessment plan\n- The Orchestrator dispatches Implementer/Frontend agents with specific file scopes\n- Follow TDD practices where applicable\n\n### Step 4: Verification\n- Code review, test execution, security check\n- Run `check({})` + `test_run({})` + `blast_radius({})`\n- Produce `verify-report.md` with findings\n\n## Using Skills Inside Steps\n\nWhen the Orchestrator activates a step:\n\n1. **Read the instruction first** — `flow({ action: 'read' })` returns the README.md for the current step\n2. **Follow step instructions** — the README.md is the primary guide for what to do\n3. **Delegate to listed agents** — each step lists which agents are appropriate\n4. **Produce the required artifact** — the step's `produces` field specifies what file to create in the artifacts directory\n5. **Check dependencies** — the step's `requires` field lists artifacts from previous steps that must exist\n6. **Report status** — agents report `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED` to the Orchestrator\n\n## Artifacts\n\nAll artifacts are stored in the run directory under `.flows/{topic}/`. The template variable `{{artifacts_path}}` resolves to the actual path at runtime.\n"},{file:`steps/assess/README.md`,content:`---
 name: assess
 description: Understand scope, analyze the codebase, and identify the implementation approach.
@@ -1193,27 +1061,7 @@ Template:
 
 Use Explorer first for breadth, then Researcher-Alpha for depth on complex areas.
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
-| \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-| \`c4-architecture\` | C4 model architecture diagrams — system context, container, component, deployment views | When visualizing system structure during assessment |
-| \`adr-skill\` | Architecture Decision Records — create, review, maintain ADRs | When assessment reveals non-trivial design decisions |
-
-### Presentation Rules
-- Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
+${n(`remember`,"| `c4-architecture` | C4 model architecture diagrams — system context, container, component, deployment views | When visualizing system structure during assessment |\n| `adr-skill` | Architecture Decision Records — create, review, maintain ADRs | When assessment reveals non-trivial design decisions |")}
 
 ## Completion Criteria
 
@@ -1223,15 +1071,9 @@ Load these skills BEFORE executing this step:
 - [ ] No unresolved open questions that block implementation
 - [ ] \`{{artifacts_path}}/assessment.md\` written
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Codebase discoveries**: File locations, architecture patterns, or dependency relationships found during assessment
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Scope decisions**: What's in scope, what's explicitly excluded, and why`)}
 `},{file:`steps/design/README.md`,content:`# 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.
@@ -1324,27 +1166,7 @@ Write \`{{artifacts_path}}/design-decisions.md\` to disk. **You MUST create this
 
 - \`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({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
+${n(`remember`,"| `c4-architecture` | C4 model architecture diagrams — system context, container, component, deployment views | When visualizing system structure during design |\n| `adr-skill` | Architecture Decision Records — create, review, maintain ADRs | When making non-trivial design or technology decisions |")}
 
 ## Completion Criteria
 
@@ -1352,15 +1174,9 @@ Load these skills BEFORE executing this step:
 - [ ] FORGE tier determined (for small features)
 - [ ] Key design decisions documented
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Design decisions**: Chosen approach and alternatives considered with trade-offs
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Constraints discovered**: Technical limitations, compatibility requirements, or performance boundaries`)}
 `},{file:`steps/implement/README.md`,content:`---
 name: implement
 description: Write code following the assessment plan, using TDD practices where applicable.
@@ -1449,47 +1265,7 @@ Template:
 
 Dispatch Implementer for backend/logic changes, Frontend for UI changes. Both can run in parallel if working on different files.
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
-| \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-| \`session-handoff\` | Context preservation for session transfers | When implementation is long-running and context may fill up |
-
-### Presentation Rules
-- Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
-
-### Orchestrator Dispatch Protocol
-
-Follow the \`multi-agents-development\` skill patterns for dispatch:
-
-1. **Independence Check** before parallelizing:
-   - Same files? → sequential
-   - Shared mutable state? → sequential
-   - Execution-order dependent? → sequential
-   - Need shared new types? → define contract first, then parallel
-   - All clear? → **parallel dispatch**
-
-2. **Subagent Context Template** (each dispatch includes):
-   - **Scope**: exact files + boundary (do NOT touch)
-   - **Goal**: acceptance criteria, testable
-   - **Arch Context**: actual code snippets via \`compact()\`/\`digest()\`
-   - **Constraints**: patterns, conventions, anti-patterns
-   - **Self-Review**: checklist before declaring DONE
-
-3. **Status Protocol**: \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
-4. **Max 2 retries** per task — then escalate to user
+${n(`remember`,"| `session-handoff` | Context preservation for session transfers | When implementation is long-running and context may fill up |",e)}
 
 ## Completion Criteria
 
@@ -1499,15 +1275,9 @@ Follow the \`multi-agents-development\` skill patterns for dispatch:
 - [ ] No files modified outside assessed scope
 - [ ] \`{{artifacts_path}}/progress.md\` written
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Implementation decisions**: Why specific approaches were chosen over alternatives
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
+- **Gotchas encountered**: Edge cases, workarounds, or non-obvious behaviors discovered during implementation`)}
 `},{file:`steps/verify/README.md`,content:`---
 name: verify
 description: Review code changes, run tests, validate correctness and quality.
@@ -1585,35 +1355,7 @@ Template:
 
 Run both in parallel — they review different aspects of the same changes.
 
-## Foundation Integration
-
-Load these skills BEFORE executing this step:
-
-| Skill | Purpose | When |
-|-------|---------|------|
-| \`aikit\` | Core MCP tools — search, analyze, remember, validate | Always (auto-loaded) |
-| \`present\` | Rich rendering for any structured output — assessments, reports, comparisons, reviews, status boards, tables, charts, and all artifact content | Use for ANY output that benefits from rich rendering, not just dashboards |
-| \`multi-agents-development\` | Dispatch templates, task decomposition, review pipeline patterns | Before dispatching any subagent |
-| \`brainstorming\` | Structured ideation for design/creative decisions | Before any design choice or new feature exploration |
-| \`lesson-learned\` | Extract engineering lessons from completed work via git history | After verification completes — capture principles from what was built |
-| \`session-handoff\` | Context preservation for session transfers | When verification is the final step and session context should be saved |
-
-### Presentation Rules
-- Use \`present\` for **any output** that benefits from rich rendering — not limited to dashboards
-- Assessments, reports, comparisons, reviews, status boards → \`present({ schemaVersion: 1, title: "Assessment", blocks: [...] })\`
-- Use \`table\` blocks for comparisons, \`kv\` for status/scores, \`list\` for findings, and \`metrics\` for numeric health indicators. NEVER \`code\` blocks for structured data.
-- Tables, charts, progress tracking, code review findings → always present
-- Use \`metrics\` for numeric indicators, \`checklist\` for task status, \`kv\` for summary, and \`table\` for review findings. NEVER \`code\` blocks for structured data.
-- Artifact content and summaries → present with structured layout; use \`markdown\` for prose sections.
-- Only use plain text for brief confirmations and simple questions
-
-### FORGE Quality Gate
-
-After all reviews complete:
-1. \`evidence_map({ action: "gate", task_id: "<slug>" })\` → returns YIELD/HOLD/HARD_BLOCK
-2. YIELD → approved, proceed to commit
-3. HOLD → minor issues, fix then re-gate (max 3 rounds)
-4. HARD_BLOCK → critical issues, escalate to user
+${n(`remember`,"| `lesson-learned` | Extract engineering lessons from completed work via git history | After verification completes — capture principles from what was built |\n| `session-handoff` | Context preservation for session transfers | When verification is the final step and session context should be saved |",t)}
 
 ## Completion Criteria
 
@@ -1624,13 +1366,7 @@ After all reviews complete:
 - [ ] Blast radius assessed
 - [ ] \`{{artifacts_path}}/verify-report.md\` written with clear PASS/FAIL verdict
 
-## Knowledge Capture
-
-Before completing this step, persist important findings using \`knowledge({ action: "remember", ... })\`:
-
-- **Test coverage gaps**: Areas that couldn't be fully tested and why
+${r(`- **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 \`knowledge({ action: "remember", ... })\` now.
-`}]};export{e as FLOWS};
+- **Session checkpoint**: Summarize what was accomplished, decisions made, and any remaining work`)}
+`}]};export{i as FLOWS};

package/scaffold/dist/definitions/protocols.mjs

@@ -18,7 +18,10 @@ When dispatched as a subagent within an active flow:
 
 ${e===`<PROFILE>`?`**Profile:** Check your role → implementer | documenter | reviewer | researcher | debugger`:`**Profile:** \`${e}\``}
 
----`}function t(){return"\n## Evidence Citation Protocol (tier-aware)\n\n**Standalone mode:** If no FORGE task_id was provided in your dispatch prompt, skip `evidence_map` calls entirely — provide free-form findings with `file:line` citations only.\n\nThe Orchestrator runs `forge_classify` before dispatching you, and runs the final `evidence_map({ action: 'gate', task_id })` after you respond. **Do not create your own task_id or run the gate** — feed into the Orchestrator's existing evidence map.\n\n| Tier | Your responsibility |\n|------|---------------------|\n| Floor | Free-form findings with `file.ts#Lxx` citations. No `evidence_map` calls required. |\n| Standard | For every CRITICAL or HIGH finding: `evidence_map({action:'add', task_id, claim, status:'V', receipt:'file.ts#Lxx'})`. Max 2-4 adds to keep signal high. |\n| Critical | Structured claims for all CRITICAL/HIGH findings (2-4 Verified + receipts) AND tag contract/security claims with `safety_gate:'commitment'` or `safety_gate:'provenance'`. |\n\n**Every response MUST include:**\n- `**FORGE Task ID:** <task_id>` (passed in by Orchestrator, or state \"not provided\")\n- `**Tier applied:** Floor | Standard | Critical`\n- `**Findings:** <list>` with `file:line` receipts\n- Verdict: `APPROVED` | `CHANGES_REQUESTED` | `BLOCKED`\n\nDo NOT:\n- Create a new `evidence_map` (the Orchestrator already did)\n- Run `evidence_map({action:'gate'})` yourself — the Orchestrator owns the gate\n- Duplicate findings into the map that weren't CRITICAL/HIGH"}const n={"code-agent-base":`# Code Agent — Shared Base Instructions
+---`}function t(){return"\n## Evidence Citation Protocol (tier-aware)\n\n**Standalone mode:** If no FORGE task_id was provided in your dispatch prompt, skip `evidence_map` calls entirely — provide free-form findings with `file:line` citations only.\n\nThe Orchestrator runs `forge_classify` before dispatching you, and runs the final `evidence_map({ action: 'gate', task_id })` after you respond. **Do not create your own task_id or run the gate** — feed into the Orchestrator's existing evidence map.\n\n| Tier | Your responsibility |\n|------|---------------------|\n| Floor | Free-form findings with `file.ts#Lxx` citations. No `evidence_map` calls required. |\n| Standard | For every CRITICAL or HIGH finding: `evidence_map({action:'add', task_id, claim, status:'V', receipt:'file.ts#Lxx'})`. Max 2-4 adds to keep signal high. |\n| Critical | Structured claims for all CRITICAL/HIGH findings (2-4 Verified + receipts) AND tag contract/security claims with `safety_gate:'commitment'` or `safety_gate:'provenance'`. |\n\n**Every response MUST include:**\n- `**FORGE Task ID:** <task_id>` (passed in by Orchestrator, or state \"not provided\")\n- `**Tier applied:** Floor | Standard | Critical`\n- `**Findings:** <list>` with `file:line` receipts\n- Verdict: `APPROVED` | `CHANGES_REQUESTED` | `BLOCKED`\n\nDo NOT:\n- Create a new `evidence_map` (the Orchestrator already did)\n- Run `evidence_map({action:'gate'})` yourself — the Orchestrator owns the gate\n- Duplicate findings into the map that weren't CRITICAL/HIGH"}function n(...e){return e.filter(Boolean).join(`
+
+`)}function r({title:e=`Knowledge Recall`,intro:t,commands:r,followUp:i}={}){return n(`## Pre-Task: ${e} (MANDATORY)`,t,["```",...(Array.isArray(r)?r:[r]).filter(Boolean),"```"].join(`
+`),i)}function i(){return n(`## Post-Task: Capture Lesson`,"**HARD RULE:** Before reporting DONE status, load the `lesson-learned` skill and extract 1-2 engineering lessons from the changes made. Skip ONLY if changes are pure config/formatting with no logic modified.",'Quick lesson capture (when full skill feels heavy):\n```\nknowledge({ action: "lesson", subAction: "create", context: "<what situation you faced>", insight: "<what principle the solution demonstrates>", evidence: "<file:line or commit that proves it>", confidence: 65 })\n```','**Confirm/Contradict (if pre-task recalled relevant lessons):**\n- Lesson proved correct → `knowledge({ action: "lesson", subAction: "confirm", id: "<recalled-lesson-path>" })`\n- Lesson was wrong/outdated → `knowledge({ action: "lesson", subAction: "contradict", id: "<recalled-lesson-path>", evidence: "<what actually happened>" })`','```\n// Periodic maintenance (suggest every ~5 sessions):\n// knowledge({ action: "lesson", subAction: "prune" })   // archive stale\n// knowledge({ action: "lesson", subAction: "group" })   // organize similar\n// knowledge({ action: "lesson", subAction: "promote" }) // share universal (user-level only)\n```')}const a={"code-agent-base":`# Code Agent — Shared Base Instructions
 
 > This file contains shared protocols for all code-modifying agents (Implementer, Frontend, Refactor, Debugger). Each agent's definition file contains only its unique identity, constraints, and workflow. **Do not duplicate this content in agent files.**
 
@@ -201,6 +204,19 @@ search({ query: "<feature/area keywords>", limit: 5 })  // check past decisions
 knowledge({ action: "list", category: "decisions" })   // scan recent decisions that might apply
 knowledge({ action: "list", category: "conventions" }) // see project conventions (includes auto-captured)
 knowledge({ action: "lesson", subAction: "list-lessons", topic: "<2-3 task keywords>", minConfidence: 70 })  // topic-scoped lessons
+
+// Lesson lifecycle management
+knowledge({ action: "lesson", subAction: "prune" })                           // dry-run: review stale candidates
+knowledge({ action: "lesson", subAction: "prune", dryRun: false })            // execute prune
+knowledge({ action: "lesson", subAction: "group" })                           // dry-run: show clusters
+knowledge({ action: "lesson", subAction: "group", dryRun: false })            // execute grouping
+knowledge({ action: "lesson", subAction: "promote" })                         // dry-run: cross-workspace scan
+knowledge({ action: "lesson", subAction: "promote", dryRun: false })          // promote to global
+knowledge({ action: "lesson", subAction: "demote", path: "<path>" })        // remove from global
+
+// Session prelude (at session start)
+status({ includePrelude: true })  // top 3 lessons + top 2 conventions + checkpoint
+
 scope_map({ task: "what you need" })        // generates a reading plan
 
 // If running as sub-agent with flow context:
@@ -792,7 +808,8 @@ Each perspective was produced independently — they have NOT seen each other's
 [Perspective A]
 {Alpha's full response}
 
-[Perspective B]Beta's full response}
+[Perspective B]
+{Beta's full response}
 
 [Perspective C]Gamma's full response}
 
@@ -962,7 +979,7 @@ evidence_map({ action: "gate", task_id: "add-user-api" })  → YIELD ✅
 3. **Standard**: \`evidence_map create\` → add 3-8 claims during work → \`evidence_map gate\`
 4. **Critical**: Full 4-phase flow with comprehensive evidence
 5. **After gate**: YIELD = done, HOLD = fix + re-gate, HARD_BLOCK = escalate
-`},r={"execution-state":`# Execution State: {Task Title}
+`},o={"execution-state":`# Execution State: {Task Title}
 
 **Status:** PLANNING | IN_PROGRESS | REVIEW | COMPLETED | BLOCKED
 **Started:** {timestamp}
@@ -1014,4 +1031,4 @@ evidence_map({ action: "gate", task_id: "add-user-api" })  → YIELD ✅
 
 ## Alternatives Considered
 {Other approaches evaluated and why they were rejected — keeps the "why not" alongside the "why"}
-`};export{n as PROTOCOLS,r as TEMPLATES};
+`};export{a as PROTOCOLS,o as TEMPLATES,i as postTaskLesson,r as preTaskKnowledgeRecall};