Add .claude directory for reference

Add MIT license
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 13:19:20 +01:00 · 2026-02-21 17:46:52 +01:00 · 2026-02-21 17:46:00 +01:00 · 2026-02-21 17:12:35 +01:00
30 changed files with 5027 additions and 20 deletions
--- a/.claude/commands/opsx/apply.md
+++ b/.claude/commands/opsx/apply.md
@@ -0,0 +1,152 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**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` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   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
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - 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
+   ```
+
+   This returns:
+   - Context file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read the files listed in `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
+
+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
+   - 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
+- Use contextFiles from CLI output, don't assume specific file names
+
+**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
--- a/.claude/commands/opsx/archive.md
+++ b/.claude/commands/opsx/archive.md
@@ -0,0 +1,157 @@
+---
+name: "OPSX: Archive"
+description: Archive a completed change in the experimental workflow
+category: Workflow
+tags: [workflow, archive, experimental]
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive 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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+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:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - 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"
+
+   If user chooses sync, execute `/opsx:sync` logic. Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use /opsx:sync approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
--- a/.claude/commands/opsx/bulk-archive.md
+++ b/.claude/commands/opsx/bulk-archive.md
@@ -0,0 +1,242 @@
+---
+name: "OPSX: Bulk Archive"
+description: Archive multiple completed changes at once
+category: Workflow
+tags: [workflow, archive, experimental, bulk]
+---
+
+Archive multiple completed changes in a single operation.
+
+This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
+
+**Input**: None required (prompts for selection)
+
+**Steps**
+
+1. **Get active changes**
+
+   Run `openspec list --json` to get all active changes.
+
+   If no active changes exist, inform user and stop.
+
+2. **Prompt for change selection**
+
+   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   - Show each change with its schema
+   - Include an option for "All changes"
+   - Allow any number of selections (1+ works, 2+ is the typical use case)
+
+   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
+
+3. **Batch validation - gather status for all selected changes**
+
+   For each selected change, collect:
+
+   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+      - Parse `schemaName` and `artifacts` list
+      - Note which artifacts are `done` vs other states
+
+   b. **Task completion** - Read `openspec/changes/<name>/tasks.md`
+      - Count `- [ ]` (incomplete) vs `- [x]` (complete)
+      - If no tasks file exists, note as "No tasks"
+
+   c. **Delta specs** - Check `openspec/changes/<name>/specs/` directory
+      - List which capability specs exist
+      - For each, extract requirement names (lines matching `### Requirement: <name>`)
+
+4. **Detect spec conflicts**
+
+   Build a map of `capability -> [changes that touch it]`:
+
+   ```
+   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
+   api  -> [change-c]            <- OK (only 1 change)
+   ```
+
+   A conflict exists when 2+ selected changes have delta specs for the same capability.
+
+5. **Resolve conflicts agentically**
+
+   **For each conflict**, investigate the codebase:
+
+   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
+
+   b. **Search the codebase** for implementation evidence:
+      - Look for code implementing requirements from each delta spec
+      - Check for related files, functions, or tests
+
+   c. **Determine resolution**:
+      - If only one change is actually implemented -> sync that one's specs
+      - If both implemented -> apply in chronological order (older first, newer overwrites)
+      - If neither implemented -> skip spec sync, warn user
+
+   d. **Record resolution** for each conflict:
+      - Which change's specs to apply
+      - In what order (if both)
+      - Rationale (what was found in codebase)
+
+6. **Show consolidated status table**
+
+   Display a table summarizing all changes:
+
+   ```
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   |---------------------|-----------|-------|---------|-----------|--------|
+   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
+   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
+   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
+   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
+   ```
+
+   For conflicts, show the resolution:
+   ```
+   * Conflict resolution:
+     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
+   ```
+
+   For incomplete changes, show warnings:
+   ```
+   Warnings:
+   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
+   ```
+
+7. **Confirm batch operation**
+
+   Use **AskUserQuestion tool** with a single confirmation:
+
+   - "Archive N changes?" with options based on status
+   - Options might include:
+     - "Archive all N changes"
+     - "Archive only N ready changes (skip incomplete)"
+     - "Cancel"
+
+   If there are incomplete changes, make clear they'll be archived with warnings.
+
+8. **Execute archive for each confirmed change**
+
+   Process changes in the determined order (respecting conflict resolution):
+
+   a. **Sync specs** if delta specs exist:
+      - Use the openspec-sync-specs approach (agent-driven intelligent merge)
+      - For conflicts, apply in resolved order
+      - Track if sync was done
+
+   b. **Perform the archive**:
+      ```bash
+      mkdir -p openspec/changes/archive
+      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      ```
+
+   c. **Track outcome** for each change:
+      - Success: archived successfully
+      - Failed: error during archive (record error)
+      - Skipped: user chose not to archive (if applicable)
+
+9. **Display summary**
+
+   Show final results:
+
+   ```
+   ## Bulk Archive Complete
+
+   Archived 3 changes:
+   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
+   - project-config -> archive/2026-01-19-project-config/
+   - add-oauth -> archive/2026-01-19-add-oauth/
+
+   Skipped 1 change:
+   - add-verify-skill (user chose not to archive incomplete)
+
+   Spec sync summary:
+   - 4 delta specs synced to main specs
+   - 1 conflict resolved (auth: applied both in chronological order)
+   ```
+
+   If any failures:
+   ```
+   Failed 1 change:
+   - some-change: Archive directory already exists
+   ```
+
+**Conflict Resolution Examples**
+
+Example 1: Only one implemented
+```
+Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
+
+Checking add-oauth:
+- Delta adds "OAuth Provider Integration" requirement
+- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
+
+Checking add-jwt:
+- Delta adds "JWT Token Handling" requirement
+- Searching codebase... no JWT implementation found
+
+Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
+```
+
+Example 2: Both implemented
+```
+Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
+
+Checking add-rest-api (created 2026-01-10):
+- Delta adds "REST Endpoints" requirement
+- Searching codebase... found src/api/rest.ts
+
+Checking add-graphql (created 2026-01-15):
+- Delta adds "GraphQL Schema" requirement
+- Searching codebase... found src/api/graphql.ts
+
+Resolution: Both implemented. Will apply add-rest-api specs first,
+then add-graphql specs (chronological order, newer takes precedence).
+```
+
+**Output On Success**
+
+```
+## Bulk Archive Complete
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+- <change-2> -> archive/YYYY-MM-DD-<change-2>/
+
+Spec sync summary:
+- N delta specs synced to main specs
+- No conflicts (or: M conflicts resolved)
+```
+
+**Output On Partial Success**
+
+```
+## Bulk Archive Complete (partial)
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+
+Skipped M changes:
+- <change-2> (user chose not to archive incomplete)
+
+Failed K changes:
+- <change-3>: Archive directory already exists
+```
+
+**Output When No Changes**
+
+```
+## No Changes to Archive
+
+No active changes found. Use `/opsx:new` to create a new change.
+```
+
+**Guardrails**
+- Allow any number of changes (1+ is fine, 2+ is the typical use case)
+- Always prompt for selection, never auto-select
+- Detect spec conflicts early and resolve by checking codebase
+- When both changes are implemented, apply specs in chronological order
+- Skip spec sync only when implementation is missing (warn user)
+- Show clear per-change status before confirming
+- Use single confirmation for entire batch
+- Track and report all outcomes (success/skip/fail)
+- Preserve .openspec.yaml when moving to archive
+- Archive directory target uses current date: YYYY-MM-DD-<name>
+- If archive target exists, fail that change but continue with others
--- a/.claude/commands/opsx/continue.md
+++ b/.claude/commands/opsx/continue.md
@@ -0,0 +1,114 @@
+---
+name: "OPSX: Continue"
+description: Continue working on a change - create the next artifact (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Continue working on a change by creating the next artifact.
+
+**Input**: Optionally specify a change name after `/opsx:continue` (e.g., `/opsx:continue 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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+
+   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.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check current status**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   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", "ready", "blocked")
+   - `isComplete`: Boolean indicating if all artifacts are complete
+
+3. **Act based on status**:
+
+   ---
+
+   **If all artifacts are complete (`isComplete: true`)**:
+   - Congratulate the user
+   - Show final status including the schema used
+   - Suggest: "All artifacts created! You can now implement this change with `/opsx:apply` or archive it with `/opsx:archive`."
+   - 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
+     ```
+   - 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
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - **Create the artifact file**:
+     - Read any completed dependency files for context
+     - 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 output path specified in instructions
+   - 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>"
+   ```
+
+**Output**
+
+After each invocation, show:
+- Which artifact was created
+- Schema workflow being used
+- Current progress (N/M complete)
+- What artifacts are now unlocked
+- Prompt: "Run `/opsx:continue` to create the next artifact"
+
+**Artifact Creation Guidelines**
+
+The artifact types and their purpose depend on the schema. Use the `instruction` field from the instructions output to understand what to create.
+
+Common artifact patterns:
+
+**spec-driven schema** (proposal → specs → design → tasks):
+- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
+  - The Capabilities section is critical - each capability listed will need a spec file.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
+- **design.md**: Document technical decisions, architecture, and implementation approach.
+- **tasks.md**: Break down implementation into checkboxed tasks.
+
+For other schemas, follow the `instruction` field from the CLI output.
+
+**Guardrails**
+- Create ONE artifact per invocation
+- Always read dependency artifacts before creating a new one
+- 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
--- a/.claude/commands/opsx/explore.md
+++ b/.claude/commands/opsx/explore.md
@@ -0,0 +1,174 @@
+---
+name: "OPSX: Explore"
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+category: Workflow
+tags: [workflow, explore, experimental, thinking]
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create one?"
+  → Can transition to `/opsx:new` or `/opsx:ff`
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into action**: "Ready to start? `/opsx:new` or `/opsx:ff`"
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
--- a/.claude/commands/opsx/ff.md
+++ b/.claude/commands/opsx/ff.md
@@ -0,0 +1,94 @@
+---
+name: "OPSX: Fast Forward"
+description: Create a change and generate all artifacts needed for implementation in one go
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Fast-forward through artifact creation - generate everything needed to start implementation.
+
+**Input**: The argument after `/opsx:ff` 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**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "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. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `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 for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "✓ Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use the `template` as a starting point, filling in based on context
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
--- a/.claude/commands/opsx/new.md
+++ b/.claude/commands/opsx/new.md
@@ -0,0 +1,69 @@
+---
+name: "OPSX: New"
+description: Start a new change using the experimental artifact workflow (OPSX)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Start a new change using the experimental artifact-driven approach.
+
+**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**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "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` and let them choose
+
+   **Otherwise**: Omit `--schema` to use the default.
+
+3. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   Add `--schema <name>` only if the user requested a specific workflow.
+   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
+
+4. **Show the artifact status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+
+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>"
+   ```
+   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
--- a/.claude/commands/opsx/onboard.md
+++ b/.claude/commands/opsx/onboard.md
@@ -0,0 +1,525 @@
+---
+name: "OPSX: Onboard"
+description: Guided onboarding - walk through a complete OpenSpec workflow cycle with narration
+category: Workflow
+tags: [workflow, onboarding, tutorial, learning]
+---
+
+Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
+
+---
+
+## Preflight
+
+Before starting, check if OpenSpec is initialized:
+
+```bash
+openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+```
+
+**If not initialized:**
+> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`.
+
+Stop here if not initialized.
+
+---
+
+## Phase 1: Welcome
+
+Display:
+
+```
+## Welcome to OpenSpec!
+
+I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
+
+**What we'll do:**
+1. Pick a small, real task in your codebase
+2. Explore the problem briefly
+3. Create a change (the container for our work)
+4. Build the artifacts: proposal → specs → design → tasks
+5. Implement the tasks
+6. Archive the completed change
+
+**Time:** ~15-20 minutes
+
+Let's start by finding something to work on.
+```
+
+---
+
+## Phase 2: Task Selection
+
+### Codebase Analysis
+
+Scan the codebase for small improvement opportunities. Look for:
+
+1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files
+2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
+3. **Functions without tests** - Cross-reference `src/` with test directories
+4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
+5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
+6. **Missing validation** - User input handlers without validation
+
+Also check recent git activity:
+```bash
+git log --oneline -10 2>/dev/null || echo "No git history"
+```
+
+### Present Suggestions
+
+From your analysis, present 3-4 specific suggestions:
+
+```
+## Task Suggestions
+
+Based on scanning your codebase, here are some good starter tasks:
+
+**1. [Most promising task]**
+   Location: `src/path/to/file.ts:42`
+   Scope: ~1-2 files, ~20-30 lines
+   Why it's good: [brief reason]
+
+**2. [Second task]**
+   Location: `src/another/file.ts`
+   Scope: ~1 file, ~15 lines
+   Why it's good: [brief reason]
+
+**3. [Third task]**
+   Location: [location]
+   Scope: [estimate]
+   Why it's good: [brief reason]
+
+**4. Something else?**
+   Tell me what you'd like to work on.
+
+Which task interests you? (Pick a number or describe your own)
+```
+
+**If nothing found:** Fall back to asking what the user wants to build:
+> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
+
+### Scope Guardrail
+
+If the user picks or describes something too large (major feature, multi-day work):
+
+```
+That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
+
+For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
+
+**Options:**
+1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
+2. **Pick something else** - One of the other suggestions, or a different small task?
+3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
+
+What would you prefer?
+```
+
+Let the user override if they insist—this is a soft guardrail.
+
+---
+
+## Phase 3: Explore Demo
+
+Once a task is selected, briefly demonstrate explore mode:
+
+```
+Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
+```
+
+Spend 1-2 minutes investigating the relevant code:
+- Read the file(s) involved
+- Draw a quick ASCII diagram if it helps
+- Note any considerations
+
+```
+## Quick Exploration
+
+[Your brief analysis—what you found, any considerations]
+
+┌─────────────────────────────────────────┐
+│   [Optional: ASCII diagram if helpful]  │
+└─────────────────────────────────────────┘
+
+Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
+
+Now let's create a change to hold our work.
+```
+
+**PAUSE** - Wait for user acknowledgment before proceeding.
+
+---
+
+## Phase 4: Create the Change
+
+**EXPLAIN:**
+```
+## Creating a Change
+
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
+
+Let me create one for our task.
+```
+
+**DO:** Create the change with a derived kebab-case name:
+```bash
+openspec new change "<derived-name>"
+```
+
+**SHOW:**
+```
+Created: `openspec/changes/<name>/`
+
+The folder structure:
+```
+openspec/changes/<name>/
+├── proposal.md    ← Why we're doing this (empty, we'll fill it)
+├── design.md      ← How we'll build it (empty)
+├── specs/         ← Detailed requirements (empty)
+└── tasks.md       ← Implementation checklist (empty)
+```
+
+Now let's fill in the first artifact—the proposal.
+```
+
+---
+
+## Phase 5: Proposal
+
+**EXPLAIN:**
+```
+## The Proposal
+
+The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
+
+I'll draft one based on our task.
+```
+
+**DO:** Draft the proposal content (don't save yet):
+
+```
+Here's a draft proposal:
+
+---
+
+## Why
+
+[1-2 sentences explaining the problem/opportunity]
+
+## What Changes
+
+[Bullet points of what will be different]
+
+## Capabilities
+
+### New Capabilities
+- `<capability-name>`: [brief description]
+
+### Modified Capabilities
+<!-- If modifying existing behavior -->
+
+## Impact
+
+- `src/path/to/file.ts`: [what changes]
+- [other files if applicable]
+
+---
+
+Does this capture the intent? I can adjust before we save it.
+```
+
+**PAUSE** - Wait for user approval/feedback.
+
+After approval, save the proposal:
+```bash
+openspec instructions proposal --change "<name>" --json
+```
+Then write the content to `openspec/changes/<name>/proposal.md`.
+
+```
+Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
+
+Next up: specs.
+```
+
+---
+
+## Phase 6: Specs
+
+**EXPLAIN:**
+```
+## Specs
+
+Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
+
+For a small task like this, we might only need one spec file.
+```
+
+**DO:** Create the spec file:
+```bash
+mkdir -p openspec/changes/<name>/specs/<capability-name>
+```
+
+Draft the spec content:
+
+```
+Here's the spec:
+
+---
+
+## ADDED Requirements
+
+### Requirement: <Name>
+
+<Description of what the system should do>
+
+#### Scenario: <Scenario name>
+
+- **WHEN** <trigger condition>
+- **THEN** <expected outcome>
+- **AND** <additional outcome if needed>
+
+---
+
+This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
+```
+
+Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
+
+---
+
+## Phase 7: Design
+
+**EXPLAIN:**
+```
+## Design
+
+The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
+
+For small changes, this might be brief. That's fine—not every change needs deep design discussion.
+```
+
+**DO:** Draft design.md:
+
+```
+Here's the design:
+
+---
+
+## Context
+
+[Brief context about the current state]
+
+## Goals / Non-Goals
+
+**Goals:**
+- [What we're trying to achieve]
+
+**Non-Goals:**
+- [What's explicitly out of scope]
+
+## Decisions
+
+### Decision 1: [Key decision]
+
+[Explanation of approach and rationale]
+
+---
+
+For a small task, this captures the key decisions without over-engineering.
+```
+
+Save to `openspec/changes/<name>/design.md`.
+
+---
+
+## Phase 8: Tasks
+
+**EXPLAIN:**
+```
+## Tasks
+
+Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
+
+These should be small, clear, and in logical order.
+```
+
+**DO:** Generate tasks based on specs and design:
+
+```
+Here are the implementation tasks:
+
+---
+
+## 1. [Category or file]
+
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+## 2. Verify
+
+- [ ] 2.1 [Verification step]
+
+---
+
+Each checkbox becomes a unit of work in the apply phase. Ready to implement?
+```
+
+**PAUSE** - Wait for user to confirm they're ready to implement.
+
+Save to `openspec/changes/<name>/tasks.md`.
+
+---
+
+## Phase 9: Apply (Implementation)
+
+**EXPLAIN:**
+```
+## Implementation
+
+Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
+```
+
+**DO:** For each task:
+
+1. Announce: "Working on task N: [description]"
+2. Implement the change in the codebase
+3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
+4. Mark complete in tasks.md: `- [ ]` → `- [x]`
+5. Brief status: "✓ Task N complete"
+
+Keep narration light—don't over-explain every line of code.
+
+After all tasks:
+
+```
+## Implementation Complete
+
+All tasks done:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+The change is implemented! One more step—let's archive it.
+```
+
+---
+
+## Phase 10: Archive
+
+**EXPLAIN:**
+```
+## Archiving
+
+When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
+```
+
+**DO:**
+```bash
+openspec archive "<name>"
+```
+
+**SHOW:**
+```
+Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`
+
+The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
+```
+
+---
+
+## Phase 11: Recap & Next Steps
+
+```
+## Congratulations!
+
+You just completed a full OpenSpec cycle:
+
+1. **Explore** - Thought through the problem
+2. **New** - Created a change container
+3. **Proposal** - Captured WHY
+4. **Specs** - Defined WHAT in detail
+5. **Design** - Decided HOW
+6. **Tasks** - Broke it into steps
+7. **Apply** - Implemented the work
+8. **Archive** - Preserved the record
+
+This same rhythm works for any size change—a small fix or a major feature.
+
+---
+
+## Command Reference
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through problems before/during work |
+| `/opsx:new` | Start a new change, step through artifacts |
+| `/opsx:ff` | Fast-forward: create all artifacts at once |
+| `/opsx:continue` | Continue working on an existing change |
+| `/opsx:apply` | Implement tasks from a change |
+| `/opsx:verify` | Verify implementation matches artifacts |
+| `/opsx:archive` | Archive a completed change |
+
+---
+
+## What's Next?
+
+Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now!
+```
+
+---
+
+## Graceful Exit Handling
+
+### User wants to stop mid-way
+
+If the user says they need to stop, want to pause, or seem disengaged:
+
+```
+No problem! Your change is saved at `openspec/changes/<name>/`.
+
+To pick up where we left off later:
+- `/opsx:continue <name>` - Resume artifact creation
+- `/opsx:apply <name>` - Jump to implementation (if tasks exist)
+
+The work won't be lost. Come back whenever you're ready.
+```
+
+Exit gracefully without pressure.
+
+### User just wants command reference
+
+If the user says they just want to see the commands or skip the tutorial:
+
+```
+## OpenSpec Quick Reference
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through problems (no code changes) |
+| `/opsx:new <name>` | Start a new change, step by step |
+| `/opsx:ff <name>` | Fast-forward: all artifacts at once |
+| `/opsx:continue <name>` | Continue an existing change |
+| `/opsx:apply <name>` | Implement tasks |
+| `/opsx:verify <name>` | Verify implementation |
+| `/opsx:archive <name>` | Archive when done |
+
+Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast.
+```
+
+Exit gracefully.
+
+---
+
+## Guardrails
+
+- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
+- **Keep narration light** during implementation—teach without lecturing
+- **Don't skip phases** even if the change is small—the goal is teaching the workflow
+- **Pause for acknowledgment** at marked points, but don't over-pause
+- **Handle exits gracefully**—never pressure the user to continue
+- **Use real codebase tasks**—don't simulate or use fake examples
+- **Adjust scope gently**—guide toward smaller tasks but respect user choice
--- a/.claude/commands/opsx/sync.md
+++ b/.claude/commands/opsx/sync.md
@@ -0,0 +1,134 @@
+---
+name: "OPSX: Sync"
+description: Sync delta specs from a change to main specs
+category: Workflow
+tags: [workflow, specs, experimental]
+---
+
+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).
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync 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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   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.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/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 (don't need to copy existing ones)
+        - 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
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## 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
+#### 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`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## 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
+- 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
--- a/.claude/commands/opsx/verify.md
+++ b/.claude/commands/opsx/verify.md
@@ -0,0 +1,164 @@
+---
+name: "OPSX: Verify"
+description: Verify implementation matches change artifacts before archiving
+category: Workflow
+tags: [workflow, verify, experimental]
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify 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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   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)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+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 tasks.md exists in contextFiles, read 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 `openspec/changes/<name>/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 design.md exists in contextFiles:
+     - 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**:
+   ```
+   ## 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
+      - 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"
--- a/.claude/skills/architect/README.md
+++ b/.claude/skills/architect/README.md
@@ -0,0 +1,112 @@
+# Requirements → Architecture Toolkit for Claude Code
+
+Skills and prompts that cover the path from project idea to implementation-ready plan.
+
+---
+
+## The Tools
+
+| Tool                             | Type          | Purpose                                           | Produces                                       |
+|:---------------------------------|:--------------|:--------------------------------------------------|:-----------------------------------------------|
+| `gather-requirements`            | Skill         | Structured requirements interview                 | `REQUIREMENTS.md`                              |
+| `requirements-analyst-prompt.md` | System prompt | Same interview, layered on `/opsx:explore`        | `REQUIREMENTS.md`                              |
+| `architect`                      | Skill         | Collaborative technical design with product owner | `TECHNICAL-SPEC.md` + `IMPLEMENTATION-PLAN.md` |
+
+---
+
+## Workflow
+
+### Without OpenSpec
+
+```
+/gather-requirements  →  REQUIREMENTS.md  →  /architect  →  TECHNICAL-SPEC.md
+                                                           →  IMPLEMENTATION-PLAN.md
+```
+
+### With OpenSpec
+
+```
+claude --append-system-prompt-file requirements-analyst-prompt.md
+  └─► /opsx:explore (structured requirements interview)
+        └─► REQUIREMENTS.md captured
+              └─► /architect (in same or new session)
+                    └─► TECHNICAL-SPEC.md + IMPLEMENTATION-PLAN.md
+                          └─► /opsx:new my-feature
+                                └─► /opsx:ff (informed by all three documents)
+```
+
+---
+
+## Install
+
+### Skills
+
+```bash
+# Project-level
+mkdir -p .claude/skills
+cp -r gather-requirements .claude/skills/
+cp -r architect .claude/skills/
+
+# OR User-level (all projects)
+cp -r gather-requirements ~/.claude/skills/
+cp -r architect ~/.claude/skills/
+```
+
+### System prompt (for OpenSpec workflow)
+
+Keep `requirements-analyst-prompt.md` wherever you like. Reference it at launch:
+
+```bash
+claude --append-system-prompt-file /path/to/requirements-analyst-prompt.md
+```
+
+---
+
+## Usage
+
+### /gather-requirements
+
+```
+$ claude
+> /gather-requirements
+```
+
+Claude interviews you in 6 phases (vision, users, functional, non-functional, constraints, priorities) and writes `REQUIREMENTS.md` with numbered requirement IDs.
+
+### /architect
+
+```
+$ claude
+> /architect
+```
+
+Claude reads `REQUIREMENTS.md` and works through the design collaboratively with you as product owner. You'll discuss and decide together on:
+
+- Architecture approach (monolith, services, serverless, etc.)
+- Technology stack
+- Data architecture
+- API and integration design
+- Testing strategy (your call — Claude presents options)
+- Infrastructure and deployment
+- Security
+- Delivery approach and phasing
+
+After the sessions, Claude writes `TECHNICAL-SPEC.md` and `IMPLEMENTATION-PLAN.md`. All three documents share a common vocabulary of requirement IDs, component names, and task IDs for full traceability.
+
+### OpenSpec prompt
+
+```bash
+claude --append-system-prompt-file requirements-analyst-prompt.md
+> /opsx:explore
+```
+
+Same structured interview, woven into OpenSpec's explore mode. When insights crystallize, Claude offers to capture `REQUIREMENTS.md` before you transition to `/opsx:new`.
+
+---
+
+## Tips
+
+- **Sequence matters.** Requirements first, architecture second. The architect skill expects `REQUIREMENTS.md` to exist.
+- **"I don't know" is fine.** In requirements, unknowns become open questions. In architecture, they become assumptions — clearly marked so the team can revisit.
+- **Iterate.** Both skills update documents in place. Re-run `/architect` after refining requirements.
+- **IDs carry forward.** FR-001 in requirements maps to components in the spec and tasks in the plan. This traceability is the point — it lets the team verify nothing was lost.
--- a/.claude/skills/architect/SKILL.md
+++ b/.claude/skills/architect/SKILL.md
@@ -0,0 +1,305 @@
+---
+name: architect
+description: Read a REQUIREMENTS.md document and collaborate with the product owner to produce a technical specification (TECHNICAL-SPEC.md) and implementation plan (IMPLEMENTATION-PLAN.md). Works through architecture decisions, technology choices, testing strategy, and delivery approach interactively. Use when the user says "architect this", "design the system", "technical spec", "implementation plan", "plan the build", or when a REQUIREMENTS.md exists and the user wants to move to architecture and planning.
+---
+
+# Technical Architect
+
+You are a senior technical architect working alongside the product owner. Your job is to read a REQUIREMENTS.md document and collaborate with the user to produce two deliverables:
+
+1. **TECHNICAL-SPEC.md** — the architectural design and technical decisions
+2. **IMPLEMENTATION-PLAN.md** — the phased plan for building it
+
+The user is the product owner. They have domain expertise, opinions on technology and process, and final say on trade-offs. You bring architectural experience and help them think through decisions — you don't make those decisions alone.
+
+## Core principles
+
+- **Propose, don't prescribe.** Present options with trade-offs. Let the user choose.
+- **Explain the "why."** When you recommend something, say why. When the user picks an option, make sure they understand the consequences.
+- **Surface decisions, don't bury them.** Every meaningful choice should be an explicit conversation, not something you silently default.
+- **Stay honest about uncertainty.** If you don't have a strong opinion, say so. If two options are genuinely equal, say that too.
+- **Right-size the architecture.** A weekend project doesn't need Kubernetes. An enterprise platform doesn't need a single SQLite file. Let the requirements — and the user's context — drive complexity.
+
+## Starting the process
+
+1. Look for `REQUIREMENTS.md` in the project root. If it doesn't exist, tell the user and suggest they run `/gather-requirements` first.
+2. Read the entire document carefully.
+3. Present a brief summary: the system's purpose, its scale, and the hardest problems you see. Ask: "Does this match your understanding?"
+4. If the requirements have open questions that would materially affect architecture, surface them now. Some you can design around with assumptions. Others need answers. Be clear about which is which.
+
+## Collaborative design sessions
+
+Work through the following areas **as conversations with the user**, not as solo work. For each area, present your analysis, offer options where choices exist, and confirm the user's decision before moving on.
+
+### Session 1 — Architecture approach
+
+Discuss the overall shape of the system:
+
+- What kind of architecture fits? (monolith, modular monolith, microservices, serverless, etc.)
+- Present 2–3 viable options with trade-offs for the project's scale, team, and timeline.
+- Discuss how the system will be structured at a high level — major components and their responsibilities.
+- Draw an ASCII architecture diagram and walk the user through it.
+
+### Session 2 — Technology choices
+
+For each technology decision, present options with trade-offs. Common decisions include:
+
+- Programming language(s) and frameworks
+- Database(s) and storage
+- Messaging/eventing (if applicable)
+- Hosting and infrastructure
+- Key libraries or platforms
+
+For each decision, frame it as:
+- "Here are the realistic options given the requirements and constraints..."
+- "Option A is [X] because [Y]. Option B is [Z] because [W]."
+- "My recommendation is [A] because [reason], but [B] is a solid choice if [user's context]."
+- Let the user decide. Record the decision and rationale.
+
+If the requirements already constrain technology choices, acknowledge them and focus on the remaining open decisions.
+
+### Session 3 — Data architecture
+
+Walk through:
+
+- Key entities and relationships (reference the conceptual data model from requirements if present)
+- Storage strategy — what goes where and why
+- Data flow — key write paths, read paths, and any transformation steps
+- Data migration needs (if replacing an existing system)
+
+Present the data model as an ASCII diagram or structured description. Confirm with the user.
+
+### Session 4 — API and integration design
+
+Discuss:
+
+- External APIs — key endpoints, contracts, versioning approach
+- Internal communication — sync vs async, protocols, event patterns
+- Third-party integrations — how they connect, failure handling
+- Authentication and authorization model
+
+### Session 5 — Testing strategy
+
+This is the user's call. Present the options and let them shape the approach:
+
+- What types of testing? (unit, integration, e2e, contract, performance, security)
+- What coverage expectations per level?
+- Which testing frameworks and tools? (present options that fit the chosen tech stack)
+- What gets automated vs manual?
+- When does each type of testing run? (local, CI, pre-deploy, post-deploy)
+- How will acceptance criteria from the requirements be verified?
+
+Frame it as: "Here's what I'd typically recommend for a system like this, but you know your team and process best. What resonates?"
+
+### Session 6 — Infrastructure and deployment
+
+Discuss:
+
+- Deployment model — cloud provider, containerization, orchestration
+- Environment strategy — dev, staging, production, preview environments
+- CI/CD pipeline — build, test, deploy stages
+- Observability — logging, metrics, alerting, tracing
+- Secrets management
+
+### Session 7 — Security
+
+Walk through:
+
+- Authentication and authorization approach
+- Data protection — encryption, PII handling
+- Key attack surfaces and mitigations
+- Compliance requirements from the requirements document
+
+### Session 8 — Risks and delivery approach
+
+Discuss:
+
+- Technical risks — what could go wrong, what's uncertain
+- Delivery strategy — iterative, MVP-first, phase-based? What fits?
+- Phase breakdown — what to build first and why
+- How to sequence for risk (hard/uncertain things early)
+- What's demoable at each phase?
+
+Ask the user about their preferences:
+- "Do you want a working MVP fast, or a solid foundation first?"
+- "How do you want to handle the riskiest parts — spike them early or defer?"
+- "What does your team's release process look like?"
+
+## Pacing
+
+Don't try to cover everything in one giant turn. Work through 1–2 sessions per exchange. After each session, summarize the decisions made and preview what's next. The user should never feel overwhelmed.
+
+If the user wants to move faster, you can combine sessions. If they want to go deeper on a topic, spend extra time there. Follow their lead.
+
+## Writing the documents
+
+After all sessions are complete (or when the user says they've decided enough), produce the two documents.
+
+### TECHNICAL-SPEC.md
+
+Write to the project root.
+
+```markdown
+# Technical Specification: [Project Name]
+
+> Based on: REQUIREMENTS.md
+> Generated: [date]
+> Status: Draft — pending review
+
+## 1. System Overview
+### 1.1 Architecture Summary
+One paragraph. What kind of system, what it does, how it's structured.
+
+### 1.2 Architecture Diagram
+ASCII diagram. Major components, data flows, external integrations.
+
+### 1.3 Key Design Decisions
+| ID      | Decision | Choice | Rationale | Alternatives Considered |
+|:--------|:---------|:-------|:----------|:------------------------|
+| ADR-001 |          |        |           |                         |
+
+Record every decision made during the sessions.
+
+## 2. Technology Stack
+| Layer | Choice | Version | Rationale |
+|-------|--------|---------|-----------|
+
+## 3. Component Design
+For each major component:
+### 3.x [Component Name]
+- **Responsibility:** Single-responsibility description
+- **Interfaces:** APIs exposed, events emitted/consumed
+- **Dependencies:** What it depends on
+- **Data:** What it owns, storage mechanism
+- **Scaling:** How it handles load
+- **Traceability:** FR-001, NFR-003, etc.
+
+## 4. Data Architecture
+### 4.1 Data Model (diagram or structured description)
+### 4.2 Storage Decisions
+### 4.3 Data Flow
+
+## 5. API Design
+### 5.1 External APIs
+### 5.2 Internal APIs / Contracts
+### 5.3 Third-Party Integrations
+
+## 6. Infrastructure & Deployment
+### 6.1 Deployment Architecture
+### 6.2 Environment Strategy
+### 6.3 CI/CD Pipeline
+### 6.4 Observability
+
+## 7. Security Architecture
+### 7.1 Authentication & Authorization
+### 7.2 Data Protection
+### 7.3 Threat Considerations
+
+## 8. Testing Strategy
+### 8.1 Testing Levels and Coverage
+### 8.2 Tools and Frameworks
+### 8.3 Automation Approach
+### 8.4 Acceptance Criteria Verification
+
+## 9. Cross-Cutting Concerns
+### 9.1 Error Handling Strategy
+### 9.2 Configuration Management
+### 9.3 Logging Standards
+
+## 10. Technical Risks & Mitigations
+| ID     | Risk | Likelihood | Impact | Mitigation |
+|:-------|:-----|:-----------|:-------|:-----------|
+| TR-001 |      |            |        |            |
+
+## 11. Assumptions
+Technical assumptions. Reference open questions from REQUIREMENTS.md.
+
+## 12. Traceability Matrix
+| Requirement | Component(s) | Verified By | Notes |
+|:------------|:-------------|:------------|:------|
+| FR-001      |              |             |       |
+| NFR-001     |              |             |       |
+
+Every requirement must appear. "Verified By" references the testing approach.
+```
+
+### IMPLEMENTATION-PLAN.md
+
+Write to the project root.
+
+```markdown
+# Implementation Plan: [Project Name]
+
+> Based on: TECHNICAL-SPEC.md, REQUIREMENTS.md
+> Generated: [date]
+> Status: Draft — pending review
+
+## 1. Delivery Strategy
+### 1.1 Approach
+Overall strategy as agreed with the product owner.
+
+### 1.2 Milestones
+| Milestone | Description | Deliverable | Exit Criteria |
+|:----------|:------------|:------------|:--------------|
+| M1        |             |             |               |
+
+## 2. Phase Breakdown
+
+### Phase 1: [Name]
+**Goal:** What's true when this phase is done.
+**Prerequisites:** What must exist before starting.
+**Demo:** What can be shown to stakeholders at the end.
+
+| Task  | Description | Component | Depends On | Requirements | Complexity |
+|:------|:------------|:----------|:-----------|:-------------|:-----------|
+| T-1.1 |             |           |            | FR-001       | S/M/L      |
+
+**Testing at this phase:**
+What gets tested and how, per the agreed testing strategy.
+
+**Exit Criteria:**
+Specific, verifiable conditions.
+
+### Phase 2: [Name]
+...
+
+## 3. Dependency Graph
+ASCII diagram. Tasks/phases and what blocks what. Highlight the critical path.
+
+## 4. Risk-Adjusted Sequencing
+Why the phases are ordered this way. Which risks are being retired early.
+
+## 5. Testing Milestones
+When each testing level activates across phases.
+
+## 6. Definition of Done
+For a task. For a phase. For the project.
+
+## 7. Open Items
+Decisions or prerequisites that must be resolved before specific phases begin.
+```
+
+### Writing guidelines for both documents
+
+- **Trace everything.** Components → requirements. Tasks → requirements and components. Tests → acceptance criteria. The traceability matrix must cover every FR and NFR.
+- **Record decisions faithfully.** Capture what the user chose and why, not what you would have chosen.
+- **Use relative complexity, not time estimates.** Size tasks as S/M/L. Time estimates are the team's job.
+- **Use diagrams freely.** ASCII diagrams for architecture, data flow, deployment, dependencies.
+- **Name trade-offs.** Be explicit about what the design optimizes for and what it sacrifices.
+
+## After writing
+
+- Tell the user both files have been created and where they are.
+- Summarize: the 3 most important design decisions, the critical path, and the top 3 risks.
+- Suggest they review with their engineering team before starting implementation.
+- Note that the requirement IDs, component names, and task IDs provide a shared vocabulary across all three documents.
+
+## Handling edge cases
+
+- **Requirements are thin.** Note which areas lack detail, make reasonable assumptions (clearly marked), and flag them to the user. Ask if they want to go back and refine requirements first.
+- **Requirements are contradictory.** Surface the contradiction. Don't silently resolve it.
+- **Scope is too large.** Propose a system-level architecture with separate specs per subsystem. Write the system-level spec and help the user decide which subsystem to detail first.
+- **Technology is pre-decided.** Respect the constraints. If a constraint forces a sub-optimal choice, explain the trade-off so the user can make an informed call.
+- **Existing codebase.** Read it first. Design to integrate, not replace, unless requirements explicitly call for a rewrite.
+- **User wants to skip a session.** That's fine. Note the skipped area as "not discussed — defaults applied" and list what you defaulted. They can revisit later.
+- **User disagrees with your recommendation.** Go with their choice. Record it with their rationale. You can note your concern once, but don't push. It's their project.
--- a/.claude/skills/openspec-apply-change/SKILL.md
+++ b/.claude/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,156 @@
+---
+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.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**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` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   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
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - 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
+   ```
+
+   This returns:
+   - Context 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
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read the files listed in `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
+
+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
+   - 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! Ready to archive this change.
+```
+
+**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
+- Use contextFiles from CLI output, don't assume specific file names
+
+**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
--- a/.claude/skills/openspec-archive-change/SKILL.md
+++ b/.claude/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,114 @@
+---
+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.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+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:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - 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"
+
+   If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
--- a/.claude/skills/openspec-bulk-archive-change/SKILL.md
+++ b/.claude/skills/openspec-bulk-archive-change/SKILL.md
@@ -0,0 +1,246 @@
+---
+name: openspec-bulk-archive-change
+description: Archive multiple completed changes at once. Use when archiving several parallel changes.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Archive multiple completed changes in a single operation.
+
+This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
+
+**Input**: None required (prompts for selection)
+
+**Steps**
+
+1. **Get active changes**
+
+   Run `openspec list --json` to get all active changes.
+
+   If no active changes exist, inform user and stop.
+
+2. **Prompt for change selection**
+
+   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   - Show each change with its schema
+   - Include an option for "All changes"
+   - Allow any number of selections (1+ works, 2+ is the typical use case)
+
+   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
+
+3. **Batch validation - gather status for all selected changes**
+
+   For each selected change, collect:
+
+   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+      - Parse `schemaName` and `artifacts` list
+      - Note which artifacts are `done` vs other states
+
+   b. **Task completion** - Read `openspec/changes/<name>/tasks.md`
+      - Count `- [ ]` (incomplete) vs `- [x]` (complete)
+      - If no tasks file exists, note as "No tasks"
+
+   c. **Delta specs** - Check `openspec/changes/<name>/specs/` directory
+      - List which capability specs exist
+      - For each, extract requirement names (lines matching `### Requirement: <name>`)
+
+4. **Detect spec conflicts**
+
+   Build a map of `capability -> [changes that touch it]`:
+
+   ```
+   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
+   api  -> [change-c]            <- OK (only 1 change)
+   ```
+
+   A conflict exists when 2+ selected changes have delta specs for the same capability.
+
+5. **Resolve conflicts agentically**
+
+   **For each conflict**, investigate the codebase:
+
+   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
+
+   b. **Search the codebase** for implementation evidence:
+      - Look for code implementing requirements from each delta spec
+      - Check for related files, functions, or tests
+
+   c. **Determine resolution**:
+      - If only one change is actually implemented -> sync that one's specs
+      - If both implemented -> apply in chronological order (older first, newer overwrites)
+      - If neither implemented -> skip spec sync, warn user
+
+   d. **Record resolution** for each conflict:
+      - Which change's specs to apply
+      - In what order (if both)
+      - Rationale (what was found in codebase)
+
+6. **Show consolidated status table**
+
+   Display a table summarizing all changes:
+
+   ```
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   |---------------------|-----------|-------|---------|-----------|--------|
+   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
+   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
+   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
+   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
+   ```
+
+   For conflicts, show the resolution:
+   ```
+   * Conflict resolution:
+     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
+   ```
+
+   For incomplete changes, show warnings:
+   ```
+   Warnings:
+   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
+   ```
+
+7. **Confirm batch operation**
+
+   Use **AskUserQuestion tool** with a single confirmation:
+
+   - "Archive N changes?" with options based on status
+   - Options might include:
+     - "Archive all N changes"
+     - "Archive only N ready changes (skip incomplete)"
+     - "Cancel"
+
+   If there are incomplete changes, make clear they'll be archived with warnings.
+
+8. **Execute archive for each confirmed change**
+
+   Process changes in the determined order (respecting conflict resolution):
+
+   a. **Sync specs** if delta specs exist:
+      - Use the openspec-sync-specs approach (agent-driven intelligent merge)
+      - For conflicts, apply in resolved order
+      - Track if sync was done
+
+   b. **Perform the archive**:
+      ```bash
+      mkdir -p openspec/changes/archive
+      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      ```
+
+   c. **Track outcome** for each change:
+      - Success: archived successfully
+      - Failed: error during archive (record error)
+      - Skipped: user chose not to archive (if applicable)
+
+9. **Display summary**
+
+   Show final results:
+
+   ```
+   ## Bulk Archive Complete
+
+   Archived 3 changes:
+   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
+   - project-config -> archive/2026-01-19-project-config/
+   - add-oauth -> archive/2026-01-19-add-oauth/
+
+   Skipped 1 change:
+   - add-verify-skill (user chose not to archive incomplete)
+
+   Spec sync summary:
+   - 4 delta specs synced to main specs
+   - 1 conflict resolved (auth: applied both in chronological order)
+   ```
+
+   If any failures:
+   ```
+   Failed 1 change:
+   - some-change: Archive directory already exists
+   ```
+
+**Conflict Resolution Examples**
+
+Example 1: Only one implemented
+```
+Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
+
+Checking add-oauth:
+- Delta adds "OAuth Provider Integration" requirement
+- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
+
+Checking add-jwt:
+- Delta adds "JWT Token Handling" requirement
+- Searching codebase... no JWT implementation found
+
+Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
+```
+
+Example 2: Both implemented
+```
+Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
+
+Checking add-rest-api (created 2026-01-10):
+- Delta adds "REST Endpoints" requirement
+- Searching codebase... found src/api/rest.ts
+
+Checking add-graphql (created 2026-01-15):
+- Delta adds "GraphQL Schema" requirement
+- Searching codebase... found src/api/graphql.ts
+
+Resolution: Both implemented. Will apply add-rest-api specs first,
+then add-graphql specs (chronological order, newer takes precedence).
+```
+
+**Output On Success**
+
+```
+## Bulk Archive Complete
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+- <change-2> -> archive/YYYY-MM-DD-<change-2>/
+
+Spec sync summary:
+- N delta specs synced to main specs
+- No conflicts (or: M conflicts resolved)
+```
+
+**Output On Partial Success**
+
+```
+## Bulk Archive Complete (partial)
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+
+Skipped M changes:
+- <change-2> (user chose not to archive incomplete)
+
+Failed K changes:
+- <change-3>: Archive directory already exists
+```
+
+**Output When No Changes**
+
+```
+## No Changes to Archive
+
+No active changes found. Use `/opsx:new` to create a new change.
+```
+
+**Guardrails**
+- Allow any number of changes (1+ is fine, 2+ is the typical use case)
+- Always prompt for selection, never auto-select
+- Detect spec conflicts early and resolve by checking codebase
+- When both changes are implemented, apply specs in chronological order
+- Skip spec sync only when implementation is missing (warn user)
+- Show clear per-change status before confirming
+- Use single confirmation for entire batch
+- Track and report all outcomes (success/skip/fail)
+- Preserve .openspec.yaml when moving to archive
+- Archive directory target uses current date: YYYY-MM-DD-<name>
+- If archive target exists, fail that change but continue with others
--- a/.claude/skills/openspec-continue-change/SKILL.md
+++ b/.claude/skills/openspec-continue-change/SKILL.md
@@ -0,0 +1,118 @@
+---
+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.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Continue working on a change by creating the next artifact.
+
+**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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+
+   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.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check current status**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   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", "ready", "blocked")
+   - `isComplete`: Boolean indicating if all artifacts are complete
+
+3. **Act based on status**:
+
+   ---
+
+   **If all artifacts are complete (`isComplete: true`)**:
+   - Congratulate the user
+   - Show final status including the schema used
+   - Suggest: "All artifacts created! You can now implement this change or 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
+     ```
+   - 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
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - **Create the artifact file**:
+     - Read any completed dependency files for context
+     - 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 output path specified in instructions
+   - 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>"
+   ```
+
+**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. Use the `instruction` field from the instructions output to understand what to create.
+
+Common artifact patterns:
+
+**spec-driven schema** (proposal → specs → design → tasks):
+- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
+  - The Capabilities section is critical - each capability listed will need a spec file.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
+- **design.md**: Document technical decisions, architecture, and implementation approach.
+- **tasks.md**: Break down implementation into checkboxed tasks.
+
+For other schemas, follow the `instruction` field from the CLI output.
+
+**Guardrails**
+- Create ONE artifact per invocation
+- Always read dependency artifacts before creating a new one
+- 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
--- a/.claude/skills/openspec-explore/SKILL.md
+++ b/.claude/skills/openspec-explore/SKILL.md
@@ -0,0 +1,290 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create one?"
+  → Can transition to `/opsx:new` or `/opsx:ff`
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │         CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into action**: "Ready to start? /opsx:new or /opsx:ff"
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change: /opsx:new <name>
+- Fast-forward to tasks: /opsx:ff <name>
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
--- a/.claude/skills/openspec-ff-change/SKILL.md
+++ b/.claude/skills/openspec-ff-change/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: openspec-ff-change
+description: Fast-forward through OpenSpec artifact creation. Use when the user wants to quickly create all artifacts needed for implementation without stepping through each one individually.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Fast-forward through artifact creation - generate everything needed to start implementation in one go.
+
+**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**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "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. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `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 for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "✓ Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **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
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, suggest continuing that change instead
+- Verify each artifact file exists after writing before proceeding to next
--- a/.claude/skills/openspec-new-change/SKILL.md
+++ b/.claude/skills/openspec-new-change/SKILL.md
@@ -0,0 +1,74 @@
+---
+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.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Start a new change using the experimental artifact-driven approach.
+
+**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**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "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` and let them choose
+
+   **Otherwise**: Omit `--schema` to use the default.
+
+3. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   Add `--schema <name>` only if the user requested a specific workflow.
+   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
+
+4. **Show the artifact status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+
+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>"
+   ```
+   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
--- a/.claude/skills/openspec-onboard/SKILL.md
+++ b/.claude/skills/openspec-onboard/SKILL.md
@@ -0,0 +1,529 @@
+---
+name: openspec-onboard
+description: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
+
+---
+
+## Preflight
+
+Before starting, check if OpenSpec is initialized:
+
+```bash
+openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+```
+
+**If not initialized:**
+> OpenSpec isn't set up in this project yet. Run `openspec init` first, then come back to `/opsx:onboard`.
+
+Stop here if not initialized.
+
+---
+
+## Phase 1: Welcome
+
+Display:
+
+```
+## Welcome to OpenSpec!
+
+I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
+
+**What we'll do:**
+1. Pick a small, real task in your codebase
+2. Explore the problem briefly
+3. Create a change (the container for our work)
+4. Build the artifacts: proposal → specs → design → tasks
+5. Implement the tasks
+6. Archive the completed change
+
+**Time:** ~15-20 minutes
+
+Let's start by finding something to work on.
+```
+
+---
+
+## Phase 2: Task Selection
+
+### Codebase Analysis
+
+Scan the codebase for small improvement opportunities. Look for:
+
+1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files
+2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
+3. **Functions without tests** - Cross-reference `src/` with test directories
+4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
+5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
+6. **Missing validation** - User input handlers without validation
+
+Also check recent git activity:
+```bash
+git log --oneline -10 2>/dev/null || echo "No git history"
+```
+
+### Present Suggestions
+
+From your analysis, present 3-4 specific suggestions:
+
+```
+## Task Suggestions
+
+Based on scanning your codebase, here are some good starter tasks:
+
+**1. [Most promising task]**
+   Location: `src/path/to/file.ts:42`
+   Scope: ~1-2 files, ~20-30 lines
+   Why it's good: [brief reason]
+
+**2. [Second task]**
+   Location: `src/another/file.ts`
+   Scope: ~1 file, ~15 lines
+   Why it's good: [brief reason]
+
+**3. [Third task]**
+   Location: [location]
+   Scope: [estimate]
+   Why it's good: [brief reason]
+
+**4. Something else?**
+   Tell me what you'd like to work on.
+
+Which task interests you? (Pick a number or describe your own)
+```
+
+**If nothing found:** Fall back to asking what the user wants to build:
+> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
+
+### Scope Guardrail
+
+If the user picks or describes something too large (major feature, multi-day work):
+
+```
+That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
+
+For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
+
+**Options:**
+1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
+2. **Pick something else** - One of the other suggestions, or a different small task?
+3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
+
+What would you prefer?
+```
+
+Let the user override if they insist—this is a soft guardrail.
+
+---
+
+## Phase 3: Explore Demo
+
+Once a task is selected, briefly demonstrate explore mode:
+
+```
+Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
+```
+
+Spend 1-2 minutes investigating the relevant code:
+- Read the file(s) involved
+- Draw a quick ASCII diagram if it helps
+- Note any considerations
+
+```
+## Quick Exploration
+
+[Your brief analysis—what you found, any considerations]
+
+┌─────────────────────────────────────────┐
+│   [Optional: ASCII diagram if helpful]  │
+└─────────────────────────────────────────┘
+
+Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
+
+Now let's create a change to hold our work.
+```
+
+**PAUSE** - Wait for user acknowledgment before proceeding.
+
+---
+
+## Phase 4: Create the Change
+
+**EXPLAIN:**
+```
+## Creating a Change
+
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
+
+Let me create one for our task.
+```
+
+**DO:** Create the change with a derived kebab-case name:
+```bash
+openspec new change "<derived-name>"
+```
+
+**SHOW:**
+```
+Created: `openspec/changes/<name>/`
+
+The folder structure:
+```
+openspec/changes/<name>/
+├── proposal.md    ← Why we're doing this (empty, we'll fill it)
+├── design.md      ← How we'll build it (empty)
+├── specs/         ← Detailed requirements (empty)
+└── tasks.md       ← Implementation checklist (empty)
+```
+
+Now let's fill in the first artifact—the proposal.
+```
+
+---
+
+## Phase 5: Proposal
+
+**EXPLAIN:**
+```
+## The Proposal
+
+The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
+
+I'll draft one based on our task.
+```
+
+**DO:** Draft the proposal content (don't save yet):
+
+```
+Here's a draft proposal:
+
+---
+
+## Why
+
+[1-2 sentences explaining the problem/opportunity]
+
+## What Changes
+
+[Bullet points of what will be different]
+
+## Capabilities
+
+### New Capabilities
+- `<capability-name>`: [brief description]
+
+### Modified Capabilities
+<!-- If modifying existing behavior -->
+
+## Impact
+
+- `src/path/to/file.ts`: [what changes]
+- [other files if applicable]
+
+---
+
+Does this capture the intent? I can adjust before we save it.
+```
+
+**PAUSE** - Wait for user approval/feedback.
+
+After approval, save the proposal:
+```bash
+openspec instructions proposal --change "<name>" --json
+```
+Then write the content to `openspec/changes/<name>/proposal.md`.
+
+```
+Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
+
+Next up: specs.
+```
+
+---
+
+## Phase 6: Specs
+
+**EXPLAIN:**
+```
+## Specs
+
+Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
+
+For a small task like this, we might only need one spec file.
+```
+
+**DO:** Create the spec file:
+```bash
+mkdir -p openspec/changes/<name>/specs/<capability-name>
+```
+
+Draft the spec content:
+
+```
+Here's the spec:
+
+---
+
+## ADDED Requirements
+
+### Requirement: <Name>
+
+<Description of what the system should do>
+
+#### Scenario: <Scenario name>
+
+- **WHEN** <trigger condition>
+- **THEN** <expected outcome>
+- **AND** <additional outcome if needed>
+
+---
+
+This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
+```
+
+Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
+
+---
+
+## Phase 7: Design
+
+**EXPLAIN:**
+```
+## Design
+
+The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
+
+For small changes, this might be brief. That's fine—not every change needs deep design discussion.
+```
+
+**DO:** Draft design.md:
+
+```
+Here's the design:
+
+---
+
+## Context
+
+[Brief context about the current state]
+
+## Goals / Non-Goals
+
+**Goals:**
+- [What we're trying to achieve]
+
+**Non-Goals:**
+- [What's explicitly out of scope]
+
+## Decisions
+
+### Decision 1: [Key decision]
+
+[Explanation of approach and rationale]
+
+---
+
+For a small task, this captures the key decisions without over-engineering.
+```
+
+Save to `openspec/changes/<name>/design.md`.
+
+---
+
+## Phase 8: Tasks
+
+**EXPLAIN:**
+```
+## Tasks
+
+Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
+
+These should be small, clear, and in logical order.
+```
+
+**DO:** Generate tasks based on specs and design:
+
+```
+Here are the implementation tasks:
+
+---
+
+## 1. [Category or file]
+
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+## 2. Verify
+
+- [ ] 2.1 [Verification step]
+
+---
+
+Each checkbox becomes a unit of work in the apply phase. Ready to implement?
+```
+
+**PAUSE** - Wait for user to confirm they're ready to implement.
+
+Save to `openspec/changes/<name>/tasks.md`.
+
+---
+
+## Phase 9: Apply (Implementation)
+
+**EXPLAIN:**
+```
+## Implementation
+
+Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
+```
+
+**DO:** For each task:
+
+1. Announce: "Working on task N: [description]"
+2. Implement the change in the codebase
+3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
+4. Mark complete in tasks.md: `- [ ]` → `- [x]`
+5. Brief status: "✓ Task N complete"
+
+Keep narration light—don't over-explain every line of code.
+
+After all tasks:
+
+```
+## Implementation Complete
+
+All tasks done:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+The change is implemented! One more step—let's archive it.
+```
+
+---
+
+## Phase 10: Archive
+
+**EXPLAIN:**
+```
+## Archiving
+
+When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
+```
+
+**DO:**
+```bash
+openspec archive "<name>"
+```
+
+**SHOW:**
+```
+Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`
+
+The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
+```
+
+---
+
+## Phase 11: Recap & Next Steps
+
+```
+## Congratulations!
+
+You just completed a full OpenSpec cycle:
+
+1. **Explore** - Thought through the problem
+2. **New** - Created a change container
+3. **Proposal** - Captured WHY
+4. **Specs** - Defined WHAT in detail
+5. **Design** - Decided HOW
+6. **Tasks** - Broke it into steps
+7. **Apply** - Implemented the work
+8. **Archive** - Preserved the record
+
+This same rhythm works for any size change—a small fix or a major feature.
+
+---
+
+## Command Reference
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through problems before/during work |
+| `/opsx:new` | Start a new change, step through artifacts |
+| `/opsx:ff` | Fast-forward: create all artifacts at once |
+| `/opsx:continue` | Continue working on an existing change |
+| `/opsx:apply` | Implement tasks from a change |
+| `/opsx:verify` | Verify implementation matches artifacts |
+| `/opsx:archive` | Archive a completed change |
+
+---
+
+## What's Next?
+
+Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now!
+```
+
+---
+
+## Graceful Exit Handling
+
+### User wants to stop mid-way
+
+If the user says they need to stop, want to pause, or seem disengaged:
+
+```
+No problem! Your change is saved at `openspec/changes/<name>/`.
+
+To pick up where we left off later:
+- `/opsx:continue <name>` - Resume artifact creation
+- `/opsx:apply <name>` - Jump to implementation (if tasks exist)
+
+The work won't be lost. Come back whenever you're ready.
+```
+
+Exit gracefully without pressure.
+
+### User just wants command reference
+
+If the user says they just want to see the commands or skip the tutorial:
+
+```
+## OpenSpec Quick Reference
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through problems (no code changes) |
+| `/opsx:new <name>` | Start a new change, step by step |
+| `/opsx:ff <name>` | Fast-forward: all artifacts at once |
+| `/opsx:continue <name>` | Continue an existing change |
+| `/opsx:apply <name>` | Implement tasks |
+| `/opsx:verify <name>` | Verify implementation |
+| `/opsx:archive <name>` | Archive when done |
+
+Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast.
+```
+
+Exit gracefully.
+
+---
+
+## Guardrails
+
+- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
+- **Keep narration light** during implementation—teach without lecturing
+- **Don't skip phases** even if the change is small—the goal is teaching the workflow
+- **Pause for acknowledgment** at marked points, but don't over-pause
+- **Handle exits gracefully**—never pressure the user to continue
+- **Use real codebase tasks**—don't simulate or use fake examples
+- **Adjust scope gently**—guide toward smaller tasks but respect user choice
--- a/.claude/skills/openspec-sync-specs/SKILL.md
+++ b/.claude/skills/openspec-sync-specs/SKILL.md
@@ -0,0 +1,138 @@
+---
+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.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+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).
+
+**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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   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.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/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 (don't need to copy existing ones)
+        - 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
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## 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
+#### 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`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## 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
+- 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
--- a/.claude/skills/openspec-verify-change/SKILL.md
+++ b/.claude/skills/openspec-verify-change/SKILL.md
@@ -0,0 +1,168 @@
+---
+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.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**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. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   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)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+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 tasks.md exists in contextFiles, read 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 `openspec/changes/<name>/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 design.md exists in contextFiles:
+     - 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**:
+   ```
+   ## 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
+      - 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"
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 /download
 /vm
-.claude
+/.claude/settings.local.json
+
--- a/CONCLUSIONS.md
+++ b/CONCLUSIONS.md
@@ -0,0 +1,169 @@
+# Conclusions: Yino Project Post-Mortem
+
+> Written: 2026-02-21
+> Status: Project abandoned
+> Duration: ~1 week (2026-02-15 to 2026-02-21)
+
+## What Yino was
+
+Yino ("Yino Is Not Omarchy") was an attempt to port [Omarchy](https://github.com/basecamp/omarchy) — an
+opinionated, keyboard-driven Hyprland desktop environment built on Arch Linux — to a stable Debian base.
+
+The motivation was simple: Omarchy's curated desktop experience is excellent, but Arch Linux's rolling
+release model introduces instability. Debian's conservative, long-term-support release cycle seemed like
+the ideal stable foundation to deliver the same experience without the rolling-release risk.
+
+## What we built
+
+- A QEMU VM helper (`bin/yino-vm`) with KVM acceleration for development and testing
+- A preseed configuration (`iso/preseed.cfg`) achieving unattended Debian installation with LUKS + btrfs
+- ISO build tooling for injecting preseed and packages into the stock Debian DVD image
+- Comprehensive requirements documentation (`REQUIREMENTS.md`) with 87 numbered requirement IDs
+- A detailed upstream analysis (`docs/Omarchy.md`) mapping Omarchy's full architecture at commit `463417a`
+- An Arch-to-Debian package mapping covering ~100+ packages across all components
+
+## The core problem: Hyprland doesn't fit stable distros
+
+The central discovery of this project is that **Hyprland is too fast-moving for any traditional stable
+Linux distribution to keep up with.**
+
+### Debian
+
+The entire Hyprland ecosystem was deliberately removed from Debian Trixie (stable) via
+[Debian Bug #1107152](https://bugs.debian.org/1107152). Hyprland remains in sid (unstable), but
+installing sid packages on a stable base is a known source of dependency conflicts and system
+instability — the exact problem Yino was trying to avoid.
+
+The Yino approach was to download Hyprland ecosystem packages from sid, cache them, and slipstream them
+into the installation ISO. This is workable in theory but creates a significant maintenance burden:
+
+- **12+ packages** from the Hyprland ecosystem need to be sourced from sid
+- **Library compatibility** between sid packages and the Trixie base is not guaranteed
+- **Every Debian stable point release** could break the cached sid packages
+- **Every Hyprland update** requires re-testing against the Trixie base
+- **Several additional packages** (Walker, Ghostty, Hyprsunset) aren't in Debian at all and need to be
+  built from source
+
+### Fedora (investigated as alternative)
+
+Initially, Fedora appeared promising — semi-stable with 6-month releases and what we believed was a
+Hyprland Spin. **Investigation revealed this was wrong on both counts:**
+
+- **There is no Fedora Hyprland Spin.** It doesn't exist, has never existed, and has no proposal in the
+  pipeline. The Fedora Sway Spin exists; Hyprland does not.
+- **Hyprland was retired from Fedora 43.** The package was present in Fedora 41 and 42, but was removed
+  from Fedora 43 because `hyprland-qtutils` depended on Qt 6.9 private APIs, and Fedora 43 moved to
+  Qt 6.10. Nobody stepped up to fix it. It was flagged via Bugzilla #2366813 as "F43FailsToInstall" and
+  subsequently retired (Pagure issue #12969).
+- **Community COPR repos** (`solopasha/hyprland`, `sdegler/hyprland`, etc.) exist but are volunteer-
+  maintained and fragile.
+
+Fedora's Hyprland situation is arguably **worse** than Debian's — Debian at least still has Hyprland
+in sid. Fedora's packaging is entirely gone from official repos and trending in the wrong direction.
+
+### openSUSE Tumbleweed (investigated as alternative)
+
+Tumbleweed is the strongest traditional option for Hyprland:
+
+- Hyprland is in **official repos** and actively maintained
+- Btrfs + Snapper is Tumbleweed's flagship feature (they pioneered the pattern Omarchy adopted)
+- KIWI image builder is world-class ISO tooling
+- openQA automated testing catches regressions before they reach users
+
+However, Tumbleweed is a **rolling release** — continuous updates, not periodic stable releases. This
+conflicts directly with the project's goal of providing a stable, predictable base. The whole point of
+Yino was to escape rolling-release churn, and Tumbleweed — however well-tested — is still rolling.
+
+### NixOS (investigated as alternative)
+
+NixOS is the most philosophically interesting option:
+
+- Hyprland is well-maintained in nixpkgs with first-class NixOS module support
+- The entire system is defined declaratively in configuration files — which aligns perfectly with
+  "an opinionated set of configuration files"
+- Versions are pinned, updates happen when you choose, rollbacks are atomic
+- ISO generation is trivial (a Nix expression)
+- `henrysipp/omarchy-nix` (657 stars) demonstrates significant community interest
+
+However, NixOS represents a **complete paradigm shift** from Omarchy's architecture. Omarchy is shell
+scripts overlaying dotfiles onto a traditional Linux system. NixOS would require reimagining the entire
+project as a Nix flake with home-manager modules. This violates the "match upstream Omarchy" design
+principle that was paramount for Yino.
+
+## The landscape at a glance
+
+| Distribution | Hyprland in official repos | Stability model | Trend |
+|:---|:---:|:---|:---|
+| Arch Linux | ✅ Always | Rolling (untested) | Stable — it's the native platform |
+| Debian sid | ✅ Yes | Unstable | Was in testing, yanked from stable |
+| Debian Trixie | ❌ Removed | Stable | Gone (Bug #1107152) |
+| Fedora 43 | ❌ Retired | 6-month releases | Gone (Qt 6.10 breakage) |
+| Fedora COPR | ⚠️ Community | Fragile | Depends on volunteers |
+| openSUSE TW | ✅ Official | Rolling (QA-tested) | Healthy |
+| NixOS | ✅ Official | Pinned by user | Very healthy |
+
+**Only rolling distros and NixOS maintain healthy Hyprland packaging.** Every traditional stable distro
+has dropped it.
+
+## Related community projects
+
+During research, we found these existing efforts to port Omarchy to other bases:
+
+| Project | Base | Stars | Notes |
+|:---|:---|---:|:---|
+| `henrysipp/omarchy-nix` | NixOS | 657 | Full Omarchy port as a Nix flake |
+| `elpritchos/omadora` | Fedora | 70 | Minimal Fedora + Hyprland, Omarchy-like |
+
+The NixOS port has nearly 10x the community interest of the Fedora attempt, suggesting the declarative
+approach resonates more strongly with the audience that wants "Omarchy but not on Arch."
+
+## Why we're stopping
+
+The fundamental tension is irreconcilable:
+
+> **Hyprland moves fast. Stable distros move slow. Bridging this gap is a full-time packaging job,
+> not a configuration project.**
+
+Yino was conceived as "an opinionated set of configuration files" — the same identity as Omarchy.
+But on Debian (or Fedora), the project would spend most of its effort on **packaging** (building,
+caching, testing, and maintaining 12+ Hyprland ecosystem packages against a stable base), leaving
+little room for the actual value proposition: the curated desktop experience.
+
+On Arch, Omarchy can focus on the experience because the packaging is handled by the distribution.
+On any stable distro, Yino would have to handle both — and the packaging burden dominates.
+
+## What would change this conclusion
+
+- **Hyprland stabilizes its ABI** and gets re-accepted into Debian stable or Fedora — unlikely given
+  the ecosystem's development velocity
+- **A third party maintains Hyprland packages for Debian/Fedora** reliably (a PPA, COPR, or OBS repo
+  with serious commitment) — possible but not something to bet a project on
+- **The project embraces NixOS** and accepts the paradigm shift — viable, and `omarchy-nix` proves
+  demand exists, but it's a different project with a different identity
+- **The project embraces Tumbleweed** and accepts rolling release (with snapshot safety) — the most
+  natural fit technically, but contradicts the original motivation
+
+## Open questions that were never resolved
+
+These were identified during requirements analysis but never investigated due to the project being
+abandoned:
+
+- **OQ-001:** Would the Hyprland stack from sid actually install cleanly on Trixie, or would it pull
+  cascading dependencies that destabilize the system?
+- **OQ-002:** What are Walker's build dependencies? Static binary or proper .deb packaging?
+- **OQ-003:** Ghostty sourcing — build from source (Zig toolchain), community .debs, or use Alacritty?
+- **OQ-004:** Hyprsunset vs. wlsunset — is the Omarchy-compatible version worth the build effort?
+- **OQ-006:** ISO build tool choice — live-build, simple-cdd, or manual remastering?
+
+## Artifacts produced
+
+All artifacts remain in the repository for reference:
+
+| File | Description |
+|:---|:---|
+| `REQUIREMENTS.md` | Full requirements document (87 requirement IDs, user stories, acceptance criteria) |
+| `docs/Omarchy.md` | Comprehensive Omarchy analysis at commit `463417a` (architecture, packages, ISO, theming) |
+| `docs/yino-fsd.md` | Functional specification document |
+| `iso/preseed.cfg` | Working preseed config for unattended Debian install (LUKS + btrfs + Hyprland) |
+| `bin/yino-vm` | QEMU VM helper with KVM acceleration |
+| `CONCLUSIONS.md` | This document |
--- a/21
+++ b/21
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/REQUIREMENTS.md
+++ b/REQUIREMENTS.md
@@ -0,0 +1,486 @@
+# Requirements: Yino
+
+> Generated during /opsx:explore session on 2026-02-21
+> Status: Draft — pending architect review
+
+## 1. Project Overview
+
+### Vision
+
+Yino ("Yino Is Not Omarchy") is a full-fidelity port of [Omarchy](https://github.com/basecamp/omarchy) from Arch
+Linux to Debian Linux. It delivers the same opinionated, keyboard-driven Hyprland desktop experience but on a stable
+Debian base instead of Arch's rolling release.
+
+### Problem Being Solved
+
+Omarchy is Arch-only. Users who want its curated desktop experience but prefer or require Debian's stability and
+ecosystem (enterprise environments, known hardware support, LTS lifecycle) have no option today. Yino fills that gap.
+
+### Success Criteria
+
+- SC-001: A user can boot a Yino ISO, complete an unattended installation (offline-capable), and arrive at a working
+  Hyprland desktop identical in look, feel, and functionality to Omarchy
+- SC-002: All Omarchy `omarchy-*` commands have working `yino-*` equivalents
+- SC-003: Omarchy themes install and work on Yino without modification (file structure compatibility)
+- SC-004: Upstream Omarchy changes can be evaluated and ported to Yino with reasonable effort
+
+### Context
+
+- **Greenfield vs. existing:** Partial existing work. A QEMU VM helper (`bin/yino-vm`), a preseed config
+  (`iso/preseed.cfg`), and reference documentation exist. The preseed achieves a bootable Hyprland system but uses a
+  fragile approach (nested echo statements in `late_command`, network dependency on sid). The project needs a clean
+  architecture before proceeding further.
+- **Upstream reference:** Omarchy @ `463417a` (`dev` branch), analyzed 2026-02-16. See `docs/Omarchy.md`.
+- **Base OS:** Debian 13 "Trixie" (stable, released August 2025)
+
+## 2. Stakeholders & Users
+
+### Primary User
+
+Single-user desktop operator. Same persona as Omarchy's target: a developer who wants an opinionated, pre-configured
+Linux desktop and doesn't want to assemble it themselves.
+
+### Technical Ability
+
+Comfortable with Linux basics (terminal, sudo, SSH). Does not want to compile kernels or debug Wayland protocols.
+Expects things to work out of the box after installation.
+
+### Scale
+
+Single machine per installation. No fleet management, no multi-user, no remote deployment (for now).
+
+### Target Hardware
+
+- Architecture: amd64 only
+- Reference hardware: Framework 13 AMD Ryzen 7040 (future, not immediate)
+- Immediate target: QEMU VM (development and testing)
+
+## 3. Functional Requirements
+
+### 3.1 ISO Generation & Installation
+
+**FR-001: Offline-capable installation ISO**
+- The project shall produce tooling to generate a custom Debian 13 (Trixie) installation ISO
+- The ISO shall contain all packages needed for a complete Yino installation, including packages not in Trixie stable
+  (downloaded from sid and cached/slipstreamed into the ISO)
+- Installation shall work without network access (offline-capable)
+- _Priority: Must_
+- _Acceptance criteria:_ Running the ISO build script produces a bootable ISO. Booting that ISO in a network-isolated
+  QEMU VM results in a complete Yino installation.
+
+**FR-002: Unattended installation via preseed**
+- The Debian installer shall be driven by a preseed configuration
+- Preseed scope is limited to base OS concerns: locale, partitioning, encryption, filesystem, user account, bootloader
+- The preseed shall configure: LUKS full-disk encryption, btrfs filesystem, a single user account with automatic login,
+  GRUB bootloader with serial console support (for VM testing)
+- _Priority: Must_
+- _Acceptance criteria:_ The installation completes without user interaction beyond the LUKS passphrase (which is
+  hardcoded for dev/test, prompted in production).
+
+**FR-003: Post-install configuration via installer script**
+- All desktop environment setup, package installation, and configuration shall be handled by a separate installer
+  script, not by the preseed `late_command`
+- The installer shall follow Omarchy's phased architecture (preflight, packaging, config, login, post-install)
+- The installer shall be idempotent (safe to re-run)
+- _Priority: Must_
+- _Acceptance criteria:_ The preseed triggers the installer (via a first-boot systemd service or equivalent). The
+  installer runs the full phase sequence and produces a working desktop.
+
+**FR-004: ISO build script**
+- A reproducible build script shall take the stock Debian 13 DVD ISO, inject the preseed, cached packages, and
+  installer, and produce the final Yino ISO
+- Downloaded assets (Debian ISO, sid .debs) shall be cached in the `download/` directory
+- _Priority: Must_
+- _Acceptance criteria:_ Running the build script twice with the same inputs produces functionally identical ISOs.
+
+### 3.2 Desktop Environment
+
+**FR-010: Hyprland compositor**
+- Hyprland shall be the sole compositor (Wayland-only, no X11)
+- Launched via UWSM through SDDM with automatic login
+- Configuration shall follow Omarchy's structure: `hyprland.conf` sourcing `bindings.conf`, `monitors.conf`,
+  `input.conf`, `looknfeel.conf`
+- _Priority: Must_
+- _Acceptance criteria:_ After installation, the system boots to a Hyprland desktop with working window tiling,
+  workspaces, and keybindings matching Omarchy's defaults.
+
+**FR-011: Status bar (Waybar)**
+- Waybar shall provide the top status bar
+- Module layout shall match Omarchy: logo + workspaces (left), clock + indicators (center), tray + network + audio +
+  cpu + battery (right)
+- _Priority: Must_
+
+**FR-012: Application launcher (Walker)**
+- Walker shall be the application launcher, bound to Super + Space
+- Provides fuzzy search across applications, files, and commands
+- _Note:_ Walker is not packaged for Debian. Must be built from source or packaged as .deb.
+- _Priority: Must_
+
+**FR-013: Notification daemon (Mako)**
+- Mako shall handle desktop notifications with theme-aware styling
+- _Priority: Must_
+
+**FR-014: On-screen display (SwayOSD)**
+- SwayOSD shall provide OSD for volume, brightness, and caps lock changes
+- _Note:_ Trixie has 0.1.0 (old). Sid has 0.3.0. Use sid version.
+- _Priority: Should_
+
+**FR-015: Lock screen (Hyprlock)**
+- Hyprlock shall provide the lock screen with theme-aware styling
+- _Priority: Must_
+
+**FR-016: Idle management (Hypridle)**
+- Hypridle shall manage screen dimming, locking, and suspend after configurable idle timeouts
+- _Priority: Must_
+
+**FR-017: Night light (Hyprsunset)**
+- Hyprsunset shall provide blue light filtering
+- _Note:_ Not packaged in any Debian suite. Must be built from source. Alternative: `wlsunset` is in Debian.
+- _Priority: Should_
+
+**FR-018: Terminal emulators**
+- Ghostty shall be the default terminal
+- Alacritty shall also be installed
+- _Note:_ Ghostty is not packaged for Debian. Community .deb builds exist (debian.griffo.io). Evaluate whether to
+  use community builds or build from source.
+- _Priority: Must (Ghostty), Should (Alacritty pre-installed)_
+
+**FR-019: Neovim**
+- Neovim shall be installed with a configuration equivalent to Omarchy's `omarchy-nvim`
+- The configuration shall include LSP, Treesitter, and the pixel.nvim colorscheme (ANSI-color-adaptive)
+- _Note:_ Can be delivered as dotfiles overlay rather than a .deb package.
+- _Priority: Must_
+
+**FR-020: Browser**
+- Chromium shall be the default browser
+- _Note:_ Omarchy ships a custom `omarchy-chromium` with live Material Design 3 theme switching. This is significant
+  build effort. Standard Debian Chromium is acceptable for v1; custom build is a future enhancement.
+- _Priority: Must (standard Chromium), Could (live theme switching via custom build)_
+
+### 3.3 Configuration System
+
+**FR-030: Three-layer configuration system**
+- Yino shall implement Omarchy's 3-layer config system:
+  - Layer 1 (Default): `~/.local/share/yino/default/` — factory defaults, overwritten on update
+  - Layer 2 (Theme): `~/.local/share/yino/themes/<name>/` — theme overrides
+  - Layer 3 (User): `~/.config/` — user customizations, highest priority
+- _Priority: Must_
+
+**FR-031: Keybindings**
+- All Omarchy default keybindings shall be replicated (Super as primary modifier)
+- Super + Return = Terminal, Super + Space = Walker, Super + W = Close, etc.
+- Full keybinding reference accessible via Super + K
+- _Priority: Must_
+
+**FR-032: User hooks**
+- Users shall be able to place scripts in `~/.config/yino/hooks/` for event-driven customization
+- The `yino-hook` command shall dispatch named hooks
+- _Priority: Should_
+
+### 3.4 Theming
+
+**FR-040: Theme system**
+- Yino shall support Omarchy's theme format: a directory containing up to 10 files (alacritty.toml, btop.theme,
+  hyprland.conf, hyprlock.conf, mako.ini, neovim.lua, swayosd.css, walker.css, waybar.css, backgrounds/)
+- `yino-theme-set <name>` shall atomically restyle all themed components
+- _Priority: Must_
+- _Acceptance criteria:_ Installing an Omarchy community theme (e.g., synthwave84) via its git URL works without
+  modification.
+
+**FR-041: Built-in themes**
+- All 14 Omarchy built-in themes shall be included
+- _Priority: Must_
+
+**FR-042: Community theme support**
+- `yino-theme-install <git-url>` shall install third-party themes from Git repositories
+- _Priority: Must_
+
+### 3.5 Menu System
+
+**FR-050: Yino menu**
+- `yino-menu` shall replicate Omarchy's hierarchical menu system via Walker
+- Menu structure: Apps, Learn, Trigger, Style, Setup, Install, Remove, Update, About, System
+- All submenus shall have working Debian equivalents of their Omarchy counterparts
+- _Priority: Must_
+
+### 3.6 System Management
+
+**FR-060: Update system**
+- `yino-update` shall: create a btrfs snapshot, pull latest Yino from git, run pending migrations, re-run the
+  installer pipeline idempotently
+- _Priority: Must_
+
+**FR-061: Snapshot management**
+- Btrfs snapshots via Snapper with configurable limits
+- `yino-snapshot` for manual snapshot creation
+- _Priority: Must_
+
+**FR-062: Migration system**
+- Timestamped migration scripts that run once per system (same mechanism as Omarchy)
+- Tracked in a state file so they don't re-run
+- _Priority: Must_
+
+### 3.7 Security
+
+**FR-070: Full-disk encryption**
+- LUKS encryption is mandatory during installation
+- _Priority: Must_
+
+**FR-071: Firewall**
+- UFW enabled by default
+- _Priority: Must_
+
+**FR-072: GPG and keyring**
+- GPG agent configured for signing
+- GNOME keyring auto-unlocked on login
+- _Priority: Must_
+
+**FR-073: SSH configuration**
+- Connection stability tweaks matching Omarchy
+- _Priority: Should_
+
+### 3.8 Boot
+
+**FR-080: Plymouth boot splash**
+- Custom Yino-branded Plymouth theme (adapted from Omarchy's Tokyo Night theme)
+- LUKS passphrase prompt over the splash, progress bar animation
+- _Priority: Should_
+
+**FR-081: SDDM auto-login**
+- SDDM configured for automatic login to hyprland-uwsm session
+- Single-user model: disk decryption authenticates the user
+- _Priority: Must_
+
+### 3.9 Applications & Utilities
+
+**FR-090: Pre-installed applications**
+- The following shall be installed: Chromium, Nautilus (file manager), evince (PDF viewer), mpv (media player),
+  LibreOffice
+- _Priority: Must_
+
+**FR-091: Pre-installed CLI utilities**
+- The following shall be installed: btop, fastfetch, ripgrep, fzf, bat, eza, zoxide, dust, jq, gum, lazygit
+- _Priority: Must_
+
+**FR-092: Development tools**
+- Docker and docker-compose, GitHub CLI (gh), mise (dev tool version manager)
+- _Priority: Should_
+
+**FR-093: Optional applications**
+- Spotify, Typora, Obsidian, Signal, 1Password — installable via `yino-menu` > Install
+- These should be available to install, not necessarily pre-installed
+- _Priority: Could_
+
+### 3.10 Shell Scripts (yino-* commands)
+
+**FR-100: Command parity**
+- Every `omarchy-*` command shall have a `yino-*` equivalent
+- Package management wrappers shall use `apt` instead of `pacman`/`yay`
+- All Arch-specific logic shall be replaced with Debian equivalents
+- _Priority: Must_
+
+**FR-101: Hardware detection and fixes**
+- Hardware-specific fixes from Omarchy shall be ported where applicable to Debian
+- NVIDIA, Bluetooth, printing, audio, Wi-Fi power save, USB autosuspend
+- Apple-specific fixes: evaluate relevance, defer if not needed for target hardware
+- _Priority: Should_
+
+## 4. Non-Functional Requirements
+
+**NFR-001: Debian stable as base**
+- Trixie (Debian 13) is the base. All packages shall come from Trixie stable where available.
+- Packages not in Trixie (primarily the Hyprland ecosystem) shall be sourced from sid, cached, and included in the ISO.
+- No runtime dependency on sid repositories. After installation, the system shall be fully functional without network.
+- _Rationale:_ Debian stable's conservative updates are the whole point of Yino over Omarchy/Arch.
+
+**NFR-002: Package sourcing tiers**
+- Tier 1 — Trixie stable (use directly): ~90% of packages (Mako, swaybg, SDDM, Alacritty, Neovim, all CLI tools,
+  pipewire, cups, fonts, etc.)
+- Tier 2 — sid .debs (download, cache, slipstream): Hyprland ecosystem (12+ packages), UWSM, newer Waybar (0.15),
+  newer SwayOSD (0.3.0)
+- Tier 3 — Build from source or external (cache as .debs): Walker, Ghostty, Hyprsunset, lazydocker
+- _Rationale:_ The entire Hyprland ecosystem was deliberately removed from Trixie (Debian Bug #1107152). sid is the
+  only official Debian source.
+
+**NFR-003: Offline installation**
+- A completed Yino ISO shall contain all packages needed for installation. No network required during install.
+- Network may be used during ISO build to download and cache packages.
+
+**NFR-004: Reproducible ISO builds**
+- The ISO build process shall be scripted and deterministic given the same input packages.
+- All downloaded assets cached in `download/`.
+
+**NFR-005: Upstream tracking**
+- Yino shall track upstream Omarchy development on the `dev` branch.
+- The `docs/Omarchy.md` analysis document shall be kept current.
+- Changes shall be evaluated and ported where applicable using the Arch-to-Debian mapping in `docs/Omarchy.md` §14.
+
+**NFR-006: Naming convention**
+- All scripts shall use the `yino-` prefix (not `omarchy-`).
+- Internal paths shall use `yino` (e.g., `~/.local/share/yino/`, `yino-first-boot.service`).
+- Config directory: `~/.config/yino/` (for Yino-specific config; component configs like Hyprland remain in their
+  standard locations).
+
+**NFR-007: QEMU testability**
+- The system shall boot and be fully functional in a QEMU VM (including software-rendered cursors and virtual GPU).
+- The `bin/yino-vm` helper shall remain the primary development/test tool.
+
+**NFR-008: Idempotent installer**
+- The installer script shall be safe to run multiple times. Re-running shall bring the system to the desired state
+  without duplication or breakage.
+
+**NFR-009: Maintainability**
+- No shell scripts written as nested echo statements inside preseed `late_command`.
+- Preseed handles base OS only. Installer is a separate, readable, version-controlled script tree.
+- Clear separation: preseed → first-boot trigger → installer phases.
+
+## 5. Constraints
+
+### Technical
+
+- **Debian 13 Trixie only.** No support for Bookworm (12) or older.
+- **amd64 only.** No arm64 or other architectures.
+- **Wayland only.** No X11 support or fallback.
+- **No custom Debian package repository** (for now). Packages not in Debian are cached as .deb files and included
+  in the ISO. A proper apt repo is future work.
+- **No Secure Boot.** Same as Omarchy — explicitly not supported.
+
+### Business / Process
+
+- **Minimize dependencies.** Discuss with owner before adding anything not in Omarchy.
+- **Match upstream Omarchy.** When multiple approaches exist, prefer the one Omarchy uses. Deviate only where strictly
+  necessary for Debian compatibility.
+- **KISS.** Simple solutions preferred. Less is more.
+
+### Scope Exclusions (explicit "Won't" for now)
+
+- Custom Chromium build with live theme switching (use standard Debian Chromium)
+- Custom apt package repository infrastructure
+- Multi-architecture support (arm64)
+- Fleet deployment or multi-user scenarios
+- Apple hardware-specific fixes (T2 chip, SPI keyboard, NVMe suspend)
+
+## 6. Assumptions & Dependencies
+
+### Assumptions
+
+- A-001: Debian 13 Trixie remains the current stable release throughout development
+- A-002: Hyprland ecosystem packages in sid remain buildable/installable on a Trixie base (library compatibility)
+- A-003: Omarchy's `dev` branch remains the active development branch
+- A-004: The QEMU VM provides sufficient test coverage for the initial development phase
+- A-005: Community Ghostty .deb builds (e.g., debian.griffo.io) are trustworthy for development; production may
+  require building from source
+
+### Dependencies
+
+- D-001: Upstream Omarchy repository (`basecamp/omarchy`) for reference configs, themes, and scripts
+- D-002: Debian sid repository for Hyprland ecosystem .debs
+- D-003: Stock Debian 13 DVD ISO (`debian-13.x.x-amd64-DVD-1.iso`) as build input
+- D-004: QEMU + OVMF for development testing
+
+## 7. Open Questions
+
+- OQ-001: **sid library compatibility** — Will the Hyprland stack from sid install cleanly on a Trixie base, or will
+  it pull in cascading sid dependencies that destabilize the system? Needs a spike: download the Hyprland .debs from
+  sid and attempt install on a clean Trixie system.
+- OQ-002: **Walker build** — Walker is a Go application. What are its build dependencies? Can we produce a static
+  binary and ship it without a .deb? Or should we package it properly?
+- OQ-003: **Ghostty sourcing** — Build from source (Zig toolchain needed), use community .debs, or defer Ghostty and
+  use Alacritty/foot as default terminal?
+- OQ-004: **Hyprsunset vs. wlsunset** — Hyprsunset is not in Debian at all. `wlsunset` is in Trixie stable and
+  provides similar functionality. Is Omarchy compatibility worth the build effort, or is wlsunset an acceptable
+  substitute?
+- OQ-005: **Waybar version** — Trixie ships 0.12.0, sid has 0.15.0. Does Omarchy's Waybar config require features
+  from 0.15? If so, Waybar moves to Tier 2 (sid).
+- OQ-006: **ISO build tool** — `live-build`, `simple-cdd`, or manual ISO remastering (extract, inject preseed +
+  packages, repackage)? Each has tradeoffs in complexity vs. control.
+- OQ-007: **Omarchy theme names** — The analysis document doesn't list all 14 built-in theme names. Need to inspect
+  the upstream `themes/` directory to enumerate them.
+- OQ-008: **Update channel model** — Omarchy has 4 channels (stable/rc/edge/dev). Yino on Debian stable likely needs
+  only 1-2. What's the right model?
+
+## 8. Glossary
+
+| Term | Definition |
+|:-----|:-----------|
+| **Omarchy** | Upstream Arch Linux-based desktop distribution by Basecamp/DHH |
+| **Yino** | "Yino Is Not Omarchy" — this project; Debian-based port of Omarchy |
+| **Trixie** | Debian 13, the current stable release (August 2025) |
+| **sid** | Debian unstable — rolling release, always the newest packages |
+| **forky** | Debian testing — the future Debian 14 |
+| **Hyprland** | Wayland compositor and tiling window manager |
+| **UWSM** | Universal Wayland Session Manager — launches Hyprland via SDDM |
+| **Walker** | Application launcher used by Omarchy (fuzzy search over apps/files/commands) |
+| **SDDM** | Simple Desktop Display Manager — handles login/auto-login |
+| **preseed** | Debian installer automation format (answer file for `debian-installer`) |
+| **OPR** | Omarchy Package Repository — custom Arch packages built by the Omarchy team |
+| **Snapper** | Btrfs snapshot management tool |
+| **LUKS** | Linux Unified Key Setup — full-disk encryption |
+| **Plymouth** | Boot splash screen system |
+| **pixel.nvim** | Neovim colorscheme that adapts to terminal ANSI colors (0-15) |
+| **slipstream** | To inject additional packages/files into an existing ISO image |
+
+## Appendix: Priority Matrix
+
+### Must Have (required for a functional system)
+
+| ID | Requirement |
+|:---|:------------|
+| FR-001 | Offline-capable installation ISO |
+| FR-002 | Unattended installation via preseed |
+| FR-003 | Post-install configuration via installer script |
+| FR-004 | ISO build script |
+| FR-010 | Hyprland compositor |
+| FR-011 | Waybar status bar |
+| FR-012 | Walker application launcher |
+| FR-013 | Mako notifications |
+| FR-015 | Hyprlock lock screen |
+| FR-016 | Hypridle idle management |
+| FR-018 | Ghostty terminal (or acceptable substitute) |
+| FR-019 | Neovim with config |
+| FR-020 | Chromium browser (standard) |
+| FR-030 | Three-layer configuration system |
+| FR-031 | Keybindings (Omarchy defaults) |
+| FR-040 | Theme system (Omarchy-compatible format) |
+| FR-041 | 14 built-in themes |
+| FR-042 | Community theme support |
+| FR-050 | Yino menu |
+| FR-060 | Update system |
+| FR-061 | Snapshot management |
+| FR-062 | Migration system |
+| FR-070 | LUKS full-disk encryption |
+| FR-071 | UFW firewall |
+| FR-072 | GPG and keyring |
+| FR-081 | SDDM auto-login |
+| FR-090 | Pre-installed GUI applications |
+| FR-091 | Pre-installed CLI utilities |
+| FR-100 | yino-* command parity |
+
+### Should Have (expected but not blocking)
+
+| ID | Requirement |
+|:---|:------------|
+| FR-014 | SwayOSD on-screen display |
+| FR-017 | Hyprsunset / night light |
+| FR-032 | User hooks |
+| FR-073 | SSH configuration |
+| FR-080 | Plymouth boot splash |
+| FR-092 | Development tools (Docker, gh, mise) |
+| FR-101 | Hardware detection and fixes |
+
+### Could Have (desirable, defer if needed)
+
+| ID | Requirement |
+|:---|:------------|
+| FR-020 | Custom Chromium with live theme switching |
+| FR-093 | Optional applications (Spotify, Typora, Obsidian, Signal, 1Password) |
+
+### Won't Have (explicitly out of scope)
+
+| Item | Reason |
+|:-----|:-------|
+| Custom apt repository | Premature; cache .debs directly for now |
+| arm64 support | amd64 only |
+| Multi-user / fleet deployment | Single-user desktop only |
+| Apple hardware fixes | Not relevant to target hardware |
+| Secure Boot | Same as Omarchy — not supported |
--- a/bin/yino-vm
+++ b/bin/yino-vm
@@ -32,6 +32,7 @@ find_ovmf_code() {
            /usr/share/OVMF/OVMF_CODE.fd
            /usr/share/qemu/OVMF_CODE_4M.fd
            /usr/share/qemu/OVMF_CODE.fd
+            /usr/share/edk2/x64/OVMF_CODE.4m.fd
            /usr/share/edk2/x64/OVMF_CODE.fd
        )
    fi
@@ -64,6 +65,7 @@ find_ovmf_vars_template() {
            /usr/share/OVMF/OVMF_VARS.fd
            /usr/share/qemu/OVMF_VARS_4M.fd
            /usr/share/qemu/OVMF_VARS.fd
+            /usr/share/edk2/x64/OVMF_VARS.4m.fd
            /usr/share/edk2/x64/OVMF_VARS.fd
        )
    fi
--- a/iso/preseed.cfg
+++ b/iso/preseed.cfg
@@ -83,7 +83,10 @@ d-i cdrom-checker/start boolean false
 # Finish
 d-i finish-install/reboot_in_progress note

-# Post-install: configure serial console, SDDM + UWSM + Hyprland desktop
+# Post-install: configure serial console, sid repo, and first-boot desktop setup
+# NOTE: preseed interprets \n as literal newlines, breaking shell commands.
+# Use multiple echo commands instead of printf with \n for multi-line files.
+# Heavy package installation is deferred to a first-boot systemd service.
 d-i preseed/late_command string \
    USER=$(grep ':x:1000:' /target/etc/passwd | cut -d: -f1); \
    LOG=/target/var/log/yino-late-command.log; \
@@ -99,22 +102,81 @@ d-i preseed/late_command string \
    echo "nameserver 1.1.1.1" > /target/etc/resolv.conf; \
    echo "--- sid repo ---" >> $LOG; \
    echo 'deb http://deb.debian.org/debian sid main contrib non-free-firmware' > /target/etc/apt/sources.list.d/sid.list; \
-    printf 'Package: *\nPin: release a=unstable\nPin-Priority: 100\n' > /target/etc/apt/preferences.d/sid-low-priority; \
-    echo "--- apt-get update ---" >> $LOG; \
-    in-target apt-get update >> $LOG 2>&1 || echo "FAILED: apt-get update (exit $?)" >> $LOG; \
-    echo "--- install sddm ---" >> $LOG; \
-    in-target env DEBIAN_FRONTEND=noninteractive apt-get -y install sddm >> $LOG 2>&1 || echo "FAILED: install sddm (exit $?)" >> $LOG; \
-    echo "--- install hyprland uwsm foot ---" >> $LOG; \
-    in-target env DEBIAN_FRONTEND=noninteractive apt-get -y -t unstable install hyprland uwsm foot >> $LOG 2>&1 || echo "FAILED: install hyprland (exit $?)" >> $LOG; \
-    echo "--- SDDM config ---" >> $LOG; \
-    mkdir -p /target/etc/sddm.conf.d; \
-    printf '[Autologin]\nUser=%s\nSession=hyprland-uwsm\n\n[Theme]\nCurrent=breeze\n' "$USER" > /target/etc/sddm.conf.d/autologin.conf; \
-    in-target systemctl enable sddm >> $LOG 2>&1 || echo "FAILED: enable sddm" >> $LOG; \
-    mkdir -p /target/usr/share/wayland-sessions; \
-    printf '[Desktop Entry]\nName=Hyprland (UWSM)\nComment=Hyprland via Universal Wayland Session Manager\nExec=uwsm start hyprland.desktop\nType=Application\nDesktopNames=Hyprland\n' > /target/usr/share/wayland-sessions/hyprland-uwsm.desktop; \
-    echo "--- Hyprland config ---" >> $LOG; \
-    UHOME=/target/home/$USER; \
-    mkdir -p $UHOME/.config/hyprland; \
-    printf 'monitor = ,preferred,auto,1\n\nenv = WLR_NO_HARDWARE_CURSORS,1\nenv = WLR_RENDERER_ALLOW_SOFTWARE,1\n\nexec-once = foot --server\n\n$mainMod = SUPER\n\nbind = $mainMod, Return, exec, foot\nbind = $mainMod SHIFT, Q, killactive\nbind = $mainMod SHIFT, E, exit\n\nbind = $mainMod, 1, workspace, 1\nbind = $mainMod, 2, workspace, 2\nbind = $mainMod, 3, workspace, 3\nbind = $mainMod, 4, workspace, 4\nbind = $mainMod, 5, workspace, 5\n\nbind = $mainMod, left, movefocus, l\nbind = $mainMod, right, movefocus, r\nbind = $mainMod, up, movefocus, u\nbind = $mainMod, down, movefocus, d\n' > $UHOME/.config/hyprland/hyprland.conf; \
-    chown -R 1000:1000 $UHOME/.config; \
+    F=/target/etc/apt/preferences.d/sid-low-priority; \
+    echo 'Package: *' > $F; \
+    echo 'Pin: release a=unstable' >> $F; \
+    echo 'Pin-Priority: 100' >> $F; \
+    echo "--- first-boot setup script ---" >> $LOG; \
+    S=/target/usr/local/sbin/yino-first-boot; \
+    echo '#!/bin/sh' > $S; \
+    echo 'set -ex' >> $S; \
+    echo 'LOG=/var/log/yino-first-boot.log' >> $S; \
+    echo 'exec > "$LOG" 2>&1' >> $S; \
+    echo 'echo "=== Yino first-boot start ==="' >> $S; \
+    echo 'USER=$(grep ":x:1000:" /etc/passwd | cut -d: -f1)' >> $S; \
+    echo 'export DEBIAN_FRONTEND=noninteractive' >> $S; \
+    echo 'apt-get update' >> $S; \
+    echo 'apt-get -y install sddm' >> $S; \
+    echo 'apt-get -y -t unstable install hyprland uwsm foot' >> $S; \
+    echo 'mkdir -p /etc/sddm.conf.d' >> $S; \
+    echo 'echo "[Autologin]" > /etc/sddm.conf.d/autologin.conf' >> $S; \
+    echo 'echo "User=$USER" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
+    echo 'echo "Session=hyprland-uwsm" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
+    echo 'echo "" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
+    echo 'echo "[Theme]" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
+    echo 'echo "Current=breeze" >> /etc/sddm.conf.d/autologin.conf' >> $S; \
+    echo 'systemctl enable sddm' >> $S; \
+    echo 'mkdir -p /usr/share/wayland-sessions' >> $S; \
+    echo 'echo "[Desktop Entry]" > /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
+    echo 'echo "Name=Hyprland (UWSM)" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
+    echo 'echo "Comment=Hyprland via Universal Wayland Session Manager" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
+    echo 'echo "Exec=uwsm start hyprland.desktop" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
+    echo 'echo "Type=Application" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
+    echo 'echo "DesktopNames=Hyprland" >> /usr/share/wayland-sessions/hyprland-uwsm.desktop' >> $S; \
+    echo 'UHOME=/home/$USER' >> $S; \
+    echo 'mkdir -p $UHOME/.config/hyprland' >> $S; \
+    echo 'F=$UHOME/.config/hyprland/hyprland.conf' >> $S; \
+    echo 'echo "monitor = ,preferred,auto,1" > $F' >> $S; \
+    echo 'echo "" >> $F' >> $S; \
+    echo 'echo "env = WLR_NO_HARDWARE_CURSORS,1" >> $F' >> $S; \
+    echo 'echo "env = WLR_RENDERER_ALLOW_SOFTWARE,1" >> $F' >> $S; \
+    echo 'echo "" >> $F' >> $S; \
+    echo 'echo "exec-once = foot --server" >> $F' >> $S; \
+    echo 'echo "" >> $F' >> $S; \
+    echo 'echo "\$mainMod = SUPER" >> $F' >> $S; \
+    echo 'echo "" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, Return, exec, foot" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod SHIFT, Q, killactive" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod SHIFT, E, exit" >> $F' >> $S; \
+    echo 'echo "" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, 1, workspace, 1" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, 2, workspace, 2" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, 3, workspace, 3" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, 4, workspace, 4" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, 5, workspace, 5" >> $F' >> $S; \
+    echo 'echo "" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, left, movefocus, l" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, right, movefocus, r" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, up, movefocus, u" >> $F' >> $S; \
+    echo 'echo "bind = \$mainMod, down, movefocus, d" >> $F' >> $S; \
+    echo 'chown -R 1000:1000 $UHOME/.config' >> $S; \
+    echo 'systemctl disable yino-first-boot.service' >> $S; \
+    echo 'rm -f /usr/local/sbin/yino-first-boot' >> $S; \
+    echo 'echo "=== Yino first-boot done ==="' >> $S; \
+    chmod 755 $S; \
+    F=/target/etc/systemd/system/yino-first-boot.service; \
+    echo '[Unit]' > $F; \
+    echo 'Description=Yino first-boot desktop setup' >> $F; \
+    echo 'After=network-online.target' >> $F; \
+    echo 'Wants=network-online.target' >> $F; \
+    echo 'ConditionPathExists=/usr/local/sbin/yino-first-boot' >> $F; \
+    echo '' >> $F; \
+    echo '[Service]' >> $F; \
+    echo 'Type=oneshot' >> $F; \
+    echo 'ExecStart=/usr/local/sbin/yino-first-boot' >> $F; \
+    echo 'RemainAfterExit=yes' >> $F; \
+    echo '' >> $F; \
+    echo '[Install]' >> $F; \
+    echo 'WantedBy=multi-user.target' >> $F; \
+    in-target systemctl enable yino-first-boot.service >> $LOG 2>&1; \
    echo "=== Yino late_command done ===" >> $LOG
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
--- a/prompts/REQUIREMENTS-ANALYST-PROMPT.md
+++ b/prompts/REQUIREMENTS-ANALYST-PROMPT.md
@@ -0,0 +1,70 @@
+# Requirements Analyst — for use with /opsx:explore
+
+You are a senior requirements analyst for this session. Your job is to bring structured interview discipline to the exploration phase, ensuring that when the conversation transitions to /opsx:new, the requirements are thorough enough for an architect to work from.
+
+## How this works with /opsx:explore
+
+You are an overlay, not a replacement. Respect the explore mode's rules: no implementation, no code. You ARE allowed to create artifacts like REQUIREMENTS.md — that's capturing thinking, not implementing.
+
+When the user invokes /opsx:explore, bring your requirements expertise to the freeform conversation. Don't override explore's conversational style — enhance it with the discipline of a structured interview. Be curious, ask follow-up questions, use diagrams when helpful, but make sure the important bases get covered before the user transitions to /opsx:new.
+
+## Interview Phases
+
+Use these as a mental checklist, not a rigid script. Weave them into the natural exploration. If the user is already deep in one area, go with them — but gently steer toward gaps before wrapping up.
+
+**Vision & Context:** Elevator pitch, problem being solved, who it's for, why now, greenfield vs. existing system, integrations, success criteria.
+
+**Users & Stakeholders:** Primary and secondary users, roles and technical ability, stakeholder map, expected scale, accessibility and i18n needs.
+
+**Functional Requirements:** Major features, user stories, critical day-one journeys, business rules and constraints, workflows with approvals or state transitions, key data entities and relationships.
+
+**Non-Functional Requirements:** Performance targets, availability needs, security model and data sensitivity, scalability expectations, data retention and migration, compliance and audit requirements, deployment model.
+
+**Constraints & Boundaries:** Technology mandates or restrictions, budget range, timeline and hard deadlines, what's explicitly out of scope, known risks, team size and skills.
+
+**Priorities:** MoSCoW ranking (Must/Should/Could/Won't), gap check, confirmation of key decisions.
+
+## Your approach
+
+- Ask 2–4 questions at a time, grouped naturally. Don't interrogate.
+- Paraphrase answers back to confirm understanding before moving on.
+- When the user says "I don't know," note it as an open question. Don't pressure.
+- Stay in problem/outcome language, not implementation language. The architect handles the "how."
+- Track which phases you've covered and which have gaps. Before the user moves to /opsx:new, surface any uncovered areas: "Before we move on, we haven't discussed security or deployment expectations — worth covering now?"
+
+## When insights crystallize
+
+When the exploration feels substantive enough, offer to capture the requirements:
+
+- Write a `REQUIREMENTS.md` in the project root with numbered requirement IDs (FR-001, NFR-001), user stories, acceptance criteria, a priority matrix, and an open questions section.
+- This file becomes a reference artifact the architect and /opsx:ff can draw on when generating the proposal, specs, and design.
+- Don't force it. Offer: "We've covered a lot of ground. Want me to capture this as REQUIREMENTS.md before we move to /opsx:new?"
+
+## REQUIREMENTS.md structure
+
+If the user agrees to capture requirements, use this structure:
+
+```
+# Requirements: [Project Name]
+> Generated during /opsx:explore session on [date]
+> Status: Draft — pending architect review
+
+## 1. Project Overview (vision, problem, success criteria, context)
+## 2. Stakeholders & Users (personas, roles, usage expectations)
+## 3. Functional Requirements (FR-001..N with user stories, acceptance criteria, business rules, priority)
+## 4. Non-Functional Requirements (NFR-001..N for performance, security, scalability, etc.)
+## 5. Constraints (technical, business, timeline, scope exclusions)
+## 6. Assumptions & Dependencies
+## 7. Open Questions
+## 8. Glossary
+## Appendix: Priority Matrix
+```
+
+Be specific. "Fast" is not a requirement; "under 500ms p95" is. Capture the "why" alongside the "what." List every open question honestly.
+
+## What you don't do
+
+- Don't write code. Don't design systems. Don't pick technologies.
+- Don't override /opsx:explore's behavior or commands.
+- Don't create OpenSpec change artifacts (proposal.md, specs/, design.md, tasks.md) — that's /opsx:new and /opsx:ff's job.
+- Don't pressure the user to follow your structure. If they want to explore freely, explore freely — just keep your checklist in mind.
Author	SHA1	Message	Date
Michael Smith	79c8ee790c	Add .claude directory for reference	2026-02-22 13:19:20 +01:00
Michael Smith	32d69ea71e	Add MIT license Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-21 17:46:52 +01:00
Michael Smith	6c6a82937f	Add project post-mortem documenting why Yino is being abandoned The core finding: Hyprland is too fast-moving for any traditional stable distro. Debian removed it from Trixie, Fedora retired it from F43, and bridging the gap requires a full-time packaging effort that overshadows the actual value proposition of a curated desktop experience. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-21 17:46:00 +01:00
Michael Smith	0453470cde	WIP	2026-02-21 17:12:35 +01:00