@vpxa/aikit 0.1.20 → 0.1.21

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:

package/scaffold/general/skills/aikit/SKILL.md

@@ -43,7 +43,7 @@ core → store → embeddings → chunker → indexer → analyzers → tools
 ### Start (do ALL)
 ```
 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
@@ -189,7 +189,7 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 | `flow_start` | `aikit flow start` | Start a named flow |
 | `flow_step` | `aikit flow step` | Advance, skip, or redo the current step |
 | `flow_status` | `aikit flow status` | Check if a flow is active and view the current step |
-| `flow_read_skill` | `aikit flow read-skill` | Read the current step's skill file content directly |
+| `flow_read_instruction` | `aikit flow read-instruction` | Read the current step's instruction file content directly |
 | `flow_reset` | `aikit flow reset` | Clear flow state to start over |
 
 ### Presentation (1)
@@ -219,8 +219,8 @@ Flows are multi-step guided workflows that structure complex tasks. Each step ha
 flow_list()                          # See available flows
 flow_info({ flow: "aikit:basic" })   # View steps, skills, agents
 flow_start({ flow: "aikit:basic" })  # Start — sets current step to first
-flow_read_skill({ step: "assess" })  # Read current step's skill instructions
-# ... do the work described in the skill ...
+flow_read_instruction({ step: "assess" })  # Read current step's instructions
+# ... do the work described in the instruction ...
 flow_step({ action: "next" })        # Advance to next step
 flow_step({ action: "skip" })        # Skip current step
 flow_step({ action: "redo" })        # Redo current step
@@ -241,14 +241,14 @@ artifacts_dir: .spec
 steps:
   - id: design
     name: Design
-    skill: skills/design/SKILL.md
+    instruction: steps/design/README.md
     description: "Create the design document"
     produces: [design.md]
     requires: []
     agents: [Planner]
   - id: implement
     name: Implement
-    skill: skills/implement/SKILL.md
+    instruction: steps/implement/README.md
     description: "Implement the design"
     produces: [code]
     requires: [design]
@@ -271,7 +271,7 @@ install: []
 ### Agent-Flow Integration
 
 - All code agents have a "Flows" section instructing them to check `flow_status()` first
-- If a flow is active, the agent follows the current step's skill via `flow_read_skill()`
+- If a flow is active, the agent follows the current step's instruction via `flow_read_instruction()`
 - After completing a step's work, advance with `flow_step({ action: "next" })`
 - The **Orchestrator** selects and starts flows; other agents follow them
 - The **Orchestrator** specifies `aikit` skill loading — all agents should load `aikit` skill to access flow tools
@@ -528,7 +528,7 @@ Flows are structured multi-step workflows that guide agents through complex task
 | `flow_info` | Get flow details including steps and skill paths |
 | `flow_start` | Start a named flow |
 | `flow_step` | Advance: `next`, `skip`, or `redo` current step |
-| `flow_read_skill` | Read the current step's skill file content directly |
+| `flow_read_instruction` | Read the current step's instruction file content directly |
 | `flow_reset` | Clear flow state to start over |
 
 ### Flow Selection
@@ -545,7 +545,7 @@ Flows are structured multi-step workflows that guide agents through complex task
 ### Flow Lifecycle
 
 1. **Start**: `flow_list({})` → choose flow → `flow_start({ flow: "<name>" })`
-2. **Each step**: `flow_read_skill({ step: "<name>" })` → follow skill instructions → complete work
+2. **Each step**: `flow_read_instruction({ step: "<name>" })` → follow step instructions → complete work
 3. **Advance**: `flow_step({ action: "next" })` → repeat from step 2
-4. **Resume**: `flow_status({})` → if active, `flow_read_skill` for current step → continue
+4. **Resume**: `flow_status({})` → if active, `flow_read_instruction` for current step → continue
 5. **Reset**: `flow_reset({})` if you need to start over

package/scaffold/general/skills/brainstorming/SKILL.md

@@ -90,7 +90,7 @@ digraph brainstorming_simple {
 
 1. **Explore project context** — check files, docs, recent commits
 2. **Assess scope** — if multiple independent subsystems, decompose before detailing (see below)
-3. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See `visual-companion.md`.
+3. **Offer visual presentation support** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. Use `present({ format: "html" })` to display brainstorming results as a rich visual dashboard.
 4. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 5. **Propose 2-3 approaches via Decision Protocol** — launch ALL 4 Researcher variants in parallel to independently generate approaches. Synthesize their output into deduplicated options with trade-offs and your recommendation. Present agreements and disagreements to the user. *(See "Decision Protocol Integration" below.)*
 6. **Present design** — in sections scaled to their complexity, get user approval after each section
@@ -122,7 +122,7 @@ digraph brainstorming_advanced {
     "Assess scope" [shape=diamond];
     "Decompose into sub-projects" [shape=box];
     "Visual questions ahead?" [shape=diamond];
-    "Offer Visual Companion\n(own message)" [shape=box];
+    "Offer Visual Presentation\n(own message)" [shape=box];
     "Ask clarifying questions" [shape=box];
     "Decision Protocol:\n4 Researchers in parallel" [shape=box, style=bold];
     "Synthesize approaches" [shape=box];
@@ -138,9 +138,9 @@ digraph brainstorming_advanced {
     "Assess scope" -> "Decompose into sub-projects" [label="too large"];
     "Assess scope" -> "Visual questions ahead?" [label="right-sized"];
     "Decompose into sub-projects" -> "Visual questions ahead?" [label="first sub-project"];
-    "Visual questions ahead?" -> "Offer Visual Companion\n(own message)" [label="yes"];
+    "Visual questions ahead?" -> "Offer Visual Presentation\n(own message)" [label="yes"];
     "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
-    "Offer Visual Companion\n(own message)" -> "Ask clarifying questions";
+    "Offer Visual Presentation\n(own message)" -> "Ask clarifying questions";
     "Ask clarifying questions" -> "Decision Protocol:\n4 Researchers in parallel";
     "Decision Protocol:\n4 Researchers in parallel" -> "Synthesize approaches";
     "Synthesize approaches" -> "Present design sections";
@@ -242,18 +242,16 @@ Wait for the user's response. If they request changes, make them and re-run the
 - **Incremental validation** — Present design, get approval before moving on
 - **Be flexible** — Go back and clarify when something doesn't make sense
 
-## Visual Companion (Advanced Mode Only)
+## Visual Presentation Support (Advanced Mode Only)
 
-A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
+Use the `present` MCP tool for showing mockups, diagrams, and visual options during brainstorming. It is available as a tool, not a separate mode. Choosing this means you can present rich visual output when it helps; it does NOT mean every question should become visual.
 
-**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
-> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. The browser opens automatically when I start the visual companion. This feature is still new and can be token-intensive. Want to try it?"
+**Offering visual presentation:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
+> "Some of what we're working on might be easier to explain visually. I can use `present({ format: \"html\" })` to show mockups, diagrams, comparisons, and other visuals as we go. Want me to use that when helpful?"
 
 **This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
 
-**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use visual output or plain chat. The test: **would the user understand this better by seeing it than reading it?**
 
-- **Use the browser** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
-- **Use the terminal** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
-
-If they agree to the companion, read `visual-companion.md` for the detailed setup and usage guide.
+- **Use `present({ format: "html" })`** for visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use regular chat** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions

package/scaffold/general/skills/c4-architecture/SKILL.md

@@ -12,6 +12,7 @@ Generate software architecture documentation using C4 model diagrams in Mermaid
 1. **Understand scope** - Determine which C4 level(s) are needed based on audience
 2. **Analyze codebase** - Explore the system to identify components, containers, and relationships
 3. **Generate diagrams** - Create Mermaid C4 diagrams at appropriate abstraction levels
+  > **Tip:** Use `present({ format: "html" })` to render diagrams as interactive visual output, rather than raw Mermaid code blocks. This provides a better viewing experience for stakeholders.
 4. **Document** - Write diagrams to markdown files with explanatory context
 
 ## C4 Diagram Levels