specs/agent-projection/opencode/commands/opsx-new.md

description

description
Start a new change using the experimental artifact workflow (OPSX)

Start a new change using the experimental artifact-driven approach.

OpenSpec store (WealthLedger): Use only wealth-ledger-specs, whose physical root is specs/openspec. Every OpenSpec command that reads or writes specs or changes MUST include --store wealth-ledger-specs; keep this flag on every follow-up. Do not infer a store from cwd, the nearest root, or machine configuration.

OpenSpec version preflight: Before the first OpenSpec command, work from the workspace root and run bash specs/scripts/verify-openspec-version.sh. A missing or mismatched CLI is a blocking result.

Input: The argument after /opsx-new is the change name (kebab-case), OR a description of what the user wants to build.

Steps

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

   Ask the user (open-ended, no preset options):

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

   From their description, derive a kebab-case name (e.g., "add user authentication" → add-user-auth).

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

2. Determine the workflow schema

   Use the default schema (omit --schema) unless the user explicitly requests a different workflow.

   Use a different schema only if the user mentions:

   • A specific schema name → use --schema <name>
   • "show workflows" or "what workflows" → run openspec schemas --json --store wealth-ledger-specs and let them choose

   Otherwise: Omit --schema to use the default.

3. Create the change directory

   openspec new change "<name>" --store wealth-ledger-specs
   

   Add --schema <name> only if the user requested a specific workflow. This creates a scaffolded change in the planning home resolved by the CLI.

4. Show the artifact status

   openspec status --change "<name>" --json --store wealth-ledger-specs
   

   Use the returned planningHome, changeRoot, artifactPaths, and nextSteps instead of assuming repo-local paths.

5. Get instructions for the first artifact The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".

   openspec instructions <first-artifact-id> --change "<name>" --store wealth-ledger-specs
   

   This outputs the template and context for creating the first artifact.

6. STOP and wait for user direction

Output

After completing the steps, summarize:

• Change name and location
• Schema/workflow being used and its artifact sequence
• Current status (0/N artifacts complete)
• The template for the first artifact
• Prompt: "Ready to create the first artifact? Run /opsx-continue or just describe what this change is about and I'll draft it."

Guardrails

• Do NOT create any artifacts yet - just show the instructions
• Do NOT advance beyond showing the first artifact template
• If the name is invalid (not kebab-case), ask for a valid name
• If a change with that name already exists, suggest using /opsx-continue instead
• Pass --schema if using a non-default workflow