@dzhechkov/skills-feature-adr 1.3.2 → 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.2",
+  "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": {

package/src/cli.js

@@ -97,8 +97,14 @@ function parseArgs(argv) {
         command = 'version';
         break;
       default:
-        if (!arg.startsWith('-') && command === null) {
+        if (arg.startsWith('-')) {
+          error(`Unknown option: ${arg}`);
+          process.exit(1);
+        } else if (command === null) {
           command = arg;
+        } else {
+          error(`Unexpected argument: ${arg}`);
+          process.exit(1);
         }
         break;
     }

package/src/commands/init.js

@@ -56,13 +56,16 @@ function installComponent(key, comp, templatesDir, targetDir) {
 
   const filterFn = getComponentFilter(comp);
 
+  // Track files from the TEMPLATE source, never a scan of the destination — otherwise
+  // user-created files inside a component dir get adopted into the manifest and a later
+  // `remove` deletes them (finding #8). The filtered/plain copy still writes to dest.
   if (filterFn) {
     copyDirFiltered(src, dest, filterFn);
-    return getRelativePathsFiltered(dest, filterFn).map((rel) => path.join(comp.src, rel));
+    return getRelativePathsFiltered(src, filterFn).map((rel) => path.join(comp.src, rel));
   }
 
   copyDirRecursive(src, dest);
-  return getRelativePaths(dest).map((rel) => path.join(comp.src, rel));
+  return getRelativePaths(src).map((rel) => path.join(comp.src, rel));
 }
 
 // Resolve which optional component keys to install based on flags

package/src/commands/update.js

@@ -8,7 +8,7 @@ const {
   copyDirRecursive, copyDirFiltered, fileExists, readJSON,
   ensureDir, getRelativePaths, getRelativePathsFiltered, diffFiles,
   readManifest, writeManifest, getTemplatesDir,
-  COMPONENTS, MANIFEST_FILE, getComponentFilter,
+  COMPONENTS, OPTIONAL_COMPONENTS, MANIFEST_FILE, getComponentFilter,
 } = require('../utils');
 
 // ---------------------------------------------------------------------------
@@ -55,7 +55,11 @@ async function run(options) {
   const filesToCopy = [];
 
   for (const key of installedKeys) {
-    const comp = COMPONENTS[key];
+    // Optional components (--with-learning / --knowledge-extractor) live in
+    // OPTIONAL_COMPONENTS, not COMPONENTS \u2014 looking only in COMPONENTS treated them
+    // as "Unknown component" and dropped their files from the manifest on every
+    // update (finding #7). Resolve from both registries.
+    const comp = COMPONENTS[key] || OPTIONAL_COMPONENTS[key];
     if (!comp) {
       warn(`Unknown component "${key}" in manifest \u2014 skipping.`);
       continue;
@@ -131,16 +135,19 @@ async function run(options) {
   // ── e) Update manifest ────────────────────────────────────────────────
   const allFiles = [];
   for (const key of installedKeys) {
-    const comp = COMPONENTS[key];
+    const comp = COMPONENTS[key] || OPTIONAL_COMPONENTS[key];
     if (!comp) continue;
 
+    const srcPath = path.join(templatesDir, comp.src);
     const destPath = path.join(targetDir, comp.src);
     const filterFn = getComponentFilter(comp);
 
+    // Record from the TEMPLATE source, not a dest scan, so user files aren't adopted.
+    const scanBase = fileExists(srcPath) ? srcPath : destPath;
     if (fileExists(destPath)) {
       const paths = filterFn
-        ? getRelativePathsFiltered(destPath, filterFn)
-        : getRelativePaths(destPath);
+        ? getRelativePathsFiltered(scanBase, filterFn)
+        : getRelativePaths(scanBase);
       allFiles.push(...paths.map((rel) => path.join(comp.src, rel)));
     }
   }

package/templates/.claude/commands/feature-adr.md

@@ -27,12 +27,14 @@ $ARGUMENTS
    - Определи `{ACTIVE_STEPS}` и `{TIME_BUDGET}`
    - Покажи Checkpoint 0 и **жди подтверждения tier**
 
-4. **Steps 1-8 — Execute Active Steps:**
-   - Для каждого шага из `{ACTIVE_STEPS}`:
+4. **Steps 1-9 — Execute Active Steps:**
+   - Для каждого шага из `{ACTIVE_STEPS}` (включая Step 3.5 для M+ и Step 9 для L/XL):
      - Прочитай `modules/{step}.md`
      - Выполни протокол шага
      - Создай артефакты в `features/<slug>/`
      - Покажи Checkpoint N
+   - **Step 3.5 (QCSD Ideation Swarm)** обязателен для M/L/XL — спавнит 3-9 параллельных агентов и выдаёт GO/CONDITIONAL/NO-GO verdict
+   - **Step 9 (Fleet QE Assessment)** обязателен для L/XL — 4 параллельных агента (traceability ‖ risk ‖ integration ‖ regression)
 
 5. **Финализация:**
    - Создай `features/<slug>/README.md` с summary
@@ -48,17 +50,22 @@ features/<feature-slug>/
 └── 07_code_changes/ ← для манифеста изменений
 ```
 
+Дополнительные артефакты создаются по мере выполнения шагов:
+`03.5_ideation_report.md` (M+, Step 3.5) и `09_fleet_qe_assessment.md` (L/XL, Step 9).
+
 Slug: kebab-case из описания фичи (латиница, max 40 символов).
 
 ## Параллелизация (Agent Swarm)
 
 Для L/XL тiers:
 - Steps 2+3 запускай параллельно (2 агента, sonnet + opus)
-- Steps 4+5 можно параллельно если Step 3 уже завершён
+- Step 3.5: 3-9 параллельных агентов (QCSD swarm — core + conditional)
+- Steps 4+5 можно параллельно если Step 3.5 уже завершён
 - Step 7: N параллельных агентов (по одному на модуль)
-- Step 8: 3 параллельных агента (unit ‖ integration ‖ review)
+- Step 8: 3 параллельных агента (Linus ‖ Security ‖ Ramsay reviewer — brutal-honesty панель)
+- Step 9: 4 параллельных агента (traceability ‖ risk ‖ integration ‖ regression); 4-7 с `--full-qe-extended`
 
-Для S/M: всё последовательно, параллелизация не нужна.
+Для S/M: всё последовательно, параллелизация не нужна (Step 3.5 для M спавнит 3 core агента).
 
 ## Model Routing
 
@@ -68,17 +75,19 @@ Slug: kebab-case из описания фичи (латиница, max 40 сим
 | 1 Requirements | sonnet |
 | 2 Research | sonnet |
 | 3 ADR | opus |
+| 3.5 QCSD Ideation Swarm | sonnet |
 | 4 DDD | opus |
 | 5 Architecture | opus |
 | 6 Impl Plan | sonnet |
 | 7 Code | opus |
 | 8 QE | sonnet |
+| 9 Fleet QE Assessment | sonnet |
 
 ## Checkpoint формат
 
 ```
 ═══════════════════════════════════════════════════════
-⏸️ STEP N/8: [Step Name] Complete
+⏸️ STEP N: [Step Name] Complete
 <promise>[PROMISE_TAG]</promise>
 Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
 
@@ -96,5 +105,8 @@ Artifacts: [list] ✅
 - **НИКОГДА** не пропускай Step 0 (Router) — всегда классифицируй сначала
 - **НИКОГДА** не начинай Step 7 (Code) без Step 6 (Plan)
 - **НИКОГДА** не пропускай Step 8 (QE) — тестирование обязательно
+- **НИКОГДА** не пропускай Step 3.5 (QCSD Ideation Swarm) для M/L/XL — quality assessment обязателен (BLOCK)
+- **НИКОГДА** не игнорируй NO-GO verdict из Step 3.5 — требуется доработка (BLOCK)
+- **НИКОГДА** не пропускай Step 9 (Fleet QE) для L/XL — fleet assessment обязателен (BLOCK)
 - **ВСЕГДА** жди подтверждения пользователя на Checkpoint перед переходом
 - **ВСЕ артефакты** создаются в `features/<slug>/`, не в корне проекта

package/templates/.claude/rules/reward-learning.md

@@ -1,5 +1,14 @@
 # Reward Learning Rules
 
+> **Scope:** This is the **shared Keysarium learning layer**, installed by `--with-learning`.
+> It governs the Keysarium pipeline (Phases 0-5 with Casarium promise tags), NOT the
+> feature-adr pipeline. The feature-adr pipeline emits its own `FEATURE_ADR_*` promise
+> tags at Steps 0-9 and does not wire `memory_query()`/`memory_store()` into its steps.
+> Install this only if you also run the Keysarium pipeline; if `@dzhechkov/keysarium`
+> is present it already ships this layer and `--with-learning` is unnecessary.
+> The `.claude/rules/feedback-loops.md` referenced below ships with `@dzhechkov/keysarium`,
+> not with this package.
+
 ## Purpose
 
 Govern how the Keysarium pipeline integrates with the Reward-Calibrated Learning System. These rules define when and how to call `memory_query()` and `memory_store()`, how reward scores are assigned, and how historical patterns influence phase execution.
@@ -82,7 +91,7 @@ If a promise is `_INCOMPLETE`, the reward should be 0.3 or lower.
 
 ## Integration with Feedback Loops
 
-This system adds a new feedback loop to the Variable Registry (see `.claude/rules/feedback-loops.md`):
+This system adds a new feedback loop to the Variable Registry (see `.claude/rules/feedback-loops.md`, shipped with `@dzhechkov/keysarium` — not bundled in this package):
 
 ### Loop 7: Memory -> All Phases
 

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -399,7 +399,7 @@ npx @dzhechkov/skills-feature-adr init --with-learning --knowledge-extractor
 | Flag | Installs | Purpose |
 |------|----------|---------|
 | (none) | Core skill + command + rules + shard | Feature development pipeline |
-| `--with-learning` | + `lib/memory-protocol.md`, `lib/reward-tracker.md`, `.claude/rules/reward-learning.md` | Pipeline learns from checkpoint feedback |
+| `--with-learning` | + `lib/memory-protocol.md`, `lib/reward-tracker.md`, `.claude/rules/reward-learning.md` | Installs the shared **Keysarium learning layer** (Phases 0-5, `.keysarium/memory/`). The feature-adr pipeline itself does not yet wire `memory_query`/`memory_store` into its Steps 0-9 — this layer applies only if you also run the Keysarium pipeline. |
 | `--knowledge-extractor` | + `.claude/skills/knowledge-extractor/`, `.claude/commands/harvest.md` | Extract reusable patterns after feature completion |
 
 > **Note:** If `@dzhechkov/keysarium` is already installed, these flags are not needed — keysarium includes all learning and extraction capabilities.

package/templates/.claude/skills/feature-adr/modules/00-complexity-router.md

@@ -57,12 +57,16 @@ Load `references/complexity-matrix.md` for the full matrix. Summary:
 | 0 Complexity Router | ✓ | ✓ | ✓ | ✓ |
 | 1 Requirements | ✓ light | ✓ | ✓ | ✓ |
 | 2 Research | - | - | ✓ | ✓ |
-| 3 ADR | - | ✓ (1 ADR) | ✓ (N ADRs) | ✓ (N ADRs) |
+| 3 ADR + Shift-Left | - | ✓ (1 ADR) | ✓ (N ADRs) | ✓ (N ADRs) |
+| 3.5 QCSD Ideation Swarm | - | ✓ | ✓ | ✓ |
 | 4 DDD | - | - | ✓ | ✓ |
 | 5 Architecture | - | ✓ light | ✓ | ✓ |
 | 6 Implementation Plan | ✓ inline | ✓ | ✓ | ✓ |
 | 7 Code | ✓ | ✓ | ✓ | ✓ |
-| 8 QE | ✓ smoke | ✓ | ✓ | ✓ full |
+| 8 QE + Brutal Honesty | ✓ smoke | ✓ | ✓ | ✓ full |
+| 9 Fleet QE Assessment | - | - | ✓ | ✓ |
+
+> Steps 3.5 (M+) and 9 (L/XL) are mandatory — skipping them is a BLOCK per the shard Anti-Patterns.
 
 ### 5. Calculate Time Budget
 
@@ -92,7 +96,7 @@ Create artifact: `features/<slug>/00_complexity_assessment.md`
 
 ```
 ═══════════════════════════════════════════════════════
-⏸️ STEP 0/8: Complexity Router Complete
+⏸️ STEP 0: Complexity Router Complete
 <promise>FEATURE_ADR_ROUTED</promise>
 Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
 

package/templates/.claude/skills/feature-adr/references/complexity-matrix.md

@@ -79,39 +79,44 @@ Skipped: 2, 3, 4, 5
 ### Tier M (Score 9-13)
 
 ```
-Active:  0 → 1 → 3(1 ADR) → 5(light) → 6 → 7 → 8
-Skipped: 2, 4
+Active:  0 → 1 → 3(1 ADR) → 3.5 → 5(light) → 6 → 7 → 8
+Skipped: 2, 4, 9
 ```
 
 **Step adaptations:**
 - Step 3: Single ADR for the main architectural decision
+- Step 3.5: QCSD ideation swarm — 3 core agents + GO/CONDITIONAL/NO-GO verdict (mandatory for M+ — skipping is a BLOCK)
 - Step 5: Component diagram only, no full C4
 
 ### Tier L (Score 14-19)
 
 ```
-Active:  0 → 1 → [2 ‖ 3] → [4 ‖ 5] → 6 → 7 → 8
-Parallel groups: (2,3) and (4,5)
+Active:  0 → 1 → [2 ‖ 3] → 3.5 → [4 ‖ 5] → 6 → 7 → 8 → 9
+Parallel groups: (2,3) and (4,5); Step 3.5 runs after Step 3, Step 9 after Step 8
 ```
 
 **Step adaptations:**
 - Step 2: Research analogues in codebase and external patterns
 - Step 3: Multiple ADRs for each significant decision
+- Step 3.5: QCSD ideation swarm — 3-9 parallel agents + GO/CONDITIONAL/NO-GO verdict (mandatory for M+ — skipping is a BLOCK)
 - Step 4: Bounded contexts + ubiquitous language
 - Step 5: Full C4 (Context + Container + Component)
 - Step 8: Unit + integration tests + code review
+- Step 9: Fleet QE assessment — 4 parallel agents (traceability ‖ risk ‖ integration ‖ regression) (mandatory for L/XL — skipping is a BLOCK)
 
 ### Tier XL (Score 20-24)
 
 ```
-Active:  0 → 1 → [2 ‖ 3] → [4 ‖ 5] → 6 → 7(parallel) → 8(full)
-Parallel groups: (2,3), (4,5), (7 per module)
+Active:  0 → 1 → [2 ‖ 3] → 3.5 → [4 ‖ 5] → 6 → 7(parallel) → 8(full) → 9
+Parallel groups: (2,3), (4,5 — after 3.5), (7 per module)
 ```
 
 **Step adaptations:**
 - All steps at full depth
+- Step 3.5: QCSD ideation swarm — 3-9 parallel agents + GO/CONDITIONAL/NO-GO verdict (mandatory for M+ — skipping is a BLOCK)
 - Step 7: Multiple parallel agents, one per module/domain
 - Step 8: Full QE — unit + integration + e2e + performance + security review
+- Step 9: Fleet QE assessment — 4 parallel agents (4-7 with `--full-qe-extended`) (mandatory for L/XL — skipping is a BLOCK)
 
 ---
 

package/templates/lib/memory-protocol.md

@@ -1,5 +1,9 @@
 # Memory Protocol -- Reward-Calibrated Learning
 
+> **Scope:** Shared **Keysarium learning layer** (installed by `--with-learning`). Governs the
+> Keysarium pipeline (Phases 0-5, `.keysarium/memory/`), NOT the feature-adr pipeline. Install
+> only if you also run Keysarium; `@dzhechkov/keysarium` already ships this layer.
+
 Core protocol for persistent memory in the Keysarium pipeline. Provides `memory_query()` before tasks and `memory_store()` after tasks.
 
 **Protocol version: 1.1** — adds 2-tier index, record lifecycle (HOT/WARM/COLD/PURGE), and brain container manifest.

package/templates/lib/reward-tracker.md

@@ -1,5 +1,9 @@
 # Reward Tracker -- Analytics & Pattern Detection
 
+> **Scope:** Shared **Keysarium learning layer** (installed by `--with-learning`). Operates on
+> Keysarium reward records (`.keysarium/memory/`), NOT the feature-adr pipeline. Install only if
+> you also run Keysarium; `@dzhechkov/keysarium` already ships this layer.
+
 Computes aggregate statistics and detects domain patterns from accumulated reward records. Used by `/learning-stats` and by `memory_query()` for pattern enrichment.
 
 ## Overview