@dzhechkov/skills-feature-adr 1.3.10 → 1.3.12

package/README.md

@@ -379,7 +379,8 @@ npx @dzhechkov/skills-feature-adr init --with-learning --knowledge-extractor
 
 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, orthogonal concern. The three layers do **not conflict**: each is isolated by its own
+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? |
@@ -408,6 +409,25 @@ storage path, its own learning signal, and its own consumer.
 - 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`. The
+  SessionEnd hook automates this **only on clean session ends** — crashed or killed sessions are
+  missed.
+
+**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.
@@ -446,6 +466,46 @@ npx @dzhechkov/skills-feature-adr init     # Feature development
 
 ---
 
+## 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/skills-feature-adr@x.y.z`) does **not** bypass
+workspace resolution — verified.
+
+**Fixes:**
+
+```bash
+# 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](https://docs.anthropic.com/en/docs/claude-code))

package/docs/team-onboarding.md

@@ -208,6 +208,19 @@ consumer):
 **Do you need agentdb?** For A and B — **no** (each has its own store). Only layer C's *vector* tier
 uses agentdb, and even there it's optional (lexical recall works without it).
 
+**Maintenance: consolidate periodically.** Hooks/events only *collect* raw data — distilling it into
+reusable patterns is a separate consolidation step:
+- **A** — nothing to do (consolidates implicitly at each checkpoint).
+- **B** — agentic-qe queues raw experiences that only its consolidation pass distills. Skip it and a
+  project can pile up thousands of unconsolidated experiences while per-prompt pattern injection
+  returns zero useful patterns. Run `aqe learning consolidate` periodically (weekly, or after a
+  heavy QE run); `aqe learning stats` shows the backlog.
+- **C** — run `dz consolidate` (harvests session learnings into the lexical store, mirrored to the
+  vector store if present); inspect with `dz recall`. The SessionEnd hook covers **clean exits only**.
+
+**Degradation symptom:** patterns stop improving while raw logs keep growing → you're collecting,
+not distilling. Consolidate.
+
 ---
 
 ## 9. Team workflow conventions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.10",
+  "version": "1.3.12",
   "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/templates/.claude/skills/feature-adr/SKILL.md

@@ -216,6 +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) |
 | `{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] |
@@ -342,18 +343,32 @@ 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)
+
+When `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`, the pipeline runs a recall → store cycle
+over agentic-qe's MCP pattern memory (`namespace: "learning"`, `fleet_init` first):
+
+- **Step 0** — `memory_query("patterns/feature-adr/*")` → sets `{LEARNED_PATTERNS}` (top-3 by confidence); Step 1 folds them into the requirements brief as advisory lessons.
+- **Step 8** — recalls `patterns/feature-adr/qe/*` to prime the review checklist; stores a `qe-outcome` record after the gap loop closes.
+- **Step 9** — recalls `patterns/feature-adr/fleet/*` to prime agent focus; stores a `fleet-qe-finding` record after the fleet verdict.
+
+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, is gated on Direct modes only, and never touches `.keysarium/memory/`.
+
 ### What changes with `--full-qe`
 
 Full agentic-qe protocols for the same 9 core skills. No new agents, just deeper methodology.
 
 | Step | Reference Mode (default) | Direct Mode (`--full-qe`) |
 |------|--------------------------|---------------------------|
+| Step 0 | Standard routing | + pattern recall → `{LEARNED_PATTERNS}` |
 | Step 3 | Condensed shift-left protocol | Full Level 1-4 shift-left with BDD generators |
 | Step 3.5 | 3 core + flag-based conditionals | Full QCSD swarm with all 9 agents + DDD mapping |
 | Step 6 | SPARC-GOAP goal state analysis | Full agent with milestone tracking + success metrics |
 | Step 7 | Standard code generation | Standard code generation (no change) |
-| Step 8 | Brutal-honesty 3-mode review | Full calibration levels (1-3) + evidence protocol |
-| Step 9 | 4 agents with condensed protocols | 4 agents with full agentic-qe protocols |
+| Step 8 | Brutal-honesty 3-mode review | Full calibration levels (1-3) + evidence protocol + QE pattern recall/store |
+| Step 9 | 4 agents with condensed protocols | 4 agents with full agentic-qe protocols + fleet pattern recall/store |
 
 ### What `--full-qe-extended` adds on top
 
@@ -399,7 +414,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` | 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. |
+| `--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. A separate loop exists: in Direct modes (`--full-qe`/`--full-qe-extended`) the pipeline wires **agentic-qe MCP** pattern memory into Steps 0/8/9 — see "Pattern memory loop (Direct modes)" above. |
 | `--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

@@ -79,6 +79,18 @@ Load `references/complexity-matrix.md` for the full matrix. Summary:
 
 R = Requirements, P = Planning (ADR+DDD+Arch), I = Implementation, Q = QE
 
+### 6. Pattern Recall (Direct Mode only)
+
+Runs after tier classification, only when `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`
+(set during Step 0 flag detection per SKILL.md: `--full-qe`/`--full-qe-extended` + agentic-qe installed). Non-blocking — an error or empty result must never stall the pipeline.
+
+1. If the aqe fleet is not yet initialized this session, call `mcp__agentic-qe__fleet_init` first (required before any other aqe MCP tool).
+2. Call `mcp__agentic-qe__memory_query({ pattern: "patterns/feature-adr/*", namespace: "learning", limit: 5 })`.
+3. Select the top 3 results by `confidence` → set `{LEARNED_PATTERNS}`.
+4. Reference mode, no hits, or error → `{LEARNED_PATTERNS}` = `[]`; proceed normally.
+
+Step 1 folds `{LEARNED_PATTERNS}` into the requirements brief as "lessons from previous features" — advisory context only, never requirements themselves. Why here: Step 0 is the one point where recall can be keyed to the feature's phase and domain — per-prompt hook auto-injection cannot see which pipeline step is running.
+
 ## Output
 
 Set the following variables:
@@ -88,6 +100,7 @@ Set the following variables:
 {ACTIVE_STEPS} = [0, 1, 6, 7, 8]  # example for S
 {TIME_BUDGET} = { requirements: 2, planning: 0, implementation: 10, qe: 3 }
 {DIMENSION_SCORES} = { files: 1, domains: 1, integrations: 1, breaking: 1, models: 1, crosscutting: 1 }
+{LEARNED_PATTERNS} = [ ... ]  # top-3 by confidence from memory_query; [] in reference mode / no hits / error
 ```
 
 Create artifact: `features/<slug>/00_complexity_assessment.md`

package/templates/.claude/skills/feature-adr/modules/01-requirements.md

@@ -29,6 +29,12 @@ Read: .claude/skills/explore/SKILL.md
 Use the explore skill to clarify ambiguous requirements through adaptive questioning.
 For S-tier: skip explore, extract requirements directly from description.
 
+### 1.5 Fold Learned Patterns (Direct modes only)
+
+If `{LEARNED_PATTERNS}` is non-empty (set by Step 0's Pattern Recall), fold each into the
+requirements brief as an advisory "lesson from previous features" — context that informs
+elicitation, never a requirement itself. Empty/absent → skip silently.
+
 ### 2. Identify Stakeholders
 
 | Question | Why |

package/templates/.claude/skills/feature-adr/modules/08-qe.md

@@ -56,6 +56,19 @@ For critical user flows:
 - Test with realistic data volumes
 - Test failure recovery scenarios
 
+### 2.5 QE Pattern Recall (Direct Mode only)
+
+When `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`, before the brutal-honesty review starts,
+recall prior QE outcomes for similar work:
+
+```
+mcp__agentic-qe__memory_query({ pattern: "patterns/feature-adr/qe/*", namespace: "learning", limit: 5 })
+// If this session resumed directly at Step 8, call fleet_init first (as in Steps 0/9).
+```
+
+Use the results to prime the review checklist — e.g. recurring gap types, dimensions that historically
+produced blockers. Non-blocking: empty result or error → proceed with the standard checklist.
+
 ### 3. Code Review via Brutal Honesty Review (M+)
 
 > Load: `references/agentic-qe/brutal-honesty-review.md`
@@ -193,6 +206,28 @@ Compile all findings into a structured report:
 ✅ READY FOR MERGE | ❌ NEEDS FIXES | ⚠️ CONDITIONAL APPROVAL
 ```
 
+### 8. QE Pattern Store (Direct Mode only)
+
+When `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`, after the gap loop is closed and the verdict is set:
+
+```
+mcp__agentic-qe__memory_store({
+  key: "patterns/feature-adr/qe/{timestamp}",
+  namespace: "learning",
+  value: {
+    pattern: "<one-sentence lesson from this QE run>",
+    confidence: <honest 0-1 derived from the gap loop>,
+    type: "qe-outcome",
+    metadata: { tier: "{COMPLEXITY_TIER}", gaps_found: <N>, verdict: "<READY|NEEDS_FIXES|CONDITIONAL>" }
+  },
+  persist: true
+})
+```
+
+Confidence must be honest — derived from the gap loop, never a fabricated 1.0
+(e.g. zero gaps in one iteration ≈ 0.9; gaps remaining after 3 iterations ≤ 0.4).
+Non-blocking: a write failure is logged and the pipeline continues.
+
 ## Output
 
 Create `features/<slug>/08_qe_report.md` with full QE report.

package/templates/.claude/skills/feature-adr/modules/09-fleet-qe.md

@@ -263,6 +263,37 @@ are added — the same fleet runs with deeper methodology from the full skill fi
 | Agent 3 | Condensed enterprise-integration | Full hierarchical fleet + QCSD flags |
 | Agent 4 | Condensed regression-testing | Full change-based + historical + time-budget strategies |
 
+## Pattern Memory Loop (Direct Modes)
+
+When `{AGENTIC_QE_MODE}` = `direct` | `direct-extended`, Step 9 runs a recall → store cycle over
+agentic-qe pattern memory. Non-blocking: errors or empty results never stall the assessment.
+(`fleet_init` was called in Step 0; call it first if this session resumed at Step 9.)
+
+**Before fleet assembly** — prime agent focus areas:
+
+```
+mcp__agentic-qe__memory_query({ pattern: "patterns/feature-adr/fleet/*", namespace: "learning", limit: 5 })
+```
+
+Fold recurring findings (e.g. traceability chains that historically break, risk categories that recur)
+into each agent's scope brief.
+
+**After the fleet verdict** — store the finding for future pipeline runs:
+
+```
+mcp__agentic-qe__memory_store({
+  key: "patterns/feature-adr/fleet/{timestamp}",
+  namespace: "learning",
+  value: {
+    pattern: "<one-sentence lesson from this assessment>",
+    confidence: <honest 0-1 from gap synthesis — never a fabricated 1.0>,
+    type: "fleet-qe-finding",
+    metadata: { tier: "{COMPLEXITY_TIER}", verdict: "{FLEET_QE_VERDICT}", agents_used: <4-7>, remediation_count: <N> }
+  },
+  persist: true
+})
+```
+
 ## Direct Extended Mode (`--full-qe-extended`)
 
 When `{AGENTIC_QE_MODE}` = `direct-extended`, Step 9 gets everything from
@@ -282,7 +313,7 @@ These agents are spawned alongside Agents 1-4 in the same message.
 
 After Step 9 completes, if `--full-qe-extended` is active:
 1. Load `qcsd-production-swarm` feedback loop patterns
-2. Store Fleet QE findings in memory for future pipeline runs
+2. Store Fleet QE findings via the Pattern Memory Loop above (`patterns/feature-adr/fleet/{timestamp}`)
 3. Flag production health risks for monitoring post-deploy
 4. Advisory: suggest post-deploy monitoring checklist