create-issflow 1.4.0 → 1.5.0

package/bin/cli.js

@@ -266,9 +266,15 @@ function flowConfig() {
         + '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.',
+        + 'block on NEW build work (Edit/Write to SOURCE files). Checkpoint paths '
+        + '(docs/**, STATE/ISSUES/snapshots) and all Bash are never blocked; Task '
+        + 'delegation is never gated (a subagent isolates noise and shrinks context).',
+    },
+    sprint: {
+      defaultCapacity: 8,
+      _note: 'Sprint layer (/sprint). defaultCapacity = points committed to the FIRST '
+        + 'sprint before any velocity history exists; later sprints size to the rolling '
+        + 'completed-velocity average. Optional — /sprint falls back to 8 if absent.',
     },
   }, null, 2) + '\n';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "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/agents/e2e-runner.md

@@ -1,6 +1,6 @@
 ---
 name: e2e-runner
-description: Writes and runs functional browser E2E (your declared E2E runner, e.g. Playwright) BLIND — reads only the acceptance spec + docs/ENDPOINTS.md, never the implementation. Writes a trace to docs/research/e2e-<phase-slug>.md; returns a terse summary.
+description: Writes and runs functional browser E2E (your declared E2E runner, e.g. Playwright) BLIND — reads the acceptance spec, OVERVIEW (stack), docs/ENDPOINTS.md, and the E2E runner config, never the implementation. Writes a trace to docs/research/e2e-<phase-slug>.md; returns a terse summary.
 tools: Read, Grep, Glob, Write, Bash
 model: opus
 ---

package/template/.claude/commands/change-request.md

@@ -1,6 +1,6 @@
 ---
 description: Handle a mid-project requirement change — assess impact, re-estimate effort + cost, log the change order, then update the plan + proposal. Run whenever scope changes after the proposal is approved.
-argument-hint: [the requested change]
+argument-hint: [the requested change · "dry-run" to preview impact without logging]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR.
@@ -8,6 +8,11 @@ Caveman ULTRA mode. You are the ORCHESTRATOR.
 A change request is a COMMERCIAL event, not just a re-plan: changing scope changes
 cost and timeline. Handle it transparently and fairly. Change: $ARGUMENTS
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the impact analysis +
+re-estimate but EXECUTE NOTHING — print the ACTION PLAN (cost/scope/timeline delta,
+files you'd touch) and STOP. No change order is logged, no plan/proposal is edited.
+(METHODOLOGY → Dry-run.)
+
 ## PRE-FLIGHT
 Read `docs/PROPOSAL.md` (the approved baseline), `docs/PLAN.md`, `docs/STATE.md`,
 and `docs/CHANGES.md` (create if missing). No approved proposal yet -> you're still

package/template/.claude/commands/log-issue.md

@@ -12,7 +12,7 @@ Canonical format:
 
 ### <short error title — searchable, literal error keywords>
 
-- [x] open      (or “- [x] resolved”)
+- [ ] open      (or “- [x] resolved” once fixed)
 - symptom: <what was observed>
 - root cause: <the REAL underlying cause>
 - solution: <exact fix, or “pending”>
@@ -23,6 +23,8 @@ Rules:
 - title must contain literal error keywords -> grep finds it.
 - root cause is the real cause, not "the line threw an error".
 - always fill "failed attempts" — stops repeated dead ends.
+- open issues use the empty box `- [ ]`; resolved are checked `- [x] resolved`
+  (the SessionStart hook surfaces every `- [ ]` as open — keep the box empty until fixed).
 - open issues go at the TOP; resolved below; archived oldest at bottom.
 
 Confirm the entry back in 2 lines.

package/template/.claude/commands/phase.md

@@ -1,8 +1,9 @@
 ---
 description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression guard at CLOSE.
-argument-hint: [phase number]
+argument-hint: [phase number · "dry-run" to preview what the phase would do]
 ---
 
+
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
 you do NOT implement or debug yourself.
 
@@ -12,6 +13,15 @@ Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
 
 ---
 
+## DRY-RUN CHECK (first — before PRE-FLIGHT)
+
+If `$ARGUMENTS` contains `dry-run` or `--dry-run`: do the full analysis but EXECUTE
+NOTHING. Print the ACTION PLAN — files you'd create/change · agents you'd dispatch ·
+tests/gates you'd run · deploy target · cost/scope/risk impact — then STOP. Write,
+run, commit, deploy nothing. (METHODOLOGY → Dry-run.)
+
+---
+
 ## 0. PRE-FLIGHT
 
 a. PLAN-APPROVAL CHECK (hard rule 13): Read the docs/PLAN.md `> Approval:` header.

package/template/.claude/commands/propose.md

@@ -1,6 +1,6 @@
 ---
 description: Turn approved requirements + tech stack into a client proposal — scope, phase breakdown, effort + cost estimate, timeline, assumptions, and a sign-off gate. Run after /overview, before building.
-argument-hint: [optional: rate / budget / constraints]
+argument-hint: [optional: rate / budget / constraints · "dry-run" to preview]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR.
@@ -9,6 +9,10 @@ Purpose: produce `docs/PROPOSAL.md` — WHAT we build, in what phases, how long,
 much, and on what assumptions — for the client to approve BEFORE any build starts.
 A proposal is a commercial gate: always interactive (both AUTO and GUIDED).
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the full analysis but
+EXECUTE NOTHING — print the ACTION PLAN (scope, phase breakdown, rough estimate)
+and STOP. No PROPOSAL.md / proposal.html is written. (METHODOLOGY → Dry-run.)
+
 ## PRE-FLIGHT
 Read `docs/OVERVIEW.md` (scope, stack, success criteria) and `docs/PRD.md` if
 present (else the PRD in your BMAD/iSSM). No OVERVIEW -> run `/overview` first.

package/template/.claude/commands/quick.md

@@ -1,12 +1,16 @@
 ---
 description: Make a small, obvious change directly — no agent chain, no phase overhead.
-argument-hint: [what to change]
+argument-hint: [what to change · "dry-run" to preview the edit]
 ---
 
 Caveman ULTRA mode. Apply `karpathy-guidelines` skill.
 
 Purpose: skip the orchestration tax for a 5-line fix.
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, describe the exact edit
+you'd make (file · lines · the change) and the regression you'd run, then STOP —
+change nothing. (METHODOLOGY → Dry-run.)
+
 Use `/quick` when ALL hold:
 - change is small (under 30 lines) and obvious
 - no new vertical slice

package/template/.claude/commands/release.md

@@ -1,6 +1,6 @@
 ---
 description: Pre-production release pipeline — after all build phases, run the full automated gauntlet (full regression: functional / integration / e2e · all audits: UI / QA / security / code · smoke test), then hand off to manual UAT, drive the defect loop to green, produce a sign-off document, and promote to production. The automated SDLC backbone; production deploy is a human-signed hard-stop.
-argument-hint: [optional: target env]
+argument-hint: [optional: target env · "dry-run" to preview the pipeline without running it]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR.
@@ -10,6 +10,10 @@ AUTO runs all AUTOMATED stages without stopping; it STOPS only at the human gate
 UAT execution, sign-off, and the production promote (security/irreversible hard-stops).
 Record progress in STATE.md so a resumed session continues mid-pipeline.
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the full analysis but
+EXECUTE NOTHING — print the ACTION PLAN (stages, audits, deploy target, risk impact)
+and STOP. Nothing is run, signed, or promoted. (METHODOLOGY → Dry-run.)
+
 ## STAGE 1 — FULL REGRESSION (auto)
 Run the whole REAL corpus end-to-end: **functional + integration + e2e**
 (`scripts/regression.sh --real`, then the declared E2E runner via `e2e-runner`).

package/template/.claude/commands/replan.md

@@ -54,9 +54,10 @@ commercial impact (split/merge/reorder, a discovered technical re-slice).
    - A MERGE -> consolidate the merged phases' regression tests.
    - A REORDER -> keep the tests as-is (contracts are phase-independent).
    Do NOT touch phase-local `tests/phase-<n>/` here beyond renumbering dirs.
-   After reconciling, run `scripts/regression.sh --real` to confirm the
-   reconciled corpus still passes against live services. A failure -> surface it
-   and stop before approval.
+   After reconciling, re-run the regression corpus to confirm it still passes:
+   `--real` ONLY if at least one phase is done (live services exist); on a pre-build
+   replan (no done phase, managed infra not yet wired) run the mock corpus instead,
+   or skip with a noted reason. A failure -> surface it and stop before approval.
 
 6. PLAN-APPROVAL gate (hard rule 13). A re-plan reshapes UNBUILT scope, so it reverts
    the plan to unapproved: set the PLAN.md `> Approval:` header back to `PENDING`, SHOW

package/template/.claude/commands/sprint.md

@@ -1,6 +1,6 @@
 ---
 description: The Scrum sprint layer — group PLAN phases into time-/scope-boxed sprints and run the full ceremony set (planning → standups → review/demo → retrospective → close) with burndown + velocity. AUTO-facilitated: the orchestrator runs every ceremony itself and drives the sprint end-to-end without stopping, pausing only at the real hard-stops. The layer between PLAN (backlog) and PHASE (build loop).
-argument-hint: [run|plan|standup|review|retro|close|status] [sprint number]
+argument-hint: [run|plan|standup|review|retro|close|status] [sprint number · "dry-run"]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR / SCRUM MASTER. You FACILITATE the
@@ -8,6 +8,11 @@ ceremonies and ROUTE build work to subagents — you do NOT implement or debug y
 
 Subcommand: $ARGUMENTS  (default: `status`)
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the full analysis but
+EXECUTE NOTHING — print the ACTION PLAN (which phases the sprint would commit,
+ceremonies it would run, points/capacity) and STOP. No sprint file is written, no
+phase runs. (METHODOLOGY → Dry-run.)
+
 Hierarchy: **PLAN (product backlog) → SPRINT (committed slice of phases) → PHASE
 (the build loop)**. A sprint groups consecutive PLAN phases behind ONE sprint goal
 and ships ONE deployable increment. Phases still run via `/phase` exactly as before

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

@@ -15,7 +15,7 @@ Steps:
 
 - [ ] open - stuck after 3 attempts
 - symptom: <…>
-- attempts that FAILED: <hypothesis 1>, <2>, <3>
+- failed attempts: <hypothesis 1>, <2>, <3>
 
 ```
 Reference the existing debug-<slug>.md.

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

@@ -2,7 +2,11 @@
 '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)
+//   gatePct  -> HARD block of NEW build work (Edit/Write to SOURCE files)
+// Delegation (Task) is the prescribed escape — a subagent runs in its OWN context
+// and returns a terse summary, so it SHRINKS orchestrator context, never grows it.
+// Blocking it would force the orchestrator to build inline (worse). So Task is
+// never gated; only direct source mutations by the orchestrator are.
 // 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');
@@ -34,7 +38,7 @@ function run(evt) {
   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']);
+  const BLOCKABLE = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
 
   // HARD GATE — block new build mutations; reason is fed to the model.
   if (band === 'gate' && BLOCKABLE.has(tool) && !isEscape(tool, ti)) {
@@ -67,15 +71,12 @@ function run(evt) {
   return silent();
 }
 
-// Checkpoint/logging writes + the synthesizer ritual are never blocked, so the
-// model always has an escape path out of the gate.
+// Checkpoint/logging writes (docs/**, STATE/ISSUES/snapshots) are never blocked,
+// so the model always has an escape path out of the gate. (Task delegation is not
+// in BLOCKABLE at all — see the header note — so it needs no escape carve-out.)
 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 fp = ti.file_path || ti.path || ti.notebook_path || '';
+  return /(^|\/)docs\//.test(fp) || /STATE\.md|ISSUES\.md|\.snapshots\//.test(fp);
 }
 
 const fmt = (n) => (n >= 1000 ? Math.round(n / 1000) + 'k' : String(n));

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

@@ -80,7 +80,7 @@ if (issues !== null) {
 // 3b. research index
 const idx = read('docs/research/INDEX.md');
 if (idx !== null) {
-  const rows = idx.split('\n').filter((l) => /^[0-9]/.test(l));
+  const rows = idx.split('\n').filter((l) => /^\|\s*\d{4}-\d{2}-\d{2}/.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);

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

@@ -191,9 +191,9 @@ can. Escalation is at most two hops.
   phases it is dispatched BEFORE logic exists (RED-first), so blindness is
   structural, not honor-system. Writes a MOCK suite + a REAL API suite.
 - **e2e-runner** — writes/runs functional browser E2E (your declared E2E runner,
-  e.g. Playwright) BLIND. Reads only the acceptance spec + `docs/ENDPOINTS.md`,
-  never the implementation. Writes a trace to `docs/research/e2e-<phase-slug>.md`;
-  returns a terse summary.
+  e.g. Playwright) BLIND. Reads the acceptance spec, `docs/OVERVIEW.md` (stack),
+  `docs/ENDPOINTS.md`, and the E2E runner config — never the implementation. Writes
+  a trace to `docs/research/e2e-<phase-slug>.md`; returns a terse summary.
 - **debugger** — debugs in an ISOLATED context. Writes a trace to
   `docs/research/debug-<slug>.md`; returns a summary.
 - **synthesizer** — compresses `docs/STATE.md` / `docs/ISSUES.md`, prunes
@@ -351,6 +351,18 @@ development run that follows the spec and logs every problem so it never recurs.
 
 -----
 
+## Dry-run (preview — change nothing)
+
+Pass `dry-run` (or `--dry-run`) to ANY command and it does the full analysis but
+EXECUTES NOTHING: it prints the ACTION PLAN — files it would create/change · agents
+it would dispatch · tests/gates it would run · the deploy target · cost / scope /
+risk impact — then STOPS. Nothing is written, run, committed, or deployed. A safe
+preview to see the blast radius first. Most useful before side-effecting commands:
+`/phase` · `/release` · `/change-request` · `/sprint` · `/propose` · `/quick`.
+Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it only reports.)
+
+-----
+
 ## Hard rules (1–13)
 
 1. Before debugging ANY error: grep `docs/ISSUES.md` AND `docs/research/INDEX.md`.