openspec-propose

name	openspec-propose
description	Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
compatibility	opencode

Propose a new change - create the change and generate all artifacts in one step.

I'll create a change with artifacts:

• proposal.md (what & why)
• design.md (how)
• tasks.md (implementation steps)

When ready to implement, run /opsx-apply

---

Input: The user's request should include a change name (kebab-case) OR a description of what they want to build.

Steps

1. If no clear input provided, ask what they want to build

Use the question tool (open-ended, no preset options) to ask:

"What change do you want to work on? Describe what you want to build or fix."

From their description, derive an English kebab-case name that is specific and descriptive:

Naming Rules (MANDATORY):

• Must be in English — if the user provides Chinese/Japanese/Korean input, translate it to English first
• Minimum 3 meaningful words — avoid overly generic names
• Be specific about what is being changed — prefer add-oauth2-login-flow over add-login, prefer fix-race-condition-in-order-processing over fix-bug
• Maximum 8 words — keep it concise but descriptive
• Use lowercase kebab-case — words separated by hyphens

Examples:

User Input	Good Name	Bad Name (too generic)
"添加用户认证"	add-user-authentication	add-auth
"修复订单处理的竞态条件"	fix-order-processing-race-condition	fix-bug
"Improve error handling in API"	improve-api-error-handling	improve-api
"Add Dark Mode"	add-dark-mode-support	dark-mode

IMPORTANT: Do NOT proceed without understanding what the user wants to build.

2. Create the change directory

   node .opencode/skills/openspec-propose/references/new-change.js "<name>"
   

This creates a scaffolded change at openspec/changes/<name>/.

3. Get the artifact build order

   node .opencode/skills/openspec-propose/references/status.js "<name>"
   

Parse the JSON to get:

• applyRequires: array of artifact IDs needed before implementation (e.g., ["tasks"])
• artifacts: list of all artifacts with their status and dependencies

4. Create artifacts in sequence until apply-ready

Use the todowrite tool to track progress through the artifacts.

Loop through artifacts in dependency order (artifacts with no pending dependencies first):

a. For each artifact that is ready (dependencies satisfied):

• Get instructions: bash node .opencode/skills/openspec-propose/references/instructions.js <artifact-id> --change="<name>"
• The instructions JSON includes:
  • context: Project background (constraints for you - do NOT include in output)
  • rules: Artifact-specific rules (constraints for you - do NOT include in output)
  • template: The structure to use for your output file
  • instruction: Schema-specific guidance for this artifact type
  • outputPath: Where to write the artifact
  • dependencies: Completed artifacts to read for context
• Read any completed dependency files for context
• Create the artifact file using template as the structure
• Apply context and rules as constraints - but do NOT copy them into the file
• Show brief progress: "Created "

b. Continue until all applyRequires artifacts are complete

• After creating each artifact, re-run node .opencode/skills/openspec-propose/references/status.js "<name>"
• Check if every artifact ID in applyRequires has status: "done" in the artifacts array
• Stop when all applyRequires artifacts are done

c. If an artifact requires user input (unclear context):

• Use the question tool to clarify
• Then continue with creation

5. Show final status

   node .opencode/skills/openspec-propose/references/status.js "<name>"
   

Output

After completing all artifacts, summarize:

• Change name and location
• List of artifacts created with brief descriptions
• What's ready: "All artifacts created! Ready for implementation."
• Prompt: "Run /opsx-apply or ask me to implement to start working on the tasks."

Artifact Creation Guidelines

• Follow the instruction field from the instructions output for each artifact type
• The schema defines what each artifact should contain - follow it
• Read dependency artifacts for context before creating new ones
• Use template as the structure for your output file - fill in its sections
• IMPORTANT: context and rules are constraints for YOU, not content for the file
• Do NOT copy context, rules blocks into the artifact
• These guide what you write, but should never appear in the output

Guardrails

• Create ALL artifacts needed for implementation (as defined by schema's apply.requires)
• Always read dependency artifacts before creating a new one
• If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
• If a change with that name already exists, ask if user wants to continue it or create a new one
• Verify each artifact file exists after writing before proceeding to next