chore: add specs folder to version control

.cursor/commands/openspec-apply.md

@@ -0,0 +1,23 @@
+---
+name: /openspec-apply
+id: openspec-apply
+category: OpenSpec
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

.cursor/commands/openspec-archive.md

@@ -0,0 +1,27 @@
+---
+name: /openspec-archive
+id: openspec-archive
+category: OpenSpec
+description: Archive a deployed OpenSpec change and update specs.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict --no-interactive` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

.cursor/commands/openspec-proposal.md

@@ -0,0 +1,28 @@
+---
+name: /openspec-proposal
+id: openspec-proposal
+category: OpenSpec
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict --no-interactive` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

.cursor/commands/wf-apply-change.md

@@ -0,0 +1,182 @@
+---
+name: /wf-apply-change
+id: wf-apply-change
+category: Workflow
+description: Apply an approved OpenSpec change proposal to the codebase, executing openspec-apply workflow.
+---
+
+<!-- WORKFLOW:START -->
+**Purpose**
+
+Apply an approved OpenSpec change proposal to the codebase. This workflow wraps `/openspec-apply` and guides the AI through implementing the change.
+
+**When to use:** After an OpenSpec change proposal has been validated and approved, when ready to implement the change in the codebase.
+
+**Quick:** `/wf-apply-change <change-id>` or `/wf-apply-change` (interactive selection)
+
+**Guardrails**
+
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` for OpenSpec conventions
+- Work through tasks sequentially, keeping edits minimal and focused
+- Confirm completion before updating statuses - ensure every task in `tasks.md` is finished
+
+**Workflow Steps**
+
+### Step 1: Change Selection
+
+**If change ID provided in user input:**
+
+1. Parse the change ID from user input (e.g., `add-feature-x`)
+2. Resolve to change directory: `openspec/changes/<change-id>/`
+3. Verify change directory exists and contains `proposal.md`
+4. If not found, search for similar changes and suggest alternatives
+
+**If no change ID provided:**
+
+1. Search for active changes in workspace:
+   - Run: `openspec list` to get active changes
+   - Display numbered list of changes with:
+     - Change ID
+     - Status (from proposal.md)
+     - Brief description (from proposal.md summary)
+     - Last modified date (if available)
+2. Prompt user: "Select change to apply (enter number, or provide change-id):"
+3. Parse selection and resolve to change directory
+4. Verify change directory exists and is readable
+
+**Output:** Change ID, path to change directory
+
+### Step 2: Read Change Artifacts
+
+**2.1: Read Proposal**
+
+1. Read `proposal.md` to understand the change
+2. Extract key information:
+   - Rationale (from "Why" section)
+   - Scope (from "What Changes" section)
+   - Affected files/modules (from "Impact" section)
+   - Acceptance criteria
+
+**2.2: Read Tasks**
+
+1. Read `tasks.md` to get implementation checklist
+2. Extract task list:
+   - All tasks with their dependencies
+   - Task validation requirements
+   - Task execution order
+
+**2.3: Read Design (if exists)**
+
+1. If `design.md` exists:
+   - Read `design.md` for architectural decisions
+   - Extract design information:
+     - Architectural decisions
+     - Trade-offs and rationale
+     - Integration points
+     - Implementation patterns
+2. If `design.md` doesn't exist:
+   - Skip design reading (not all changes have design docs)
+
+**2.4: Read Spec Deltas**
+
+1. For each spec delta in `specs/<capability>/spec.md`:
+   - Read `spec.md`
+   - Parse ADDED/MODIFIED/REMOVED sections
+2. Extract spec delta information:
+   - All ADDED requirements with scenarios
+   - All MODIFIED requirements with changes
+   - All REMOVED requirements
+   - Cross-references to other capabilities
+
+**Output:** Complete change understanding from markdown artifacts
+
+### Step 3: Execute openspec-apply Workflow
+
+Execute the `/openspec-apply` workflow:
+
+1. **Read change artifacts:**
+   - Use markdown versions from Step 2
+   - Reference proposal, tasks, design, and spec deltas
+
+2. **Work through tasks sequentially:**
+   - Follow task order from `tasks.md`
+   - Keep edits minimal and focused on requested change
+   - Implement requirements as specified
+
+3. **Apply changes:**
+   - Implement requirements from spec deltas
+   - Follow architectural decisions from design (if available)
+   - Handle errors appropriately
+
+4. **Validate implementation:**
+   - Verify all requirements are met
+   - Run tests and quality checks as specified in tasks
+
+5. **Update task checklist:**
+   - Mark each completed task as `- [x]` in `tasks.md`
+   - Ensure all tasks reflect reality
+
+**Output:** Implemented change, task checklist updated
+
+### Step 4: Completion and Summary
+
+**4.1: Present Results**
+
+Display summary:
+
+```text
+✓ Change applied successfully
+
+Change ID: <change-id>
+Location: openspec/changes/<change-id>/
+
+Implementation:
+  ✓ All tasks completed
+  ✓ All requirements satisfied
+  ✓ Code quality checks passed
+  ✓ Tests passing
+
+Next Steps:
+  1. Review implementation: <files-modified>
+  2. Update change status if needed
+```
+
+**4.2: Provide Next Actions**
+
+1. **Review implementation:**
+   - Suggest reviewing modified files
+
+2. **Update change status:**
+   - Inform about updating proposal status if needed
+   - Mention syncing with GitHub issue if applicable
+
+**Output:** Completion summary, next action guidance
+
+**Reference**
+
+- OpenSpec apply command: `/openspec-apply`
+- OpenSpec list command: `openspec list`
+- OpenSpec show command: `openspec show <id> --json --deltas-only`
+- OpenSpec conventions: `openspec/AGENTS.md`
+- Project rules: `specfact-cli/.cursor/rules/`
+
+**Error Handling**
+
+- **Change not found:** Search and suggest alternatives, ask user to confirm
+- **Implementation fails:** Report errors clearly, allow retry, don't proceed until fixed
+
+**Common Patterns**
+
+```bash
+# With change ID
+/wf-apply-change add-feature-x
+
+# Interactive selection
+/wf-apply-change
+```
+
+<!-- WORKFLOW:END -->
+
+--- End Command ---