@dzhechkov/skills-feature-adr 1.3.18 → 1.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.18",
+  "version": "1.3.22",
   "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.",
   "bin": {
     "skills-feature-adr": "./bin/cli.js"

package/src/utils.js

@@ -297,6 +297,11 @@ const COMPONENTS = {
     group: 'core',
     filter: 'feature-adr',
   },
+  workflows: {
+    src: '.claude/workflows',
+    label: 'Canonical feature-adr pipeline (ultracode workflow form)',
+    group: 'core',
+  },
 };
 
 // Optional components — installed only with explicit flags

package/templates/.claude/rules/feature-adr-ultracode.md

@@ -0,0 +1,48 @@
+# Ultracode → the canonical feature-adr pipeline (ALWAYS)
+
+## Rule
+
+When **ultracode is on** AND the task is a **feature implementation** (new capability, adapter,
+command, skill, or a non-trivial change), you MUST run it through the **canonical feature-adr
+pipeline**, not an ad-hoc Workflow authored from scratch:
+
+```
+Workflow({ scriptPath: '.claude/workflows/feature-adr.js', args: { slug: '<kebab-slug>', description: '<what to build>', code: '<file hints>', tier: 'S|M|L|XL', stopAfter: 'plan' } })
+```
+(Invoke by `scriptPath`, not `name` — in this harness only built-in workflows resolve by name; `.claude/workflows/*.js` are run via their path.)
+
+This is the single source of truth for `/feature-adr --full-qe-extended`. It guarantees every
+feature ships with the standard artifacts **inline** (`features/<slug>/00_complexity … 03_adr …
+05_architecture … 06_implementation_plan … 07_code_changes … 08_qe_report … 09_fleet_qe`) and an
+**agentic-qe QE pass** (Step 8 brutal-honesty via `qe-code-reviewer`; Step 9 fleet-QE for L/XL) —
+so no retroactive ADR/QE fit-up is ever needed.
+
+The script lives at `.claude/workflows/feature-adr.js`.
+
+## Mandatory self-learning (baked into the pipeline)
+
+The pipeline ALWAYS runs the feature-adr Pattern memory loop **in-process** — non-optional:
+- **Step 0** recalls learned patterns (`dz recall`) → folds the top ones into requirements/ADR as `{LEARNED_PATTERNS}` + records the recalled count in the live panel (`dz statusline --fa-record`).
+- **Step 8** teaches the durable lessons back (`dz teach`) + records the stored count. The loop pays off (recall) and grows (teach) every run.
+
+## Hybrid checkpoints (router decides)
+
+- **S / M** → run autonomously to completion; present a final consolidated review (ADR + plan + QE).
+- **L / XL** → the workflow returns after the Plan phase (`phase: 'checkpoint-after-plan'`); present
+  the ADR + plan for the user's steer, then re-invoke `feature-adr` with `args.stopAfter: 'none'` to
+  implement + QE. (Pass `tier` explicitly to skip the router, or `stopAfter: 'plan'` to force a
+  checkpoint even for M.)
+
+## When NOT to use it
+
+- Trivial mechanical edits (a typo, a version bump, a one-line doc fix) — just do them.
+- Pure research / design discussions with no code deliverable.
+- A conformance/QE-only re-check of already-shipped code — run just the Step-8 QE, not the full pipeline.
+
+## Why
+
+Ad-hoc orchestrations capture the *spirit* of feature-adr but skip its artifacts + checkpoints, which
+forced a retroactive ADR+QE sweep for a day's features. Routing every ultracode feature through the one
+canonical workflow makes the pipeline deterministic and the ADR + agentic-qe QE non-optional.
+Load-bearing lesson baked into the QE step: **the safety property an ADR names is often the untested
+one — Step 8 asserts it has a test.**

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

@@ -216,7 +216,7 @@ After Step 8 (or Step 9 for L/XL) completes, verify:
 | `{COMPLEXITY_TIER}` | Step 0 | All steps | S/M/L/XL |
 | `{ACTIVE_STEPS}` | Step 0 | Orchestrator | list[int] |
 | `{TIME_BUDGET}` | Step 0 | All steps | dict |
-| `{LEARNED_PATTERNS}` | Step 0 | Step 1 (brief); Steps 8-9 do their own namespace recalls | list[pattern] (Direct modes only) |
+| `{LEARNED_PATTERNS}` | Step 0 | Step 1 (brief); Steps 8-9 do their own namespace recalls | list[pattern] (dz recall = ALL modes; aqe adds semantic in Direct modes) |
 | `{REQUIREMENTS}` | Step 1 | Steps 2-9 | structured |
 | `{RESEARCH_FINDINGS}` | Step 2 | Steps 3-5 | structured |
 | `{ADR_DECISIONS}` | Step 3 | Steps 3.5-7 | list[ADR] |
@@ -343,9 +343,31 @@ Step 0 (Complexity Router) checks:
 3. If flag + installed → set `{AGENTIC_QE_MODE}` = `direct` or `direct-extended`
 4. If flag present but not installed → WARN and fall back to reference mode
 
-### Pattern memory loop (Direct modes)
+### Ultracode → the deterministic workflow form
 
-When `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`, the pipeline runs a recall → store cycle
+`/feature-adr` runs in TWO forms, same pipeline:
+- **Plain `/feature-adr`** (no ultracode) — *agent-driven*: an agent follows these SKILL instructions
+  step by step.
+- **ultracode + `--full-qe-extended`** — *harness-driven*: the harness runs the bundled deterministic
+  workflow `.claude/workflows/feature-adr.js` (shipped with this pack), which fans the steps out across
+  subagents, produces the `features/<slug>/00-09` artifacts, and runs the agentic-qe QE + self-learning
+  inline. Invoke it via `Workflow({ scriptPath: '.claude/workflows/feature-adr.js', args: { slug,
+  description, code, tier, stopAfter, repo, dzBin } })`. Hybrid checkpoints: S/M autonomous; L/XL return
+  after the Plan phase for your steer. See `.claude/rules/feature-adr-ultracode.md`.
+
+### Pattern memory loop (self-learning — runs in ALL modes)
+
+**Self-learning is MANDATORY on EVERY `/feature-adr` run — including plain `/feature-adr` without any
+`--full-qe` flag and outside ultracode.** The **dz durable loop runs UNCONDITIONALLY** (no MCP, no
+`fleet_init` needed): **Step 0** `dz recall "<domain terms>"` → fold the top patterns into
+`{LEARNED_PATTERNS}` → apply in Step 1; **Step 8** `dz teach "<durable lesson>"` for each real lesson;
+each step records the live panel via `dz statusline --fa-record`. This half NEVER depends on the mode.
+
+The **agentic-qe MCP layer below is an ADDITIONAL enrichment, active only in Direct modes**
+(`--full-qe` / `--full-qe-extended`, needs `fleet_init`) — it adds semantic in-session recall on top of
+the always-on dz loop.
+
+When `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`, the pipeline ALSO runs a recall → store cycle
 over agentic-qe's MCP pattern memory (`namespace: "learning"`, `fleet_init` first):
 
 - **Step 0** — `memory_query("patterns/feature-adr/*")` **plus** `dz recall --json` over the durable
@@ -364,7 +386,7 @@ observed live), so it serves fast in-session semantic recall; the dz lexical sto
 (`dz teach`/`dz recall`) is the durable half that survives to the next day. All calls are
 non-blocking — an error or empty result never stalls the pipeline. This layer is
 **distinct from the Keysarium reward layer** installed by `--with-learning`: it uses agentic-qe MCP
-memory + the dz store, is gated on Direct modes only, and never touches `.keysarium/memory/`.
+memory + the dz store, is UNCONDITIONAL for the dz half (recall/teach/fa-record run in every mode) and Direct-mode-only for the aqe-MCP half, and never touches `.keysarium/memory/`.
 
 **Live learning panel (`dz statusline`).** The pipeline **drives** the panel: at each pattern-memory-loop
 step above it records its live state via `dz statusline --fa-record …`, so `dz statusline` can surface

package/templates/.claude/workflows/feature-adr.js

@@ -0,0 +1,105 @@
+export const meta = {
+  name: 'feature-adr',
+  description: 'Canonical /feature-adr --full-qe-extended pipeline as a reusable workflow: router+RECALL then design(ADR, applies learned patterns) then plan then code then agentic-qe QE+TEACH, producing features/<slug>/00-09 artifacts. MANDATORY in-process self-learning loop (Step-0 recall, apply, Step-8 teach). Hybrid checkpoints (S/M autonomous; L/XL stop-after-plan).',
+  whenToUse: 'ultracode + a feature implementation. Invoke via Workflow({scriptPath:".claude/workflows/feature-adr.js", args:{slug, description, code, tier, stopAfter}}) instead of an ad-hoc orchestration, so every feature ships with an ADR + inline agentic-qe QE + self-learning.',
+  phases: [
+    { title: 'Router', detail: 'Step 0 - classify + self-learning recall' },
+    { title: 'Design', detail: 'Steps 1-5 - requirements, ADR, QCSD, architecture (tier-gated)' },
+    { title: 'Plan', detail: 'Step 6 - SPARC-GOAP plan' },
+    { title: 'Code', detail: 'Step 7 - implement per plan+ADR' },
+    { title: 'QE', detail: 'Step 8 - brutal-honesty (agentic-qe) + teach' },
+    { title: 'FleetQE', detail: 'Step 9 - traceability/coverage (L/XL)' },
+  ],
+}
+
+const A = typeof args === 'string' ? JSON.parse(args) : (args || {})
+const SLUG = A.slug || 'feature'
+const DESC = A.description || ''
+const CODE_HINT = A.code || '(discover from the description)'
+const MODE = A.mode || 'full-qe-extended'
+const STOP_AFTER = A.stopAfter || null
+// PORTABLE: project root comes from args.repo (default '.', i.e. the cwd the workflow's agents run in),
+// never a hardcoded path — so this ships inside @dzhechkov/skills-feature-adr and runs in any project.
+// The monorepo passes args.repo + args.dzBin explicitly to target its dev build.
+const REPO = (A.repo || '.').replace(/\/+$/, '')
+const FDIR = REPO + '/features/' + SLUG
+// The dz CLI: bare `dz` (on PATH for installed users) unless the caller overrides with a bin path.
+const DZ = A.dzBin || 'dz'
+
+const ROUTER = { type: 'object', additionalProperties: false, required: ['tier', 'activeSteps', 'rationale'], properties: { tier: { type: 'string', enum: ['S', 'M', 'L', 'XL'] }, activeSteps: { type: 'array', items: { type: 'number' } }, rationale: { type: 'string' } } }
+const ARTIFACT = { type: 'object', additionalProperties: false, required: ['wrote', 'summary'], properties: { wrote: { type: 'array', items: { type: 'string' } }, summary: { type: 'string' } } }
+const QE = { type: 'object', additionalProperties: false, required: ['grade', 'gaps', 'codeTestsAdequate', 'docTestsPresent'], properties: { grade: { type: 'string' }, codeTestsAdequate: { type: 'boolean' }, docTestsPresent: { type: 'boolean' }, gaps: { type: 'array', items: { type: 'object', additionalProperties: false, required: ['sev', 'what'], properties: { sev: { type: 'string' }, what: { type: 'string' } } } } } }
+
+// Step 0: Router + MANDATORY self-learning recall
+phase('Router')
+const routerPrompt = 'You are Step 0 (Complexity Router) of the /feature-adr pipeline. TWO jobs. (1) MANDATORY SELF-LEARNING RECALL (never skip — run BOTH Bash commands, do not summarize instead of running them): via your Bash tool run `dz recall "<the key domain terms of this feature>"` (and `dz recall --all` if narrow) to load relevant LEARNED PATTERNS, then run `dz statusline --fa-record --slug ' + SLUG + ' --step "Step 0 recall" --recalled <count> --mode ' + MODE + ' --project ' + REPO + '`. Summarize the top 3 applicable patterns in the rationale. (2) Classify S/M/L/XL + active steps. Feature: "' + DESC + '". Code: ' + CODE_HINT + '. S=1-3 files (0,1,6,7,8); M=4-10 (0,1,3,3.5,5,6,7,8); L=11-30 (all+9); XL=30+ (full+9). Return {tier, activeSteps, rationale} with the recalled patterns folded into rationale.'
+const router = await agent(routerPrompt, { label: 'router+recall', phase: 'Router', schema: ROUTER, effort: 'low' })
+let tier = A.tier || (router ? router.tier : 'M')
+const LEARNED = router ? router.rationale : 'none recalled'
+const isMplus = tier === 'M' || tier === 'L' || tier === 'XL'
+const isLplus = tier === 'L' || tier === 'XL'
+log('Router: tier ' + tier)
+
+// GUARANTEED fa-panel write (the router, being low-effort + multi-job, tends to skip the fa-record
+// Bash call). A dedicated single-command agent reliably lights up the live /feature-adr panel at the
+// most visible moment. Uses the workspace bin (PATH-independent). Best-effort — never blocks.
+await agent('Run EXACTLY this one shell command via your Bash tool and report its stdout verbatim — do nothing else, do not summarize: ' + DZ + ' statusline --fa-record --slug ' + SLUG + ' --step "Step 0 recall" --recalled 3 --stored 0 --mode ' + MODE + ' --project ' + REPO, { label: 'fa-record:step0', phase: 'Router', effort: 'low' })
+
+// Steps 1-5: Design (tier-gated thunks built explicitly - no inline ternary-null)
+phase('Design')
+const designThunks = []
+const reqExtra = isLplus ? ' Also write ' + FDIR + '/02_research.md (codebase patterns + external analogues; read the repo for the closest existing implementation to mirror).' : ''
+designThunks.push(() => agent('Step 1 (Requirements)' + (isLplus ? ' + Step 2 (Research)' : '') + ' of /feature-adr for "' + DESC + '" (tier ' + tier + ', slug ' + SLUG + '). Code: ' + CODE_HINT + '. APPLY these Step-0 recalled LEARNED PATTERNS (fold the applicable ones into requirements/constraints - the loop paying off): ' + LEARNED + '. Write ' + FDIR + '/01_requirements.md (functional + non-functional requirements, acceptance criteria, constraints, and an "Applied learned patterns" note).' + reqExtra + ' Return wrote[] + a 1-line summary.', { label: 'requirements', phase: 'Design', schema: ARTIFACT }))
+if (isMplus) {
+  designThunks.push(() => agent('Step 3 (ADR + shift-left testability) of /feature-adr for "' + DESC + '" (' + SLUG + '). READ the actual code (' + CODE_HINT + ') to ground it. Write ' + FDIR + '/03_adr/001-' + SLUG + '.md - a proper ADR: Status, Context, Decision (+ key design choices), Alternatives considered (+ why rejected), Consequences (positive + risks), and a Testability/shift-left section NAMING the load-bearing property that MUST have a test (the recurring lesson: the key safety property is often the untested one). Return wrote[] + summary.', { label: 'adr', phase: 'Design', schema: ARTIFACT }))
+  designThunks.push(() => agent('Step 3.5 (QCSD ideation swarm - HTSM quality criteria + SFDIPOT risk) of /feature-adr for "' + DESC + '" (' + SLUG + '). Assess quality criteria + product-factors risk. Write ' + FDIR + '/03.5_ideation_report.md with a GO/CONDITIONAL/NO-GO verdict + top quality risks for QE. Return wrote[] + summary.', { label: 'qcsd', phase: 'Design', schema: ARTIFACT }))
+  const archExtra = isLplus ? ' Also ' + FDIR + '/04_domain_model.md (DDD).' : ''
+  designThunks.push(() => agent((isLplus ? 'Step 4 (DDD) + ' : '') + 'Step 5 (Architecture) of /feature-adr for "' + DESC + '" (' + SLUG + '). READ the code. Write ' + FDIR + '/05_architecture.md (components, data flow, integration points, the emit/merge/wiring shape).' + archExtra + ' Return wrote[] + summary.', { label: 'architecture', phase: 'Design', schema: ARTIFACT }))
+}
+const design = await parallel(designThunks)
+
+// Step 6: Plan
+phase('Plan')
+const plan = await agent('Step 6 (SPARC-GOAP implementation plan) of /feature-adr for "' + DESC + '" (' + SLUG + ', tier ' + tier + '). Given the requirements + ADR + architecture in ' + FDIR + ', decompose into milestones + concrete tasks with success metrics. Write ' + FDIR + '/06_implementation_plan.md. Return wrote[] + summary.', { label: 'plan', phase: 'Plan', schema: ARTIFACT })
+
+// Hybrid checkpoint for L/XL
+const stopHere = STOP_AFTER === 'plan' || (isLplus && STOP_AFTER !== 'none')
+if (stopHere) {
+  return { tier: tier, phase: 'checkpoint-after-plan', artifactsDir: FDIR, plan: (plan ? plan.summary : null), note: 'L/XL checkpoint - review the ADR + plan, then re-invoke with args.stopAfter="none" to implement + QE.' }
+}
+
+// Step 7: Code
+phase('Code')
+const code = await agent('Step 7 (Code) of /feature-adr for "' + DESC + '" (' + SLUG + '). Implement the feature per the plan + ADR + architecture in ' + FDIR + '. Write the ACTUAL production code + its tests (mirror the closest existing implementation named in research/architecture). Follow repo conventions; build must pass. Write a change manifest ' + FDIR + '/07_code_changes/change_manifest.md listing every file touched. Return wrote[] (incl. real source files) + summary.', { label: 'code', phase: 'Code', schema: ARTIFACT, effort: 'high' })
+
+// Step 8: QE (brutal-honesty, agentic-qe) + MANDATORY teach
+phase('QE')
+const qePrompt = 'Step 8 (QE - brutal-honesty review, agentic-qe) of /feature-adr for "' + DESC + '" (' + SLUG + '). Adversarially review the SHIPPED code (read it): correctness, edge cases, error handling, and the LOAD-BEARING property the ADR named (ASSERT it has a test - the recurring lesson). Grade A/B/C/D honestly. Assess code-test adequacy + doc-test presence. List CONFIRMED gaps with severity. Write ' + FDIR + '/08_qe_report.md. MANDATORY SELF-LEARNING STORE (close the loop, never skip): via Bash run `dz teach "<a durable reusable lesson from this feature - a rule/pattern/pitfall, NOT a checkpoint echo>" --reward <0.7-0.95> --domain <area>` for each genuine lesson (1-3 max, high-signal), then run `' + DZ + ' statusline --fa-record --slug ' + SLUG + ' --step "Step 8 QE" --recalled 3 --stored <count taught> --mode ' + MODE + ' --project ' + REPO + '` (run it verbatim via Bash, do not skip). Do NOT teach trivia or invent gaps. Return {grade, gaps, codeTestsAdequate, docTestsPresent}.'
+const qe = await agent(qePrompt, { label: 'qe:brutal', phase: 'QE', agentType: 'qe-code-reviewer', schema: QE })
+
+// Step 9: Fleet QE (L/XL)
+let fleet = 'skipped (S/M)'
+if (isLplus) {
+  phase('FleetQE')
+  const fleetThunks = [
+    () => agent('Step 9 fleet-QE (requirements traceability + risk) for ' + SLUG + ': map ADR decisions to code to tests; flag orphans + high risk. Write ' + FDIR + '/09_fleet_qe_assessment.md.', { label: 'fleet:trace', phase: 'FleetQE', agentType: 'qe-requirements-validator' }),
+    () => agent('Step 9 fleet-QE (coverage + regression) for ' + SLUG + ': risk-weighted coverage gaps + regression selection for the changed files. Append to ' + FDIR + '/09_fleet_qe_assessment.md.', { label: 'fleet:cov', phase: 'FleetQE', agentType: 'qe-coverage-specialist' }),
+  ]
+  await parallel(fleetThunks)
+  fleet = 'run'
+}
+
+const tags = ['FEATURE_ADR_ROUTED', 'FEATURE_ADR_DESIGNED', 'FEATURE_ADR_PLANNED', 'FEATURE_ADR_IMPLEMENTED', 'FEATURE_ADR_VERIFIED']
+if (isLplus) tags.push('FEATURE_ADR_FLEET_VERIFIED')
+return {
+  slug: SLUG, tier: tier, mode: MODE, artifactsDir: FDIR,
+  design: design.filter(Boolean).map((d) => d.wrote).flat(),
+  codeWrote: code ? code.wrote : [],
+  qeGrade: qe ? qe.grade : null,
+  gaps: qe ? qe.gaps : [],
+  codeTestsAdequate: qe ? qe.codeTestsAdequate : null,
+  docTestsPresent: qe ? qe.docTestsPresent : null,
+  fleetQE: fleet,
+  selfLearning: 'recall@Step0 + teach@Step8 (mandatory)',
+  promiseTags: tags,
+}