improvement-system

name

improvement-system

description

Install the Continuous Improvement system (backlog, weekly review, journal loop with hooks and skills) into a project. Use whenever the user asks to install, port, bootstrap, replicate, or hand over the improvement system, the CI loop, or the product improvement loop to a repo or another agent, and also when a user asks how a project should track ideas, run weekly reviews, keep a work journal, or make an agent log what it did and why.

Improvement System installer

Installs a self-sustaining product improvement loop into a project:

Signals ──────────────► Backlog ────────► Weekly review ───► Build ────► Track record
(analytics, feedback,   (BACKLOG.md =     (triage: move to   (daily      (journal entry:
 owner, sessions)        untriaged pile,   TRIAGED.md as      tasks)      what / why / how,
                         via `idea`)       kept / discarded)              via `worklog`)
      ▲                                                                        │
      └────────────────────────── feeds next week's signals ◄──────────────────┘

Three mechanisms make it self-sustaining. A SessionStart hook injects the system's state into every agent session. A Stop hook blocks session end once if project files were mutated but no journal entry was written. Skills encode the rituals so any session executes them identically.

Read references/rules.md BEFORE adapting anything. It states which "simplifications" were already tried and walked back. Do not install by copying files top to bottom. Read the invariants, run the interview, then install.

Invariants (never weaken these)

Everything marked ⚠️ in the assets is meant to be adapted per project. Nothing in this list is.

1. Capture and triage are separate acts. Anyone and anything appends one-line ideas. Only the owner moves items out of the backlog, at the weekly review or explicitly in chat. Both are valid triage.
2. BACKLOG.md holds only untriaged items. TRIAGED.md holds only decisions. New items never start in TRIAGED.md.
3. Every discard gets a written reason.
4. Every postponed item gets a reason and a revisit ISO week, and is resurfaced before new triage.
5. Priority (critical, medium, low) is assigned by the owner only. Medium-or-higher items that are not yet scheduled resurface at every weekly review.
6. The agent reports findings with facts (scope, duration, impact) and never assigns urgency labels like URGENT.
7. A number appears only with its source and date range. A blocked data source is recorded as a blocker, never replaced with an estimate.
8. Hooks fail open, and the Stop hook blocks at most once per stop.
9. Journal entries are append-only, one per material task, and unverified work states "Not verified".
10. The weekly review is interactive. Unattended runs may compile, pull signals, and run health checks, but never touch the backlog.
11. Ideas found mid-task are captured in one line, not designed. Return to the task.

Phase 0. Adaptation interview

Resolve these with the owner before creating any file. Record the answers, they drive every substitution.

1. Owner name (replaces {{OWNER}}) and project name (replaces {{PROJECT}}).
2. Vocabulary check. Confirm what the owner calls the untriaged pile and the decided list. Rename the files if their words differ (see rules.md rule 2).
3. Hook runtime. The Stop hook runs unchanged under bun or npx tsx. Pick the command that matches the project and put it in the settings snippet.
4. Stack mutation commands for the Stop hook. Keep git and file ops, swap the deploy, migration, package-manager, and formatter patterns in MUTATING_COMMAND_PATTERNS to match the stack.
5. Analytics sources, and whether credentials exist today. If not, that becomes a documented blocker in METRICS.md and a backlog item, never a reason to invent numbers.
6. Feedback channels (community, support, direct owner notes).
7. Kept categories for TRIAGED.md. Propose acquisition, activation, retention, revenue, plus product-specific, plus infra/tech-debt/ops. The owner adjusts.
8. Existing material to seed the backlog (notes, stale roadmaps, TODOs, agent memory).
9. Vision inputs. Schedule a short drafting pass with the owner (pillars, one north-star metric, an explicit "not doing" list). Never finalize VISION.md alone.
10. Where the agent's persistent memory lives, so standing rules can accumulate as the owner states them.

Phase 1. Data layer

mkdir -p docs/improvement/journal scripts/improvement .claude/skills/{worklog,idea,weekly-review}

Copy assets/docs/*.md into docs/improvement/, substitute {{OWNER}} and {{PROJECT}}, adapt every ⚠️ marker with the interview answers. VISION.md stays marked DRAFT until the owner has edited it.

Phase 2. Hooks

Copy assets/scripts/session-context.sh and assets/scripts/stop-worklog-check.ts into scripts/improvement/, chmod +x the shell script, and adapt the mutation patterns from interview answer 4. Merge assets/settings-hooks.json into the project's .claude/settings.json (merge, never clobber, create the file if absent), with the runtime command from answer 3.

Phase 3. Universal skills

Install the three skill templates, assets/skills/<name>.md becomes .claude/skills/<name>/SKILL.md (worklog, idea, weekly-review), substituting placeholders. Install them per project rather than globally, so each project's copy can accumulate its own Common-mistakes entries over time. Do NOT create project-specific signal skills yet, they are grown later (see growth section).

Phase 4. Anchor

Append assets/claude-md-section.md (placeholders substituted) to the project's CLAUDE.md or AGENTS.md. In persistent memory, record only that the system exists and where it lives. Standing rules are added later, when the owner actually states them.

Phase 5. Verify (all of these, in order)

1. bash scripts/improvement/session-context.sh prints one context line and exits 0. Test with and without the current week's journal file present, and from a directory with no docs/improvement (silent exit 0).
2. Copy assets/scripts/stop-worklog-check.test.ts next to the hook and run it (bun ...test.ts or npx tsx ...test.ts). All eight fixtures must pass.
3. echo '{}' | <runtime> scripts/improvement/stop-worklog-check.ts produces no output and exits 0 (fail-open).
4. Start a fresh agent session. The SessionStart line must appear in context.
5. In a live session, make a trivial file edit and try to end the session. The Stop hook must block once with the worklog instruction, accept an entry, then let the session stop.
6. Say "idea: test entry". A row must land in BACKLOG.md as I-001 (keep it or let the owner discard it with a reason, which doubles as the first triage).
7. Run a fresh subagent through the worklog skill cold, no context beyond the skill file. Patch any ambiguity it hits into the skill's Common mistakes.

Phase 6. Seed

Harvest the sources from interview answer 8 into BACKLOG.md, one line each with real I-### IDs. Open the current week's journal (docs/improvement/journal/$(date +%G-W%V).md) from the worklog template. Draft VISION.md with the owner from answer 9, or leave it explicitly marked as pending their pass.

Phase 7. Handover message to the owner

Tell the owner, in plain language, what runs automatically (the two hooks), which skills they can call and when, every blocker that waits on them (each with its backlog ID), and the single starting action, say "run the weekly review" for the first triage of the seeded items. Offer scheduling (calendar reminder or a scheduled agent that pre-compiles the week) but do not wire it until the ritual has proven itself once.

After install, how the system grows

• Add one signal-collector skill per source, only when the source is live. Contract for every collector: it writes one journal section, cites source and date range, reports blockers instead of estimating, and applies the privacy rule (themes and paraphrases in the journal, never verbatim user text).
• Add a weekly health-check step when a silent failure in a subsystem would quietly damage product quality (rules.md rule 13 has the criterion and the cautionary tale). Each step names its skill or query, thresholds, and where anomalies go.
• Verify any query, path, or credential name against live data once before baking it into a skill.
• Optionally add a read-only analyst agent for heavy digestion during reviews, once enough history exists to digest.
• Record the owner's standing rules to persistent memory as they are stated, and journal the moment.

Failure modes seen in the wild

• Installing files top to bottom without the interview, then "improving" an invariant away.
• Creating files before confirming the owner's vocabulary.
• Logging to the wrong ISO week (compute %G-W%V, mind BSD vs GNU date).
• Writing "Why: owner asked" instead of naming the actual driver.
• Letting one early journal edit cover later mutations. The final entry must follow the latest qualifying mutation.
• Treating the Stop hook as complete coverage. Investigations and decisions are logged manually.
• Triaging without an explicit owner call, self-assigning priorities, or using escalation labels.
• Paragraph-length captures, or skipping capture because an idea seems small.
• Inventing numbers, or silently skipping a blocked signal source.
• Templating the owner's vision instead of drafting it with them.
• Copying another project's signal skills instead of growing this project's own.
• Pre-populating memory with rules the owner never stated.