Init

foreman:init — bootstrap a project roadmap

Creates ROADMAP.jsonl and .foreman/config.json at the project root. Both are committed to git — they're a shared project artifact, not personal state. All reads/writes go through ${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js (see "Write phase" below) — it enforces the write invariants (id computation, parse-before/after-write) mechanically, so you don't have to. Skim ${CLAUDE_PLUGIN_ROOT}/roadmap-schema.md if you need field semantics beyond what's obvious from the names (why/what/depends_on/touches).

If args were provided, treat them as the project description seed and skip asking for it in Call 1.

---

Pre-check

If ROADMAP.jsonl already exists at the project root, ask before doing anything else:

Q1 — "ROADMAP.jsonl already exists. What do you want to do?" Options: Overwrite it (start fresh), Keep it, just add to it, Cancel

• Overwrite → continue to Call 1, the draft phase replaces the file.
• Keep, add to it → skip straight to the draft phase, append new entries

instead of replacing, don't touch .foreman/config.json if it already exists (ask the Call 2 questions only if the config file is missing).

• Cancel → stop here.

---

Call 1 — project and goals (batch 2)

Q1 — "What is this project?" Options: I'll describe it (nudge the user to use Other and give a short description — what it does, what stack, new or existing codebase)

Q2 — "What are the near-term goals for the roadmap?" Options: I'll describe them (nudge toward Other — 2-5 concrete things they want to get done soon)

---

Call 2 — the policy toggles (batch 5, these are the key decisions)

Q1 — "Should the roadmap accept Claude-suggested entries after commits?" Options:

• Yes — ask me about opportunities found after each commit — after every

git commit, Foreman's hook will prompt Claude to scan for confirmed bugs/opportunities/ideas from that work and ask what to do with each one.

• No — the roadmap only grows from what I add myself — the commit hook

stays completely silent; nothing gets suggested, ever, until re-run.

Record the answer — it becomes .foreman/config.json's discoverySuggestions field verbatim.

Q2 — "Do other plugins already own the persona or the voice in your sessions? (for example: razor owns persona, hush owns voice)" (multiSelect: true — a project may run one without the other) Options:

• A persona plugin (e.g. razor) — crafted prompts open with domain

framing instead of a "You are a [role]" sentence. Selecting this sets "usePersona": false.

• A voice plugin (e.g. hush) — crafted prompts skip the tone block.

Selecting this adds "tone" to omitSections.

Neither selected means the template's defaults apply unchanged: "usePersona": true, "omitSections": []. Both selected is the full trio shape: "usePersona": false, "omitSections": ["tone"]. Leave output_format alone either way — its default already defers to the session's style, and it is the guard against raw XML tags echoing into chat.

This is a declaration, not detection — Foreman never inspects which plugins the project runs; the user states the shape they want here.

Q3 — "When a commit looks like it finishes a task, should Foreman close it out right away?" Options:

• Yes — mark it done as soon as the commit lands — becomes

"requireVerification": false.

• No — ask me to confirm it's verified first — the commit and its

touched files are still recorded immediately, but the task stays in progress until you confirm the work actually holds up. Becomes "requireVerification": true.

Q4 — "Which model will run the prompts and handoffs Foreman crafts for this project?" Options:

• Haiku — crafted prompts elaborate fully, spelling out details a

stronger model could otherwise infer. Becomes "targetModel": "haiku".

• Sonnet — crafted prompts assemble at today's default level of detail.

Becomes "targetModel": "sonnet".

• Opus — same default level of detail as Sonnet — nothing in Foreman's

benchmarks yet justifies a distinct treatment. Becomes "targetModel": "opus".

• No fixed model / it varies — today's behavior, unchanged. Becomes

"targetModel": "inherit".

fable is the fifth valid value, declared via Other — same default level of detail as Sonnet and Opus (the official Fable prompting guide favors brief steering over enumerated detail).

This is a declaration, not detection — Foreman never inspects which model actually executes a session; the user states the expected target here.

Q5 — "When a tracked task completes but its roadmap entry is still open, what should Foreman do?" Options:

• Nothing — becomes "taskCloseGate": "off".
• Remind me to close it — the task completes normally, with a reminder

surfaced alongside it. Becomes "taskCloseGate": "nudge".

• Block completion until I close it — the task stays incomplete until

the roadmap entry is closed. Becomes "taskCloseGate": "block".

---

Draft phase (no AskUserQuestion)

From the Call 1 answers, draft 3–8 initial ROADMAP.jsonl lines following the schema exactly:

• source: "user" for every entry (nothing Claude-suggested exists yet —

these came from the user's own stated goals).

• status: "planned", depends_on filled in only where one task is

obviously sequential to another (don't invent dependencies that aren't there).

• touches as a best-guess area hint per task, or [] if genuinely

unknown (a brand-new project has no files to point at yet — that's fine).

• ids "001" through "00N" (or continuing past the existing max, if

appending to an existing file per the pre-check).

Present the draft as readable text, one task per line — title plus why — not a raw JSON dump. The user should be able to skim it in a few seconds.

---

Call 3 — approval

Q1 — "Draft roadmap ready above. Proceed?" Options: Looks good, write it, Let me adjust it first

If adjust: gather free-text revisions (add/remove/reword tasks), re-present the updated draft, ask again. Repeat until approved.

---

Write phase

1. If the pre-check chose Overwrite: clear any existing file first —

Bash: > ROADMAP.jsonl (or delete it). roadmap.js add always appends, so a fresh file means ids start at 001 again.

1. For each drafted task, call add with its fields as JSON over stdin:

`` echo '{"title":"...","why":"...","what":"...","source":"user","depends_on":[],"touches":[]}' \ | node ${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js add ` The script computes the id, sets status:"planned", stamps createdat/updatedat`, and validates the file after every write — no manual parsing, no hand-computed ids.

1. Write .foreman/config.json —

{"discoverySuggestions": , "usePersona": , "omitSections": [...], "requireVerification": , "targetModel": "", "taskCloseGate": ""} from the Call 2 answers (skip this file write if the pre-check "keep, add to it" branch found an existing config already).

1. Stage and commit just these two files:

git add ROADMAP.jsonl .foreman/config.json && git commit -m "chore: init foreman roadmap" (Only the files this skill wrote — never a broader git add.)

Report back: task count, discovery-suggestions on/off, and point the user at /foreman:roadmap to pick up the first task.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: V-Songbird
• Source: V-Songbird/foreman
• License: MIT
• Homepage: https://github.com/V-Songbird/foundry

Install and usage instructions live in the source repository linked above.