WealthLedger/specs
5
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: harden OpenSpec SDD workflow

Browse Source
This commit is contained in:
ksv741
2026-08-26 00:42:35 +03:00
parent 039b72eed3
commit a8b2c4eed9
42 changed files with 4024 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agent-projection/opencode/skills/openspec-apply-change/SKILL.md
+194
View File
@@ -0,0 +1,194 @@
---
name: openspec-apply-change
description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
Implement tasks from an OpenSpec change.
**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:** Apply is allowed only after explicit Change Owner approval of Proposal, Delta Specs, Design and Tasks in sequence. CLI status and file existence prove structure, not approval. Establish approvals from the conversation; if evidence is unavailable, ask again and stop. If any approved upstream artifact changed after downstream approval, invalidate dependent approvals and return to planning before implementation.
**Planning gate and feedback:** Before implementation run `bash specs/scripts/verify-openspec-planning.sh "<name>"`. A structural failure blocks Apply. During Apply route intent/scope to Proposal, observable behavior to Delta Specs, architecture/rollback to Design, and decomposition/ownership/coverage to Tasks; stop downstream work and invalidate dependent approvals. A format-only correction may be fixed and revalidated without reapproval only when it changes none of those semantics.
**Input**: Optionally specify a change name (e.g., `/opsx-apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json --store wealth-ledger-specs` to get available changes and ask the user to select one
Always announce: "Using change: <name>" and how to override (e.g., `/opsx-apply <other>`).
2. **Check status to understand the schema**
```bash
openspec status --change "<name>" --json --store wealth-ledger-specs
```
Parse the JSON to understand:
- `schemaName`: The workflow being used (e.g., "spec-driven")
- `planningHome`, `changeRoot`, and `actionContext`: planning scope and edit constraints
- Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
3. **Get apply instructions**
```bash
openspec instructions apply --change "<name>" --json --store wealth-ledger-specs
```
This returns:
- `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
- Progress (total, complete, remaining)
- Task list with status
- Dynamic instruction based on current state
- Optional `context`: current required project instruction input from the selected root
- Optional `operationGuidance`: current advisory guidance for apply
**Handle states:**
- If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx-continue` (if it is not installed, run `openspec status --change "<name>" --json --store wealth-ledger-specs` to see the next artifact and `openspec instructions <artifact-id> --change "<name>" --json --store wealth-ledger-specs` for how to create it)
- If `state: "all_done"`: congratulate, suggest archive
- Otherwise: proceed to implementation
Treat `context` as a required prompt-level input. Read and consider it, and
apply relevant project facts, conventions, and constraints while implementing.
Treat `operationGuidance` as optional additive advice. Read and consider every
entry, and follow entries that are applicable and compatible with the built-in
workflow.
Keep both fields separate from CLI-returned state, missing artifacts, tasks,
progress, `contextFiles`, and the built-in `instruction`. They are not
evidence of task completion, do not replace the built-in instruction, and do
not permit bypassing a blocked state. If context conflicts with the built-in
instruction, an explicit user choice, or a CLI-controlled value, report the
conflict and preserve the controlling value. If guidance is inapplicable or
conflicts with those controlling inputs, do not follow it and explain why.
These are prompt-level behavior contracts, not enforceable checks.
4. **Read context files**
Read every file path listed under `contextFiles` from the apply instructions output.
The files depend on the schema being used:
- **spec-driven**: proposal, specs, design, tasks
- Other schemas: follow the contextFiles from CLI output
Do not copy `context` or `operationGuidance` verbatim into implementation
files or planning artifacts unless the user separately asks for that content.
5. **Show current progress**
Display:
- Schema being used
- Progress: "N/M tasks complete"
- Remaining tasks overview
- Dynamic instruction from CLI
6. **Implement tasks (loop until done or blocked)**
For each pending task:
- Show which task is being worked on
- Make the code changes required
- Keep changes minimal and focused
- Mark task complete in the tasks file: `- [ ]` → `- [x]`
- Continue to next task
**Pause if:**
- Task is unclear → ask for clarification
- Implementation reveals a design issue → suggest updating artifacts
- A task needs work beyond what the spec and tasks describe, or you are tempted to drop, narrow, defer, or accept exceptions to specified behavior to make it fit → surface the added scope and ask; do not absorb it silently
- Error or blocker encountered → report and wait for guidance
- User interrupts
7. **On completion or pause, show status**
Display:
- Tasks completed this session
- Overall progress: "N/M tasks complete"
- If all done: suggest archive
- If paused: explain why and wait for guidance
**Output During Implementation**
```
## Implementing: <change-name> (schema: <schema-name>)
Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete
Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete
```
**Output On Completion**
```
## Implementation Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓
### Completed This Session
- [x] Task 1
- [x] Task 2
...
All tasks complete! You can archive this change with `/opsx-archive`.
```
**Output On Pause (Issue Encountered)**
```
## Implementation Paused
**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete
### Issue Encountered
<description of the issue>
**Options:**
1. <option 1>
2. <option 2>
3. Other approach
What would you like to do?
```
**Guardrails**
- Keep going through tasks until done or blocked
- Always read context files before starting (from the apply instructions output)
- If task is ambiguous, pause and ask before implementing
- If implementation reveals issues, pause and suggest artifact updates
- Keep code changes minimal and scoped to each task
- Update task checkbox immediately after completing each task
- Pause on errors, blockers, or unclear requirements - don't guess
- When a task needs work beyond what the spec describes, surface the added scope and pause - never silently narrow, defer, or simplify away specified behavior
- Only mark a task `- [x]` when its specified behavior is fully implemented, not when it is partially done or deferred
- Use contextFiles from CLI output, don't assume specific file names
- Do not use context or operation guidance as proof that a task is complete
- Apply relevant project context; report conflicts with controlling workflow inputs
- Consider every guidance entry; explain any inapplicable or conflicting advice
- Do not copy runtime context or operation guidance into implementation files or planning artifacts
- Preserve CLI-controlled blocked/ready/all-done behavior and completion criteria
**Fluid Workflow Integration**
This skill supports the "actions on a change" model:
- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
agent-projection/opencode/skills/openspec-archive-change/SKILL.md
+201
View File
@@ -0,0 +1,201 @@
---
name: openspec-archive-change
description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
Archive a completed change in the experimental workflow.
**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:** Archive requires explicit Change Owner approval of Proposal, Delta Specs, Design and Tasks in sequence. File/status existence is not approval. If approval evidence is unavailable, or an upstream artifact changed, invalidate dependent approvals and require cascading reapproval; stop without offering an override.
**Planning gate:** Before any archive mutation run `bash specs/scripts/verify-openspec-planning.sh "<name>"`; the full workspace dispatcher repeats it. A failure blocks archive without override, and structural success cannot replace semantic verification or independent read-only review.
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json --store wealth-ledger-specs` to get available changes and ask the user to select one
When prompting, show only active changes (not already archived).
Include the schema used for each change if available.
Always announce: "Using change: <name>" and how to override (e.g., `/opsx-archive <other>`).
**Load current archive inputs before the existing archive checks:**
After resolving the selected change and planning root, run:
```bash
openspec instructions archive --change "<name>" --json --store wealth-ledger-specs
```
Keep the same selected-root flags on this command. This lookup is advisory and
optional: it only supplies extra prompt inputs, so it must never block archiving.
If it exits non-zero or returns invalid JSON — for example on an older CLI that
does not support this command yet — continue the archive workflow with no
context and no operation guidance. Do not report an error and do not stop.
A successful response may omit both optional fields. Treat `context` as a
required prompt-level input: read and consider it, and apply relevant project
facts, conventions, and constraints. Treat `operationGuidance` as optional
additive advice: read and consider every entry, and follow entries that are
applicable and compatible with the built-in archive workflow.
Keep both fields separate from built-in steps, explicit user choices, resolved
paths, CLI checks, and command contracts. If context conflicts with one of those
controlling inputs, report the conflict and preserve the controlling value. If
guidance is inapplicable or conflicts with a controlling input, do not follow it
and explain why. Do not infer replacement paths, skipped prompts, or flags from
either field, and do not copy their text verbatim into specs, change artifacts,
or archive summaries unless the user separately asks for it. These are
prompt-level behavior contracts, not enforceable checks.
2. **Check artifact completion status**
Run `openspec status --change "<name>" --json --store wealth-ledger-specs` to check artifact completion.
Parse the JSON to understand:
- `schemaName`: The workflow being used
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
- `artifacts`: List of artifacts with their status (`done`, `skipped`, or other)
**If any artifacts are neither `done` nor `skipped`** (skipped artifacts satisfy the requirement - the change declares skip_specs):
- Stop without syncing or archiving.
- Report the incomplete artifacts as blocking conditions.
- Do not ask for or accept a confirmation override.
3. **Check task completion status**
Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
**If incomplete tasks found:**
- Stop without syncing or archiving.
- Report the incomplete tasks as blocking conditions.
- Do not ask for or accept a confirmation override.
**If no tasks file exists:** Stop without syncing or archiving. Report the missing `tasks.md` as a blocking condition.
**WealthLedger pre-archive gates:**
- Run `bash specs/scripts/verify-workspace-change.sh "<name>"` from the workspace root and require a successful result for every affected delivery area.
- Require successful semantic verification against Proposal, Delta Specs, Design and Tasks.
- Require a completed independent read-only review with no unresolved Critical or Important finding.
- Stop if any gate or evidence is missing or unsuccessful. Do not ask for or accept a confirmation override.
4. **Assess delta spec sync state**
Use `artifactPaths.specs.existingOutputPaths` from status JSON as the only
delta-spec source. If the `specs` entry is missing or
`existingOutputPaths` is empty, proceed without a sync prompt and do not infer
delta specs from other artifacts.
**If delta specs exist:**
- Compare each delta spec with its corresponding main spec at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (use the store-aware `planningHome.root` from step 2, not a hardcoded repo path)
- Determine what changes would be applied (adds, modifications, removals, renames)
- Show a combined summary before prompting
**Prompt options:**
- If changes needed: "Sync now (recommended)", "Archive without syncing"
- If already synced: "Archive now", "Sync anyway", "Cancel"
Route on the answer:
- "Cancel" — stop, do not archive
- "Archive without syncing" or "Archive now" — proceed to archive
- "Sync now" or "Sync anyway" — sync, then verify (below)
- Anything else — ask again rather than archiving
Before a selected sync writes any main spec, run
`openspec instructions specs --change "<name>" --json --store wealth-ledger-specs` once with the same
selected-root flags. Require a zero exit status and valid artifact-instruction
JSON. If the lookup fails or returns invalid JSON, report the error and stop
before writing any main spec or moving the change. A valid response with omitted
`rules` is the no-rules case. Apply returned `rules` only to the content and
form of main specs produced by this merge; do not use them as archive guidance,
change CLI behavior, or copy the rule text into any output file.
Then run the `openspec-sync-specs` workflow inline (agent-driven intelligent merge) for change '<name>', passing the delta spec analysis and the fetched specs-rule snapshot from above, and wait for it to finish. The inline sync must reuse that snapshot without fetching `specs` instructions again. Do not delegate it to a background task — step 5 would move `changeRoot` out from under a sync that is still reading it, leaving the change archived and the main specs never updated. If your agent can only run it by delegation, delegate synchronously and wait for the result.
Then re-run the comparison from the top of this step against every capability that has a delta spec in `artifactPaths.specs.existingOutputPaths` — not only the ones the sync reports it touched. A successful sync leaves nothing left to apply, so each capability must now read as already synced:
- ADDED requirements present
- MODIFIED requirements carrying the scenario and description changes named in the delta, with their other scenarios intact
- REMOVED requirements gone — and where this sync retired a capability (removed its last requirement, leaving `## Requirements` empty), its main spec deleted rather than left empty; a spec the sync deliberately kept and reported is also a match
- RENAMED requirements present under the new name and absent under the old one
If the sync failed, or any capability does not match, report what differs and stop — do not archive. Nothing has moved and `changeRoot` is intact, so the user can fix the mismatch or re-run the sync and start the archive again.
5. **Perform the archive**
Create an `archive` directory under `planningHome.changesDir` if it doesn't exist:
```bash
mkdir -p "<planningHome.changesDir>/archive"
```
Generate the target name: use the change name as-is when it already starts with a `YYYY-MM-DD-` prefix; otherwise prepend the current date as `YYYY-MM-DD-<change-name>`. Never stack a second date (same rule as `openspec archive --store wealth-ledger-specs`).
**Check if target already exists:**
- If yes: Fail with error, suggest renaming existing archive or using different date
- If no: Move `changeRoot` to the archive directory
```bash
mv "<changeRoot>" "<planningHome.changesDir>/archive/<target-name>"
```
6. **Display summary**
Show archive completion summary including:
- Change name
- Schema that was used
- Archive location
- Whether specs were synced (if applicable)
- Confirmation that all planning artifacts and tasks were complete before archive
After the move succeeds, use a deterministic two-phase evidence protocol:
- First commit the delivered changes in each affected repository, including the synced/archive state in `specs` and any as-built documentation in `docs`, and collect their actual commit IDs.
- Then write Completion Evidence in the durable registry/history with the archive path, Delivery Map, those delivery commit IDs, exact verification commands, observed results and independent review verdict.
- Commit Completion Evidence as a final follow-up in `docs`. The evidence cites the preceding docs delivery commit when docs was affected; when docs was `N/A`, it preserves that reason and does not invent an implementation commit. Its own follow-up commit cannot self-reference and is reported in the archive summary instead of repeatedly rewriting the record.
Do not add these post-archive actions as unchecked tasks in the archived change and do not claim terminal `done` before the evidence follow-up commit succeeds.
**Output On Success**
```markdown
## Archive Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/<target-name>/
**Specs:** <"✓ Synced to main specs" only if the step 4 verification passed; otherwise "No delta specs" or "Sync skipped">
All artifacts complete. All tasks complete.
```
**Guardrails**
- Announce the selected change; prompt for selection when it is ambiguous
- Use artifact graph (`openspec status --json --store wealth-ledger-specs`) for completion checking
- Treat incomplete artifacts, a missing `tasks.md`, incomplete tasks, an affected delivery area failure, missing semantic verification and missing independent read-only review as hard blockers; never offer an override
- Preserve .openspec.yaml when moving to archive (it moves with the directory)
- Show clear summary of what happened
- If sync is requested, run the `openspec-sync-specs` workflow inline (agent-driven)
- Never archive while a spec sync is still in flight — run the sync inline and verify the main specs before moving `changeRoot`
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
- Apply relevant runtime context and report conflicts; operation guidance remains advisory
- Consider every guidance entry and explain any inapplicable or conflicting advice
- Existing CLI checks, resolved paths, prompts, and command contracts are unchanged
- Artifact rules constrain only the specs being written and are never operation guidance
- Never copy runtime context, operation guidance, or artifact-rule text verbatim into output files
agent-projection/opencode/skills/openspec-continue-change/SKILL.md
+124
View File
@@ -0,0 +1,124 @@
---
name: openspec-continue-change
description: Continue working on an OpenSpec change by creating the next artifact. Use when the user wants to progress their change, create the next artifact, or continue their workflow.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
Continue working on a change by creating the next artifact.
**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, then STOP for explicit Change Owner approval. Before creating a downstream artifact, establish from the conversation that every completed dependency was explicitly approved; file/status existence is not approval. If approval cannot be established, ask again and stop. If an approved upstream artifact changed, invalidate dependent approvals and return to that artifact instead of continuing downstream.
**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**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json --store wealth-ledger-specs` to get available changes sorted by most recently modified, and ask the user to select one
When prompting, present the top 3-4 most recently modified changes as options, showing:
- Change name
- Schema (from `schema` field if present, otherwise "spec-driven")
- Status (e.g., "0/5 tasks", "complete", "no tasks")
- How recently it was modified (from `lastModified` field)
Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue.
Always announce: "Using change: <name>" and how to override (e.g., `/opsx-continue <other>`).
2. **Check current status**
```bash
openspec status --change "<name>" --json --store wealth-ledger-specs
```
Parse the JSON to understand current state. The response includes:
- `schemaName`: The workflow schema being used (e.g., "spec-driven")
- `artifacts`: Array of artifacts with their status ("done", "skipped", "ready", "blocked")
- `isPlanningComplete`: Boolean indicating if all planning artifacts are complete. Older CLI versions expose the same value as `isComplete`.
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context. Use these instead of assuming repo-local paths.
3. **Act based on status**:
---
**If all planning artifacts are complete (`isPlanningComplete: true`, or legacy `isComplete: true`)**:
- Congratulate the user
- Show final status including the schema used
- Suggest: "Planning is complete! You can now implement this change. Once implementation and any tracked work are complete, archive it."
- STOP
---
**If artifacts are ready to create** (status shows artifacts with `status: "ready"`):
- Pick the FIRST artifact with `status: "ready"` from the status output
- Get its instructions:
```bash
openspec instructions <artifact-id> --change "<name>" --json --store wealth-ledger-specs
```
- Parse the JSON. The key fields are:
- `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
- `resolvedOutputPath`: Resolved path or pattern to write the artifact
- `dependencies`: Completed artifacts to read for context (entries with `skipped: true` have no files - do not look for them)
- `skipped`/`warning`: present when the change declares skip_specs and this artifact must NOT be created - pick another artifact
- **Create the artifact file**:
- Read any completed dependency files for context - always re-read them from disk, even if you saw them earlier in the conversation (the user may have edited them)
- If the `instruction` field delegates creation to a specific skill or command, invoke it to produce the artifact instead of writing the file yourself, then verify the artifact file exists at `resolvedOutputPath`
- Otherwise use `template` as the structure - fill in its sections
- Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file
- Write to the `resolvedOutputPath` specified in instructions. If it is a glob pattern, choose the concrete file path using the schema instruction and the change's context
- Show what was created and what's now unlocked
- STOP after creating ONE artifact
---
**If no artifacts are ready (all blocked)**:
- This shouldn't happen with a valid schema
- Show status and suggest checking for issues
4. **After creating an artifact, show progress**
```bash
openspec status --change "<name>" --store wealth-ledger-specs
```
**Output**
After each invocation, show:
- Which artifact was created
- Schema workflow being used
- Current progress (N/M complete)
- What artifacts are now unlocked
- Prompt: "Want to continue? Just ask me to continue or tell me what to do next."
**Artifact Creation Guidelines**
The artifact types and their purpose depend on the schema. The `instruction` field from the instructions output is the authoritative guidance for each artifact - follow it even when the artifact has a familiar name (proposal.md, tasks.md, etc.), since custom schemas may define different content or a different process for the same file names.
If the `instruction` field directs you to use a specific skill or command to create the artifact, invoke it instead of writing the artifact directly.
**Guardrails**
- Create ONE artifact per invocation
- Always read dependency artifacts before creating a new one - re-read from disk, not from conversation memory (files may have changed since you last saw them)
- Never skip artifacts or create out of order
- If context is unclear, ask the user before creating
- Verify the artifact file exists after writing before marking progress
- Use the schema's artifact sequence, don't assume specific artifact names
- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
- Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
- These guide what you write, but should never appear in the output
agent-projection/opencode/skills/openspec-explore/SKILL.md
+39
View File
@@ -0,0 +1,39 @@
---
name: openspec-explore
description: Explore ideas without implementing or bypassing WealthLedger SDD approvals.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
Explore the actual codebase, clarify intent, compare mature solutions, surface risks and visualize trade-offs. Do not implement or modify application code.
**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:** Exploration does not approve artifacts. If the user explicitly asks to capture a decision, create at most ONE planning artifact per invocation and then STOP for explicit Change Owner approval. File/status existence is not approval.
**Planning gate:** When exploration captures an artifact, run `bash specs/scripts/verify-openspec-planning.sh "<name>"` after the write and before requesting approval. Fix structural failures; if the captured decision changes upstream semantics, return to the earliest affected artifact and invalidate dependent approvals.
## Workflow
- Discover with `openspec list --json --store wealth-ledger-specs`; resolve an existing change with `openspec status --change "<name>" --json --store wealth-ledger-specs` and read its returned artifact paths.
- Read relevant code and durable documentation. Ask only material questions. Compare mature supported solutions before custom auth, security, storage, integrations, observability, caching, concurrency, infrastructure or tooling.
- Offer to capture a stable decision in the current artifact; do not auto-capture it.
- When explicitly requested, scaffold a new change with `openspec new change "<name>" --store wealth-ledger-specs` or read existing status. Confirm dependency approvals from the conversation. The selected artifact must be the first `ready` one.
- Run `openspec instructions "<artifact-id>" --change "<name>" --json --store wealth-ledger-specs`, read completed dependencies, follow its template/instruction and create or update only that artifact at `resolvedOutputPath`.
- Show fresh status and stop for owner approval before downstream work.
If an approved upstream artifact changes, state which downstream approvals are invalidated and stop without regenerating them.
## Guardrails
- Never write implementation code in explore mode.
- Create at most ONE planning artifact per invocation.
- Never create an unapproved prerequisite or downstream artifact because status reports it ready.
- Keep versioned planning documents only in `specs/openspec`.
agent-projection/opencode/skills/openspec-new-change/SKILL.md
+79
View File
@@ -0,0 +1,79 @@
---
name: openspec-new-change
description: Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
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 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**
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 (e.g., `proposal` for spec-driven).
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? Just describe what this change is about and I'll draft it, or ask me to continue."
**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 continuing that change instead
- Pass --schema if using a non-default workflow
agent-projection/opencode/skills/openspec-propose/SKILL.md
+38
View File
@@ -0,0 +1,38 @@
---
name: openspec-propose
description: Start a WealthLedger OpenSpec change and draft only its first planning artifact.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
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.
## Workflow
1. Resolve the requested intent and a kebab-case name; ask about ambiguity that changes scope, behavior, compatibility or acceptance criteria.
2. Use the configured default schema unless the user explicitly chooses another. Available schemas are read with `openspec schemas --json --store wealth-ledger-specs`.
3. Scaffold with `openspec new change "<name>" --store wealth-ledger-specs`; add `--schema "<schema-name>"` only after an explicit choice.
4. Run `openspec status --change "<name>" --json --store wealth-ledger-specs` and use its resolved paths.
5. For the first `ready` artifact run `openspec instructions "<artifact-id>" --change "<name>" --json --store wealth-ledger-specs`. Apply returned context, rules, template and instruction; create only that artifact at `resolvedOutputPath`.
6. Run `openspec status --change "<name>" --store wealth-ledger-specs`, show the draft and stop for approval before any `/opsx-continue`.
## Guardrails
- Never create a downstream artifact in the same invocation, even if status reports it ready.
- Never infer approval from file existence, CLI status, silence or the agent's own judgment.
- If an approved upstream artifact changes, report invalidated downstream approvals and stop without regenerating them.
- Do not edit application code or start Apply.
- If the change already exists, ask whether to continue it.
agent-projection/opencode/skills/openspec-sync-specs/SKILL.md
+264
View File
@@ -0,0 +1,264 @@
---
name: openspec-sync-specs
description: Sync delta specs from a change to main specs. Use when the user wants to update main specs with changes from a delta spec, without archiving the change.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
Sync delta specs from a change to main specs.
This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
**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.
`<capability-path>` is the spec directory relative to `specs/` (for example, `user-auth` or `identity/user-auth`). Preserve the full path from each delta spec when resolving its main spec.
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json --store wealth-ledger-specs` to get available changes and ask the user to select one
When prompting, show changes that have delta specs (under `specs/` directory).
Always announce: "Using change: <name>" and how to override (e.g., `/opsx-sync <other>`).
2. **Resolve change context**
Run:
```bash
openspec status --change "<name>" --json --store wealth-ledger-specs
```
The JSON includes `planningHome.root`. Main specs live under `<planningHome.root>/openspec/specs/` — use that (store-aware) root for every main-spec path below, not a hardcoded repo path. When a store is selected it points at the store, not the current repository.
3. **Find delta specs**
Use `artifactPaths.specs.existingOutputPaths` from the status JSON as the
only source of delta spec paths. If the `specs` entry is missing or
`existingOutputPaths` is empty, report that there are no delta specs to sync,
do not infer them from other artifacts, and stop without requesting artifact
instructions or writing a main spec.
Sync every path in `existingOutputPaths` unless the caller narrowed the set.
A caller narrows it by naming an explicit list of complete entries from
`existingOutputPaths` — copy those absolute values verbatim. Archive does
this inline, and a user can too (for example, by selecting the entry ending
in `/specs/billing/invoices/spec.md`).
Then sync only the named paths and leave the remaining delta specs untouched:
bulk archive excludes a delta whose implementation it could not find, and
syncing it anyway would write a main spec the caller deliberately withheld.
Carry that narrowed selection through step 4; never widen it back to the full
list. If a named path is not in `existingOutputPaths`, do not sync it —
report it and stop, rather than dropping it silently. If the named list is
empty, report that there is nothing to sync and stop without writing a main
spec.
Each delta spec file contains sections like:
- `## ADDED Requirements` - New requirements to add
- `## MODIFIED Requirements` - Changes to existing requirements
- `## REMOVED Requirements` - Requirements to remove
- `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
If no delta specs found, inform user and stop.
4. **For each delta spec, apply changes to main specs**
Before the first main-spec write, obtain one current specs-rule snapshot:
- If archive invoked this workflow inline and supplied a valid snapshot from
`openspec instructions specs --change "<name>" --json --store wealth-ledger-specs`, reuse it and do not
fetch the same instructions again.
- Otherwise run that command once now with the same selected-root flags.
- If the direct lookup exits non-zero or returns invalid artifact-instruction
JSON, report the error and stop before writing any main spec. Do not treat the
failure as an absent rule set.
- A valid response with omitted `rules` means no artifact rules are configured
and the existing semantic merge continues.
Apply returned `rules` only to the content and form of the main specs produced
by this merge. Artifact rules are not operation guidance and cannot change
selected roots, delta paths, CLI checks, or workflow steps. Use their text as
constraints without copying it verbatim into a main spec or summary.
For each capability delta spec path selected in step 3 — the full `existingOutputPaths` list, or the narrowed subset when a caller supplied one (these may belong to a selected store, not the repo):
a. **Read the delta spec** to understand the intended changes
b. **Read the main spec** at `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (may not exist yet)
c. **Apply changes intelligently**:
**ADDED Requirements:**
- If requirement doesn't exist in main spec → add it
- If requirement already exists → update it to match (treat as implicit MODIFIED)
**MODIFIED Requirements:**
- Find the requirement in main spec
- Apply the changes - this can be:
- Adding new scenarios the main spec does not have yet
- Modifying existing scenarios
- Changing the requirement description
- Preserve scenarios/content not mentioned in the delta
**REMOVED Requirements:**
- Remove the entire requirement block from main spec
- Retiring the capability. Delete the whole `spec.md` - and the directory once
nothing else is left in it - only when ALL of these hold:
1. removing the requirements *this run* left no requirement blocks;
2. the rest of the spec is well-formed (it still has a `## Purpose`);
3. the main spec was not already empty before this sync - if you removed
nothing, change nothing;
4. every other nonblank line in the whole file is accounted for as the
title, Purpose, Requirements header, or a canonical requirement's
statement, scenarios, or fenced examples;
5. the change's `.openspec.yaml` declares `retire_capabilities: true`;
6. the `spec.md` resolves inside the real specs root (do not follow a
capability-directory symlink to delete an external file).
If removing the selected requirements would leave no requirement blocks and
any retirement condition is not satisfied, do not modify the main spec. Stop
the sync for that capability, report the blocking condition, and tell the user
how to resolve it. Never write or leave an empty `## Requirements` section.
When only the marker is missing, say that too - it is the one thing the user
can add to make the retirement go through.
- Deleting the file also deletes its `## Purpose`; any other section blocks
retirement. Name Purpose when you report the retirement. Include a pasteable
`git checkout` only when the spec lived in the caller's checkout;
otherwise give checkout-scoped recovery guidance.
**RENAMED Requirements:**
- Find the FROM requirement, rename to TO
**`## Purpose` in the delta:**
- The main spec already has one and it is authoritative - leave it alone
(this is what `openspec archive --store wealth-ledger-specs` does; it warns and moves on)
d. **Create new main spec** if capability doesn't exist yet:
- Create `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
- Add Purpose section: copy the delta's `## Purpose` body verbatim when it has one
(this is what `openspec archive --store wealth-ledger-specs` does); only write a brief TBD placeholder when it does not
- Add Requirements section with the ADDED requirements
- Follow the **Main Spec Format Reference** below
5. **Validate updated main specs**
Run `openspec validate --specs --store wealth-ledger-specs` with the same selected-root flags used earlier.
If validation fails, report the problems and do not claim the sync succeeded.
6. **Show summary**
After applying all changes, summarize:
- Which capabilities were updated
- What changes were made (requirements added/modified/removed/renamed)
- Any new main spec left with a TBD Purpose placeholder, so it gets written
now rather than lingering
- Any capability retired, naming the deleted `spec.md`, its Purpose, and
either a pasteable `git checkout` or checkout-scoped recovery guidance
**Delta Spec Format Reference**
```markdown
## Purpose
Only on a delta that introduces a brand-new capability. Seeds the new main spec.
## ADDED Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
## MODIFIED Requirements
### Requirement: Existing Feature
The system SHALL keep doing the existing thing, now also handling A.
#### Scenario: Scenario the main spec already has
- **WHEN** user does X
- **THEN** system does Y
#### Scenario: New scenario to add
- **WHEN** user does A
- **THEN** system does B
## REMOVED Requirements
### Requirement: Deprecated Feature
## RENAMED Requirements
- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`
```
**Main Spec Format Reference**
Main specs are what the delta merges INTO. They must never contain delta operation headers (`## ADDED/MODIFIED/REMOVED/RENAMED Requirements`) - after syncing, every requirement lives under a single `## Requirements` section:
```markdown
# <capability> Specification
## Purpose
Short description of what this capability does and why it exists.
## Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
```
**Key Principle: Intelligent Merging**
Unlike programmatic merging, you merge rather than overwrite:
- A MODIFIED block carries the whole requirement - body plus every scenario that survives the change. `openspec validate --store wealth-ledger-specs` and `openspec archive --store wealth-ledger-specs` both reject one that drops a scenario the main spec still has.
- Keep anything the delta does not mention, in the main spec's existing order
- Use your judgment to merge changes sensibly
**Output On Success**
```markdown
## Specs Synced: <change-name>
Updated main specs:
**<capability-1>**:
- Added requirement: "New Feature"
- Modified requirement: "Existing Feature" (added 1 scenario)
**<capability-2>**:
- Created new spec file
- Added requirement: "Another Feature"
Main specs are now updated. The change remains active - archive when implementation is complete.
```
**Guardrails**
- Read both delta and main specs before making changes
- Preserve existing content not mentioned in delta
- Never copy a delta file into a main spec as-is - merge its content so the main spec keeps the Main Spec Format Reference structure, with no delta operation headers
- If something is unclear, ask for clarification
- Show what you're changing as you go
- The operation should be idempotent - running twice should give same result
- Use only `artifactPaths.specs.existingOutputPaths`; never infer delta specs from unrelated artifacts
- Honor a caller-supplied subset of `existingOutputPaths`; never widen it back to the full list
- Fetch specs instructions once for direct sync, or reuse the archive-supplied snapshot inline
- Stop before every main-spec write on a non-zero or invalid JSON specs-instruction response
- Artifact rules constrain only the specs being written and are never copied into output files
agent-projection/opencode/skills/openspec-verify-change/SKILL.md
+193
View File
@@ -0,0 +1,193 @@
---
name: openspec-verify-change
description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
allowed-tools: Bash(openspec:*)
license: MIT
compatibility: Requires openspec CLI.
metadata:
author: openspec
version: "1.0"
generatedBy: "1.10.0"
---
Verify that an implementation matches the change artifacts (specs, tasks, design).
**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.
**Planning gate:** Before delivery verification run `bash specs/scripts/verify-openspec-planning.sh "<name>"`. The workspace verifier repeats this gate before affected-area checks. Structural success does not replace semantic verification or independent read-only review.
**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
**Steps**
1. **Select the change**
If a name is provided, use it. Otherwise:
- Infer from conversation context if the user mentioned a change
- Auto-select if only one active change exists
- If ambiguous, run `openspec list --json --store wealth-ledger-specs` to get available changes and ask the user to select one
When prompting, show changes that have implementation tasks (tasks artifact exists).
Include the schema used for each change if available.
Mark changes with incomplete tasks as "(In Progress)".
Always announce: "Using change: <name>" and how to override (e.g., `/opsx-verify <other>`).
2. **Check status to understand the schema**
```bash
openspec status --change "<name>" --json --store wealth-ledger-specs
```
Parse the JSON to understand:
- `schemaName`: The workflow being used (e.g., "spec-driven")
- `planningHome`, `changeRoot`, `artifactPaths`, and `actionContext`: path and scope context
- Which artifacts exist for this change
3. **Get planning context and load artifacts**
```bash
openspec instructions apply --change "<name>" --json --store wealth-ledger-specs
```
This returns the change directory and `contextFiles` (artifact ID -> array of concrete file paths). Read all available artifacts from `contextFiles`.
Read the Design Delivery Map and account for frontend, backend, specs and
docs. Run the workspace verifier from the workspace root:
```bash
bash specs/scripts/verify-workspace-change.sh "<name>"
```
A missing decision or failed canonical gate for any affected delivery area
is CRITICAL. The semantic report does not replace independent review:
require evidence of a completed independent read-only review and report its
absence or any unresolved Critical/Important finding as CRITICAL.
4. **Initialize verification report structure**
Create a report structure with three dimensions:
- **Completeness**: Track tasks and spec coverage
- **Correctness**: Track requirement implementation and scenario coverage
- **Coherence**: Track design adherence and pattern consistency
Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
5. **Verify Completeness**
**Task Completion**:
- If `contextFiles.tasks` exists, read every file path in it
- Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
- Count complete vs total tasks
- If incomplete tasks exist:
- Add CRITICAL issue for each incomplete task
- Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
**Spec Coverage**:
- If delta specs exist in `contextFiles.specs`:
- Extract all requirements (marked with "### Requirement:")
- For each requirement:
- Search codebase for keywords related to the requirement
- Assess if implementation likely exists
- If requirements appear unimplemented:
- Add CRITICAL issue: "Requirement not found: <requirement name>"
- Recommendation: "Implement requirement X: <description>"
6. **Verify Correctness**
**Requirement Implementation Mapping**:
- For each requirement from delta specs:
- Search codebase for implementation evidence
- If found, note file paths and line ranges
- Assess if implementation matches requirement intent
- If divergence detected:
- Add WARNING: "Implementation may diverge from spec: <details>"
- Recommendation: "Review <file>:<lines> against requirement X"
**Scenario Coverage**:
- For each scenario in delta specs (marked with "#### Scenario:"):
- Check if conditions are handled in code
- Check if tests exist covering the scenario
- If scenario appears uncovered:
- Add WARNING: "Scenario not covered: <scenario name>"
- Recommendation: "Add test or implementation for scenario: <description>"
7. **Verify Coherence**
**Design Adherence**:
- If `contextFiles.design` exists:
- Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
- Verify implementation follows those decisions
- If contradiction detected:
- Add WARNING: "Design decision not followed: <decision>"
- Recommendation: "Update implementation or revise design.md to match reality"
- If no design.md: Skip design adherence check, note "No design.md to verify against"
**Code Pattern Consistency**:
- Review new code for consistency with project patterns
- Check file naming, directory structure, coding style
- If significant deviations found:
- Add SUGGESTION: "Code pattern deviation: <details>"
- Recommendation: "Consider following project pattern: <example>"
8. **Generate Verification Report**
**Summary Scorecard**:
```markdown
## Verification Report: <change-name>
### Summary
| Dimension | Status |
|--------------|------------------|
| Completeness | X/Y tasks, N reqs|
| Correctness | M/N reqs covered |
| Coherence | Followed/Issues |
```
**Issues by Priority**:
1. **CRITICAL** (Must fix before archive):
- Incomplete tasks
- Missing requirement implementations
- Missing or failed affected delivery area gate
- Missing independent read-only review
- Each with specific, actionable recommendation
2. **WARNING** (Should fix):
- Spec/design divergences
- Missing scenario coverage
- Each with specific recommendation
3. **SUGGESTION** (Nice to fix):
- Pattern inconsistencies
- Minor improvements
- Each with specific recommendation
**Final Assessment**:
- If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
- If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
- If all clear: "All checks passed. Ready for archive."
**Verification Heuristics**
- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
- **Coherence**: Look for glaring inconsistencies, don't nitpick style
- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
**Graceful Degradation**
- If only tasks.md exists: verify task completion only, skip spec/design checks
- If tasks + specs exist: verify completeness and correctness, skip design
- If full artifacts: verify all three dimensions
- Always note which checks were skipped and why
**Output Format**
Use clear markdown with:
- Table for summary scorecard
- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
- Code references in format: `file.ts:123`
- Specific, actionable recommendations
- No vague suggestions like "consider reviewing"