ai-runtime-kit 0.5.0 → 0.9.0

package/runtime/specs/_template-bug-fix/spec.md

@@ -6,6 +6,15 @@ DRAFT
 <!-- Allowed: DRAFT | APPROVED | REJECTED | SUPERSEDED.
      See .ai/runtime/workflows/bug-fix.md for lifecycle rules. -->
 
+## Parent Feature
+
+(none — bug-fix workflow)
+<!-- Bug-fix workflow skips Step 0.5 (no feature slicing) — the
+     fix is corrective, not a sliced PRD feature. Override with
+     a real path only if the bug fix happens to be part of a
+     larger PRD-driven effort. See .ai/runtime/INDEX.md
+     § Traceability for the full chain. -->
+
 ## 1. Goal
 
 Describe the corrective outcome in one paragraph. Focus on what

package/runtime/tasks/_template.md

@@ -6,9 +6,20 @@ Describe the specific engineering goal.
 
 ---
 
-## Related Spec
+## Parent Spec
 
--
+`.ai/project/specs/YYYY-MM-DD-<slug>/spec.md`
+<!-- Required. Single path. -->
+
+---
+
+## Parent Plan
+
+`.ai/project/plans/YYYY-MM-DD-<slug>/plan.md`
+<!-- Required. Single path. For hot-fix tasks created outside
+     the normal plan-first workflow, render
+     `(none — direct task)`. See .ai/runtime/INDEX.md
+     § Traceability for the full chain. -->
 
 ---
 
@@ -64,6 +75,18 @@ TODO
 
 executor
 
+## TDD-Applies
+
+false
+<!-- Allowed: true | false.
+     Rule: true if the task introduces or modifies runtime
+     behavior (code that runs); false for documentation, refactor
+     with no behavior change, or config / packaging / metadata
+     only. When true, follow workflow Step 1.5 — a failing-test
+     commit must precede the implementation commit. When false,
+     state a one-line reason here so the skip is explicit
+     rather than implicit. -->
+
 ## Blocked By
 
 None.

package/runtime/workflows/feature-development.md

@@ -50,6 +50,12 @@ Metrics, User Stories, Out of Scope, Open Questions,
 Stakeholders. Engineering details (architecture, data flow, code
 contracts) belong in the downstream spec, not the PRD.
 
+Read `.ai/runtime/agents/prd-writer.md` to anchor the role — it
+scopes the agent's responsibilities, inputs, outputs, and
+constraints. The procedural depth (the 11-step elicit-then-write
+flow) lives in a project-side skill referenced from the agent
+file; concept lattice is **agent = WHO, skill = HOW.**
+
 Skip this step when:
 
 - the change is corrective (use `bug-fix.md` instead — bug fixes
@@ -60,9 +66,43 @@ Skip this step when:
   intent.
 
 PRD lifecycle mirrors specs: `DRAFT → APPROVED → REJECTED →
-SUPERSEDED`. An APPROVED PRD authorizes spec drafting. The
-downstream spec MUST reference its PRD by path in §1 Goal so
-review can verify the spec satisfies the PRD.
+SUPERSEDED`. An APPROVED PRD authorizes feature slicing (Step
+0.5).
+
+### 0.5. Slice into Features
+
+When Step 0 ran (a PRD exists), slice it into **≥1 feature
+docs** under:
+
+```txt
+.ai/project/features/YYYY-MM-DD-<slug>/feature.md
+```
+
+One feature per discrete capability that can be specced and
+implemented independently. The feature doc answers "what slice
+of the PRD does this satisfy, and what does done look like" —
+mid-level between PRD ("what & why") and spec ("how").
+Engineering details (architecture, contracts, test plan) belong
+in the spec, not the feature.
+
+Use `.ai/runtime/features/_template.md` as the starting point.
+Each feature must cite its parent PRD in `## Parent PRD`; the
+PRD's `## Downstream Spec` section lists the features that
+derived from it.
+
+**Mandatory whenever Step 0 ran.** Same skip criteria as Step 0:
+bug-fix workflow and engineering-only changes skip Step 0
+entirely, so they skip Step 0.5 too.
+
+Single-feature PRDs still produce **one feature doc with the
+full template structure** — sections may contain "see parent
+PRD" pointers when the content is fully captured upstream, but
+no 5-line stub allowance (consistent shape protects
+traceability tooling and audit clarity).
+
+Feature lifecycle mirrors specs: `DRAFT → APPROVED → REJECTED →
+SUPERSEDED`. An APPROVED feature authorizes spec drafting for
+that feature.
 
 ### 1. Define Spec
 
@@ -72,9 +112,12 @@ Create a feature spec under:
 .ai/project/specs/YYYY-MM-DD-feature-name/spec.md
 ```
 
-If the spec is downstream of a PRD (Step 0), §1 Goal must cite
-the PRD path so reviewers can check that the spec covers the
-PRD's requirements without quietly expanding scope.
+If the spec is downstream of a feature (Step 0.5), §1 Goal must
+cite the feature path (the feature in turn cites its parent
+PRD, so the chain assembles upward). Reviewers walk the chain to
+check that the spec covers the feature's requirements without
+quietly expanding scope and that the feature covers its share of
+the PRD's metrics.
 
 Spec must include:
 
@@ -86,8 +129,45 @@ Spec must include:
 - Verification Commands
 - Rollback Plan
 
+### 1.5. TDD Phase (per task, when applicable)
+
+For each task produced under the spec's plan: if the task
+carries `TDD-Applies: true` (see
+`.ai/runtime/tasks/_template.md` § TDD-Applies), a **failing-
+test commit must land before** that task's implementation
+commit. The role file for this step is
+`.ai/runtime/agents/tdd-writer.md`.
+
+**Trigger.** Task's `TDD-Applies` value is `true`. The
+boundary follows parent-PRD-style rules: behavior-changing
+tasks → `true`; doc / refactor-with-no-behavior-change /
+config-only → `false`.
+
+**Required artifact.** A separate commit whose diff contains
+only the failing test(s) for the task. Verify red (test
+actually fails) before declaring the step done. The
+implementation commit lands on a distinct commit hash with a
+later timestamp, satisfying the test that was just authored.
+
+**Skip rule.** Tasks with `TDD-Applies: false` skip this step
+entirely. The skip is explicit on the task itself (the
+`## TDD-Applies` section in the task file states the boolean
+plus a one-line reason); never implicit.
+
+**Per-task semantics.** This is not a single workflow-wide
+pause. Step 1.5 runs once *per applicable task*, interleaved
+with that task's implementation. A feature with N
+TDD-applicable tasks fires Step 1.5 N times.
+
 ### 2. Execute with Claude Code
 
+> Step 1.5 is a per-task prerequisite for any task with
+> `TDD-Applies: true`. The execute step below covers plan
+> authoring, task production, implementation, and verification
+> as one umbrella; the TDD discipline runs *inside* that
+> umbrella, per applicable task, before each task's
+> implementation commit.
+
 Claude Code must read:
 
 - `.ai/runtime/agents/executor.md`

package/src/init.js

@@ -11,6 +11,7 @@ const { isPathGitignored } = require('./git');
 
 const PROJECT_SKELETON_DIRS = [
   'prds',
+  'features',
   'specs',
   'plans',
   'tasks',