create-issflow 1.6.0 → 1.8.0

package/README.md

@@ -7,14 +7,14 @@ and tool-agnostic. Non-destructive: it never overwrites your files.
 
 ```bash
 cd my-project
-npx create-issflow                  # prompts for your AI tool
-npx create-issflow --tool=claude    # or pass it: claude | codex | cursor | gemini | aider | all
-# then open your tool — Claude Code fires the SessionStart hook automatically
+npx create-issflow                  # omit --tool = install EVERY adapter
+npx create-issflow --tool=cursor    # claude | codex | cursor | gemini | aider | all
+# then open your tool and run:
 /overview                           # bootstrap the project
 ```
 
 Flags:
-- `--tool=<name>` — pick the target tool (skips the prompt). `all` writes every adapter.
+- `--tool=<name>` — pick the target tool. **Omit = `all`** (every adapter).
 - `--ci` — also write `.github/workflows/issflow-feature.yml` (headless `/feature`
   via GitHub Actions: label an issue `feature:approved` → the lane runs).
 - `--docker` — also write `Dockerfile.issflow` + `scripts/feature-docker.js`
@@ -31,20 +31,20 @@ Flags:
 The portable kit (every tool) in `<project>/.claude/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
-- `commands/` — `/overview` `/feature` `/propose` `/phase` `/sprint` `/ui-audit` `/qa-audit` `/security-audit` `/release` `/uat` `/change-request` `/replan` `/quick` `/synthesize` `/runbook` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
+- `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`
 - `skills/` — caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards
 - `hooks/` — session-start · context-guard · plan-gate (rule-13 enforcement) · pre-compact · subagent-stop · feature-gate (Stop gate for `/feature`, artifact-verified)
 - `istartsoft-flow/METHODOLOGY.md` — the full methodology (single source of truth)
 
-Plus a root `AGENTS.md` (the open standard) and the per-tool adapter:
+Plus a root **`AGENTS.md`** (open standard — primary entry) and the per-tool adapter:
 
 | Tool | Adds |
 |------|------|
-| `claude` | merges hooks into `.claude/settings.json` |
 | `codex` | nothing extra — `AGENTS.md` is read natively |
 | `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` |
 | `all` | every adapter above |
 
 It also un-ignores the workflow dirs in `.gitignore` if `.claude/*` was ignored.

package/bin/cli.js

@@ -40,7 +40,7 @@ function printHelp() {
 
 Usage: npx create-issflow [--tool=<name>] [--dry-run] [--force]
 
-Tools (--tool=, interactive prompt if omitted):`);
+Tools (--tool=). Omit --tool to install EVERY adapter (same as --tool=all):`);
   for (const [k, v] of Object.entries(TOOLS)) log(`  ${k.padEnd(7)} ${v}`);
   log(`
 Flags:
@@ -51,27 +51,22 @@ Flags:
   -h, --help  this message
 
 Every tool installs the portable kit in .claude/ + a root AGENTS.md (the open
-standard). The full methodology lives in .claude/istartsoft-flow/METHODOLOGY.md.`);
+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.`);
 }
 
-// Resolve the target tool: flag -> interactive (TTY) -> default 'claude'.
+// Typo / alias map → canonical TOOLS key
+const TOOL_ALIASES = { cusor: 'cursor' };
+
+// Resolve the target tool: --tool= flag → default 'all' when omitted.
 function pickTool() {
   if (toolArg) {
-    if (!TOOLS[toolArg]) { console.error(`create-issflow: unknown --tool=${toolArg}. One of: ${Object.keys(TOOLS).join(', ')}`); process.exit(1); }
-    return toolArg;
-  }
-  if (process.stdin.isTTY && process.stdout.isTTY && !DRY) {
-    const keys = Object.keys(TOOLS);
-    process.stdout.write('\nWhich AI coding tool? (the kit is portable — pick your primary)\n');
-    keys.forEach((k, i) => process.stdout.write(`  ${i + 1}) ${k} — ${TOOLS[k]}\n`));
-    process.stdout.write('> ');
-    let line = '';
-    try { line = (fs.readFileSync(0, 'utf8').split('\n')[0] || '').trim().toLowerCase(); } catch (_) {}
-    const chosen = TOOLS[line] ? line : keys[parseInt(line, 10) - 1];
-    if (!chosen) { console.error('create-issflow: no valid choice; defaulting to claude.'); return 'claude'; }
-    return chosen;
+    const key = TOOL_ALIASES[toolArg] || toolArg;
+    if (!TOOLS[key]) { console.error(`create-issflow: unknown --tool=${toolArg}. One of: ${Object.keys(TOOLS).join(', ')}`); process.exit(1); }
+    return key;
   }
-  return 'claude'; // non-interactive default = back-compatible
+  return 'all'; // omit --tool = every adapter
 }
 
 // write a single file, non-destructive (honors DRY/FORCE).
@@ -217,9 +212,9 @@ function agentsMd() {
     '## Roles — `.claude/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
-    '/overview · /feature · /propose · /phase · /sprint · /ui-audit · /qa-audit · /security-audit ·',
-    '/release · /uat · /change-request · /replan · /quick · /synthesize · /runbook · /store-wisdom ·',
-    '/log-issue · /log-decision · /unstuck', '',
+    '/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', '',
     '## Autonomy', '',
@@ -237,7 +232,9 @@ function agentsMd() {
     '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.', '',
+    '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).', '',
     '## Your stack', '',
     'Declare your stack (language, framework, infra, auth, test + E2E runner,',
     'planning source) once in `docs/OVERVIEW.md`. Every rule references *your declared',
@@ -318,7 +315,10 @@ function main() {
 
   // 3b. headless feature lane (opt-in): materialize the automation templates.
   const autoDir = path.join(TPL, '.claude', 'templates', 'automation');
-  if (CI) writeFile(path.join('.github', 'workflows', 'issflow-feature.yml'), fs.readFileSync(path.join(autoDir, 'issflow-feature.yml'), 'utf8'));
+  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'));
+  }
   if (DOCKER) {
     writeFile('Dockerfile.issflow', fs.readFileSync(path.join(autoDir, 'Dockerfile'), 'utf8'));
     writeFile(path.join('scripts', 'feature-docker.js'), fs.readFileSync(path.join(autoDir, 'feature-docker.js'), 'utf8'), { exec: true });
@@ -341,6 +341,7 @@ function main() {
   for (const w of warnings) log(`  ! ${w}`);
   log(NEXT_STEPS[TOOL] || NEXT_STEPS.claude);
   if (!CI && !DOCKER) log('Headless feature lane: re-run with --ci (GitHub Action) and/or --docker (container runner).');
+  log('New to the kit? Plain-language guide (EN/TH): https://iamstarter.github.io/istartsoftflow/how-to-use.html');
 }
 
 main();

package/package.json

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

package/template/.claude/agents/debugger.md

@@ -2,7 +2,7 @@
 name: debugger
 description: Diagnoses one specific failing test or bug in an ISOLATED context. Keeps debug noise out of the main session.
 tools: Read, Grep, Glob, Edit, Bash, Write
-model: opus
+model: inherit
 ---
 
 You are the DEBUGGER. Caveman ULTRA mode.

package/template/.claude/agents/e2e-runner.md

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

package/template/.claude/agents/implementer.md

@@ -2,7 +2,7 @@
 name: implementer
 description: Implements exactly one phase from docs/PLAN.md. Writes code only — no tests. On TDD phases runs in SCAFFOLD or FILL mode. Maintains docs/ENDPOINTS.md after each phase.
 tools: Read, Grep, Glob, Edit, Write, Bash
-model: opus
+model: inherit
 ---
 
 You are the IMPLEMENTER. Caveman ULTRA mode. Apply karpathy-guidelines skill.

package/template/.claude/agents/planner.md

@@ -2,7 +2,7 @@
 name: planner
 description: Turns research findings and OVERVIEW into a vertical-slice phase plan. Phase 0 (infra) leads only when infra is self-managed; with managed infra it is N/A. Last code phase always includes deployment. Writes docs/PLAN.md.
 tools: Read, Grep, Glob, Write
-model: opus
+model: inherit
 ---
 
 You are the PLANNER. Caveman ULTRA mode.

package/template/.claude/agents/researcher.md

@@ -2,7 +2,7 @@
 name: researcher
 description: Two-mode fact gathering. DESIGN mode: domain/constraint research before planning — discovers service limits, API contracts, architectural constraints. IMPL mode: codebase + service investigation during a phase. Always checks KB snapshot first. Always writes findings to docs/research/, returns only terse summary + path.
 tools: Read, Grep, Glob, Write, WebSearch, WebFetch
-model: haiku
+model: sonnet
 ---
 
 You are the RESEARCHER. Caveman ULTRA mode.

package/template/.claude/agents/test-author.md

@@ -2,7 +2,7 @@
 name: test-author
 description: Writes tests for a phase WITHOUT reading the implementation logic. On TDD phases, writes the suite BEFORE logic exists (RED-first). Tests behavior from the plan's acceptance spec only.
 tools: Read, Grep, Glob, Write, Bash
-model: opus
+model: inherit
 ---
 
 You are the TEST-AUTHOR. Caveman ULTRA mode. You write UNBIASED tests.

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

@@ -33,36 +33,57 @@ Is this an in-scope **clarification** (no cost change) or a real **scope change*
 (add / remove / alter)? Clarification -> log it, proceed, no re-price. Scope change
 -> continue.
 
+Also classify commercial lane:
+- **Warranty / defect** (bug vs approved scope, inside support window) → prefer
+  `/support` or `/quick` — not a billable CR unless the client expands scope.
+- **Billable CR** → continue below.
+
 ## STEP 2 — IMPACT ANALYSIS
 Determine:
 - phases affected — **done phases are frozen** (their cost is already spent and
   counts); new / changed phases; cut phases (credit back the un-started effort).
-- knock-on effects — architecture, **security (re-threat-model?)**, tests, timeline.
+- knock-on effects — architecture, **UX pack**, **security (re-threat-model?)**,
+  tests, timeline. If UX or arch artifacts change, those gates re-open (rule 15).
 - dispatch `researcher` (DESIGN or IMPL) if the change needs grounding in facts.
 
-## STEP 3 — RE-ESTIMATE (the DELTA only; reasonable + transparent)
-- Use the SAME estimation config as PROPOSAL.md (unit, rate card, currency,
-  contingency) — consistency is what makes the re-price defensible.
+## STEP 3 — RE-ESTIMATE (the DELTA only)
+- Reuse the SAME estimation config used for the approved proposal’s **internal**
+  math (unit, rate card, currency, contingency) if still available in a private
+  estimate memo or chat-recorded answers.
+- If rate / contingency is missing → **ASK once** (same rule as `/propose`). Never
+  invent a kit default rate; never commit personal rates into public kit files.
 - added effort × rate = added cost; cut effort = credit.
-- **net cost Δ** + **new total** vs the approved baseline — as a range + assumptions.
+- **net cost Δ** + **new total** vs the approved baseline — as a range.
+- Show rate math **in chat to the human only**.
 - **timeline Δ**. State what stays the SAME so the client sees the price is fair.
 
-## STEP 4 — LOG the change order to docs/CHANGES.md (append-only)
+### CLIENT-DOC RULE
+Anything the client sees (CR summary, updated PROPOSAL.md / proposal.html) shows
+**Δ cost + new total** (and effort/timeline) only — **never** rate, rate card, or
+contingency %.
+
+## STEP 4 — LOG the change order
+1. Append a one-line summary to `docs/CHANGES.md` (append-only):
 ```
 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:
+   classification, impact, Δ cost, warranty vs billable, status). Keep the detail
+   file client-safe on money fields (totals only).
 
 ## STEP 5 — APPROVAL GATE
-Show me CR-<n> (impact + price delta + new total). **STOP for approval** (commercial
-gate — always interactive).
+Show me CR-<n> (impact + price delta + new total — no rate). **STOP for approval**
+(commercial gate — always interactive).
 - **Approved** -> set CR status `approved`; bump PROPOSAL.md to a new version (vN+1)
-  with the delta folded in; re-render `docs/proposal.html` from it (same template +
-  language); 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 the plan sign-off, so `/phase` and
-  `/sprint` stay blocked until you also re-approve the revised plan.
+  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
+  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
+  the plan sign-off, so `/phase` and `/sprint` stay blocked until you also
+  re-approve the revised plan. If UX/arch scope changed, reset `design:` /
+  `architecture:` in STATE to PENDING (rule 15) before build resumes.
 - **Rejected** -> set CR status `rejected`; PLAN + PROPOSAL unchanged.
 
 ## STEP 6 — RECORD

package/template/.claude/commands/design.md

@@ -0,0 +1,51 @@
+---
+description: Post-proposal DESIGN + ARCHITECTURE gates — produce UX pack and architecture note, stop for human approve before /phase (hard rule 15).
+argument-hint: [optional: "ux" | "arch" | "both" · "dry-run"]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Purpose: after a **client proposal is signed** (or when the project opts into these
+gates), produce build-ready design + architecture artifacts and get human approve
+**before** `/phase` runs. Vertical slices still build UX+code together — these gates
+lock the *frame* first (model B).
+
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, outline what you'd write
+and STOP. Write nothing.
+
+## PRE-FLIGHT
+- Read `docs/OVERVIEW.md`, `docs/PLAN.md`, `docs/PROPOSAL.md` (if any), `docs/STATE.md`.
+- PLAN must be approved (rule 13). If a proposal exists for quoted work, it should
+  be signed off first (`/propose`) — otherwise warn and confirm they want design
+  gates without a commercial proposal (internal projects may skip `/propose` and
+  still run `/design`, or skip rule 15 entirely when STATE has `design: n/a` and
+  `architecture: n/a` set deliberately for non-quoted work).
+
+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`.
+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>`
+   in STATE.md; HISTORY line `design v<n> approved`.
+6. On change request: revise and re-show; header stays PENDING.
+
+## 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`.
+3. Apply `code-standards` architecture guidance; security trust boundaries via
+   `security` skill when relevant.
+4. SHOW me ARCHITECTURE.md. **STOP for approval.**
+5. On approve: stamp header; set `architecture: approved <date>` in STATE.md;
+   HISTORY line `architecture v<n> approved`. Optionally `/log-decision` for
+   material pattern choices.
+6. On change request: revise and re-show.
+
+## STEP 3 — HANDOFF
+When both required gates are approved (or N/A for internal skip):
+- Tell me `/phase` is unblocked for rule 15.
+- Reminder: frontend phases still run the `ux-design` CLOSE check (rule 9);
+  architecture drift still needs `/log-decision` (rule 8).

package/template/.claude/commands/feature.md

@@ -146,6 +146,12 @@ All slices done + full feature suite green -> check gate `build-green`.
 - Self-review: reread the diff against FEATURE.md acceptance criteria — every
   criterion maps to a test; every assumption still holds.
 - Run the regression corpus (`scripts/regression.sh`) + the full real suite.
+  No regression corpus in this repo (fresh brownfield install)? -> run the
+  project's OWN full test suite (the test command declared in OVERVIEW.md, or
+  the repo's obvious one — package.json test script, make test, pytest, …) and
+  note "corpus: n/a (brownfield)" in the summary. NOTHING runnable at all ->
+  that is a hard-stop: a feature cannot be verified green on a repo with no
+  tests; say so instead of pretending.
   Green -> check gates `review-harden` + `regression-green`.
 
 ## 7. MANUAL TEST PLAN

package/template/.claude/commands/goal.md

@@ -0,0 +1,77 @@
+---
+description: Goal layer — declare an OUTCOME, then let the kit drive lanes toward it until done, blocked, or budget spent. Goal-driven (stops on the outcome), not just time-driven like an interval loop.
+argument-hint: [set "<outcome>" · run [id] · status · done <id> · drop <id> · "dry-run"]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR. Goals live in `docs/GOALS.md`.
+
+A GOAL is bigger than one task: "clear the approved feature queue", "get the
+release candidate green", "close every open HIGH issue". The goal layer picks
+the next actionable unit, routes it through the RIGHT lane (METHODOLOGY → Lane
+routing), and repeats — with the same gates every lane already enforces.
+
+DRY-RUN: with `dry-run`, `/goal run` prints the pick-order + lanes it would fire
+and STOPS. `/goal set` always stops at the confirmation gate anyway.
+
+---
+
+## /goal set "<outcome>"
+
+1. UNDERSTAND-FIRST gate (hard rule 14) — BRIEF-BACK before writing anything:
+   - the outcome as YOU understand it, restated in one paragraph
+   - **Done when** — a measurable finish line (else the loop never terminates)
+   - scope / out-of-scope · assumptions · which lanes will likely fire
+   - **Budget** — max units per run (features/phases/quick fixes) so a runaway
+     goal cannot burn the wallet
+   STOP for explicit confirmation. Correction -> re-brief. Never skip this.
+2. On confirm, append to `docs/GOALS.md`:
+   ```
+   ## G<n> — <outcome> [active]
+   > Done when: <measurable condition>
+   > Budget: <max units per run / other caps>
+   > Approved: <name> <date>
+   ```
+   The `Approved:` line is what arms HEADLESS goal runs (same doctrine as the
+   feature lane: recorded consent, scoped to this goal).
+
+## /goal run [id]   (default: the single active goal)
+
+LOOP — repeat until a stop condition:
+1. PICK the next actionable unit, in this order:
+   a. an in-progress unit in STATE (finish what is started)
+   b. an APPROVED, pending `docs/features/*/FEATURE.md` that advances the goal
+   c. the next pending PLAN phase that advances the goal (plan must be approved — rule 13)
+   d. an open ISSUES.md item inside the goal's scope (route `/quick` or `/feature`)
+   Nothing actionable -> report + stop.
+2. ROUTE it through the lane-routing table (`/feature` · `/phase` · `/quick`).
+   The lane runs with ALL its own gates — the goal layer never bypasses one.
+3. TICK: append one line under the goal (`- [x] <unit> — <lane> — <result>`),
+   decrement budget, update STATE (`goal: G<n> (active — <units left>)`).
+4. CHECK "Done when". Met -> mark `[done]`, STATE `goal: G<n> (done)`, final
+   report (units shipped · parked blockers · budget used). Not met -> loop.
+
+STOP conditions (whichever first): Done-when met · budget spent · a lane
+hard-stop (surface it; headless: `BLOCKED.md` + clean exit) · nothing actionable.
+Every stop produces ONE consolidated report — never a silent end.
+
+## /goal status · /goal done <id> · /goal drop <id>
+
+Show goals + progress ticks · force-close (human says it's done) · abandon
+(log why). Both edits keep the history lines — GOALS.md is append-style memory.
+
+---
+
+## Recurrence (running a goal on a schedule)
+
+`/goal run` is one pass: it works until done/blocked/budget. To keep pressure on
+a long goal, re-fire the pass on a schedule — host-level, not kit-level:
+- **Claude Code web/desktop**: `/loop 30m /goal run` — the host's interval loop
+  re-invokes the pass; the goal layer supplies the state + finish line that a
+  bare interval loop lacks (it stops itself when Done-when is met).
+- **CI (headless)**: `create-issflow --ci` also installs
+  `.github/workflows/issflow-goal.yml` — a cron-ready workflow that runs
+  `/goal run` with `ISSFLOW_HEADLESS=1` (schedule commented out by default;
+  uncomment to arm). The `Approved:` line in GOALS.md is the recorded consent.
+- **Docker**: `node scripts/feature-docker.js` per feature stays the unit
+  runner; a goal pass inside a container is `claude -p "/goal run"` on the
+  same image (cron it with the scheduler you already have).

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

@@ -13,6 +13,8 @@ Canonical format:
 ### <short error title — searchable, literal error keywords>
 
 - [ ] open      (or “- [x] resolved” once fixed)
+- severity: P1 | P2 | P3   (optional; required when filed via /support)
+- commercial: warranty | billable | n/a
 - symptom: <what was observed>
 - root cause: <the REAL underlying cause>
 - solution: <exact fix, or “pending”>
@@ -26,5 +28,6 @@ Rules:
 - open issues use the empty box `- [ ]`; resolved are checked `- [x] resolved`
   (the SessionStart hook surfaces every `- [ ]` as open — keep the box empty until fixed).
 - open issues go at the TOP; resolved below; archived oldest at bottom.
+- For after-go-live tickets prefer `/support` first (triage), then this log.
 
 Confirm the entry back in 2 lines.

package/template/.claude/commands/overview.md

@@ -104,10 +104,14 @@ proceeds to the planner. (This is the planning confirmation gate.)
 
 phase: 0 (pending)
 plan: PENDING
+design: PENDING
+architecture: PENDING
 completed: project bootstrapped — design research done, double grill done
 blocker: none
 
 ```
+(For internal non-quoted work you may set `design: n/a` and `architecture: n/a`
+instead of PENDING so rule 15 does not block `/phase`.)
 8. Create docs/ISSUES.md with header `# Issues` and `## Archived` section.
 
 9. Create empty docs/HISTORY.md.
@@ -138,6 +142,9 @@ blocker: none
 
     AUTO governs the development loop that runs AFTER this gate, never the gate itself.
 
-Optional next step (client / quoted work only): run `/propose` to turn this
-OVERVIEW + PLAN into a proposal + estimate for sign-off before building. Internal or
-personal projects skip it and go straight to `/phase`.
+Optional next steps (client / quoted work):
+1. `/propose` — proposal + estimate (asks rate in chat; client docs stay totals-only).
+2. `/design` — UX pack + architecture approve gates (hard rule 15) before `/phase`.
+
+Internal or personal projects may skip `/propose` and set `design: n/a` /
+`architecture: n/a` in STATE, then go to `/phase`.

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

@@ -29,6 +29,16 @@ a. PLAN-APPROVAL CHECK (hard rule 13): Read the docs/PLAN.md `> Approval:` heade
    start. Route me to the `/overview` PLAN-APPROVAL gate (or `/replan` then re-approve).
    Approved -> continue.
 
+a2. DESIGN + ARCHITECTURE GATES (hard rule 15): Read `docs/STATE.md` for `design:`
+    and `architecture:`.
+    - Quoted / client work (approved `docs/PROPOSAL.md` exists): both must read
+      `approved <date>` (or explicit `n/a` only if the human waived the gate in
+      writing). Still PENDING / missing -> STOP. Route me to `/design`.
+    - Internal / no proposal: if STATE has `design: n/a` and `architecture: n/a`,
+      continue; if fields are missing, treat as n/a once (set them) unless OVERVIEW
+      opted into the gates.
+    Approved / n/a -> continue.
+
 b. INFRA CHECK (phases > 0): Read the declared infra in docs/OVERVIEW.md.
    - Managed infra -> confirm it is reachable; no provisioning step is needed.
    - Self-managed infra -> confirm Phase 0 (infra) ran and is healthy.

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

@@ -34,18 +34,37 @@ Derive the vertical-slice phases (or read `docs/PLAN.md` if it exists). Size eac
 - effort: an ideal-days RANGE (e.g. 2–3d), + story points if your team uses them
 - risk / unknowns: what could move the estimate
 
-## STEP 3 — ESTIMATE (flexible, transparent — no false precision)
-Read the **estimation config** from OVERVIEW (or ask once — a commercial/planning
-input, allowed). Everything is configurable; use sensible defaults if unset:
-- **unit:** ideal-days (default) | story-points | both.
-- **rate card:** a single blended rate, OR per-role rates (e.g. senior / mid /
-  junior). Cost = Σ(effort per role × that role's rate).
-- **currency:** as declared (THB default for a Thai project).
-- **contingency:** a % buffer for unknowns (default 10–15%).
-- **payment milestones:** by-phase, or a split (e.g. 30/40/30), or none.
-- **language:** the rendered doc's language (default = the project language).
-Compute cost per phase, then a **Total as a RANGE (low–high)** incl. contingency —
-show the math. **Timeline:** phases in dependency order → calendar estimate (note parallelism).
+## 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.
+
+1. Read estimation fields from OVERVIEW **only if the human already put them there
+   for this project** (unit, rate card, currency, contingency, milestones, language).
+2. If **rate card** or **contingency** is missing → **ASK once** in chat (commercial
+   input, allowed). Do not guess. Do not copy rates from other repos or prior chats
+   into kit files.
+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.
+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
+   - **language:** rendered doc language (default = project language)
+
+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**.
+**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.
 
 ## STEP 4 — ASSUMPTIONS & EXCLUSIONS
 List every assumption the estimate rests on (infra provided, third-party/licence
@@ -54,29 +73,41 @@ change-orders re-price against.
 
 ## STEP 5 — WRITE + RENDER
 1. Write `docs/PROPOSAL.md` — the SOURCE OF TRUTH (versioned v1 + date). This is
-   what `CHANGES.md` re-prices against. Template:
+   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
-## Total        — <low>–<high> (incl. <buffer>% contingency)
+## Total        — <low>–<high>   ← totals only; no “incl. X% contingency”
 ## Timeline     — <estimate>, dependency order
 ## Assumptions  — …
 ## Exclusions   — …
 ## Payment      — milestones (if any)
 ## Sign-off     — approved by: ___  date: ___  version: v1
 ```
+   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. Print-ready (Ctrl/Cmd-P → A4 → Save as PDF). Keep
-   PROPOSAL.md (source) and proposal.html (deliverable) in sync.
+   never hardcode the kit's name. Leave `{{TOTAL_NOTE}}` empty or a non-rate line
+   (e.g. currency / “ราคารวมทั้งโครงการ”) — **never** a contingency % or rate.
+   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).
 On approval: record the approved version + date in PROPOSAL.md and STATE.md, and
-append a HISTORY line `proposal v<n> approved (<total>)`. Building starts only after
-sign-off. On rejection: revise per feedback and re-show.
+append a HISTORY line `proposal v<n> approved (<total>)`.
+
+**Next (quoted / client work):** before `/phase`, run the **DESIGN + ARCHITECTURE
+gates** (METHODOLOGY lifecycle · hard rule 15) — produce `docs/UX-PACK.md` +
+`docs/ARCHITECTURE.md`, get human approve, stamp STATE. Building starts only after
+proposal sign-off **and** those gates (or explicit skip for internal non-quoted
+work). On rejection: revise per feedback and re-show.

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

@@ -21,11 +21,16 @@ If any fail -> STOP, tell me, recommend `/phase`.
 (Hard rule 10: never route phase-worthy work through `/quick` to dodge the RED gate.)
 
 Steps:
+0. UNDERSTAND-FIRST (hard rule 14): brief back in 2–3 lines — the change as you
+   understand it · file(s) you'll touch · blast radius — and WAIT for my confirm.
+   One cheap turn beats redoing a misunderstood edit. (Already confirmed in this
+   conversation? say so and proceed — don't re-ask the same understanding.)
 1. grep docs/ISSUES.md for anything related.
 2. Make the change. Smallest diff that works.
 3. Run it — lint/typecheck/smoke. Show me result.
-4. REGRESSION GUARD: run `scripts/regression.sh` (mock corpus). A break BLOCKS the
-   `/quick` — surface it to me and stop. No agent chain is added.
+4. REGRESSION GUARD: run `scripts/regression.sh` (mock corpus). No corpus in this
+   repo? run the project's own test suite instead (or the touched area's tests).
+   A break BLOCKS the `/quick` — surface it to me and stop. No agent chain is added.
 5. Error you cannot fix in 2 tries -> STOP. Recommend `/phase`.
 6. Change revealed a bug -> `/log-issue`.
 7. ARCHITECTURE SELF-CHECK: touched an agent, hook, command, or workflow rule?

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

@@ -49,7 +49,16 @@ sign-off** — a release gate, always interactive in both modes.
 On a SIGNED sign-off only: deploy to production, smoke-test prod (health 200), update
 `docs/ENDPOINTS.md` base URL, tag the release. HISTORY line: `released v<n> (<date>)`.
 
-## STAGE 8 — GO-LIVE & SUPPORT
-Enter after-go-live support (hypercare): watch for incidents, keep the issue log live.
-New scope → `/change-request` (impact + re-price + sign-off). The project is live; the
-loop continues through change requests.
+## STAGE 8 — GO-LIVE & SUPPORT (hypercare)
+Enter after-go-live support:
+
+1. **Watch** — incidents, error budgets, critical paths; keep `docs/ISSUES.md` live.
+2. **Front door** — route client/prod reports through `/support` (severity P1–P3,
+   warranty vs billable). Warranty defects → `/quick` (or larger lane); do not
+   silently expand scope for free.
+3. **New scope** → `/change-request` (impact + re-price + sign-off).
+4. **Ops memory** — update `/runbook` when a fix changes operational steps.
+5. Default warranty window if unset: **30 days** from this promote (STATE/HISTORY);
+   override from PROPOSAL assumptions when present.
+
+The project is live; the loop continues through `/support` and change requests.

package/template/.claude/commands/support.md

@@ -0,0 +1,43 @@
+---
+description: After-go-live support triage — severity, warranty vs billable CR, hotfix via /quick or route to /change-request. Use for bugs and issues in hypercare / warranty.
+argument-hint: [symptom or ticket summary · "dry-run"]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Purpose: handle production / post-release issues like a small software house —
+triage first, then fix under warranty or open a billable CR. Issue: $ARGUMENTS
+
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, print the triage plan and
+STOP. Log and fix nothing.
+
+Apply the `support-triage` skill.
+
+## PRE-FLIGHT
+Read `docs/PROPOSAL.md` (warranty / support assumptions if any), `docs/STATE.md`,
+`docs/ISSUES.md`, `docs/RUNBOOK.md` (if present), and recent HISTORY release lines.
+No live release yet → say so; may still log the issue for pre-prod.
+
+## STEP 1 — TRIAGE
+Brief-back (rule 14) then classify:
+
+| Field | Values |
+|-------|--------|
+| Severity | **P1** (down / data loss / security) · **P2** (major feature broken, workaround) · **P3** (minor / cosmetic) |
+| Type | defect vs approved scope · clarification · **new scope** |
+| Commercial | **warranty** (in support window, defect) · **billable** (out of window or new scope) · **unclear** (ask) |
+
+Default warranty window if unset in PROPOSAL/OVERVIEW: **30 days** after production
+promote (`released` HISTORY line). Ask once if the human wants a different window.
+
+## STEP 2 — ROUTE
+- **Warranty defect** → `/log-issue` (severity in title/symptom) → fix with `/quick`
+  (or `/phase` / `/feature` if phase-worthy — do not dodge TDD via quick for large
+  work, rule 10). P1: prioritize; note runbook updates via `/runbook` if ops-related.
+- **Billable / new scope** → `/change-request` (do not silently build free work).
+- **Unclear** → STOP and ask warranty vs billable before coding.
+
+## STEP 3 — CLOSE THE LOOP
+- Confirm ISSUES entry + HISTORY note `support P<n>: <title> → <route>`.
+- If fixed under warranty: mark issue resolved; no PROPOSAL bump.
+- Reminder: release STAGE 8 hypercare keeps ISSUES live; `/support` is the front door.

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

@@ -139,6 +139,8 @@ emit('  Hard-stops only: security / irreversible-or-outbound actions / contradic
 emit('- caveman ULTRA mode is active.');
 emit('- PLAN-APPROVAL gate (rule 13): no /phase or /sprint while STATE `plan:` reads');
 emit('  PENDING — the plan needs a human sign-off via /overview first.');
+emit('- UNDERSTAND-FIRST (rule 14): new free-text task -> brief back your understanding');
+emit('  (goal · scope · assumptions · blast radius) and WAIT for confirm before executing.');
 emit('- before debugging ANY error: grep ISSUES.md AND research/INDEX.md first.');
 emit('- debug attempts: WARN at 2; cap 3. AUTO: log + park the slice + continue (batched');
 emit('  report at the phase boundary). GUIDED: stop and ask you.');

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

@@ -106,34 +106,55 @@ from idea to closeout:
 5. **Proposal & estimate (OPTIONAL — depends on the job)** — for client / quoted
    work, `/propose` reads OVERVIEW + PLAN → `docs/PROPOSAL.md` + a rendered
    `docs/proposal.html`: scope, phase breakdown, effort + cost estimate, timeline,
-   assumptions, with a **client sign-off gate** before build. Internal / personal
-   projects skip straight from plan to build.
-6. **Build** — the loop, one phase at a time (`/phase`, AUTO dev loop). Each phase's
+   assumptions, with a **client sign-off gate** before build. **Ask rate +
+   contingency in chat** when missing — the kit stores **no** default rate (rates
+   are confidential). Client docs show **totals only** (never rate or contingency %).
+   Internal / personal projects skip straight from plan to build (and may set
+   design/architecture gates to `n/a`).
+6. **Design + architecture gates (rule 15 — after proposal, before build)** —
+   `/design` produces `docs/UX-PACK.md` + `docs/ARCHITECTURE.md` and stops for
+   human approve. Vertical slices still implement UI+code together; these gates
+   lock the *frame* first (software-house shape without abandoning slices).
+7. **Build** — the loop, one phase at a time (`/phase`, AUTO dev loop). Each phase's
    tests (unit + integration + e2e) are automated and MUST pass before the next phase.
    Optionally wrap the phases in the **sprint layer** (`/sprint`): group them into
    capacity-bounded sprints, each shipping one demoable increment with planning →
    standups → review → retro. `/sprint run` drives this end-to-end (see Sprint layer).
-7. **Change mid-flight** — `/change-request`: impact analysis + re-estimate + a logged
-   change order (`docs/CHANGES.md`) + sign-off, then `/replan`. Scope and cost never
-   change silently.
-8. **Release** — `/release`: full regression (functional/integration/e2e) → auto
+8. **Change mid-flight** — `/change-request`: impact analysis + re-estimate + a logged
+   change order (`docs/CHANGES.md` + `docs/changes/CR-<n>.md`) + sign-off, then
+   `/replan`. Scope and cost never change silently. Client-facing CR = Δ cost + new
+   total only.
+9. **Release** — `/release`: full regression (functional/integration/e2e) → auto
    audits (UI / QA / security / code) → smoke → **manual UAT** (`/uat`, scenario sheet
    + captured results) → defect loop → **sign-off** (`docs/SIGNOFF-…`) → promote to
    production (a human-signed hard-stop).
-9. **Go-live & support** — after-go-live hypercare; new scope routes through
-   `/change-request`. The project is live; the loop continues.
-10. **Closeout** — `/synthesize` → a project summary: what was built, key decisions,
+10. **Go-live & support** — hypercare + `/support` triage (severity, warranty vs
+    billable CR, hotfix via `/quick`). New scope → `/change-request`.
+11. **Closeout** — `/synthesize` → a project summary: what was built, key decisions,
     every change order, and the final cost vs the original estimate.
 
 **Logging is continuous and total.** Every stage writes to a durable artifact:
-requirements (PRD / OVERVIEW), commercial (PROPOSAL / CHANGES), execution
-(PLAN / HISTORY), decisions (DESIGN_LOG), errors (ISSUES), research (research/).
-Nothing important lives only in chat — it is on disk, so the project can always be
-reconstructed and summarised.
+requirements (PRD / OVERVIEW), commercial (PROPOSAL / CHANGES), design
+(UX-PACK / ARCHITECTURE), execution (PLAN / HISTORY), decisions (DESIGN_LOG),
+errors (ISSUES), research (research/). Nothing important lives only in chat — it
+is on disk, so the project can always be reconstructed and summarised.
 
 **Approval gates are always interactive** (both modes): the **PLAN-APPROVAL** gate
-(rule 13), the proposal sign-off, and every change-order approval pause for the human.
-AUTO governs the *dev loop between* those gates, never the plan or the money decisions.
+(rule 13), the proposal sign-off, **DESIGN + ARCHITECTURE** (rule 15), and every
+change-order approval pause for the human. AUTO governs the *dev loop between*
+those gates, never the plan, the money, or the design/arch frame.
+
+### Software-house roles → kit map
+
+| House role | Kit surface |
+|------------|-------------|
+| BA / PM | `/overview` grill · `grill-me` · PLAN / PROPOSAL / CR gates |
+| UX / UI | `/design` (UX pack) · `ux-design` skill · `/ui-audit` · rule 9 CLOSE |
+| Architect | `/design` (ARCHITECTURE) · `researcher` DESIGN · `code-standards` · `/log-decision` |
+| Developer | `implementer` · `/phase` · `/feature` · `/quick` |
+| QA | `test-author` · `e2e-runner` · `/qa-audit` · `/uat` |
+| DevOps | final-phase deploy · `/release` promote |
+| Support | `/support` · `/log-issue` · `/runbook` · release hypercare |
 
 -----
 
@@ -258,6 +279,20 @@ 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:` tier suited to its work, so the RIGHT model runs each task by default:
+
+| Role | `model:` | Why |
+|------|----------|-----|
+| planner · debugger · implementer · test-author | `inherit` | hardest reasoning — follows the session model the OWNER picked (`/model` / `--model`), so one choice cascades |
+| researcher · e2e-runner | `sonnet` | judgment-heavy but mid-tier is the sweet spot |
+| synthesizer | `haiku` | mechanical compression — cheapest tier |
+
+Owner wants a SPECIFIC model? Edit the role's `model:` line — values `haiku` ·
+`sonnet` · `opus` · `inherit` · or a full model id. The installer is
+non-destructive, so your pins survive kit updates. Hosts without per-agent model
+support run everything on the session model (graceful degrade).
+
 -----
 
 ## Procedures (the slash-command set)
@@ -266,12 +301,23 @@ Named procedures, each with a canonical body in `.claude/commands/<name>.md`.
 
 **Lane routing — which entry point for which job:**
 
+**Default paths** (most days — elevate these in HOW-TO / landing):
+
 | The job | Lane |
 |---------|------|
-| Brand-new project (no OVERVIEW yet) | `/overview` → `/phase` (optionally `/sprint`) |
+| Brand-new project (no OVERVIEW yet) | `/overview` → (`/propose` if quoted) → `/design` → `/phase` (optionally `/sprint`) |
 | New FEATURE on an existing product | `/feature` (scaffold the doc with `/feature new`) |
 | Small, obvious, non-phase change (a fix, a rename, a copy tweak) | `/quick` |
+
+**Advanced** (same kit — do not cut; use when the job needs them):
+
+| The job | Lane |
+|---------|------|
+| Client quote after plan approval | `/propose` (asks rate; client totals only) |
+| UX pack + architecture sign-off | `/design` (rule 15) |
 | Scope change to already-approved work | `/change-request` |
+| After-go-live bug / triage | `/support` |
+| An OUTCOME spanning several units ("clear the feature queue") | `/goal` (drives the lanes above) |
 | Whole-product quality sweep / pre-release | `/ui-audit` · `/qa-audit` · `/security-audit` · `/release` |
 
 On ambiguity between `/quick` and `/feature`: does it add or change a public
@@ -287,10 +333,22 @@ surface or need its own acceptance criteria? -> `/feature`. Otherwise `/quick`.
   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".
+- **goal [set|run|status|done|drop]** — the goal layer: declare an OUTCOME with a
+  measurable Done-when + budget (`set`, behind the rule-14 brief-back), then
+  `run` loops pick-next-unit → route lane → tick until done / budget / hard-stop.
+  Goal-driven, not time-driven: it stops itself on the finish line. Recurrence is
+  host-level (interval loop or the cron-ready `issflow-goal.yml`). `docs/GOALS.md`
+  holds state; its `Approved:` line arms headless passes.
 - **propose** — turn approved requirements + stack into `PROPOSAL.md` (scope, phase
   breakdown, effort + cost estimate, assumptions) with a client sign-off gate.
+  Asks rate/contingency in chat when missing; client artifacts are totals-only.
+- **design** — post-proposal UX pack + architecture note (`UX-PACK.md` /
+  `ARCHITECTURE.md`) with human approve (rule 15) before `/phase`.
 - **change-request** — a mid-project scope change: impact analysis + re-estimate +
-  a logged change order (`CHANGES.md`) + sign-off, then `replan`.
+  a logged change order (`CHANGES.md` + `docs/changes/CR-<n>.md`) + sign-off, then
+  `replan`. Client sees Δ cost + new total only.
+- **support** — after-go-live triage: severity P1–P3, warranty vs billable CR,
+  hotfix via `/quick` or route to `/change-request`.
 - **phase [n]** — run one phase end-to-end with the circuit breaker. Chooses the
   TDD or non-TDD order at RESEARCH. CLOSE runs the regression guard + ENDPOINTS
   coverage gate. When a sprint is active, CLOSE also fires a `/sprint standup` tick.
@@ -441,7 +499,7 @@ Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it
 
 -----
 
-## Hard rules (1–13)
+## Hard rules (1–15)
 
 1. Before debugging ANY error: grep `docs/ISSUES.md` AND `docs/research/INDEX.md`.
    The SESSION-OPEN ritual surfaces ISSUES.md — there is no excuse to miss it.
@@ -505,6 +563,24 @@ Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it
     the planning twin of the commercial sign-off gate (`/propose`). A `/replan` that
     adds or reshapes UNBUILT scope reverts the affected plan to `PENDING` and
     re-surfaces it for confirmation before those phases run.
+14. **UNDERSTAND-FIRST gate (brief-back).** No new task starts executing on an
+    unconfirmed understanding. Any command that takes free-text work (`/quick`,
+    `/change-request`, `/goal set`, the `/overview` grill) BRIEFS BACK first:
+    restate the task — goal · scope · out-of-scope · assumptions · plan sketch ·
+    blast radius — then WAIT for explicit confirmation before touching anything.
+    A recorded approval artifact IS the confirmation for its lane (approved
+    PLAN → phases · APPROVED FEATURE doc → the feature lane · approved CR → the
+    change · `Approved:` goal → goal runs) — that is exactly what arms headless.
+    Rationale: a wrong understanding burns tokens and context at 100× the cost
+    of one confirm turn. AUTO governs execution AFTER intake, never instead of it.
+15. **DESIGN + ARCHITECTURE gates.** After a client proposal is signed (quoted
+    work), no `/phase` / `/sprint` build starts until `docs/UX-PACK.md` and
+    `docs/ARCHITECTURE.md` carry human approval, recorded as `design:` /
+    `architecture:` in `docs/STATE.md` plus HISTORY lines. Run `/design` to
+    author and stop for sign-off. Internal / non-quoted projects may set both to
+    `n/a`. A CR that reshapes UX or architecture reverts the affected gate to
+    `PENDING`. Client-facing commercial docs never include rate cards or
+    contingency percentages (ask rates in chat; totals only on the page).
 
 -----
 
@@ -540,14 +616,17 @@ the KB. The kit works normally without a KB.
 ## File contract
 
 - `docs/PRD.md` — crystallised product requirements (or your BMAD/iSSM stories).
-- `docs/PROPOSAL.md` — scope + phase breakdown + effort/cost estimate + assumptions
-  + sign-off. Versioned; the commercial baseline (source of truth).
+- `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).
-- `.claude/templates/` — client-facing document templates (proposal.html, …) the
-  commands render into `docs/`.
+- `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,
+  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.
+- `docs/changes/CR-<n>.md` — detailed CR from `CR-template.md` (client-safe totals).
 - `docs/UAT-<date>.md` — UAT scenario sheet (all cases) + captured tester results
   (PASS/FAIL + notes). Drives the release defect loop.
 - `docs/SIGNOFF-<date>.md` — release sign-off: scope delivered, test/audit/UAT
@@ -561,13 +640,17 @@ 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 Action ·
+- `.claude/templates/automation/` — headless-runner sources (GitHub Actions ·
   Dockerfile · docker wrapper), materialized by `create-issflow --ci` /
-  `--docker` as `.github/workflows/issflow-feature.yml` · `Dockerfile.issflow` ·
-  `scripts/feature-docker.js`.
+  `--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`
   scaffolds (Approval/Automation headers + spec sections).
-- `docs/STATE.md` — current position. Small. Rewritten, not appended.
+- `docs/STATE.md` — current position. Small. Rewritten, not appended. Includes
+  `plan:`, `design:`, `architecture:` gate pointers (approved · PENDING · n/a).
 - `docs/ISSUES.md` — error log. Deduped by synthesizer.
 - `docs/PLAN.md` — the phase plan (the product backlog). Carries an `> Approval:`
   header — `PENDING` until the rule-13 PLAN-APPROVAL gate stamps `approved <date> v<n>`;

package/template/.claude/skills/support-triage/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: support-triage
+description: >
+  After-go-live issue triage for software-house support — severity P1–P3,
+  warranty vs billable CR, hotfix vs change-request routing. Use with /support,
+  production incidents, hypercare, client bug reports, or when classifying
+  whether a fix is free warranty work. Keywords: support, hypercare, warranty,
+  P1, severity, ticket, hotfix, aftercare, ซัพพอร์ต, รับประกัน.
+---
+
+# support-triage — post-release front door
+
+Caveman ULTRA mode. Triage before you code. Wrong commercial lane (free vs
+billable) is a process defect.
+
+## Severity
+
+| Level | Meaning | Response shape |
+|-------|---------|----------------|
+| **P1** | Service down, data loss, active security incident | Drop-everything; runbook; fix or mitigate now |
+| **P2** | Major feature broken; workaround exists | Same-day / next business day aim |
+| **P3** | Minor, cosmetic, nice-to-have | Queue; batch with other P3s |
+
+## Warranty vs billable
+
+- **Warranty:** defect against **approved** scope inside the support window
+  (default 30 days after prod `released` unless PROPOSAL/OVERVIEW says otherwise)
+  → log + `/quick` (or larger lane if needed) — **no** proposal bump.
+- **Billable:** new scope, enhancement, or outside window → `/change-request`.
+- **Unclear:** ask once; do not assume free work.
+
+## Routing checklist
+
+1. Reproduce / capture symptom (prefer client steps).
+2. Grep `docs/ISSUES.md` + runbook — known issue?
+3. Assign P1–P3 + warranty/billable.
+4. Route: support fix · CR · or escalate (infra / vendor).
+5. HISTORY line for the triage decision.
+
+Never put personal rate cards into public tickets or client emails from this skill.

package/template/.claude/skills/ux-design/SKILL.md

@@ -27,18 +27,23 @@ against the cookbook + wireframe and produces a UX CHECK verdict; nothing UI shi
 without it. New visual direction (a layout or look the wireframe doesn't cover) is
 confirmed with the user before building — design is where human taste matters.
 
+- **Authoring the UX pack** (`/design` → `docs/UX-PACK.md`) after proposal sign-off
+  and before `/phase` (hard rule 15) — produce the frame the build must stay inside.
 - Building a screen / page / component.
 - Reviewing a UI diff (the "ตรวจ" pass).
 - CLOSE gate of any frontend phase — the cookbook check MUST pass.
 
-This skill is the STANDARD + the inline GATE (one screen, at phase close). For a
-WHOLE-PRODUCT sweep against this same cookbook — periodic or before a release — run
-`/ui-audit` (same rubric, broader scope, a scored report).
+This skill is the STANDARD + the inline GATE (one screen, at phase close) **and**
+the authoring guide for the pre-build UX pack. For a WHOLE-PRODUCT sweep against
+this same cookbook — periodic or before a release — run `/ui-audit` (same rubric,
+broader scope, a scored report).
 
 Order: **wireframe first** (does the layout match the baseline frame?) ->
 **cookbook** (do the details obey the system?). Never invent layout the
 wireframe does not have. If the design truly needs a frame the wireframe lacks,
 STOP and update the wireframe baseline first (a design decision -> `log-decision`).
+When an approved `docs/UX-PACK.md` exists, treat it as the project frame — drift
+from the pack is a defect unless the pack is re-approved.
 
 -----
 

package/template/.claude/templates/ARCHITECTURE-template.md

@@ -0,0 +1,53 @@
+# Architecture — <project>
+
+> Approval: PENDING
+> (Stamp on sign-off: `approved <YYYY-MM-DD> v<n>` — hard rule 15)
+
+## Purpose
+Build-ready architecture note after commercial sign-off. Refines OVERVIEW stack
+into concrete boundaries the implementer follows per phase.
+
+## Context
+- OVERVIEW stack summary:
+- Constraints / non-goals:
+
+## Pattern
+- Declared architecture: Feature-Based (default) | layered | hexagonal | other:
+- Why this fits:
+
+## System diagram (text)
+```
+(clients) → (API / BFF) → (domain) → (data / external)
+```
+
+## Boundaries & modules
+| Module | Owns | Talks to |
+|--------|------|----------|
+| | | |
+
+## Data
+- Stores / schemas (high level):
+- Migrations approach:
+
+## Auth & trust boundaries
+- Authn / authz:
+- Secrets:
+- Threat notes (STRIDE if security-touching):
+
+## Integrations
+| Service | Use | Failure mode |
+|---------|-----|--------------|
+| | | |
+
+## Quality & ops
+- Test + E2E runners (from OVERVIEW):
+- Deploy target:
+- Observability / runbook hooks:
+
+## Decisions open
+-
+
+## Sign-off
+- Approved by: ___
+- Date: ___
+- Version: v1

package/template/.claude/templates/CR-template.md

@@ -0,0 +1,34 @@
+# CR-<n> — <short title>
+
+> Status: proposed | approved | rejected
+> Date: <YYYY-MM-DD>
+> Baseline: PROPOSAL v<n> | FEATURE `<slug>`
+
+## Classification
+- [ ] Clarification (no cost change)
+- [ ] Billable scope change (add / remove / alter)
+- [ ] Warranty defect (prefer `/support` / `/quick` — not billable unless scope expands)
+
+## Request
+<what the client / stakeholder asked>
+
+## Impact
+- Phases affected (done phases frozen):
+- UX pack impact: none | amend → re-approve (rule 15)
+- Architecture impact: none | amend → re-approve (rule 15)
+- Security re-threat-model?: no | yes
+- Timeline Δ:
+
+## Commercial (client-safe)
+| | |
+|--|--|
+| Effort Δ | <± range> |
+| Cost Δ | <± amount · currency> |
+| New total | <amount> |
+
+**Do not** put rate, rate card, or contingency % in this file if it is shared with
+the client. Show math with rates only in private chat / private estimate memo.
+
+## Decision
+- Approved by: ___ · Date: ___
+- Or rejected because:

package/template/.claude/templates/UX-PACK-template.md

@@ -0,0 +1,37 @@
+# UX pack — <project>
+
+> Approval: PENDING
+> (Stamp on sign-off: `approved <YYYY-MM-DD> v<n>` — hard rule 15)
+
+## Purpose
+Hi-fi-enough UI direction for build: screens, flows, and frame the implementer
+must stay inside. Wireframe baseline first; visual direction confirmed here.
+
+## Users & jobs
+-
+
+## Key flows
+1.
+2.
+
+## Screen inventory
+| Screen | Job | Priority |
+|--------|-----|----------|
+| | | |
+
+## Frame & tokens
+- Wireframe baseline: (link or summary)
+- Brand / tokens: (or “follow OVERVIEW UX direction”)
+- Breakpoints: XS · SM · MD · LG · XL
+
+## States & a11y notes
+- Empty / loading / error covered for each primary view
+- WCAG 2.1 AA targets
+
+## Out of scope (design)
+-
+
+## Sign-off
+- Approved by: ___
+- Date: ___
+- Version: v1

package/template/.claude/templates/automation/Dockerfile

@@ -28,6 +28,10 @@ RUN useradd --create-home --shell /bin/sh runner
 USER runner
 WORKDIR /work
 
+# the mounted repo is owned by the HOST uid, not `runner` — without this every
+# git command fails with "detected dubious ownership in repository".
+RUN git config --global --add safe.directory '*'
+
 # headless marker — /feature degrades every hard-stop to a BLOCKED report + clean exit.
 ENV ISSFLOW_HEADLESS=1
 

package/template/.claude/templates/automation/feature-docker.js

@@ -82,16 +82,17 @@ if (useWorktree) {
   console.log(`feature-docker: parallel lane — this run is isolated in ${wt}; your checkout stays untouched.`);
 }
 
-console.log(`feature-docker: running /feature ${doc} in ${IMAGE} (repo mounted at /work)`);
-const args = [
-  'run', '--rm',
-  '--entrypoint', 'claude',
-  '-v', `${mountDir}:/work`, '-w', '/work',
-];
-// a worktree's .git is a FILE pointing at the main repo's .git by absolute host
-// path — mount the main repo at that same path so git resolves inside the
-// container. (Path-identical mounts: Linux/macOS; on Windows use the default mode.)
-if (useWorktree) args.push('-v', `${repo}:${repo}`);
+console.log(`feature-docker: running /feature ${doc} in ${IMAGE}`);
+const args = ['run', '--rm', '--entrypoint', 'claude'];
+if (useWorktree) {
+  // a worktree's git metadata references BOTH trees by absolute HOST path
+  // (.git file -> main .git/worktrees/<n>; gitdir file -> back to the worktree).
+  // Mount both at their host paths so every pointer resolves in-container.
+  // (Path-identical mounts: Linux/macOS; on Windows use the default mode.)
+  args.push('-v', `${repo}:${repo}`, '-v', `${mountDir}:${mountDir}`, '-w', mountDir);
+} else {
+  args.push('-v', `${mountDir}:/work`, '-w', '/work');
+}
 args.push(
   '-e', 'ANTHROPIC_API_KEY',
   '-e', 'ISSFLOW_HEADLESS=1'

package/template/.claude/templates/automation/issflow-feature.yml

@@ -66,9 +66,10 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
           prompt: "/feature ${{ env.FEATURE_DOC }}"
-          # Ephemeral runner = the sandbox; the Stop hook (feature-gate.js) still
-          # enforces the gate checklist inside the run.
-          claude_args: "--dangerously-skip-permissions"
+          # Broad allowlist via the documented --allowedTools flag (the ephemeral
+          # runner is the sandbox). The Stop hook (feature-gate.js) still enforces
+          # the gate checklist inside the run.
+          claude_args: "--allowedTools Bash,Edit,Write,Read,Glob,Grep,Task,WebFetch,WebSearch,TodoWrite"
 
       # The lane's own delivery step (git push / PR) runs inside Claude per the
       # doc's `> Automation:` header. This job only reports.

package/template/.claude/templates/automation/issflow-goal.yml

@@ -0,0 +1,48 @@
+# iStartSoftFlow — scheduled goal pass (GitHub Actions).
+# Installed by `npx create-issflow --ci` as .github/workflows/issflow-goal.yml.
+#
+# Runs ONE `/goal run` pass headless: pick next actionable unit -> route lane ->
+# tick -> repeat until Done-when / budget / hard-stop. The goal's `> Approved:`
+# line in docs/GOALS.md is the recorded consent that arms the run; a lane
+# hard-stop writes BLOCKED.md and exits cleanly. It never merges, never deploys.
+#
+# DISARMED BY DEFAULT: uncomment `schedule:` to run on cron. Manual dispatch
+# always works. Setup: secret ANTHROPIC_API_KEY + Actions write permissions
+# (same as issflow-feature.yml).
+
+name: issflow-goal
+
+on:
+  workflow_dispatch:
+    inputs:
+      goal_id:
+        description: Goal id to run (blank = the single active goal)
+        required: false
+        type: string
+  # schedule:
+  #   - cron: '0 1 * * 1-5'   # 01:00 UTC weekdays — one pass per night
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  goal:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run one goal pass
+        uses: anthropics/claude-code-action@v1
+        env:
+          ISSFLOW_HEADLESS: "1"
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: "/goal run ${{ inputs.goal_id }}"
+          # Documented --allowedTools flag; the ephemeral runner is the sandbox.
+          claude_args: "--allowedTools Bash,Edit,Write,Read,Glob,Grep,Task,WebFetch,WebSearch,TodoWrite"

package/template/.claude/templates/proposal.html

@@ -91,7 +91,8 @@
 
   <div class="total">
     <span><span class="lbl" style="margin:0">ราคารวม <em>Total</em></span><br><span class="muted" style="font-size:9px">{{TIMELINE}}</span></span>
-    <span class="amt">{{TOTAL_COST}} <small>{{CONTINGENCY_NOTE}}</small></span>
+    <!-- CLIENT-SAFE: totals only. Never put rate, rate card, or contingency % in {{TOTAL_NOTE}}. Leave empty or a non-rate label (e.g. currency). -->
+    <span class="amt">{{TOTAL_COST}} <small>{{TOTAL_NOTE}}</small></span>
   </div>
 
   <div class="cols">