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

description

description
Start a change and draft its first planning artifact

Start a WealthLedger OpenSpec change and draft only its first currently ready planning artifact. This workflow authorizes planning only and never implementation.

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.

Approval boundary: Create at most ONE planning artifact per invocation. After showing it, STOP for explicit Change Owner approval. File existence or OpenSpec done status is not approval. If approval of a dependency cannot be established from the current conversation, ask again before creating a downstream artifact.

Planning gate: After writing or editing the one artifact and before requesting approval, run bash specs/scripts/verify-openspec-planning.sh "<name>". Fix structural failures and rerun the available stage checks. Structural success does not grant approval; a semantic mismatch returns to the earliest affected artifact and invalidates dependent approvals.

Input: A kebab-case change name or a description of the intended change.

Steps

1. Understand the intent. If material scope, observable behavior, compatibility or acceptance criteria are ambiguous, ask before writing. Derive a kebab-case name when needed.

2. Use the configured default schema unless the user explicitly names another schema. To show available schemas, run openspec schemas --json --store wealth-ledger-specs and let the user choose.

3. Create only the scaffold:

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

   Add --schema "<schema-name>" only after an explicit schema choice.

4. Read status:

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

   Use returned planningHome, changeRoot, artifactPaths and actionContext; do not assume paths.

5. Select the first artifact with status: "ready", then obtain its instructions:

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

   Apply context, rules, template and instruction as constraints. Write only to resolvedOutputPath; do not copy prompt-level context/rules into the artifact. For the default wealth-ledger-sdd schema the first artifact is Proposal and contains owner-readable intent without implementation details.

6. Verify that one artifact exists and show fresh status:

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

7. Show the drafted artifact and stop. Tell the user that explicit approval is required before /opsx-continue may create the next artifact.

Guardrails

• Never create a downstream artifact in the same invocation, even if OpenSpec reports it ready.
• Never treat generated status, silence or the agent's own assessment as owner approval.
• If an approved upstream artifact changes, state which downstream approvals are invalidated and stop; do not regenerate them in this invocation.
• Do not edit application code or begin Apply.
• If the change already exists, ask whether to continue it instead of overwriting it.