create-issflow 1.8.0 → 1.8.1

package/bin/cli.js

@@ -201,22 +201,28 @@ const NEXT_STEPS = {
 function agentsMd() {
   return [
     '# AGENTS.md — iStartSoftFlow', '',
-    'This repo runs the **iStartSoftFlow** agentic dev workflow. The complete,',
-    'tool-agnostic methodology — the loop, roles, procedures, rituals, and hard',
-    'rules — lives in ONE file. Read it before acting:', '',
+    'This repo runs the **iStartSoftFlow** agentic dev workflow.', '',
+    '**Primary entry (this file).** The complete, tool-agnostic methodology — loop,',
+    'roles, procedures, rituals, hard rules — lives in ONE place. Read before acting:', '',
     '> **`.claude/istartsoft-flow/METHODOLOGY.md`** ← single source of truth.', '',
-    'Do not restate its rules elsewhere; this file only indexes it (anti-drift invariant).', '',
+    'The portable kit lives in **`.claude/`** (folder name = host convention for',
+    'commands/agents/hooks — content is tool-agnostic; see `.claude/README.md`).',
+    'Do not restate METHODOLOGY rules elsewhere (anti-drift).', '',
     '## The loop', '',
-    'design-research → grill ×2 → plan → implement → test → deploy — one VERTICAL',
-    'SLICE per phase. Phase 0 (infra) leads only when infra is self-managed.', '',
+    'design-research → grill ×2 → plan → (propose/design if quoted) → implement →',
+    'test → deploy — one VERTICAL SLICE per phase. Phase 0 (infra) only when',
+    'infra is self-managed.', '',
     '## Roles — `.claude/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
-    '/overview · /feature · /goal · /propose · /phase · /sprint · /ui-audit · /qa-audit ·',
-    '/security-audit · /release · /uat · /change-request · /replan · /quick · /synthesize ·',
-    '/runbook · /store-wisdom · /log-issue · /log-decision · /unstuck', '',
+    '**Default:** `/overview` · `/feature` · `/quick`', '',
+    '**Advanced:** `/propose` · `/design` · `/support` · `/phase` · `/sprint` · `/goal` ·',
+    '`/ui-audit` · `/qa-audit` · `/security-audit` · `/release` · `/uat` ·',
+    '`/change-request` · `/replan` · `/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', '',
+    'caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards ·',
+    'support-triage', '',
     '## Autonomy', '',
     'Planning (`/overview` grill + plan approval) always asks — that input is cheap.',
     '**AUTO (default)** governs the DEV loop: follow the plan, decide + log + continue,',
@@ -225,16 +231,8 @@ function agentsMd() {
     'mid-flow. **GUIDED** asks at each fork in dev too. Declare the mode in',
     '`docs/OVERVIEW.md`. See METHODOLOGY → Autonomy.', '',
     '## Hard-rule index (full text in METHODOLOGY.md)', '',
-    '1 grep ISSUES + research before debugging · 2 debug cap = 3 (AUTO: park + continue) ·',
-    '3 log every fix · 4 synthesize + context-reset per phase · 5 phase gate = real suite',
-    'green · 6 blind tests (RED-first) · 7 programmatic E2E auth · 8 log-decision on arch',
-    'change · 9 UI conforms to the `ux-design` cookbook + wireframe frame · 10 no-rationalization ·',
-    '11 Secure SDLC: threat-model → secure coding → SAST/SCA/secrets each phase → pentest',
-    'gate + security review before deploy (`security` skill) · 12 code-standards gate:',
-    'lint/format clean + naming per language idiom + declared architecture (`code-standards`) ·',
-    '13 PLAN-APPROVAL gate: no phase/sprint starts until `docs/PLAN.md` is human-approved ·',
-    '14 UNDERSTAND-FIRST gate: brief back any new free-text task and wait for confirm',
-    'before executing (an approved PLAN/FEATURE/CR/goal is the recorded confirmation).', '',
+    '1–12 as in METHODOLOGY · 13 PLAN-APPROVAL · 14 UNDERSTAND-FIRST ·',
+    '15 DESIGN + ARCHITECTURE gates (after proposal, before `/phase`; internal may n/a).', '',
     '## Your stack', '',
     'Declare your stack (language, framework, infra, auth, test + E2E runner,',
     'planning source) once in `docs/OVERVIEW.md`. Every rule references *your declared',
@@ -244,17 +242,14 @@ function agentsMd() {
 
 function claudeMd() {
   return [
-    '# CLAUDE.md — iStartSoftFlow (Claude Code entry)', '',
+    '# CLAUDE.md — host shim for Claude Code', '',
     '@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.', '',
+    'Claude Code auto-loads **this filename only**. The import above is the real',
+    'entry (`AGENTS.md` → METHODOLOGY). Do NOT restate rules here.', '',
+    '## Host wiring (automatic — see `.claude/settings.json`)', '',
+    '- **SessionStart** injects git state + `docs/STATE.md` + open `docs/ISSUES.md`.',
+    '- **PreCompact** + **SubagentStop** rituals run automatically.',
+    '- Commands in `.claude/commands/` → `/name`; agents in `.claude/agents/` → native subagents.', '',
   ].join('\n');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.8.0",
+  "version": "1.8.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/README.md

@@ -0,0 +1,33 @@
+# `.claude/` — portable iStartSoftFlow kit
+
+This directory is the **portable workflow kit** installed into every project.
+Content is **tool-agnostic**. The folder name `.claude/` is a **host convention**
+(Claude Code and several other agents load commands/agents/hooks from this path).
+It is **not** “Claude-only product branding.”
+
+**Human entry points (repo root):**
+
+| File | Role |
+|------|------|
+| `AGENTS.md` | Open-standard primary entry — indexes this kit |
+| `CLAUDE.md` | Thin shim (`@AGENTS.md`) — only because Claude Code auto-loads that filename |
+
+**Single source of truth for rules:** [`istartsoft-flow/METHODOLOGY.md`](./istartsoft-flow/METHODOLOGY.md)
+
+## Layout
+
+| Path | What |
+|------|------|
+| `agents/` | Fresh-context workers (planner, researcher, implementer, …) |
+| `commands/` | Procedures — Default: `/overview` `/feature` `/quick`; Advanced: `/propose` `/design` `/support` … |
+| `skills/` | On-demand cookbooks (ux-design, security, support-triage, …) |
+| `hooks/` | Lifecycle enforcement (context, plan gate, feature gate, …) |
+| `istartsoft-flow/` | METHODOLOGY.md — every hard rule lives here once |
+| `templates/` | Proposal / UX pack / architecture / CR / FEATURE / automation |
+| `settings.json` | Host hook wiring (when using Claude Code adapter) |
+| `flow-config.json` | Context watchdog + sprint knobs (optional overrides) |
+
+Do **not** duplicate METHODOLOGY rules into other files (anti-drift).
+Do **not** put personal rate cards or salary numbers in this kit.
+
+Installer: `npx create-issflow` (omit `--tool` = all adapters).

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

@@ -1,16 +1,20 @@
 # iStartSoftFlow — portable agent methodology (single source of truth)
 
-> **The iStartSoft execution loop.** Namespaced under `.claude/istartsoft-flow/`
-> so it coexists with a repo's own agent-instruction files (`CLAUDE.md`,
-> `AGENTS.md`, `GEMINI.md`, …) — it does NOT replace them. The kit is
-> **stack-agnostic and tool-agnostic**: it pins a *process*, not a *stack*.
-> Declare your stack (language, framework, infra, auth, test + E2E runner,
-> planning source) once in `docs/OVERVIEW.md`; every rule below references *your
-> declared stack* and hardcodes none. If infra is **managed** (a PaaS + a managed
-> datastore), Phase 0 (infra) is N/A and phases begin at the first vertical slice;
-> otherwise Phase 0 provisions infra first. Planning source of truth stays in your
-> PRD / architecture / stories (e.g. BMAD / iSSM); iStartSoftFlow is the execution
-> loop layered on top.
+> **The iStartSoft execution loop.** Lives under `.claude/istartsoft-flow/` as
+> part of the **portable kit**. The directory name `.claude/` is a **host
+> convention** (several agents load commands/hooks from that path) — not
+> Claude-only branding. Primary human entry is root **`AGENTS.md`** (open
+> standard). `CLAUDE.md` / `GEMINI.md` / … are thin host adapters that point
+> here; they do NOT replace this file.
+>
+> The kit is **stack-agnostic and tool-agnostic**: it pins a *process*, not a
+> *stack*. Declare your stack (language, framework, infra, auth, test + E2E
+> runner, planning source) once in `docs/OVERVIEW.md`; every rule below
+> references *your declared stack* and hardcodes none. If infra is **managed**
+> (a PaaS + a managed datastore), Phase 0 (infra) is N/A and phases begin at the
+> first vertical slice; otherwise Phase 0 provisions infra first. Planning source
+> of truth stays in your PRD / architecture / stories (e.g. BMAD / iSSM);
+> iStartSoftFlow is the execution loop layered on top.
 
 <!-- ISTARTSOFTFLOW-AGENTS-SENTINEL-v2.0 -->
 > **SENTINEL.** The HTML comment above (`ISTARTSOFTFLOW-AGENTS-SENTINEL-v2.0`) is a
@@ -23,10 +27,11 @@
 > open `AGENTS.md` standard, get the full methodology from here.
 
 > **Anti-drift invariant (load-bearing).** Every rule lives in exactly ONE place:
-> this file. `CLAUDE.md` restates NO rule — it only maps roles to Claude-native
-> files and says "native mechanism X performs ritual Y automatically." A rule and
-> its automation may never contradict. Duplication between files is an
-> architectural defect, not a convenience.
+> this file. Host entry files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, …) restate
+> NO rule — they only index this file and wire host-native mechanisms
+> ("mechanism X performs ritual Y automatically"). A rule and its automation may
+> never contradict. Duplication between files is an architectural defect, not a
+> convenience.
 
 Caveman ULTRA mode always on. Apply the `karpathy-guidelines` skill (engineering
 discipline) on every coding and debugging task. Apply the `ux-design` skill (the UX
@@ -694,19 +699,19 @@ the KB. The kit works normally without a KB.
 
 ## Capability matrix (which host gets what)
 
-The kit is single-source (`.claude/` + this file). `create-issflow --tool=<host>`
-writes the right adapter; unsupported features degrade to model-run rituals, never
-silently vanish. The portable assets (agents, commands, skills, methodology) are
-the same everywhere — only the *wiring* differs.
+Single-source kit: **`.claude/` tree** (portable) + **this file** (rules) + root
+**`AGENTS.md`** (open-standard entry). `create-issflow --tool=<host>` (omit =
+all) writes adapters; unsupported features degrade to model-run rituals, never
+silently vanish. Assets are the same everywhere — only the *wiring* differs.
 
 | Host | Entry file | Commands | Subagents | Lifecycle hooks | Shared KB |
 |------|-----------|----------|-----------|-----------------|-----------|
-| **Claude Code** (reference) | `CLAUDE.md` (`@AGENTS.md`) + `.claude/` | `.claude/commands/` | native | SessionStart · PreToolUse (context watchdog + rule-13 plan gate) · PreCompact · SubagentStop · Stop (feature gate) | yes |
+| **Any AGENTS.md host** | `AGENTS.md` | read as reference | model-run | model-run | 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 |
 | **Aider** | `.aider.conf.yml` → `AGENTS.md` | read as reference | model-run | model-run | yes |
-| **Any AGENTS.md host** | `AGENTS.md` | read as reference | model-run | model-run | yes |
+| **Claude Code** | `CLAUDE.md` (`@AGENTS.md`) + `.claude/` | `.claude/commands/` | native | SessionStart · PreToolUse (context watchdog + plan gate) · PreCompact · SubagentStop · Stop | yes |
 
 "model-run" = the host can't automate the ritual, so the model performs it by hand
 (SESSION-OPEN at the top of each session; the COMPRESS snapshot before a reset).