@vpxa/aikit 0.1.19 → 0.1.21

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

@@ -0,0 +1,107 @@
+# Design Gate — Basic Flow
+
+Lightweight design gate for bug fixes, small features, and refactoring. Evaluates the task type and determines whether design work is needed before proceeding.
+
+## When This Step Runs
+
+This is the **first step** of the `aikit:basic` flow. It runs before assessment.
+
+## Instructions
+
+### 1. Task Classification
+
+Classify the task into one of these categories:
+
+| Category | Indicators | Action |
+|----------|-----------|--------|
+| **Bug fix** | Error reports, stack traces, regression, "fix", "broken" | → **Auto-skip** to next step |
+| **Refactor** | Code cleanup, rename, restructure, no behavior change | → **Auto-skip** to next step |
+| **Small feature** | New behavior, new endpoint, new component, UI change | → Run **Quick Design** below |
+
+**If the task is a bug fix or refactor**, produce a minimal `design-decisions.md`:
+```markdown
+## Design Decisions
+- **Task type**: Bug fix / Refactor
+- **Design gate**: Auto-skipped — no design work needed
+- **Proceed to**: Assessment
+```
+Then report `DONE` to the Orchestrator so the flow advances.
+
+### 2. Quick Design (Small Features Only)
+
+For small features that need minimal design:
+
+1. **FORGE Classify** — Run `forge_classify({ task: "<task description>", files: [<relevant files>] })` to determine complexity tier
+2. **Brainstorming** (if tier ≥ Standard) — Load the `brainstorming` skill and run a focused brainstorming session:
+   - What is the user trying to achieve?
+   - What are the constraints?
+   - What is the simplest approach?
+3. **Decision Protocol** (if technical decisions exist) — Delegate to 2-4 Researcher agents in parallel:
+   - Each researcher evaluates a different approach
+   - Synthesize findings into a recommendation
+4. **Produce `design-decisions.md`**:
+
+```markdown
+## Design Decisions
+
+### FORGE Assessment
+- **Tier**: {Floor | Standard | Critical}
+- **Rationale**: {why this tier}
+
+### Task Summary
+- **Goal**: {what we're building}
+- **Approach**: {chosen approach}
+- **Key decisions**: {list}
+
+### Constraints
+- {constraint 1}
+- {constraint 2}
+```
+
+### 3. Report to Orchestrator
+
+When complete, report status:
+- `DONE` — design decisions captured, ready for assessment
+- `DONE_WITH_CONCERNS` — design captured but open questions remain (list them)
+
+**Do NOT call `flow_step`** — let the Orchestrator advance the flow.
+
+## Produces
+
+- `design-decisions.md` — Task classification, FORGE tier, key design decisions
+
+## Agents
+
+- `Researcher-Alpha`, `Researcher-Beta`, `Researcher-Gamma`, `Researcher-Delta` — for parallel research during decision protocol
+
+## 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

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

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

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

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

package/scaffold/general/skills/requirements-clarity/SKILL.md

@@ -70,7 +70,7 @@ When invoked, detect vague requirements:
 1. Parse and understand core requirement
 2. Generate feature name (kebab-case format)
 3. Determine document version (default `1.0` unless user specifies otherwise)
-4. Ensure `./docs/prds/` exists for PRD output
+4. Ensure `.spec/{feature_name}/` exists for PRD output
 5. Perform initial clarity assessment (0-100)
 
 **Assessment Rubric**:
@@ -85,6 +85,8 @@ Technical Specificity: /25 points
 - Integration points identified: 8 pts
 - Constraints specified: 9 pts
 
+
+If you present this rubric or a requirements scorecard to the user, use `present({ format: 'html' })` to display a rich dashboard when visual formatting would help.
 Implementation Completeness: /25 points
 - Edge cases considered: 8 pts
 - Error handling mentioned: 9 pts
@@ -191,9 +193,9 @@ Once clarity score ≥ 90, generate comprehensive PRD.
 
 **Output File**:
 
-1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md`
+1. **Final PRD**: `.spec/{feature_name}/requirements.md`
 
-Use the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).
+Use `create_file` to save this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).
 
 ## PRD Document Structure
 

package/scaffold/general/skills/session-handoff/SKILL.md

@@ -20,6 +20,8 @@ Determine which mode applies:
 **Proactive suggestion?** After substantial work (5+ file edits, complex debugging, major decisions), suggest:
 > "We've made significant progress. Consider creating a handoff document to preserve this context for future sessions. Say 'create handoff' when ready."
 
+> **aikit Integration:** If the project uses the aikit MCP server, complement file-based handoffs with `remember({ title: "Session checkpoint: ...", content: "...", category: "conventions" })` to persist key decisions in the knowledge base. Use `search({ query: "SESSION CHECKPOINT" })` at session start to retrieve past checkpoints.
+
 ## CREATE Workflow
 
 ### Step 1: Generate Scaffold