create-issflow 1.6.0 → 1.7.0

package/README.md

@@ -31,7 +31,7 @@ Flags:
 The portable kit (every tool) in `<project>/.claude/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
-- `commands/` — `/overview` `/feature` `/propose` `/phase` `/sprint` `/ui-audit` `/qa-audit` `/security-audit` `/release` `/uat` `/change-request` `/replan` `/quick` `/synthesize` `/runbook` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
+- `commands/` — `/overview` `/feature` `/goal` `/propose` `/phase` `/sprint` `/ui-audit` `/qa-audit` `/security-audit` `/release` `/uat` `/change-request` `/replan` `/quick` `/synthesize` `/runbook` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
 - `skills/` — caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards
 - `hooks/` — session-start · context-guard · plan-gate (rule-13 enforcement) · pre-compact · subagent-stop · feature-gate (Stop gate for `/feature`, artifact-verified)
 - `istartsoft-flow/METHODOLOGY.md` — the full methodology (single source of truth)

package/bin/cli.js

@@ -217,9 +217,9 @@ function agentsMd() {
     '## Roles — `.claude/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
-    '/overview · /feature · /propose · /phase · /sprint · /ui-audit · /qa-audit · /security-audit ·',
-    '/release · /uat · /change-request · /replan · /quick · /synthesize · /runbook · /store-wisdom ·',
-    '/log-issue · /log-decision · /unstuck', '',
+    '/overview · /feature · /goal · /propose · /phase · /sprint · /ui-audit · /qa-audit ·',
+    '/security-audit · /release · /uat · /change-request · /replan · /quick · /synthesize ·',
+    '/runbook · /store-wisdom · /log-issue · /log-decision · /unstuck', '',
     '## Skills — `.claude/skills/` (loaded on demand)', '',
     'caveman · grill-me · karpathy-guidelines · ux-design · security (Secure SDLC) · code-standards', '',
     '## Autonomy', '',
@@ -237,7 +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',
@@ -318,7 +320,10 @@ function main() {
 
   // 3b. headless feature lane (opt-in): materialize the automation templates.
   const autoDir = path.join(TPL, '.claude', 'templates', 'automation');
-  if (CI) writeFile(path.join('.github', 'workflows', 'issflow-feature.yml'), fs.readFileSync(path.join(autoDir, 'issflow-feature.yml'), 'utf8'));
+  if (CI) {
+    writeFile(path.join('.github', 'workflows', 'issflow-feature.yml'), fs.readFileSync(path.join(autoDir, 'issflow-feature.yml'), 'utf8'));
+    writeFile(path.join('.github', 'workflows', 'issflow-goal.yml'), fs.readFileSync(path.join(autoDir, 'issflow-goal.yml'), 'utf8'));
+  }
   if (DOCKER) {
     writeFile('Dockerfile.issflow', fs.readFileSync(path.join(autoDir, 'Dockerfile'), 'utf8'));
     writeFile(path.join('scripts', 'feature-docker.js'), fs.readFileSync(path.join(autoDir, 'feature-docker.js'), 'utf8'), { exec: true });
@@ -341,6 +346,7 @@ function main() {
   for (const w of warnings) log(`  ! ${w}`);
   log(NEXT_STEPS[TOOL] || NEXT_STEPS.claude);
   if (!CI && !DOCKER) log('Headless feature lane: re-run with --ci (GitHub Action) and/or --docker (container runner).');
+  log('New to the kit? Plain-language guide (EN/TH): https://iamstarter.github.io/istartsoftflow/how-to-use.html');
 }
 
 main();

package/package.json

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

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

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

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

package/template/.claude/commands/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/session-start.js

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

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

@@ -258,6 +258,20 @@ can. Escalation is at most two hops.
 
 The orchestrator ROUTES. It does not implement or debug.
 
+**Model routing (per-role tiers).** Each role's `.claude/agents/<role>.md` pins a
+`model:` tier suited to its work, so the RIGHT model runs each task by default:
+
+| Role | `model:` | Why |
+|------|----------|-----|
+| planner · debugger · implementer · test-author | `inherit` | hardest reasoning — follows the session model the OWNER picked (`/model` / `--model`), so one choice cascades |
+| researcher · e2e-runner | `sonnet` | judgment-heavy but mid-tier is the sweet spot |
+| synthesizer | `haiku` | mechanical compression — cheapest tier |
+
+Owner wants a SPECIFIC model? Edit the role's `model:` line — values `haiku` ·
+`sonnet` · `opus` · `inherit` · or a full model id. The installer is
+non-destructive, so your pins survive kit updates. Hosts without per-agent model
+support run everything on the session model (graceful degrade).
+
 -----
 
 ## Procedures (the slash-command set)
@@ -272,6 +286,7 @@ Named procedures, each with a canonical body in `.claude/commands/<name>.md`.
 | 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
@@ -287,6 +302,12 @@ surface or need its own acceptance criteria? -> `/feature`. Otherwise `/quick`.
   story into a PENDING doc (approval stays human). Gate checklist in
   `docs/features/<slug>/GATES.md`, enforced by the `Stop` hook with artifact
   verification. Headless-capable (CI / Docker, `ISSFLOW_HEADLESS=1`). See "Feature lane".
+- **goal [set|run|status|done|drop]** — the goal layer: declare an OUTCOME with a
+  measurable Done-when + budget (`set`, behind the rule-14 brief-back), then
+  `run` loops pick-next-unit → route lane → tick until done / budget / hard-stop.
+  Goal-driven, not time-driven: it stops itself on the finish line. Recurrence is
+  host-level (interval loop or the cron-ready `issflow-goal.yml`). `docs/GOALS.md`
+  holds state; its `Approved:` line arms headless passes.
 - **propose** — turn approved requirements + stack into `PROPOSAL.md` (scope, phase
   breakdown, effort + cost estimate, assumptions) with a client sign-off gate.
 - **change-request** — a mid-project scope change: impact analysis + re-estimate +
@@ -441,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.
@@ -505,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.
 
 -----
 
@@ -561,10 +592,13 @@ the KB. The kit works normally without a KB.
   `BLOCKED.md` (headless blocker reports).
 - `docs/WISDOM-QUEUE.md` — auto-appended wisdom candidates from feature runs;
   `/store-wisdom` reads it before pushing to the shared KB (push stays human).
-- `.claude/templates/automation/` — headless-runner sources (GitHub Action ·
+- `.claude/templates/automation/` — headless-runner sources (GitHub Actions ·
   Dockerfile · docker wrapper), materialized by `create-issflow --ci` /
-  `--docker` as `.github/workflows/issflow-feature.yml` · `Dockerfile.issflow` ·
-  `scripts/feature-docker.js`.
+  `--docker` as `.github/workflows/issflow-feature.yml` +
+  `.github/workflows/issflow-goal.yml` (cron-ready, disarmed by default) ·
+  `Dockerfile.issflow` · `scripts/feature-docker.js`.
+- `docs/GOALS.md` — the goal layer's state: one `## G<n>` block per goal
+  (Done-when · Budget · `Approved:` line · progress ticks). Maintained by `/goal`.
 - `.claude/templates/FEATURE-template.md` — the Feature-doc form `/feature new`
   scaffolds (Approval/Automation headers + spec sections).
 - `docs/STATE.md` — current position. Small. Rewritten, not appended.

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

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

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

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

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

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

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

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