@vpxa/aikit 0.1.66 → 0.1.68

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpxa/aikit",
-  "version": "0.1.66",
+  "version": "0.1.68",
   "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>

package/scaffold/general/skills/c4-architecture/references/c4-syntax.md

@@ -484,6 +484,24 @@ Keep diagrams under 15 elements. Split complex architectures into multiple focus
 **Element Ordering:**
 Elements appear in the order they are defined. Reorder statements to adjust layout.
 
+### Special Characters
+
+Node labels and subgraph titles containing `@`, `/`, `#`, or other special characters must be quoted:
+
+```mermaid
+%% WRONG — will break parsing
+subgraph @scope/package
+  NodeA[@scope/lib]
+end
+
+%% CORRECT — quoted labels
+subgraph ScopePkg["@scope/package"]
+  NodeA["@scope/lib"]
+end
+```
+
+Use plain alphanumeric strings for node IDs (aliases). Put display names with special characters inside `["..."]`.
+
 ### Alternative Tools
 
 For features Mermaid doesn't support, consider:

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

@@ -206,6 +206,22 @@ How to confirm it worked.
 Common issues and solutions.
 ```
 
+### Decision Index Template (`docs/decisions/index.md`)
+
+```markdown
+# Architecture Decision Record Index
+
+This page is the ADR log for the project. IDs are assigned sequentially as decisions are recorded.
+
+## Index
+
+| ID | Title | Status | Date | Source |
+| --- | --- | --- | --- | --- |
+| ADR-001 | {Decision title} | {Accepted/Proposed/Deprecated/Superseded} | {YYYY-MM-DD} | [{flow-topic}]({relative-path-to-flow-artifact}) |
+```
+
+The **Source** column links to the flow artifact (typically `design.md` or `design-decisions.md`) where the decision was originally designed. Use the flow's run directory path relative to the index file location (e.g., `../../.flows/{topic}/{artifacts}/design.md`). If the decision was made outside a flow, use "Manual" or link to the relevant discussion.
+
 ### Reference Template (`docs/reference/{topic}.md`)
 
 ```markdown
@@ -229,6 +245,7 @@ Brief description of what this reference covers.
 - All ADRs live in `docs/decisions/`
 - When the docs-sync step detects an architecture decision was made during the flow, delegate to `adr-skill`
 - After `adr-skill` creates/updates an ADR, update `docs/decisions/index.md`
+- Include the Source column linking to the flow artifact where the decision was designed.
 - Cross-reference ADRs from component docs where relevant
 
 ### `c4-architecture` Integration
@@ -237,6 +254,14 @@ Brief description of what this reference covers.
 - Use Mermaid format for docs files (not HTML) — markdown renders in GitHub
 - Reference diagrams from component docs
 
+### Mermaid Syntax Rules
+
+When generating Mermaid diagrams in documentation:
+
+- **Quote node labels containing special characters** — Names with `@`, `/`, or other special characters must be wrapped in double quotes inside square brackets: `subgraph Commons["@scope/package-name"]`, `NodeId["@org/lib"]`
+- **Quote subgraph titles with special characters** — `subgraph Title["@scope/name"]` not `subgraph @scope/name`
+- Node IDs (aliases) must not contain special characters — use plain alphanumeric IDs and put the display name in `["..."]`
+
 ## Project Knowledge Acquisition
 
 Produces seven populated documents in `docs/architecture/` covering everything needed to work effectively on the project — stack, structure, design, conventions, integrations, testing, and concerns.
@@ -431,7 +456,7 @@ docs/
 │   ├── 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)
+│   └── index.md           ← ADR log with Source column linking to flow artifacts
 ├── guides/
 │   └── testing.md         ← From analyze_patterns test info
 └── reference/
@@ -483,6 +508,25 @@ Follow these rules when generating documentation content. Adapted from *The Elem
 - **No summary closers** — Do not end every paragraph by restating what it just said
 - **Consistent terminology** — Pick one term and use it throughout; do not alternate synonyms for variety
 
+## Link Rules
+
+### Relative Path Correctness
+
+All links in generated docs must be correct relative to the file that contains them. Compute the path from the target doc's directory, not from the project root.
+
+| Doc location | Link to `src/types/index.ts` | Link to `.flows/topic/artifacts/design.md` |
+|---|---|---|
+| `docs/README.md` | `../src/types/index.ts` | `../.flows/topic/artifacts/design.md` |
+| `docs/architecture/overview.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
+| `docs/decisions/index.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
+| `docs/reference/api.md` | `../../src/types/index.ts` | `../../.flows/topic/artifacts/design.md` |
+
+**Rules:**
+1. Count the directory depth from the doc file to `docs/`, then add `../` to reach the project root
+2. Verify every link target exists before writing it — use `find({ pattern })` if unsure
+3. Never use absolute paths in documentation — always relative
+4. Test links mentally: from `docs/architecture/overview.md`, `../../` reaches the project root
+
 ## Anti-Patterns
 
 ### Documentation Maintenance