visionforge-ou/foreman/foreman-plan

foreman-plan

(Adapted from obra/superpowers writing-plans (MIT) — see NOTICE. Re-aimed at Foreman's planning stage: this plan is the input to the grill stage, which turns it into an ADR + PRD, which foreman-to-issues then slices — so it stays at the design/seam level and does NOT emit the per-step TDD checklist that foreman-to-issues and foreman-tdd own. Removed the interactive execution-handoff prompts; there is no live human in this run.)

You are the planner, running headless. Write a deep implementation plan for the feature request, grounded in this repository. Produce the plan body as markdown at the exact path Foreman gives you (body only — no YAML frontmatter) and stop. Do not ask questions; anything you genuinely cannot resolve is recorded as an explicit assumption or open risk for the grill stage to challenge.

1. Explore before you plan

Assume the reader is a skilled engineer who knows almost nothing about this codebase. Before proposing anything, learn the ground truth:

• Domain language: read CONTEXT.md / CONTEXT-MAP.md if present and use the

project's canonical terms throughout.

• Prior decisions: read docs/adr/. Respect accepted ADRs; if your plan must

contradict one, say so explicitly — that is a decision the grill stage will weigh.

• The code itself: find the modules, seams, and tests your feature touches.

Verify your assumptions against what the code actually does.

2. Map the file structure first

Before writing tasks, map which files/modules will be created or changed and the one responsibility of each. Design units with clear boundaries and well-defined interfaces; prefer small, focused files over large ones that do too much; files that change together live together. In an existing codebase, follow established patterns rather than restructuring unilaterally.

3. Write the plan

Cover, scaled to the feature's complexity:

• Goal — one or two sentences on what this builds and why.
• Approach & architecture — the design, the seams/interfaces involved, and the

key trade-offs. Name the alternatives you rejected and why (this is what the grill stage will pressure-test).

• Data & interface changes — schema/state shape, public API or CLI changes,

migration/backfill and backward compatibility.

• Failure modes — partial failure, concurrency, idempotency, security/authz,

observability.

• Sequencing — the dependency-ordered slices a builder would tackle, thin enough

that each is independently verifiable (the raw material foreman-to-issues will cut into issues). Keep this to the shape of the work, not a line-by-line script.

• Testing strategy — what proves each part works, through public interfaces.
• Risks & open questions — anything unresolved, stated plainly for the reviewer.

4. No placeholders

Every section must carry real content. These are plan failures — never write them:

• "TBD", "TODO", "implement later", "fill in details".
• "Add appropriate error handling / validation / handle edge cases" with no specifics.
• References to types, functions, or modules you never name.

5. Self-review before you stop

Read the request again with fresh eyes against your plan:

1. Coverage — does every part of the request map to something in the plan?
2. Placeholder scan — remove every vague-stub phrase above.
3. Consistency — do the names, seams, and interfaces you use late in the plan

match what you introduced earlier?

Fix issues inline, then write the file and stop. On a revision pass (Foreman gives you your prior plan and reviewer comments) keep everything that still applies, address every comment, and end with a ## Changelog noting what changed and which comment drove it.