create-issflow 1.5.0 → 1.7.0

package/README.md

@@ -15,6 +15,12 @@ npx create-issflow --tool=claude    # or pass it: claude | codex | cursor | gemi
 
 Flags:
 - `--tool=<name>` — pick the target tool (skips the prompt). `all` writes 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`
+  (headless `/feature` in an unprivileged container; the container is the sandbox).
+  The image must ship Node ≥ 18 — the kit's hooks are Node scripts; the shipped
+  Dockerfile is Node-based and the wrapper preflights `node` before every run.
 - `--dry-run` — print what would happen, write nothing.
 - `--force` — overwrite existing kit files (default keeps yours; conflicts are
   written as `<file>.issflow-new` for you to merge).
@@ -25,9 +31,9 @@ Flags:
 The portable kit (every tool) in `<project>/.claude/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
-- `commands/` — `/overview` `/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 · pre-compact · subagent-stop
+- `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:

package/bin/cli.js

@@ -15,6 +15,8 @@ const CWD = process.cwd();
 const argv = process.argv.slice(2);
 const DRY = argv.includes('--dry-run');
 const FORCE = argv.includes('--force');
+const CI = argv.includes('--ci');
+const DOCKER = argv.includes('--docker');
 const HELP = argv.includes('-h') || argv.includes('--help');
 const toolArg = (argv.find(a => a.startsWith('--tool=')) || '').split('=')[1];
 
@@ -42,6 +44,8 @@ Tools (--tool=, interactive prompt if omitted):`);
   for (const [k, v] of Object.entries(TOOLS)) log(`  ${k.padEnd(7)} ${v}`);
   log(`
 Flags:
+  --ci        also write .github/workflows/issflow-feature.yml (headless /feature via GitHub Actions)
+  --docker    also write Dockerfile.issflow + scripts/feature-docker.js (headless /feature in a container)
   --dry-run   print what would happen, write nothing
   --force     overwrite existing kit files (default keeps yours -> <file>.issflow-new)
   -h, --help  this message
@@ -121,9 +125,11 @@ function adapterClaude() {
   writeFile('.claude/flow-config.json', flowConfig());
   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' }] }],
+    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' }] }],
   };
   const sp = path.join(CWD, '.claude', 'settings.json');
   let settings = {};
@@ -211,9 +217,9 @@ function agentsMd() {
     '## Roles — `.claude/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
-    '/overview · /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', '',
@@ -231,7 +237,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',
@@ -310,6 +318,17 @@ function main() {
   // 3. per-tool adapters
   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');
+  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 });
+  }
+
   // 4. .gitignore: track the workflow dirs if .claude/* is ignored
   const gi = path.join(CWD, '.gitignore');
   if (fs.existsSync(gi)) {
@@ -326,6 +345,8 @@ function main() {
   if (conflicts) log('Review *.issflow-new files and merge manually (your originals were untouched).');
   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.5.0",
+  "version": "1.7.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

@@ -18,6 +18,16 @@ Read `docs/PROPOSAL.md` (the approved baseline), `docs/PLAN.md`, `docs/STATE.md`
 and `docs/CHANGES.md` (create if missing). No approved proposal yet -> you're still
 pre-build; use `/propose` instead.
 
+**FEATURE-LANE VARIANT** — the change targets a feature-lane run (STATE has a
+`feature: <slug>` line, or `/feature` hard-stopped here on scope creep): the
+baseline is the APPROVED `docs/features/<slug>/FEATURE.md`, not the proposal.
+Run the same steps against the doc — impact on its slices, effort Δ if the
+project prices work — then log the CR and **amend the FEATURE doc** (scope +
+acceptance criteria) and reset its header to `> Approval: PENDING`: a changed
+doc needs a fresh human approval before the lane re-arms. Skip the PROPOSAL/
+plan-replan steps unless the change spills beyond the feature. No proposal in
+this project is fine for this variant — the feature doc is the commercial unit.
+
 ## STEP 1 — CLASSIFY
 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

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

@@ -0,0 +1,206 @@
+---
+description: Feature lane — one APPROVED Feature doc in, a tested + hardened + documented feature branch out. Near-100% hands-off; humans remain at doc approval, UAT, and merge. Runs interactive or headless (CI / Docker).
+argument-hint: [path to Feature doc, e.g. docs/features/<slug>/FEATURE.md · "dry-run"]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
+you do NOT implement or debug yourself. Subagents cannot talk to the user; only YOU can.
+
+Target doc: $ARGUMENTS  (default: the single `docs/features/*/FEATURE.md` whose
+`> Status:` reads `approved, pending` — zero or multiple candidates -> STOP and list them.)
+
+---
+
+## ENTRY MODES (before the pipeline)
+
+- **`/feature new <name>`** — scaffold only. Copy
+  `.claude/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
+  connected (e.g. iSSM `load_story`), load the story and transform it into the
+  template's sections (story intent -> What & why, ACs -> Acceptance criteria,
+  the rest mapped or left as explicit gaps). Write it as `Approval: PENDING` and
+  STOP for human review + approval — a story is planning input, not a sign-off.
+  No story MCP connected -> say so and fall back to `/feature new`.
+- **`/feature <path>`** (or bare `/feature`) — run the pipeline below.
+
+HEADLESS DETECT: env `ISSFLOW_HEADLESS=1` (set by the CI workflow / Docker runner)
+means NO human is available this run. Every hard-stop below then degrades to:
+write the blocker to `docs/features/<slug>/BLOCKED.md` + mark the gate `parked`
++ EXIT cleanly with a report. Never guess through a hard-stop.
+
+---
+
+## DRY-RUN CHECK (first)
+
+`$ARGUMENTS` contains `dry-run` -> full analysis, EXECUTE NOTHING. Print the
+ACTION PLAN (files · agents · tests/gates · branch · delivery target) then STOP.
+
+---
+
+## 0. INTAKE + PRE-FLIGHT
+
+a. BROWNFIELD CHECK: `docs/OVERVIEW.md` must exist — the feature lane extends an
+   EXISTING product. Missing -> STOP; route to `/overview` (greenfield lane).
+
+b. APPROVAL GATE (the ONE human gate at entry): the Feature doc must carry a header
+   ```
+   > Approval: APPROVED <name> <date>
+   > 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
+   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.
+
+c. WORKSPACE: slug = kebab-case of the doc's title. Ensure
+   `docs/features/<slug>/FEATURE.md` (move the doc there if given elsewhere).
+   Write `docs/features/<slug>/GATES.md` — the gate checklist, all unchecked:
+   ```
+   # GATES — <slug>
+   - [ ] spec-complete
+   - [ ] adversarial-doc-review
+   - [ ] mini-plan
+   - [ ] contract-probe
+   - [ ] build-green
+   - [ ] review-harden
+   - [ ] regression-green
+   - [ ] test-plan
+   - [ ] docs-updated
+   - [ ] token-stamp
+   - [ ] summary
+   - [ ] memory-queued
+   ```
+   The `Stop` hook (`feature-gate.js`) BLOCKS session end while any gate is
+   unchecked — check each box the moment its step truly passes, never earlier.
+   Aborting legitimately: set `feature: <slug> (parked — <reason>)` in STATE.md.
+
+d. STATE + BRANCH: `docs/STATE.md` gets `feature: <slug> (active)`. Work on
+   branch `feature/<slug>` (create from the default branch if needed). Never the
+   default branch.
+
+---
+
+## 1. PREPARATION & SPEC COMPLETION
+
+Dispatch `researcher` (IMPL mode) scoped to the doc: which modules/files the
+feature touches, which dependencies + versions are involved, what the doc leaves
+unstated. Fill every gap with the most reasonable interpretation and log each one
+under `## Assumptions` in FEATURE.md (AUTO decision protocol — decide + log +
+continue). Check gate `spec-complete`.
+
+## 2. ADVERSARIAL DOC-REVIEW (before planning)
+
+Dispatch TWO reviewers in parallel, each told to ATTACK the doc, not summarize it:
+- correctness lens: contradictions, missing edge cases, undefined behaviour,
+  hidden scope, unstated integrations.
+- security lens: does the feature cross a TRUST BOUNDARY (auth, untrusted input,
+  data store, money, PII)? If yes, threat-model it now (`security` skill) and fold
+  abuse cases into the acceptance criteria as negative cases.
+
+Merge findings into FEATURE.md `## Acceptance criteria` (positive + negative).
+Internally CONTRADICTORY spec -> HARD-STOP (methodology hard-stop 3). Merely
+incomplete -> fill + log. Check gate `adversarial-doc-review`.
+
+## 3. MINI-PLAN
+
+Dispatch `planner` scoped to the doc -> `docs/features/<slug>/PLAN.md`: 1–3
+VERTICAL slices, each with acceptance spec + `[N pts]`. The main `docs/PLAN.md`
+is NOT touched — the feature lane is self-contained. If the plan cannot fit the
+doc's stated scope (planner needs work the doc never mentions) -> HARD-STOP:
+that is scope creep; route to `/change-request`. Check gate `mini-plan`.
+
+## 4. CONTRACT SURFACE PROBE
+
+Before any test is written: enumerate every public surface the feature ADDS or
+CHANGES — endpoints, exported functions/classes, CLI commands, events, schemas.
+Diff against `docs/ENDPOINTS.md` + the existing types. Write
+`docs/features/<slug>/CONTRACTS.md`: exact signatures, request/response shapes,
+error shapes. A changed EXISTING contract is a breaking change -> list every
+caller + the migration in CONTRACTS.md. This file is what test-author asserts
+against. Check gate `contract-probe`.
+
+## 5. BUILD LOOP (per slice — the /phase machinery, feature-scoped)
+
+For each slice in `docs/features/<slug>/PLAN.md`, in order:
+- TDD APPLICABILITY per the methodology (default `TDD_PHASE=true`, log the call).
+- TDD slice: SCAFFOLD (implementer, stubs from CONTRACTS.md) -> RED (`test-author`,
+  BLIND — reads FEATURE.md acceptance criteria + CONTRACTS.md only, never the
+  implementation) -> GREEN (`implementer`) -> e2e (`e2e-runner`) when the slice has
+  a user-facing flow. Non-TDD slice: IMPLEMENT -> TEST.
+- Debug circuit breaker: WARN at 2, cap 3, `/unstuck` once per slice; still stuck
+  -> park the slice (BLOCKED in the feature PLAN) + continue to the next
+  independent slice. Blockers batch-report at the end, never mid-flow.
+- Rule 11 (secure coding + SAST/SCA/secrets) and rule 12 (lint/format/naming/
+  architecture) apply per slice as in `/phase`.
+- `implementer` updates `docs/ENDPOINTS.md` as surfaces land.
+
+All slices done + full feature suite green -> check gate `build-green`.
+
+## 6. REVIEW & HARDEN (adversarial + self-review)
+
+- Dispatch TWO reviewers against the full feature diff: correctness lens +
+  security lens. CONFIRMED findings -> fix loop, capped at 2 rounds; leftovers
+  are logged in ISSUES.md, severity-tagged; any HIGH leftover -> HARD-STOP.
+- 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
+
+Write `docs/features/<slug>/TEST-PLAN.md` — an all-case scenario sheet a human
+tester can run without reading code: happy paths, negative cases, edge cases,
+per-scenario steps + expected results, in the project language (OVERVIEW). Same
+format `/uat` consumes, so the sheet plugs straight into the UAT cycle.
+Check gate `test-plan`.
+
+## 8. DOCS + STAMPS + MEMORY
+
+a. Documentation update: `docs/ENDPOINTS.md` final pass; README/docs deltas the
+   feature makes stale. Check gate `docs-updated`.
+b. Token stamp — append to FEATURE.md:
+   ```
+   ## Token stamp
+   context: ~<pct>% of window · subagents: <n> · slices: <n> · debug rounds: <n>
+   ```
+   Check gate `token-stamp`.
+c. Summary — append to FEATURE.md `## Summary`: what shipped, assumptions made,
+   parked blockers, contract changes. One line to `docs/HISTORY.md`.
+   Check gate `summary`.
+d. Memory update — append wisdom candidates (resolved issues, reusable findings)
+   to `docs/WISDOM-QUEUE.md`. The QUEUE is local + automatic; pushing to the
+   shared KB stays human (`/store-wisdom` reads the queue). Check gate `memory-queued`.
+
+Then: STATE.md -> `feature: <slug> (done)`.
+
+## 9. DELIVERY
+
+Commit the feature branch (clear message per slice or one squashed commit).
+Then by the doc's `> Automation:` header:
+- `none` (default) -> STOP here. Show the human: branch name, summary, TEST-PLAN
+  path. Push is theirs (methodology hard-stop 1).
+- `push` -> push `feature/<slug>` (`git push -u origin feature/<slug>`). No PR.
+- `push+pr` -> push + open a PR to the default branch. PR body = FEATURE.md
+  Summary + link to TEST-PLAN.md. NEVER merge. NEVER deploy. Merge and prod
+  stay human, always.
+
+Final report (interactive: to the user · headless: as the run's closing output):
+gates table · parked blockers · assumptions · branch/PR · "next: run /uat with
+docs/features/<slug>/TEST-PLAN.md".
+
+---
+
+## What stays human (by design — do not automate these away)
+
+1. Writing + APPROVING the Feature doc (entry gate).
+2. Any hard-stop: contradictory spec · scope creep · HIGH security finding.
+3. UAT against TEST-PLAN.md, and the merge.
+4. Production deploy — never in this lane; that is `/release`.

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/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/hooks/feature-gate.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Stop hook — the feature-lane gate. While a /feature run is active
+// (docs/STATE.md has `feature: <slug> (active)`), the session may not end
+// with unchecked gates in docs/features/<slug>/GATES.md — and a CHECKED gate
+// whose artifact is verifiable must have the artifact on disk (a ticked box
+// with no TEST-PLAN.md behind it is treated as unchecked). Suites staying
+// green is still proven by the steps themselves; this hook proves the
+// deliverables exist. Pure Node, cross-platform, zero deps.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+try { process.chdir(process.env.CLAUDE_PROJECT_DIR || '.'); } catch (_) {}
+
+const allow = () => process.exit(0);
+const block = (reason) => { process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n'); process.exit(0); };
+const read = (f) => { try { return fs.readFileSync(f, 'utf8'); } catch (_) { return null; } };
+
+// stdin: hook input JSON. stop_hook_active=true means we already blocked once
+// this stop — allow through to avoid an infinite block loop.
+let input = {};
+try { input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); } catch (_) {}
+if (input.stop_hook_active) allow();
+
+const state = read(path.join('docs', 'STATE.md'));
+if (!state) allow();
+
+// an ACTIVE feature arms the full gate; a DONE feature still gets artifact
+// verification (done-with-fake-gates must not slip through by never stopping
+// while active). `(parked — reason)` disarms entirely.
+const mActive = state.match(/^\s*feature:\s*([A-Za-z0-9._-]+)\s*\(active\)/m);
+const mDone = state.match(/^\s*feature:\s*([A-Za-z0-9._-]+)\s*\(done\)/m);
+const m = mActive || mDone;
+if (!m) allow();
+const slug = m[1];
+const isDone = !mActive;
+
+const gates = read(path.join('docs', 'features', slug, 'GATES.md'));
+if (!gates) block(
+  `Feature "${slug}" is active in docs/STATE.md but docs/features/${slug}/GATES.md is missing. ` +
+  `Recreate the gate checklist (see /feature step 0c), or park the run: set ` +
+  `"feature: ${slug} (parked — <reason>)" in docs/STATE.md.`
+);
+
+const open = gates.split('\n').filter((l) => /^\s*- \[ \]/.test(l)).map((l) => l.replace(/^\s*- \[ \]\s*/, '').trim());
+const checked = gates.split('\n').filter((l) => /^\s*- \[[xX]\]/.test(l)).map((l) => l.replace(/^\s*- \[[xX]\]\s*/, '').trim());
+
+// artifact verification — a checked gate must have its deliverable on disk.
+const fdir = path.join('docs', 'features', slug);
+const featureDoc = read(path.join(fdir, 'FEATURE.md')) || '';
+const ARTIFACTS = {
+  'mini-plan':      () => fs.existsSync(path.join(fdir, 'PLAN.md')) || `docs/features/${slug}/PLAN.md is missing`,
+  'contract-probe': () => fs.existsSync(path.join(fdir, 'CONTRACTS.md')) || `docs/features/${slug}/CONTRACTS.md is missing`,
+  'test-plan':      () => fs.existsSync(path.join(fdir, 'TEST-PLAN.md')) || `docs/features/${slug}/TEST-PLAN.md is missing`,
+  'token-stamp':    () => /^##\s*Token stamp/mi.test(featureDoc) || `FEATURE.md has no "## Token stamp" section`,
+  'summary':        () => /^##\s*Summary/mi.test(featureDoc) || `FEATURE.md has no "## Summary" section`,
+  'memory-queued':  () => fs.existsSync(path.join('docs', 'WISDOM-QUEUE.md')) || `docs/WISDOM-QUEUE.md is missing`,
+};
+const fake = [];
+for (const g of checked) {
+  const check = ARTIFACTS[g];
+  if (!check) continue;
+  const r = check();
+  if (r !== true) fake.push(`${g} (${r})`);
+}
+if (fake.length) block(
+  `Feature "${slug}": ${fake.length} gate(s) are checked but their artifacts do not exist — ` +
+  `${fake.join(' · ')}. A gate is done when its deliverable is on disk, not when the box is ticked. ` +
+  `Produce the artifact(s) (see /feature), or untick the gate(s) and finish the step.`
+);
+
+if (isDone) {
+  if (open.length) block(
+    `Feature "${slug}" is marked (done) in docs/STATE.md but GATES.md still has ` +
+    `${open.length} unchecked gate(s): ${open.join(' · ')}. Finish them, or set the state ` +
+    `to "feature: ${slug} (active)" / "(parked — <reason>)" to reflect reality.`
+  );
+  allow();
+}
+
+if (open.length === 0) block(
+  `Feature "${slug}": all gates are checked but docs/STATE.md still says (active). ` +
+  `Finish the close-out: set "feature: ${slug} (done)" in docs/STATE.md (/feature step 8).`
+);
+
+block(
+  `Feature "${slug}" has ${open.length} unchecked gate(s): ${open.join(' · ')}. ` +
+  `Finish those steps and tick each box in docs/features/${slug}/GATES.md, ` +
+  `or park the run: set "feature: ${slug} (parked — <reason>)" in docs/STATE.md ` +
+  `and record the blocker in docs/features/${slug}/BLOCKED.md.`
+);

package/template/.claude/hooks/plan-gate.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// PreToolUse plan gate — hard rule 13 as code. While docs/PLAN.md carries
+// `> Approval: PENDING`, no SOURCE file may be created or edited: the plan
+// needs a human sign-off before build work starts. Docs, kit config, and
+// planning artifacts stay writable (planning is exactly what PENDING is for).
+// An active feature lane is exempt — its doc approval is its own rule-13-scoped
+// gate and it never touches the main PLAN. Fail-OPEN on any error: a hook bug
+// must never wedge the tool loop. Pure Node, cross-platform, zero deps.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const silent = () => process.exit(0);
+const deny = (reason) => {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: reason },
+  }));
+  process.exit(0);
+};
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (d) => (input += d));
+process.stdin.on('end', () => {
+  let evt;
+  try { evt = JSON.parse(input); } catch (_) { return silent(); }
+  try { run(evt); } catch (_) { silent(); }
+});
+
+function run(evt) {
+  const MUTATORS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+  if (!MUTATORS.has(evt.tool_name || '')) return silent();
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || evt.cwd || '.';
+  const read = (f) => { try { return fs.readFileSync(path.join(projectDir, f), 'utf8'); } catch (_) { return null; } };
+
+  const plan = read(path.join('docs', 'PLAN.md'));
+  if (!plan) return silent();                              // no plan world (e.g. /quick-only repo)
+  const approval = plan.match(/^>\s*Approval:\s*(.+)$/m);
+  if (!approval) return silent();                          // not our PLAN format — don't guess
+  if (!/pending/i.test(approval[1])) return silent();      // signed off — build away
+
+  // the feature lane carries its own scoped approval and never edits the main PLAN.
+  const state = read(path.join('docs', 'STATE.md')) || '';
+  if (/^\s*feature:\s*\S+\s*\(active\)/m.test(state)) return silent();
+
+  const file = String((evt.tool_input || {}).file_path || (evt.tool_input || {}).notebook_path || '');
+  if (!file) return silent();
+  const rel = path.relative(projectDir, path.resolve(projectDir, file)).split(path.sep).join('/');
+
+  // writable while PENDING: planning + docs + kit + repo meta — never product source.
+  const ALLOW = [
+    /^docs\//, /^\.claude\//, /^\.cursor\//, /^\.github\//, /^\.aider/, /^\.git/,
+    /^(README|AGENTS|CLAUDE|GEMINI|CHANGELOG|LICENSE)[^/]*$/i, /^[^/]+\.md$/,
+  ];
+  if (ALLOW.some((re) => re.test(rel))) return silent();
+
+  deny(
+    `PLAN-APPROVAL gate (hard rule 13): docs/PLAN.md still reads "> Approval: PENDING", ` +
+    `so source changes are blocked (attempted: ${rel}). Get the plan signed off first — ` +
+    `run /overview's PLAN-APPROVAL step (or /replan, then re-approve) and stamp the header ` +
+    `"> Approval: approved <date> v<n>". Planning artifacts under docs/ stay writable.`
+  );
+}

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

@@ -77,13 +77,15 @@ if (issues !== null) {
   emit('');
 }
 
-// 3b. research index
+// 3b. research index — token economy: inject only the 5 newest rows, each
+// truncated; the full table stays on disk for grep, sessions don't re-pay it.
 const idx = read('docs/research/INDEX.md');
 if (idx !== null) {
   const rows = idx.split('\n').filter((l) => /^\|\s*\d{4}-\d{2}-\d{2}/.test(l));
   emit(`## research/INDEX.md (${rows.length} prior investigations)`);
   emit('grep this before any new research or debugging.');
-  for (const l of rows.slice(-15)) emit('  ' + l);
+  for (const l of rows.slice(-5)) emit('  ' + (l.length > 220 ? l.slice(0, 217) + '…' : l));
+  if (rows.length > 5) emit(`  … (+${rows.length - 5} older — grep docs/research/INDEX.md)`);
   emit('');
 }
 
@@ -137,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

@@ -137,6 +137,63 @@ AUTO governs the *dev loop between* those gates, never the plan or the money dec
 
 -----
 
+## Feature lane (hands-off delivery — `/feature`)
+
+The lifecycle above is the GREENFIELD lane (a whole project). The **feature lane**
+is the BROWNFIELD lane: one APPROVED Feature doc in → a tested + hardened +
+documented feature branch out, near-100% hands-off. Humans remain at exactly three
+points: **approve the doc** (entry) · **UAT** (`/uat` against the generated
+TEST-PLAN) · **merge**. Production deploy is never in this lane (`/release` owns it).
+
+Pipeline (canonical body in `.claude/commands/feature.md`):
+spec completion → adversarial doc-review → mini-plan → contract surface probe →
+build loop (the `/phase` machinery, feature-scoped) → review & harden → manual
+test plan → docs + token stamp + summary → memory queue → delivery.
+
+Three layers make "hands-off" real — each uses the mechanism suited to its job:
+
+1. **Judgment → the orchestrator + subagents.** `/feature` routes the pipeline
+   through the standard roles under AUTO; the circuit breaker, rules 11/12, and
+   blind TDD apply unchanged.
+2. **Must-happen-every-time → a lifecycle hook.** `docs/features/<slug>/GATES.md`
+   is the run's gate checklist; the `Stop` hook (`.claude/hooks/feature-gate.js`)
+   BLOCKS session end while the feature is `(active)` in STATE with unchecked
+   gates — and it verifies ARTIFACTS, not ticks: a checked `test-plan` /
+   `mini-plan` / `contract-probe` / `token-stamp` / `summary` / `memory-queued`
+   gate whose deliverable is missing on disk blocks too (also re-checked in the
+   `(done)` state). A prompt can be ignored; the hook cannot. Rule 13 gets the
+   same treatment: the `PreToolUse` plan gate (`.claude/hooks/plan-gate.js`)
+   denies source Edit/Write while `docs/PLAN.md` reads `> Approval: PENDING`
+   (docs/kit paths stay writable; an active feature lane is exempt — its doc
+   approval is its own scoped gate). Hosts without lifecycle hooks run these as
+   model-run rituals.
+3. **No-human-at-the-keyboard → a headless runner.** `ISSFLOW_HEADLESS=1` tells the
+   lane no human is present: every hard-stop degrades to a `BLOCKED.md` report +
+   clean exit — never a guess. Two shipped runners (`create-issflow --ci|--docker`,
+   sources in `.claude/templates/automation/`):
+   - **GitHub Actions** — label an issue `feature:approved` (or dispatch with a doc
+     path); the workflow runs the lane on an ephemeral runner.
+   - **Docker** — `node scripts/feature-docker.js <FEATURE.md>` builds
+     `Dockerfile.issflow` and runs the lane in an unprivileged container with the
+     repo mounted; the container is the sandbox that makes a skip-permissions run
+     acceptable. Works for any host that ships a headless CLI. The runner image
+     MUST contain Node ≥ 18 — the lifecycle hooks are `node .claude/hooks/*.js`,
+     and without node they die silently (no session context, no feature gate).
+     The shipped image is Node-based and the wrapper preflights `node` before
+     every run, including bring-your-own images (`ISSFLOW_IMAGE=<name>`).
+     `--worktree` isolates a run in its own `git worktree` + branch, so 2–3
+     features build in parallel without touching your checkout or each other
+     (path-identical mounts: Linux/macOS).
+
+**Approval semantics (rule-13 scoped).** The doc header
+`> Approval: APPROVED <name> <date>` is the human sign-off, scoped to that doc
+only; the mini-plan inherits it while it stays inside the doc's stated scope —
+scope creep hard-stops to `/change-request`. The `> Automation: none|push|push+pr`
+header pre-authorizes outbound git actions for THAT run (hard-stop 1 satisfied by
+recorded consent). Merge and prod deploy can never be pre-authorized.
+
+-----
+
 ## BMAD integration (planning front-end)
 
 iStartSoftFlow is the EXECUTION loop; **BMAD-METHOD** is an optional PLANNING
@@ -201,14 +258,56 @@ 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)
 
 Named procedures, each with a canonical body in `.claude/commands/<name>.md`.
 
+**Lane routing — which entry point for which job:**
+
+| The job | Lane |
+|---------|------|
+| Brand-new project (no OVERVIEW yet) | `/overview` → `/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` |
+| Scope change to already-approved work | `/change-request` |
+| 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
+surface or need its own acceptance criteria? -> `/feature`. Otherwise `/quick`.
+
 - **overview** — bootstrap a project: design-research → grill r1 → design-research
   → re-grill r2 → `OVERVIEW.md` → planner → `PLAN.md`.
+- **feature [new <name> | from-story <key> | doc]** — the brownfield feature lane:
+  one APPROVED Feature doc → spec completion → adversarial doc-review → mini-plan
+  → contract probe → build loop → review & harden → manual test plan →
+  docs/stamps/memory → delivery. `new` scaffolds the doc from
+  `.claude/templates/FEATURE-template.md`; `from-story` transforms a BMAD/iSSM
+  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.
 - **change-request** — a mid-project scope change: impact analysis + re-estimate +
@@ -363,7 +462,7 @@ Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it
 
 -----
 
-## Hard rules (1–13)
+## Hard rules (1–14)
 
 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.
@@ -427,6 +526,16 @@ 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.
 
 -----
 
@@ -476,6 +585,22 @@ the KB. The kit works normally without a KB.
   summary, known limitations, approver — the gate to promote to production.
 - `docs/ui-audit-<date>.md` · `docs/qa-audit-<date>.md` · `docs/security-audit-<date>.md`
   — scored whole-product audit reports (from the `*-audit` commands).
+- `docs/features/<slug>/` — one dir per feature-lane run: `FEATURE.md` (the doc:
+  approval header, acceptance criteria, assumptions, token stamp, summary),
+  `PLAN.md` (mini-plan), `CONTRACTS.md` (probed public surfaces), `TEST-PLAN.md`
+  (the UAT scenario sheet), `GATES.md` (the Stop-hook-enforced checklist),
+  `BLOCKED.md` (headless blocker reports).
+- `docs/WISDOM-QUEUE.md` — auto-appended wisdom candidates from feature runs;
+  `/store-wisdom` reads it before pushing to the shared KB (push stays human).
+- `.claude/templates/automation/` — headless-runner sources (GitHub Actions ·
+  Dockerfile · docker wrapper), materialized by `create-issflow --ci` /
+  `--docker` as `.github/workflows/issflow-feature.yml` +
+  `.github/workflows/issflow-goal.yml` (cron-ready, disarmed by default) ·
+  `Dockerfile.issflow` · `scripts/feature-docker.js`.
+- `docs/GOALS.md` — the goal layer's state: one `## G<n>` block per goal
+  (Done-when · Budget · `Approved:` line · progress ticks). Maintained by `/goal`.
+- `.claude/templates/FEATURE-template.md` — the Feature-doc form `/feature new`
+  scaffolds (Approval/Automation headers + spec sections).
 - `docs/STATE.md` — current position. Small. Rewritten, not appended.
 - `docs/ISSUES.md` — error log. Deduped by synthesizer.
 - `docs/PLAN.md` — the phase plan (the product backlog). Carries an `> Approval:`
@@ -527,7 +652,7 @@ the same everywhere — only the *wiring* differs.
 
 | Host | Entry file | Commands | Subagents | Lifecycle hooks | Shared KB |
 |------|-----------|----------|-----------|-----------------|-----------|
-| **Claude Code** (reference) | `CLAUDE.md` (`@AGENTS.md`) + `.claude/` | `.claude/commands/` | native | SessionStart · PreToolUse (context-budget watchdog) · PreCompact · SubagentStop | yes |
+| **Claude Code** (reference) | `CLAUDE.md` (`@AGENTS.md`) + `.claude/` | `.claude/commands/` | native | SessionStart · PreToolUse (context watchdog + rule-13 plan gate) · PreCompact · SubagentStop · Stop (feature gate) | yes |
 | **Codex CLI** | `AGENTS.md` (native) | `.claude/commands/` (read as prompts) | read as reference | model-run | yes |
 | **Cursor** | `.cursor/rules/` + `AGENTS.md` | `.cursor/commands/` | reads `.claude/agents/` | `.cursor/hooks.json` (sessionStart · subagentStop) | yes |
 | **Gemini CLI** | `GEMINI.md` + `AGENTS.md` | `.claude/commands/` (read as prompts) | read as reference | model-run | yes |

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

@@ -0,0 +1,43 @@
+# FEATURE: <feature name>
+
+> Status: draft
+> Approval: PENDING            <!-- APPROVED <name> <YYYY-MM-DD> arms the lane -->
+> Automation: none             <!-- none | push | push+pr — what the run may do outbound -->
+
+<!--
+The ONE human input of the feature lane. Fill it in, flip Approval to
+APPROVED, then run:  /feature docs/features/<slug>/FEATURE.md
+(or headless: node scripts/feature-docker.js docs/features/<slug>/FEATURE.md)
+Everything below Approval is the spec the agents build and test against —
+write WHAT and WHY; the lane decides HOW and logs it.
+-->
+
+## What & why
+
+<2–5 sentences: the capability, who uses it, why now. Plain language.>
+
+## Scope
+
+- <bullet the concrete behaviours in scope — each becomes acceptance criteria>
+- <keep it to ONE feature; a second feature = a second doc>
+
+## Out of scope
+
+- <name what this doc deliberately does NOT cover — the scope-creep fence.
+   The lane HARD-STOPS to /change-request if the plan needs anything here>
+
+## Constraints & contracts
+
+- <APIs / schemas / integrations it must respect or extend, if known>
+- <performance, compliance, or platform constraints, if any>
+
+## Acceptance criteria
+
+<!-- The lane's adversarial doc-review will ATTACK this list and fold in the
+     negative/abuse cases it finds. Start with the positives you care about. -->
+- <given/when/then or checklist form — every line must be testable>
+
+## Done when
+
+- Every acceptance criterion has a passing test (blind TDD).
+- Every scenario in the generated TEST-PLAN.md passes UAT.

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

@@ -0,0 +1,44 @@
+# iStartSoftFlow — headless runner image (Docker lane).
+# Installed by `npx create-issflow --docker` as Dockerfile.issflow.
+# Built + run by scripts/feature-docker.js — you rarely use this file directly.
+#
+# The container IS the sandbox: an ephemeral, unprivileged workspace where
+# `claude --dangerously-skip-permissions` is acceptable because the blast radius
+# is the mounted repo only. Never mount the Docker socket or your $HOME into it.
+#
+# The image is tool-only; YOUR project's runtime deps are not baked in. If the
+# feature lane must run your test suite and it needs more than Node (Python, Go,
+# a DB client, …), extend this image: `FROM issflow-runner` + your toolchain.
+
+FROM node:20-bookworm-slim
+
+# git — branches/commits are the lane's deliverable. ca-certificates — API TLS.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates \
+    && rm -rf /var/lib/apt/lists/* \
+    && npm install -g @anthropic-ai/claude-code
+
+# sanity: the kit's lifecycle hooks are `node .claude/hooks/*.js` — a runner
+# image WITHOUT node runs claude fine but every hook silently dies (no
+# session-start context, no feature gate). Fail the build, not the run.
+RUN node --version && claude --version
+
+# unprivileged runner; /work is the mounted repo.
+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
+
+# identity for the commits the lane makes (override via docker run -e).
+ENV GIT_AUTHOR_NAME="issflow-runner" \
+    GIT_AUTHOR_EMAIL="issflow-runner@local" \
+    GIT_COMMITTER_NAME="issflow-runner" \
+    GIT_COMMITTER_EMAIL="issflow-runner@local"
+
+ENTRYPOINT ["claude"]

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// iStartSoftFlow — run the feature lane headless in Docker.
+// Installed by `npx create-issflow --docker` as scripts/feature-docker.js.
+// Pure Node, cross-platform (macOS / Windows / Linux). Needs: docker, ANTHROPIC_API_KEY.
+//
+//   node scripts/feature-docker.js docs/features/<slug>/FEATURE.md [--rebuild] [--worktree]
+//
+// What it does: build the runner image (Dockerfile.issflow) if missing, then run
+// `claude -p "/feature <doc>"` inside an ephemeral container with THIS repo
+// mounted at /work. The container is the sandbox — the run edits, tests, and
+// commits on feature/<slug> in your working tree. Push/PR happen only if the
+// doc's `> Automation:` header authorizes them AND credentials are available
+// in the container; otherwise the branch stays local and pushing is yours.
+//
+// --worktree: parallel lane. Mounts a FRESH `git worktree` (../<repo>-feature-<slug>,
+// on branch feature/<slug>) instead of your working tree, so 2–3 features can run
+// concurrently without touching your checkout or each other. Each run needs its
+// own doc + slug. Results come back as commits on feature/<slug> (visible from the
+// main repo); remove the dir with `git worktree remove` after merge.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const IMAGE = process.env.ISSFLOW_IMAGE || 'issflow-runner';
+const argv = process.argv.slice(2);
+const rebuild = argv.includes('--rebuild');
+const useWorktree = argv.includes('--worktree');
+const doc = argv.find((a) => !a.startsWith('--'));
+
+const die = (msg) => { console.error('feature-docker: ' + msg); process.exit(1); };
+const run = (cmd, args, opts = {}) => spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+
+if (!doc) die('usage: node scripts/feature-docker.js <path/to/FEATURE.md> [--rebuild] [--worktree]');
+const repo = process.cwd();
+if (!fs.existsSync(path.join(repo, doc))) die(`Feature doc not found: ${doc} (run from the repo root)`);
+if (!fs.existsSync(path.join(repo, '.claude', 'commands', 'feature.md'))) die('no .claude/commands/feature.md here — run from a repo with the kit installed');
+if (!process.env.ANTHROPIC_API_KEY) die('ANTHROPIC_API_KEY is not set');
+
+const dockerOk = spawnSync('docker', ['version'], { stdio: 'ignore' });
+if (dockerOk.error || dockerOk.status !== 0) die('docker is not available');
+
+const haveImage = spawnSync('docker', ['image', 'inspect', IMAGE], { stdio: 'ignore' }).status === 0;
+if (!haveImage || rebuild) {
+  const df = fs.existsSync(path.join(repo, 'Dockerfile.issflow'))
+    ? 'Dockerfile.issflow'
+    : path.join('.claude', 'templates', 'automation', 'Dockerfile');
+  console.log(`feature-docker: building ${IMAGE} from ${df} …`);
+  if (run('docker', ['build', '-t', IMAGE, '-f', df, '.']).status !== 0) die('image build failed');
+}
+
+// preflight: the kit's hooks (session-start, the feature gate) are Node
+// scripts. An image without node — e.g. claude installed as a native binary,
+// or a bring-your-own ISSFLOW_IMAGE built on a non-Node base — runs claude
+// but every hook dies silently, so the gate enforcement is gone. Refuse early.
+const nodeCheck = spawnSync('docker', ['run', '--rm', '--entrypoint', 'node', IMAGE, '--version'], { stdio: 'ignore' });
+if (nodeCheck.status !== 0) die(
+  `image "${IMAGE}" has no usable node — the kit's lifecycle hooks are Node scripts and cannot run. ` +
+  `Use the shipped image (delete it + rerun with --rebuild), or base your custom image on Node >= 18 ` +
+  `(e.g. FROM issflow-runner).`
+);
+
+// --worktree: isolate the run in its own checkout so features run in parallel.
+let mountDir = repo;
+if (useWorktree) {
+  const slug = path.basename(path.dirname(path.resolve(repo, doc))) || 'feature';
+  const wt = path.join(path.dirname(repo), `${path.basename(repo)}-feature-${slug}`);
+  const branch = `feature/${slug}`;
+  if (!fs.existsSync(wt)) {
+    console.log(`feature-docker: creating worktree ${wt} on ${branch}`);
+    const branchExists = spawnSync('git', ['rev-parse', '--verify', branch], { stdio: 'ignore' }).status === 0;
+    const wtArgs = branchExists ? ['worktree', 'add', wt, branch] : ['worktree', 'add', '-b', branch, wt];
+    if (run('git', wtArgs).status !== 0) die('git worktree add failed');
+  }
+  // the doc may only exist in the main tree so far — carry it into the worktree.
+  const wtDoc = path.join(wt, doc);
+  if (!fs.existsSync(wtDoc)) {
+    fs.mkdirSync(path.dirname(wtDoc), { recursive: true });
+    fs.copyFileSync(path.resolve(repo, doc), wtDoc);
+  }
+  mountDir = wt;
+  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}`);
+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'
+);
+// pass git identity through when the host has one configured.
+for (const k of ['GIT_AUTHOR_NAME', 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_NAME', 'GIT_COMMITTER_EMAIL'])
+  if (process.env[k]) args.push('-e', k);
+args.push(IMAGE, '-p', `/feature ${doc}`, '--dangerously-skip-permissions');
+
+const res = run('docker', args);
+if (res.status !== 0) die(`run exited with status ${res.status} — see output above; blockers land in docs/features/<slug>/BLOCKED.md`);
+console.log('feature-docker: done. Review the feature branch, then run /uat with the TEST-PLAN.');

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

@@ -0,0 +1,82 @@
+# iStartSoftFlow — headless feature lane (GitHub Actions).
+# Installed by `npx create-issflow --ci` as .github/workflows/issflow-feature.yml.
+#
+# Two triggers:
+#   1. Label an issue `feature:approved` — the issue TITLE becomes the slug and
+#      the issue BODY becomes docs/features/<slug>/FEATURE.md. The body must
+#      already carry the `> Approval:` / `> Automation:` headers (/feature step 0b);
+#      the label is the human act that fires the run.
+#   2. Manual dispatch with the path of a Feature doc already committed.
+#
+# The run pushes feature/<slug> and opens a PR when the doc says
+# `> Automation: push+pr`. It NEVER merges and NEVER deploys — UAT + merge stay human.
+#
+# Setup: repo secret ANTHROPIC_API_KEY. Grant Actions "Read and write permissions"
+# (Settings → Actions → General → Workflow permissions) so the run can push + open PRs.
+
+name: issflow-feature
+
+on:
+  issues:
+    types: [labeled]
+  workflow_dispatch:
+    inputs:
+      feature_doc:
+        description: Path to the approved Feature doc (docs/features/<slug>/FEATURE.md)
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+jobs:
+  feature:
+    if: github.event_name == 'workflow_dispatch' || github.event.label.name == 'feature:approved'
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Issue trigger: materialize the issue body as the Feature doc.
+      - name: Write Feature doc from issue
+        if: github.event_name == 'issues'
+        env:
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_BODY: ${{ github.event.issue.body }}
+        run: |
+          slug=$(printf '%s' "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g')
+          test -n "$slug"
+          mkdir -p "docs/features/$slug"
+          printf '%s\n' "$ISSUE_BODY" > "docs/features/$slug/FEATURE.md"
+          echo "FEATURE_DOC=docs/features/$slug/FEATURE.md" >> "$GITHUB_ENV"
+
+      - name: Resolve Feature doc path
+        if: github.event_name == 'workflow_dispatch'
+        run: echo "FEATURE_DOC=${{ inputs.feature_doc }}" >> "$GITHUB_ENV"
+
+      - name: Run the feature lane
+        uses: anthropics/claude-code-action@v1
+        env:
+          ISSFLOW_HEADLESS: "1"
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: "/feature ${{ env.FEATURE_DOC }}"
+          # 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.
+      - name: Report back to the issue
+        if: github.event_name == 'issues' && always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh issue comment ${{ github.event.issue.number }} \
+            --body "issflow-feature run finished: ${{ job.status }}. See the run log + the feature/<slug> branch. Next: /uat with docs/features/<slug>/TEST-PLAN.md."

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"