@vpxa/aikit 0.1.63 → 0.1.65

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

@@ -37,11 +37,45 @@ You are the **Documenter**, documentation specialist that creates and maintains
 | Architecture | Design decisions | Context, decision, consequences |
 | Changelog | After implementation | `changelog` tool, Keep a Changelog format |
 
-## Rules
+## Writing Style
 
-- **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
+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
+
+**Escape hatch** (Orwell Rule 6): Break any style rule sooner than write something unclear or unnatural.
 
 ## Skills (load on demand)
 
@@ -180,10 +214,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
 ```
@@ -419,6 +458,7 @@ Always return this structure when invoked as a sub-agent:
 |-------|--------------|
 | 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 |
 
 
 ## Flows

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

@@ -185,10 +185,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/general/agents/Implementer.agent.md

@@ -24,7 +24,7 @@ You are the **Implementer**, persistent implementation agent that writes code fo
 
 - **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
@@ -172,10 +172,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/general/agents/Orchestrator.agent.md

@@ -71,7 +71,7 @@ You orchestrate the full development lifecycle: **planning → implementation
      | 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.
@@ -85,7 +85,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.
 
@@ -94,8 +100,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):
@@ -133,8 +144,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`
 
@@ -153,11 +165,12 @@ Reviewers add findings to the Orchestrator's existing `evidence_map` `task_id` a
 |------|---------|
 | `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
 
@@ -260,6 +273,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").
 
@@ -273,7 +287,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
 ```

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

@@ -234,10 +234,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/general/agents/Refactor.agent.md

@@ -183,10 +183,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/general/agents/Security.agent.md

@@ -180,10 +180,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/general/agents/_shared/code-agent-base.md

@@ -126,10 +126,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/general/skills/aikit/SKILL.md

@@ -54,7 +54,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 — creates .flows/{topic}/
 list()                                                         # See stored knowledge
 search({ query: "SESSION CHECKPOINT", origin: "curated" })     # Resume prior work
 ```
@@ -134,6 +134,37 @@ remember({ title: "Session checkpoint: <topic>", content: "<what was done, decis
 | `list` | `aikit list` | List curated entries |
 | `produce_knowledge` | — | Auto-generate knowledge from analysis |
 
+### Auto-Knowledge (automatic background extraction)
+
+Auto-knowledge runs automatically in the background after every tool completion. It extracts useful facts from tool outputs and stores them in curated memory — no manual action required.
+
+**What gets captured:**
+
+| Extractor | Triggers on | What it stores |
+|-----------|-------------|----------------|
+| Test results | `check`, `test_run` | Framework detection (vitest/jest/mocha), test file naming patterns |
+| Environment | `env`, `config`, `status` | Node.js version, OS, workspace path, store backend, embedding model |
+| Research | `web_search`, `web_fetch`, `search` | Web research findings, fetched page summaries |
+| Conventions | `check`, `analyze_patterns`, `analyze_structure`, `onboard` | Linter/formatter, TypeScript strict mode, package manager, monorepo detection |
+| Build commands | `check`, `test_run` | Verified check results, test summaries, test runner commands |
+| Codebase insights | `analyze_*`, `scope_map`, `blast_radius`, `onboard` | Structure analysis, dependency info, entry points, impact analysis |
+| Tool failures | All tools (global) | Classified actionable errors (filters out transient network/ENOENT errors) |
+
+**Quality controls:**
+- **Quality gate**: Facts scored 0-1; only facts >= 0.3 are stored
+- **Dedup**: Checks existing curated titles + in-memory hash dedup
+- **TTL**: Transient facts (errors, blast radius, search context) automatically expire after 1-2 hours
+- **Session limit**: Maximum 50 auto-knowledge facts per session
+
+**Searching auto-knowledge:**
+Auto-knowledge facts are stored as regular curated entries. Search them with:
+```
+search({ query: "error patterns", origin: "curated" })
+search({ query: "conventions", origin: "curated" })
+list({ category: "conventions" })
+list({ tags: ["errors"] })
+```
+
 ### Verified Lanes (1 tool, 6 actions)
 | Tool | CLI | Purpose |
 |------|-----|---------|
@@ -190,16 +221,17 @@ Lane actions: `create` (copy files to lane), `list`, `status` (modified/added/de
 | `queue` | `aikit queue` | Task queue for sequential agent operations (create/push/next/done/fail) |
 | `replay` | `aikit replay` | View or clear the audit trail of tool invocations (action: list/clear) |
 
-### Flows (10)
+### Flows (11)
 | Tool | CLI | Purpose |
 |------|-----|---------|
-| `flow_list` | `aikit flow list` | List available flows |
+| `flow_list` | `aikit flow list` | List available flows and active run |
 | `flow_info` | `aikit flow info` | Get flow details including steps and skill paths |
-| `flow_start` | `aikit flow start` | Start a named flow |
+| `flow_start` | `aikit flow start` | Start a flow with topic — creates `.flows/{topic-slug}/` run directory |
 | `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_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 |
+| `flow_status` | `aikit flow status` | Check active run including slug, runDir, artifactsPath |
+| `flow_read_instruction` | `aikit flow read-instruction` | Read instruction with `{{artifacts_path}}` and `{{run_dir}}` resolved |
+| `flow_reset` | `aikit flow reset` | Abandon the active flow (preserves run directory) |
+| `flow_runs` | `aikit flow runs` | List all flow runs (current and past) |
 | `flow_add` | `aikit flow add` | Add a custom flow from a directory |
 | `flow_update` | `aikit flow update` | Update an existing custom flow |
 | `flow_remove` | `aikit flow remove` | Remove a custom flow |
@@ -242,14 +274,18 @@ Flows are multi-step guided workflows that structure complex tasks. Each step ha
 ```text
 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_instruction({ step: "assess" })  # Read current step's instructions
+flow_start({ flow: "aikit:basic", topic: "Fix login bug" })  # Start — creates .flows/fix-login-bug/
+flow_read_instruction()              # Read current step's instructions ({{artifacts_path}} resolved)
 # ... 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
-flow_status()                        # Check progress
-flow_reset()                         # Clear state, start over
+flow_status()                        # Check progress (includes slug, runDir, artifactsPath, phase, isEpilogue)
+flow_reset()                         # Abandon active flow
+flow_runs()                          # List all runs (current + past)
+# Epilogue steps (mandatory, injected after every flow):
+# After last flow step → _docs-sync epilogue runs automatically
+# flow_status() shows phase: 'after', isEpilogue: true during epilogue
 ```
 
 Custom flow lifecycle management:
@@ -680,7 +716,7 @@ Flows are structured multi-step workflows that guide agents through complex task
 
 | Tool | Purpose |
 |------|---------|
-| `flow_status` | Check if a flow is active + current step |
+| `flow_status` | Check if a flow is active + current step + phase (before/flow/after) + isEpilogue |
 | `flow_list` | List available flows |
 | `flow_info` | Get flow details including steps and skill paths |
 | `flow_start` | Start a named flow |
@@ -704,8 +740,9 @@ Flows are structured multi-step workflows that guide agents through complex task
 
 ### Flow Lifecycle
 
-1. **Start**: `flow_list({})` → choose flow → `flow_start({ flow: "<name>" })`
+1. **Start**: `flow_list({})` → choose flow → `flow_start({ flow: "<name>", topic: "<task>" })`
 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_instruction` for current step → continue
-5. **Reset**: `flow_reset({})` if you need to start over
+4. **Epilogue**: After last flow step, mandatory epilogue steps run (e.g., `_docs-sync` updates `docs/`)
+5. **Resume**: `flow_status({})` → if active, `flow_read_instruction` for current step → continue
+6. **Reset**: `flow_reset({})` if you need to start over