continuous-improvement 3.1.0 → 3.9.1

package/plugins/continuous-improvement/skills/ralph/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: ralph
+tier: companion
+description: "Enforces Law 6 (Iterate Means One Thing) of the 7 Laws of AI Agent Discipline at PRD scale. Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete. Converts PRDs to executable JSON, implements stories iteratively with quality checks, and tracks progress."
+origin: https://github.com/snarktank/ralph
+---
+
+# Ralph — Autonomous Agent Loop
+
+Ralph runs iteratively until all PRD stories are complete. Each iteration: picks highest priority story, implements, runs quality checks, commits if passing, updates progress, repeats.
+
+## When to Use
+
+- Large features that exceed a single context window
+- Multi-story PRDs that need consistent implementation
+- Tasks requiring repeated verification and commit cycles
+- Long-running development that benefits from persistence across interruptions
+
+## Do NOT Use When
+
+- Task is a one-shot fix completable in a single edit — just edit the file
+- You haven't written a PRD yet — write the PRD first, then run Ralph against it
+- The work spans fewer than 3 stories — single-iteration verification is enough
+- You need to explore or plan before committing to scope — use a planning skill first; Ralph is for execution, not discovery
+- You want manual control over each iteration — run quality checks yourself, no need for Ralph's loop
+
+## Prerequisites
+
+- Git repository
+- PRD document (markdown format)
+- `jq` installed (`brew install jq` on macOS)
+
+## Workflow
+
+### 1. Create a PRD
+
+Generate a detailed requirements document using the PRD skill:
+
+```
+Load the prd skill and create a PRD for [your feature description]
+```
+
+Output saved to `tasks/prd-[feature-name].md`
+
+**CRITICAL — refine generic criteria before iteration begins.** Auto-generated PRD scaffolds often produce generic acceptance criteria like `["Implementation is complete", "Code compiles without errors"]`. These are theater — Ralph cannot prove a story passes against criteria that don't actually constrain it. Replace every generic criterion with a concrete, testable statement before moving to step 2.
+
+- Bad: `"Function is implemented correctly"`
+- Good: `"Function parseUserInput(s) returns {ok: true, value} for valid s and {ok: false, error} for invalid s, asserted by tests/parse-user-input.test.ts"`
+- Bad: `"Code compiles"`
+- Good: `"TypeScript compiles with no errors (npm run build) AND lsp diagnostics show 0 errors on src/parse-user-input.ts"`
+
+If you cannot write a testable criterion, the story is too big. Break it down before continuing.
+
+**Example — refining a scaffold criterion**
+
+Auto-generated:
+
+```json
+"acceptanceCriteria": [
+  "Implementation is complete",
+  "Code compiles without errors"
+]
+```
+
+After refinement:
+
+```json
+"acceptanceCriteria": [
+  "POST /api/users returns 201 with {id, email} for valid input, asserted by tests/api-users.test.ts",
+  "POST /api/users returns 400 with {error} for missing email, asserted by tests/api-users.test.ts",
+  "TypeScript compiles with 0 errors (npm run build)",
+  "lsp diagnostics show 0 errors on src/api/users.ts"
+]
+```
+
+### 2. Convert PRD to Ralph Format
+
+Convert the markdown PRD to executable JSON:
+
+```
+Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json
+```
+
+This creates `prd.json` with user stories structured for autonomous execution.
+
+### 3. Run Ralph
+
+Execute the autonomous loop:
+
+```bash
+# Using Amp (default)
+./scripts/ralph/ralph.sh [max_iterations]
+
+# Using Claude Code
+./scripts/ralph/ralph.sh --tool claude [max_iterations]
+```
+
+Default: 10 iterations. Use `--tool amp` or `--tool claude` to select your AI tool.
+
+## Ralph Loop Steps
+
+1. **Create feature branch** — from PRD `branchName`
+2. **Pick highest priority story** — where `passes: false`
+3. **Implement that single story** — fresh context per iteration
+4. **Run quality checks** — verify the current story's specific acceptance criteria with fresh evidence:
+   - For EACH acceptance criterion, run the test/build/lint that proves it
+   - Read the output, do not assume
+   - If ANY criterion is not met, continue working — do NOT mark the story as `passes: true`
+   - **Suite-level "all tests pass" is NOT a substitute for criterion-level proof.**
+
+   **Example — story-by-story verification**
+
+   Bad:
+
+   ```
+   Story US-002: "Add /api/users endpoint"
+   - Ran npm test → all green → marked passes: true
+   ```
+
+   Why bad: suite-level pass doesn't prove THIS story's criteria. Other tests could be passing while the new endpoint is broken.
+
+   Good:
+
+   ```
+   Story US-002: "Add /api/users endpoint"
+   - Criterion 1: POST /api/users → 201 → ran `npx vitest tests/api-users.test.ts -t "valid input"` → PASS
+   - Criterion 2: POST /api/users → 400 → ran `npx vitest tests/api-users.test.ts -t "missing email"` → PASS
+   - Criterion 3: typecheck → ran `npm run build` → 0 errors
+   - All criteria met with fresh evidence → marked passes: true
+   ```
+
+   Why good: each criterion proven with a targeted run; the output was read before the mark.
+
+5. **Commit if checks pass** — atomic commits per story
+6. **Update prd.json** — mark story as `passes: true`
+7. **Append learnings** — to `progress.txt`
+8. **Repeat** — until all stories pass or max iterations reached
+
+## Key Concepts
+
+### Each Iteration = Fresh Context
+
+Every story gets a clean slate. Previous work is visible only via git history and `prd.json`, preventing context pollution.
+
+### Small Tasks
+
+Stories should be completable in 10-30 minutes. If a story stalls, break it down.
+
+### AGENTS.md Updates Are Critical
+
+Ralph updates `AGENTS.md` after each story so subsequent iterations know what's already done.
+
+### Feedback Loops
+
+- Build/test failures: immediate fix or rollback
+- Test failures: investigate before declaring pass
+- Confusion: log to `progress.txt` for human review
+
+### Browser Verification for UI Stories
+
+Ralph starts a dev server and uses Playwright to verify UI stories actually render.
+
+### Stop Condition
+
+Ralph stops when:
+- All stories have `passes: true`
+- Max iterations reached
+- Critical failure encountered (user intervention required)
+
+## Anti-patterns
+
+These thoughts mean STOP — Ralph is about to slip:
+
+| Thought | Why it's wrong |
+|---|---|
+| "All stories pass, time to summarise and wait for the user" mid-loop | Polite-stop. Ralph continues through commit + progress update + next pick in the same turn. |
+| "Tests pass at the suite level, the story must be done" | Suite-level pass is not criterion-level proof. Verify each criterion with fresh evidence. |
+| "Story is bigger than expected, I'll mark it passes: true and add a TODO" | Scope reduction. Either complete the story or break it down — never declare partial completion. |
+| "The criterion is generic but obviously the test covers it" | PRD theater. Refine the criterion to something specific before proceeding. |
+| "I'll skip the failing test by deleting/skipping it" | Tests are evidence. Fix the implementation, not the test. |
+| "Reviewer said it looks good" — without running fresh checks | "Looks good" is not verification. Run the build, run the tests, read the output. |
+
+## Final Checklist (Hard Gate)
+
+Ralph cannot exit cleanly until ALL of these are true:
+
+- [ ] Every story in `prd.json` has `passes: true` (no incomplete stories)
+- [ ] Acceptance criteria are task-specific (no `"Implementation is complete"` generics)
+- [ ] All requirements from the original task are met (no scope reduction)
+- [ ] Fresh test run output shows all tests pass (read it, don't assume)
+- [ ] Fresh build output shows success (read it, don't assume)
+- [ ] No tests were deleted, skipped, or weakened to make checks green
+- [ ] `progress.txt` records implementation details and learnings per iteration
+- [ ] Working tree is clean (every story committed atomically)
+
+A failing checkbox is a hard halt — do not declare done.
+
+## Files
+
+- `prd.json` — executable PRD with user stories
+- `progress.txt` — accumulated learnings and status
+- `ralph.sh` — the loop script
+- `AGENTS.md` — iteration memory
+
+## Debugging
+
+If Ralph gets stuck:
+
+1. Check `prd.json` for malformed stories
+2. Review `progress.txt` for accumulated errors
+3. Verify tests pass independently: `npm test` or equivalent
+4. Check git status for uncommitted changes
+5. Run single iteration manually to isolate issues
+
+## Customizing the Prompt
+
+Edit the prompt template in `scripts/ralph/prompt.md` (Amp) or `scripts/ralph/CLAUDE.md` (Claude Code) to adjust behavior.
+
+## Archiving
+
+After completion, archive `prd.json` and `progress.txt` to `tasks/archive/[date]/` for future reference.

package/plugins/continuous-improvement/skills/recovery-classification/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: recovery-classification
+tier: "2"
+description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. After any failure in the verification ladder or auto-loop, classify the failure class before retrying — provider, tool-schema, deterministic-policy, git, worktree, runtime — so retry-vs-pause-vs-self-heal-vs-stop is an intentional decision, not a generic 'try again'."
+origin: continuous-improvement
+---
+
+# Recovery Classification Skill
+
+When a phase or unit fails, name the failure class first. Generic "retry on failure" hides repeatable failure modes and turns them into flaky tests.
+
+## When to Use
+
+- After any Phase 1–6 failure in `verification-loop`.
+- After any auto-loop unit that exits non-zero.
+- After any tool call the harness rejects (schema validation, policy gate, deterministic block).
+- Before re-running anything that just failed — classification fires once, before the first retry.
+
+## Why This Skill Exists
+
+GSD-2's [CONTEXT.md](https://github.com/gsd-build/gsd-2/blob/main/CONTEXT.md) names "Recovery Classification" as one of four runtime invariant modules. Common failure modes it catches:
+
+- **Deterministic-policy blocks misclassified as generic provider failures** — gateguard denials retried in a loop until budget is exhausted.
+- **Schema-validation failures retried verbatim** — wasting tokens on a call the validator will keep rejecting.
+- **Stale-worker / stale-lock states** — no retry can resolve a worker that died holding a lock; the loop just spins.
+- **Worktree-invalidity errors** — recovery can't fix without operator intervention; retrying writes to a broken root.
+
+A retry without a class is a guess; a guess at scale is a budget leak.
+
+## The Classification Taxonomy
+
+Six classes. Each maps to one intentional action:
+
+| Class | Signal | Action |
+|---|---|---|
+| **provider** | API timeout, 5xx, rate limit, network, transient cloud error | retry with exponential backoff |
+| **tool-schema** | tool input rejected by validator, missing required field, type mismatch | repair input, do **not** retry verbatim |
+| **deterministic-policy** | gateguard / write-gate / permission denied / explicit policy block | pause, ask operator (do **not** retry) |
+| **git** | merge conflict, detached HEAD, unmerged paths, lockfile, pre-commit hook | self-heal if known recipe, else pause |
+| **worktree** | missing `.git`, invalid root, lease lost, prunable worktree, foreign session | stop — never spawn workers into unresolved paths |
+| **runtime** | OOM, segfault, host kill, parent process gone, context exhaustion | stop, surface to operator |
+
+A failure that fits no class is `unclassified` — that itself is a signal: the taxonomy is incomplete and needs a new entry, not a retry.
+
+## The Output Contract
+
+Before any retry, emit one fenced block:
+
+```
+recovery-classification:
+  failure:        <one-line summary>
+  class:          tool-schema
+  evidence:       stderr line 14: "missing required field: workspace_id"
+  action:         repair input (add workspace_id from session context), do NOT retry verbatim
+  retry budget:   2/3 remaining (this class)
+```
+
+Retry budgets are **per-class**, not global. A failed class that resolves on retry resets its budget; a class that exhausts its budget escalates to `pause` regardless of remaining global retries. This keeps a flaky network from masking a persistent schema bug.
+
+## Anti-Patterns
+
+- **One retry budget for all classes.** A network blip and a schema mismatch consume the same counter, so persistent schema bugs masquerade as "flaky network."
+- **Auto-retry on `deterministic-policy`.** The gate exists exactly because retry is wrong. Pause instead and surface the policy that fired.
+- **Classifying after retry.** The class informs the action; classifying afterward turns it into a post-mortem label and the loop has already misspent its budget.
+- **Coalescing `worktree` into `git`.** Worktree errors are stop-class; git errors are usually self-heal-class. Conflating them lets workers spawn into broken roots.
+- **Treating `unclassified` as `provider`.** Unknown is not transient. Force a taxonomy update; do not paper over the gap with a backoff.
+
+## Pairs With
+
+- [verification-loop](verification-loop.md) — every Phase 1–6 failure routes through here before any retry.
+- [state-reconciliation](state-reconciliation.md) — runs before the next loop iteration when class is `git` or `runtime`, since those classes often leave drift behind.
+- [worktree-safety](worktree-safety.md) — class `worktree` is exactly worktree-safety's failure surface; the two are co-defined.
+- [gateguard](gateguard.md) — class `deterministic-policy` is gateguard's surface; recovery-classification names what gateguard already blocked.

package/plugins/continuous-improvement/skills/safety-guard/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: safety-guard
+tier: "2"
+description: Enforces Law 3 (One Thing at a Time) of the 7 Laws of AI Agent Discipline by scoping edits to a directory and blocking destructive shell commands. Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
+origin: continuous-improvement
+---
+
+# Safety Guard — Prevent Destructive Operations
+
+## When to Use
+
+- When working on production systems
+- When agents are running autonomously (full-auto mode)
+- When you want to restrict edits to a specific directory
+- During sensitive operations (migrations, deploys, data changes)
+
+## How It Works
+
+Three modes of protection:
+
+### Mode 1: Careful Mode
+
+Intercepts destructive commands before execution and warns:
+
+```
+Watched patterns:
+- rm -rf (especially /, ~, or project root)
+- git push --force
+- git reset --hard
+- git checkout . (discard all changes)
+- DROP TABLE / DROP DATABASE
+- docker system prune
+- kubectl delete
+- chmod 777
+- sudo rm
+- npm publish (accidental publishes)
+- Any command with --no-verify
+```
+
+When detected: shows what the command does, asks for confirmation, suggests safer alternative.
+
+### Mode 2: Freeze Mode
+
+Locks file edits to a specific directory tree:
+
+```
+/safety-guard freeze src/components/
+```
+
+Any Write/Edit outside `src/components/` is blocked with an explanation. Useful when you want an agent to focus on one area without touching unrelated code.
+
+### Mode 3: Guard Mode (Careful + Freeze combined)
+
+Both protections active. Maximum safety for autonomous agents.
+
+```
+/safety-guard guard --dir src/api/ --allow-read-all
+```
+
+Agents can read anything but only write to `src/api/`. Destructive commands are blocked everywhere.
+
+### Unlock
+
+```
+/safety-guard off
+```
+
+## Implementation
+
+Currently implemented as skill-side discipline: when restricted-mode is active, the agent reads this skill and refuses Bash, Write, Edit, and MultiEdit calls that violate the rules before invoking the tool. There is no bundled tool-call gate today — the same enforcement gap that existed for `gateguard` before issue #106 / PR #108. A future runtime version would track via a follow-up issue.
+
+## Integration
+
+- Enable by default for `codex -a never` sessions
+- Pair with observability risk scoring in continuous-improvement v2
+- Logs all blocked actions to `~/.claude/safety-guard.log`

package/plugins/continuous-improvement/skills/state-reconciliation/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: state-reconciliation
+tier: "2"
+description: "Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline. Pre-dispatch invariant: reconcile DB-vs-disk-vs-memory state before any unit runs, so a stale flag, missing artifact, or out-of-sync row never re-dispatches a unit that already completed or never started."
+origin: continuous-improvement
+---
+
+# State Reconciliation Skill
+
+A pre-dispatch invariant. Before the verification ladder runs (or any auto-loop unit dispatches), reconcile the three state sources — DB / disk / in-memory — and surface any divergence as a blocker, not a silent re-dispatch.
+
+## When to Use
+
+- Before Phase 1 of `verification-loop` if the project tracks runtime state outside source control (sqlite, KV, redis, `completed-units.json`, milestone JSON, lockfiles).
+- Before any auto-loop iteration in long-running sessions.
+- After a crash, pause/resume, or context compaction — the in-memory loop state is gone but DB and disk persist.
+- When a flag like `is_sketch`, `in_progress`, or a stale lock keeps re-firing the same unit.
+
+## Why This Skill Exists
+
+GSD-2's [CONTEXT.md](https://github.com/gsd-build/gsd-2/blob/main/CONTEXT.md) names "State Reconciliation" as one of four runtime invariant modules. Common failure modes it catches:
+
+- **Stale flags re-dispatch completed units** — `is_sketch`, stale worker rows, stale sequence/dependency rows that no one cleared.
+- **Disk artifacts present, DB status lags** — `PROJECT.md` milestone registration, completion timestamps, roadmap divergence.
+- **Recovery helpers exist but aren't wired into dispatch** — divergence accrues silently between iterations.
+
+A verification ladder that runs against unreconciled state reports green on the wrong inputs.
+
+## The Reconciliation Contract
+
+For every state class the project tracks, define and run before dispatch:
+
+1. **Authority** — which surface is the source of truth (DB, disk artifact, in-memory loop state).
+2. **Projection** — direction of state flow (DB → disk, disk → DB, or both with a named winner).
+3. **Reconciliation** — the deterministic check that proves authority and projection match.
+4. **Failure mode** — what happens on divergence (block dispatch, repair, ask operator).
+
+Output a single fenced block before any dispatch, so the operator sees the resolved state before it costs a misread:
+
+```
+state-reconciliation (resolved):
+  participants table:        DB authoritative; disk projection at data/participants.json — match (1247 rows)
+  completed_units.json:      project root authoritative after crash; worktree projection — match
+  is_sketch flag:            DB authoritative — clear (no re-dispatch risk)
+  open lock at /tmp/foo.lck: stale (PID 1234 not running) — STALE, blocks dispatch
+  milestone registration:    PROJECT.md authoritative; DB row — DIVERGED (DB shows in_progress, disk shows complete)
+```
+
+Each row shows class + authority + reconciliation result. `STALE`, `DIVERGED`, `MISSING` surface as blockers; only every-row-`match` unblocks dispatch.
+
+## Anti-Patterns
+
+- **Reconciling at unit boundary, not lifecycle boundary.** Checking only when a unit is about to run lets earlier units write to invalid state. Reconcile once at lifecycle start and on every resume.
+- **One-way trust.** Assuming DB is always right (or disk always right) without naming authority per state class. Authority is a per-class decision; codify it.
+- **Silent repair.** Auto-fixing divergence without surfacing it. If reconciliation fixes 12 rows, the operator must see the count and the classes.
+- **Reconciling the wrong direction.** Projecting disk → DB when DB was the authority overwrites correct state with stale data. The direction is part of the contract, not a default.
+- **Treating "missing" as "match".** An absent state class is not the same as a reconciled one. Missing means the projection never ran; surface it explicitly.
+
+## Pairs With
+
+- [verification-loop](verification-loop.md) — runs as a pre-Phase-0 invariant; the resolved-state block fires before the resolved-ladder block.
+- [worktree-safety](worktree-safety.md) — both fire before dispatch; safety runs first because reconciliation depends on a valid worktree root.
+- [recovery-classification](recovery-classification.md) — divergence found here routes through recovery-classification on the next loop iteration if the reconciler can't auto-repair.

package/plugins/continuous-improvement/skills/strategic-compact/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: strategic-compact
+tier: "2"
+description: Enforces Law 5 (Reflect After Every Session) of the 7 Laws of AI Agent Discipline at phase boundaries. Suggests manual context compaction at logical intervals to preserve context through task phases rather than arbitrary auto-compaction.
+origin: continuous-improvement
+---
+
+# Strategic Compact Skill
+
+Suggests manual `/compact` at strategic points in your workflow rather than relying on arbitrary auto-compaction.
+
+## When to Activate
+
+- Running long sessions that approach context limits (200K+ tokens)
+- Working on multi-phase tasks (research → plan → implement → test)
+- Switching between unrelated tasks within the same session
+- After completing a major milestone and starting new work
+- When responses slow down or become less coherent (context pressure)
+
+## Why Strategic Compaction?
+
+Auto-compaction triggers at arbitrary points:
+- Often mid-task, losing important context
+- No awareness of logical task boundaries
+- Can interrupt complex multi-step operations
+
+Strategic compaction at logical boundaries:
+- **After exploration, before execution** — Compact research context, keep implementation plan
+- **After completing a milestone** — Fresh start for next phase
+- **Before major context shifts** — Clear exploration context before different task
+
+## How It Works
+
+The `suggest-compact.js` script runs on PreToolUse (Edit/Write) and:
+
+1. **Tracks tool calls** — Counts tool invocations in session
+2. **Threshold detection** — Suggests at configurable threshold (default: 50 calls)
+3. **Periodic reminders** — Reminds every 25 calls after threshold
+
+## Hook Setup
+
+Add to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "node ~/.claude/skills/strategic-compact/suggest-compact.js" }]
+      }
+    ]
+  }
+}
+```
+
+## Configuration
+
+Environment variables:
+- `COMPACT_THRESHOLD` — Tool calls before first suggestion (default: 50)
+
+## Compaction Decision Guide
+
+Use this table to decide when to compact:
+
+| Phase Transition | Compact? | Why |
+|-----------------|----------|-----|
+| Research → Planning | Yes | Research context is bulky; plan is the distilled output |
+| Planning → Implementation | Yes | Plan is in TodoWrite or a file; free up context for code |
+| Implementation → Testing | Maybe | Keep if tests reference recent code; compact if switching focus |
+| Debugging → Next feature | Yes | Debug traces pollute context for unrelated work |
+| Mid-implementation | No | Losing variable names, file paths, and partial state is costly |
+| After a failed approach | Yes | Clear the dead-end reasoning before trying a new approach |
+
+## What Survives Compaction
+
+Understanding what persists helps you compact with confidence:
+
+| Persists | Lost |
+|----------|------|
+| Agent instructions (from CLAUDE.md / AGENTS.md) | Intermediate reasoning and analysis |
+| TodoWrite task list | File contents you previously read |
+| Memory files (`~/.claude/memory/`) | Multi-step conversation context |
+| Git state (commits, branches) | Tool call history and counts |
+| Files on disk | Nuanced user preferences stated verbally |
+
+## Best Practices
+
+1. **Compact after planning** — Once plan is finalized in TodoWrite, compact to start fresh
+2. **Compact after debugging** — Clear error-resolution context before continuing
+3. **Don't compact mid-implementation** — Preserve context for related changes
+4. **Read the suggestion** — The hook tells you *when*, you decide *if*
+5. **Write before compacting** — Save important context to files or memory before compacting
+6. **Use `/compact` with a summary** — Add a custom message: `/compact Focus on implementing auth middleware next`
+
+## Related
+
+- [The Longform Guide](https://x.com/affaanmustafa/status/2014040193557471352) — Token optimization section
+- Memory persistence hooks — For state that survives compaction
+- `continuous-learning` skill — Extracts patterns before session ends