@vpxa/aikit 0.1.63 → 0.1.64

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/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.
@@ -133,8 +133,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 +154,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
 
@@ -273,7 +275,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/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
 ```
@@ -190,16 +190,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 +243,15 @@ 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)
+flow_reset()                         # Abandon active flow
+flow_runs()                          # List all runs (current + past)
 ```
 
 Custom flow lifecycle management:
@@ -704,7 +706,7 @@ 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