@vpxa/aikit 0.1.66 → 0.1.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "type": "module",
   "description": "Local-first AI developer toolkit — knowledge base, code analysis, context management, and developer tools for LLM agents",
   "license": "MIT",

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

@@ -65,7 +65,9 @@ Run `forge_ground({ task, root_path: "." })` to:
 
 **Auto-upgrade check**: If `forge_ground` reveals contract-type unknowns or security concerns not caught by initial `forge_classify`, recommend tier upgrade.
 
-### 6. Produce `design-decisions.md`
+### 6. Write `{{artifacts_path}}/design-decisions.md` to disk
+
+**You MUST create this file on disk** using `create_file` or equivalent — do not just present content in chat.
 
 ```markdown
 ## Design Decisions
@@ -122,9 +124,13 @@ After user approves:
 
 **Do NOT call `flow_step`** — let the Orchestrator advance the flow.
 
+## Outputs
+
+Write `{{artifacts_path}}/design-decisions.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat. This file is a prerequisite for the next step.
+
 ## Produces
 
-- `design-decisions.md` — FORGE tier, approach, key decisions, constraints, risks
+- `{{artifacts_path}}/design-decisions.md` — FORGE tier, approach, key decisions, constraints, risks
 
 ## Agents
 
@@ -153,6 +159,14 @@ Load these skills BEFORE executing this step:
 - Artifact content and summaries → present with structured layout
 - Only use plain text for brief confirmations and simple questions
 
+## Completion Criteria
+
+- [ ] `{{artifacts_path}}/design-decisions.md` written to disk (NOT just presented in chat)
+- [ ] FORGE tier determined and documented
+- [ ] Brainstorming session completed (for Standard+ tier)
+- [ ] Key design decisions documented with rationale
+- [ ] User approval received (🛑 MANDATORY STOP)
+
 ## Knowledge Capture
 
 Before completing this step, persist important findings using `remember()`:

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

@@ -38,7 +38,9 @@ Execute all tasks from the breakdown, dispatching implementation agents in batch
 
 ## Outputs
 
-Produce `{{artifacts_path}}/progress.md` with:
+Write `{{artifacts_path}}/progress.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Execution Progress: <feature title>

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

@@ -38,7 +38,9 @@ Translate the specification into a concrete, phased implementation plan with arc
 
 ## Outputs
 
-Produce `{{artifacts_path}}/plan.md` with:
+Write `{{artifacts_path}}/plan.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Implementation Plan: <feature title>

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

@@ -36,7 +36,9 @@ Transform a vague or broad feature request into a precise, testable specificatio
 
 ## Outputs
 
-Produce `{{artifacts_path}}/spec.md` with:
+Write `{{artifacts_path}}/spec.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Specification: <feature title>

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

@@ -35,7 +35,9 @@ Decompose the implementation plan into small, atomic tasks that agents can execu
 
 ## Outputs
 
-Produce `{{artifacts_path}}/tasks.md` with:
+Write `{{artifacts_path}}/tasks.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Task Breakdown: <feature title>

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

@@ -44,7 +44,9 @@ Perform thorough multi-perspective validation of all changes through parallel du
 
 ## Outputs
 
-Produce `{{artifacts_path}}/verify-report.md` with:
+Write `{{artifacts_path}}/verify-report.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Verification Report: <feature title>

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

@@ -38,7 +38,9 @@ If any prerequisites are missing or incomplete:
 
 ## Outputs
 
-Produce `{{artifacts_path}}/assessment.md` with:
+Write `{{artifacts_path}}/assessment.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Assessment: <task title>

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

@@ -18,13 +18,14 @@ Classify the task into one of these categories:
 | **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`:
+**If the task is a bug fix or refactor**, write `{{artifacts_path}}/design-decisions.md` to disk:
 ```markdown
 ## Design Decisions
 - **Task type**: Bug fix / Refactor
 - **Design gate**: Auto-skipped — no design work needed
 - **Proceed to**: Assessment
 ```
+**You MUST create this file on disk** at the exact `{{artifacts_path}}/design-decisions.md` path — do not just present the content in chat.
 Then report `DONE` to the Orchestrator so the flow advances.
 
 ### 2. Quick Design (Small Features Only)
@@ -39,7 +40,7 @@ For small features that need minimal design:
 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`**:
+4. **Write `{{artifacts_path}}/design-decisions.md`** to disk:
 
 ```markdown
 ## Design Decisions
@@ -66,9 +67,13 @@ When complete, report status:
 
 **Do NOT call `flow_step`** — let the Orchestrator advance the flow.
 
+## Outputs
+
+Write `{{artifacts_path}}/design-decisions.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat. This file is a prerequisite for the next step.
+
 ## Produces
 
-- `design-decisions.md` — Task classification, FORGE tier, key design decisions
+- `{{artifacts_path}}/design-decisions.md` — Task classification, FORGE tier, key design decisions
 
 ## Agents
 
@@ -96,6 +101,10 @@ Load these skills BEFORE executing this step:
 
 ## Completion Criteria
 
+- [ ] `{{artifacts_path}}/design-decisions.md` written to disk (NOT just presented in chat)
+- [ ] FORGE tier determined (for small features)
+- [ ] Key design decisions documented
+
 ## Knowledge Capture
 
 Before completing this step, persist important findings using `remember()`:

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

@@ -39,7 +39,9 @@ If any prerequisites are missing or incomplete:
 
 ## Outputs
 
-Produce `{{artifacts_path}}/progress.md` with:
+Write `{{artifacts_path}}/progress.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Implementation Progress: <task title>

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

@@ -42,7 +42,9 @@ If any prerequisites are missing or incomplete:
 
 ## Outputs
 
-Produce `{{artifacts_path}}/verify-report.md` with:
+Write `{{artifacts_path}}/verify-report.md` to disk. **You MUST create this file** using `create_file` or equivalent — do not just present content in chat.
+
+Template:
 
 ```markdown
 # Verification Report: <task title>