Produce a user-verified implementation spec that Codex can execute with minimal ambiguity, minimal scope creep, explicit validation, explicit assumptions, a bounded source challenge, and ADRs for durable architectural decisions when needed. Save every final spec using the repo's clear convention or a confirmed destination; save ADR files only when the ADR gate requires one.
Run this preflight before substantive interviewing or repository exploration. A skill cannot change the host's collaboration mode during an active turn, and the user's use of the word "plan" does not prove that native Plan mode is active.
The active Plan-mode interview is read-only. It may inspect repository and external evidence, but it must not create, edit, or persist specs, ADRs, documentation, source files, or other files.
-
Run the native Plan mode preflight above.
-
Classify the requested effort as compact, standard, or deep using the mode table in references/spec-rubric.md.
-
Inspect only the minimum repo context needed to avoid low-value questions. During this pass, note spec and ADR destinations by following references/artifact-destinations.md; defer destination confirmation to the final checkpoint unless that reference requires earlier confirmation.
-
Ask one high-impact question at a time when the answer affects the next decision; batch up to 3 questions only when they are independent and low-friction. In active Plan mode, use request_user_input whenever available. Prefer answering discoverable questions from repo files, ADRs, code search, MCP tools, or web sources instead of asking the user. Use references/question-bank.md for question selection.
-
After each answer or evidence pass, summarize the current understanding, explicit assumptions, and remaining unknowns.
-
Continue until every material requirement, non-goal, edge case, validation path, rollout concern, and ADR implication is source-backed, answered by the user, or explicitly accepted as non-blocking.
-
Draft a spec hypothesis, then challenge it against sources using references/source-challenge.md. Challenge only decisions that materially affect correctness, safety, maintainability, or implementation strategy.
-
Run the ADR gate using references/adr-gate.md. If a durable architectural decision is required, draft the ADR, identify the required ADR path, and mark implementation blocked until acceptance when the spec depends on that decision.
-
If the challenge invalidates a requirement or prior assumption, revise the spec, mark the conflict, or propose a preceding ADR or spec step before implementation.
-
Present a final checkpoint with scope, non-goals, assumptions, open questions, risks, validation plan, source challenge, ADR result, and artifact path basis. Ask whether anything material is missing or wrong. Pause for an explicit answer when a material decision, ambiguous destination, overwrite, new directory, or ADR write is involved, and continue interviewing if a material gap appears.
-
After the checkpoint is verified, prepare the approved spec from assets/spec-template.compact.md, assets/spec-template.standard.md, or assets/spec-template.deep.md. Convert ambiguous requirements into testable acceptance criteria; prefer EARS-like phrasing when behavior must be testable. For compact specs, use artifact_path as the only persisted artifact field.
-
If the user explicitly declined persistence, write no files. Return the full approved spec and any ADR draft in chat, include the companion Codex execution prompt, report Persistence status: declined, and state that normal persistence completion was not met.
-
If native Plan mode is active, do not write the approved artifacts. Report Persistence status: pending Plan-mode exit, then provide this copy-ready save-only continuation with the approved paths substituted:
Exit Plan mode, then persist the approved spec from this conversation to <spec-path>, any required ADR, and the minimal ADR index entry required by the repository's existing convention. Do not implement the feature. Validate the saved artifacts, emit the companion Codex execution prompt, report the persisted paths, and stop.
Stop the turn. This is an approved planning result, not completion of the persistence workflow.
-
On the user's save-only continuation outside Plan mode, persist only the approved spec, any required ADR, and the minimal ADR index entry required by the repository's existing convention. Do not implement the feature or make other repo-facing changes. Validate and report the artifacts, produce the companion Codex execution prompt from assets/codex-execution-prompt.md, and stop.
-
In the documented conversational fallback, save the final spec after checkpoint verification, save an ADR only when the ADR gate requires one, and make the minimal ADR index entry required by the repository's existing convention. If persistence is blocked, return the full save-ready artifact and reason without writing files, include the companion Codex execution prompt, and report normal completion as unmet.
-
Record all repo-facing documentation work other than a convention-required ADR index entry in the spec for later implementation; do not perform it during the Plan interview or save-only continuation.
-
Run a final self-check against references/spec-rubric.md.
No bundled scripts.
When supported native Plan mode is inactive, return only the brief transition explanation and copy-ready /plan command from the preflight.
Do not claim persisted paths or normal completion, and do not emit the implementation execution prompt before the save-only continuation completes. The exception is an explicit persistence decline, which returns the full save-ready artifacts and execution prompt in chat with completion reported as unmet.
Do not paste the full final spec or ADR by default after they are saved. Print full artifact contents only when the user asks, when the environment cannot write files, or when the user needs a review before approval.
