continuous-improvement 3.1.0 → 3.9.1

package/commands/harvest.md

@@ -0,0 +1,76 @@
+---
+name: harvest
+description: Harvest friction events from observation logs into typed instincts (env_issue, permission_block, wrong_approach, buggy_code) with confidence scoring.
+---
+
+# /harvest — Friction Harvest
+
+Run the friction-harvest classifier against this project's observation log and append new typed instincts to `instincts.jsonl`. Idempotent on re-run.
+
+## What it does
+
+Reads `~/.claude/instincts/<project-hash>/observations.jsonl` produced by the Mulahazah hook, classifies failure rows into four typed friction patterns, scores confidence with a recency-weighted decay, and appends new instincts to `<project-hash>/instincts.jsonl` alongside.
+
+| Type | What it catches |
+|---|---|
+| `env_issue` | jq missing, command not found, not recognized as cmdlet |
+| `permission_block` | sandbox / harness blocked, Permission denied |
+| `wrong_approach` | file changed since last read (parallel-actor stale) |
+| `buggy_code` | file not read first, old_string ambiguous, file too large |
+
+## How to invoke
+
+```
+node bin/harvest-friction.mjs
+node bin/harvest-friction.mjs <project-hash>
+node bin/harvest-friction.mjs --list
+```
+
+`--list` shows new classifications without writing to `instincts.jsonl` — useful for dry-run before committing the harvest output.
+
+## Idempotency
+
+Each instinct carries a `dedup_key = sha1(type + tool + summary[:120])`. Re-running on the same observations does not duplicate previously-written instincts; `loadExistingDedupKeys()` reads the destination file once at start.
+
+## Confidence model
+
+```
+confidence = log10(occurrence_count + 1) * recency_factor
+recency_factor = 0.5 + 0.5 * exp(-days_since_last_seen / 14)
+```
+
+One occurrence today → 0.30. Ten occurrences today → clamped to 1.0. One occurrence 30 days ago → 0.17.
+
+## Output shape
+
+```
+harvest-friction project=0af156594b39
+  observations rows:    9346
+  tool_complete rows:   2104
+  classified failures:  47
+  thin-schema rows:     0
+  new instincts:        12
+  skipped (existing):   35
+
+New instincts:
+  [0.92] env_issue on Bash (×8): bash: jq: command not found
+  [0.74] permission_block on Bash (×4): harness blocked direct push to main
+  ...
+
+Appended 12 instinct(s) to /Users/.../instincts/0af156594b39/instincts.jsonl
+```
+
+## When the classifier emits zero instincts
+
+If `tool_complete rows: 0`, the bash-fallback hook is active (no jq AND the Node observer is not on PATH) and only emits `tool_start` events. Two remediation paths:
+
+- **Install jq** — `winget install jqlang.jq` (Windows), `brew install jq` (macOS), `apt install jq` (Linux).
+- **Wire the Node observer** — ensure `hooks/bin/observe.mjs` is reachable from the active hook script.
+
+Both are documented in the WARNING the classifier prints on a thin-schema host.
+
+## Pairs with
+
+- **`continuous-improvement`** (core SKILL.md, Law 7 — Learn From Every Session) — the harvest pipeline is the concrete mechanism behind Law 7's "capture patterns as instincts" contract.
+- **`workspace-surface-audit`** — Phase 1 Environment Grain confirms whether jq + Node observer are available; if not, the harvest will run inert until that gap closes.
+- **`gateguard`** — observation rows include the Parallel-Actor Gate's HEAD/upstream baselines when divergence-halts fire; the classifier surfaces those as `wrong_approach` instincts.

package/commands/learn-eval.md

@@ -0,0 +1,117 @@
+---
+name: learn-eval
+description: "Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project)."
+---
+
+# /learn-eval - Extract, Evaluate, then Save
+
+Extends `/learn` with a quality gate, save-location decision, and knowledge-placement awareness before writing any skill file.
+
+## What to Extract
+
+Look for:
+
+1. **Error Resolution Patterns** — root cause + fix + reusability
+2. **Debugging Techniques** — non-obvious steps, tool combinations
+3. **Workarounds** — library quirks, API limitations, version-specific fixes
+4. **Project-Specific Patterns** — conventions, architecture decisions, integration patterns
+
+## Process
+
+1. Review the session for extractable patterns
+2. Identify the most valuable/reusable insight
+
+3. **Determine save location:**
+   - Ask: "Would this pattern be useful in a different project?"
+   - **Global** (`~/.claude/skills/learned/`): Generic patterns usable across 2+ projects (bash compatibility, LLM API behavior, debugging techniques, etc.)
+   - **Project** (`.claude/skills/learned/` in current project): Project-specific knowledge (quirks of a particular config file, project-specific architecture decisions, etc.)
+   - When in doubt, choose Global (moving Global → Project is easier than the reverse)
+
+4. Draft the skill file using this format:
+
+```markdown
+---
+name: pattern-name
+description: "Under 130 characters"
+user-invocable: false
+origin: auto-extracted
+---
+
+# [Descriptive Pattern Name]
+
+**Extracted:** [Date]
+**Context:** [Brief description of when this applies]
+
+## Problem
+[What problem this solves - be specific]
+
+## Solution
+[The pattern/technique/workaround - with code examples]
+
+## When to Use
+[Trigger conditions]
+```
+
+5. **Quality gate — Checklist + Holistic verdict**
+
+   ### 5a. Required checklist (verify by actually reading files)
+
+   Execute **all** of the following before evaluating the draft:
+
+   - [ ] Grep `~/.claude/skills/` and relevant project `.claude/skills/` files by keyword to check for content overlap
+   - [ ] Check MEMORY.md (both project and global) for overlap
+   - [ ] Consider whether appending to an existing skill would suffice
+   - [ ] Confirm this is a reusable pattern, not a one-off fix
+
+   ### 5b. Holistic verdict
+
+   Synthesize the checklist results and draft quality, then choose **one** of the following:
+
+   | Verdict | Meaning | Next Action |
+   |---------|---------|-------------|
+   | **Save** | Unique, specific, well-scoped | Proceed to Step 6 |
+   | **Improve then Save** | Valuable but needs refinement | List improvements → revise → re-evaluate (once) |
+   | **Absorb into [X]** | Should be appended to an existing skill | Show target skill and additions → Step 6 |
+   | **Drop** | Trivial, redundant, or too abstract | Explain reasoning and stop |
+
+   **Guideline dimensions** (informing the verdict, not scored):
+
+   - **Specificity & Actionability**: Contains code examples or commands that are immediately usable
+   - **Scope Fit**: Name, trigger conditions, and content are aligned and focused on a single pattern
+   - **Uniqueness**: Provides value not covered by existing skills (informed by checklist results)
+   - **Reusability**: Realistic trigger scenarios exist in future sessions
+
+6. **Verdict-specific confirmation flow**
+
+   - **Improve then Save**: Present the required improvements + revised draft + updated checklist/verdict after one re-evaluation; if the revised verdict is **Save**, save after user confirmation, otherwise follow the new verdict
+   - **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
+   - **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
+   - **Drop**: Show checklist results + reasoning only (no confirmation needed)
+
+7. Save / Absorb to the determined location
+
+## Output Format for Step 5
+
+```
+### Checklist
+- [x] skills/ grep: no overlap (or: overlap found → details)
+- [x] MEMORY.md: no overlap (or: overlap found → details)
+- [x] Existing skill append: new file appropriate (or: should append to [X])
+- [x] Reusability: confirmed (or: one-off → Drop)
+
+### Verdict: Save / Improve then Save / Absorb into [X] / Drop
+
+**Rationale:** (1-2 sentences explaining the verdict)
+```
+
+## Design Rationale
+
+This version replaces the previous 5-dimension numeric scoring rubric (Specificity, Actionability, Scope Fit, Non-redundancy, Coverage scored 1-5) with a checklist-based holistic verdict system. Modern frontier models (Opus 4.6+) have strong contextual judgment — forcing rich qualitative signals into numeric scores loses nuance and can produce misleading totals. The holistic approach lets the model weigh all factors naturally, producing more accurate save/drop decisions while the explicit checklist ensures no critical check is skipped.
+
+## Notes
+
+- Don't extract trivial fixes (typos, simple syntax errors)
+- Don't extract one-time issues (specific API outages, etc.)
+- Focus on patterns that will save time in future sessions
+- Keep skills focused — one pattern per skill
+- When the verdict is Absorb, append to the existing skill rather than creating a new file

package/commands/planning-with-files.md

@@ -0,0 +1,66 @@
+---
+name: planning-with-files
+description: Create and maintain task_plan.md, findings.md, and progress.md for persistent file-based planning
+---
+
+# /planning-with-files
+
+Use this workflow only when the user explicitly wants persistent, file-based planning. It is opt-in.
+
+## Project Root
+
+1. Run `git rev-parse --show-toplevel 2>/dev/null`
+2. If that fails, use the current working directory
+3. Create and read planning files in that root only
+
+The planning files are:
+- `task_plan.md`
+- `findings.md`
+- `progress.md`
+
+## `init`
+
+If the files do not exist, create them in the project root.
+
+`task_plan.md` must include:
+- `## Goal`
+- `## Status`
+- `## Phases`
+- `## Key Questions`
+- `## Decisions Made`
+- `## Errors Encountered`
+
+Default phases:
+- `Research`
+- `Plan`
+- `Execute`
+- `Verify`
+- `Reflect`
+
+Never overwrite existing planning files unless the user explicitly asks you to reset or replace them.
+
+## `status`
+
+Read all three files and summarize:
+- Current status from `task_plan.md`
+- Checked vs unchecked phases
+- Whether `findings.md` has real notes yet
+- Whether `progress.md` has real session or verification entries yet
+
+If the files do not exist, say so and offer to initialize them.
+
+## `checkpoint`
+
+After a meaningful work chunk:
+- Update `progress.md` with what happened, commands run, and verification notes
+- Add new discoveries or sources to `findings.md`
+- Update `task_plan.md` progress, decisions, and errors
+
+Do not hide failures. Log them in `## Errors Encountered`.
+
+## `recover`
+
+When resuming after context loss or a new session:
+- Re-read `task_plan.md`, `findings.md`, and `progress.md` before making major decisions
+- Restate the current goal, phase, open questions, and latest verification state
+- Continue from the recorded plan instead of rebuilding context from memory

package/commands/proceed-with-the-recommendation.md

@@ -0,0 +1,62 @@
+---
+name: proceed-with-the-recommendation
+description: "Execute the agent's prior recommendation list under the 7 Laws — walk in order, route per item, verify, reflect. Standalone companion skill with inline fallbacks when other skills are not installed."
+---
+
+# /proceed-with-the-recommendation
+
+Walk an agent-generated recommendation list top-to-bottom under the continuous-improvement 7 Laws. Each item is routed to the best specialist skill when available, falls back to concrete inline behavior when it is not.
+
+Invoke immediately after the agent has offered a numbered list of recommendations, next steps, or suggested actions.
+
+## Trigger phrases
+
+- `/proceed-with-the-recommendation`
+- "proceed with your recommendation"
+- "do all of it"
+- "go ahead with the plan"
+- "execute the recommendations"
+- "yes do it" / "all of them"
+
+## What happens
+
+1. **Pre-flight (Law 1)** — restate the recommendation list in original order, tag each `safe` / `caution` / `needs-approval`
+2. **Plan (Law 2)** — inline restatement if ≤3 items, call `superpowers:writing-plans` if larger
+3. **Execute (Law 3)** — route each item to the preferred skill; apply inline fallback if the skill is not installed
+4. **Verify (Law 4)** — smallest check per item, non-transitive (no later item retroactively verifies an earlier one)
+5. **Iterate (Law 6)** — one change → verify → next; never carry a failure forward
+6. **Reflect (Laws 5 + 7)** — end-of-run Reflection block appended to `observations.jsonl`
+7. **Close** — three-section user-facing block: **What has been done → What is next → Recommendation** (tiered tables + one decisive "My recommendation" paragraph + a binary "Want me to: A or B?" closer)
+
+## Hard halts (never silently proceed)
+
+- Any `needs-approval` item: deploy, force-push, DB drop, secret change, shared-state mutation
+- Verification failure with non-obvious fix
+- Drive-by temptation outside the original list
+- Context budget above 80%
+
+## Pairs best with
+
+| Preferred skill | Used for |
+|---|---|
+| `workspace-surface-audit` | Law 1 pre-flight when the list touches unknown surface area |
+| `superpowers:writing-plans` | Plan breakdown when the list >3 items or >150 LOC |
+| `superpowers:*` | Per-item specialist routing (TDD, debugging, review, verification, parallel) |
+| `ralph` | Long-running PRD-style autonomous execution |
+| `simplify`, `security-review`, `documentation-lookup`, `schedule`, `loop`, `update-config`, `commit-commands:*` | continuous-improvement helpers |
+
+If none of those are installed, the skill still works — every routing row has an inline fallback and every item still gets a verification step.
+
+## Skill file
+
+Full behavior is defined in [`skills/proceed-with-the-recommendation.md`](../skills/proceed-with-the-recommendation.md).
+
+## Install standalone
+
+```bash
+mkdir -p ~/.claude/skills/proceed-with-the-recommendation
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/proceed-with-the-recommendation.md \
+  -o ~/.claude/skills/proceed-with-the-recommendation/SKILL.md
+```
+
+Restart the Claude Code session so the registry picks it up.

package/commands/ralph.md

@@ -0,0 +1,103 @@
+---
+name: ralph
+description: "Convert PRD to executable JSON and run autonomous agent loop until all stories complete"
+---
+
+# /ralph
+
+Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.
+
+## Subcommands
+
+### `/ralph init`
+
+Initialize Ralph in your project:
+
+1. Create `scripts/ralph/` directory
+2. Add `ralph.sh` loop script
+3. Add prompt templates for Amp and Claude Code
+4. Create example `prd.json`
+
+### `/ralph convert <prd-file>`
+
+Convert a markdown PRD to Ralph's executable JSON format:
+
+```
+/ralph convert tasks/prd-auth-feature.md
+```
+
+Output: `prd.json` with structured user stories
+
+### `/ralph run [iterations]`
+
+Run the autonomous loop:
+
+```
+/ralph run 10
+```
+
+Default: 10 iterations. Stops early if all stories complete.
+
+## Ralph Loop Behavior
+
+1. **Create branch** from PRD `branchName`
+2. **Pick highest priority** story where `passes: false`
+3. **Implement story** — fresh context, no pollution
+4. **Run quality checks** — typecheck, tests, lint
+5. **Commit if passing** — atomic commits per story
+6. **Update prd.json** — mark `passes: true`
+7. **Log learnings** — append to `progress.txt`
+8. **Repeat** until done or max iterations
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `prd.json` | Executable PRD with user stories |
+| `progress.txt` | Accumulated learnings |
+| `ralph.sh` | The loop script |
+| `AGENTS.md` | Iteration memory (auto-updated) |
+
+## Workflow Integration
+
+Ralph works best with:
+- **Superpowers** — for structured development stages
+- **continuous-improvement** — for reflection and learning between iterations
+- **workspace-surface-audit** — to verify capabilities before starting
+
+## Critical Concepts
+
+### Fresh Context Per Iteration
+Each story runs in isolation. Previous work is visible only via git history and `prd.json`.
+
+### AGENTS.md Updates
+Ralph updates `AGENTS.md` after each story so subsequent iterations know what's already done.
+
+### Browser Verification
+For UI stories, Ralph starts a dev server and uses Playwright to verify rendering.
+
+### Stop Conditions
+- All stories pass
+- Max iterations reached
+- Critical failure (requires human intervention)
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Ralph stuck | Check `prd.json` for malformed stories |
+| Tests failing | Run `npm test` independently to isolate |
+| Uncommitted changes | Check git status, commit or stash |
+| Wrong tool | Use `--tool amp` or `--tool claude` flag |
+
+## Example Session
+
+```
+User: /ralph convert tasks/prd-checkout.md
+[Creates prd.json with 8 stories]
+
+User: /ralph run 15
+[Ralph creates branch, implements stories 1-8 over 12 iterations]
+
+[All tests pass, branch ready for PR]
+```

package/commands/release-train.md

@@ -0,0 +1,81 @@
+---
+name: release-train
+description: "Autonomous multi-PR release train — plan stacked single-concern PRs, open each on its own branch, monitor CI, rebase on conflicts, and ship in dependency order while you sleep. Driven by report.html horizon item 'Autonomous Multi-PR Release Trains'."
+---
+
+# /release-train
+
+Long-running autonomous orchestrator for stacked-PR rollouts. Driven by the user's session report (1,218 messages, 178 sessions): the audit-then-execute pattern landed at `fully_achieved` when sessions opened with a stacked-PR plan; sessions that started as big-bang multi-file edits landed at `partially_achieved`.
+
+This command formalizes the pattern. It does NOT bypass branch protection, force-push, or merge unreviewed PRs.
+
+## Preconditions
+
+Before invoking this command:
+
+1. A `RELEASE_PLAN.md` (or `docs/plans/YYYY-MM-DD-<slug>.md`) exists in the repo with a per-PR table, dependency graph, worktree-per-PR, and out-of-scope list. Per the Stacked-PR Plan Precondition in the unified `/superpowers` dispatcher.
+2. The plan was reviewed and explicitly approved by the operator.
+3. The base branch (`main`) is clean and up to date with `origin/main`.
+4. CI is green on `origin/main`.
+
+If any precondition fails, this command halts and reports what is missing rather than improvising.
+
+## Behavior
+
+For each PR in the plan, in dependency order:
+
+1. **Worktree** — `git worktree add -b <branch> ../<branch> origin/main` (or off the previous PR's branch when the dependency requires it).
+2. **Implement** — TDD-first per `superpowers:test-driven-development`: failing test, watch it fail, write minimal code, watch it pass, commit.
+3. **Verify** — `superpowers:verification-before-completion` before claiming done. Smallest check that proves correctness.
+4. **Review** — dispatch a fresh subagent for spec-compliance + code-quality two-stage review per `superpowers:subagent-driven-development`. Critical findings block progress.
+5. **Open PR** — `gh pr create --base <base-of-this-PR> --head <branch>` with single-concern description that cites the plan doc.
+6. **Wait for CI** — poll until green. Auto-rebase on conflicts (max 2 attempts; halt on third).
+7. **Address review** — `superpowers:receiving-code-review` to walk reviewer comments. Critical findings produce a fix commit; non-critical are logged on the PR.
+8. **Merge when green and approved** — never bypass branch protection. If branch protection blocks, post a status comment and continue with the next independent PR.
+9. **Deploy receipt** — when the merged branch is on an auto-deploy target, run `deploy-receipt` to verify deployed SHA matches merge SHA + healthcheck 200 before reporting the PR as done.
+
+Logs every state transition to `release-train.log` in the repo root.
+
+## Stop conditions
+
+Halt and surface to the operator if any of these occur:
+
+- A `CRITICAL` reviewer finding cannot be auto-resolved.
+- Two consecutive auto-rebase attempts fail on the same PR.
+- A PR has been waiting on CI for more than 30 minutes.
+- A required check (branch protection, status check, required reviewer) blocks merge.
+- A deploy-receipt times out or returns non-200.
+- The plan's dependency graph becomes unsatisfiable (e.g. a dependency PR was closed unmerged).
+
+When halted, write a state file to `release-train.halt.md` describing exactly which PR halted, why, and what the operator needs to decide before resuming.
+
+## Resuming
+
+Re-invoke `/release-train` after the halt is resolved. The orchestrator reads `release-train.log` and `release-train.halt.md` to skip already-merged PRs and resume from the halt point.
+
+## Composition
+
+This command activates the unified `/superpowers` dispatcher and routes through:
+
+- `superpowers:writing-plans` (or its inline fallback) to validate the plan
+- `superpowers:using-git-worktrees` for isolation per PR
+- `superpowers:test-driven-development` for implementation
+- `superpowers:subagent-driven-development` for two-stage review
+- `superpowers:finishing-a-development-branch` for merge decisions
+- `deploy-receipt` (CI-bundled) for production verification
+- `proceed-with-the-recommendation` orchestrator to walk the plan's PR list
+
+## Anti-patterns this command refuses
+
+- **Big-bang merge.** Will not merge a PR that touches more than 15 non-generated files.
+- **Bypass.** Will not use `--admin`, `--force`, or `--no-verify`.
+- **Speculative fix during CI wait.** Will not push speculative fixes during the first-time-contributor workflow-approval gate.
+- **Drive-by scope.** Will not add a fix outside the plan's scope; logs as deferred follow-up instead.
+
+## Example
+
+```
+/release-train docs/plans/2026-05-07-unified-five-plugin-dispatcher.md
+```
+
+Reads the plan, opens worktrees in dependency order, ships each PR through the full discipline, halts only at policy gates.

package/commands/seven-laws.md

@@ -0,0 +1,16 @@
+---
+name: seven-laws
+description: "Brand-aligned alias for /continuous-improvement. Reflect on the current session, analyze observations for patterns, and show instinct status under the 7 Laws of AI Agent Discipline."
+---
+
+# /seven-laws
+
+Brand-aligned alias for [`/continuous-improvement`](continuous-improvement.md). Both commands run the exact same three-step workflow under the 7 Laws of AI Agent Discipline:
+
+1. **Reflect** (Law 5) — generate a reflection block for this session.
+2. **Analyze** (Law 7) — process pending observations into instincts.
+3. **Status** — show all instincts for the project + global with confidence and current level.
+
+Run the workflow defined in [`continuous-improvement.md`](continuous-improvement.md). Subcommands `weekly` and `always-on` work identically.
+
+`/continuous-improvement` remains supported indefinitely for backward compatibility. Prefer `/seven-laws` going forward — it matches the brand and the SKILL.md spec.