plan-create

name	plan-create
description	Draft, revise, or update the implementation-ready engineering plan as the Software Architect operator before plan-review. Use when turning an approved spec into `./docs/workflows/{slug}/plan.md`, updating an existing plan, or incorporating accepted plan-review feedback before implementation.

Plan Create

Use this skill as the Software Architect operator playbook.

The operator owns drafting and updating ./docs/workflows/{slug}/plan.md.

Use assets/template.md as the default output skeleton when creating a new artifact. Adapt sections as needed, but preserve the slugged title format.

Requirements:

• derive slug from the workflow dossier or source spec
• update the existing plan in the dossier instead of creating duplicates
• preserve the dossier slug unless the workflow intentionally splits into a new dossier
• start the artifact with the exact H1 # Plan - {slug}
• link to the source spec artifact path in the plan body
• keep the plan self-contained enough that a later engineer can resume from the plan plus the repository without needing run.md
• make clear near the top what changes for the user or system and how successful delivery will be observed
• keep the permanent artifact concise and skimmable by default
• treat ./docs/workflows/{slug}/plan.md as the authoritative execution plan for the workflow
• repo-local PLANS.md may be read as optional project context, but it must not replace this workflow's plan structure, stage contract, or execution control unless the user explicitly asks for repo-native planning mode
• treat the plan as a living current-state document, not an implementation journal
• keep implementation decisions current; once implementation starts, detailed step evidence belongs in execution.md
• define non-obvious terms in plain language instead of assuming prior repo knowledge
• when revising after plan-review, incorporate accepted review outcomes into plan.md
• when the plan is ready for execution, mark that state clearly in the plan body

Operator responsibility:

• draft the source artifact for later review
• do not try to review or approve your own work
• leave material objections for plan-review

Plan boundary:

• use the spec to define what must be true for users
• use the plan to define engineering decisions, sequencing, interfaces, validation, idempotence, and recovery
• use execution.md for checks run, changed areas, remediation history, and deviations during multi-step implementation
• send user-visible behavior, privacy, correctness, or scope gaps back to spec-create

Decision rule:

• if a missing detail affects user-visible behavior, privacy, or correctness, stop and send it back to the spec
• if a missing detail is only needed for implementation, decide it in the plan
• if the plan would introduce a new architectural direction, major architectural constraint, or a new third-party service, SDK, hosted platform, or external tool, treat that as materially important and route it back through the orchestrator for clarification or approval when needed
• when unsure, do not backfill product discovery into the plan; push unclear user-facing contract questions back to the spec

Architecture standard:

• prefer the simplest plan that can credibly satisfy the approved spec
• reuse existing repository patterns, abstractions, and infrastructure before introducing new ones
• justify each non-trivial layer, service, dependency, job, external tool, or abstraction in present-tense terms
• cut any proposed component that cannot be justified by the current spec
• do not add speculative extensibility, future-proofing layers, or optional platformization unless the current spec clearly requires them

Style rule:

• focus on decisions, sequencing, interfaces, validation, and recovery
• prefer compact bullets or short prose blocks over long explanatory narrative
• avoid restating the same intent, dependency, or risk in multiple sections unless the repetition materially improves implementation safety
• make design tradeoffs legible with the shortest explanation that still justifies the choice
• prefer one recommended approach over broad option catalogs unless the decision is still intentionally open

Require these expectations:

• the plan must be restartable from plan.md plus the repository alone
• treat restartability as a hard requirement
• Implementation Decisions, Current Plan, Validation and Acceptance, and Idempotence And Recovery are mandatory current-state sections
• validation should include concrete commands or checks with expected observable outcomes when the project permits them
• accepted review outcomes must be incorporated into the plan before implementation begins
• do not append a long implementation journal to the plan; summarize progress and point to execution.md

Do not:

• restate product policy unless the spec is ambiguous
• mix in brainstorming
• begin implementation
• silently repair product-contract gaps that should have been clarified in the spec
• expand straightforward decisions into essay-style rationale unless the tradeoff is non-obvious or high risk
• introduce architecture that is primarily justified by hypothetical future needs
• duplicate the same control point across multiple layers unless the redundancy is intentional and clearly justified
• repeat spec acceptance criteria only when the repetition materially reduces implementation risk

The output of this stage should be ready for plan-review.