@vpxa/aikit 0.1.63 → 0.1.65

package/scaffold/definitions/agents.mjs

@@ -21,6 +21,7 @@ export const AGENTS = {
     sharedBase: null, // Orchestrator has inline instructions
     sharedProtocols: ['decision-protocol', 'forge-protocol'],
     category: 'orchestration',
+    skills: [],
   },
 
   Planner: {
@@ -120,6 +121,10 @@ export const AGENTS = {
     skills: [
       ['aikit', '**Always** — AI Kit tool signatures, search, analysis'],
       ['present', 'When presenting documentation previews or architecture visuals to the user'],
+      [
+        'docs',
+        'When creating or updating project documentation — docs/ convention, architecture blueprints, Diátaxis framework',
+      ],
     ],
   },
 

package/scaffold/definitions/bodies.mjs

@@ -54,7 +54,7 @@ ${agentTable}
      | New feature, API design, architecture change, multi-component work | \`aikit:advanced\` |
      | Task matches a custom flow's description/tags exactly | That custom flow |
 
-   - **Auto-start:** When exactly one flow matches, start it immediately — \`flow_start({ flow: '<matched>' })\` — and inform the user which flow was activated and why.
+   - **Auto-start:** When exactly one flow matches, start it immediately — \`flow_start({ flow: '<matched>', topic: '<task description>' })\` — and inform the user which flow was activated and why. The \`topic\` becomes the \`.flows/\` directory name (slugified).
    - **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.
@@ -68,7 +68,13 @@ For EACH step in the active flow:
 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
+5. Repeat until all flow steps AND epilogue steps are complete
+
+**Epilogue steps** (mandatory, injected by aikit):
+- After the last flow step, the state machine transitions to epilogue steps (e.g., \`_docs-sync\`)
+- \`flow_status\` will show \`phase: 'after'\` and \`isEpilogue: true\` during epilogue
+- Delegate epilogue work to the appropriate agent (e.g., Documenter for \`_docs-sync\`)
+- Epilogue steps follow the same execution pattern: \`flow_read_instruction\` → do work → \`flow_step({ action: 'next' })\`
 
 **Custom flows work identically** — \`flow_list\` returns them alongside builtins. The execution loop is the same for ALL flows.
 
@@ -77,8 +83,13 @@ For EACH step in the active flow:
 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\`)
+- When the last flow step's \`flow_step({ action: 'next' })\` is called, the flow transitions to **mandatory epilogue steps** (e.g., \`_docs-sync\`)
+- Epilogue steps run automatically after every flow — they are NOT optional (but can be skipped with \`flow_step({ action: 'skip' })\` + warning)
+- The \`_docs-sync\` epilogue loads the \`docs\` skill and updates \`docs/\` based on changes made during the flow
+- After ALL epilogue steps complete, the flow reaches \`completed\` status
+- After completion: run post-implementation protocol (\`check\` → \`test_run\` → \`blast_radius\` → \`reindex\`)
+- Note: auto-knowledge facts are captured automatically from all tool outputs above
+- Then continue with \`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):
@@ -116,8 +127,9 @@ Batch 2 (after batch 1):
 2. **Goal** — acceptance criteria, testable
 3. **Arch Context** — code snippets from \`compact()\`/\`digest()\`
 4. **Constraints** — patterns, conventions
-5. **FORGE** — tier + task_id + evidence requirements (reviewers add CRITICAL/HIGH claims into your task_id; never create their own)
-6. **Self-Review** — checklist before declaring status
+5. **Artifacts Path** — the active flow's run directory and artifacts path from \`flow_status\` (e.g. \`.flows/add-authentication/.spec/\`)
+6. **FORGE** — tier + task_id + evidence requirements (reviewers add CRITICAL/HIGH claims into your task_id; never create their own)
+7. **Self-Review** — checklist before declaring status
 
 **Subagent status protocol:** \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`
 
@@ -136,11 +148,12 @@ Reviewers add findings to the Orchestrator's existing \`evidence_map\` \`task_id
 |------|---------|
 | \`flow_list\` | List installed flows and active flow |
 | \`flow_info\` | Get detailed flow info including steps |
-| \`flow_start\` | Start a named flow |
+| \`flow_start\` | Start a flow with a topic — creates \`.flows/{topic-slug}/\` run directory |
 | \`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_instruction\` | Read the instruction content for the current step |
+| \`flow_status\` | Check current execution state including slug, runDir, artifactsPath |
+| \`flow_reset\` | Abandon the active flow (preserves run directory for history) |
+| \`flow_read_instruction\` | Read the current step's instruction with \`{{artifacts_path}}\` resolved |
+| \`flow_runs\` | List all flow runs (current and past) with topic, status, progress |
 
 ## Emergency: STOP → ASSESS → CONTAIN → RECOVER → DOCUMENT
 
@@ -243,6 +256,7 @@ Before every tool call, verify:
 | \`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 |
+| \`docs\` | During \`_docs-sync\` epilogue — living documentation convention, templates, change-to-doc mapping |
 
 **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").
 
@@ -256,7 +270,7 @@ flow_status({})                                                # Check/resume ac
 status({})                                                     # Check AI Kit health + onboard state
 # If onboard not run → onboard({ path: "." })                 # First-time codebase analysis
 flow_list({})                                                  # See available flows
-# Select flow based on task → flow_start({ flow: "<name>" })  # Start flow if appropriate
+# Select flow based on task → flow_start({ flow: "<name>", topic: "<task>" })  # Start flow — creates .flows/{topic}/
 list()                                                         # See stored knowledge
 search({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work
 \`\`\`
@@ -397,7 +411,7 @@ When subagents complete, their visual outputs (from \`present\`) are NOT visible
 
 - **Test-first always** — No implementation without a failing test
 - **Minimal code** — Don't build what isn't asked for
-- **Follow existing patterns** — Search AI Kit for conventions before creating new ones
+- **Follow existing patterns** — Search AI Kit for conventions before creating new ones (\`search("convention")\`, \`list({ category: "conventions" })\`)
 - **Never modify tests to make them pass** — Fix the implementation instead
 - **Run \`check\` after every change** — Catch errors early
 - **Loop-break** — If the same test fails 3 times with the same error after your fixes, STOP. Re-read the error from scratch, check your assumptions with \`trace\` or \`symbol\`, and try a fundamentally different approach. Do not attempt a 4th fix in the same direction
@@ -469,7 +483,7 @@ If the pre-flight dev server cannot be started (e.g. sandbox), fall back to
 
 ## Debugging Protocol
 
-1. **AI Kit Recall** — Search for known issues matching this error pattern
+1. **AI Kit Recall** — \`search("error patterns")\` to find auto-captured error patterns; \`list({ tags: ["errors"] })\` for all error entries; search for known issues matching this error pattern
 2. **Reproduce** — Confirm the error, use \`parse_output\` on stack traces and build errors for structured analysis
 3. **Verify targets exist** — Before tracing, confirm the files and functions mentioned in the error actually exist. Use \`find\` or \`symbol\` to verify paths and signatures. **Never trace into a file you haven't confirmed exists**
 4. **Trace** — \`graph\` (module imports), \`symbol\` (definitions/references), \`trace\` (call chains) — start with \`graph\` to understand module relationships, then drill into symbols
@@ -604,11 +618,45 @@ For multi-approach uncertainty (A vs B), do NOT create lanes. Instead:
 | Architecture | Design decisions | Context, decision, consequences |
 | Changelog | After implementation | \`changelog\` tool, Keep a Changelog format |
 
-## Rules
+## Writing Style
+
+Rules adapted from *The Elements of Agent Style* (CC BY 4.0, Yue Zhao) and classic writing authorities (Strunk & White, Orwell, Pinker, Gopen & Swan). Apply these when generating any documentation.
+
+### Clarity and Precision
+
+| Rule | Do | Do Not |
+|------|-----|--------|
+| Concrete language | "The retry handler backs off exponentially" | "The relevant component handles the situation appropriately" |
+| No needless words | "Retries three times" | "It should be noted that the system retries a total of three times" |
+| Active voice | "The scheduler processes the queue" | "The queue is processed by the scheduler" |
+| Affirmative form | "Use UTC timestamps" | "Do not use non-UTC timestamps" (unless a warning) |
+| Calibrated claims | "Reduces latency by 40% in benchmarks (see perf.md)" | "Dramatically improves performance" |
+
+### Structure
+
+- **Parallel structure** — Express coordinate ideas in similar form: consistent table columns, consistent list item grammar, consistent heading patterns
+- **Stress position** — Place the most important information at the end of the sentence
+- **Sentence variety** — Split sentences over 30 words; alternate short and long sentences to maintain rhythm
+- **Bullets for lists only** — Do not convert flowing prose into bullet points; two items or a single sentence do not need bullets
+- **Consistent terms** — Pick one term per concept and use it throughout; do not alternate synonyms for variety
+
+### AI-Tell Avoidance (patterns to eliminate)
+
+- ❌ Dying metaphors: "cutting-edge", "leverages", "streamlines", "robust", "seamless", "game-changing", "next-generation"
+- ❌ Transition-word openers: "Additionally", "Furthermore", "Moreover", "It is worth noting that"
+- ❌ Em-dash overuse: use commas, semicolons, or separate sentences instead
+- ❌ Summary closers: do not end every paragraph by restating what it just said
+- ❌ Consecutive same-starts: do not begin consecutive sentences with the same word or phrase
+- ❌ Filler hedging: "It should be noted", "It is important to", "In order to" → just state the point
+
+### Core Principles
+
+- **Accuracy over completeness** — Correct and concise beats thorough and wrong
+- **Examples always** — Every API section needs a code example; every concept needs a concrete illustration
+- **Evidence-backed** — Support factual claims with file paths, tool output, or citations; do not fabricate
+- **Keep it current** — Update docs with every code change; stale docs are worse than no docs
 
-- **Accuracy over completeness** — Better to be correct and concise than thorough and wrong
-- **Examples always** — Every API docs section needs a code example
-- **Keep it current** — Update docs with every code change
+**Escape hatch** (Orwell Rule 6): Break any style rule sooner than write something unclear or unnatural.
 
 ## Skills (load on demand)
 

package/scaffold/definitions/plugins.mjs

@@ -127,4 +127,10 @@ export const PLUGINS = {
     source: 'scaffold/general/skills/typescript/SKILL.md',
     required: false,
   },
+  docs: {
+    description:
+      'Living documentation management — Diátaxis framework, docs/ convention, staleness detection, integration with adr-skill and c4-architecture',
+    source: 'scaffold/general/skills/docs/SKILL.md',
+    required: true,
+  },
 };

package/scaffold/definitions/protocols.mjs

@@ -134,10 +134,15 @@ Always follow this order when you need to understand something. **Never skip to
 | C4 architecture diagram | \`diagram.md\` |
 | Module graph with key symbols | \`code-map.md\` |
 
-### Step 2: Curated Knowledge (past decisions, remembered patterns)
+### Step 2: Curated Knowledge (past decisions, remembered patterns, auto-knowledge)
+
+Auto-knowledge captures facts automatically from tool outputs (conventions, errors, test results, research).
+Search it alongside manual knowledge:
 
 \`\`\`
-search("your keywords")    // searches curated + indexed content
+search("your keywords")    // searches curated + indexed content (includes auto-knowledge)
+search("error patterns")   // find auto-captured error patterns for current tools
+list({ category: "conventions" })  // see detected project conventions
 scope_map("what you need") // generates a reading plan
 list()                     // see all stored knowledge entries
 \`\`\`

package/scaffold/flows/_epilogue/steps/docs-sync/README.md

@@ -0,0 +1,120 @@
+# Epilogue: Documentation Sync
+
+> **This is a mandatory epilogue step.** It runs automatically after every flow completes to keep project documentation synchronized with code changes.
+
+## Objective
+
+Review the changes made during this flow and update the `docs/` folder using AI Kit analysis tools — never write docs from scratch when a tool can generate the foundation.
+
+## Prerequisites
+
+Load the `docs` skill before proceeding — it contains the full documentation convention, templates, architecture blueprint workflow, and change-to-doc mapping rules.
+
+## Instructions
+
+### 0. Gather Flow Artifacts
+
+Read all artifacts produced during this flow — they contain design decisions, requirements, and verification results that are the most valuable documentation input.
+
+```
+flow_status()                                           # Get artifactsPath
+find({ pattern: "*.md", path: "{{artifacts_path}}" })   # Discover all flow artifacts
+digest({ sources: [                                     # Compress artifacts for context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
+```
+
+Map each discovered artifact to documentation actions using the artifact-to-doc mapping from the `docs` skill. Different flows produce different artifacts — read everything `find()` returns and focus on content that contains decisions, requirements, and verification results.
+
+If no artifacts exist, proceed to Step 1 in source-only mode.
+
+### 1. Assess Changes (tool-driven)
+
+```
+git_context({})                                         # What changed in this flow
+blast_radius({ changed_files: ["<changed-files>"] })    # Impact analysis — which modules affected
+```
+
+Use the output to classify changes:
+
+| Change Signal | Documentation Action |
+|---------------|---------------------|
+| New files in `src/` | Potential new component doc |
+| Modified API surface | Update reference docs |
+| New package or module boundary | Update architecture overview |
+| Architecture decision made | Delegate to `adr-skill` |
+| Test-only or config-only changes | Likely skip |
+
+### 2. Apply the Change-to-Doc Mapping
+
+Follow the decision tree from the `docs` skill to determine which documentation actions are needed.
+
+### 3. Bootstrap `docs/` If Needed (full tool-driven workflow)
+
+If `docs/` doesn't exist, run the **Architecture Blueprint Workflow** from the `docs` skill:
+
+```
+# Step 1: Generate content with AI Kit tools
+produce_knowledge({ path: "." })                        # → Foundation for docs/README.md
+analyze_structure({ path: "." })                        # → docs/architecture/overview.md structure
+analyze_diagram({ path: "." })                          # → docs/architecture/ Mermaid diagrams
+analyze_dependencies({ path: "." })                     # → docs/architecture/overview.md deps section
+analyze_entry_points({ path: "." })                     # → docs/reference/api.md foundation
+analyze_patterns({ path: "." })                         # → docs/architecture/overview.md patterns
+
+# Step 2: Create the docs/ tree from tool outputs
+docs/
+├── README.md              ← From produce_knowledge + project context
+├── architecture/
+│   ├── overview.md        ← From analyze_structure + analyze_dependencies + analyze_diagram
+│   └── components/        ← From analyze_symbols per major component
+├── decisions/
+│   └── index.md           ← ADR log (delegate to adr-skill)
+├── guides/
+│   └── testing.md         ← From analyze_patterns test info
+└── reference/
+    └── api.md             ← From analyze_entry_points
+```
+
+Use the Architecture Blueprint sections from the `docs` skill as the template for each document.
+
+### 4. Update Existing Docs (tool-assisted)
+
+When `docs/` already exists:
+
+```
+compact({ path: "docs/architecture/overview.md", query: "section to update" })  # Read target section
+blast_radius({ changed_files: ["<files>"] })                                     # What's affected
+```
+
+- **Don't rewrite** — update the relevant sections of existing docs
+- **Don't duplicate** — if the information is in code comments or READMEs, reference it
+- Use `compact` to read existing doc sections before editing
+- Use `blast_radius` output to determine which sections need updating
+
+### 5. Delegate When Appropriate
+
+- Architecture decisions → `adr-skill` → `docs/decisions/`
+- Architecture diagrams → `c4-architecture` skill → `docs/architecture/`
+- Full architecture refresh → Run the Architecture Blueprint Workflow from `docs` skill
+
+### 6. Update Index
+
+If documents were added, removed, or renamed, update `docs/README.md` to reflect the current structure.
+
+### 7. Skip If Nothing Changed
+
+If the flow's changes don't warrant doc updates (e.g., pure bug fix with no revelations), report:
+- "No documentation updates needed"
+- Reason: (brief explanation)
+
+## Completion Criteria
+
+- [ ] `git_context` + `blast_radius` used to assess changes
+- [ ] Change-to-doc mapping applied from `docs` skill
+- [ ] `docs/` bootstrapped with tool outputs if it didn't exist
+- [ ] Relevant docs created or updated (or skipped with reason)
+- [ ] `docs/README.md` index is current
+- [ ] No placeholder/empty docs created — all content tool-generated or hand-written with purpose

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

@@ -67,4 +67,4 @@ When the Orchestrator activates a step:
 
 ## Artifacts
 
-All artifacts are stored in the `.spec/` directory relative to the project root.
+All artifacts are stored in the run directory under `.flows/{topic}/`. The template variable `{{artifacts_path}}` resolves to the actual path at runtime.

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

@@ -9,7 +9,7 @@ description: Implement all tasks from the task breakdown, dispatching agents in
 
 Before starting this step, verify:
 - [ ] Task breakdown approved with valid task graph
-- [ ] `.spec/<slug>/tasks.md` exists with defined batches and dependencies
+- [ ] `{{artifacts_path}}/tasks.md` exists with defined batches and dependencies
 
 If prerequisites are NOT met -> **backtrack to task step** (`flow_step({ action: 'redo' })` on previous step)
 
@@ -19,7 +19,7 @@ Execute all tasks from the breakdown, dispatching implementation agents in batch
 
 ## Inputs
 
-- `.spec/<slug>/tasks.md` — the atomic task list with dependencies and agent assignments
+- `{{artifacts_path}}/tasks.md` — the atomic task list with dependencies and agent assignments
 
 ## Process
 
@@ -38,7 +38,7 @@ Execute all tasks from the breakdown, dispatching implementation agents in batch
 
 ## Outputs
 
-Produce `.spec/<slug>/progress.md` with:
+Produce `{{artifacts_path}}/progress.md` with:
 
 ```markdown
 # Execution Progress: <feature title>
@@ -130,7 +130,7 @@ Follow the `multi-agents-development` skill patterns for dispatch:
 - [ ] `check({})` passes
 - [ ] `test_run({})` passes
 - [ ] No blocked items remaining
-- [ ] `.spec/<slug>/progress.md` written
+- [ ] `{{artifacts_path}}/progress.md` written
 
 ## Knowledge Capture
 

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

@@ -9,7 +9,7 @@ description: Analyze the codebase, design the architecture, and create a detaile
 
 Before starting this step, verify:
 - [ ] Specification approved with clarity score ≥90
-- [ ] `.spec/<slug>/spec.md` exists and is complete
+- [ ] `{{artifacts_path}}/spec.md` exists and is complete
 
 If prerequisites are NOT met → **backtrack to spec step** (`flow_step({ action: 'redo' })` on previous step)
 
@@ -19,7 +19,7 @@ Translate the specification into a concrete, phased implementation plan with arc
 
 ## Inputs
 
-- `.spec/<slug>/spec.md` — the validated specification
+- `{{artifacts_path}}/spec.md` — the validated specification
 
 ## Process
 
@@ -38,7 +38,7 @@ Translate the specification into a concrete, phased implementation plan with arc
 
 ## Outputs
 
-Produce `.spec/<slug>/plan.md` with:
+Produce `{{artifacts_path}}/plan.md` with:
 
 ```markdown
 # Implementation Plan: <feature title>
@@ -107,7 +107,7 @@ Load these skills BEFORE executing this step:
 - [ ] Architecture decisions documented with rationale
 - [ ] Dependency graph has no circular dependencies
 - [ ] Risks identified with mitigations
-- [ ] `.spec/<slug>/plan.md` written
+- [ ] `{{artifacts_path}}/plan.md` written
 
 ## Knowledge Capture
 

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

@@ -36,7 +36,7 @@ Transform a vague or broad feature request into a precise, testable specificatio
 
 ## Outputs
 
-Produce `.spec/<slug>/spec.md` with:
+Produce `{{artifacts_path}}/spec.md` with:
 
 ```markdown
 # Specification: <feature title>
@@ -106,7 +106,7 @@ Load these skills BEFORE executing this step:
 - [ ] Scope boundaries are explicit
 - [ ] Requirements clarity score ≥ 90
 - [ ] No open questions remain
-- [ ] `.spec/<slug>/spec.md` written
+- [ ] `{{artifacts_path}}/spec.md` written
 
 ## Knowledge Capture
 

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

@@ -9,7 +9,7 @@ description: Break the implementation plan into ordered, atomic tasks with depen
 
 Before starting this step, verify:
 - [ ] Implementation plan approved
-- [ ] `.spec/<slug>/plan.md` exists with defined phases
+- [ ] `{{artifacts_path}}/plan.md` exists with defined phases
 
 If prerequisites are NOT met → **backtrack to plan step** (`flow_step({ action: 'redo' })` on previous step)
 
@@ -19,7 +19,7 @@ Decompose the implementation plan into small, atomic tasks that agents can execu
 
 ## Inputs
 
-- `.spec/<slug>/plan.md` — the phased implementation plan
+- `{{artifacts_path}}/plan.md` — the phased implementation plan
 
 ## Process
 
@@ -35,7 +35,7 @@ Decompose the implementation plan into small, atomic tasks that agents can execu
 
 ## Outputs
 
-Produce `.spec/<slug>/tasks.md` with:
+Produce `{{artifacts_path}}/tasks.md` with:
 
 ```markdown
 # Task Breakdown: <feature title>
@@ -104,7 +104,7 @@ Load these skills BEFORE executing this step:
 - [ ] Dependencies form a DAG (no cycles)
 - [ ] Parallelism opportunities identified
 - [ ] Architect review confirms no integration risks
-- [ ] `.spec/<slug>/tasks.md` written
+- [ ] `{{artifacts_path}}/tasks.md` written
 
 ## Knowledge Capture
 

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

@@ -10,7 +10,7 @@ description: Dual code review, architecture review, security review, and compreh
 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
+- [ ] `{{artifacts_path}}/progress.md` exists with execution results
 
 If prerequisites are NOT met → **backtrack to execute step** (`flow_step({ action: 'redo' })` on previous step)
 
@@ -20,10 +20,10 @@ Perform thorough multi-perspective validation of all changes through parallel du
 
 ## Inputs
 
-- `.spec/<slug>/spec.md` — original requirements and acceptance criteria
-- `.spec/<slug>/plan.md` — architecture decisions and phase design
-- `.spec/<slug>/tasks.md` — task breakdown with per-task acceptance criteria
-- `.spec/<slug>/progress.md` — implementation status and changes made
+- `{{artifacts_path}}/spec.md` — original requirements and acceptance criteria
+- `{{artifacts_path}}/plan.md` — architecture decisions and phase design
+- `{{artifacts_path}}/tasks.md` — task breakdown with per-task acceptance criteria
+- `{{artifacts_path}}/progress.md` — implementation status and changes made
 
 ## Process
 
@@ -44,7 +44,7 @@ Perform thorough multi-perspective validation of all changes through parallel du
 
 ## Outputs
 
-Produce `.spec/<slug>/verify-report.md` with:
+Produce `{{artifacts_path}}/verify-report.md` with:
 
 ```markdown
 # Verification Report: <feature title>
@@ -130,7 +130,7 @@ After all reviews complete:
 - [ ] `test_run({})` passes
 - [ ] All spec acceptance criteria verified
 - [ ] FORGE gate passed (YIELD)
-- [ ] `.spec/<slug>/verify-report.md` written with clear verdict
+- [ ] `{{artifacts_path}}/verify-report.md` written with clear verdict
 
 ## Knowledge Capture
 

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

@@ -48,4 +48,4 @@ When the Orchestrator activates a step:
 
 ## Artifacts
 
-All artifacts are stored in the `.spec/` directory relative to the project root.
+All artifacts are stored in the run directory under `.flows/{topic}/`. The template variable `{{artifacts_path}}` resolves to the actual path at runtime.

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

@@ -38,7 +38,7 @@ If any prerequisites are missing or incomplete:
 
 ## Outputs
 
-Produce `.spec/<slug>/assessment.md` with:
+Produce `{{artifacts_path}}/assessment.md` with:
 
 ```markdown
 # Assessment: <task title>
@@ -94,7 +94,7 @@ Load these skills BEFORE executing this step:
 - [ ] Implementation approach is concrete (not vague)
 - [ ] Risks documented with mitigations
 - [ ] No unresolved open questions that block implementation
-- [ ] `.spec/<slug>/assessment.md` written
+- [ ] `{{artifacts_path}}/assessment.md` written
 
 ## Knowledge Capture
 

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

@@ -11,7 +11,7 @@ Execute the implementation plan from the assessment, writing production code and
 
 ## Inputs
 
-- `.spec/<slug>/assessment.md` — the approach, affected files, and risks
+- `{{artifacts_path}}/assessment.md` — the approach, affected files, and risks
 
 ## Prerequisites Check
 
@@ -28,7 +28,7 @@ If any prerequisites are missing or incomplete:
 
 ## Process
 
-1. **Read assessment** — Load `.spec/<slug>/assessment.md` and internalize the approach
+1. **Read assessment** — Load `{{artifacts_path}}/assessment.md` and internalize the approach
 2. **Set up tests first** — Where applicable, write failing tests that define success
 3. **Implement changes** — Follow the approach steps sequentially
    - One logical change per commit-worthy chunk
@@ -39,7 +39,7 @@ If any prerequisites are missing or incomplete:
 
 ## Outputs
 
-Produce `.spec/<slug>/progress.md` with:
+Produce `{{artifacts_path}}/progress.md` with:
 
 ```markdown
 # Implementation Progress: <task title>
@@ -116,7 +116,7 @@ Follow the `multi-agents-development` skill patterns for dispatch:
 - [ ] `check({})` passes (no type/lint errors)
 - [ ] `test_run({})` passes (no test failures)
 - [ ] No files modified outside assessed scope
-- [ ] `.spec/<slug>/progress.md` written
+- [ ] `{{artifacts_path}}/progress.md` written
 
 ## Knowledge Capture
 

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

@@ -11,8 +11,8 @@ Validate that the implementation meets the original requirements, passes all qua
 
 ## Inputs
 
-- `.spec/<slug>/assessment.md` — original requirements and approach
-- `.spec/<slug>/progress.md` — what was implemented and any deviations
+- `{{artifacts_path}}/assessment.md` — original requirements and approach
+- `{{artifacts_path}}/progress.md` — what was implemented and any deviations
 
 ## Prerequisites Check
 
@@ -42,7 +42,7 @@ If any prerequisites are missing or incomplete:
 
 ## Outputs
 
-Produce `.spec/<slug>/verify-report.md` with:
+Produce `{{artifacts_path}}/verify-report.md` with:
 
 ```markdown
 # Verification Report: <task title>
@@ -108,7 +108,7 @@ After all reviews complete:
 - [ ] Code review complete with no blocking issues
 - [ ] Security review complete
 - [ ] Blast radius assessed
-- [ ] `.spec/<slug>/verify-report.md` written with clear PASS/FAIL verdict
+- [ ] `{{artifacts_path}}/verify-report.md` written with clear PASS/FAIL verdict
 
 ## Knowledge Capture
 

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

@@ -13,7 +13,7 @@ You are the **Debugger**, expert debugger that diagnoses issues, traces errors,
 
 ## Debugging Protocol
 
-1. **AI Kit Recall** — Search for known issues matching this error pattern
+1. **AI Kit Recall** — `search("error patterns")` to find auto-captured error patterns; `list({ tags: ["errors"] })` for all error entries; search for known issues matching this error pattern
 2. **Reproduce** — Confirm the error, use `parse_output` on stack traces and build errors for structured analysis
 3. **Verify targets exist** — Before tracing, confirm the files and functions mentioned in the error actually exist. Use `find` or `symbol` to verify paths and signatures. **Never trace into a file you haven't confirmed exists**
 4. **Trace** — `graph` (module imports), `symbol` (definitions/references), `trace` (call chains) — start with `graph` to understand module relationships, then drill into symbols
@@ -159,10 +159,15 @@ Always follow this order when you need to understand something. **Never skip to
 | C4 architecture diagram | `diagram.md` |
 | Module graph with key symbols | `code-map.md` |
 
-### Step 2: Curated Knowledge (past decisions, remembered patterns)
+### Step 2: Curated Knowledge (past decisions, remembered patterns, auto-knowledge)
+
+Auto-knowledge captures facts automatically from tool outputs (conventions, errors, test results, research).
+Search it alongside manual knowledge:
 
 ```
-search("your keywords")    // searches curated + indexed content
+search("your keywords")    // searches curated + indexed content (includes auto-knowledge)
+search("error patterns")   // find auto-captured error patterns for current tools
+list({ category: "conventions" })  // see detected project conventions
 scope_map("what you need") // generates a reading plan
 list()                     // see all stored knowledge entries
 ```