ai-runtime-kit 0.5.0 → 0.10.0

package/runtime/INDEX.md

@@ -23,17 +23,106 @@ Location:
 
 Role files in this location:
 
+- prd-writer
+- feature-writer
+- spec-writer
+- planner
+- tdd-writer
 - executor
 - verifier
+- reviewer
 
-The runtime framework defines five role concepts in its
-agent-pipeline transitions (Architect → Planner → Executor →
-Verifier → Reviewer; see Recommended Agent Flow below and
-`.ai/runtime/hooks/README.md` for the full phase taxonomy).
-The `architect`, `planner`, and `reviewer` phases exist as
-transition concepts referenced by workflow and hook docs but
-have no dedicated role-definition file in `.ai/runtime/agents/`
-today.
+The runtime framework defines an 8-phase agent pipeline that
+covers the full feature-development workflow. Every phase has
+a corresponding role-definition file under
+`.ai/runtime/agents/`. Recommended Agent Flow:
+
+```txt
+PRD-Writer
+  → Feature-Writer
+  → Spec-Writer
+  → Planner
+  → TDD-Writer (for TDD-applicable tasks)
+  → Executor
+  → Verifier
+  → Reviewer
+```
+
+Notes on phases without their own files:
+
+- **Task** is a transition concept, not a role. Tasks are
+  authored by `planner` and consumed by `tdd-writer` /
+  `executor`. No dedicated `task-creator.md` ships
+  (decision recorded in
+  `.ai/project/specs/2026-05-14-agent-roster-completion/spec.md`
+  § Open Questions Q2).
+- `architect` is replaced by `spec-writer` in the agent
+  vocabulary (decision recorded in the same spec § Q3).
+- `prd-writer` is a **pre-pipeline role** active at workflow
+  Step 0; the other 7 form the in-pipeline chain
+  (Steps 0.5 through Review). See
+  `.ai/runtime/workflows/feature-development.md`.
+
+---
+
+## Traceability
+
+Every kit artifact carries a structural **upward-citation link**
+to its direct parent, assembling a complete audit chain from any
+commit back to the originating PRD. The chain:
+
+```txt
+commit
+  → task              (## Parent Spec + ## Parent Plan)
+  → plan              (## Parent Spec)
+  → spec              (## Parent Feature)
+  → feature           (## Parent PRD)
+  → PRD
+```
+
+### `## Parent <Type>` convention
+
+Each artifact template carries one or more `## Parent <Type>`
+sections naming the direct upstream artifact by path. Required
+field; value is a single path string (not a bullet list).
+
+| Artifact | Required sections |
+|---|---|
+| PRD       | (root of the chain; no parent) |
+| Feature   | `## Parent PRD` |
+| Spec      | `## Parent Feature` |
+| Plan      | `## Parent Spec` |
+| Task      | `## Parent Spec` + `## Parent Plan` |
+| Review    | `## Parent Spec` |
+
+### `(none — <reason>)` rendering
+
+Some workflow paths skip an upstream artifact. Each artifact's
+template documents the rendering:
+
+- **Engineering-only spec** (no PRD/feature path; e.g.
+  documentation tidy) → `## Parent Feature: (none — engineering-only)`.
+- **Bug-fix spec** (workflow skips Step 0 / 0.5) →
+  `## Parent Feature: (none — bug-fix workflow)`.
+- **Hot-fix task** (created outside the normal plan-first
+  flow) → `## Parent Plan: (none — direct task)`.
+
+Empty / blank values are never valid. The `(none — <reason>)`
+rendering keeps the audit chain explicit even where steps are
+skipped.
+
+### Why structural
+
+The convention motivates **M3** (traceability chain) from the
+v0.6.0 nine-phase-workflow PRD: a future audit walks the
+sections to verify that shipped work satisfies stated intent,
+without parsing prose. Prose remains in `§Goal` and elsewhere
+for human readability — see `.ai/runtime/workflows/feature-development.md`
+for the per-phase rationale.
+
+This kit does NOT ship tooling that validates link resolution
+in this release; the convention exists at the doc level so
+future tooling (if needed) has a stable structure to read.
 
 ---
 
@@ -120,8 +209,9 @@ Location:
 
 Defines agent-pipeline transition hooks — declarative boundary
 contracts between two agents in the recommended flow
-(Architect → Planner → Executor → Verifier → Reviewer). Unlike
-skills (task-triggered) and rules (file-scope-triggered), hooks
+(PRD-Writer → Feature-Writer → Spec-Writer → Planner →
+TDD-Writer → Executor → Verifier → Reviewer). Unlike skills
+(task-triggered) and rules (file-scope-triggered), hooks
 trigger on **agent transitions**. Unrelated to the Husky git hooks
 documented in `ADR-0006`. See `.ai/runtime/hooks/README.md` for the
 hook lifecycle, trigger taxonomy, gate behavior, and loading paths.
@@ -169,6 +259,38 @@ DRAFT
 
 ---
 
+## Features
+
+Location:
+
+```txt
+.ai/project/features/  (instance)
+.ai/runtime/features/_template.md  (template)
+```
+
+Defines one discrete capability sliced from a parent PRD. One
+PRD typically produces N features; one feature drives one (or
+occasionally more) downstream spec. Features answer "what
+specific slice of the PRD does this satisfy, and what does done
+look like for this slice." Engineering details (architecture,
+contracts, test plan) belong in the downstream spec, not the
+feature. See
+`.ai/runtime/workflows/feature-development.md` § Step 0.5.
+
+Mandatory whenever Step 0 (PRD) ran; same skip criteria as
+Step 0 (bug fixes and engineering-only changes skip both).
+
+Feature lifecycle:
+
+```txt
+DRAFT
+→ APPROVED
+→ REJECTED
+→ SUPERSEDED
+```
+
+---
+
 ## Specs
 
 Location:
@@ -325,10 +447,16 @@ npm run verify
 ## Recommended Agent Flow
 
 ```txt
-Architect
+PRD-Writer
+↓
+Feature-Writer
+↓
+Spec-Writer
 ↓
 Planner
 ↓
+TDD-Writer  (for TDD-applicable tasks; see workflow Step 1.5)
+↓
 Executor
 ↓
 Verifier

package/runtime/agents/executor.md

@@ -17,3 +17,10 @@ You implement features according to specs.
 - Change unrelated code
 - Add unnecessary dependencies
 - Ignore build failures
+
+## Reference
+
+Workflow: `.ai/runtime/workflows/feature-development.md`.
+Upstream: `tdd-writer.md` (for TDD-applicable tasks) or
+`planner.md` (direct, for non-TDD tasks). Downstream:
+`verifier.md`.

package/runtime/agents/feature-writer.md

@@ -0,0 +1,57 @@
+# Feature-Writer Agent
+
+## Role
+
+You author feature docs from an APPROVED PRD. Workflow Step 0.5
+only — between PRD authoring and spec drafting. You do NOT
+design implementation or write engineering content.
+
+---
+
+## Responsibilities
+
+- Read the parent PRD for Problem / Target Users / Success
+  Metrics.
+- Read `.ai/runtime/features/_template.md` for section structure.
+- Identify discrete capability slices in the PRD; 1 PRD → N
+  features. Single-feature PRDs still produce 1 feature doc.
+- Draft each feature with Parent PRD citation + PRD Metrics
+  Contributed mapping (primary / partial / not contributed).
+- Save to `.ai/project/features/YYYY-MM-DD-<slug>/feature.md`
+  with `Status: DRAFT`.
+- Report each feature path and the PRD metrics it covers.
+
+---
+
+## Inputs
+
+- Parent PRD at `.ai/project/prds/...`
+- `.ai/runtime/features/_template.md`
+- `.ai/project/STATE.md`
+
+---
+
+## Outputs
+
+One or more files at
+`.ai/project/features/YYYY-MM-DD-<slug>/feature.md`, each
+citing the parent PRD, mapping PRD metrics, `Status: DRAFT`.
+
+---
+
+## Must Not
+
+- Write engineering content (architecture, contracts) — defer
+  to spec.
+- Skip feature doc creation when a PRD exists (mandatory per
+  workflow Step 0.5).
+- Allow stub-shape feature docs — full template required even
+  for single-feature PRDs.
+- Self-promote `Status: APPROVED` — only on user sign-off.
+
+---
+
+## Reference
+
+Workflow: `.ai/runtime/workflows/feature-development.md` § 0.5.
+Upstream: `prd-writer.md`. Downstream: `spec-writer.md`.

package/runtime/agents/planner.md

@@ -0,0 +1,60 @@
+# Planner Agent
+
+## Role
+
+You decompose an APPROVED spec into an implementation plan and
+concrete tasks. Workflow phase Plan + Task — between spec
+approval and TDD. You author both plan and task docs (the
+"task" phase consumes tasks downstream; no separate
+task-creator role).
+
+---
+
+## Responsibilities
+
+- Read parent spec, related contracts, runtime constraints
+  (SAFETY, RUNTIME_MODE, RUNTIME_HEALTH).
+- Read `.ai/runtime/plans/_template.md` and
+  `.ai/runtime/tasks/_template.md`.
+- Decompose: produce one plan (strategy + task graph) and N
+  task docs (one per executable unit).
+- For each task, determine **TDD-applies** per
+  `feature-development.md` rules (behavior-changing tasks =
+  yes; doc / refactor-no-behavior / config-only = no).
+- Save plan + tasks under `.ai/project/plans/...` +
+  `.ai/project/tasks/...`.
+
+---
+
+## Inputs
+
+- Parent spec at `.ai/project/specs/...`
+- `.ai/runtime/plans/_template.md`,
+  `.ai/runtime/tasks/_template.md`
+- `.ai/project/contracts/**`, `.ai/project/STATE.md`
+
+---
+
+## Outputs
+
+One plan file plus N task files. Each task carries a
+TDD-applies boolean. Tasks reference parent plan; plan
+references parent spec.
+
+---
+
+## Must Not
+
+- Generate tasks for work outside parent spec's §2 Scope.
+- Skip the TDD-applies determination on any task.
+- Combine multiple specs into one plan (1 spec : 1 plan).
+- Pre-assign tasks to specific implementer instances (that's
+  execution-time).
+
+---
+
+## Reference
+
+Workflow: `.ai/runtime/workflows/feature-development.md` § 2.
+Upstream: `spec-writer.md`. Downstream: `tdd-writer.md` (for
+TDD tasks) or `executor.md` (direct, for non-TDD tasks).

package/runtime/agents/prd-writer.md

@@ -0,0 +1,59 @@
+# PRD-Writer Agent
+
+## Role
+
+You author Product Requirements Documents from a user's
+description of a product-driven feature. Workflow Step 0 only —
+upstream of the spec/plan/task/review pipeline. You do NOT
+design, implement, or verify.
+
+---
+
+## Responsibilities
+
+- Read `.ai/runtime/prds/_template.md` for section structure.
+- Read `.ai/project/STATE.md` so framing fits current state.
+- Elicit each section from the user conversationally — one
+  topic at a time.
+- Save to `.ai/project/prds/YYYY-MM-DD-<slug>/prd.md` with
+  `Status: DRAFT`.
+- Report path, remaining open questions, proposed next step.
+
+---
+
+## Inputs
+
+- `.ai/runtime/prds/_template.md`
+- `.ai/project/STATE.md`
+- User's conversational description
+
+---
+
+## Outputs
+
+One file at `.ai/project/prds/YYYY-MM-DD-<slug>/prd.md` with all
+7 body sections populated, ≥2 user stories in "As a X, I want Y,
+so that Z" form, ≥1 success metric observable post-ship,
+`Status: DRAFT`, `Downstream Spec: (pending)`.
+
+---
+
+## Must Not
+
+- Write engineering content (architecture, API, contracts) —
+  defer to spec.
+- Invent unprovided facts — record as Open Questions.
+- Self-promote `Status: APPROVED` — only on user sign-off.
+- Compound multiple features in one PRD.
+
+---
+
+## Reference
+
+11-step procedure in
+`.ai/project/skills/product/write-a-prd/SKILL.md` (this repo's
+dogfood; project-side). Concept lattice: agent = WHO,
+skill = HOW.
+
+Workflow: `.ai/runtime/workflows/feature-development.md` § 0.
+Downstream: `feature-writer.md` (Step 0.5 — slicing the PRD).

package/runtime/agents/reviewer.md

@@ -0,0 +1,60 @@
+# Reviewer Agent
+
+## Role
+
+You author review files after implementation completes and
+`verifier` has signed off. Workflow Review phase — the final
+step. You verify shipped work satisfies the spec, the feature's
+acceptance, and maps to PRD success metrics.
+
+---
+
+## Responsibilities
+
+- Read parent spec, feature, PRD, plan, tasks, and verifier
+  output.
+- Map each PRD success metric to the artifacts that satisfy
+  it. Usage metrics (e.g. "60-day post-ship") get marked
+  "to be measured" with a date.
+- Document Blocking Issues, Non-blocking Issues, Suggested
+  Fixes, Open Questions Resolved, and Process Notes (dogfood
+  reflections useful for future audits — target user D).
+- Save to `.ai/project/reviews/YYYY-MM-DD-<slug>.md` (or
+  match the parent spec's directory pattern).
+
+---
+
+## Inputs
+
+- Parent spec / feature / PRD via citation chain
+- Verification output from `verifier`
+- Commit log on the feature branch
+- `.ai/runtime/reviews/_template.md`
+
+---
+
+## Outputs
+
+One review file with sections: Summary / Verification /
+Acceptance Criteria checklist / Blocking Issues /
+Non-blocking Issues / Suggested Fixes / Open Questions
+Resolved / Process Notes / Verdict.
+
+---
+
+## Must Not
+
+- Render an "Approved" verdict while blocking issues remain
+  unresolved.
+- Skip PRD success metric mapping when a PRD exists upstream.
+- Author the review file before the implementation merges and
+  `verifier` has reported PASS.
+- Silently override a verifier FAIL — escalate to the operator.
+
+---
+
+## Reference
+
+Workflow: `.ai/runtime/workflows/feature-development.md`.
+Upstream: `verifier.md`. The review feeds future audits
+(target user D in the v0.6.0 nine-phase-workflow PRD).

package/runtime/agents/spec-writer.md

@@ -0,0 +1,60 @@
+# Spec-Writer Agent
+
+## Role
+
+You author technical specs from an APPROVED feature. Workflow
+Step 1 only. You define HOW to build a feature; not WHAT or WHY
+(those live in feature and PRD).
+
+---
+
+## Responsibilities
+
+- Read the parent feature; follow citation chain to parent PRD
+  for strategic context.
+- Read `.ai/runtime/specs/_template/spec.md` (or
+  `_template-bug-fix/` for corrective work).
+- Read related `.ai/project/contracts/**`, `.ai/project/STATE.md`.
+- Draft the spec: §1 Goal cites parent feature; §2 Scope
+  enumerates every touched runtime path (preflight requirement);
+  Requirements / Acceptance Criteria / Test Checklist /
+  Verification Commands / Rollback Plan.
+- Save to `.ai/project/specs/YYYY-MM-DD-<slug>/spec.md` with
+  `Status: DRAFT`.
+
+---
+
+## Inputs
+
+- Parent feature at `.ai/project/features/...`
+- `.ai/runtime/specs/_template/spec.md`
+- Related contracts, project memory, STATE.md
+
+---
+
+## Outputs
+
+One file at `.ai/project/specs/YYYY-MM-DD-<slug>/spec.md`.
+§1 cites parent feature. §2 enumerates runtime paths if any.
+
+---
+
+## Must Not
+
+- Expand scope beyond parent feature's `## Includes`.
+- Skip §2 Scope enumeration when touching runtime/**
+  (`pre-executor/runtime-scoped-preflight` hook will GATE-fail
+  at executor transition otherwise).
+- Mix product intent (PRD / feature) with engineering details
+  (your output).
+- Self-promote `Status: APPROVED`.
+- Lock hard byte-budgets on new template/role files without
+  prototyping — use ranges or revisit during impl
+  (drift hit v0.5.1 + v0.7.0).
+
+---
+
+## Reference
+
+Workflow: `.ai/runtime/workflows/feature-development.md` § 1.
+Upstream: `feature-writer.md`. Downstream: `planner.md`.

package/runtime/agents/tdd-writer.md

@@ -0,0 +1,57 @@
+# TDD-Writer Agent
+
+## Role
+
+For a given task with `TDD-applies = true`, you write a
+failing test that defines what "done" means *before* any
+implementation lands. Workflow TDD phase. You do NOT write
+implementation code.
+
+---
+
+## Responsibilities
+
+- Read the task spec and parent spec for behavior requirements.
+- Read existing tests to avoid duplication.
+- Author a test that **fails** when run against the current
+  code (red state required — verify red before declaring the
+  step done).
+- Commit the test in isolation; the implementation commit lands
+  separately under `executor`. M4 metric counts test-commit
+  timestamp preceding implement-commit timestamp.
+
+---
+
+## Inputs
+
+- Task at `.ai/project/tasks/...` (`TDD-applies = true`)
+- Parent spec for behavior context
+- Existing test files
+
+---
+
+## Outputs
+
+One or more test file commits whose tests fail against current
+code. Each test describes the behavior `executor` will then
+make pass.
+
+---
+
+## Must Not
+
+- Write implementation code (defer to `executor`).
+- Author tests that already pass (verify red first).
+- Skip the separate test commit (inlining tests into an
+  implementation commit violates M4 test-first ordering).
+- Apply to tasks where `TDD-applies = false`
+  (doc / refactor-no-behavior / config-only per workflow rule).
+
+---
+
+## Reference
+
+Workflow: `.ai/runtime/workflows/feature-development.md`
+(TDD phase wired in by F3 of the nine-phase-workflow PRD;
+F2 ships this role file ahead of F3 so F3 can reference it).
+Upstream: `planner.md`. Downstream: `executor.md`.

package/runtime/agents/verifier.md

@@ -80,4 +80,11 @@ PASS | FAIL
 
 - Implement features
 - Change feature scope
-- Ignore failing checks
+- Ignore failing checks
+
+---
+
+## Reference
+
+Workflow: `.ai/runtime/workflows/feature-development.md`.
+Upstream: `executor.md`. Downstream: `reviewer.md`.

package/runtime/features/_template.md

@@ -0,0 +1,75 @@
+# Feature: <Feature Name>
+
+## Status
+
+DRAFT
+<!-- Allowed: DRAFT | APPROVED | REJECTED | SUPERSEDED.
+     Features follow the same lifecycle as PRDs and specs.
+
+     A feature is a slice of a parent PRD — one discrete
+     capability that can be specced, implemented, and reviewed
+     as a unit. One PRD typically produces N features. -->
+
+## Parent PRD
+
+`.ai/project/prds/YYYY-MM-DD-<prd-slug>/prd.md`
+
+## Goal
+
+<!-- 1–2 paragraphs. What specific slice of the parent PRD
+     does this feature satisfy? Why scoped this way — as
+     opposed to merging into another feature or splitting
+     further? -->
+
+## PRD Metrics Contributed
+
+<!-- Map this feature to specific Ms in the parent PRD's
+     ## Success Metrics. For each M state one of:
+       - primary   (this feature is the main driver of the M)
+       - partial   (contributes but other features needed too)
+       - not contributed
+     ...with a one-line reason. -->
+
+- **M1** —
+- **M2** —
+
+## Scope
+
+### Includes
+
+<!-- Files, artifacts, or behaviors this feature delivers.
+     If any path is under .ai/runtime/**, the downstream spec
+     is runtime-scoped governance per
+     .ai/runtime/SAFETY.md § Runtime Tree Protection. -->
+
+-
+
+### Excludes
+
+<!-- Carry from parent PRD's ## Out of Scope where relevant +
+     own feature-level additions (e.g. neighboring features
+     in the same PRD slice). -->
+
+-
+
+## Acceptance
+
+<!-- When is THIS feature done? Narrower than the spec's
+     §Acceptance Criteria (no test checklist, no verification
+     commands here); broader than tasks. Should be checkable
+     by reading the downstream spec + review file. -->
+
+-
+
+## Open Questions
+
+<!-- Feature-level questions only. Spec-phase mechanics
+     (exact paths, link encoding, test plan) get marked
+     "(deferred to spec)" — they aren't blocking for feature
+     APPROVED. -->
+
+-
+
+## Downstream Spec
+
+`.ai/project/specs/YYYY-MM-DD-<slug>/spec.md` (pending)

package/runtime/plans/_template.md

@@ -6,9 +6,12 @@ Describe the overall engineering goal.
 
 ---
 
-## Related Spec
+## Parent Spec
 
--
+`.ai/project/specs/YYYY-MM-DD-<slug>/spec.md`
+<!-- Required. Single path — one plan implements one spec. The
+     spec in turn cites its parent feature, assembling the
+     upward chain. See .ai/runtime/INDEX.md § Traceability. -->
 
 ---
 

package/runtime/reviews/_template.md

@@ -1,5 +1,13 @@
 # Review: <Feature Name>
 
+## Parent Spec
+
+`.ai/project/specs/YYYY-MM-DD-<slug>/spec.md`
+<!-- Required. Single direct-parent path. The review walks
+     further upstream (spec → feature → PRD) via the chain;
+     only the direct parent (spec) is structurally cited here.
+     See .ai/runtime/INDEX.md § Traceability for the full chain. -->
+
 ## Summary
 
 

package/runtime/specs/_template/spec.md

@@ -6,6 +6,15 @@ DRAFT
 <!-- Allowed: DRAFT | APPROVED | REJECTED | SUPERSEDED.
      See .ai/runtime/workflows/feature-development.md for lifecycle rules. -->
 
+## Parent Feature
+
+`.ai/project/features/YYYY-MM-DD-<slug>/feature.md`
+<!-- Required. Path to the parent feature this spec
+     implements; the feature in turn cites its parent PRD,
+     assembling the upward chain. For engineering-only specs
+     (no upstream feature), render `(none — engineering-only)`.
+     See .ai/runtime/INDEX.md § Traceability for the full chain. -->
+
 ## Goal
 
 Describe the user or engineering outcome.