@vpxa/aikit 0.1.65 → 0.1.67

package/scaffold/general/skills/docs/references/diataxis-templates.md

@@ -1,120 +1,120 @@
-# Diataxis Templates
-
-Templates for Tutorial and Explanation documents. For How-To and Reference templates, see the main docs SKILL.md.
-
-## Tutorial Template
-
-**Location**: `docs/guides/tutorials/{topic}.md`
-**Quadrant**: Tutorial (learning-oriented, practical)
-
-```markdown
----
-type: tutorial
----
-
-# Tutorial: {Title — Start with a Verb Phrase}
-
-> **What you'll build/learn**: One sentence describing the concrete outcome.
-
-## Prerequisites
-
-- {Prerequisite 1} — [install guide](link)
-- {Prerequisite 2}
-
-## Steps
-
-### 1. {First Visible Result}
-
-{Concrete action with immediate, visible output.}
-
-```bash
-{command or code}
-```
-
-> **You'll see**: {expected output — always show what success looks like}
-
-### 2. {Build on Step 1}
-
-{Next concrete action that builds on the previous result.}
-
-> **You'll see**: {expected output}
-
-### 3. {Complete the Goal}
-
-{Final action that achieves the tutorial's stated outcome.}
-
-> **You'll see**: {final result matching the "What you'll build" promise}
-
-## What You Learned
-
-{One-paragraph summary of skills acquired. No new concepts here.}
-
-## Next Steps
-
-- [How to {related task}](../guides/{topic}.md) — apply what you learned
-- [{Topic} Reference](../../reference/{topic}.md) — full API details
-- [About {concept}](../../architecture/{topic}.md) — understand the design
-```
-
-### Tutorial Rules
-
-1. **Always show results** — every step must have a "You'll see" block
-2. **Linear path only** — no branching, no optional steps, no alternatives
-3. **No explanations** — if the reader asks "why?", link to an Explanation doc
-4. **Concrete outcome** — the tutorial must produce something visible (output, file, running service)
-5. **Minimum viable scope** — teach ONE thing; link to other tutorials for more
-
-## Explanation Template
-
-**Location**: `docs/architecture/{topic}.md` or `docs/decisions/NNN-{title}.md`
-**Quadrant**: Explanation (understanding-oriented, theoretical)
-
-```markdown
----
-type: explanation
----
-
-# About {Topic}
-
-## Context
-
-{Why this topic matters. What problem or question it addresses. Set the stage.}
-
-## Background
-
-{Historical context, prior art, or constraints that shaped the current approach.}
-
-## How It Works
-
-{Discursive description — connections between components, data flow, design reasoning.}
-{NO step-by-step procedures — link to How-To guides for that.}
-
-## Design Decisions
-
-{Why this approach was chosen over alternatives.}
-{Link to ADRs where they exist: [ADR-NNN](../decisions/NNN-{title}.md)}
-
-## Trade-Offs
-
-| Gained | Sacrificed |
-|--------|-----------|
-| {benefit} | {cost} |
-
-## Related
-
-- [How to {task}](../guides/{topic}.md) — practical application
-- [{API} Reference](../reference/{topic}.md) — technical details
-- [Tutorial: {topic}](../guides/tutorials/{topic}.md) — hands-on introduction
-```
-
-### Explanation Rules
-
-1. **Take a position** — good explanation has perspective and opinion
-2. **Connect concepts** — show relationships, not isolated facts
-3. **No procedures** — if you write "Step 1:", move it to a How-To doc
-4. **Bounded scope** — explain ONE concept/decision/pattern per document
-5. **Link to evidence** — reference ADRs, code, or analysis tool output
-
----
-
+# Diataxis Templates
+
+Templates for Tutorial and Explanation documents. For How-To and Reference templates, see the main docs SKILL.md.
+
+## Tutorial Template
+
+**Location**: `docs/guides/tutorials/{topic}.md`
+**Quadrant**: Tutorial (learning-oriented, practical)
+
+```markdown
+---
+type: tutorial
+---
+
+# Tutorial: {Title — Start with a Verb Phrase}
+
+> **What you'll build/learn**: One sentence describing the concrete outcome.
+
+## Prerequisites
+
+- {Prerequisite 1} — [install guide](link)
+- {Prerequisite 2}
+
+## Steps
+
+### 1. {First Visible Result}
+
+{Concrete action with immediate, visible output.}
+
+```bash
+{command or code}
+```
+
+> **You'll see**: {expected output — always show what success looks like}
+
+### 2. {Build on Step 1}
+
+{Next concrete action that builds on the previous result.}
+
+> **You'll see**: {expected output}
+
+### 3. {Complete the Goal}
+
+{Final action that achieves the tutorial's stated outcome.}
+
+> **You'll see**: {final result matching the "What you'll build" promise}
+
+## What You Learned
+
+{One-paragraph summary of skills acquired. No new concepts here.}
+
+## Next Steps
+
+- [How to {related task}](../guides/{topic}.md) — apply what you learned
+- [{Topic} Reference](../../reference/{topic}.md) — full API details
+- [About {concept}](../../architecture/{topic}.md) — understand the design
+```
+
+### Tutorial Rules
+
+1. **Always show results** — every step must have a "You'll see" block
+2. **Linear path only** — no branching, no optional steps, no alternatives
+3. **No explanations** — if the reader asks "why?", link to an Explanation doc
+4. **Concrete outcome** — the tutorial must produce something visible (output, file, running service)
+5. **Minimum viable scope** — teach ONE thing; link to other tutorials for more
+
+## Explanation Template
+
+**Location**: `docs/architecture/{topic}.md` or `docs/decisions/NNN-{title}.md`
+**Quadrant**: Explanation (understanding-oriented, theoretical)
+
+```markdown
+---
+type: explanation
+---
+
+# About {Topic}
+
+## Context
+
+{Why this topic matters. What problem or question it addresses. Set the stage.}
+
+## Background
+
+{Historical context, prior art, or constraints that shaped the current approach.}
+
+## How It Works
+
+{Discursive description — connections between components, data flow, design reasoning.}
+{NO step-by-step procedures — link to How-To guides for that.}
+
+## Design Decisions
+
+{Why this approach was chosen over alternatives.}
+{Link to ADRs where they exist: [ADR-NNN](../decisions/NNN-{title}.md)}
+
+## Trade-Offs
+
+| Gained | Sacrificed |
+|--------|-----------|
+| {benefit} | {cost} |
+
+## Related
+
+- [How to {task}](../guides/{topic}.md) — practical application
+- [{API} Reference](../reference/{topic}.md) — technical details
+- [Tutorial: {topic}](../guides/tutorials/{topic}.md) — hands-on introduction
+```
+
+### Explanation Rules
+
+1. **Take a position** — good explanation has perspective and opinion
+2. **Connect concepts** — show relationships, not isolated facts
+3. **No procedures** — if you write "Step 1:", move it to a How-To doc
+4. **Bounded scope** — explain ONE concept/decision/pattern per document
+5. **Link to evidence** — reference ADRs, code, or analysis tool output
+
+---
+
 *Templates follow the Diátaxis documentation framework (CC-BY-SA 4.0, Daniele Procida).*

package/scaffold/general/skills/docs/references/flow-artifacts-guide.md

@@ -1,70 +1,70 @@
-# Flow Artifacts Guide
-
-## What Are Flow Artifacts
-
-Flows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.
-
-Use artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.
-
-## How to Discover Artifacts
-
-```text
-flow_status()                                      # Get artifactsPath
-find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files
-digest({ sources: [                                # Compress into working context
-  { path: "<found-artifact-1>" },
-  { path: "<found-artifact-2>" },
-  ...
-]})
-```
-
-Read every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.
-
-## Artifact Catalog
-
-| Artifact | Flow | Contains |
-|---|---|---|
-| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |
-| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |
-| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |
-| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |
-| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |
-| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |
-| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |
-
-## Artifact-to-Documentation Mapping
-
-| Artifact | Contains | Documentation Target | Action |
-|---|---|---|---|
-| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |
-| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |
-| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |
-| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |
-| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |
-| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |
-| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |
-| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |
-| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |
-
-## Reading Strategy
-
-Read every artifact `find()` returns. Triage by content type:
-
-| Content Signal | Documentation Value | Action |
-|---|---|---|
-| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |
-| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |
-| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |
-| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |
-
-Skip artifacts that only repeat completed work with no insights beyond the code diff.
-
-> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.
-
-## What Not to Document
-
-| Avoid | Do Instead |
-|---|---|
-| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |
-| Documenting every task or progress update | Keep only durable insights that help future readers |
+# Flow Artifacts Guide
+
+## What Are Flow Artifacts
+
+Flows produce structured markdown artifacts in `{{artifacts_path}}/`. These files capture requirements, decisions, plan shape, implementation progress, and verification results for the completed flow.
+
+Use artifacts to document the why behind changes. Code diffs still matter, but artifacts usually contain the rationale, constraints, risks, and review findings that should shape durable documentation.
+
+## How to Discover Artifacts
+
+```text
+flow_status()                                      # Get artifactsPath
+find({ pattern: "*.md", path: "<artifactsPath>" }) # Discover artifact files
+digest({ sources: [                                # Compress into working context
+  { path: "<found-artifact-1>" },
+  { path: "<found-artifact-2>" },
+  ...
+]})
+```
+
+Read every artifact `find()` returns. Different flows produce different files — do not assume specific filenames exist.
+
+## Artifact Catalog
+
+| Artifact | Flow | Contains |
+|---|---|---|
+| `design-decisions.md` | `aikit:basic`, `aikit:advanced` | FORGE tier, approach, key decisions, constraints, and risks |
+| `assessment.md` | `aikit:basic` | Goal, affected files, approach steps, risks, and open questions |
+| `spec.md` | `aikit:advanced` | Requirements, acceptance criteria, and scope boundaries |
+| `plan.md` | `aikit:advanced` | Phased implementation plan and architecture decisions |
+| `tasks.md` | `aikit:advanced` | Atomic task list, dependencies, and agent assignments |
+| `progress.md` | `aikit:basic`, `aikit:advanced` | Changes made, tests, deviations, and validation results |
+| `verify-report.md` | `aikit:basic`, `aikit:advanced` | Verdict, quality gates, review findings, security, and recommendation |
+
+## Artifact-to-Documentation Mapping
+
+| Artifact | Contains | Documentation Target | Action |
+|---|---|---|---|
+| `design-decisions.md` | FORGE tier, approach, key decisions | `docs/decisions/` | Create or update ADRs via `adr-skill` for each key decision |
+| `design-decisions.md` | Architecture approach, constraints | `docs/architecture/overview.md` | Update the design rationale section |
+| `spec.md` | Requirements, acceptance criteria | `docs/reference/` | Update API or component reference when public surface changed |
+| `plan.md` | Architecture decisions, phase design | `docs/architecture/` | Update architecture docs with structural changes |
+| `tasks.md` | Task breakdown, dependencies | Usually skip | Only document if it reveals new component boundaries |
+| `progress.md` | Files changed, deviations, tests | `docs/guides/testing.md` | Update when testing strategy changed |
+| `progress.md` | Deviations from plan | `docs/decisions/` | Document significant deviations as ADRs |
+| `verify-report.md` | Code review findings, security | `docs/architecture/overview.md` | Update if findings reveal architectural patterns |
+| `verify-report.md` | Security concerns | `docs/guides/` | Create or update security guidance when concerns are material |
+
+## Reading Strategy
+
+Read every artifact `find()` returns. Triage by content type:
+
+| Content Signal | Documentation Value | Action |
+|---|---|---|
+| Decisions, rationale, constraints | High — durable knowledge | Extract into `docs/decisions/` or architecture docs |
+| Requirements, scope, acceptance criteria | High — defines intent | Update reference docs if public surface changed |
+| Review findings, security concerns, quality gates | Medium — surfaces issues | Update architecture or guides if findings are material |
+| Implementation progress, task lists | Low — transient | Document only meaningful deviations from the plan |
+
+Skip artifacts that only repeat completed work with no insights beyond the code diff.
+
+> The catalog and mapping tables above list artifacts from built-in flows (`aikit:basic`, `aikit:advanced`). Custom flows may produce entirely different artifacts — always discover dynamically with `find()` and classify by content, not by filename.
+
+## What Not to Document
+
+| Avoid | Do Instead |
+|---|---|
+| Copying artifact text verbatim into `docs/` | Extract decisions, rationale, constraints, and stable guidance |
+| Documenting every task or progress update | Keep only durable insights that help future readers |
 | Mirroring temporary planning details | Preserve the final reasoning, not the transient workflow chatter |

package/scaffold/general/skills/docs/references/project-knowledge-gotchas.md

@@ -1,32 +1,32 @@
-# Project Knowledge — Gotchas
-
-Common pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).
-
-## Environment Gotchas
-
-**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
-
-**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
-
-**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don't map directly to the filesystem. Map aliases to real paths before documenting structure.
-
-**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.
-
-**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.
-
-**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.
-
-**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.
-
-**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.
-
-## Anti-Pattern Table
-
-| ❌ Don't | ✅ Do instead |
-|---------|--------------|
-| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |
-| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what's actually there |
-| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |
-| Document `dist/` or `build/` naming patterns as conventions | Source files only |
-| Assume README describes current architecture | Cross-reference with actual file structure via `analyze_structure` |
+# Project Knowledge — Gotchas
+
+Common pitfalls when documenting project knowledge. Reference this during Phase 2 (Investigate) and Phase 4 (Validate).
+
+## Environment Gotchas
+
+**Monorepos:** Root `package.json` may have no source — check for `workspaces`, `packages/`, or `apps/` directories. Each workspace may have independent dependencies and conventions. Map each sub-package separately.
+
+**Outdated README:** README often describes intended architecture, not the current one. Cross-reference with actual file structure before treating any README claim as fact.
+
+**TypeScript path aliases:** `tsconfig.json` `paths` config means imports like `@/foo` don't map directly to the filesystem. Map aliases to real paths before documenting structure.
+
+**Generated/compiled output:** Never document patterns from `dist/`, `build/`, `generated/`, `.next/`, `out/`, or `__pycache__/`. These are artefacts — document source conventions only.
+
+**`.env.example` reveals required config:** Secrets are never committed. Read `.env.example`, `.env.template`, or `.env.sample` to discover required environment variables.
+
+**`devDependencies` ≠ production stack:** Only `dependencies` (or equivalent) runs in production. Document linters, formatters, and test frameworks separately as dev tooling in `stack.md`.
+
+**Test TODOs ≠ production debt:** TODOs inside test directories are coverage gaps, not production technical debt. Separate them in `concerns.md`.
+
+**High-churn files = fragile areas:** Files appearing most in recent `git_context({})` output have the highest modification rate and likely hidden complexity. Always note them in `concerns.md`.
+
+## Anti-Pattern Table
+
+| ❌ Don't | ✅ Do instead |
+|---------|--------------|
+| "Uses Clean Architecture with Domain/Data layers" (when no such directories exist) | State only what directory structure actually shows |
+| "This is a Next.js project" (without checking `package.json`) | Check `dependencies` first. State what's actually there |
+| Guess the database from a variable name like `dbUrl` | Check manifest for `pg`, `mysql2`, `mongoose`, `prisma`, etc. |
+| Document `dist/` or `build/` naming patterns as conventions | Source files only |
+| Assume README describes current architecture | Cross-reference with actual file structure via `analyze_structure` |
 | Treat test TODOs as production tech debt | Separate coverage gaps from production concerns in `concerns.md` |