✨ Add experimental orb-operator runtime integration

.claude/commands/sdd-cleanup.md

@@ -0,0 +1,54 @@
+Clean up completed specs: update statuses, backfill PR links, archive done work, and flag stale ideas.
+
+## Step 1: Inventory specs
+
+1. List all directories under `specs/` matching `YYYY-MM-DD-*/`.
+2. Read the `README.md` frontmatter in each to get its status and pr field.
+3. Categorize into: `done` (with pr), `done` (without pr), `pr-submitted`, `in-progress`, `ready`, `idea`.
+4. Present a summary table to the user.
+
+## Step 2: Promote merged pr-submitted specs
+
+For each spec with `status: pr-submitted`:
+
+1. If it has a `pr:` field, check whether the linked PR has been merged (use `gh pr view`).
+2. If it has no `pr:` field, search for a merged PR referencing the spec slug (same approach as Step 3).
+3. If the PR is merged, update the README.md frontmatter to `status: done` (keep or add the `pr:` field).
+4. Report which specs were promoted.
+
+## Step 3: Backfill PR links on done specs
+
+For each spec with `status: done` and no `pr:` field:
+
+1. Search for a merged PR whose title or body references the spec slug (use `gh pr list --state merged --search "<slug>"`).
+2. If exactly one PR matches, add `pr: <URL>` to the frontmatter.
+3. If multiple match, present the candidates and use AskUserQuestion to let the user pick.
+4. If none match, note it in the summary (some specs predate the PR workflow — that's fine, skip them).
+
+## Step 4: Archive done specs
+
+1. Create `specs/closed/` if it doesn't exist.
+2. Move every spec directory with `status: done` into `specs/closed/`.
+3. Report how many specs were archived.
+
+## Step 5: Flag stale ideas
+
+For each spec with `status: idea`:
+
+1. Check when it was last modified (use `jj log -r 'ancestors(@)' --no-graph -T 'commit_id ++ "\n"' -n 1 -- <spec-dir>` or fall back to `git log -1 --format=%ci -- <spec-dir>`).
+2. If last touched more than 30 days ago, flag it as stale.
+3. Present any stale ideas to the user and use AskUserQuestion to ask whether to drop, keep, or refine each one.
+
+## Step 6: Commit
+
+1. Use AskUserQuestion to confirm before committing.
+2. Commit all changes with message: `chore: clean up completed specs`.
+
+## Step 7: Summary
+
+Report what was done:
+- Specs promoted from pr-submitted to done
+- PR links backfilled
+- Specs archived to specs/closed/
+- Stale ideas flagged (and any actions taken)
+- Remaining active specs (in-progress, ready, idea)

.claude/commands/sdd-ideate.md

@@ -0,0 +1,59 @@
+Brainstorm and add new work items to the backlog.
+
+## Step 1: Gather context
+
+1. Read `specs/mission.md` to understand project goals and non-goals.
+2. Read `specs/tech-stack.md` to understand the current tech stack.
+3. List all `specs/YYYY-MM-DD-*/` directories and read their README.md files to understand existing work items and their statuses.
+4. Briefly summarize the current state: what exists, what's in progress, what's done, and where the backlog currently stands.
+
+## Step 2: Surface unrefined items
+
+If there are existing work items with `status: idea`, list them and use AskUserQuestion to ask whether the user wants to refine any of them further before brainstorming new ideas. If so, use AskUserQuestion iteratively to flesh out the idea with more detail, then update its README.md accordingly (keeping `status: idea` - refinement to `ready` happens in `/sdd-plan-next-phase`).
+
+## Step 3: Brainstorm
+
+If the user provided input via $ARGUMENTS, use that as a starting theme.
+
+Use AskUserQuestion to explore:
+- Problems or gaps in the current codebase
+- User requests or feature ideas
+- Technical debt worth addressing
+- Mission goals that aren't yet addressed by any work item
+- Dependencies between potential items
+
+## Step 4: Propose candidates
+
+For each candidate work item, present:
+- **Short name** (slug-friendly)
+- **One-line description**
+- **3-6 deliverable bullets**
+- **Why it matters** (connection to mission goals)
+
+## Step 5: Iterate
+
+Use AskUserQuestion to refine:
+- Split large items into smaller ones
+- Merge overlapping items
+- Reorder by priority
+- Check for dependencies between items
+- Verify none conflict with non-goals from `specs/mission.md`
+
+## Step 6: Create work items
+
+For each finalized item, create `specs/YYYY-MM-DD-<slug>/README.md`:
+
+```markdown
+---
+status: idea
+---
+# <Title>
+
+<One or two sentence description of the idea.>
+```
+
+Use today's date for the `YYYY-MM-DD` prefix.
+
+## Step 7: Summary
+
+Summarize what was added to the backlog. Suggest running `/sdd-plan-next-phase` to refine and start the next item.

.claude/commands/sdd-implement.md

@@ -0,0 +1,50 @@
+Implement a work item from its spec.
+
+## Step 1: Identify the work item
+
+If the user provided input via $ARGUMENTS, use that to find the spec directory.
+
+Otherwise, list `specs/YYYY-MM-DD-*/` directories with `status: ready` or `status: in-progress` in their README.md frontmatter. Use AskUserQuestion to ask which one to implement.
+
+## Step 2: Read the spec
+
+Read all files in the work item's spec directory:
+- `README.md` - summary and design
+- `requirements.md` - functional requirements and acceptance criteria
+- `plan.md` - implementation plan
+- `verification.md` - verification criteria
+
+If the spec is incomplete (still an `idea` or missing files), stop and tell the user to run `/sdd-plan-next-phase` to refine it first.
+
+## Step 3: Update status
+
+Set the frontmatter `status: in-progress` in the work item's README.md.
+
+## Step 4: Implement
+
+Follow the implementation plan in `plan.md` task groups in order. For each task group:
+
+1. Start a new jj change for this task group: `jj new -m ":sparkles: <description>"` (use the appropriate emoji prefix from `specs/conventions.md`).
+2. Read `specs/mission.md` for design principles and `specs/tech-stack.md` for technical guidance.
+3. Implement the changes for this task group. Changes are automatically tracked by jj.
+4. Run `make lint && make test-unit` to verify nothing is broken.
+5. Use AskUserQuestion for any decisions not covered by the spec.
+6. When done, the current jj change already contains the committed work. Start the next task group with another `jj new -m "..."`.
+
+## Step 5: Verify
+
+After implementation is complete:
+
+1. Walk through each check in `verification.md` and confirm it passes.
+2. Walk through each acceptance criterion in `requirements.md` and confirm it is met.
+3. Run `make lint && make test-unit` one final time.
+4. Run `make verify` to ensure generated code is up-to-date.
+5. If any verification check or criterion fails, fix it in the change where the issue was introduced (navigate with `jj edit` and changes are applied automatically).
+
+## Step 6: Update governing docs
+
+Review whether anything learned during implementation should be reflected in global SDD documents (`specs/mission.md`, `specs/tech-stack.md`, `specs/conventions.md`, `CLAUDE.md`, or any other top-level specs). If updates are needed, make them in a dedicated change separate from the implementation changes.
+
+## Step 7: Suggest review
+
+Suggest the user run `/sdd-review` to review the changes for correctness and consistency before shipping.

.claude/commands/sdd-plan-next-phase.md

@@ -0,0 +1,112 @@
+Plan the next work item for the project.
+
+## Step 1: Check for clean state
+
+Ensure the working tree is on a fresh, empty change with no pending modifications. If there are pending changes, use AskUserQuestion to ask whether to proceed anyway or abort.
+
+## Step 2: Analyze the backlog
+
+1. List all directories under `specs/` matching `YYYY-MM-DD-*/`.
+2. Read the `README.md` in each to get its title, status (from frontmatter), and summary.
+3. Categorize items by status: `idea`, `ready`, `in-progress`, `pr-submitted`, `done`.
+4. Present a summary to the user showing the current state of the backlog.
+
+## Step 3: Choose what to work on
+
+If the user provided input via $ARGUMENTS, use that as a starting point.
+
+Otherwise, use AskUserQuestion to help the user decide:
+- Show `idea` and `ready` items as candidates
+- Suggest which item to tackle next based on: dependencies between items, logical ordering, and project goals from `specs/mission.md`
+- The user can also describe a new idea to create
+
+## Step 4: Create a bookmark and branch
+
+1. Create a new jj change: `jj new -m "planning: <work item name>"`
+2. Create a jj bookmark for this work: `jj bookmark create <slug>`
+
+## Step 5: Create or refine the work item
+
+### If creating a new item:
+
+1. Create `specs/YYYY-MM-DD-<slug>/README.md` with this structure:
+   ```markdown
+   ---
+   status: idea
+   ---
+   # <Title>
+
+   <One or two sentence description of the idea.>
+   ```
+2. Use AskUserQuestion to ask: should we refine this now or leave it as an idea for later?
+
+### If refining an existing `idea` item (or a new item the user wants to refine now):
+
+Use AskUserQuestion iteratively to gather requirements, implementation approach, and verification criteria. Reference `specs/tech-stack.md` for tech choices and `specs/mission.md` for design principles throughout.
+
+When refined, update the spec directory to the full structure with four files:
+
+**README.md** - high-level summary and overview:
+```markdown
+---
+status: ready
+---
+# <Title>
+
+## Summary
+<What this work item delivers and why it matters.>
+
+## Design
+<Key design decisions, type definitions, caller patterns, and how different
+implementations map to the API. This is the heart of the spec - it should
+be detailed enough that a reader understands the full shape of the work.>
+```
+
+**requirements.md** - functional requirements:
+```markdown
+# Requirements
+
+- <Requirement 1>
+- <Requirement 2>
+- ...
+
+## Acceptance Criteria
+- <Criterion 1>
+- <Criterion 2>
+- ...
+```
+
+**plan.md** - specific implementation plan:
+```markdown
+# Implementation Plan
+
+1. <Task group 1>
+2. <Task group 2>
+3. ...
+```
+
+**verification.md** - how to verify the implementation:
+```markdown
+# Verification
+
+## Implementation Correctness
+- [ ] <Verification that the implementation plan was followed correctly>
+- [ ] <Verification step 2>
+- ...
+
+## Project Conventions
+- [ ] <Check against specs/conventions.md>
+- [ ] <Check against specs/mission.md design principles>
+- [ ] <Check against specs/tech-stack.md>
+- ...
+```
+
+## Step 6: Review
+
+After writing, re-read all spec files and check:
+- Does the implementation plan align with `specs/mission.md` design principles?
+- Does it use the tech stack from `specs/tech-stack.md` correctly?
+- Are acceptance criteria testable and specific?
+- Are there any gaps or ambiguities?
+
+Fix straightforward issues directly. Use AskUserQuestion for anything with multiple valid options.

.claude/commands/sdd-quick-item.md

@@ -0,0 +1,28 @@
+Quickly capture a work item idea to the backlog.
+
+## Step 1: Get the idea
+
+If the user provided input via $ARGUMENTS, use that as the idea description.
+
+Otherwise, use AskUserQuestion to ask the user to describe the idea in one or two sentences.
+
+## Step 2: Generate a slug
+
+Derive a short, descriptive slug from the idea (lowercase, hyphens, no special characters).
+
+## Step 3: Create the work item
+
+Create `specs/YYYY-MM-DD-<slug>/README.md` using today's date:
+
+```markdown
+---
+status: idea
+---
+# <Title>
+
+<The user's idea description.>
+```
+
+## Step 4: Confirm
+
+Report the created file path. Suggest `/sdd-plan-next-phase` to refine it when ready.

.claude/commands/sdd-review.md

@@ -0,0 +1,54 @@
+Review the current branch's changes for correctness and consistency.
+
+## Step 1: Identify changes
+
+Use `jj diff -r @` and `jj log` to identify all changes on the current bookmark compared to main. Read each changed file.
+
+## Step 2: Find the work item spec
+
+Look for a `specs/YYYY-MM-DD-*/` directory with `status: in-progress`. If found, read all files in the spec directory (README.md, requirements.md, plan.md, verification.md) for context on what the changes should accomplish.
+
+## Step 3: Check correctness
+
+For each changed file:
+- Does the code follow Go conventions and the project's design principles from `specs/mission.md`?
+- Are there bugs, logic errors, or edge cases missed?
+- Are tests adequate for the changes?
+- Is the public API surface intentional and minimal?
+- Are legacy dependencies (`operator-framework/api`, `operator-framework/operator-registry`) used only where necessary?
+- Is there any code that introduces Kubernetes cluster dependencies (kubeconfig, kube client, etc.)?
+
+## Step 4: Check consistency with governing specs
+
+- Does the implementation match the requirements and acceptance criteria in `requirements.md` (if one exists)?
+- Was `plan.md` followed correctly?
+- Do all checks in `verification.md` pass?
+- Is the code consistent with `specs/tech-stack.md` (correct dependencies, project structure)?
+- Do change descriptions follow `specs/conventions.md`?
+- Does `CLAUDE.md` need updating to reflect new packages, commands, or conventions?
+
+## Step 5: Check for issues
+
+Look for:
+- Dead code or unused imports
+- Inconsistent naming or patterns across the changeset
+- Missing or incomplete test coverage
+- Overly broad public API (things that should be in `internal/`)
+
+## Step 6: Run project checks
+
+Run `make lint && make test-unit` to confirm all checks pass. If API types changed, also run `make verify-crd-compatibility`.
+
+## Step 7: Act on findings
+
+- Apply straightforward fixes directly (formatting, obvious bugs, missing error checks).
+- Use AskUserQuestion for issues with multiple valid options.
+- Summarize any remaining concerns that need the author's judgment.
+
+## Step 8: Update spec status
+
+If the review found no blocking issues and the work item's spec is still `status: in-progress`, use AskUserQuestion to ask whether to set it to `status: done`. If yes, update the README.md frontmatter.
+
+## Step 9: Suggest shipping
+
+If no blocking issues remain, suggest the user run `/sdd-ship` to finalize and publish the changes.