@dzhechkov/skills-feature-adr 1.3.3 → 1.3.5

package/README.md

@@ -1,8 +1,18 @@
 # @dzhechkov/skills-feature-adr
 
-**Adaptive Feature Development skill pack for Claude Code**
+**Spec-Driven Development pipeline for AI coding agents (Claude Code, Codex, …)**
 
-11-step pipeline with Complexity Router (S/M/L/XL) for developing features of any scale — from a 3-file config change to a cross-cutting 30+ file refactoring. Integrates 15 skills from [agentic-qe](https://github.com/proffesor-for-testing/agentic-qe) for comprehensive quality engineering. Part of the [Keysarium](https://www.npmjs.com/package/@dzhechkov/keysarium) ecosystem.
+An 11-step, complexity-routed pipeline that makes an AI coding agent build a feature the way a
+disciplined engineering team does: **spec first, code last.** Every phase emits a durable,
+versioned, human-approved **specification artifact** (`00_…`–`08_…`), and code is *generated from
+the frozen spec* — not reverse-documented after the fact. Scales from a 3-file config change to a
+cross-cutting 30+ file refactor via a Complexity Router (S/M/L/XL). Integrates 15 skills from
+[agentic-qe](https://github.com/proffesor-for-testing/agentic-qe) for quality engineering. Part of
+the [Keysarium](https://www.npmjs.com/package/@dzhechkov/keysarium) ecosystem.
+
+> **For your team:** the `features/<slug>/` folder this produces *is* the spec — reviewable in a PR,
+> onboarding doc for free, every decision captured as an ADR, and machine-checked back against the
+> code by the QE phase. See **[Spec-Driven Development](#spec-driven-development-sdd)** below.
 
 ---
 
@@ -96,6 +106,90 @@ ARCHITECTURE → IMPLEMENTATION →  CODE   →   QE
 
 ---
 
+## Spec-Driven Development (SDD)
+
+Feature ADR is a **spec-driven** pipeline. The point is not to write documentation — it's to make
+the **specification the executable contract** that drives the code, and to keep the agent from ever
+skipping ahead to implementation before the spec is agreed. Three ideas make that real.
+
+### 1. The artifacts *are* the spec — one layered document, built top-down
+
+Each phase emits a spec artifact at a different altitude. Together they form a single, traceable
+specification chain from intent to verified code:
+
+| Artifact | Spec layer | Answers |
+|----------|-----------|---------|
+| `00_complexity_assessment.md` | **Scope spec** | How big is this? Which phases are even needed? |
+| `01_requirements.md` | **Behavioral spec** | What must be true when we're done? (SMART, testable) |
+| `02_research.md` | **Prior-art spec** | What patterns/analogues constrain the design? |
+| `03_adr/00N-*.md` | **Decision spec** | Which option, and *why* — with ≥2 alternatives + trade-offs |
+| `03.5_ideation_report.md` | **Quality-risk spec** | HTSM/SFDIPOT risks + a GO / CONDITIONAL / NO-GO verdict |
+| `04_domain_model.md` | **Domain spec** | Entities, aggregates, invariants (DDD) |
+| `05_architecture.md` + `diagrams/` | **Structural spec** | C4 + sequence diagrams; components & contracts |
+| `06_implementation_plan.md` | **Task spec** | SPARC-GOAP milestones — the plan the code must follow |
+| `07_code_changes/` | **The implementation** | Code in the repo + a `change_manifest.md` |
+| `08_qe_report.md` / `09_fleet_qe_assessment.md` | **Conformance spec** | Does the code satisfy the spec? Traceability + gaps |
+
+The spec is **version-controlled** (numbered files under `features/<slug>/`) and reviewable in a
+pull request exactly like code. Code is **Step 7** — the second-to-last thing that happens.
+
+### 2. The spec is a typed contract carried forward — not prose that gets ignored
+
+Each phase's output becomes a **cross-phase variable** that downstream phases *consume as input*, so
+a later phase can't silently contradict an earlier decision — it's building on a fixed upstream spec:
+
+```
+{REQUIREMENTS} → {RESEARCH_FINDINGS} → {ADR_DECISIONS} → {IDEATION_VERDICT}/{QUALITY_RISKS}
+             → {DOMAIN_MODEL} → {ARCHITECTURE} → {IMPL_PLAN} → {CODE_CHANGES} → {QE_RESULTS}
+```
+
+e.g. Step 5 (Architecture) *requires* `{ADR_DECISIONS}` as input — "architecture without an ADR"
+is a blocked anti-pattern. Step 7 (Code) consumes `{IMPL_PLAN}`; "code without a plan" is blocked.
+
+### 3. Every spec layer is *gated* — machine-checkable + human-approved
+
+Two gates guard the boundary between phases, so the spec is enforced, not aspirational:
+
+- **Promise tags** — each phase must emit a completion token before the next may start:
+  `FEATURE_ADR_ROUTED → …_REQUIREMENTS_GATHERED → …_DESIGNED → …_QUALITY_ASSESSED → …_ARCHITECTED
+  → …_PLANNED → …_IMPLEMENTED → …_VERIFIED → …_FLEET_VERIFIED`. A missing/`_INCOMPLETE` promise
+  halts the pipeline.
+- **Checkpoints** — after each phase the agent stops and shows you the artifact for approval
+  (`"ок"` → next, `"углуби X"` → elaborate, free text → adjust). **You co-author and freeze the
+  spec** one layer at a time; the agent never runs a 30-file feature unattended.
+
+### 4. The loop closes — code is verified *against* the spec
+
+This is what separates SDD from "write a design doc, then wing it." The QE phases trace the
+implementation **back to the specification**:
+
+- **`qe-requirements-validation`** builds a traceability matrix (`01_requirements.md` ⇄ code ⇄ tests).
+- **Gap-detection loop** in Step 8 must close with **zero remaining gaps** — every requirement is
+  covered or the pipeline blocks.
+- For L/XL, **Step 9 Fleet QE** adds risk-based, regression, integration and coverage checks and
+  emits `COMPLETE` or `NEEDS_REMEDIATION`.
+
+So a requirement that never got implemented, or code that satisfies no requirement, is caught by a
+gate — not discovered in production.
+
+### SDD principle → how Feature ADR implements it
+
+| SDD principle | In this pipeline |
+|---------------|------------------|
+| Spec before code | Steps 0–6 produce specs; code is Step 7 |
+| Executable / enforced spec | Cross-phase variables + promise-tag gates + zero-gap QE loop |
+| Decisions are first-class | ADRs with ≥2 alternatives + trade-offs (`03_adr/`) |
+| Human stays in control | A checkpoint after every phase; NO-GO verdict blocks |
+| Spec ⇄ code traceability | Requirements-validation matrix + gap loop (Steps 8–9) |
+| Right-sized ceremony | Complexity Router: S-tier skips ADR/DDD/architecture entirely |
+| Spec is a durable asset | Numbered, versioned artifacts in `features/<slug>/`, PR-reviewable |
+
+> **Tip for teams:** treat `features/<slug>/` as the deliverable of the *design* PR, merged and
+> reviewed **before** the implementation PR. The ADRs and architecture diagrams become your living
+> documentation; the QE report is your acceptance evidence.
+
+---
+
 ## Complexity Tiers
 
 | Tier | Scope | Active Steps | Time Budget |
@@ -120,22 +214,42 @@ ARCHITECTURE → IMPLEMENTATION →  CODE   →   QE
 
 ## Pipeline Steps
 
-| Step | Name | Tiers | Model | Agentic QE Skill | Output |
-|------|------|-------|-------|------------------|--------|
-| 0 | Complexity Router | All | haiku | — | `00_complexity_assessment.md` |
-| 1 | Requirements | All | sonnet | — | `01_requirements.md` |
-| 2 | Research | L/XL | sonnet | — | `02_research.md` |
-| 3 | ADR + Shift-Left | M+ | opus | shift-left-testing | `03_adr/001-*.md` |
-| 3.5 | QCSD Ideation Swarm | M+ | sonnet | qcsd-ideation-swarm | `03.5_ideation_report.md` |
-| 4 | DDD | L/XL | opus | — | `04_domain_model.md` |
-| 5 | Architecture | M+ | opus | — | `05_architecture.md` + diagrams |
-| 6 | SPARC-GOAP Plan | All | sonnet | code-goal-planner | `06_implementation_plan.md` |
-| 7 | Code | All | opus | tdd-london-chicago* | `07_code_changes/` |
-| 8 | QE + Brutal Honesty | All | sonnet | brutal-honesty-review | `08_qe_report.md` |
-| 9 | Fleet QE | L/XL | sonnet | 5 skills (4 agents) | `09_fleet_qe_assessment.md` |
+| Step | Name | Tiers | Model | Fable? | Agentic QE Skill | Output |
+|------|------|-------|-------|:------:|------------------|--------|
+| 0 | Complexity Router | All | haiku | ✅ | — | `00_complexity_assessment.md` |
+| 1 | Requirements | All | sonnet | ✅ | — | `01_requirements.md` |
+| 2 | Research | L/XL | sonnet | ✅ | — | `02_research.md` |
+| 3 | ADR + Shift-Left | M+ | opus | ⚠️ | shift-left-testing | `03_adr/001-*.md` |
+| 3.5 | QCSD Ideation Swarm | M+ | sonnet | ✅ | qcsd-ideation-swarm | `03.5_ideation_report.md` |
+| 4 | DDD | L/XL | opus | ⚠️ | — | `04_domain_model.md` |
+| 5 | Architecture | M+ | opus | ⚠️ | — | `05_architecture.md` + diagrams |
+| 6 | SPARC-GOAP Plan | All | sonnet | ✅ | code-goal-planner | `06_implementation_plan.md` |
+| 7 | Code | All | opus | ⚠️ | tdd-london-chicago* | `07_code_changes/` |
+| 8 | QE + Brutal Honesty | All | sonnet | ✅ | brutal-honesty-review | `08_qe_report.md` |
+| 9 | Fleet QE | L/XL | sonnet | ⚠️ | 5 skills (4 agents) | `09_fleet_qe_assessment.md` |
 
 *\* Extended skills (marked with \*) are only available with `--full-qe-extended`*
 
+### The `Model` / `Fable?` columns — read this before swapping models
+
+The `Model` column is the **default recommendation, fully overridable** — the routing rule is
+"phase difficulty → model tier": a fast tier for classification, a mid tier (`sonnet`) for
+structured drafting / QE synthesis, a top tier (`opus`) for load-bearing judgment.
+
+The **`Fable?`** column flags where switching to **Fable** is low-risk to try:
+
+- **✅ Fable-friendly** — drafting / classification / synthesis phases that are **gated by a
+  checkpoint and cheap to redo** (0 Router, 1 Requirements, 2 Research, 3.5 Ideation, 6 Plan,
+  8 QE draft). If Fable holds quality here, you gain speed/cost with a human gate right after.
+- **⚠️ Validate first** — **load-bearing reasoning** phases where a wrong call cascades downstream
+  (3 ADR decisions, 4 DDD, 5 Architecture, 7 Code, 9 Fleet QE). Keep the `opus`/`sonnet` default
+  unless you've A/B-validated Fable on your codebase.
+
+> **How to decide with data, not vibes:** install with `--with-learning` and run 2–3 features with
+> Fable on the ✅ steps; compare the reward patterns / rework counts against your `sonnet` baseline.
+> The pipeline's own reward tracker tells you where Fable is safe. This table is a **starting
+> heuristic**, not a benchmark — tune per project.
+
 ---
 
 ## Output Structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Adaptive Feature Development skill pack for Claude Code — 11-step pipeline with Complexity Router (S/M/L/XL), ADR-driven architecture, 15 agentic-qe skills, multi-agent fleet QE. Supports --full-qe, --full-qe-extended, --with-learning, and --knowledge-extractor modes.",
   "main": "src/cli.js",
   "bin": {
@@ -57,4 +57,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}