create-issflow 1.2.0 → 1.2.1

package/bin/cli.js

@@ -107,8 +107,21 @@ function copyTemplateCommands(destDir) {
 // ---- adapters (keep the methodology single-source — these POINT at it) ------
 
 function adapterClaude() {
+  // Claude Code auto-loads CLAUDE.md only — NOT AGENTS.md. Without a CLAUDE.md
+  // the methodology never enters context on its own (the SessionStart hook still
+  // injects the per-session summary, but the full single-source doc would not
+  // load). A one-line `@AGENTS.md` import gives Claude Code the full baseline
+  // while keeping ONE source of truth — no rule is restated here (anti-drift).
+  const c0 = conflicts;
+  writeFile('CLAUDE.md', claudeMd());
+  if (conflicts > c0) warnings.push('claude: you already keep a CLAUDE.md — ours was written as CLAUDE.md.issflow-new. Add a line `@AGENTS.md` to your CLAUDE.md so the methodology auto-loads.');
+  // Context-budget watchdog config (consumed by .claude/hooks/context-guard.js).
+  // Shipped default window:0 = auto-detect; flow-config.json lives at .claude root,
+  // outside build.js's copied DIRS, so the installer writes it here.
+  writeFile('.claude/flow-config.json', flowConfig());
   const HOOKS = {
     SessionStart: [{ matcher: 'startup|clear|compact', hooks: [{ type: 'command', command: 'node .claude/hooks/session-start.js' }] }],
+    PreToolUse:   [{ matcher: '*',                     hooks: [{ type: 'command', command: 'node .claude/hooks/context-guard.js' }] }],
     PreCompact:   [{ matcher: 'auto|manual',           hooks: [{ type: 'command', command: 'node .claude/hooks/pre-compact.js' }] }],
     SubagentStop: [{ hooks: [{ type: 'command', command: 'node .claude/hooks/subagent-stop.js' }] }],
   };
@@ -176,7 +189,7 @@ function adapterAider() {
 const ADAPTERS = { claude: adapterClaude, codex: adapterCodex, cursor: adapterCursor, gemini: adapterGemini, aider: adapterAider };
 
 const NEXT_STEPS = {
-  claude: 'Open Claude Code — the SessionStart hook fires automatically. Run /overview to bootstrap.',
+  claude: 'Open Claude Code — CLAUDE.md (@AGENTS.md) loads the methodology and the SessionStart hook fires automatically. Run /overview to bootstrap.',
   codex:  'Open Codex CLI — it reads AGENTS.md. Start by running the /overview procedure (.claude/commands/overview.md).',
   cursor: 'Open Cursor — the rule applies automatically. Run the /overview command to bootstrap.',
   gemini: 'Open Gemini CLI — it reads GEMINI.md. Run the SESSION-OPEN ritual, then the overview procedure.',
@@ -199,7 +212,7 @@ function agentsMd() {
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
     '/overview · /propose · /phase · /ui-audit · /qa-audit · /security-audit ·',
-    '/change-request · /replan · /quick · /synthesize · /store-wisdom · /log-issue ·',
+    '/change-request · /replan · /quick · /synthesize · /runbook · /store-wisdom · /log-issue ·',
     '/log-decision · /unstuck', '',
     '## Skills — `.claude/skills/` (loaded on demand)', '',
     'caveman · grill-me · karpathy-guidelines · ux-design · security (Secure SDLC) · code-standards', '',
@@ -225,6 +238,40 @@ function agentsMd() {
   ].join('\n');
 }
 
+function claudeMd() {
+  return [
+    '# CLAUDE.md — iStartSoftFlow (Claude Code entry)', '',
+    '@AGENTS.md', '',
+    'The import above is the single source of truth — it points to',
+    '`.claude/istartsoft-flow/METHODOLOGY.md` (read on demand). Do NOT restate any',
+    'rule here; this file only wires Claude-native mechanisms (anti-drift invariant).', '',
+    '## Claude-native wiring (automatic — see `.claude/settings.json`)', '',
+    '- **SessionStart** hook injects git state + `docs/STATE.md` + open `docs/ISSUES.md`',
+    '  + the rule summary each session — read those first.',
+    '- **PreCompact** + **SubagentStop** hooks run their rituals automatically.',
+    '- Commands in `.claude/commands/` run as `/name`; agents in `.claude/agents/` are',
+    '  native subagents.', '',
+  ].join('\n');
+}
+
+function flowConfig() {
+  return JSON.stringify({
+    context: {
+      window: 0,
+      warnPct: 60,
+      gatePct: 78,
+      _note: 'Context-budget watchdog (.claude/hooks/context-guard.js, PreToolUse hook). '
+        + 'window 0 = auto-detect from the model id (200000 for standard models). '
+        + 'Some 1M-context models report their id WITHOUT a [1m] tag, so auto-detect '
+        + 'assumes 200000 and may false-gate around 156k — if you run a 1M model, set '
+        + 'window:1000000 here by hand. warnPct = soft non-blocking nudge; gatePct = hard '
+        + 'block on NEW build work (Edit/Write-to-source/feature Task). Checkpoint paths '
+        + '(docs/**, STATE/ISSUES/snapshots), the synthesizer subagent, and all Bash are '
+        + 'never blocked.',
+    },
+  }, null, 2) + '\n';
+}
+
 // ---- main -------------------------------------------------------------------
 
 function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Scaffold the iStartSoftFlow AI-coding workflow into a project. Stack-agnostic, tool-agnostic (Claude Code, Codex, Cursor, Gemini, Aider), non-destructive.",
   "bin": {
     "create-issflow": "bin/cli.js"

package/template/.claude/commands/runbook.md

@@ -0,0 +1,38 @@
+---
+description: Capture an operational/incident scenario in docs/RUNBOOK.md — one grep-able markdown so prod-debug knowledge isn't re-derived under pressure.
+argument-hint: [scenario, or "from the incident we just solved"]
+---
+
+Caveman ULTRA mode.
+
+Distill an operational scenario into docs/RUNBOOK.md. Scenario: $ARGUMENTS
+
+This is the runbook pattern Anthropic's Security + Data-Infra teams converged on
+independently: consolidate stack traces, dashboard signals, and the exact
+remediation commands into ONE searchable file so the next incident is a lookup,
+not a re-investigation.
+
+If $ARGUMENTS says "from the incident we just solved" (or similar), distill the
+debugging session in context — symptom, the REAL root cause, the commands that
+fixed it — instead of asking the user to re-type it.
+
+Append an entry to docs/RUNBOOK.md (create the file if missing). Canonical format:
+```
+
+### <scenario title — searchable, literal symptom keywords>
+
+- trigger: <what you observe first — alert, error string, dashboard signal>
+- diagnose: <steps/commands to confirm the real root cause>
+- remediate: <the exact commands/actions that fix it>
+- verify: <how to confirm recovery — what "healthy" looks like>
+- refs: <dashboard URLs, docs, related docs/ISSUES.md titles>
+
+```
+Rules:
+- title carries literal symptom keywords -> grep finds it mid-incident.
+- remediate must be runnable as-is; no "investigate further".
+- mark any step that is irreversible / PROD-writing with ⚠ so it's never run blind.
+- cross-link the matching docs/ISSUES.md entry instead of duplicating root-cause prose.
+- newest scenario at the TOP.
+
+Confirm the entry back in 2 lines.

package/template/.claude/hooks/context-guard.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+// PreToolUse context watchdog (iStartSoftFlow). Two tiers, one hook:
+//   warnPct  -> non-blocking nudge (additionalContext) once per climb into the band
+//   gatePct  -> HARD block of NEW build work (Edit/Write-to-source/feature Task)
+// Reads REAL token usage from the transcript. Fail-OPEN: any error -> allow,
+// never wedge the tool loop on a hook bug.
+const path = require('path');
+const fs = require('fs');
+
+const silent = () => process.exit(0);
+const out = (obj) => { process.stdout.write(JSON.stringify(obj)); process.exit(0); };
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (d) => (input += d));
+process.stdin.on('end', () => {
+  let evt;
+  try { evt = JSON.parse(input); } catch (_) { return silent(); }
+  try { run(evt); } catch (_) { silent(); }
+});
+
+function run(evt) {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || evt.cwd || '.';
+  let ctx;
+  try { ctx = require(path.join(projectDir, '.claude/hooks/lib/ctx.js')); } catch (_) { return silent(); }
+  const cfg = ctx.loadConfig(projectDir);
+  const warn = cfg.warnPct || 60;
+  const gate = cfg.gatePct || 78;
+
+  const u = ctx.contextUsage(evt.transcript_path, cfg);
+  if (!u) return silent();
+
+  const tool = evt.tool_name || '';
+  const ti = evt.tool_input || {};
+  const band = u.pct >= gate ? 'gate' : u.pct >= warn ? 'warn' : 'ok';
+  const BLOCKABLE = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Task']);
+
+  // HARD GATE — block new build mutations; reason is fed to the model.
+  if (band === 'gate' && BLOCKABLE.has(tool) && !isEscape(tool, ti)) {
+    return out({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: gateReason(u, gate),
+      },
+    });
+  }
+
+  // NON-BLOCKING WARN — emit once each time we climb into a higher band.
+  const bandFile = path.join(projectDir, 'docs/.snapshots/.ctx-band');
+  const rank = (b) => (b === 'gate' ? 2 : b === 'warn' ? 1 : 0);
+  let prev = 'ok';
+  try { prev = (fs.readFileSync(bandFile, 'utf8').trim() || 'ok'); } catch (_) {}
+
+  if (rank(band) !== rank(prev)) {
+    try { fs.mkdirSync(path.dirname(bandFile), { recursive: true }); fs.writeFileSync(bandFile, band); } catch (_) {}
+  }
+  if (rank(band) > rank(prev) && band !== 'ok') {
+    return out({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        additionalContext: band === 'gate' ? gateReason(u, gate) : warnReason(u, warn, gate),
+      },
+    });
+  }
+  return silent();
+}
+
+// Checkpoint/logging writes + the synthesizer ritual are never blocked, so the
+// model always has an escape path out of the gate.
+function isEscape(tool, ti) {
+  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit' || tool === 'NotebookEdit') {
+    const fp = ti.file_path || ti.path || ti.notebook_path || '';
+    return /(^|\/)docs\//.test(fp) || /STATE\.md|ISSUES\.md|\.snapshots\//.test(fp);
+  }
+  if (tool === 'Task') return (ti.subagent_type || '').toLowerCase() === 'synthesizer';
+  return false;
+}
+
+const fmt = (n) => (n >= 1000 ? Math.round(n / 1000) + 'k' : String(n));
+
+function gateReason(u, gate) {
+  return [
+    `⛔ CONTEXT GATE — ${u.pct}% (${fmt(u.tokens)}/${fmt(u.window)} tok), เกิน ${gate}% = หยุดเปิดงาน build ใหม่.`,
+    'ทำก่อนไปต่อ:',
+    '  1) ปิด/commit งานค้างให้จบ (Bash/git ไม่ถูก block)',
+    '  2) /synthesize  (อัด handoff docs — subagent นี้ไม่ถูก block)',
+    '  3) /clear       (session ใหม่ บางลง)',
+    'build ต่อหลัง clear. กลาง irreversible op? ใช้ Bash ปิดให้จบก่อน clear.',
+    'ปลดล็อกชั่วคราว: เพิ่ม gatePct ใน .claude/flow-config.json.',
+  ].join('\n');
+}
+
+function warnReason(u, warn, gate) {
+  return [
+    `⚠️ CONTEXT ${u.pct}% (${fmt(u.tokens)}/${fmt(u.window)} tok) — แตะ warn band ${warn}%.`,
+    `วางแผนปิด phase: ทยอย /synthesize → /clear ก่อนถึง gate ${gate}% (เลยจุดนั้น hook block งาน build ใหม่).`,
+    'Delegate งาน noisy ให้ subagent เพื่อกัน context โต.',
+  ].join('\n');
+}

package/template/.claude/hooks/lib/ctx.js

@@ -0,0 +1,82 @@
+'use strict';
+// Shared context-budget math for iStartSoftFlow watchdog hooks.
+// Reads the live Claude Code transcript (JSONL) and reports how full the
+// model's context window currently is — from the REAL token usage the API
+// reported, not a heuristic. Pure Node, cross-platform.
+const fs = require('fs');
+
+// Known context windows by model-id substring. First match wins. The 1M
+// Opus/Sonnet variants advertise "[1m]" in the model id.
+const WINDOWS = [
+  [/\[1m\]|-1m\b|:1m\b|1m-/i, 1000000],
+  [/opus|sonnet|haiku|claude/i, 200000],
+];
+
+function inferWindow(model) {
+  if (!model) return 200000;
+  for (const [re, w] of WINDOWS) if (re.test(model)) return w;
+  return 200000;
+}
+
+// Read project flow config; returns the `context` block or {}.
+function loadConfig(projectDir) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(projectDir + '/.claude/flow-config.json', 'utf8'));
+    return (cfg && cfg.context) || {};
+  } catch (_) { return {}; }
+}
+
+// Read only the last `bytes` of a file (the recent assistant turns live at the
+// tail of the JSONL — no need to load a multi-MB transcript on every tool).
+function readTail(p, bytes) {
+  const fd = fs.openSync(p, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - bytes);
+    const len = size - start;
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, start);
+    return { text: buf.toString('utf8'), partial: start > 0 };
+  } finally { fs.closeSync(fd); }
+}
+
+// Scan lines (newest first) for the most recent assistant usage block.
+// input_tokens + cache_read + cache_creation == the full prompt size actually
+// sent == current context occupancy.
+function scanUsage(text, dropFirst) {
+  const lines = text.split('\n');
+  const lo = dropFirst ? 1 : 0; // first line may be a truncated tail fragment
+  for (let i = lines.length - 1; i >= lo; i--) {
+    const ln = lines[i].trim();
+    if (!ln) continue;
+    let obj;
+    try { obj = JSON.parse(ln); } catch (_) { continue; }
+    const m = obj && obj.message;
+    if (m && m.role === 'assistant' && m.usage && typeof m.usage.input_tokens === 'number') {
+      return { usage: m.usage, model: m.model || obj.model || null };
+    }
+  }
+  return null;
+}
+
+function contextUsage(transcriptPath, cfg) {
+  if (!transcriptPath) return null;
+  let hit;
+  try {
+    const tail = readTail(transcriptPath, 512 * 1024);
+    hit = scanUsage(tail.text, tail.partial);
+    if (!hit && tail.partial) {
+      // usage not in the tail window — fall back to a full read (rare).
+      hit = scanUsage(fs.readFileSync(transcriptPath, 'utf8'), false);
+    }
+  } catch (_) { return null; }
+  if (!hit) return null;
+  const u = hit.usage;
+  const tokens = (u.input_tokens || 0)
+    + (u.cache_read_input_tokens || 0)
+    + (u.cache_creation_input_tokens || 0);
+  const window = (cfg && cfg.window) ? cfg.window : inferWindow(hit.model);
+  return { tokens, window, model: hit.model, pct: Math.round((tokens / window) * 100) };
+}
+
+module.exports = { contextUsage, inferWindow, loadConfig, readTail, scanUsage };

package/template/.claude/istartsoft-flow/METHODOLOGY.md

@@ -421,7 +421,7 @@ the same everywhere — only the *wiring* differs.
 
 | Host | Entry file | Commands | Subagents | Lifecycle hooks | Shared KB |
 |------|-----------|----------|-----------|-----------------|-----------|
-| **Claude Code** (reference) | `AGENTS.md` + `.claude/` | `.claude/commands/` | native | SessionStart · PreCompact · SubagentStop (with context injection) | yes |
+| **Claude Code** (reference) | `CLAUDE.md` (`@AGENTS.md`) + `.claude/` | `.claude/commands/` | native | SessionStart · PreToolUse (context-budget watchdog) · PreCompact · SubagentStop | yes |
 | **Codex CLI** | `AGENTS.md` (native) | `.claude/commands/` (read as prompts) | read as reference | model-run | yes |
 | **Cursor** | `.cursor/rules/` + `AGENTS.md` | `.cursor/commands/` | reads `.claude/agents/` | `.cursor/hooks.json` (sessionStart · subagentStop) | yes |
 | **Gemini CLI** | `GEMINI.md` + `AGENTS.md` | `.claude/commands/` (read as prompts) | read as reference | model-run | yes |