cc-dev-template 0.1.103 → 0.1.105

package/package.json

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

package/src/scripts/statusline.js

@@ -21,9 +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 = 120000; // 2 minutes
-const USAGE_LOCK_TTL = 30000; // 30s lock to prevent concurrent refresh spawns
-const USAGE_HISTORY_MAX = 20; // ~40 min of readings at 2min intervals
+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_LOCK_TTL = 15000; // 15s lock (curl timeout is 5s, 15s is generous)
+const USAGE_HISTORY_MAX = 20; // ~10 min of readings at 30s intervals
 
 // Background refresh mode: fetch usage data and write cache, then exit
 if (process.argv.includes('--refresh')) {
@@ -307,13 +308,33 @@ function getOAuthToken() {
   }
 }
 
+/**
+ * Write error backoff to cache — preserves existing data/history,
+ * but delays next refresh attempt by USAGE_ERROR_TTL.
+ */
+function writeErrorBackoff() {
+  const now = Date.now();
+  try {
+    const existing = JSON.parse(readFileSync(USAGE_CACHE_PATH, 'utf-8'));
+    existing.nextRefreshAfter = now + USAGE_ERROR_TTL;
+    writeFileSync(USAGE_CACHE_PATH, JSON.stringify(existing));
+  } catch {
+    writeFileSync(USAGE_CACHE_PATH, JSON.stringify({
+      timestamp: now,
+      nextRefreshAfter: now + USAGE_ERROR_TTL,
+      data: null,
+      history: [],
+    }));
+  }
+}
+
 /**
  * Fetch usage data from API and write to cache (runs in background)
  */
 function refreshUsageCache() {
   try {
     const token = getOAuthToken();
-    if (!token) return;
+    if (!token) { writeErrorBackoff(); return; }
 
     const result = spawnSync('curl', [
       '-s', '--max-time', '3',
@@ -323,59 +344,62 @@ function refreshUsageCache() {
       '-H', 'Content-Type: application/json',
     ], { encoding: 'utf-8', timeout: 5000 });
 
-    if (result.status === 0 && result.stdout) {
-      const data = JSON.parse(result.stdout.trim());
-      if (data.five_hour && data.seven_day) {
-        // Load existing history and append new reading
-        let history = [];
-        try {
-          const existing = JSON.parse(readFileSync(USAGE_CACHE_PATH, 'utf-8'));
-          if (Array.isArray(existing.history)) history = existing.history;
-        } catch {}
-
-        const now = Date.now();
-        history.push({
-          t: now,
-          five_hour: data.five_hour.utilization,
-          seven_day: data.seven_day.utilization,
-        });
+    if (result.status !== 0 || !result.stdout) { writeErrorBackoff(); return; }
 
-        // Keep only the last N readings
-        if (history.length > USAGE_HISTORY_MAX) {
-          history = history.slice(-USAGE_HISTORY_MAX);
-        }
+    let responseData;
+    try { responseData = JSON.parse(result.stdout.trim()); } catch { writeErrorBackoff(); return; }
 
-        writeFileSync(USAGE_CACHE_PATH, JSON.stringify({
-          timestamp: now,
-          data,
-          history,
-        }));
-        try { unlinkSync(USAGE_LOCK_PATH); } catch {}
-      }
+    if (!responseData.five_hour || !responseData.seven_day) { writeErrorBackoff(); return; }
+
+    // --- Success path ---
+    let history = [];
+    try {
+      const existing = JSON.parse(readFileSync(USAGE_CACHE_PATH, 'utf-8'));
+      if (Array.isArray(existing.history)) history = existing.history;
+    } catch {}
+
+    const now = Date.now();
+    history.push({
+      t: now,
+      five_hour: responseData.five_hour.utilization,
+      seven_day: responseData.seven_day.utilization,
+    });
+
+    if (history.length > USAGE_HISTORY_MAX) {
+      history = history.slice(-USAGE_HISTORY_MAX);
     }
+
+    writeFileSync(USAGE_CACHE_PATH, JSON.stringify({
+      timestamp: now,
+      nextRefreshAfter: now + USAGE_CACHE_TTL,
+      data: responseData,
+      history,
+    }));
   } catch {
-    // Silently fail - stale cache will be used on next render
+    writeErrorBackoff();
+  } finally {
+    try { unlinkSync(USAGE_LOCK_PATH); } catch {}
   }
 }
 
 /**
- * Read cached usage data, trigger background refresh if stale
+ * Read cached usage data, trigger background refresh if scheduled time has passed.
+ * All instances share the same nextRefreshAfter timestamp — only one refresh per cycle.
  */
 function getUsageData() {
   let cacheData = null;
   let cacheHistory = null;
-  let cacheAge = Infinity;
+  let shouldRefresh = true; // refresh if no cache exists
 
   try {
     const raw = readFileSync(USAGE_CACHE_PATH, 'utf-8');
     const cache = JSON.parse(raw);
     cacheData = cache.data;
     cacheHistory = cache.history || null;
-    cacheAge = Date.now() - cache.timestamp;
+    shouldRefresh = Date.now() > (cache.nextRefreshAfter || 0);
   } catch {}
 
-  // Trigger background refresh if cache is stale and no other refresh is running
-  if (cacheAge > USAGE_CACHE_TTL) {
+  if (shouldRefresh) {
     let lockHeld = false;
     try {
       const lockTime = parseInt(readFileSync(USAGE_LOCK_PATH, 'utf-8'), 10);

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)