MasterMind: Blueprint

The plan turns the spec's what into a how that can be checked against the constitution before a line is written. Layout and IDs: ~/.mastermind/engineering/core/spec-driven.md. Input: $ARGUMENTS.

Before planning

1. Find the feature folder and read spec.md in full, plus specs/constitution.md, specs/tech.md, and the active field's stack-defaults.md when a field pack exists.
2. Refuse to plan over open questions. If [NEEDS CLARIFICATION] markers remain, run interview first. When the user insists on skipping, proceed and record the open markers as risks in plan.md.
3. Run the constitution gate. For each principle, write pass, n/a or violates in the plan's gate table. A violation stops the plan until the user accepts it in the complexity table.

Plan

Write plan.md from specs/.templates/plan.md if present, else template.md. Then:

1. Technical context. Language, dependencies, storage, testing, platform, performance and scale targets. Each value comes from tech.md, the code, or a decision you make in step 2.
2. Research the unknowns. One entry in research.md per real decision: chosen, why, rejected and why. Read the primary source for anything version-sensitive (learn). Library choices with real adoption risk go to the tech-scout agent.
3. Design. Dispatch the architect agent with the spec, the constitution and tech.md. Its output becomes the plan's design section. Keep the boundaries, data model, contracts and the reason for each. Where no isolated agent exists, follow architect's method yourself and say so in the plan.
4. Write what the design implies, each only when it has content:
   • data-model.md: entities with fields, validation rules taken from the spec, relationships, state changes.
   • contracts/: every interface another system or user depends on, in the form the project already uses, or a plain table when it has none.
   • quickstart.md: the runnable steps that prove the feature works end to end, with expected output. A short script is allowed when steps alone cannot drive it.
5. Name the real paths. The structure section lists the actual directories and files to create or change in this repository. Never a generic layout.
6. Name what the spec implies but never says. A reasonable user expects some inputs handled that no requirement and no edge case names. List up to five of them, such as an empty name, a double submit or a timezone at midnight. Add each to the plan's risks and give it a task in breakdown. A spec's silence is not permission to crash.
7. Re-run the gate against the finished design. Set the spec's status to planned.

Gotchas

• The plan is not the code. No function bodies, no full migrations, no test suites. Signatures and shapes only; the code is build's job. A plan longer than the spec it serves is a sign it wrote code.
• Failure is not cancellation. In a state model, a failed attempt, a retry and a cancelled one are different states, and every retry names the state it re-enters.
• Every decision traces to a requirement. A dependency, service or layer nobody asked for goes in the complexity table with the simpler option it beat, or it goes.
• Match the repository. A plan that introduces a second ORM, router or state library has to justify it against the one already there.
• A requirement the plan cannot meet is a finding, not a footnote. Report it to the user before breakdown runs.

Report

The files written, the decisions with one-line reasons, the gate result before and after design, any accepted violation, and the next step: breakdown, or checklist first for a sensitive feature.

Then run mastermind next and end with the step it names, so the user sees where the feature stands.