create-issflow 1.8.1 → 1.9.1

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).',
@@ -204,23 +210,23 @@ function agentsMd() {
     '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.', '',
-    '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).', '',
+    '> **`.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 → (propose/design if quoted) → implement →',
     'test → deploy — one VERTICAL SLICE per phase. Phase 0 (infra) only when',
     'infra is self-managed.', '',
-    '## Roles — `.claude/agents/`', '',
+    '## Roles — `.issflow/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
-    '## Procedures — `.claude/commands/` (run as `/name`)', '',
+    '## 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 — `.claude/skills/` (loaded on demand)', '',
+    '## Skills — `.issflow/skills/` (loaded on demand)', '',
     'caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards ·',
     'support-triage', '',
     '## Autonomy', '',
@@ -246,10 +252,12 @@ function claudeMd() {
     '@AGENTS.md', '',
     '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`)', '',
+    '## 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.',
-    '- Commands in `.claude/commands/` → `/name`; agents in `.claude/agents/` → native subagents.', '',
+    '- Edit the kit in `.issflow/`, then re-run `create-issflow --tool=claude` to refresh the mirror.', '',
   ].join('\n');
 }
 
@@ -259,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 '
@@ -281,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);
   }
@@ -289,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).`);
@@ -309,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'));
@@ -319,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.1",
+  "version": "1.9.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/.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).
 
@@ -77,7 +77,8 @@ Show me CR-<n> (impact + price delta + new total — no rate). **STOP for approv
 (commercial gate — always interactive).
 - **Approved** -> set CR status `approved`; bump PROPOSAL.md to a new version (vN+1)
   with the delta folded in (**totals only**); re-render `docs/proposal.html` from it
-  (same template + language; no contingency note / rate); then dispatch `/replan` to
+  (same `/propose` package rows + screen appendix — do not dump every PLAN phase
+  onto the sign table; same template + language; no contingency note / rate); then dispatch `/replan` to
   apply the phase changes to PLAN.md (done phases stay frozen). Update STATE.md.
   NOTE: `/replan` reverts PLAN.md to `> Approval: PENDING` and re-runs the
   PLAN-APPROVAL gate (hard rule 13) — the commercial CR sign-off is SEPARATE from

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

@@ -1,17 +1,18 @@
 ---
-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.
+description: Turn approved requirements + tech stack into a client proposal — scope, packages, effort + cost estimate, timeline, assumptions, screen appendix, and a sign-off gate. Run after /overview, before building.
 argument-hint: [optional: rate / budget / constraints · "dry-run" to preview]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR.
 
-Purpose: produce `docs/PROPOSAL.md` — WHAT we build, in what phases, how long, how
+Purpose: produce `docs/PROPOSAL.md` — WHAT we build, in what packages, how long, how
 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.)
+EXECUTE NOTHING — print the ACTION PLAN (scope, phase breakdown, package collapse,
+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
@@ -28,12 +29,15 @@ List the deliverables (features / epics) from OVERVIEW / PRD. Mark each
 **in-scope** or **out-of-scope** explicitly — naming out-of-scope items now is what
 prevents silent scope creep (and grounds change-order re-pricing later).
 
-## STEP 2 — PHASE BREAKDOWN
+## STEP 2 — PHASE BREAKDOWN (internal)
 Derive the vertical-slice phases (or read `docs/PLAN.md` if it exists). Size each:
 - complexity: **S | M | L | XL**
 - effort: an ideal-days RANGE (e.g. 2–3d), + story points if your team uses them
 - risk / unknowns: what could move the estimate
 
+Keep this sizing for the **chat math**. Do **not** dump every PLAN phase onto the
+client table — collapse into packages in STEP 5.
+
 ## STEP 3 — ESTIMATE (ask rate · never invent a kit default)
 Estimation config is **project-private**. The public kit ships **no** default rate
 card and **no** sample salary/rate numbers — rates are confidential.
@@ -46,22 +50,35 @@ card and **no** sample salary/rate numbers — rates are confidential.
 3. Optional: store the answered rate/contingency in a **project-local** file the
    team keeps private (e.g. `docs/ESTIMATE.local.md` gitignored, or OVERVIEW fields
    that never get published). Never commit personal rate/salary into a public kit
-   or template.
+   or template. If you create `docs/ESTIMATE.local.md`, add it to the project's
+   `.gitignore` when it is not already listed.
 4. Configurable fields (ask or read — no invented kit defaults for money):
    - **unit:** ideal-days | hours | story-points | both
    - **rate card:** blended OR per-role (senior / mid / junior…)
    - **currency:** as declared (ask if unset; THB is common for Thai clients)
    - **contingency:** % buffer for unknowns (ask if unset)
-   - **payment milestones:** by-phase, split (e.g. 30/40/30), or none
+   - **payment split:** e.g. 30/40/30 — **ASK once; do not guess** a ratio
    - **language:** rendered doc language (default = project language)
 
+Ask these **once each** if unset (commercial input — do not invent kit defaults):
+
+- **Hours columns:** does the client table show estimated hours next to billed
+  hours? If yes → columns ประเมิน / คิดเงิน / ยอด. If no / unset → ชุดงาน + ยอด
+  only. Hours are effort, not a rate — still never print the rate.
+- **Managed hosting / database:** is platform hosting+database **in** the quoted
+  total? If **not included**, write clearly on page 1 (out of scope + exclusions)
+  that the client pays the provider directly. A one-line exclusion is enough —
+  do **not** paste vendor SKU/price tables into the kit or invent list prices.
+- **Bank:** include a bank block **only if the human provides** account details
+  in this project. No kit default. If none given, omit the column.
+
 Compute cost per phase, then a **Total as a RANGE (low–high)** that already folds
 in contingency. Show the math **in chat to the human** (rate × effort + contingency).
 **Timeline:** phases in dependency order → calendar estimate (note parallelism).
 
 ### CLIENT-DOC RULE (hard — commercial privacy)
 Client-facing artifacts (`docs/PROPOSAL.md` client sections, `docs/proposal.html`,
-and any PDF/print) MUST show **totals and phase costs only**.
+and any PDF/print) MUST show **totals and package costs only**.
 **Never** print: hourly/day rates, rate cards, contingency %, “incl. X% buffer”,
 salary, or the estimate math. Contingency is already inside the numbers — do not
 label it on the client page.
@@ -71,38 +88,83 @@ List every assumption the estimate rests on (infra provided, third-party/licence
 costs excluded, content/design provided, etc.). These are the baseline that
 change-orders re-price against.
 
+If hosting/database is not in the quote, the exclusion **must** say the client
+pays the provider directly.
+
 ## STEP 5 — WRITE + RENDER
+Collapse the internal PLAN phases into **3–6 client packages / sprints** that a
+non-engineer can read. PLAN may have any number of phases; the sign page does not
+list them all.
+
+Payment copy = short **software delivery events** tied to those packages, e.g.
+deposit on sign-off then work starts · when the main package is usable · when
+production is up within the scope on this quote. **Never** construction wording
+(% structure, house handover, site prep / equipment staging).
+
 1. Write `docs/PROPOSAL.md` — the SOURCE OF TRUTH (versioned v1 + date). This is
    what `CHANGES.md` re-prices against. **Client-safe** body (no rate / no
    contingency %):
 ```
 # Proposal — <project>   (v1, <date>)
 ## Scope        — in-scope: … | out-of-scope: …
-## Phases       — table: phase | complexity | effort (range) | cost
+## Packages     — table: package | cost
+                — or package | estimated | billed | cost  (only if hours columns requested)
 ## Total        — <low>–<high>   ← totals only; no “incl. X% contingency”
 ## Timeline     — <estimate>, dependency order
 ## Assumptions  — …
-## Exclusions   — …
-## Payment      — milestones (if any)
+## Exclusions   — … (hosting/database: client pays provider, if that was the answer)
+## Payment      — software delivery events + the asked split (if any)
+## Screens      — docs/proposal.html pages 2–N (or “none — no UI in scope”)
+                — not pixel-binding; sign page 1 only; page count must match the HTML
 ## Sign-off     — approved by: ___  date: ___  version: v1
 ```
+   Point the Screens section at the **real** HTML page range after render
+   (page 1 = sign · remaining sheets = screen appendix). Keep PROPOSAL.md and
+   `docs/proposal.html` in sync.
    If you keep an internal rate memo, put it in a **separate private** file (not
    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`:
-   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
-   it spills to a second page. Fill `{{COMPANY}}` / `{{COMPANY_TAGLINE}}` / `{{LOGO}}`
-   from the ISSUING company's brand declared in OVERVIEW (or ask once) — white-label,
-   never hardcode the kit's name. Leave `{{TOTAL_NOTE}}` empty or a non-rate line
+2. RENDER a client-facing `docs/proposal.html` from `.issflow/templates/proposal.html`
+   (Claude Code also mirrors this under `.claude/templates/` — same file). Copy it,
+   replace every `{{PLACEHOLDER}}`, and fill the CONTENT in the declared language
+   (the section labels are already bilingual TH / EN).
+
+   **Page 1 = the only signable A4 sheet.** Be terse (≈ 3–6 package rows, ≈ 4
+   assumptions, short scope items). If page 1 overflows A4, **trim the sign-page
+   copy first** — never spill the sign block onto page 2. The screen appendix may
+   grow extra `.sheet` pages.
+
+   Fill `{{PACKAGE_TABLE}}` with the matching header:
+   - default: ชุดงาน / Packages + Cost
+   - if hours columns requested: ประเมิน / คิดเงิน / ยอด (and EN equivalents)
+   Fill `{{BANK_COL}}` only when the human gave bank details; otherwise leave
+   empty so payment takes the full width.
+   Fill `{{COMPANY}}` / `{{COMPANY_TAGLINE}}` / `{{LOGO}}` from the ISSUING
+   company's brand declared in OVERVIEW (or ask once) — white-label, never
+   hardcode the kit's name. Leave `{{TOTAL_NOTE}}` empty or a non-rate line
    (e.g. currency / “ราคารวมทั้งโครงการ”) — **never** a contingency % or rate.
+   Set `{{PAGE_FOOTER}}` to the real page count (e.g. sign page 1 of N).
+
+   **Screen appendix (required when UI is in scope)** — same `docs/proposal.html`,
+   not a second signable file. After page 1's page-break, emit `.sheet.screens`
+   into `{{SCREEN_SHEETS}}`:
+   - Build frames from **PLAN + OVERVIEW** modules/capabilities (empty chrome is
+     fine). Do **not** wait for UX-PACK (that gate is after sign-off).
+   - Cover **every** in-scope module and capability — not a 4–8 frame sampler.
+   - Group sheets by package; module bar on each sheet; numbered short captions
+     under frames.
+   - Label: not pixel-binding. Sign on page 1 only. **No emoji as icons.**
+   - Use the template's desk/phone/sidebar/card/table CSS. Do not invent a
+     parallel stylesheet.
+
    Print-ready (Ctrl/Cmd-P → A4 → Save as PDF). Keep PROPOSAL.md and proposal.html
    in sync.
 
 ## STEP 6 — SIGN-OFF GATE
 Show me the proposal. **STOP for approval** (commercial gate — always interactive).
+Do **not** run `/design` or `/phase` yourself.
+
 On approval: record the approved version + date in PROPOSAL.md and STATE.md, and
 append a HISTORY line `proposal v<n> approved (<total>)`.
 

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.