plan-implementation

name

plan-implementation

description

Create or revise an approved mechanical execution contract from accepted docs/concept/ by choosing and verifying the stack, defining validation gates, updating AGENTS.md Project Specifics and BUILD_STATE.md, and conditionally creating or revising DESIGN.md and ROADMAP.md. Use for initial operational planning, explicit re-planning of an operationally planned project, or when new architecture, phases, slices, roadmap order, or release gates must be resolved without writing product code.

Plan Implementation

Turn accepted product intent into a mechanical execution package, or revise that package when implementation reality requires explicit re-planning. Resolve the technical strategy here so implementation agents can execute verified slices without inventing product or architecture decisions.

Enter the stage

1. Read AGENTS.md, inventory .agents/, and read every file in docs/concept/.
2. Require docs/concept/README.md to say Ready for operational planning for an initial plan, Ready for operational re-planning after accepted product intent changed, or Operationally planned for explicit mechanical re-planning. During either re-planning path, preserve the existing package and change only what the approved planning scope requires. If material product contradictions remain, return to /shape-concept instead of resolving them as technical choices.
3. Inspect the repository and existing mechanical files. Treat absent BUILD_STATE.md, DESIGN.md, and ROADMAP.md as normal only during initial planning; during re-planning, reconcile existing files rather than replacing them wholesale.
4. Separate product decisions from technical decisions, research gates, and implementation sequencing.

Resolve the technical strategy

Determine only what execution needs:

• system shape and component boundaries;
• stack, package manager, runtime, and supported environments;
• exact install, format, lint, typecheck, test, run, build, and packaging commands that actually apply;
• architecture, security, tenancy, data, migration, and deployment constraints;
• ordered validation gates and evidence expectations;
• locally authored project-skill needs; and
• implementation phases, slices, go/no-go gates, and stop conditions when the work is too large for one immediate milestone.

Use current primary documentation for factual stack claims. Never invent a command. Mark unresolved choices and research them before proposing the contract. Do not install dependencies, initialise frameworks, create source code, or run mutating setup commands during planning.

Propose before writing

Return a compact proposal containing:

• System: the recommended shape and why it fits the concept.
• Toolchain: exact intended commands and their evidence source.
• Mechanical package: BUILD_STATE.md always; DESIGN.md and ROADMAP.md only when their gates below are met, preserving existing human additions during re-planning.
• Tension: the single most important unresolved technical trade-off, if any.
• Decision: one approval or clarification needed before writing.

Keep ordinary responses under 200 words. Expand only when the user asks for the technical comparison or research detail. Do not write the mechanical package until the user approves the proposal.

Generate the execution package

After approval:

1. Update only the Project Specifics region of AGENTS.md with the descriptor, toolchain, ordered validation gates, and stack-specific rules.
2. Create or reconcile BUILD_STATE.md with a lean Now, Decisions, Session log, and Archive. Set the current milestone, planning evidence, one executable next step, and blockers. Do not copy the full plan into Now, erase verified history, or report planning work as implemented behaviour.
3. Create or revise DESIGN.md only when the accepted concept contains a meaningful visual, interaction, content-design, or other medium-specific design contract. Derive semantic tokens and rationale from the concept without inventing decoration, and preserve compatible human additions.
4. Create or revise ROADMAP.md only when execution requires multiple ordered slices, phases, migrations, research or evaluation gates, release gates, or explicit stop conditions. Keep the current position in BUILD_STATE.md and future sequence in ROADMAP.md. Size each slice as one small, independently verifiable implementation checkpoint that ordinarily fits one focused session. Split setup work when its outcome or validation would otherwise combine several distinct changes.
5. Record approved technical decisions and unresolved external gates. Do not turn product ambiguity into implementation discretion.
6. Set or retain the concept index status as Operationally planned while preserving the accepted concept content.

Readiness gate

Before recommending implementation, verify:

• every declared command is sourced or verified and no required command is blank;
• validation gates are ordered and capable of proving a slice against reality;
• component boundaries and high-risk constraints are explicit;
• every roadmap slice has an observable outcome and verification method;
• every roadmap slice is small enough to finish and verify as one checkpoint;
• BUILD_STATE.md points to exactly one next step;
• DESIGN.md and ROADMAP.md exist only when justified; and
• a contradiction, duplication, stale-reference, canonical-name, and source audit is clean across all concept and generated files. Search for superseded project names and headings explicitly instead of assuming linked files agree.

Approval of the proposal authorises generation in the current turn. After applying the package, present the resulting diff and readiness evidence. Then stop before implementation and tell the user to start a fresh session with: Continue from BUILD_STATE.md.

Boundaries

• Do not edit the universal baseline above the Project Specifics marker.
• Do not create product source code, tests, infrastructure, or dependencies.
• Do not commit, push, deploy, or contact external services.
• Do not create remote-derived skills. Recommend a narrow locally authored skill contract when repeatable project behaviour warrants one.
• Do not create prompt.md. AGENTS.md owns startup behaviour and BUILD_STATE.md owns current execution state.