# Discovery during execution

During the task, retain concrete bugs, design ideas, optimization opportunities,
and other improvements observed beyond its scope. Before reporting completion,
review these findings even after an investigation or work without a commit.
Include findings returned by subagents. Use evidence already observed: paths,
symbols, behavior and impact. A concrete missing behavior or improvement can
qualify without being a reproduced bug; label uncertainty and propose an
investigation when the cause is unknown. Do not launch another audit or invent findings.

In the executing project, require `ROADMAP.jsonl` and honor
`.foreman/config.json`'s `discoverySuggestions:false`. A missing setting defaults
to enabled. If disabled or no roadmap exists, skip this discovery workflow.

A background subagent returns candidates and evidence to its coordinator;
it must not discard them, ask the user, or add entries itself. The coordinator
or user-facing executor handles the following steps:

1. Run `roadmap.js check-duplicate` with each candidate's title and why before
   offering it. Suppress rejected matches; for other existing matches, reference
   the entry only when new evidence adds something. Do not repeat a proposal
   already answered or pending in this conversation.
2. For each unmatched candidate, explain the finding and ask the user:
   **Add to roadmap / Execute here / Execute with a background subagent / Reject**.
   Use the active host's available question mechanism, or ask a concise
   plain-text question if no suitable tool is available. Wait for a decision before adding
   inferred work or expanding scope; honor an explicit decision already given.
3. Add uses `roadmap.js add` with `source:codex-suggested` and `status:planned`.
   An explicit Reject uses the same call with `status:rejected`. Execute choices
   authorize only the chosen finding and destination; follow the normal execution
   workflow and do not infer permission to create a sidebar task.

Use the currently installed Foreman `scripts/roadmap.js`, resolving its location
from the loaded Foreman skill. Supply JSON safely through a UTF-8 payload file
or safely quoted stdin. Write dense why/what from existing evidence.

For separate authorized work already implemented inline, offer **Log it / Skip**.
Only on Log it, add and record its actual completion and evidence, honoring
`requireVerification` and never inventing a commit. Discovery does not reopen
the original task or replace its acceptance. Say nothing when there are no
concrete, untracked candidates.

# Selectable questions in Codex

Use this protocol for Foreman's questions in Codex: task selection, execution
preferences, and the other choices a flow asks for. Ask one picker at a time:
collect the task, then the destination, skipping either already specified by
the user; a batch of questions becomes consecutive pickers when the tool takes
one at a time. A preference needed to continue this flow is not an approval
request merely because Foreman waits for it.

For a handoff carrying `reviewEachIncrement:true`, use the result-specific
[review protocol](../roadmap/increment-review.md). Its Accept / Request changes /
Pause choices replace recommendation labels: do not mark Accept as recommended.
A preselected option is never a submitted answer. The same answer handling and
text fallback below still apply.

## Choose the tool

Prefer `request_user_input_async` when exposed and permitted by the current
host. Submit one `questions` item with a self-contained `title` and an `options`
array of visible choice strings. Include the task id or destination in each
option, followed by a brief explanation. Put the recommended option first and
mark it `(Recommended)`; keep the remaining options in their relative order.
The user can also answer in free text. Do not add an Other placeholder.

For example, the async payload for a task menu has this shape; replace the
example rows with the actual CLI menu fields:

```json
{"questions":[{"title":"Which task next?","options":["002 - Clarify the profile (Recommended) - Helps recruiters understand your work; unblocks six tasks.","006 - Remove legacy models - Removes unused assets; unblocks three tasks."]}]}
```

If only `request_user_input` is usable, follow its different schema and current
mode restrictions. It can be Plan-only; being listed does not authorize calling
it in another mode. Do not switch modes just to display a picker.

Fit the usable tool's option limit with grouped or paged selectable menus.
For task pages, preserve CLI order and include a More tasks choice until every
row is reachable. For the four destinations, use the grouping described in
[destination-question.md](../roadmap/destination-question.md). A smaller option
limit alone is not a reason to replace the picker with text.

## Collect the answer

Actually call the tool; writing a menu in a message does not create a picker.
With the async tool, `accepted:true` acknowledges submission only. The answer
arrives in a later user message. Continue useful independent preparation or
use an available interruptible wait in intervals of at most 60 seconds. Keep
the choice pending; do not finalize with "Select an option above", resubmit
the same pending question, or advance on a timer or preselected recommendation.
For a synchronous tool, consume its returned answer. Honor free-text choices
and changed preferences just as selected options.

Do not append "Foreman requires this question" or a skill citation to routine
pickers. Once answered, continue the flow without requesting the same choice
again. Ask a focused clarification only when the answer is ambiguous.

If no permitted question tool exists, a call fails, or the user reports a
missing picker, briefly explain the concrete limitation and ask a self-contained
question using the host's allowed text format. Never refer to invisible options
or claim a modal appeared based only on a submission acknowledgment.

# Running Foreman

Foreman runs in Claude Code and in Codex from the same files. Every rule here
applies to both hosts unless a paragraph names one. A handoff adds the goal,
evidence, constraints, and completion criteria to the destination's own
instructions; it does not replace them or select a fixed model.

## Paths

`${CLAUDE_PLUGIN_ROOT}` in a command means Foreman's plugin root, the directory
that holds `scripts/`, `hooks/`, and `skills/`. In Claude Code the harness fills
it in. In Codex, resolve it from the loaded skill's actual location: a skill at
`<plugin-root>/skills/<name>/SKILL.md` belongs to `<plugin-root>`. Replace the
variable with that absolute path and quote it for the active shell; do not
assume the shell defines a plugin-root variable. Supporting references are
relative to the file that links them.

The project directory is separate: scripts resolve `FOREMAN_PROJECT_DIR`, then
`CODEX_CWD`, then `CLAUDE_PROJECT_DIR`, then the shell working directory. Run
commands in the user's project.

## JSON payloads

Commands show their JSON after `echo` for readability. Never interpolate
user-written text into a shell command: send that JSON through a quoted heredoc
(`<<'EOF'`), a PowerShell literal here-string (`@'...'@`), or a UTF-8 payload
file piped to the script. Use the execution and patch tools the host actually
provides rather than tools named for the other host.

## Roadmap stores

Every roadmap, archive, or lesson-store read and mutation goes through
`node ${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js <verb>`. The same CLI owns id
allocation, validation, locking, migration, and compare-and-set guards. Read
[the schema](../../roadmap-schema.md) only when a field needs explanation, and
use `--help` for exact payloads. Do not edit those stores by hand.

## Intent and questions

An explicit request to add, correct, defer, archive, or restore specified work
already authorizes that mutation. Do it, show the concrete result, and do not
ask for the same permission again. Ask when Foreman inferred or proposed the
change, when the request leaves the target or the new value open, or when the
change would go beyond what the user named. Inferred new work and unresolved
product choices need the user's decision unless the current conversation
already provides it; destructive replacement and final acceptance always need
the user's own explicit decision.

Ask workflow choices directly, without saying Foreman requires a question or
citing a skill as the reason to choose. Honor choices already supplied, and do
not treat an unanswered question as approval.

- In Claude Code, ask with `AskUserQuestion`: at most four options per question,
  each a label plus a description. It appends its own free-text option, so never
  author one.
- In Codex, use the picker and answer handling in [questions.md](questions.md).
- With no usable question tool, ask one self-contained plain-text question and
  never refer to options the user cannot see.

Acceptance is distinct from implementation completion: `requireVerification`
defaults to true, so finished work records `awaiting_acceptance` until the user
accepts it. Never interpret a test passing, a subagent finishing, or a new pick
request as that acceptance.

## Work and delegation

Honor the user's destination, or ask Foreman's shared
[destination question](../roadmap/destination-question.md) before crafting the
handoff. A background agent shares this working tree: it must not switch
branches or commit checkpoints. It inherits the model and
reasoning settings unless the user chose otherwise.

- In Claude Code, a background agent is an `Agent` call with
  `run_in_background: true` and no `model`, dispatched without `isolation`.
  Its own handoff opens and closes its roadmap entry. Never call `mcp__ccd_session__spawn_task`: tasks spawned through it don't get
  MCP tools.
- In Codex, honor applicable `AGENTS.md` files, the current mode, available
  tools, and existing authorization, and leave general planning and tool use to
  Codex's native behavior. Inside the chosen destination, use available
  collaboration subagents for concrete independent subtasks alongside useful
  coordinator work, giving each a bounded scope, relevant evidence, expected
  output, and verification; wait for them and integrate their results before
  claiming the task done. If optional internal delegation is unavailable, handle
  that subtask locally. If the user selected a background destination that is
  unavailable, disclose it and offer a prompt artifact or another destination;
  do not start local execution without the user's choice. Subagents and
  user-owned Codex tasks are different destinations.
  Create a new sidebar task only when the user explicitly requests one.
  A subagent id can be resumed only
  while the current host still knows it. A subagent stages and commits nothing;
  the coordinator owns integration, roadmap transitions, and final acceptance.

## Bookkeeping and commits

Crafting or copying a prompt leaves its entry `planned`; the session that
actually starts the work opens it.

- In Claude Code, Foreman's hooks carry that lifecycle: creating a task whose
  description names an entry opens it, completing that task gates its close, and
  session start surfaces unfinished work.
- In Codex, when execution of a selected entry begins, run
  `node ${CLAUDE_PLUGIN_ROOT}/hooks/codex-task.js start --id <id>` and proceed
  only after exit 0 and `dispatchReady:true`. Blocked, deferred, or terminal work
  is not dispatchable; inspect the returned reason instead of bypassing the
  check. Before reporting a completed entry, run the companion `check --id <id>`;
  a failed check arms the optional Stop reminder for this session. At a flow's
  entrance, surface unfinished or awaiting work from compact CLI reads when the
  session-start hook has not already done so, and read lessons for the task's
  paths with `roadmap.js notes --paths <comma-joined paths>` when useful. After a
  commit the hook did not handle, use
  `list --status in_progress,awaiting_acceptance --summary` to find the entries
  it implements. Hooks add assistance, but these explicit calls remain part of
  the flow, and a warning is not evidence of completion or acceptance.

Respect the user's branch restrictions before every mutation. Never switch,
merge, or commit on a protected branch — one the user said not to modify, or
one the host or repository marks as protected; if a writable branch is needed,
create a descriptive branch first (`codex/<descriptive-name>` in Codex). Keep parent
repositories and submodule pointers outside the task untouched.

Task commits use `scripts/safe-commit.js`: `begin` before changes and `finish`
after verification, with the returned baseline and the owned file surface. A
`dirty:true` start means no automated commits; Foreman's own bookkeeping comes
back under `ledger_dirty` and does not count. A moved HEAD, unexpected files, or
failed staging needs inspection, never a broader staging command.

Every roadmap-owned commit carries the exact final trailer `Foreman: <id>`. For
a staged close, `finish --no-commit` stages the owned work, `update-status` with
`staged:true` includes the close, then one commit carries that trailer. Record
follow-up commits without changing `awaiting_acceptance` to `done`. Record
model and effort only as the executing environment knows them — a Claude family
label (`haiku`, `sonnet`, `opus`, `fable`) in Claude Code, the exact model id in
Codex — and omit unknown values.

## Discovery

With `discoverySuggestions` on (the default), concrete findings outside the
task's scope become roadmap suggestions. In Claude Code, the commit hook raises
them after each commit. In Codex, follow [discovery.md](discovery.md) before
reporting completion, including investigations and work without a commit; the
`start` and `check` results carry the same reminder.

## Trial events

Trial logging is local and opt-in: every call is a no-op unless the project set
`trialLog`, and a failure to record never interrupts work. Record only events
that actually occurred. `question_asked` is one question interaction the user
saw: one `AskUserQuestion` call in Claude Code, however many questions it
batches; one picker call or one plain-text question in Codex. A skipped question
is never logged. Log counts, booleans, ranks, and the writer's closed vocabulary
only; never task text, paths, or user input.

---
name: foreman
description: "The one entrance to Foreman, which keeps a project's plan and task history. Say what you want in plain language and this routes it to one of the six things Foreman does to a project: add work, show status, correct work, check the roadmap, pick work, or reconcile and pick. It owns no flow of its own. Use for Foreman or roadmap requests, not ordinary implementation work."
when_to_use: "Trigger on any plain-language Foreman request that does not already name a command — \"what should I work on\", \"add this to the roadmap\", \"where does the project stand\", \"that entry's description is wrong\", \"my roadmap is broken\", \"is the roadmap file healthy\", \"check the roadmap's still right and then give me something\", \"foreman\" on its own, or invokes /foreman:foreman. Skip it when the user named the specialized skill they want (/foreman:roadmap, /foreman:survey, /foreman:init, /foreman:craft-prompt) — go straight there."
argument-hint: "<what you want, in plain language>"
allowed-tools: AskUserQuestion, Skill, Read
---

# foreman — the one entrance

Foreman runs in Claude Code and in Codex. Every step applies to both unless it names a host. Read [the shared runtime](runtime.md) first: it covers plugin paths, JSON payloads, questions and authorization for both hosts.

This skill routes. It does not add, pick, correct, or survey anything
itself, and it never reads or writes `ROADMAP.jsonl`. Every step
of every flow lives in the skill that owns it; duplicating any of it here
would give Foreman two versions of the same truth. Classify the request,
say in one short line which flow is taking it, then hand off and let that
skill run from its own first step.

## The six intents

| The user says something like… | Intent | Route to |
| --- | --- | --- |
| "add this", "put X on the roadmap", "we also need to…", "track this for later" | **add work** | `foreman:roadmap` → "Branch: Add a task" ([add.md](../roadmap/add.md)) |
| "where are we", "roadmap status", "what's left", "what's waiting on me" | **show status** | `foreman:roadmap` → "Branch: Review status" ([status.md](../roadmap/status.md)) |
| "that entry is wrong", "reword 003", "retarget 007 at the proxy", "its description is stale" | **correct work** | `foreman:roadmap` → "Branch: Correct a task" ([correct.md](../roadmap/correct.md)) |
| "my roadmap is broken", "check the roadmap", "is the roadmap file healthy" | **check the roadmap** | `foreman:roadmap` → "Branch: Check the roadmap" ([doctor.md](../roadmap/doctor.md)) |
| "what's next", "pick a task", "something quick on auth", "give me work" | **pick work** | `foreman:roadmap` → "Branch: Pick the next task" ([pick.md](../roadmap/pick.md)) |
| "is the roadmap still accurate — then give me something", "double-check the top tasks before I start", "audit it and pick" | **reconcile and pick** | `foreman:roadmap` → "Branch: Pick the next task", its reconcile path ([pick.md](../roadmap/pick.md), which runs [survey](../survey/SKILL.md) first) |

Each route reads [the roadmap skill](../roadmap/SKILL.md) and then the linked
branch file.

Notes that change how a route is handed over:

- **pick work** is **Fast pick**, the default confidence mode and the sense of
  a bare "what's next": that branch deliberately does not investigate the
  codebase. Don't promote it to **reconcile and pick** because the roadmap
  looks old — the user asks for that or it doesn't happen.
- **reconcile and pick** is the other confidence mode, **Reconcile and pick**
  — survey and pick in sequence, nothing new. The pick branch owns that
  sequence: it takes the near-term set from its own menu, hands it to
  `foreman:survey`, which ground-truths those entries and applies only the
  repairs the user authorizes, then picks from the repaired roadmap. Say up
  front that the reconcile half costs real tokens, since that is the whole
  difference from a plain pick.
- **check the roadmap** is a structural check — is the file itself well
  formed (duplicate ids, broken dependency edges, a stale schema version)
  — not a check against the codebase. That's the difference from
  **reconcile and pick**: this one never touches `foreman:survey` and never
  leads into a pick unless the user separately asks for one.
- Four of the five roadmap intents can also be reached by the user picking
  from `foreman:roadmap`'s own menu; **check the roadmap** is phrase-reached
  only. Route to the branch when the request already names one; hand over
  without a branch when it genuinely doesn't.

## When the request fits two intents

When two intents fit and the distinction changes the work, ask one concise
question naming the closest two intents in the user's own terms —
`AskUserQuestion` in Claude Code, the picker in [questions.md](questions.md) in
Codex. Never a menu of all six, and never a guess dressed up as a route. Then
hand off to the one they pick. Skip the question when the intent is clear.

The pairs worth expecting: "what's next" after describing new work (add
work vs. pick work), "the plan looks off" (correct work vs. reconcile and
pick), and "sort out what's next" (pick work vs. reconcile and pick).

## Anything else is out of scope here

This entrance covers those six intents and nothing else. When a request
falls outside them, name the skill that owns it in one line and stop —
don't stretch a route to fit. If the user names a specialized skill, go
straight to it.

- setting a project up for the first time, or re-initializing it —
  `foreman:init` ([init](../init/SKILL.md)).
- explicitly building or refining a handoff prompt for something that isn't a
  roadmap entry — `foreman:craft-prompt` ([craft-prompt](../craft-prompt/SKILL.md)).
- accepting, resuming, deferring, archiving, or restoring entries — those live
  inside `foreman:roadmap`'s branches above; route to the intent that carries
  them rather than describing the mechanics here.
- anything that isn't a Foreman request at all — this skill has no opinion
  on it and shouldn't have taken the turn.