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,56 @@
+---
+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:
+
+   ```bash
+   openspec new change "<name>" --store wealth-ledger-specs
+   ```
+
+   Add `--schema "<schema-name>"` only after an explicit schema choice.
+4. Read status:
+
+   ```bash
+   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:
+
+   ```bash
+   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:
+
+   ```bash
+   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.