create-issflow 1.8.0 → 1.9.0

package/README.md

@@ -28,7 +28,7 @@ Flags:
 
 ## What it installs
 
-The portable kit (every tool) in `<project>/.claude/`:
+The portable kit (every tool) in `<project>/.issflow/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
 - `commands/` — `/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`
@@ -44,10 +44,10 @@ Plus a root **`AGENTS.md`** (open standard — primary entry) and the per-tool a
 | `cursor` | `.cursor/rules/` + `.cursor/commands/` + `.cursor/hooks.json` |
 | `gemini` | `GEMINI.md` pointer |
 | `aider` | `.aider.conf.yml` that loads the methodology |
-| `claude` | thin `CLAUDE.md` (`@AGENTS.md`) + merges hooks into `.claude/settings.json` |
+| `claude` | thin `CLAUDE.md` (`@AGENTS.md`) + `.claude/` kit mirror + merges hooks into `.claude/settings.json` (hooks run from `.issflow/`) |
 | `all` | every adapter above |
 
-It also un-ignores the workflow dirs in `.gitignore` if `.claude/*` was ignored.
+It also un-ignores the workflow dirs in `.gitignore` if `.issflow/*` was ignored.
 
 ## Loop
 
@@ -58,10 +58,10 @@ PRD / architecture / stories (e.g. BMAD / iSSM).
 
 ## Maintainers
 
-The kit lives in the repo's `.claude/`. After editing it, run `npm run build`
+The kit lives in the repo's `.issflow/`. After editing it, run `npm run build`
 (pure Node — cmd / PowerShell / sh) to refresh `template/`, then `npm version patch`
 and `npm publish`. `prepublishOnly` rebuilds `template/` on publish automatically.
 
 Everything is cross-platform: the installer and `build.js` are pure Node, and the
-lifecycle hooks are Node scripts (`node .claude/hooks/*.js`) — no bash/jq/python,
+lifecycle hooks are Node scripts (`node .issflow/hooks/*.js`) — no bash/jq/python,
 so the kit runs the same on macOS, Windows, and Linux.

package/bin/cli.js

@@ -3,7 +3,7 @@
 // current project. Pure Node, zero deps, cross-platform, NON-DESTRUCTIVE:
 // never overwrites an existing file — on conflict it writes `<file>.issflow-new`.
 //
-// Tool-agnostic: the portable kit lives in `.claude/` and the methodology is the
+// Tool-agnostic: the portable kit lives in `.issflow/` and the methodology is the
 // single source of truth. `--tool=<name>` writes the right adapter so the same
 // kit drives Claude Code, Codex, Cursor, Gemini CLI, Aider, or any AGENTS.md tool.
 'use strict';
@@ -23,7 +23,7 @@ const toolArg = (argv.find(a => a.startsWith('--tool=')) || '').split('=')[1];
 const TOOLS = {
   claude: 'Claude Code (Anthropic) — full: subagents, lifecycle hooks, skills',
   codex:  'OpenAI Codex CLI — AGENTS.md native; subagents/skills as readable files',
-  cursor: 'Cursor — .cursor/rules + commands + hooks; reads .claude/agents natively',
+  cursor: 'Cursor — .cursor/rules + commands + hooks; kit stays in .issflow/ (no .claude/)',
   gemini: 'Google Gemini CLI — GEMINI.md pointer; commands/skills as readable files',
   aider:  'Aider — .aider.conf.yml loads the methodology as conventions',
   all:    'Write every adapter above (mixed-team repo)',
@@ -50,10 +50,10 @@ Flags:
   --force     overwrite existing kit files (default keeps yours -> <file>.issflow-new)
   -h, --help  this message
 
-Every tool installs the portable kit in .claude/ + a root AGENTS.md (the open
-standard — primary entry for most hosts). The full methodology lives in
-.claude/istartsoft-flow/METHODOLOGY.md. Claude Code also gets a thin CLAUDE.md
-shim (@AGENTS.md) because that host only auto-loads CLAUDE.md.`);
+Every tool installs the portable kit in .issflow/ + a root AGENTS.md (open
+standard). Methodology: .issflow/istartsoft-flow/METHODOLOGY.md.
+Claude Code ONLY (--tool=claude|all) also gets a .claude/ mirror + CLAUDE.md
+shim — other tools do not create .claude/.`);
 }
 
 // Typo / alias map → canonical TOOLS key
@@ -98,33 +98,38 @@ function walk(dir) {
 }
 
 function copyTemplateCommands(destDir) {
-  const cmdDir = path.join(TPL, '.claude', 'commands');
+  const cmdDir = path.join(TPL, '.issflow', 'commands');
   if (!fs.existsSync(cmdDir)) return;
   for (const f of fs.readdirSync(cmdDir)) writeFile(path.join(destDir, f), fs.readFileSync(path.join(cmdDir, f), 'utf8'));
 }
 
+/** Claude Code loads commands/agents/skills from `.claude/`. Mirror the
+ *  portable `.issflow/` kit there (Claude adapter only — Cursor never gets this). */
+function materializeClaudeMirror() {
+  const kitTpl = path.join(TPL, '.issflow');
+  for (const src of walk(kitTpl)) {
+    const rel = path.relative(kitTpl, src);
+    writeFile(path.join('.claude', rel), fs.readFileSync(src, 'utf8'));
+  }
+}
+
 // ---- 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).
+  // Claude Code: needs CLAUDE.md auto-load + native `.claude/` tree for
+  // commands/agents/skills discovery. Portable SoT remains `.issflow/`;
+  // hooks execute from `.issflow/` (single source).
   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());
+  materializeClaudeMirror();
   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' }] },
-                   { matcher: 'Edit|Write|MultiEdit|NotebookEdit', hooks: [{ type: 'command', command: 'node .claude/hooks/plan-gate.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' }] }],
-    Stop:         [{ hooks: [{ type: 'command', command: 'node .claude/hooks/feature-gate.js' }] }],
+    SessionStart: [{ matcher: 'startup|clear|compact', hooks: [{ type: 'command', command: 'node .issflow/hooks/session-start.js' }] }],
+    PreToolUse:   [{ matcher: '*',                     hooks: [{ type: 'command', command: 'node .issflow/hooks/context-guard.js' }] },
+                   { matcher: 'Edit|Write|MultiEdit|NotebookEdit', hooks: [{ type: 'command', command: 'node .issflow/hooks/plan-gate.js' }] }],
+    PreCompact:   [{ matcher: 'auto|manual',           hooks: [{ type: 'command', command: 'node .issflow/hooks/pre-compact.js' }] }],
+    SubagentStop: [{ hooks: [{ type: 'command', command: 'node .issflow/hooks/subagent-stop.js' }] }],
+    Stop:         [{ hooks: [{ type: 'command', command: 'node .issflow/hooks/feature-gate.js' }] }],
   };
   const sp = path.join(CWD, '.claude', 'settings.json');
   let settings = {};
@@ -135,27 +140,28 @@ function adapterClaude() {
   for (const k of Object.keys(HOOKS)) if (!settings.hooks[k]) { settings.hooks[k] = HOOKS[k]; added.push(k); }
   if (added.length) { log(`  + .claude/settings.json hooks: ${added.join(', ')}`); if (!DRY) { fs.mkdirSync(path.dirname(sp), { recursive: true }); fs.writeFileSync(sp, JSON.stringify(settings, null, 2) + '\n'); } }
   else log('  = .claude/settings.json hooks already present');
+  warnings.push('claude: portable SoT is .issflow/ — .claude/ is a host mirror; refresh with create-issflow --tool=claude after kit edits.');
 }
 
 function adapterCodex() {
-  warnings.push('codex: AGENTS.md is read natively. Lifecycle hooks unsupported (rituals model-run); subagents in .claude/agents/ are read as reference, not isolated contexts.');
+  warnings.push('codex: AGENTS.md is read natively. Lifecycle hooks unsupported (rituals model-run); subagents in .issflow/agents/ are read as reference, not isolated contexts.');
 }
 
 function adapterCursor() {
   writeFile('.cursor/rules/istartsoftflow.mdc', [
     '---', 'description: iStartSoftFlow workflow — always apply', 'alwaysApply: true', '---', '',
     'Run the **iStartSoftFlow** workflow. The full, single-source methodology is',
-    '`.claude/istartsoft-flow/METHODOLOGY.md` — read it before acting. Roles live in',
-    '`.claude/agents/` (Cursor reads them natively); procedures in `.cursor/commands/`',
-    '(mirror of `.claude/commands/`). Caveman ULTRA mode; apply the `karpathy-guidelines`',
+    '`.issflow/istartsoft-flow/METHODOLOGY.md` — read it before acting. Roles live in',
+    '`.issflow/agents/` (Cursor reads them natively); procedures in `.cursor/commands/`',
+    '(mirror of `.issflow/commands/`). Caveman ULTRA mode; apply the `karpathy-guidelines`',
     'and `ux-design` skills. See `AGENTS.md` for the role/command/skill map.', '',
   ].join('\n'));
   copyTemplateCommands('.cursor/commands');
   writeFile('.cursor/hooks.json', JSON.stringify({
     version: 1,
     hooks: {
-      sessionStart: [{ command: 'node .claude/hooks/session-start.js' }],
-      subagentStop: [{ command: 'node .claude/hooks/subagent-stop.js' }],
+      sessionStart: [{ command: 'node .issflow/hooks/session-start.js' }],
+      subagentStop: [{ command: 'node .issflow/hooks/subagent-stop.js' }],
     },
   }, null, 2) + '\n');
   warnings.push('cursor: PreCompact has no Cursor equivalent (snapshot ritual degrades to model-run); verify hooks.json against cursor.com/docs/hooks — the schema evolves.');
@@ -166,9 +172,9 @@ function adapterGemini() {
     '# GEMINI.md — iStartSoftFlow', '',
     'This repo runs the **iStartSoftFlow** agentic dev workflow. The complete,',
     'tool-agnostic methodology (the single source of truth) lives in',
-    '`.claude/istartsoft-flow/METHODOLOGY.md` — read it before acting. Roles are in',
-    '`.claude/agents/`, procedures in `.claude/commands/` (run their bodies as prompts),',
-    'skills in `.claude/skills/` (read on demand). See `AGENTS.md` for the full map.', '',
+    '`.issflow/istartsoft-flow/METHODOLOGY.md` — read it before acting. Roles are in',
+    '`.issflow/agents/`, procedures in `.issflow/commands/` (run their bodies as prompts),',
+    'skills in `.issflow/skills/` (read on demand). See `AGENTS.md` for the full map.', '',
     'Lifecycle hooks do not auto-fire in Gemini CLI — run the SESSION-OPEN ritual',
     '(git state, docs/STATE.md, docs/ISSUES.md) yourself at the start of each session.', '',
   ].join('\n'));
@@ -181,7 +187,7 @@ function adapterAider() {
     '# Aider has no lifecycle hooks/subagents; the workflow degrades to model-run rituals.',
     'read:',
     '  - AGENTS.md',
-    '  - .claude/istartsoft-flow/METHODOLOGY.md',
+    '  - .issflow/istartsoft-flow/METHODOLOGY.md',
     '',
   ].join('\n'));
   warnings.push('aider: hooks + named subagents unsupported — the loop runs as a single-agent, model-driven workflow.');
@@ -191,7 +197,7 @@ const ADAPTERS = { claude: adapterClaude, codex: adapterCodex, cursor: adapterCu
 
 const NEXT_STEPS = {
   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).',
+  codex:  'Open Codex CLI — it reads AGENTS.md. Start by running the /overview procedure (.issflow/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.',
   aider:  'Run aider — it loads AGENTS.md + METHODOLOGY.md. Drive the loop manually (overview -> phase).',
@@ -201,22 +207,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:', '',
-    '> **`.claude/istartsoft-flow/METHODOLOGY.md`** ← single source of truth.', '',
-    'Do not restate its rules elsewhere; this file only indexes it (anti-drift invariant).', '',
+    '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:', '',
+    '> **`.issflow/istartsoft-flow/METHODOLOGY.md`** ← single source of truth.', '',
+    'The portable kit lives in **`.issflow/`** (commands, agents, hooks, skills,',
+    'methodology — see `.issflow/README.md`). Host adapters (`.cursor/`, `CLAUDE.md`,',
+    '…) point at it. 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.', '',
-    '## Roles — `.claude/agents/`', '',
+    '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 — `.issflow/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', '',
-    '## Skills — `.claude/skills/` (loaded on demand)', '',
-    'caveman · grill-me · karpathy-guidelines · ux-design · security (Secure SDLC) · code-standards', '',
+    '## Procedures — `.issflow/commands/` (run as `/name`)', '',
+    '**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 — `.issflow/skills/` (loaded on demand)', '',
+    '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 +237,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 +248,16 @@ 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', '',
+    '- **`.claude/`** is a mirror of `.issflow/` for command/agent/skill discovery.',
+    '- **Hooks** run from `.issflow/hooks/` (see `.claude/settings.json`).',
+    '- **SessionStart** injects git state + `docs/STATE.md` + open `docs/ISSUES.md`.',
+    '- **PreCompact** + **SubagentStop** rituals run automatically.',
+    '- Edit the kit in `.issflow/`, then re-run `create-issflow --tool=claude` to refresh the mirror.', '',
   ].join('\n');
 }
 
@@ -264,7 +267,7 @@ function flowConfig() {
       window: 0,
       warnPct: 60,
       gatePct: 78,
-      _note: 'Context-budget watchdog (.claude/hooks/context-guard.js, PreToolUse hook). '
+      _note: 'Context-budget watchdog (.issflow/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 '
@@ -286,7 +289,7 @@ function flowConfig() {
 
 function main() {
   if (HELP) { printHelp(); return; }
-  if (!fs.existsSync(path.join(TPL, '.claude'))) {
+  if (!fs.existsSync(path.join(TPL, '.issflow'))) {
     console.error('create-issflow: embedded template/ missing. From source run: npm run build');
     process.exit(1);
   }
@@ -294,14 +297,14 @@ function main() {
   const TOOL = pickTool();
   const targets = TOOL === 'all' ? Object.keys(TOOLS).filter(t => t !== 'all') : [TOOL];
 
-  // 1. portable kit tree (.claude/) — every tool gets it.
-  for (const src of walk(path.join(TPL, '.claude'))) {
+  // 1. portable kit tree (.issflow/) — every tool gets it.
+  for (const src of walk(path.join(TPL, '.issflow'))) {
     const rel = path.relative(TPL, src);
     writeFile(rel, fs.readFileSync(src, 'utf8'));
   }
 
   // 1b. integrity: confirm the methodology resolved on disk (load-bearing sentinel).
-  const methPath = path.join(CWD, '.claude', 'istartsoft-flow', 'METHODOLOGY.md');
+  const methPath = path.join(CWD, '.issflow', 'istartsoft-flow', 'METHODOLOGY.md');
   const SENTINEL = 'ISTARTSOFTFLOW-AGENTS-SENTINEL-v2.0';
   if (!DRY && (!fs.existsSync(methPath) || !fs.readFileSync(methPath, 'utf8').includes(SENTINEL))) {
     warnings.push(`integrity: ${SENTINEL} not found in installed METHODOLOGY.md — the kit may be incomplete; re-run create-issflow (or npm run build from source).`);
@@ -314,7 +317,7 @@ function main() {
   for (const t of targets) ADAPTERS[t]();
 
   // 3b. headless feature lane (opt-in): materialize the automation templates.
-  const autoDir = path.join(TPL, '.claude', 'templates', 'automation');
+  const autoDir = path.join(TPL, '.issflow', 'templates', 'automation');
   if (CI) {
     writeFile(path.join('.github', 'workflows', 'issflow-feature.yml'), fs.readFileSync(path.join(autoDir, 'issflow-feature.yml'), 'utf8'));
     writeFile(path.join('.github', 'workflows', 'issflow-goal.yml'), fs.readFileSync(path.join(autoDir, 'issflow-goal.yml'), 'utf8'));
@@ -324,13 +327,13 @@ function main() {
     writeFile(path.join('scripts', 'feature-docker.js'), fs.readFileSync(path.join(autoDir, 'feature-docker.js'), 'utf8'), { exec: true });
   }
 
-  // 4. .gitignore: track the workflow dirs if .claude/* is ignored
+  // 4. .gitignore: track the workflow dirs if .issflow/* is ignored
   const gi = path.join(CWD, '.gitignore');
   if (fs.existsSync(gi)) {
     const txt = fs.readFileSync(gi, 'utf8');
-    if (/^\.claude\/\*\s*$/m.test(txt) && !txt.includes('!.claude/agents/')) {
-      const block = '\n# iStartSoftFlow workflow — track as project config\n!.claude/agents/\n!.claude/commands/\n!.claude/skills/\n!.claude/hooks/\n!.claude/istartsoft-flow/\n';
-      log('  + .gitignore: un-ignore .claude workflow dirs');
+    if (/^\.issflow\/\*\s*$/m.test(txt) && !txt.includes('!.issflow/agents/')) {
+      const block = '\n# iStartSoftFlow workflow — track as project config\n!.issflow/agents/\n!.issflow/commands/\n!.issflow/skills/\n!.issflow/hooks/\n!.issflow/istartsoft-flow/\n';
+      log('  + .gitignore: un-ignore .issflow workflow dirs');
       if (!DRY) fs.appendFileSync(gi, block);
     }
   }

package/package.json

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

@@ -0,0 +1,36 @@
+# `.issflow/` — portable iStartSoftFlow kit
+
+This directory is the **portable workflow kit** (tool-agnostic). Every
+`--tool=` install gets this tree. Host-specific adapters live **outside** it
+(`.cursor/`, `CLAUDE.md` + `.claude/` mirror, `GEMINI.md`, …).
+
+**Human entry (repo root):** `AGENTS.md` → indexes this kit.
+
+**Rules SoT:** [`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 scripts |
+| `istartsoft-flow/` | METHODOLOGY.md — every hard rule lives here once |
+| `templates/` | Proposal / UX pack / architecture / CR / FEATURE / automation |
+
+## Claude Code only
+
+Anthropic’s Claude Code loads commands/agents/skills from **`.claude/`**. When you
+install `--tool=claude` (or `all`), the installer also **mirrors** this kit into
+`.claude/` plus a root `CLAUDE.md` shim (`@AGENTS.md`). Cursor / Codex / Gemini /
+Aider installs do **not** create `.claude/`.
+
+Edit the kit in **`.issflow/`**, then re-run `create-issflow --tool=claude` (with
+`--force` if needed) to refresh the Claude mirror. Hooks run from `.issflow/`
+(single source); Claude settings point there.
+
+Do **not** duplicate METHODOLOGY rules into other files (anti-drift).
+Do **not** put personal rate cards in this kit.
+
+Installer: `npx create-issflow` (omit `--tool` = all adapters).

package/template/{.claude → .issflow}/commands/change-request.md

@@ -68,7 +68,7 @@ contingency %.
 CR-<n> | <date> | <change> | impact: <phases> | effort Δ: <±days> |
 cost Δ: <±amount> | new total: <amount> | status: proposed
 ```
-2. Fill `.claude/templates/CR-template.md` → `docs/changes/CR-<n>.md` (detail:
+2. Fill `.issflow/templates/CR-template.md` → `docs/changes/CR-<n>.md` (detail:
    classification, impact, Δ cost, warranty vs billable, status). Keep the detail
    file client-safe on money fields (totals only).
 

package/template/{.claude → .issflow}/commands/design.md

@@ -25,7 +25,7 @@ Target: `$ARGUMENTS` → `ux` | `arch` | `both` (default **both**).
 
 ## STEP 1 — UX PACK (if ux|both)
 1. Apply `ux-design` skill (authoring mode): wireframe baseline + cookbook direction.
-2. Scaffold or update `docs/UX-PACK.md` from `.claude/templates/UX-PACK-template.md`.
+2. Scaffold or update `docs/UX-PACK.md` from `.issflow/templates/UX-PACK-template.md`.
 3. Fill flows, screen inventory, tokens/frame, a11y notes from OVERVIEW + PLAN.
 4. SHOW me UX-PACK.md. **STOP for approval.**
 5. On approve: stamp `> Approval: approved <date> v<n>`; set `design: approved <date>`
@@ -35,7 +35,7 @@ Target: `$ARGUMENTS` → `ux` | `arch` | `both` (default **both**).
 ## STEP 2 — ARCHITECTURE (if arch|both)
 1. Dispatch `researcher` (DESIGN) only if open unknowns remain; else use OVERVIEW.
 2. Scaffold or update `docs/ARCHITECTURE.md` from
-   `.claude/templates/ARCHITECTURE-template.md`.
+   `.issflow/templates/ARCHITECTURE-template.md`.
 3. Apply `code-standards` architecture guidance; security trust boundaries via
    `security` skill when relevant.
 4. SHOW me ARCHITECTURE.md. **STOP for approval.**

package/template/{.claude → .issflow}/commands/feature.md

@@ -14,7 +14,7 @@ Target doc: $ARGUMENTS  (default: the single `docs/features/*/FEATURE.md` whose
 ## ENTRY MODES (before the pipeline)
 
 - **`/feature new <name>`** — scaffold only. Copy
-  `.claude/templates/FEATURE-template.md` to `docs/features/<kebab-name>/FEATURE.md`,
+  `.issflow/templates/FEATURE-template.md` to `docs/features/<kebab-name>/FEATURE.md`,
   fill `<feature name>`, then STOP: the human writes the spec and flips
   `> Approval:` to APPROVED. Never auto-approve; never continue into the pipeline.
 - **`/feature from-story <key>`** — planning-stack bridge. If a story MCP is
@@ -50,7 +50,7 @@ b. APPROVAL GATE (the ONE human gate at entry): the Feature doc must carry a hea
    > Automation: <none | push | push+pr>
    ```
    Missing/PENDING -> HARD-STOP: a human approves the DOC, not the run (need a doc?
-   `/feature new <name>` scaffolds `.claude/templates/FEATURE-template.md`). Doc approval
+   `/feature new <name>` scaffolds `.issflow/templates/FEATURE-template.md`). Doc approval
    is the rule-13 sign-off *scoped to this doc only* — the mini-plan it produces
    inherits approval as long as it stays inside the doc's stated scope.
 

package/template/{.claude → .issflow}/commands/propose.md

@@ -90,7 +90,7 @@ change-orders re-price against.
    the client PROPOSAL.md / HTML). PROPOSAL.md itself stays client-safe so it can
    be shared.
 
-2. RENDER a client-facing `docs/proposal.html` from `.claude/templates/proposal.html`:
+2. RENDER a client-facing `docs/proposal.html` from `.issflow/templates/proposal.html`:
    copy it, replace every `{{PLACEHOLDER}}`, and fill the CONTENT in the declared
    language (the section labels are already bilingual TH / EN). It must fit ONE A4
    page — be terse (≈ 3–6 phase rows, ≈ 4 assumptions, short scope items); trim before

package/template/{.claude → .issflow}/commands/security-audit.md

@@ -15,7 +15,7 @@ Security = "is it SAFE?" — a different axis from QA ("does it work?") and UI
 ("does it look right?"). Passing those never implies this.
 
 ## PRE-FLIGHT
-Read the rubric: `.claude/skills/security/SKILL.md` (the Secure SDLC cookbook) and
+Read the rubric: `.issflow/skills/security/SKILL.md` (the Secure SDLC cookbook) and
 its `references/` (OWASP Top 10 / ASVS / WSTG / ISO 27001 / SLSA). The cookbook IS the
 checklist — audit against it; don't invent criteria.
 

package/template/{.claude → .issflow}/commands/store-wisdom.md

@@ -11,15 +11,15 @@ Only resolved issues and completed research qualify. Open issues do NOT.
 
 ## PRE-FLIGHT
 
-1. Read `.claude/kb-config.json`.
-   - Not found -> STOP. Tell me: "KB not configured. Create `.claude/kb-config.json`
+1. Read `.issflow/kb-config.json`.
+   - Not found -> STOP. Tell me: "KB not configured. Create `.issflow/kb-config.json`
      with `kb_path` + `kb_remote` pointing at the shared KB repo, then retry /store-wisdom."
    - Found -> extract `kb_path` and `kb_remote`.
 
 2. Expand `kb_path` (resolve `~` to home directory).
    Verify the path exists and is a git repo (`git -C <path> status`).
    - Fails -> STOP. Tell me the path is broken and to fix `kb_path` in
-     `.claude/kb-config.json`.
+     `.issflow/kb-config.json`.
 
 ---
 

package/template/{.claude → .issflow}/commands/ui-audit.md

@@ -11,7 +11,7 @@ scores the product, and surfaces drift that accumulated across changes. Run befo
 release, after big UI work, or on request.
 
 ## PRE-FLIGHT
-Read the rubric: `.claude/skills/ux-design/SKILL.md` (the cookbook) and
+Read the rubric: `.issflow/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.
 

package/template/.issflow/flow-config.json

@@ -0,0 +1,12 @@
+{
+  "context": {
+    "window": 1000000,
+    "warnPct": 60,
+    "gatePct": 78,
+    "_note": "window = this session's real context window. THIS repo runs Opus 4.8 [1m] but the transcript records model id as 'claude-opus-4-8' (no [1m] tag), so auto-detect (window:0) would wrongly assume 200000 and false-gate around 156k. Set it explicitly here. Kit template default stays 200000 — override per your model. warnPct = soft non-blocking nudge. gatePct = hard PreToolUse block on NEW build work (Edit/Write to SOURCE files). Checkpoint paths (docs/**, STATE/ISSUES/snapshots) and all Bash (git) are never blocked; Task delegation is never gated (a subagent isolates noise and shrinks orchestrator 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 this block is absent."
+  }
+}

package/template/{.claude → .issflow}/hooks/context-guard.js

@@ -27,7 +27,7 @@ process.stdin.on('end', () => {
 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(); }
+  try { ctx = require(path.join(projectDir, '.issflow/hooks/lib/ctx.js')); } catch (_) { return silent(); }
   const cfg = ctx.loadConfig(projectDir);
   const warn = cfg.warnPct || 60;
   const gate = cfg.gatePct || 78;
@@ -89,7 +89,7 @@ function gateReason(u, gate) {
     '  2) /synthesize  (อัด handoff docs — subagent นี้ไม่ถูก block)',
     '  3) /clear       (session ใหม่ บางลง)',
     'build ต่อหลัง clear. กลาง irreversible op? ใช้ Bash ปิดให้จบก่อน clear.',
-    'ปลดล็อกชั่วคราว: เพิ่ม gatePct ใน .claude/flow-config.json.',
+    'ปลดล็อกชั่วคราว: เพิ่ม gatePct ใน .issflow/flow-config.json.',
   ].join('\n');
 }
 

package/template/{.claude → .issflow}/hooks/lib/ctx.js

@@ -21,7 +21,7 @@ function inferWindow(model) {
 // 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'));
+    const cfg = JSON.parse(fs.readFileSync(projectDir + '/.issflow/flow-config.json', 'utf8'));
     return (cfg && cfg.context) || {};
   } catch (_) { return {}; }
 }

package/template/{.claude → .issflow}/hooks/plan-gate.js

@@ -50,7 +50,7 @@ function run(evt) {
 
   // writable while PENDING: planning + docs + kit + repo meta — never product source.
   const ALLOW = [
-    /^docs\//, /^\.claude\//, /^\.cursor\//, /^\.github\//, /^\.aider/, /^\.git/,
+    /^docs\//, /^\.issflow\//, /^\.claude\//, /^\.cursor\//, /^\.github\//, /^\.aider/, /^\.git/,
     /^(README|AGENTS|CLAUDE|GEMINI|CHANGELOG|LICENSE)[^/]*$/i, /^[^/]+\.md$/,
   ];
   if (ALLOW.some((re) => re.test(rel))) return silent();

package/template/{.claude → .issflow}/hooks/session-start.js

@@ -90,7 +90,7 @@ if (idx !== null) {
 }
 
 // 3d. shared KB — pull latest + load snapshot
-const KB_CONFIG = '.claude/kb-config.json';
+const KB_CONFIG = '.issflow/kb-config.json';
 let kbActive = false;
 if (exists(KB_CONFIG)) {
   let cfg = {}; try { cfg = JSON.parse(read(KB_CONFIG) || '{}'); } catch (_) {}
@@ -126,7 +126,7 @@ if (exists(KB_CONFIG)) {
     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('Fix kb_path in .issflow/kb-config.json (or re-run: npx create-issflow).');
     emit('');
   }
 }

package/template/{.claude → .issflow}/istartsoft-flow/METHODOLOGY.md

@@ -1,16 +1,19 @@
 # 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 `.issflow/istartsoft-flow/` as
+> part of the **portable kit** (tool-agnostic SoT). Primary human entry is root
+> **`AGENTS.md`** (open standard). `CLAUDE.md` / `GEMINI.md` / `.cursor/` / … are
+> thin host adapters that point here; they do NOT replace this file. Claude Code
+> also gets a `.claude/` **mirror** of this kit (host discovery only).
+>
+> 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 +26,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
@@ -166,7 +170,7 @@ documented feature branch out, near-100% hands-off. Humans remain at exactly thr
 points: **approve the doc** (entry) · **UAT** (`/uat` against the generated
 TEST-PLAN) · **merge**. Production deploy is never in this lane (`/release` owns it).
 
-Pipeline (canonical body in `.claude/commands/feature.md`):
+Pipeline (canonical body in `.issflow/commands/feature.md`):
 spec completion → adversarial doc-review → mini-plan → contract surface probe →
 build loop (the `/phase` machinery, feature-scoped) → review & harden → manual
 test plan → docs + token stamp + summary → memory queue → delivery.
@@ -177,13 +181,13 @@ Three layers make "hands-off" real — each uses the mechanism suited to its job
    through the standard roles under AUTO; the circuit breaker, rules 11/12, and
    blind TDD apply unchanged.
 2. **Must-happen-every-time → a lifecycle hook.** `docs/features/<slug>/GATES.md`
-   is the run's gate checklist; the `Stop` hook (`.claude/hooks/feature-gate.js`)
+   is the run's gate checklist; the `Stop` hook (`.issflow/hooks/feature-gate.js`)
    BLOCKS session end while the feature is `(active)` in STATE with unchecked
    gates — and it verifies ARTIFACTS, not ticks: a checked `test-plan` /
    `mini-plan` / `contract-probe` / `token-stamp` / `summary` / `memory-queued`
    gate whose deliverable is missing on disk blocks too (also re-checked in the
    `(done)` state). A prompt can be ignored; the hook cannot. Rule 13 gets the
-   same treatment: the `PreToolUse` plan gate (`.claude/hooks/plan-gate.js`)
+   same treatment: the `PreToolUse` plan gate (`.issflow/hooks/plan-gate.js`)
    denies source Edit/Write while `docs/PLAN.md` reads `> Approval: PENDING`
    (docs/kit paths stay writable; an active feature lane is exempt — its doc
    approval is its own scoped gate). Hosts without lifecycle hooks run these as
@@ -191,14 +195,14 @@ Three layers make "hands-off" real — each uses the mechanism suited to its job
 3. **No-human-at-the-keyboard → a headless runner.** `ISSFLOW_HEADLESS=1` tells the
    lane no human is present: every hard-stop degrades to a `BLOCKED.md` report +
    clean exit — never a guess. Two shipped runners (`create-issflow --ci|--docker`,
-   sources in `.claude/templates/automation/`):
+   sources in `.issflow/templates/automation/`):
    - **GitHub Actions** — label an issue `feature:approved` (or dispatch with a doc
      path); the workflow runs the lane on an ephemeral runner.
    - **Docker** — `node scripts/feature-docker.js <FEATURE.md>` builds
      `Dockerfile.issflow` and runs the lane in an unprivileged container with the
      repo mounted; the container is the sandbox that makes a skip-permissions run
      acceptable. Works for any host that ships a headless CLI. The runner image
-     MUST contain Node ≥ 18 — the lifecycle hooks are `node .claude/hooks/*.js`,
+     MUST contain Node ≥ 18 — the lifecycle hooks are `node .issflow/hooks/*.js`,
      and without node they die silently (no session context, no feature gate).
      The shipped image is Node-based and the wrapper preflights `node` before
      every run, including bring-your-own images (`ISSFLOW_IMAGE=<name>`).
@@ -251,7 +255,7 @@ the planning phase when a project needs that rigor, then drive delivery here.
 ## Roles (fresh-context workers)
 
 Each role is a fresh-context worker mapped to a named Claude Code subagent in
-`.claude/agents/*.md`. A worker dumps its noise to a file and returns only a
+`.issflow/agents/*.md`. A worker dumps its noise to a file and returns only a
 terse summary + path. Workers cannot address the user — only the orchestrator
 can. Escalation is at most two hops.
 
@@ -279,7 +283,7 @@ can. Escalation is at most two hops.
 
 The orchestrator ROUTES. It does not implement or debug.
 
-**Model routing (per-role tiers).** Each role's `.claude/agents/<role>.md` pins a
+**Model routing (per-role tiers).** Each role's `.issflow/agents/<role>.md` pins a
 `model:` tier suited to its work, so the RIGHT model runs each task by default:
 
 | Role | `model:` | Why |
@@ -297,7 +301,7 @@ support run everything on the session model (graceful degrade).
 
 ## Procedures (the slash-command set)
 
-Named procedures, each with a canonical body in `.claude/commands/<name>.md`.
+Named procedures, each with a canonical body in `.issflow/commands/<name>.md`.
 
 **Lane routing — which entry point for which job:**
 
@@ -329,7 +333,7 @@ surface or need its own acceptance criteria? -> `/feature`. Otherwise `/quick`.
   one APPROVED Feature doc → spec completion → adversarial doc-review → mini-plan
   → contract probe → build loop → review & harden → manual test plan →
   docs/stamps/memory → delivery. `new` scaffolds the doc from
-  `.claude/templates/FEATURE-template.md`; `from-story` transforms a BMAD/iSSM
+  `.issflow/templates/FEATURE-template.md`; `from-story` transforms a BMAD/iSSM
   story into a PENDING doc (approval stays human). Gate checklist in
   `docs/features/<slug>/GATES.md`, enforced by the `Stop` hook with artifact
   verification. Headless-capable (CI / Docker, `ISSFLOW_HEADLESS=1`). See "Feature lane".
@@ -402,7 +406,7 @@ At the start of every session, before any other work, surface:
    surface its goal + burndown from `docs/sprints/sprint-<n>.md`.
 3. open items in `docs/ISSUES.md`.
 4. `docs/research/INDEX.md` (research map) + infra/auth status.
-5. shared KB: pull latest + load `docs/.kb-snapshot.md` if `.claude/kb-config.json`
+5. shared KB: pull latest + load `docs/.kb-snapshot.md` if `.issflow/kb-config.json`
    exists.
 6. a one-line reminder of the hard rules below.
 
@@ -606,7 +610,7 @@ fail the other.
 
 ## Shared KB (optional)
 
-If `.claude/kb-config.json` exists, the SESSION-OPEN ritual pulls the KB and loads
+If `.issflow/kb-config.json` exists, the SESSION-OPEN ritual pulls the KB and loads
 a snapshot to `docs/.kb-snapshot.md`. The researcher checks the snapshot (step 0)
 before any web search. Run `store-wisdom` to promote resolved issues + research to
 the KB. The kit works normally without a KB.
@@ -619,10 +623,10 @@ the KB. The kit works normally without a KB.
 - `docs/PROPOSAL.md` — scope + phase breakdown + effort/cost totals + assumptions
   + sign-off. Versioned; client-safe commercial baseline (no rate / contingency %).
 - `docs/proposal.html` — the client-facing proposal, rendered from PROPOSAL.md via
-  `.claude/templates/proposal.html`, in the project language; print-ready (PDF).
+  `.issflow/templates/proposal.html`, in the project language; print-ready (PDF).
 - `docs/UX-PACK.md` · `docs/ARCHITECTURE.md` — pre-build design/arch frames
-  (rule 15); templates under `.claude/templates/`.
-- `.claude/templates/` — document templates (proposal.html, UX-PACK, ARCHITECTURE,
+  (rule 15); templates under `.issflow/templates/`.
+- `.issflow/templates/` — document templates (proposal.html, UX-PACK, ARCHITECTURE,
   CR, FEATURE, …) the commands render into `docs/`.
 - `docs/CHANGES.md` — change-order log (append-only): each scope change with its
   impact, effort/cost delta, new total, and approval status. The commercial audit trail.
@@ -640,14 +644,14 @@ the KB. The kit works normally without a KB.
   `BLOCKED.md` (headless blocker reports).
 - `docs/WISDOM-QUEUE.md` — auto-appended wisdom candidates from feature runs;
   `/store-wisdom` reads it before pushing to the shared KB (push stays human).
-- `.claude/templates/automation/` — headless-runner sources (GitHub Actions ·
+- `.issflow/templates/automation/` — headless-runner sources (GitHub Actions ·
   Dockerfile · docker wrapper), materialized by `create-issflow --ci` /
   `--docker` as `.github/workflows/issflow-feature.yml` +
   `.github/workflows/issflow-goal.yml` (cron-ready, disarmed by default) ·
   `Dockerfile.issflow` · `scripts/feature-docker.js`.
 - `docs/GOALS.md` — the goal layer's state: one `## G<n>` block per goal
   (Done-when · Budget · `Approved:` line · progress ticks). Maintained by `/goal`.
-- `.claude/templates/FEATURE-template.md` — the Feature-doc form `/feature new`
+- `.issflow/templates/FEATURE-template.md` — the Feature-doc form `/feature new`
   scaffolds (Approval/Automation headers + spec sections).
 - `docs/STATE.md` — current position. Small. Rewritten, not appended. Includes
   `plan:`, `design:`, `architecture:` gate pointers (approved · PENDING · n/a).
@@ -681,32 +685,32 @@ the KB. The kit works normally without a KB.
 - `tests/phase-<n>/` — phase-local test suites.
 - `tests/regression/` — cross-phase contract tests (the regression corpus). Run by
   `scripts/regression.sh` (default mock; `--real` runs the real corpus).
-- `.claude/skills/ux-design/` — the UX cookbook + wireframe baseline (read on
+- `.issflow/skills/ux-design/` — the UX cookbook + wireframe baseline (read on
   demand for any UI work).
-- `.claude/skills/security/` — the Secure SDLC cookbook + threat-modeling /
+- `.issflow/skills/security/` — the Secure SDLC cookbook + threat-modeling /
   secure-coding / pentest / standards references (read on demand for security work).
-- `.claude/skills/code-standards/` — naming-per-language + architecture cookbook
+- `.issflow/skills/code-standards/` — naming-per-language + architecture cookbook
   (read on demand for any coding / scaffolding / structure decision).
-- `.claude/kb-config.json` — shared KB path + remote (optional).
+- `.issflow/kb-config.json` — shared KB path + remote (optional).
 - `docs/.kb-snapshot.md` — KB INDEX loaded this session (auto-generated, gitignored).
 
 -----
 
 ## 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: **`.issflow/` 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 |
-| **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 |
+| **Codex CLI** | `AGENTS.md` (native) | `.issflow/commands/` (read as prompts) | read as reference | model-run | yes |
+| **Cursor** | `.cursor/rules/` + `AGENTS.md` | `.cursor/commands/` | reads `.issflow/agents/` | `.cursor/hooks.json` (sessionStart · subagentStop) | yes |
+| **Gemini CLI** | `GEMINI.md` + `AGENTS.md` | `.issflow/commands/` (read as prompts) | read as reference | model-run | yes |
+| **Aider** | `.aider.conf.yml` → `AGENTS.md` | read as reference | model-run | model-run | yes |
+| **Claude Code** | `CLAUDE.md` (`@AGENTS.md`) + `.claude/` mirror | `.claude/commands/` (mirror of `.issflow/`) | native | SessionStart · PreToolUse (context watchdog + plan gate) · PreCompact · SubagentStop · Stop — hooks run from `.issflow/` | 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).

package/template/{.claude → .issflow}/templates/automation/Dockerfile

@@ -18,7 +18,7 @@ RUN apt-get update \
     && rm -rf /var/lib/apt/lists/* \
     && npm install -g @anthropic-ai/claude-code
 
-# sanity: the kit's lifecycle hooks are `node .claude/hooks/*.js` — a runner
+# sanity: the kit's lifecycle hooks are `node .issflow/hooks/*.js` — a runner
 # image WITHOUT node runs claude fine but every hook silently dies (no
 # session-start context, no feature gate). Fail the build, not the run.
 RUN node --version && claude --version

package/template/{.claude → .issflow}/templates/automation/feature-docker.js

@@ -34,7 +34,7 @@ const run = (cmd, args, opts = {}) => spawnSync(cmd, args, { stdio: 'inherit', .
 if (!doc) die('usage: node scripts/feature-docker.js <path/to/FEATURE.md> [--rebuild] [--worktree]');
 const repo = process.cwd();
 if (!fs.existsSync(path.join(repo, doc))) die(`Feature doc not found: ${doc} (run from the repo root)`);
-if (!fs.existsSync(path.join(repo, '.claude', 'commands', 'feature.md'))) die('no .claude/commands/feature.md here — run from a repo with the kit installed');
+if (!fs.existsSync(path.join(repo, '.issflow', 'commands', 'feature.md'))) die('no .issflow/commands/feature.md here — run from a repo with the kit installed');
 if (!process.env.ANTHROPIC_API_KEY) die('ANTHROPIC_API_KEY is not set');
 
 const dockerOk = spawnSync('docker', ['version'], { stdio: 'ignore' });
@@ -44,7 +44,7 @@ const haveImage = spawnSync('docker', ['image', 'inspect', IMAGE], { stdio: 'ign
 if (!haveImage || rebuild) {
   const df = fs.existsSync(path.join(repo, 'Dockerfile.issflow'))
     ? 'Dockerfile.issflow'
-    : path.join('.claude', 'templates', 'automation', 'Dockerfile');
+    : path.join('.issflow', 'templates', 'automation', 'Dockerfile');
   console.log(`feature-docker: building ${IMAGE} from ${df} …`);
   if (run('docker', ['build', '-t', IMAGE, '-f', df, '.']).status !== 0) die('image build failed');
 }