create-issflow 1.10.1 → 1.11.1

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

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-// SessionStart hook. stdout is injected into the agent's context every session.
-// Pure Node, cross-platform (macOS / Windows / Linux) — no bash/jq/python needed.
+// SessionStart — Tier A inject (~lean). stdout → agent context.
 'use strict';
 const fs = require('fs');
 const path = require('path');
@@ -15,144 +14,81 @@ const read = (f) => { try { return fs.readFileSync(f, 'utf8'); } catch (_) { ret
 const exists = (f) => fs.existsSync(f);
 const sh = (cmd) => { try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); } catch (_) { return ''; } };
 
-emit('=== iStartSoftFlow AUTO-CONTEXT (injected by hook, NOT optional) ===');
-emit('');
+let cfg = {};
+try { cfg = JSON.parse(read('.issflow/flow-config.json') || '{}'); } catch (_) {}
+const maxStateLines = (cfg.context && cfg.context.injectMaxLines) || 25;
+const staleHours = (cfg.delivery && cfg.delivery.staleAfterHours) || 24;
+
+// Resume/compact: keep inject tiny (Pattern 1 — skip heavy bodies)
+let source = 'startup';
+try {
+  const raw = fs.readFileSync(0, 'utf8');
+  if (raw) {
+    const j = JSON.parse(raw);
+    source = j.source || j.hook_event_name || source;
+  }
+} catch (_) {}
+const leanResume = /resume|compact/i.test(String(source));
 
-// 1. git state
-emit('## Git');
-emit('branch: ' + (sh('git branch --show-current').trim() || 'n/a'));
-const uncommitted = sh('git status --short').split('\n').filter((l) => l.trim() !== '').length;
-emit('uncommitted: ' + uncommitted + ' file(s)');
-for (const l of sh('git log --oneline -3').replace(/\n+$/, '').split('\n').filter(Boolean)) emit('  ' + l);
+emit('=== iStartSoftFlow Tier-A (session) ===');
+emit('source: ' + source);
+emit('git: ' + (sh('git branch --show-current').trim() || 'n/a') +
+  ' · dirty ' + sh('git status --short').split('\n').filter((l) => l.trim()).length);
 emit('');
 
-// 2. active state (cap size — STATE.md is meant to stay small)
 const state = read('docs/STATE.md');
-if (state !== null) {
-  emit('## STATE.md (current position - READ THIS FIRST)');
-  const sl = state.replace(/\n$/, '').split('\n');
-  for (const l of sl.slice(0, 40)) emit(l);
-  if (sl.length > 40) emit(`… (+${sl.length - 40} more — STATE.md should be small; trim it)`);
-  emit('');
+if (!state) {
+  emit('STATE.md missing → /overview');
 } else {
-  emit('## STATE.md missing -> run /overview to bootstrap the project.');
-  emit('');
-}
+  emit('## STATE (read first)');
+  const lines = state.replace(/\n$/, '').split('\n');
+  for (const l of lines.slice(0, maxStateLines)) emit(l);
+  if (lines.length > maxStateLines) emit(`… (+${lines.length - maxStateLines} more)`);
 
-// 2b. active sprint (sprint layer) — surface goal + burndown if one is active
-const sprintMatch = (state || '').match(/^\s*sprint:\s*(\d+)\s*\(active\)/m);
-if (sprintMatch) {
-  const sf = read(`docs/sprints/sprint-${sprintMatch[1]}.md`);
-  if (sf !== null) {
-    emit(`## Sprint ${sprintMatch[1]} (active)`);
-    const goal = (sf.match(/goal:\s*(.+)/i) || [])[1];
-    if (goal) emit('goal: ' + goal.trim());
-    const burn = sf.split('\n').find((l) => /burndown|remaining|pts? left|[▁▂▃▄▅▆▇█]/i.test(l));
-    if (burn) emit('burndown: ' + burn.trim());
-    emit(`see docs/sprints/sprint-${sprintMatch[1]}.md for the full sprint.`);
-    emit('');
-  }
-}
-
-// 3. issue log — inject only OPEN issues (resolved ones stay in the file for
-//    grep, but are NOT re-paid in tokens every session). Capped.
-const issues = read('docs/ISSUES.md');
-if (issues !== null) {
-  const blocks = [];
-  let cur = null;
-  for (const l of issues.split('\n')) {
-    if (/^### /.test(l)) { if (cur) blocks.push(cur); cur = [l]; }
-    else if (cur) cur.push(l);
-  }
-  if (cur) blocks.push(cur);
-  const open = blocks.filter((b) => b.some((l) => /- \[ \]/.test(l)));
-  emit(`## ISSUES.md (${open.length} open) - grep this file before debugging anything`);
-  if (open.length) {
-    const flat = open.flat();
-    for (const l of flat.slice(0, 50)) emit(l);
-    if (flat.length > 50) emit('… (more — grep docs/ISSUES.md for full detail)');
-  } else {
-    emit('(no open issues)');
+  // Delivery / WAITING_STALE nudge
+  const waitSince = (state.match(/waiting_since:\s*(\S+)/) || [])[1];
+  const status = (state.match(/^\s*status:\s*(\S+)/m) || [])[1] || '';
+  const waitingFor = (state.match(/waiting_for:\s*(.+)/) || [])[1];
+  const nextHuman = (state.match(/next_human_action:\s*(.+)/) || [])[1];
+  const agentEta = (state.match(/agent_eta:\s*(\S+)/) || [])[1];
+  if (agentEta && agentEta !== 'none') emit('delivery.agent_eta: ' + agentEta + ' · status: ' + status);
+  if (/WAITING/i.test(status) || (waitingFor && waitingFor.trim() !== 'none')) {
+    emit('WAITING_ON_HUMAN: ' + (waitingFor || status).trim());
+    if (nextHuman) emit('next_human_action: ' + nextHuman.trim());
+    if (waitSince && waitSince !== 'none') {
+      const since = Date.parse(waitSince);
+      if (!Number.isNaN(since)) {
+        const hours = (Date.now() - since) / 3600000;
+        if (hours >= staleHours) emit('WAITING_STALE: human gate older than ' + staleHours + 'h — AI clock paused; not an agent hang.');
+      }
+    }
   }
-  emit('');
-}
-
-// 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(-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('');
 }
+emit('');
 
-// 3d. shared KB — pull latest + load snapshot
-const KB_CONFIG = '.issflow/kb-config.json';
-let kbActive = false;
-if (exists(KB_CONFIG)) {
-  let cfg = {}; try { cfg = JSON.parse(read(KB_CONFIG) || '{}'); } catch (_) {}
-  let kbPath = cfg.kb_path || '';
-  if (kbPath.startsWith('~')) kbPath = path.join(os.homedir(), kbPath.slice(1));
-  if (kbPath && exists(kbPath) && fs.statSync(kbPath).isDirectory()) {
-    emit('## Shared KB');
-    let pulled = true;
-    try { execSync(`git -C "${kbPath}" pull --ff-only --quiet`, { stdio: 'ignore' }); } catch (_) { pulled = false; }
-    emit(pulled ? 'KB pulled: OK' : 'KB pull skipped (offline or conflict — using local copy)');
-
-    const cut = new Date(); cut.setMonth(cut.getMonth() - 6);
-    const cutoff = cut.toISOString().slice(0, 10);
-    const today = new Date().toISOString().slice(0, 10);
-    const kbIndex = path.join(kbPath, 'INDEX.md');
-    if (exists(kbIndex)) {
-      const lines = (read(kbIndex) || '').split('\n').filter((l) => l && !l.startsWith('#'));
-      const snap = [`# KB snapshot — loaded ${today}`, `# Stale = created date older than ${cutoff}`, ''];
-      let stale = 0, total = 0;
-      for (const line of lines) {
-        if (line.includes('|')) total++;
-        const entryDate = (line.split('|')[0] || '').trim();
-        if (/^\d{4}-\d{2}-\d{2}$/.test(entryDate) && entryDate < cutoff) { snap.push('[STALE] ' + line); stale++; }
-        else snap.push(line);
-      }
-      try { fs.mkdirSync('docs', { recursive: true }); fs.writeFileSync('docs/.kb-snapshot.md', snap.join('\n') + '\n'); } catch (_) {}
-      emit(`KB snapshot loaded: ${total} entries (${stale} stale — researcher will re-research these)`);
-      emit('Snapshot at docs/.kb-snapshot.md — researcher reads this before web search.');
-    } else {
-      emit(`KB INDEX.md not found at ${kbPath} — run /store-wisdom to populate it.`);
+if (!leanResume) {
+  const issues = read('docs/ISSUES.md');
+  let openCount = 0;
+  if (issues) {
+    const blocks = [];
+    let cur = null;
+    for (const l of issues.split('\n')) {
+      if (/^### /.test(l)) { if (cur) blocks.push(cur); cur = [l]; }
+      else if (cur) cur.push(l);
     }
-    emit('');
-    kbActive = true;
-  } else {
-    emit('## Shared KB: configured but path not found (' + (cfg.kb_path || '') + ')');
-    emit('Fix kb_path in .issflow/kb-config.json (or re-run: npx create-issflow).');
-    emit('');
+    if (cur) blocks.push(cur);
+    openCount = blocks.filter((b) => b.some((l) => /- \[ \]/.test(l))).length;
   }
+  emit('open issues: ' + openCount + ' (grep docs/ISSUES.md — bodies not injected)');
+  emit('');
 }
 
-// 4. hard rule reminder
-emit('## RULES (enforced this session)');
-emit('- AUTO mode (default) governs the DEV loop: follow the plan — decide + log +');
-emit('  continue, do NOT stop to ask. (Planning / grill still asks — that part is fine.)');
-emit('  Hard-stops only: security / irreversible-or-outbound actions / contradictory spec.');
-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.');
-emit('- end of every phase: run /synthesize, then /clear.');
-emit('- small obvious change? use /quick, not /phase.');
-emit('- token economy: keep context lean. Delegate noisy work to subagents (they');
-emit('  return summaries). If one phase grows past ~50% of the model window, split');
-emit('  it or /synthesize -> /clear — do not coast to auto-compact.');
-if (kbActive) {
-  emit('- KB active: researcher checks docs/.kb-snapshot.md before web search.');
-  emit('- learned something worth keeping? run /store-wisdom.');
-}
-emit('=== END AUTO-CONTEXT ===');
+emit('## RULES');
+emit('- PM-mode: report ETA/stage/DONE|BLOCKED|WAITING|SLIP|HANDOFF — do not pair as junior dev.');
+emit('- Plan PENDING → no source edits (rule 13). Design-direction locked before UI propose.');
+emit('- Past agent_eta while AGENT_ACTIVE → SLIP report. Waiting human → eta_paused.');
+emit('- Assumption budget per phase (flow-config). End phase: /synthesize (keep delivery:) → /clear.');
+emit('- Prefer clear+handoff over compact near context gate.');
+emit('=== END Tier-A ===');
 
 process.stdout.write(out.join('\n') + '\n');

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

@@ -200,14 +200,28 @@ those gates, never the plan, the money, or the design/arch frame.
 
 | House role | Kit surface |
 |------------|-------------|
-| BA / PM | `/overview` grill · `grill-me` · PLAN / PROPOSAL / CR gates |
-| UX / UI | `/design` (UX pack) · `ui-ux-pro-max` (look) · `ux-design` (frame + gate) · `/ui-audit` · rule 9 CLOSE |
-| Architect | `/design` (ARCHITECTURE) · `researcher` DESIGN · `code-standards` · `/log-decision` |
-| Developer | `implementer` · `/phase` · `/feature` · `/quick` |
+| BA / PM | `/overview` grill · `grill-me` · PLAN / PROPOSAL / CR gates · delivery ETA board |
+| UX / UI | Direction Picker → tokens · `/design` UX pack · `ui-ux-pro-max` (only if unlocked) · `ux-design` · `/ui-audit` |
+| Architect / SA | `/design` ARCHITECTURE + auth decision · `researcher` DESIGN · `/log-decision` |
+| Developer | `implementer` · `/phase` · `/feature` · `/quick` — **no direct user chat** |
 | QA | `test-author` · `e2e-runner` · `/qa-audit` · `/uat` |
 | DevOps | final-phase deploy · `/release` promote |
 | Support | `/support` · `/log-issue` · `/runbook` · release hypercare |
 
+**Human conversation mode:** the owner talks to the orchestrator as PM/SA. Subagents
+never address the user. During AUTO build, report stage / ETA / WAITING / SLIP /
+DONE — do not pair-program unless GUIDED.
+
+### When `grill-me` runs
+
+| Command | Grill? |
+|---------|--------|
+| `/overview` | Yes — automatic double grill |
+| `/design` | Short grill only if auth/surfaces still open |
+| `/change-request` | No full grill — 1–3 mini-asks if UX/arch/auth hit |
+| `/phase` · `/feature` build | No — use STATE + stuck/ETA |
+| User says “grill me” | On demand anytime |
+
 -----
 
 ## Feature lane (hands-off delivery — `/feature`)
@@ -341,9 +355,26 @@ The orchestrator ROUTES. It does not implement or debug.
 | 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).
+`sonnet` · `opus` · `inherit` · or a full model id. Cross-host suggestions live in
+`.issflow/models/MODEL-MATRIX.md` (update `as_of` when vendors change). Adaptive
+router under `.issflow/routing/` is advisory/fail-closed — never invent unverified
+API IDs. Hosts without per-agent model support run the session model (graceful degrade).
+
+### Delivery clocks (finish-date honesty)
+
+Three clocks — do not mix:
+
+1. **Scope effort (A)** — ideal-days for commercial value / pricing  
+2. **Agent-active ETA (B)** — when AI may finish DoD if not waiting on humans  
+3. **Waiting-on-human (C)** — pauses B; `WAITING_STALE` after `staleAfterHours`
+
+STATE `delivery:` is mandatory during `/phase` and `/feature`. Past `agent_eta`
+while `AGENT_ACTIVE` → SLIP report. Assumption budget per phase from flow-config.
+
+### Plan-Ready (before rule 13 approve)
+
+Testable acceptance per phase · no TBD on auth/money/PII/primary surfaces ·
+direction locked if UI · size+lane tags · dependencies clear.
 
 -----
 
@@ -448,15 +479,18 @@ inject context, the model performs them itself.
 
 ### SESSION-OPEN (start / clear / compact-resume)
 
-At the start of every session, before any other work, surface:
-1. git state (branch, uncommitted count, last 3 commits).
-2. `docs/STATE.md` — the current position. READ THIS FIRST. If a sprint is active,
-   surface its goal + burndown from `docs/sprints/sprint-<n>.md`.
-3. open items in `docs/ISSUES.md`.
-4. `docs/research/INDEX.md` (research map) + infra/auth status.
-5. shared KB: pull latest + load `docs/.kb-snapshot.md` if `.issflow/kb-config.json`
-   exists.
-6. a one-line reminder of the hard rules below.
+**Tier A (default — keep short):** SessionStart hook / model-run checklist:
+1. git one-liner (branch · dirty count · tip).
+2. `docs/STATE.md` top — phase, plan, design-direction, **delivery ETA/status**.
+3. open-issue count (not full dump).
+4. If `WAITING_STALE` / past `agent_eta` while AGENT_ACTIVE → surface that first.
+5. Hard-rule one-liner (plan PENDING → no source edits).
+
+**Tier B (full, on demand / first overview):** research INDEX · infra/auth · KB
+snapshot · sprint burndown. Prefer Hard handoff (`/synthesize` keep `delivery:` →
+`/clear`) over cold `/compact` near the context gate.
+
+Hosts without hooks: the orchestrator runs Tier A by hand before any Edit/Write.
 
 ### SPRINT-STANDUP (auto — at phase close inside an active sprint)
 
@@ -475,9 +509,15 @@ recover: current phase, next action, open blocker.
 
 The cheapest token is the one never loaded. The kit is built to minimise context:
 
+- **SessionStart is Tier A** — git one-liner + STATE top + open-issue count +
+  delivery ETA/WAITING nudge. Target a small inject; resume/compact stays leaner.
+- **Near context gate:** prefer writing handoff into STATE + `/synthesize` +
+  `/clear` over `/compact` (cold compact is expensive). Soft warn ~55%; hard
+  gate ~70% (see `flow-config.json`).
 - **Phase boundary is the primary reset.** `/synthesize -> /clear` ends every
   phase so the next one starts with a small, fresh context instead of carrying
-  the whole history forward. The **sprint boundary** (`/sprint close`) is a second,
+  the whole history forward. Synthesizer must **preserve the `delivery:` block**
+  in STATE. The **sprint boundary** (`/sprint close`) is a second,
   coarser reset — synthesize + clear there too before the next sprint plans.
 - **Lazy, not always-on.** This methodology + the skills load on demand; only the
   SessionStart hook output is paid every session, and it injects just the live

package/template/.issflow/models/MODEL-MATRIX.md

@@ -0,0 +1,33 @@
+# Model matrix (guidance)
+
+**as_of:** 2026-11-04  
+Update this file when vendors ship new models. Do **not** hardcode unverified API IDs into agent runners.
+
+Agent frontmatter stays: `haiku` · `sonnet` · `opus` · `inherit`.  
+Adaptive router (`.issflow/routing/`) remains advisory / fail-closed.
+
+## Capability tiers → host suggestions
+
+| Kit alias / role band | Claude Code | Cursor | Codex CLI | Antigravity |
+|----------------------|-------------|--------|-----------|-------------|
+| `haiku` (synthesizer, cheap) | Haiku 5.5 alias `haiku` | Composer 2.5 / Auto | Luna-class (plan-dependent) | Gemini 3.8 Flash |
+| `sonnet` (researcher, e2e, daily) | Sonnet 5.5 alias `sonnet` | Composer 2.5 / Auto / Sonnet | Terra-class | Gemini 3.8 Flash |
+| `opus` / `inherit` hard (planner, debugger, arch) | Opus 5.5 / session model | Opus / Sol / Grok flagship | Sol-class | Gemini 4 Argon |
+| Long-horizon session | Fable / `opus[1m]` | Grok flagship | Sol + high effort | Argon High |
+
+## Role defaults (unchanged aliases)
+
+| Role | `model:` |
+|------|----------|
+| synthesizer | `haiku` |
+| researcher · e2e-runner | `sonnet` |
+| planner · debugger · implementer · test-author | `inherit` |
+
+## Verify before pinning IDs
+
+- Claude: https://code.claude.com/docs/en/model-config  
+- Cursor: https://cursor.com/help/models-and-usage/available-models  
+- Codex: https://learn.chatgpt.com/docs/models  
+- Antigravity: https://antigravity.google/docs/models/  
+
+If a host cannot switch models per agent, run everything on the session model.

package/template/.issflow/routing/model-router.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * Host-aware model routing. Pure decision logic; does not alter approvals,
+ * mutate host configuration, or assume UI labels are model identifiers.
+ * Hosts must inject verified capabilities and a switchModel implementation.
+ */
+const policy = require('./policy.json');
+const SUPPORTED = Object.freeze(['codex', 'claude', 'cursor']);
+const TIERS = Object.freeze(['economy', 'balanced', 'advanced']);
+const HIGH_RISK = new Set(['security', 'authentication', 'authorization', 'payments', 'secrets', 'production', 'migration']);
+
+function route(input = {}) {
+  const { provider, agent = 'orchestrator', task = '', risk = 'low', complexity = 'medium',
+    mode = policy.defaultMode, capabilities = {} } = input;
+  if (!SUPPORTED.includes(provider)) throw new Error('Unsupported provider: ' + String(provider));
+  if (!['advisory', 'automatic'].includes(mode)) throw new Error('Invalid routing mode');
+  const elevated = risk === 'high' || HIGH_RISK.has(String(task).toLowerCase());
+  let tier = policy.agents[agent] || 'balanced';
+  if (elevated || complexity === 'high') tier = 'advanced';
+  if (!TIERS.includes(tier)) tier = 'balanced';
+
+  const preference = policy.providers[provider][tier];
+  const verified = Array.isArray(capabilities.models) ? capabilities.models : [];
+  // Never invent model IDs: only an explicitly configured, verified model is selectable.
+  const configured = capabilities.tiers && capabilities.tiers[tier];
+  const modelId = configured && configured.modelId || preference.modelId;
+  const match = verified.find(m => m.id === modelId);
+  const requestedEffort = configured && configured.reasoningEffort !== undefined
+    ? configured.reasoningEffort : preference.reasoningEffort;
+  const supportedEfforts = match && Array.isArray(match.reasoningEfforts) ? match.reasoningEfforts : [];
+  const effort = requestedEffort && supportedEfforts.includes(requestedEffort) ? requestedEffort : null;
+  const eligible = !!match && (!requestedEffort || !!effort);
+  return {
+    provider, agent, tier, mode, modelId: eligible ? modelId : null,
+    reasoningEffort: eligible ? effort : null,
+    availability: eligible ? 'verified' : 'unknown',
+    action: eligible ? (mode === 'automatic' ? 'switch-request' : 'recommend') : 'inherit',
+    reason: elevated ? 'Elevated risk' : complexity === 'high' ? 'High complexity' : 'Agent default',
+    fallback: 'inherit',
+  };
+}
+
+/**
+ * Automatic mode is opt-in. switchModel must be a host-provided function
+ * returning {confirmed:true, modelId, reasoningEffort}; a request alone is
+ * never considered a successful model switch.
+ */
+async function execute(input = {}, host = {}) {
+  const decision = route(input);
+  if (decision.action !== 'switch-request') return { ...decision, switched: false };
+  if (host.supportsSwitch !== true || typeof host.switchModel !== 'function') {
+    return { ...decision, action: 'recommend', switched: false, reason: 'Host switch unavailable' };
+  }
+  try {
+    const result = await host.switchModel({ modelId: decision.modelId, reasoningEffort: decision.reasoningEffort });
+    const confirmed = result && result.confirmed === true && result.modelId === decision.modelId &&
+      (decision.reasoningEffort === null || result.reasoningEffort === decision.reasoningEffort);
+    return { ...decision, action: confirmed ? 'switched' : 'recommend', switched: !!confirmed,
+      reason: confirmed ? decision.reason : 'Host did not confirm selected model/effort' };
+  } catch (_) {
+    return { ...decision, action: 'recommend', switched: false, reason: 'Host switch failed' };
+  }
+}
+
+module.exports = { route, execute, policy };

package/template/.issflow/routing/policy.json

@@ -0,0 +1,69 @@
+{
+  "version": 1,
+  "defaultMode": "advisory",
+  "tiers": {
+    "economy": {
+      "description": "Low-risk documentation and routine checks"
+    },
+    "balanced": {
+      "description": "Implementation and test work"
+    },
+    "advanced": {
+      "description": "Architecture, security and complex debugging"
+    }
+  },
+  "agents": {
+    "orchestrator": "balanced",
+    "researcher": "economy",
+    "planner": "advanced",
+    "implementer": "balanced",
+    "test-author": "balanced",
+    "debugger": "balanced",
+    "e2e-runner": "economy",
+    "synthesizer": "economy"
+  },
+  "providers": {
+    "codex": {
+      "economy": {
+        "modelId": null,
+        "reasoningEffort": "medium"
+      },
+      "balanced": {
+        "modelId": null,
+        "reasoningEffort": "high"
+      },
+      "advanced": {
+        "modelId": null,
+        "reasoningEffort": "xhigh"
+      }
+    },
+    "claude": {
+      "economy": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "balanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "advanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      }
+    },
+    "cursor": {
+      "economy": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "balanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "advanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      }
+    }
+  }
+}

package/template/.issflow/scripts/entry-notice.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Repo-internal PostToolUse hook (NOT shipped by create-issflow — build.js only
+// copies agents/commands/skills/hooks/istartsoft-flow/templates + README).
+// When root entry shims are edited, nudge to keep AGENTS.md / host adapters aligned.
+'use strict';
+let data = '';
+process.stdin.on('data', (c) => (data += c)).on('end', () => {
+  try {
+    const f = (JSON.parse(data || '{}').tool_input || {}).file_path || '';
+    if (/(^|[\\/])CLAUDE\.md$/.test(f)) {
+      process.stdout.write(JSON.stringify({
+        systemMessage: 'CLAUDE.md is a host shim — keep `@AGENTS.md` as the only SoT pointer. Sync BMAD if needed: save_artifact type=claude-md',
+      }));
+    } else if (/(^|[\\/])AGENTS\.md$/.test(f)) {
+      process.stdout.write(JSON.stringify({
+        systemMessage: 'AGENTS.md changed — keep it an index of `.issflow/istartsoft-flow/METHODOLOGY.md` (anti-drift: do not paste hard rules here).',
+      }));
+    }
+  } catch (_) { /* ignore malformed hook input */ }
+});

package/template/.issflow/scripts/token-lint.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Portable copy — prefer project `scripts/token-lint.js` after install.
+// Same logic as repo-root scripts/token-lint.js for kit consumers.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+const TOKENS = path.join(ROOT, 'docs', 'design', 'tokens.css');
+const SCAN_GLOBS = ['src', 'app', 'components', 'pages', 'web', 'frontend', 'ui'];
+const EXT = new Set(['.css', '.scss', '.tsx', '.jsx', '.vue', '.svelte', '.html']);
+const HEX = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+const RGB = /\brgba?\([^)]+\)/g;
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name === 'dist' || e.name === '.git') continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else if (EXT.has(path.extname(e.name))) out.push(p);
+  }
+  return out;
+}
+
+if (!fs.existsSync(TOKENS)) {
+  console.log('token-lint: skip (no docs/design/tokens.css)');
+  process.exit(0);
+}
+
+const tokenSrc = fs.readFileSync(TOKENS, 'utf8');
+const allowed = new Set();
+for (const m of tokenSrc.matchAll(HEX)) allowed.add(m[0].toLowerCase());
+for (const m of tokenSrc.matchAll(RGB)) allowed.add(m[0].replace(/\s+/g, '').toLowerCase());
+
+const files = SCAN_GLOBS.flatMap((d) => walk(path.join(ROOT, d)));
+const hits = [];
+for (const file of files) {
+  if (path.resolve(file) === path.resolve(TOKENS)) continue;
+  const text = fs.readFileSync(file, 'utf8');
+  const rel = path.relative(ROOT, file);
+  for (const m of text.matchAll(HEX)) {
+    if (!allowed.has(m[0].toLowerCase())) hits.push(`${rel}: raw hex ${m[0]}`);
+  }
+  for (const m of text.matchAll(RGB)) {
+    const norm = m[0].replace(/\s+/g, '').toLowerCase();
+    if (!allowed.has(norm)) hits.push(`${rel}: raw color ${m[0]}`);
+  }
+}
+
+if (!hits.length) {
+  console.log(`token-lint: ok (${files.length} files)`);
+  process.exit(0);
+}
+console.error('token-lint: BLOCK — use semantic tokens from docs/design/tokens.css');
+for (const h of hits.slice(0, 40)) console.error('  ' + h);
+if (hits.length > 40) console.error(`  … +${hits.length - 40} more`);
+process.exit(1);

package/template/.issflow/skills/ui-ux-pro-max/SKILL.md

@@ -66,5 +66,10 @@ python3 .issflow/skills/ui-ux-pro-max/scripts/search.py "<query>" --stack <detec
 4. Then apply `ux-design` authoring (wireframe + cookbook). Catalogue must still
    pass: no emoji icons, tokens not raw hex in components, WCAG AA.
 
-If UX-PACK is already **approved**, read it and stop — unless the human asked to
-change the look.
+If UX-PACK is already **approved**, or STATE `design-direction:` is **locked**,
+read the locked DIRECTION/tokens and stop — unless the human asked to change the
+look (then re-picker + re-approve). Never re-roll styles at `/propose` appendix or
+`/phase` CLOSE.
+
+Direction Picker: fill `.issflow/templates/design/picker.html` placeholders only;
+do not rewrite the template chrome.

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

@@ -47,6 +47,9 @@ 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.
+When `docs/design/tokens.css` exists, components must use those semantic tokens —
+raw hex / off-grid spacing in UI files is a **BLOCK** (run `node scripts/token-lint.js`
+when present). Frontend CLOSE also needs a **task check** for the primary user job.
 
 -----
 

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

@@ -29,10 +29,14 @@ into concrete boundaries the implementer follows per phase.
 - Stores / schemas (high level):
 - Migrations approach:
 
-## Auth & trust boundaries
-- Authn / authz:
-- Secrets:
+## Auth & trust boundaries (decision record)
+- Provider (e.g. Clerk / Auth.js / Supabase / custom / LINE Login):
+- Session model (cookie session / JWT / opaque):
+- Identity linking (e.g. LINE userId ↔ app user):
+- Roles / authz:
+- Secrets handling:
 - Threat notes (STRIDE if security-touching):
+- Open auth questions: none | (list — blocks Architectural approve if material)
 
 ## Integrations
 | Service | Use | Failure mode |