@dzhechkov/skills-feature-adr

Spec-Driven Development pipeline for AI coding agents (Claude Code, Codex, …)

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_…–09_…), 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 for quality engineering. Part of the 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 below.

👉 Onboarding a team? Start here: Feature ADR — Team Onboarding — a single read-top-to-bottom playbook (install → first feature → SDD mechanics → model routing incl. Fable → self-learning layers → team PR workflow → FAQ). It also ships inside this package at node_modules/@dzhechkov/skills-feature-adr/docs/team-onboarding.md (raw copy on unpkg), so every install has it locally.

Quick Start

# Core install (feature-adr pipeline only)
npx @dzhechkov/skills-feature-adr init

# Full install with learning + knowledge extraction
npx @dzhechkov/skills-feature-adr init --with-learning --knowledge-extractor

# Or install globally
npm install -g @dzhechkov/skills-feature-adr
skills-feature-adr init --with-learning --knowledge-extractor

# Already have @dzhechkov/keysarium? Just install core (learning & harvest included)
npx @dzhechkov/skills-feature-adr init

After installation, open Claude Code in your project directory and use /feature-adr.

What You Get

| Component | Count | Description | |-----------|-------|-------------| | Skill | 1 | feature-adr — 11-step pipeline with complexity routing | | Modules | 11 | Steps 00-09 + 03.5: Router → Requirements → Research → ADR → QCSD → DDD → Architecture → Plan → Code → QE → Fleet QE | | References | 4+15 | Complexity matrix, ADR/C4/QE templates + 15 agentic-qe skill protocols | | Examples | 1 | Sample M-tier feature output | | Command | 1 | /feature-adr — orchestrator (supports --full-qe and --full-qe-extended) | | Rules | 1 | feature-adr-conventions — directory structure and naming | | Shards | 1 | feature-adr — governance shard with quality gates |

Everything is installed into your project's .claude/ directory and works natively with Claude Code.

Commands

npx @dzhechkov/skills-feature-adr                    # Full install (same as init)
npx @dzhechkov/skills-feature-adr init               # Install core components
npx @dzhechkov/skills-feature-adr init --with-learning                  # + reward learning
npx @dzhechkov/skills-feature-adr init --knowledge-extractor            # + knowledge extractor
npx @dzhechkov/skills-feature-adr init --with-learning --knowledge-extractor  # + both
npx @dzhechkov/skills-feature-adr init --force       # Overwrite existing files
npx @dzhechkov/skills-feature-adr init --dry-run     # Preview without making changes
npx @dzhechkov/skills-feature-adr update             # Update to latest version
npx @dzhechkov/skills-feature-adr remove             # Clean uninstall
npx @dzhechkov/skills-feature-adr list               # Show installed components
npx @dzhechkov/skills-feature-adr doctor             # Health check

Feature ADR Pipeline

Step 0        Step 1          Step 2       Step 3      Step 3.5      Step 4
COMPLEXITY → REQUIREMENTS → RESEARCH  →   ADR    →  QCSD SWARM  →   DDD
  ROUTER                   (L/XL only)  (M+ only)   (M+ only)    (L/XL only)

Step 5         Step 6            Step 7     Step 8     Step 9
ARCHITECTURE → IMPLEMENTATION →  CODE   →   QE    →  FLEET QE
(M+ only)       PLAN                                (L/XL only)

Usage in Claude Code

# Start the full adaptive pipeline
/feature-adr Add user authentication with OAuth2 and JWT

# The Complexity Router classifies your feature automatically:
#   S  → fast track (5 steps)
#   M  → standard (8 steps)
#   L  → full pipeline (11 steps)
#   XL → full DAG + multi-agent swarm

# With full agentic-qe integration (requires: npm install -g agentic-qe)
/feature-adr --full-qe Add payment processing module
# Full protocols for 9 core skills, same agents, deeper methodology

# With extended agentic-qe (chaos, security, performance, mutation, TDD)
/feature-adr --full-qe-extended Migrate authentication to zero-trust architecture
# Full protocols + 6 extra skills, up to 7 fleet QE agents

Codex model routing (optional)

If Codex is installed + logged in, the pipeline can route work to Codex — always asking first, always with a Claude fallback (it never blocks on Codex). Three opt-in knobs (via the workflow args, or offered interactively at the planning checkpoint):

| Knob | Step | What it does | |---|---|---| | planner: 'codex' | 6 Plan | plan on Codex's top model (Claude fallback) | | coder: 'codex-fallback' | 7 Code | Claude first; if the Claude Code limit is exhausted mid-run → retry on Codex | | qeReviewer: 'codex-fallback' | 8 QE/tests | same fallback for the review/testing stage | | codexModel: 'auto' | — | which Codex model (auto default (Codex self-selects) · or an id your account exposes (e.g. gpt-5.5)) |

Scenario — never stall on a rate limit: a long L/XL feature hits the Claude Code session limit while writing code. Without this the run stalls; with coder: 'codex-fallback' the pipeline logs "Claude unavailable (limit?) — falling back to Codex auto" and finishes the code + tests on Codex, no restart and no lost work.

Codex writes are out-of-band — the Step-7.5 landed barrier waits for them. Codex applies edits via its own runtime, so a naive pipeline runs QE before the async write flushes and false-grades "Step 7 never ran" on real code. For a Codex-coded run the pipeline polls a bounded 120s backing-off window (1,2,2,5,5,10,10,15,20,25,25s), preferring the code stage's declared expected files when known, and emits an explicit changed=0 after 120s — genuinely not landed only when the window truly expires — so QE distinguishes "not implemented" from "not yet flushed". A Claude-coded run is synchronous and skips the barrier entirely (zero added wait). Note: if Codex flushes slower than 120s, re-verify after the run rather than trusting the end-of-run grade.

# Headless login on a VPS (no browser):
codex login --device-auth                       # prints a code + URL you approve on another device
# — or —
printenv OPENAI_API_KEY | codex login --with-api-key

// ultracode (the deterministic workflow form): plan on Codex, code+QE fall back to Codex on Claude-limit:
Workflow({ scriptPath: '.claude/workflows/feature-adr.js',
  args: { slug: 'add-oauth', description: '…', tier: 'M',
          planner: 'codex', coder: 'codex-fallback', qeReviewer: 'codex-fallback', codexModel: 'auto' } })  // 'auto' = Codex picks top; or pin e.g. 'gpt-5.5'

Omit the Codex knobs entirely for today's all-Claude behavior. The run result reports plannerUsed / coderUsed / qeReviewerUsed / codexModel / modelsUsed so you can see who did what.

Live model visibility in /workflows: each stage's agent label is decorated with its resolved model — e.g. adr · codex:gpt-5.5:xhigh, plan · opus — so you see which model actually ran a stage in the live progress tree, not just in the final report. This matters because a Codex stage's auto model-badge shows the codex:codex-rescue Claude wrapper (the session model), never codex; the label text is the honest signal. A Claude fallback appears as its own distinct node (never mislabeled as Codex), and a routing-off run adds no suffix (byte-identical to today).

Per-stage model routing — args.models

The three Codex knobs above are shortcuts. args.models is the general dial: an optional map that routes each of the 11 pipeline stages to an optimal model. Keys: {router, requirements, research, adr, ideation, ddd, architecture, plan, code, qe, fleet}. Each value is a spec — Claude fable|opus|sonnet|haiku, or Codex codex / codex:<id> / codex:<id>:<reasoning> (reasoning ∈ low|medium|high|xhigh; ids incl. gpt-5.5, gpt-5.6, gpt-5.6-sol — the last is the default auto-top reviewer; ids are account-specific, so probe with codex exec -m <id> before pinning).

Recommended DEFAULT TABLE (applied only when you opt in — one args.models key or any Codex knob turns it on; otherwise every stage is session-inherited, byte-identical to today):

| router | requirements | adr | ideation | architecture | plan | code | qe | fleet | |---|---|---|---|---|---|---|---|---| | fable | sonnet | opus | sonnet | opus | sonnet | coder (default opus) | cross-model | sonnet |

(research folds into requirements, ddd into architecture — recorded in modelsUsed, not a separate call.)

Cross-model QE default (load-bearing): when args.models.qe is unset, QE auto-routes to the other family than the coder — a model that writes code must not also self-QE; independent cross-model review catches what self-review misses. coder=Codex ⇒ QE=Claude (opus); coder=Claude ⇒ QE=Codex (codex:<top>:high), or a Claude reviewer if Codex is unavailable (never blocks).

Precedence: args.models[stage] wins; the legacy planner/coder/qeReviewer/codexModel knobs fill only unspecified stages. codexModel seeds the id for a bare 'codex' spec. gpt-5.6-ready: a new Codex id is a data-only allowlist edit.

// Claude writes the code; Codex independently QEs it (cross-model by construction):
Workflow({ scriptPath: '.claude/workflows/feature-adr.js',
  args: { slug: 'add-oauth', description: '…', tier: 'L',
          models: { code: 'opus', qe: 'codex:gpt-5.6:high', architecture: 'opus', router: 'fable' } } })

Usage-adaptive routing — pre-emptive Codex switch at ≥ 70% Claude usage

The codex-fallback knobs above are reactive — they catch a stage after it dies on a limit. At true exhaustion even the fallback dispatch can die, so the pipeline also switches pre-emptively: when model routing is opted into, it probes Claude SESSION (fixed-length transcript block) and WEEKLY (fixed reset anchor such as Wed 08:59) usage at each phase boundary via dz usage --json (from @dzhechkov/harness-cli), and moves the remaining stages to Codex before hitting the wall.

| Knob (args.*) | Default | Effect | |---|---|---| | usageAdaptive | true when routing is requested; false otherwise | true forces it on by itself; false disables all probes (byte-identical to no-routing runs) | | usageThreshold | 70 | the >= percent (SESSION or WEEKLY) that triggers the switch | | usageReasoning | built-in map | per-stage reasoning under the override (design/code/plan → xhigh; router/qe/fleet → high) |

Two-way, hysteretic, fail-safe:

• >= usageThreshold on either metric ⇒ ALL remaining stages switch to codex:<top>.
• Both metrics back below (positive numbers, not nulls) ⇒ the normal model mix is restored.
• A probe whose agent dies (often means the limit was hit) fail-safe-switches to Codex; a value-null (limits not configured) flips nothing — no flapping, no false switches.
• A reactive belt remains: a stage agent returning null while not overridden also flips the switch for the remaining stages.

Observability: switched stages carry (usage-switched) in modelsUsed; results include usageEvents ([{phase, sessionPct, weeklyPct, action}], action ∈ switch|restore|keep|fail-safe-switch|reactive-switch|none) and usageThreshold.

Config (optional): percentages are local-transcript estimates; claude.ai/settings/usage is authoritative. They stay null — and never trigger a switch — until you set your plan's limits in .dz/config.json. When weeklyTokenLimitByModel is configured, weeklyPct is the binding per-model weekly estimate; otherwise it is the all-model weekly estimate.

{
  "memory": {
    "usage": {
      "sessionTokenLimit": 200000000,
      "weeklyTokenLimit": 1000000000,
      "weeklyResetAnchor": "Wed 08:59",
      "sessionBlockHours": 5,
      "weeklyTokenLimitByModel": { "fable": 500000000 }
    }
  }
}

// Claude codes until usage crosses 70%, then every remaining stage runs on Codex until it drops back:
Workflow({ scriptPath: '.claude/workflows/feature-adr.js',
  args: { slug: 'add-oauth', description: '…', tier: 'L',
          models: { code: 'opus' }, usageAdaptive: true, usageThreshold: 70 } })

Note: under the override, coder and QE both run on Codex — the cross-model self-QE guard is consciously suspended (a Claude QE reviewer is exactly the agent that dies under limit pressure). The (usage-switched) suffix + usageEvents keep it auditable; re-run an independent QE after limits reset if the switch fired during Step 8.

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 | |------|-------|-------------|-------------| | S | 1-3 files, 1 domain | 0→1→6→7→8 | ~15 min | | M | 4-10 files, 1-2 domains | 0→1→3→3.5→5→6→7→8 | ~45 min | | L | 11-30 files, 2-4 domains | Full pipeline with parallelism | ~2 hours | | XL | 30+ files, cross-cutting | Full DAG + multi-agent swarm | ~4+ hours |

Complexity Dimensions (scored 1-4 each)

| Dimension | 1 (Low) | 4 (High) | |-----------|---------|----------| | Files affected | 1-3 | 30+ | | Domain breadth | Single module | Cross-cutting concerns | | Integration points | 0-1 external | 4+ external systems | | Risk / reversibility | Easily reverted | Data migration required | | Novelty | Well-known pattern | No prior art in codebase | | Stakeholder count | Solo developer | 4+ teams affected |

Pipeline Steps

| 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

Step 0 is architecture- & project-aware (opt-in, zero-config when absent)

Beyond classifying the tier, Step 0 now aligns the feature to your product and folds in project-specific skills — both are fully opt-in and a run with neither file present is byte-identical to before.

Architecture сverka (needs dz ≥ 0.3.111 + an architecture/ map in the repo). Step 0 runs dz architecture --check against your product map + vision and surfaces the verdict in the checkpoint:

# author these two committed files once:
#   architecture/subsystems.manifest.json   — the product's subsystems (the 5 jobs + foundation/arsenal/ops)
#   architecture/vision.md                    — what the product is, where it goes, what it must NOT do
dz architecture              # see the map
dz architecture --check --slug <slug> --desc "<what you're building>" --cmd <new,cmds>

⛔ block (confidence 0.90) — duplicate-command: "recall" already exists in subsystem "learn". Confirm this is intentional.

A block (a hard-stop, e.g. re-adding an existing command) is surfaced for your confirmation — it never auto-aborts. At the end of a complete run the map is refreshed (architecture/map.json) so the next feature's сverka sees this one.

Project-skill polymorphism (needs dz ≥ 0.3.112). If the repo ships architecture/project-skills.json, Step 0 resolves it and folds each declared skill into its stage as guidance — so a generic pipeline becomes project-aware without editing the workflow:

{ "version": 1,
  "roles": { "product-vision": "architecture/vision.md", "critic": ".dz-skills/my-critic/SKILL.md" },
  "extra": [ { "skill": ".dz-skills/security-checklist/SKILL.md", "phase": "qe", "as": "guidance" } ] }

Fixed roles map to fixed stages (product-vision→design+QE, critic→QE, brand→code, impl-bar→code); the open extra list adds guidance to any stage. dz project-skills prints the who-injected report. Absent ⇒ a normal generic run. (See dz mr-rakes --gen-critic to auto-generate the critic skill from your recurring rakes.)

Bundled role-default skills (backend-service defaults; principles portable). This pack ships four depersonalized quality skills you can point the roles at — all calibrated by your architecture/vision.md (build it with dz feature-adr-setup), so they carry your project's reality, not a vendor's. The examples assume a backend-service stack (async web / RDB / JWT-JWKS / k8s); the principles are portable — translate the examples for a different stack:

• code-critic — an independent code-quality reviewer (god-object growth, security invariants, anti-pattern detection by intent, honest severity, "low precision costs more than low recall"). Point the critic role at it: "roles": { "critic": ".claude/skills/code-critic/SKILL.md" }.
• code-impl — the implementer's quality bar (top-5 hard rules, god-object rule, reuse-map discipline, security invariants, decision discipline, done-ness). Point the impl-bar role at it.
• system-grill — a Socratic architecture-intuition trainer (predict-before-reveal, honest 🔴/🟡/🟢 journal) that generates its curriculum from your architecture/subsystems.manifest.json + map.json + vision.md — for a product person to feel the system before briefing an agent. Trigger: "погоняй меня по системе".
• code-skills-creator — a meta-factory that produces a project-tuned code-impl + code-critic pair. It starts from the two generic bases above and specializes them with your project's own evidence — dz mr-rakes recurring code rakes (primary) or a parallel-critic audit (fallback), your god-object freeze table and reuse-map — then generalizes every rake to a class of defect (never a bug-list linter). Writes the pair to architecture/project-{impl,critic}/SKILL.md (augment-never-clobber). With no evidence it hands back the generic pair unchanged rather than invent mistakes. Trigger: "build a quality bar pair".

Adversarial plan-gate at the L/XL checkpoint (needs dz ≥ 0.3.117)

Cross-model QE (Step 8) catches problems after the code is written. At the checkpoint-after-plan the pipeline now also runs an adversarial challenge panel on the plan itself — a FRESH reviewer that did not write the plan tries to BREAK it across a fixed C1-C8 owner-question set (arch-anti-cement, prod-ready, test sufficiency + honesty, overengineering, silent decisions, runtime consistency, scope, executability):

• Panel ≠ plan author (hard invariant): if Claude wrote the plan the adversary is Codex (honest codex exec, never a fire-and-forget stub); if Codex wrote it the adversary is a fresh Claude. An unknown family never silently claims cross-family.
• Every P0/P1 is cross-validated by a second independent agent, matched by index (never by title), and the non-validated ones are dropped — theory never reaches you. If the validator can't cover them, they are surfaced UNVALIDATED, never silently dropped.
• Advisory — the verdict returns as challengeVerdict alongside the ADR + plan; it never auto-blocks.
• Calibrated by architecture/vision.md + testing.md + map.json + architecture/degradations.md (a deviation from a pattern registered in the degradations file is not flagged). Run it ad-hoc with dz challenge --plan <plan.md> or the challenge-panel skill; scaffold the degradations registry via dz feature-adr-setup --from-spec <spec with {"degradations":true}> --apply.

ADR quality gate (Step 3 generates → Step 8 enforces)

Step 3 and Step 8 share an ADR best-practices contract distilled from the architecture-decision-record monograph:

• Step 3 emits a MADR-structured ADR — invariant core (Title/Status/Context/Decision/Consequences), ranked Decision Drivers, Considered Options (the chosen approach framed as an option alongside the rejected ones, symmetric pros/cons), Rationale mapped to drivers, negative consequences + follow-up links + after-action review, a ## Confirmation stanza (method, monitoring, success metric, owner) naming the load-bearing property, and a ## Links traceability block. Template weight is tier-mapped: S/M → Nygard/ITD-lightweight, L/XL → MADR + Confirmation.
• Step 8 runs a 13-point ADR fitness checklist (qe-code-reviewer) against every generated ADR and fails the gate on any miss — decision-shaped title, controlled-vocabulary Status + reversibility, neutral Context-before-Decision, symmetric options, driver-mapped rationale, concrete/testable decision, negative consequences, traceability links, no placeholder, and rejects explainer-masquerading-as-ADR. The Confirmation→test link is load-bearing: if the named safety property has no automated test the ADR grades no better than C.

The pipeline dog-foods this: a harness test runs the gate against feature-adr's own generated ADR, so a Step-3↔Step-8 drift fails CI rather than shipping.

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

features/<feature-slug>/
├── 00_complexity_assessment.md     ← Always
├── 01_requirements.md              ← Always
├── 02_research.md                  ← L/XL only
├── 03_adr/
│   └── 001-<decision-slug>.md      ← M+ only
├── 03.5_ideation_report.md         ← M+ only
├── 04_domain_model.md              ← L/XL only
├── 05_architecture.md              ← M+ only
├── 06_implementation_plan.md       ← Always
├── 07_code_changes/
│   └── change_manifest.md          ← Always
├── 08_qe_report.md                 ← Always
├── 09_fleet_qe_assessment.md       ← L/XL only
├── diagrams/                       ← M+ only
│   ├── architecture-c4.mermaid
│   └── sequence-*.mermaid
└── README.md                       ← Always

Agentic QE Integration

Feature ADR integrates 15 skills from agentic-qe for quality engineering at every step.

Three Modes

| Mode | Flag | Skills | Requires | |------|------|--------|----------| | Reference | (none) | 9 core (condensed copies) | Nothing — works out of the box | | Direct | --full-qe | 9 core (full protocols) | agentic-qe installed | | Direct Extended | --full-qe-extended | 15 (9 core + 6 extended) | agentic-qe installed |

Installing agentic-qe (required for --full-qe and --full-qe-extended)

# 1. Install agentic-qe globally
npm install -g agentic-qe

# 2. Initialize in your project (auto-detects tech stack, configures MCP)
cd your-project && aqe init --auto

Source: github.com/proffesor-for-testing/agentic-qe

After installation, feature-adr auto-detects agentic-qe when you use the --full-qe or --full-qe-extended flags. If agentic-qe is not found, the pipeline falls back to Reference Mode with a warning.

Core Skills (9, all modes)

| Skill | Step | Purpose | |-------|------|---------| | shift-left-testing | 3 | ADR testability validation | | qcsd-ideation-swarm | 3.5 | HTSM + SFDIPOT quality swarm | | code-goal-planner | 6 | SPARC-GOAP milestone planning | | brutal-honesty-review | 8 | Linus/Ramsay/Bach code review | | qe-requirements-validation | 9 | Traceability matrix + SMART | | risk-based-testing | 9 | Probability×Impact 5×5 scoring | | enterprise-integration-testing | 9 | Contract testing + E2E flows | | regression-testing | 9 | Change-based test selection | | qe-coverage-analysis | 9 | Risk-weighted coverage |

Extended Skills (6, --full-qe-extended only)

| Skill | Step | Condition | |-------|------|-----------| | tdd-london-chicago | 7 | Always | | mutation-testing | 8 | If test suite exists | | security-testing | 8, 9 | HAS_AUTH / HAS_EXTERNAL_API | | performance-testing | 8, 9 | HAS_PERFORMANCE_SLA | | chaos-engineering-resilience | 9 | HAS_INFRASTRUCTURE_CHANGE | | qcsd-production-swarm | Post-9 | Advisory feedback loops |

Optional Features: Learning & Knowledge Extraction

Feature ADR can be extended with reward learning and knowledge extraction — no additional packages required.

--with-learning — Reward Learning

Adds the Memory Protocol and Reward Tracker. The pipeline learns from your feedback at every checkpoint:

• Stores reward scores based on your responses (immediate approval = 1.0, minor adjustments = 0.7, rework = 0.3)
• Loads historical patterns at the start of each step
• Detects domain-specific bottlenecks and skill effectiveness trends

npx @dzhechkov/skills-feature-adr init --with-learning

Installs: lib/memory-protocol.md, lib/reward-tracker.md, .claude/rules/reward-learning.md

--knowledge-extractor — Knowledge Harvesting

Adds the Knowledge Extractor skill with the /harvest command. After completing a feature, extract reusable patterns:

npx @dzhechkov/skills-feature-adr init --knowledge-extractor

# After completing a feature:
/harvest features/<feature-slug>/

Installs: .claude/skills/knowledge-extractor/ (5 agents, 7 categories, 8 quality gates), .claude/commands/harvest.md

Both at once

npx @dzhechkov/skills-feature-adr init --with-learning --knowledge-extractor

Already using @dzhechkov/keysarium?

If you have @dzhechkov/keysarium installed, these flags are not needed. Keysarium already includes reward learning, knowledge extraction, and more. The installer auto-detects keysarium and skips optional components to avoid duplication.

Self-Learning Layers

There are three independent self-learning systems that can sit under a Feature ADR run. --full-qe-extended does not turn on learning by itself — it controls QE depth. Learning is a separate concern — though in Direct modes the pipeline now adds explicit touchpoints into layer B (Step 0 pattern recall, Steps 8/9 outcome store — see the skill's "Pattern memory loop" section). The three layers do not conflict: each is isolated by its own storage path, its own learning signal, and its own consumer.

| Layer | Turn it on with | Learns from | Storage (distinct!) | Needs a DB? | |-------|-----------------|-------------|---------------------|-------------| | A — feature-adr reward learning | install flag --with-learning (or bundled with @dzhechkov/keysarium) | your checkpoint responses (ок=1.0 / minor=0.7 / rework=0.3 / restart=0.0) | .keysarium/memory/*.json | No — plain JSON files | | B — agentic-qe learning | comes with agentic-qe (required by --full-qe / --full-qe-extended), initialized by aqe init | QE task experiences (ReasoningBank + dream scheduler) | .agentic-qe/memory.db + patterns.rvf | Self-contained (its own store) | | C — dz harness self-learning | the dz CLI (dz setup / dz teach / dz consolidate / dz recall) | your dz sessions | .dz/ (+ optional .dz/agentdb.db vector tier) | Optional — lexical works without one; agentdb only adds vector search |

Do they conflict? No — but observe one rule

• No logical conflict: different files, different signals, different readers → no write contention and no data clobbering. Enabling all three at once is fine; they're complementary.
• Auto-dedup: if @dzhechkov/keysarium is present, the installer skips --with-learning (keysarium already ships layer A), so you can't accidentally double-install it.
• ⚠️ The one rule — one DB file per writer. Layer C writes to SQLite natively (better-sqlite3, WAL); agentic-qe (layer B) can write via sql.js (whole-file overwrite). Pointing both at the same .db file risks corruption. By default they use different files (.agentic-qe/memory.db ≠ .dz/agentdb.db), so out of the box you're safe — just never hand-repoint one system's AGENTDB_PATH at the other's database.

Which to enable

• Writing features with this pipeline and want it to learn from your feedback → npx @dzhechkov/skills-feature-adr init --with-learning (no agentdb needed).
• Running --full-qe / --full-qe-extended → agentic-qe's learning already runs via its hooks.
• Living inside the dz harness and want cross-session memory → dz setup (add agentdb only if you want the vector tier).

Maintenance: consolidate periodically

Hooks and events only collect raw data — distilling it into reusable patterns is a separate consolidation step, and for layers B and C that step is worth running deliberately:

• A (reward JSON) — nothing to do; it consolidates implicitly at every checkpoint.
• B (agentic-qe) — queues raw experiences that only its consolidation pass distills into patterns. Left alone, a project can pile up thousands of unconsolidated experiences over a month while its per-prompt pattern injection returns zero useful patterns. Run aqe learning consolidate periodically (e.g. weekly, or after a heavy QE run); aqe learning stats shows the experience backlog.
• C (dz harness) — run dz consolidate to harvest session learnings into the lexical store (mirrored to the agentdb vector store if present); inspect the result with dz recall. Consolidation now runs automatically on PreCompact — Claude Code fires this before every context compaction (both auto-compaction and manual /compact), so long or heavily-compacted sessions consolidate at each compaction boundary rather than only at a clean end. It is throttled (a .dz/.last-consolidate marker enforces a minimum of ~15 min between auto-runs) so rapid compactions don't reload the embedding model repeatedly. SessionEnd remains as a secondary trigger for clean exits, and you can still run dz consolidate manually anytime. PreCompact is the primary reliable trigger — earlier the SessionEnd-only hook missed long, compacted, or crashed sessions, which left consolidation effectively manual.

Degradation symptom: patterns stop improving while raw logs keep growing. If recall/injection quality plateaus, you're collecting but not distilling — consolidate.

There is no single unified "what did the whole stack learn" view — each layer reports from its own store. That's the price of isolation (and the reason there are no cascading failures). Tune each where it lives.

Shared Skills

Feature ADR uses these skills from @dzhechkov/keysarium (if installed):

| Skill | Used In | Purpose | |-------|---------|---------| | explore | Step 1 | Requirements clarification | | problem-solver-enhanced | Step 3 | Trade-off analysis for ADR | | frontend-design | Step 7 | UI implementation (if applicable) |

These are optional — Feature ADR works standalone but benefits from the full toolkit.

Integration with Keysarium Ecosystem

# Install the full ecosystem
npx @dzhechkov/keysarium init              # Research pipeline
npx @dzhechkov/skills-bto init             # Build-Test-Optimize
npx @dzhechkov/skills-feature-adr init     # Feature development

# Use the right tool for the job:
/casarium [case description]                        # AI case research (7 phases)
/feature-adr [feature description]                  # Feature development (11 steps)
/feature-adr --full-qe [feature description]        # + full agentic-qe protocols
/feature-adr --full-qe-extended [feature desc]      # + extended QE skills
/bto [skill path]                                   # Skill evaluation & optimization

Troubleshooting

sh: 1: skills-feature-adr: not found — npx inside a monorepo with workspaces

If you run npx @dzhechkov/skills-feature-adr <command> from inside a monorepo whose root package.json declares "workspaces" (npm/pnpm/yarn) and a local workspace package shadows this name (e.g. you vendored or forked this package, or you're developing it), npx resolves the local workspace copy instead of fetching from the registry. It then looks for the bin shim in node_modules/.bin/ — which the workspace manager may never have created (pnpm links shims only for declared dependencies) — and falls back to running the bare command in your shell:

sh: 1: skills-feature-adr: not found

Note: pinning a version (npx @dzhechkov/[email protected]) does not bypass workspace resolution — verified.

Fixes:

# 1. Run it where it belongs — in the TARGET project (where .claude/ lives).
#    That directory is normally not the package's own monorepo:
cd /path/to/your-project
npx @dzhechkov/skills-feature-adr update

# 2. Developing inside the monorepo that contains this package? Invoke the
#    workspace copy's bin directly:
node <monorepo>/packages/@dzhechkov/skills-feature-adr/bin/cli.js update

# 3. Or use a global install (resolves independently of any workspace):
npm install -g @dzhechkov/skills-feature-adr
skills-feature-adr update

Related: init/update/remove operate on the current directory's .claude/ install — running them inside the package's own monorepo is almost never what you want anyway.

Requirements

• Claude Code CLI — installed and configured (installation guide)
• Node.js >= 16.0.0 — required for the npm install method

License

MIT

Links

• Team Onboarding playbook (public, rendered): dz-skill-bundles/docs/feature-adr-team-onboarding.md — also shipped in this package at docs/team-onboarding.md (raw on unpkg)
• GitHub (public docs & bundles): https://github.com/djd1m/dz-skill-bundles
• Issues: https://github.com/djd1m/dz-skill-bundles/issues
• Note: the source monorepo (djd1m/dz-harness-hub) is private; the links above are the public entry points.
• npm: https://www.npmjs.com/package/@dzhechkov/skills-feature-adr
• Keysarium: https://www.npmjs.com/package/@dzhechkov/keysarium
• BTO: https://www.npmjs.com/package/@dzhechkov/skills-bto