@dzhechkov/skills-feature-adr 1.3.3 → 1.3.4

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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "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"
   }
-}
+}