codex-sdd:propose

OpenSpec Propose

Context

Propose is the first phase of the OpenSpec workflow. It transforms a raw requirement into a structured proposal.md that defines scope, constraints, and acceptance criteria. This is the "constrain the requirement" step.

Trigger

Any of these patterns triggers this skill:

• User says "openspec propose" or "openspec:propose"
• User describes a new feature or change they want to make
• User says "start a new change" or "new proposal"
• openspec_get_status shows phase is idle and user describes work

Workflow

Step 1: Understand the Requirement

Ask clarifying questions if the requirement is vague:

• What is the business goal?
• What is in scope / out of scope?
• Are there any constraints or acceptance criteria?

Use minimal clarification for straightforward requests. For ambiguous/complex requests, spend more time to nail scope before writing.

Step 2: Detect Existing Layout

Call the openspec_detect_layout tool to check if an OpenSpec structure already exists in the project. If one does, note the existing archives and specs as prior context.

Step 3: Build Context

Call docs_build_context with the requirement keywords before creating the proposal. Also call knowledge_search for the same keywords to find prior pitfalls, decisions, and compatibility notes. Use cited source paths from the context pack in the proposal background or acceptance criteria when they affect scope.

Step 4: Create Proposal

Call the openspec_create_change tool with the requirement description:

openspec_create_change({
  description: "<clear description of the requirement>",
  background: "<optional context>",
  outOfScope: "<optional out-of-scope items>",
  preset: "full"
})

This generates openspec/changes/<changeId>/proposal.md plus the preset artifacts and sets up the v2 state machine.

Step 5: Present for Review

Present the generated proposal to the user. Highlight:

• Change ID: So they can reference it later
• Scope: What will and won't be done
• Next Action: The state machine says what happens next