feat: harden OpenSpec SDD workflow

2026-08-26 00:42:35 +03:00
parent 039b72eed3
commit a8b2c4eed9
42 changed files with 4024 additions and 181 deletions
@@ -0,0 +1,70 @@
+---
+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**
+   ```bash
+   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**
+   ```bash
+   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".
+   ```bash
+   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