create-issflow 1.0.3 → 1.2.0

package/template/.claude/commands/ui-audit.md

@@ -0,0 +1,54 @@
+---
+description: Holistic UI audit — sweep the WHOLE product's UI against the ux-design cookbook (+ a11y / responsive / consistency), score it, and produce a prioritized findings report. On-demand or before a release. This is NOT the per-phase gate — the `ux-design` gate checks one screen at phase close (pass/block); this audit sweeps every screen and reports accumulated drift.
+argument-hint: [optional scope — a route, or "all"]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Purpose: a periodic, WHOLE-PRODUCT UI audit — distinct from the inline `ux-design`
+gate. The gate validates ONE screen at phase close; this AUDIT sweeps EVERY screen,
+scores the product, and surfaces drift that accumulated across changes. Run before a
+release, after big UI work, or on request.
+
+## PRE-FLIGHT
+Read the rubric: `.claude/skills/ux-design/SKILL.md` (the cookbook) and
+`references/wireframe-template.md` (the frame). The cookbook IS the checklist —
+do not invent new criteria; audit against it.
+
+## STEP 1 — INVENTORY
+List every screen / route / major component to audit (from the router, the
+wireframe baseline, or `$ARGUMENTS`). Audit shared components once.
+
+## STEP 2 — SWEEP  (dispatch a worker per area to keep context lean)
+Score each screen against the cookbook dimensions:
+- design tokens · 8-pt spacing · type scale (no raw hex/px)
+- iconography — a real SVG set, **NEVER emoji**
+- accessibility (WCAG 2.1 AA): contrast ≥ 4.5:1, visible focus, keyboard reach,
+  semantic HTML, labels / alt / aria, 44×44 targets, `prefers-reduced-motion`
+- state matrix: default · hover · focus · active · disabled · loading · empty · error
+- responsive breakpoints (no overflow / break)
+- content & i18n (no hardcoded strings; growth-safe)
+- consistency / wireframe conformance (no drift BETWEEN screens)
+Run automated tools if the project has them (axe-core / Lighthouse / pa11y) and fold
+their output in; otherwise do the manual cookbook sweep.
+
+## STEP 3 — SCORE + FINDINGS
+Rate each dimension PASS / WARN / FAIL. For every finding record:
+- **severity**: BLOCKER (a11y / contrast / unusable) · MAJOR (drift / missing state)
+  · MINOR (polish)
+- **location**: screen + element
+- **issue** + the cookbook rule it breaks
+- **fix**: the concrete change
+
+## STEP 4 — REPORT
+Write `docs/ui-audit-<YYYY-MM-DD>.md`:
+- coverage (screens audited) · a per-dimension scoreboard · the findings table sorted
+  by severity · a prioritized fix list.
+- Log BLOCKER / MAJOR findings to `docs/ISSUES.md`.
+- **VERDICT: SHIP | FIX-FIRST** — a release must not ship with open BLOCKERs.
+
+## STEP 5 — REMEDIATE
+AUTO: fix MINOR / MAJOR that don't change the visual direction, re-audit them, log.
+A new visual direction or a design-token change → confirm with the user first
+(hard rule 9 — UI conforms to the frame; new direction is a human call).
+Hand back the report + what was fixed vs parked.

package/template/.claude/commands/unstuck.md

@@ -1,40 +1,40 @@
----
-description: Forced re-research after a circuit breaker. Stops flailing, re-routes to deep research with full memory of dead ends.
----
-
-Caveman ULTRA mode.
-
-Trigger: I chose "re-research" at a circuit breaker (see /phase step 5).
-
-Steps:
-
-1. WRITE IT DOWN. Append to docs/ISSUES.md as OPEN:
-```
-
-### <error title>
-
-- [ ] open - stuck after 3 attempts
-- symptom: <…>
-- attempts that FAILED: <hypothesis 1>, <2>, <3>
-
-```
-Reference the existing debug-<slug>.md.
-
-2. RESET FRAME. The 3 failed hypotheses are probably all wrong. Discard them.
-
-3. DEEP RESEARCH. Dispatch `researcher` in IMPL mode WIDE:
-- Read existing debug-<slug>.md and ISSUES.md failed-attempts FIRST.
-- Re-read the actual error from scratch.
-- Check real external service contract / docs.
-- Look one layer below: config? env? version? data shape?
-- Return fresh HYPOTHESIS backed by NEW evidence.
-
-4. RE-PLAN if needed. Research shows phase design was wrong -> dispatch planner.
-
-5. RESUME. Hand fresh hypothesis to `debugger`. It reads the prior debug file
-(already knows what's ruled out). Budget = 3, NEW hypotheses only.
-
-6. This counts as the path chosen at the first breaker. If STUCK again ->
-/phase step 5 SECOND STUCK. Do not loop further.
-
-Report each step.
+---
+description: Forced re-research after a circuit breaker. Stops flailing, re-routes to deep research with full memory of dead ends.
+---
+
+Caveman ULTRA mode.
+
+Trigger: I chose "re-research" at a circuit breaker (see /phase step 5).
+
+Steps:
+
+1. WRITE IT DOWN. Append to docs/ISSUES.md as OPEN:
+```
+
+### <error title>
+
+- [ ] open - stuck after 3 attempts
+- symptom: <…>
+- attempts that FAILED: <hypothesis 1>, <2>, <3>
+
+```
+Reference the existing debug-<slug>.md.
+
+2. RESET FRAME. The 3 failed hypotheses are probably all wrong. Discard them.
+
+3. DEEP RESEARCH. Dispatch `researcher` in IMPL mode WIDE:
+- Read existing debug-<slug>.md and ISSUES.md failed-attempts FIRST.
+- Re-read the actual error from scratch.
+- Check real external service contract / docs.
+- Look one layer below: config? env? version? data shape?
+- Return fresh HYPOTHESIS backed by NEW evidence.
+
+4. RE-PLAN if needed. Research shows phase design was wrong -> dispatch planner.
+
+5. RESUME. Hand fresh hypothesis to `debugger`. It reads the prior debug file
+(already knows what's ruled out). Budget = 3, NEW hypotheses only.
+
+6. This counts as the path chosen at the first breaker. If STUCK again ->
+/phase step 5 SECOND STUCK. Do not loop further.
+
+Report each step.

package/template/.claude/hooks/pre-compact.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// PreCompact hook. Fires before auto/manual compaction. Snapshots the live
+// position so a post-compact session can recover. Pure Node, cross-platform.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+try { process.chdir(process.env.CLAUDE_PROJECT_DIR || '.'); } catch (_) {}
+
+const sh = (cmd) => { try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); } catch (_) { return ''; } };
+const read = (f) => { try { return fs.readFileSync(f, 'utf8'); } catch (_) { return null; } };
+
+fs.mkdirSync('docs/.snapshots', { recursive: true });
+const d = new Date();
+const p2 = (n) => String(n).padStart(2, '0');
+const stamp = `${d.getFullYear()}${p2(d.getMonth() + 1)}${p2(d.getDate())}-${p2(d.getHours())}${p2(d.getMinutes())}${p2(d.getSeconds())}`;
+const snap = path.join('docs/.snapshots', `precompact-${stamp}.md`);
+
+const state = read('docs/STATE.md');
+const body = [
+  `# Pre-compact snapshot ${stamp}`, '',
+  '## Git',
+  sh('git status --short').replace(/\n+$/, ''),
+  sh('git diff --stat').replace(/\n+$/, ''),
+  '',
+  '## STATE.md at compact time',
+  state !== null ? state.replace(/\n$/, '') : '(no STATE.md)',
+  '',
+].join('\n');
+fs.writeFileSync(snap, body);
+
+// keep the 5 newest precompact snapshots
+const old = fs.readdirSync('docs/.snapshots')
+  .filter((f) => /^precompact-.*\.md$/.test(f))
+  .map((f) => ({ f, t: fs.statSync(path.join('docs/.snapshots', f)).mtimeMs }))
+  .sort((a, b) => b.t - a.t)
+  .slice(5);
+for (const { f } of old) { try { fs.unlinkSync(path.join('docs/.snapshots', f)); } catch (_) {} }
+
+process.stdout.write(`Context was compacted. Recovery snapshot saved at ${snap}.\n`);
+process.stdout.write('STATE.md and ISSUES.md were re-injected by the SessionStart hook - trust those.\n');

package/template/.claude/hooks/session-start.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// SessionStart hook. stdout is injected into the agent's context every session.
+// Pure Node, cross-platform (macOS / Windows / Linux) — no bash/jq/python needed.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+try { process.chdir(process.env.CLAUDE_PROJECT_DIR || '.'); } catch (_) {}
+
+const out = [];
+const emit = (s = '') => out.push(s);
+const read = (f) => { try { return fs.readFileSync(f, 'utf8'); } catch (_) { return null; } };
+const exists = (f) => fs.existsSync(f);
+const sh = (cmd) => { try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); } catch (_) { return ''; } };
+
+emit('=== iStartSoftFlow AUTO-CONTEXT (injected by hook, NOT optional) ===');
+emit('');
+
+// 1. git state
+emit('## Git');
+emit('branch: ' + (sh('git branch --show-current').trim() || 'n/a'));
+const uncommitted = sh('git status --short').split('\n').filter((l) => l.trim() !== '').length;
+emit('uncommitted: ' + uncommitted + ' file(s)');
+for (const l of sh('git log --oneline -3').replace(/\n+$/, '').split('\n').filter(Boolean)) emit('  ' + l);
+emit('');
+
+// 2. active state (cap size — STATE.md is meant to stay small)
+const state = read('docs/STATE.md');
+if (state !== null) {
+  emit('## STATE.md (current position - READ THIS FIRST)');
+  const sl = state.replace(/\n$/, '').split('\n');
+  for (const l of sl.slice(0, 40)) emit(l);
+  if (sl.length > 40) emit(`… (+${sl.length - 40} more — STATE.md should be small; trim it)`);
+  emit('');
+} else {
+  emit('## STATE.md missing -> run /overview to bootstrap the project.');
+  emit('');
+}
+
+// 3. issue log — inject only OPEN issues (resolved ones stay in the file for
+//    grep, but are NOT re-paid in tokens every session). Capped.
+const issues = read('docs/ISSUES.md');
+if (issues !== null) {
+  const blocks = [];
+  let cur = null;
+  for (const l of issues.split('\n')) {
+    if (/^### /.test(l)) { if (cur) blocks.push(cur); cur = [l]; }
+    else if (cur) cur.push(l);
+  }
+  if (cur) blocks.push(cur);
+  const open = blocks.filter((b) => b.some((l) => /- \[ \]/.test(l)));
+  emit(`## ISSUES.md (${open.length} open) - grep this file before debugging anything`);
+  if (open.length) {
+    const flat = open.flat();
+    for (const l of flat.slice(0, 50)) emit(l);
+    if (flat.length > 50) emit('… (more — grep docs/ISSUES.md for full detail)');
+  } else {
+    emit('(no open issues)');
+  }
+  emit('');
+}
+
+// 3b. research index
+const idx = read('docs/research/INDEX.md');
+if (idx !== null) {
+  const rows = idx.split('\n').filter((l) => /^[0-9]/.test(l));
+  emit(`## research/INDEX.md (${rows.length} prior investigations)`);
+  emit('grep this before any new research or debugging.');
+  for (const l of rows.slice(-15)) emit('  ' + l);
+  emit('');
+}
+
+// 3d. shared KB — pull latest + load snapshot
+const KB_CONFIG = '.claude/kb-config.json';
+let kbActive = false;
+if (exists(KB_CONFIG)) {
+  let cfg = {}; try { cfg = JSON.parse(read(KB_CONFIG) || '{}'); } catch (_) {}
+  let kbPath = cfg.kb_path || '';
+  if (kbPath.startsWith('~')) kbPath = path.join(os.homedir(), kbPath.slice(1));
+  if (kbPath && exists(kbPath) && fs.statSync(kbPath).isDirectory()) {
+    emit('## Shared KB');
+    let pulled = true;
+    try { execSync(`git -C "${kbPath}" pull --ff-only --quiet`, { stdio: 'ignore' }); } catch (_) { pulled = false; }
+    emit(pulled ? 'KB pulled: OK' : 'KB pull skipped (offline or conflict — using local copy)');
+
+    const cut = new Date(); cut.setMonth(cut.getMonth() - 6);
+    const cutoff = cut.toISOString().slice(0, 10);
+    const today = new Date().toISOString().slice(0, 10);
+    const kbIndex = path.join(kbPath, 'INDEX.md');
+    if (exists(kbIndex)) {
+      const lines = (read(kbIndex) || '').split('\n').filter((l) => l && !l.startsWith('#'));
+      const snap = [`# KB snapshot — loaded ${today}`, `# Stale = created date older than ${cutoff}`, ''];
+      let stale = 0, total = 0;
+      for (const line of lines) {
+        if (line.includes('|')) total++;
+        const entryDate = (line.split('|')[0] || '').trim();
+        if (/^\d{4}-\d{2}-\d{2}$/.test(entryDate) && entryDate < cutoff) { snap.push('[STALE] ' + line); stale++; }
+        else snap.push(line);
+      }
+      try { fs.mkdirSync('docs', { recursive: true }); fs.writeFileSync('docs/.kb-snapshot.md', snap.join('\n') + '\n'); } catch (_) {}
+      emit(`KB snapshot loaded: ${total} entries (${stale} stale — researcher will re-research these)`);
+      emit('Snapshot at docs/.kb-snapshot.md — researcher reads this before web search.');
+    } else {
+      emit(`KB INDEX.md not found at ${kbPath} — run /store-wisdom to populate it.`);
+    }
+    emit('');
+    kbActive = true;
+  } else {
+    emit('## Shared KB: configured but path not found (' + (cfg.kb_path || '') + ')');
+    emit('Fix kb_path in .claude/kb-config.json (or re-run: npx create-issflow).');
+    emit('');
+  }
+}
+
+// 4. hard rule reminder
+emit('## RULES (enforced this session)');
+emit('- AUTO mode (default) governs the DEV loop: follow the plan — decide + log +');
+emit('  continue, do NOT stop to ask. (Planning / grill still asks — that part is fine.)');
+emit('  Hard-stops only: security / irreversible-or-outbound actions / contradictory spec.');
+emit('- caveman ULTRA mode is active.');
+emit('- before debugging ANY error: grep ISSUES.md AND research/INDEX.md first.');
+emit('- debug attempts: WARN at 2; cap 3. AUTO: log + park the slice + continue (batched');
+emit('  report at the phase boundary). GUIDED: stop and ask you.');
+emit('- end of every phase: run /synthesize, then /clear.');
+emit('- small obvious change? use /quick, not /phase.');
+emit('- token economy: keep context lean. Delegate noisy work to subagents (they');
+emit('  return summaries). If one phase grows past ~50% of the model window, split');
+emit('  it or /synthesize -> /clear — do not coast to auto-compact.');
+if (kbActive) {
+  emit('- KB active: researcher checks docs/.kb-snapshot.md before web search.');
+  emit('- learned something worth keeping? run /store-wisdom.');
+}
+emit('=== END AUTO-CONTEXT ===');
+
+process.stdout.write(out.join('\n') + '\n');

package/template/.claude/hooks/subagent-stop.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// SubagentStop hook. Appends a trace line, keeps the log bounded. Cross-platform.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+try { process.chdir(process.env.CLAUDE_PROJECT_DIR || '.'); } catch (_) {}
+
+fs.mkdirSync('docs/.snapshots', { recursive: true });
+const log = path.join('docs/.snapshots', 'agent-trace.log');
+const d = new Date();
+const p2 = (n) => String(n).padStart(2, '0');
+const ts = `${p2(d.getHours())}:${p2(d.getMinutes())}:${p2(d.getSeconds())}`;
+
+let lines = [];
+try { lines = fs.readFileSync(log, 'utf8').split('\n').filter(Boolean); } catch (_) {}
+lines.push(`${ts} subagent finished`);
+fs.writeFileSync(log, lines.slice(-50).join('\n') + '\n');