continuous-improvement 3.1.0 → 3.8.0

package/skills/README.md

@@ -0,0 +1,79 @@
+# Source Skills
+
+This directory holds the **source-of-truth** for the companion skills bundled with the `continuous-improvement` plugin.
+
+> Edit files **here**. The plugin bundle at `plugins/continuous-improvement/skills/<name>/SKILL.md` is **regenerated** every time you run `npm run build` (see [`bin/generate-plugin-manifests.mjs`](../bin/generate-plugin-manifests.mjs)). Edits made directly inside `plugins/continuous-improvement/skills/` will be overwritten.
+
+## Featured companion — installed by default with the plugin
+
+`proceed-with-the-recommendation` is the **recommended pairing** for the 7 Laws. It is the execution arm that turns "do all of it" into a disciplined, verified, one-concern-at-a-time walk through the agent's recommendation list. If you only adopt one companion alongside the core skill, adopt this one.
+
+| Skill | What it does | Source |
+|-------|--------------|--------|
+| **`proceed-with-the-recommendation`** ⭐ | Walks any agent's recommendation list top-to-bottom under the 7 Laws — routes each item to the right specialist (`superpowers:*`, `ralph`, `workspace-surface-audit`, `simplify`, `security-review`, `schedule`, `loop`), falls back to inline behavior when a specialist isn't installed, verifies per item, halts on `needs-approval` | @naimkatiman |
+
+## Tier 1 — recommended pairing for **beginner** mode
+
+These add concrete enforcement to the 7 Laws. Tier-1 skills are the always-on minimum for any user running `npx continuous-improvement install` (default beginner mode).
+
+| Skill | What it does | Pairs with which Law |
+|-------|--------------|----------------------|
+| `para-memory-files` | File-based persistent memory using PARA (Projects/Areas/Resources/Archives) for cross-session context | Law 5 (Reflect), Law 7 (Learn) |
+| `verification-loop` | Six-phase verification (build, types, lint, tests, security, diff) with a structured PASS/FAIL report | Law 4 (Verify Before Reporting) |
+| `gateguard` | PreToolUse fact-forcing gate that blocks Edit/Write/destructive Bash until concrete investigation is presented | Law 1 (Research) |
+| `tdd-workflow` | RED→GREEN→REFACTOR enforcement, 80%+ coverage gate across unit/integration/E2E | Law 3 (One Thing), Law 4 (Verify) |
+
+## Tier 2 — additional skills for **expert** mode
+
+Tier-2 skills layer on top of tier-1 for users running `npx continuous-improvement install --mode expert`. They cover autonomous-mode safety, response-depth control, and context-window discipline that matter once an agent runs longer or more aggressively.
+
+| Skill | What it does | When it pays off |
+|-------|--------------|------------------|
+| `safety-guard` | Three-mode runtime guard (careful/freeze/guard) that blocks destructive commands and locks edits to a directory | Autonomous loops, prod systems, `--dangerously-skip-permissions` sessions |
+| `token-budget-advisor` | Heuristic input/output token estimator that offers 25%/50%/75%/100% depth choices before answering | Long sessions where response size matters |
+| `strategic-compact` | PreToolUse hook that suggests `/compact` at logical phase boundaries (research→plan, plan→implement, debug→next) instead of arbitrary auto-compaction | Multi-phase tasks that approach context limits |
+| `wild-risa-balance` | Decision-framing lens that pairs WILD (Wild/Imaginative/Limitless/Disruptive) generation with RISA (Realistic/Important/Specific/Agreeable) execution, used to split recommendation lists into bold pilots above a safe baseline | Multi-item recommendation blocks where bold options keep losing to safe ones in a flat list |
+
+The `/learn-eval` slash command also ships as part of the expert install: extract a session pattern, run a checklist quality gate, and decide global-vs-project save location before writing any skill file.
+
+## Other always-bundled companion skills
+
+These ship in the same plugin bundle regardless of mode and are available the moment you install the `continuous-improvement` plugin from the marketplace.
+
+| Skill | What it does | Source |
+|-------|--------------|--------|
+| `ralph` | Autonomous loop that executes a PRD story-by-story with quality checks between iterations | [snarktank/ralph](https://github.com/snarktank/ralph) |
+| `superpowers` | **Law activator.** Routes tasks to the correct Law-aligned specialist (brainstorming → Law 2, writing-plans → Law 2, TDD → Law 3+4, verification-before-completion → Law 4, etc.) so the right discipline fires automatically. Not a peer skill — a dispatcher for the others. | [obra/superpowers](https://github.com/obra/superpowers) |
+| `workspace-surface-audit` | Audits the active repo, MCP servers, plugins, and env, then recommends high-value skills/workflows | continuous-improvement |
+
+## How they get to your machine
+
+Two paths, you pick:
+
+**Path A — Install the plugin (recommended).** Bundled with the core skill, no per-skill copying. All companions land in one shot:
+
+```bash
+/plugin marketplace add naimkatiman/continuous-improvement
+/plugin install continuous-improvement@continuous-improvement
+```
+
+(The `-dev` suffix is reserved for the in-repo development marketplace at `plugins/continuous-improvement/.claude-plugin/marketplace.json` — only used when iterating on the bundle locally.)
+
+**Path B — Drop a single skill in by hand.** Useful if you want only one companion without the rest of the plugin:
+
+```bash
+SKILL=proceed-with-the-recommendation
+mkdir -p ~/.claude/skills/$SKILL
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/$SKILL.md \
+  -o ~/.claude/skills/$SKILL/SKILL.md
+```
+
+Or paste the file's contents directly into your agent's system prompt.
+
+## Pressure-test logs
+
+Adversarial pressure-test logs for skills in this directory live under [`docs/testing/`](../docs/testing/). They are not skills — they are baseline guarantees future edits must preserve.
+
+## Relationship to the core skill
+
+The core [`SKILL.md`](../SKILL.md) at the repo root defines the **7 Laws of discipline**. The skills in this directory are independent execution tools that build on those laws. They do not depend on `SKILL.md` and `SKILL.md` does not depend on them — but `proceed-with-the-recommendation` was written specifically to operationalize the 7 Laws end-to-end, which is why it's the featured pairing.

package/skills/deploy-receipt.md

@@ -0,0 +1,131 @@
+---
+name: deploy-receipt
+tier: "1"
+description: Enforces Law 4 (Verify Before Reporting) of the 7 Laws of AI Agent Discipline at the deploy seam. A merge into a branch that auto-deploys is not "done" until the deploy provider reports the merged commit SHA running and a healthcheck endpoint returns 200. Companion to the vendored `finishing-a-development-branch` skill — does not replace it, runs after it for projects on Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, or any other auto-deploy target.
+origin: https://github.com/naimkatiman/continuous-improvement
+---
+
+# Deploy Receipt — Closing the Merge-to-Production Gap
+
+## Why This Skill Exists
+
+Multiple sessions in the operator's recent telemetry ended in a "partially achieved" state with the same shape: PR merged green, branch deleted, agent reports done — and then hours later the operator discovers the deploy provider never picked up the commit, was building from a stale lockfile, or silently rolled back. The merge happened. The deploy did not.
+
+`finishing-a-development-branch` (vendored from Obra superpowers in `third-party/superpowers/`) ends at the merge. For repos that do not auto-deploy that is the correct boundary. For repos that DO auto-deploy from `main` (Railway, Cloudflare Workers, Vercel, Netlify, Fly.io, Cloud Run, App Runner, et al.) the merge is only the trigger — the work is not done until the deployed SHA matches the merged HEAD and the application answers a healthcheck.
+
+This skill defines the receipt that closes that gap, without modifying the vendored upstream file.
+
+## When to Activate
+
+Activate when ALL of the following are true:
+
+1. A merge into the deploy branch (typically `main` or `master`) has just landed
+2. The repo declares an auto-deploy target — detect via any of:
+   - `railway.toml`, `railway.json`, or `RAILWAY_*` env vars in `.env.example`
+   - `wrangler.toml` / `wrangler.jsonc` (Cloudflare Workers)
+   - `vercel.json` or `.vercel/` directory
+   - `netlify.toml`
+   - `fly.toml`
+   - `app.yaml` (App Engine), `apprunner.yaml` (App Runner)
+   - GitHub Actions workflow with `deploy:` job triggered on push to the deploy branch
+3. `finishing-a-development-branch` has reported "merged" — not "PR opened", not "review pending"
+
+Do NOT activate when:
+- Repo is library-only / package-published (npm, PyPI, crates.io) — those have a different verification surface
+- Deploy is manual (operator runs `wrangler deploy` themselves) — the merge is genuinely the boundary
+- Merge target is a non-deploy branch (`develop`, `staging-only`, `experimental`)
+
+## What a Receipt Is
+
+A deploy receipt has three components, all required:
+
+1. **SHA match.** The deploy provider's currently-running revision SHA equals the merge commit SHA on the deploy branch. Not "the latest deploy started after the merge" — the SHA itself.
+2. **Health response.** A documented healthcheck endpoint (project-specific; common shapes: `GET /health`, `GET /api/health`, `GET /version`) returns HTTP 200 within a reasonable timeout (default 5 minutes from merge).
+3. **Build artifact integrity** (when verifiable). If the deploy emits a build hash, log digest, or version string, it matches what was built on the merge commit. If it does not emit one, this component is recorded as `not verifiable for this provider` — it does not block the receipt, but the gap is logged.
+
+A receipt missing any required component is NOT a receipt. The merge is reported as `merged but not deployed — operator action required` per the close-the-loop rule below.
+
+## How to Verify (per provider)
+
+The skill is provider-aware but never hardcodes a specific API key or token shape. Three verification routes, in priority order:
+
+### Route A — Provider CLI (preferred when authenticated)
+
+The CLI is the highest-fidelity source.
+
+| Provider | Command shape | Receipt extraction |
+|---|---|---|
+| Railway | `railway status --json` | `.deployments[0].meta.commitHash` |
+| Cloudflare Workers | `wrangler deployments list --json` | `[0].metadata.deployment_trigger.metadata.commit_hash` |
+| Vercel | `vercel inspect <url> --json` | `.gitSource.sha` |
+| Netlify | `netlify api listSiteDeploys --data='{"site_id":"<id>"}'` | `[0].commit_ref` |
+| Fly.io | `fly releases --json` | `[0].commit_sha` |
+
+If the CLI is not installed or not authenticated in this session, fall through to Route B. Do NOT prompt the operator to install the CLI mid-session — that is a drive-by.
+
+### Route B — GitHub Deployments API (works for any provider that posts back)
+
+```
+gh api repos/{owner}/{repo}/deployments --jq '.[0] | {sha, ref, environment}'
+gh api repos/{owner}/{repo}/deployments/{id}/statuses --jq '.[0] | {state, target_url}'
+```
+
+A `state: success` status whose parent deployment's `sha` matches the merge SHA is a valid receipt component (1).
+
+### Route C — Version endpoint curl (works for any HTTP service)
+
+The most provider-agnostic. Requires the application to expose a version endpoint that returns its build SHA.
+
+```
+curl -fsS https://<deployed-host>/version
+# Expect a JSON body or plain text containing the merge SHA, e.g. {"commit":"a477ec1"}
+# Or a Git-style SHA prefix that matches `git rev-parse --short HEAD`
+```
+
+If no version endpoint exists in the project, log this as a gap and recommend adding one as a deferred follow-up — do not fabricate a receipt from a 200 on `/` or `/health` alone, because both can succeed against the OLD deploy.
+
+## Output Shape (always emit this verbatim block)
+
+After running verification:
+
+```
+## Deploy Receipt — <project name>
+- Merge SHA:        <abbreviated sha>
+- Deployed SHA:     <abbreviated sha or "not retrieved (reason)">
+- SHA match:        yes | no | not verifiable
+- Health endpoint:  <url> → <status code> in <ms>ms
+- Build artifact:   <digest if available, else "not emitted by provider">
+- Receipt status:   COMPLETE | INCOMPLETE — <reason>
+- Verified via:     CLI | GitHub Deployments | version curl | combination
+```
+
+A `COMPLETE` receipt is the only state that lets the merge be reported as `done`. `INCOMPLETE` receipts surface a single named operator-action item (e.g. "Railway last deploy is older than the merge — re-trigger from dashboard or `railway up`").
+
+## Anti-Patterns
+
+- **"Eventually consistent" excuse.** Reporting done with `Deployed SHA: not retrieved` and a comment like "deploy will pick up shortly" is exactly the failure mode this skill prevents. There is no eventually — there is COMPLETE or INCOMPLETE.
+- **Health-only receipts.** A 200 on `/health` against a stale deploy is not a receipt. Without SHA match, the receipt is INCOMPLETE.
+- **Skipping for "small changes."** A docs-only commit still needs a receipt if the deploy branch auto-deploys — small changes have caused stale-build incidents on every provider in the table above.
+- **Recommending the CLI install mid-receipt.** If Route A is unavailable, fall through to B then C. Adding tooling is a separate decision the operator makes outside the receipt loop.
+- **Treating absence of evidence as evidence of success.** If none of the three routes produce a SHA, the receipt is `INCOMPLETE — no provider source available`, not `COMPLETE (assumed)`.
+
+## Pairs With
+
+- `finishing-a-development-branch` (vendored, third-party/superpowers/) — runs first; reports the merge. This skill runs after.
+- `verification-loop` — same Law 4 family; this skill is the deploy-seam specialization
+- `proceed-with-the-recommendation` — routing-table row for "Merge / close branch" should pair `finishing-a-development-branch` with this skill when the project is auto-deploy
+- `safety-guard` — orthogonal; safety-guard prevents destructive ops, this verifies post-deploy state
+
+## Close-the-Loop Rule
+
+If the receipt is INCOMPLETE, the merge is NOT reported as a closed item in the Phase 7 summary of `proceed-with-the-recommendation`. It moves to **What is next → Immediate operator action**, with the named action and the exact command or dashboard step. The operator's session record is what determines done — not the agent's optimism.
+
+## Installation
+
+```bash
+mkdir -p ~/.claude/skills/deploy-receipt
+curl -L https://raw.githubusercontent.com/naimkatiman/continuous-improvement/main/skills/deploy-receipt.md \
+  -o ~/.claude/skills/deploy-receipt/SKILL.md
+```
+
+Restart the Claude Code session so the registry picks it up.

package/skills/gateguard.md

@@ -0,0 +1,155 @@
+---
+name: gateguard
+tier: "1"
+description: Enforces Law 1 (Research Before Executing) of the 7 Laws of AI Agent Discipline. Fact-forcing gate that blocks Edit/Write/Bash (including MultiEdit) and demands concrete investigation (importers, data schemas, user instruction) before allowing the action. Measurably improves output quality by +2.25 points vs ungated agents.
+origin: community
+---
+
+# GateGuard — Fact-Forcing Pre-Action Gate
+
+A PreToolUse hook that forces the agent to investigate before editing. Instead of self-evaluation ("are you sure?"), it demands concrete facts. The act of investigation creates awareness that self-evaluation never did.
+
+## When to Activate
+
+- Working on any codebase where file edits affect multiple modules
+- Projects with data files that have specific schemas or date formats
+- Teams where AI-generated code must match existing patterns
+- Any workflow where the agent tends to guess instead of investigating
+
+## Core Concept
+
+LLM self-evaluation doesn't work. Ask "did you violate any policies?" and the answer is always "no." This is verified experimentally.
+
+But asking "list every file that imports this module" forces the LLM to run Grep and Read. The investigation itself creates context that changes the output.
+
+**Three-stage gate:**
+
+```
+1. DENY  — block the first Edit/Write/Bash attempt
+2. FORCE — tell the model exactly which facts to gather
+3. ALLOW — permit retry after facts are presented
+```
+
+No competitor does all three. Most stop at deny.
+
+## Evidence
+
+Two independent A/B tests, identical agents, same task:
+
+| Task | Gated | Ungated | Gap |
+| --- | --- | --- | --- |
+| Analytics module | 8.0/10 | 6.5/10 | +1.5 |
+| Webhook validator | 10.0/10 | 7.0/10 | +3.0 |
+| **Average** | **9.0** | **6.75** | **+2.25** |
+
+Both agents produce code that runs and passes tests. The difference is design depth.
+
+## Gate Types
+
+### Edit / MultiEdit Gate (first edit per file)
+
+MultiEdit is handled identically — each file in the batch is gated individually.
+
+```
+Before editing {file_path}, present these facts:
+
+1. List ALL files that import/require this file (use Grep)
+2. List the public functions/classes affected by this change
+3. If this file reads/writes data files, show field names, structure,
+   and date format (use redacted or synthetic values, not raw production data)
+4. Quote the user's current instruction verbatim
+```
+
+### Write Gate (first new file creation)
+
+```
+Before creating {file_path}, present these facts:
+
+1. Name the file(s) and line(s) that will call this new file
+2. Confirm no existing file serves the same purpose (use Glob)
+3. If this file reads/writes data files, show field names, structure,
+   and date format (use redacted or synthetic values, not raw production data)
+4. Quote the user's current instruction verbatim
+```
+
+### Destructive Bash Gate (every destructive command)
+
+Triggers on: `rm -rf`, `git reset --hard`, `git push --force`, `drop table`, etc.
+
+```
+1. List all files/data this command will modify or delete
+2. Write a one-line rollback procedure
+3. Quote the user's current instruction verbatim
+```
+
+### Routine Bash Gate (once per session)
+
+```
+Quote the user's current instruction verbatim.
+```
+
+### Parallel-Actor Gate (first mutation per session, then divergence-checked)
+
+A second Claude/Codex/Maulana session can be running on the same host and the same working tree. On this operator's setup that is the common case, not the edge case (multi-clauding observed at 67% of recent messages). A mutation that looks safe in isolation can land on top of an upstream commit, an unstaged change, or a branch advance that this session never saw.
+
+**On the first Edit / Write / mutating Bash of a session:**
+
+```
+Baseline these three values and quote them in your response:
+
+1. `git rev-parse HEAD` — record the commit you started on
+2. `git rev-parse @{u}` (if branch tracks an upstream) — record where origin was
+3. `git status --porcelain` — record the working tree state
+
+If any value is "unknown" (detached HEAD, no upstream, untracked-only tree),
+say so explicitly. Do not proceed past the baseline silently.
+```
+
+**On every subsequent Edit / Write / mutating Bash, before allowing the action:**
+
+```
+Re-check the three baselines against current state:
+
+1. `git rev-parse HEAD` — has it advanced past your baseline without your commits?
+2. `git rev-parse @{u}` — did upstream move while you worked?
+3. `git status --porcelain` — are there modifications you did not introduce?
+
+If ANY of those drifted from baseline, HALT. Emit:
+"Parallel-actor divergence: <field> moved from <baseline> to <current>.
+Working tree may belong to another session. Stop, surface to operator,
+get clearance before next mutation."
+```
+
+This gate is what catches the squash-merge / ahead-of-origin trap recorded in the operator's memory (`feedback_pre_branch_check.md`, `feedback_parallel_actor.md`) — both classes of failure occurred because a baseline was never captured at session start.
+
+## Quick Start
+
+### Option A: Use the continuous-improvement hook (zero install)
+
+The hook at `scripts/hooks/gateguard-fact-force.js` is included in this plugin. Enable it via hooks.json.
+
+### Option B: Full package with config
+
+```bash
+pip install gateguard-ai
+gateguard init
+```
+
+This adds `.gateguard.yml` for per-project configuration (custom messages, ignore paths, gate toggles).
+
+## Anti-Patterns
+
+- **Don't use self-evaluation instead.** "Are you sure?" always gets "yes." This is experimentally verified.
+- **Don't skip the data schema check.** Both A/B test agents assumed ISO-8601 dates when real data used `%Y/%m/%d %H:%M`. Checking data structure (with redacted values) prevents this entire class of bugs.
+- **Don't gate every single Bash command.** Routine bash gates once per session. Destructive bash gates every time. This balance avoids slowdown while catching real risks.
+
+## Best Practices
+
+- Let the gate fire naturally. Don't try to pre-answer the gate questions — the investigation itself is what improves quality.
+- Customize gate messages for your domain. If your project has specific conventions, add them to the gate prompts.
+- Use `.gateguard.yml` to ignore paths like `.venv/`, `node_modules/`, `.git/`.
+
+## Related Skills
+
+- `safety-guard` — Runtime safety checks (complementary, not overlapping)
+- `code-reviewer` — Post-edit review (GateGuard is pre-edit investigation)

package/skills/para-memory-files.md

@@ -0,0 +1,108 @@
+---
+name: para-memory-files
+tier: "1"
+description: >
+  Enforces Law 5 (Reflect After Every Session) and Law 7 (Learn From Every Session)
+  of the 7 Laws of AI Agent Discipline by giving the agent a durable file-based
+  memory it can read on resume and write at session end.
+  File-based memory system using Tiago Forte's PARA method. Use this skill whenever
+  you need to store, retrieve, update, or organize knowledge across sessions. Covers
+  three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
+  (2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
+  handles planning files, memory decay, weekly synthesis, and recall via qmd.
+  Trigger on any memory operation: saving facts, writing daily notes, creating
+  entities, running weekly synthesis, recalling past context, or managing plans.
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use qmd
+
+Use `qmd` rather than grepping files:
+
+```bash
+qmd query "what happened at Christmas"   # Semantic search with reranking
+qmd search "specific phrase"              # BM25 keyword search
+qmd vsearch "conceptual question"         # Pure vector similarity
+```
+
+Index your personal folder: `qmd index $AGENT_HOME`
+
+Vectors + BM25 + reranking finds things even when the wording differs.
+
+## Planning
+
+Keep plans in timestamped files in `plans/` at the project root (outside personal memory so other agents can access them). Use `qmd` to search plans. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.