cc-dev-template 0.1.104 → 0.1.106

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.104",
+  "version": "0.1.106",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/scripts/statusline.js

@@ -21,10 +21,10 @@ const { homedir } = require('os');
 // Usage API cache
 const USAGE_CACHE_PATH = join(homedir(), '.claude', '.usage-cache.json');
 const USAGE_LOCK_PATH = join(homedir(), '.claude', '.usage-cache.lock');
-const USAGE_CACHE_TTL = 30000; // 30s normal refresh interval
-const USAGE_ERROR_TTL = 300000; // 5 min backoff on errors (rate limit, network, etc.)
+const USAGE_CACHE_TTL = 180000; // 3 min refresh interval (API rate limit is ~10 calls/5 min)
+const USAGE_ERROR_TTL = 600000; // 10 min backoff on errors (rate limit recovery is slow)
 const USAGE_LOCK_TTL = 15000; // 15s lock (curl timeout is 5s, 15s is generous)
-const USAGE_HISTORY_MAX = 20; // ~10 min of readings at 30s intervals
+const USAGE_HISTORY_MAX = 20; // ~60 min of readings at 3 min intervals
 
 // Background refresh mode: fetch usage data and write cache, then exit
 if (process.argv.includes('--refresh')) {
@@ -87,8 +87,8 @@ function getUsageBurnRate(history, key) {
   const newest = history[history.length - 1];
   const minutesElapsed = (newest.t - oldest.t) / 60000;
 
-  // Need at least 2 minutes of data for a stable reading
-  if (minutesElapsed < 2) return null;
+  // Need at least 6 minutes of data for a stable reading (2 refresh cycles)
+  if (minutesElapsed < 6) return null;
 
   const deltaUtilization = newest[key] - oldest[key];
   return deltaUtilization / minutesElapsed;

package/src/skills/prevent-regression/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: prevent-regression
+description: "Codifies an agent mistake into a permanent backpressure mechanism. Use when an agent did something wrong and you want to ensure it never happens again. User-invoked only."
+disable-model-invocation: true
+argument-hint: "[description of what the agent did wrong]"
+---
+
+# Prevent Regression
+
+The issue to prevent: **$ARGUMENTS**
+
+## Core Principle: Generate Backpressure
+
+Backpressure is a deterministic feedback loop that lets the agent self-correct without human intervention. The goal of this workflow is to convert a one-time mistake into a permanent mechanism that applies automatic corrective force whenever the agent drifts toward the same error.
+
+The key insight: **you can accidentally steer a model, but you cannot accidentally steer a type checker.** The more deterministic the check, the stronger the backpressure. Prose instructions are the weakest form — the model can misread them, ignore them, or be steered away from them by conflicting context. A lint test or a hook that exits non-zero is impossible to ignore.
+
+Read `references/step-1-diagnose.md`.

package/src/skills/prevent-regression/references/step-1-diagnose.md

@@ -0,0 +1,33 @@
+# Step 1: Diagnose
+
+Understand what went wrong and why the agent did it.
+
+## Examine the Evidence
+
+Read the relevant code or files involved. If a specific location was mentioned, go there. Search for the violation in the actual source.
+
+## Find the Root Cause
+
+Determine why the agent did this. Common causes:
+
+| Cause | Signal |
+|-------|--------|
+| **Pattern-matched bad code** | Existing code elsewhere does the same wrong thing |
+| **No guidance existed** | No CLAUDE.md or rule covered this case |
+| **Reasonable but wrong** | Defensible on general principles — just not our convention |
+| **Wrong hierarchy level** | Guidance existed but wasn't loaded for this file type |
+| **Conflicting guidance** | Two instructions pointed in different directions |
+| **Black-box assumption** | Agent assumed how an external system works without verifying |
+
+If the agent pattern-matched on bad existing code, identify all instances of that bad code — they may need to be fixed alongside adding the prevention mechanism.
+
+If the agent made a wrong assumption about an external system (SDK, API, CLI), note that — a learning test may be appropriate alongside the backpressure mechanism.
+
+## Output
+
+State:
+1. The exact violation (one sentence)
+2. The most likely root cause (one sentence)
+3. Any existing bad code that should be cleaned up
+
+**IMPORTANT: You are not done. Read `references/step-2-triage.md` now.**

package/src/skills/prevent-regression/references/step-2-triage.md

@@ -0,0 +1,81 @@
+# Step 2: Choose the Backpressure Mechanism
+
+Evaluate each tier in order. Use the **highest tier that can catch this violation** — higher tiers are more deterministic and harder to ignore.
+
+The backpressure hierarchy, from strongest to weakest:
+
+## Tier 1: Automated Test (Strongest — Try First)
+
+A test that runs in CI or via a `make`/`npm`/`cargo` command.
+
+Viable when you can write a test that:
+- Detects the violation deterministically (grep pattern, AST check, import analysis, etc.)
+- Won't false-positive on legitimate code
+- Can run without external dependencies (no network, no API keys)
+
+Common patterns:
+- **Lint/grep tests**: Walk source files and flag banned patterns (e.g., forbidden imports, wrong naming conventions, missing annotations)
+- **Architecture tests**: Verify dependency boundaries, module structure, or export constraints
+- **Contract tests**: Assert invariants about configuration files, schema shapes, or API surfaces
+
+This is the strongest backpressure because it runs deterministically, produces clear error messages, and blocks merging. The agent gets immediate feedback with exact file and line numbers.
+
+If viable → go to `references/step-3-implement.md` with **decision = Tier 1**.
+
+## Tier 2: Claude Code Hook (Try Second)
+
+A hook that fires when the agent writes or edits files, runs commands, or thinks it's done.
+
+Viable when:
+- The violation happens during code generation, not in saved code
+- You can detect it from the tool input (file path, content, command)
+- A test can't catch it because the wrong code looks syntactically fine
+- You want to catch it *before* it's written, not after
+
+Available hook events:
+- **`PreToolUse` on `Edit|Write`** — inspect file path + new content before it's written; can block (exit 2) or advise (exit 0 + JSON context)
+- **`PreToolUse` on `Bash`** — inspect the command about to run
+- **`PostToolUse` on `Edit|Write`** — react after a file is written
+- **`Stop` hook** — runs when the agent thinks it's done; deterministically run final checks and inject failures back into context
+
+Blocking (exit 2): write reason to stderr — the agent sees it and must adjust.
+Advising (exit 0 + JSON): output context that gets injected into the agent's window — softer but still automatic.
+
+Stop hooks are particularly powerful: they let you run a full test suite or validation pass at the moment the agent believes it's finished, catching anything that slipped through.
+
+If viable → go to `references/step-3-implement.md` with **decision = Tier 2**.
+
+## Tier 3: Pre-commit Hook (Try Third)
+
+A git pre-commit hook that blocks the commit if violations are found.
+
+Viable when:
+- The check should run against the full staged changeset, not individual edits
+- You want a final gate before code lands in version control
+- The check is fast enough to run on every commit (< 5 seconds)
+
+Pre-commit hooks are strong backpressure because they're deterministic and the agent cannot bypass them (unless explicitly told to skip). They also protect against human mistakes, not just agent mistakes.
+
+If viable → go to `references/step-3-implement.md` with **decision = Tier 3**.
+
+## Tier 4: CLAUDE.md Rule (Weakest — Last Resort)
+
+A prose instruction in a CLAUDE.md or rules file.
+
+Use when Tiers 1–3 are not viable. This is the weakest backpressure because:
+- The model can misread or overlook it
+- Conflicting context can steer the model away from following it
+- There is no deterministic enforcement — it relies entirely on the model's judgment
+
+To maximize effectiveness of prose rules:
+- Write imperatives, not suggestions ("Never import X from Y" not "You should avoid importing X from Y")
+- Place the rule in the most specific file in the hierarchy (path-scoped rules files > directory CLAUDE.md > root CLAUDE.md)
+- If possible, pair with a higher-tier mechanism — the prose explains *why*, the test/hook enforces *what*
+
+If Tier 4 is the only option → go to `references/step-3-implement.md` with **decision = Tier 4**.
+
+---
+
+**Tiers are not mutually exclusive.** The best backpressure is layered: a lint test (Tier 1) catches it in CI, a hook (Tier 2) catches it at write-time, and a CLAUDE.md rule (Tier 4) explains the *why* so the agent avoids the mistake in the first place. Deterministic enforcement + prose explanation is stronger than either alone.
+
+**IMPORTANT: You are not done. Read `references/step-3-implement.md` now.**

package/src/skills/prevent-regression/references/step-3-implement.md

@@ -0,0 +1,133 @@
+# Step 3: Implement
+
+Implement the backpressure mechanism for your chosen tier, then verify it works.
+
+---
+
+## Tier 1: Add an Automated Test
+
+Find the project's existing test infrastructure. Look for:
+- An existing lint or architecture test file (search for patterns like `walkFiles`, `lint_test`, `architecture.test`, or grep-based test assertions)
+- The project's test runner and how to invoke it
+
+If there's an existing lint/architecture test file, add your check there following the established patterns. If there isn't one, create one in the appropriate test directory.
+
+The test should:
+1. Scan the relevant source files
+2. Detect the violation pattern
+3. Report the exact file, line number, and violating code
+4. Include a clear error message explaining **why** this is wrong and **what to do instead**
+
+The error message is critical — it's the "tokens" that give the agent (or human) feedback. A message like `"Found 3 violations"` is weak backpressure. A message like `"auth.go:42: Direct DB query in handler. Use the repository pattern instead — see docs/architecture.md"` is strong backpressure because it tells the agent exactly what's wrong and how to fix it.
+
+After adding the test:
+1. Run it — confirm it detects the violation (if the violating code still exists)
+2. Fix the violating code
+3. Run it again — confirm it passes cleanly
+
+If you also want to add a CLAUDE.md annotation, mark it `[enforced by test]` so agents know there's a deterministic check behind the instruction.
+
+---
+
+## Tier 2: Add a Claude Code Hook
+
+Add the hook to the project's `.claude/settings.json` (project-level) or `~/.claude/settings.json` (user-level).
+
+For simple checks, use an inline command:
+```json
+{
+  "matcher": "Edit|Write",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "bash -c 'INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r \".tool_input.file_path // empty\"); if [[ -z \"$FILE\" ]]; then exit 0; fi; # your check here; exit 0'"
+    }
+  ]
+}
+```
+
+For complex logic, write a script:
+- Save to `.claude/scripts/your-check.sh` (project-level) or `~/.claude/scripts/your-check.sh` (user-level)
+- Make it executable: `chmod +x`
+- Reference it: `"command": "bash .claude/scripts/your-check.sh"`
+
+Script template for a **blocking** check (exit 2):
+```bash
+#!/bin/bash
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')
+
+# Only check relevant files
+if [[ "$FILE" != *.go ]]; then exit 0; fi
+
+# Detect the violation
+if echo "$CONTENT" | grep -q "BANNED_PATTERN"; then
+  echo "Blocked: [explain the rule and what to do instead]" >&2
+  exit 2
+fi
+
+exit 0
+```
+
+Script template for an **advising** check (exit 0 + context injection):
+```bash
+#!/bin/bash
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Inject a reminder into the agent's context
+echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","additionalContext":"Reminder: [your guidance here]"}}'
+exit 0
+```
+
+For **Stop hooks** (runs when agent thinks it's done):
+```json
+{
+  "matcher": "Stop",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "bash -c 'cd /path/to/project && make lint 2>&1 || exit 2'"
+    }
+  ]
+}
+```
+
+Test the hook by triggering the bad action and confirming the block/advice fires.
+
+---
+
+## Tier 3: Add a Pre-commit Hook
+
+Add or update the project's pre-commit hook (`.git/hooks/pre-commit` or via a framework like pre-commit, husky, or lefthook).
+
+The hook should:
+1. Inspect staged files (`git diff --cached --name-only`)
+2. Check for the violation pattern
+3. Print a clear error message explaining what's wrong
+4. Exit non-zero to block the commit
+
+If the project uses a pre-commit framework, add your check as a new hook entry following the existing patterns.
+
+---
+
+## Tier 4: Update CLAUDE.md
+
+Find the most specific applicable file in the project's CLAUDE.md hierarchy. The more specific the file, the less noise it adds to unrelated work.
+
+General hierarchy (most specific → least specific):
+- Path-scoped rules files (`.claude/rules/*.md` with glob patterns)
+- Directory-level CLAUDE.md files (`src/auth/CLAUDE.md`)
+- Root CLAUDE.md
+
+Write instructions, not documentation. Imperative. One or two sentences.
+
+Good: `Never import from internal/compiler in the bridge package. This creates a circular dependency. [enforced by test]`
+Bad: `You should consider avoiding imports from the compiler package in bridge code for architectural reasons.`
+
+---
+
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
+
+Read `references/step-4-reflect.md` now.

package/src/skills/prevent-regression/references/step-4-reflect.md

@@ -0,0 +1,32 @@
+# Step 4: Reflect
+
+**IMPORTANT: This step is mandatory. The prevent-regression workflow is not complete until this step is finished. Do not skip this.**
+
+## Assess the Backpressure Quality
+
+Answer these questions:
+
+1. **Determinism** — Is the mechanism deterministic? Can the agent ignore it? A lint test or hook that exits non-zero is impossible to ignore. A CLAUDE.md rule is not. If you chose a lower tier, go back and check: could a higher tier have worked?
+
+2. **Observability** — Does the mechanism produce clear, actionable feedback? The agent needs tokens that tell it *what* went wrong and *how* to fix it. Vague error messages are weak backpressure. Specific messages with file paths, line numbers, and fix instructions are strong backpressure.
+
+3. **Root cause fixed?** — If the agent pattern-matched bad existing code, did you clean up that code too? Leaving bad examples in the codebase while adding a rule creates conflicting signals — the code says "do this" while the rule says "don't do this." The code often wins because the model pattern-matches on what it sees.
+
+4. **Layering** — Did you consider combining tiers? The strongest prevention is layered: a deterministic check (Tier 1/2/3) catches violations mechanically, paired with a prose explanation (Tier 4) that helps the agent avoid the mistake in the first place. Enforcement + explanation > either alone.
+
+5. **Specificity** — Is the mechanism scoped correctly? A rule that belongs in a path-scoped rules file but landed in the root CLAUDE.md will fire for every file and add noise. A hook that checks every file when it should only check `*.go` files wastes cycles and risks false positives.
+
+## Act
+
+If any answer reveals a problem:
+- Fix the prevention mechanism (wrong tier → implement the better tier; bad code still present → clean it up; vague error message → make it specific)
+- If you found that the skill instructions were missing something for this scenario, note it in the report
+
+## Report
+
+Tell the user:
+1. What tier(s) were used and why
+2. What was implemented (test name/location, hook config, rule file, or combination)
+3. The backpressure strength — is it deterministic (agent cannot ignore) or advisory (agent should follow)?
+4. How to verify it works (run command, trigger scenario, etc.)
+5. Any follow-up work (bad patterns still in codebase, related rules to add, opportunities to upgrade to a stronger tier later)