🌱 Add spec-driven development (SDD) framework

.claude/commands/sdd-implement.md

@@ -0,0 +1,44 @@
+Implement the current phase spec for operator-controller.
+
+## Steps
+
+1. Identify the active phase spec. Look for a `specs/*/plan.md` file on the current branch. If multiple exist or none are found, use AskUserQuestion to clarify which phase to implement.
+
+2. Read all spec files for the phase:
+   - `plan.md` — understand the goals and approach
+   - `requirements.md` — follow task groups in order
+   - `validation.md` — know the acceptance criteria upfront
+
+3. Implement task groups in the order specified in `requirements.md`. For each task group:
+   - Read the requirements carefully before writing code
+   - Follow existing patterns in the codebase (see `AGENTS.md` for conventions)
+   - Use AskUserQuestion for any decisions not covered by the spec
+
+4. After implementing each task group, verify the relevant validation criteria from `validation.md`.
+
+5. Run the project check commands after implementation:
+   ```
+   make lint && make test-unit
+   ```
+
+6. If code generation is needed (API changes, CRD changes):
+   ```
+   make generate && make manifests
+   ```
+
+7. Run format to ensure consistency:
+   ```
+   make fmt
+   ```
+
+8. Verify all generated code is up-to-date:
+   ```
+   make verify
+   ```
+
+9. If validation criteria require e2e tests and a kind cluster is available:
+   ```
+   make test-e2e
+   ```
+
+10. Use AskUserQuestion for any implementation decisions not covered by the spec, referencing `specs/mission.md` design principles and `specs/tech-stack.md` constraints.

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

@@ -0,0 +1,39 @@
+Plan the next development phase for operator-controller.
+
+## Steps
+
+1. Check for uncommitted changes with `git status`. If there are uncommitted changes, use AskUserQuestion to ask whether to stash them (`git stash`) or abort.
+
+2. Check out `main` and pull latest from upstream:
+   ```
+   git checkout main && git pull upstream main
+   ```
+
+3. Read `specs/roadmap.md` and find the next undefined phase (look for "TBD" or the last numbered phase and increment).
+
+4. Create a new branch:
+   ```
+   git checkout -b phase-{N}-{short-name}
+   ```
+
+5. Use AskUserQuestion to gather details about the upcoming phase:
+   - What is the focus area for this phase?
+   - What are the key deliverables (3-6 items)?
+   - Are there any dependencies or blockers?
+   - What validation criteria define "done" for this phase?
+
+6. Create the phase spec directory and files:
+   ```
+   specs/YYYY-MM-DD-phase-{N}-{name}/
+     plan.md          — overview, goals, approach
+     requirements.md  — detailed requirements and task groups
+     validation.md    — acceptance criteria and test plan
+   ```
+
+7. Reference `specs/mission.md` for alignment with project goals and design principles. Reference `specs/tech-stack.md` for implementation constraints (build commands, test frameworks, CI requirements).
+
+8. After writing the spec files, run a self-review:
+   - Check internal consistency across plan, requirements, and validation
+   - Verify alignment with mission goals and non-goals
+   - Ensure deliverables are concrete and testable
+   - Flag any gaps or ambiguities using AskUserQuestion

.claude/commands/sdd-review.md

@@ -0,0 +1,46 @@
+Review all changes on the current branch for consistency and quality.
+
+## Steps
+
+1. Identify the base branch and get the diff:
+   ```
+   git diff main...HEAD --name-only
+   ```
+
+2. Read all changed files. For each file, check:
+   - Does the change follow existing patterns and conventions in the codebase?
+   - Are there any security concerns (OWASP top 10, RBAC escalation, injection)?
+   - Is error handling consistent with surrounding code?
+   - Are tests included for new functionality?
+
+3. Check consistency with governing specs:
+   - Read `specs/mission.md` — does the change align with goals and design principles?
+   - Read `specs/tech-stack.md` — are the right tools and patterns being used?
+   - Read `specs/conventions.md` — do commit messages and code style match conventions?
+
+4. If a phase spec exists for this branch, check against it:
+   - Read `specs/*/validation.md` — are validation criteria met?
+   - Read `specs/*/requirements.md` — are all required task groups addressed?
+
+5. Check whether any governing documents need updating:
+   - Does `AGENTS.md` need updates for new patterns, APIs, or conventions?
+   - Do any specs need amendments based on what was learned during implementation?
+
+6. For issues with multiple valid approaches, use AskUserQuestion to present options and let the author decide.
+
+7. Apply straightforward fixes directly:
+   - Typos, formatting inconsistencies
+   - Missing error checks that follow established patterns
+   - Import ordering issues
+
+8. Verify generated files are up-to-date (CRDs, deepcopy, manifests):
+   ```
+   make verify
+   ```
+
+9. Run the check commands to verify the branch is clean:
+   ```
+   make lint && make test-unit
+   ```
+
+10. Summarize findings: what looks good, what needs attention, and any spec updates recommended.

.claude/commands/sdd-ship.md

@@ -0,0 +1,83 @@
+Verify, commit, and publish the current branch for operator-controller.
+
+## Phase 1: Verify
+
+1. Run the project check commands:
+   ```
+   make lint && make test-unit
+   ```
+
+2. Run format to ensure consistency:
+   ```
+   make fmt
+   ```
+
+3. Verify all generated code is up-to-date:
+   ```
+   make verify
+   ```
+
+4. If a phase spec exists for this branch, read `specs/*/validation.md` and verify all acceptance criteria are met.
+
+5. Check if `AGENTS.md` needs updating for any new patterns, APIs, or conventions introduced in this branch.
+
+6. If any verification step fails, fix the issue before proceeding. Use AskUserQuestion if the fix is ambiguous.
+
+## Phase 2: Commit
+
+1. Read `specs/conventions.md` for commit message and PR format requirements.
+
+2. Review all staged and unstaged changes:
+   ```
+   git status
+   git diff
+   ```
+
+3. Use AskUserQuestion to confirm the commit plan:
+   - Show a summary of what will be committed
+   - Propose a commit message following conventions (no emoji prefix on commits; that's for PR titles)
+   - Ask whether to create a single commit or multiple logical commits
+
+4. If there are post-review fixup commits that should be squashed, handle squashing into logical commits. Preserve DCO sign-off trailers (`Signed-off-by`) when squashing. Use AskUserQuestion to confirm before any interactive rebase.
+
+5. Ensure all commits have DCO sign-off (`-s` flag).
+
+## Phase 3: Publish
+
+1. Check the current branch. If on `main`, use AskUserQuestion to warn that shipping directly to main is not allowed — a feature branch is required. Abort if confirmed.
+
+2. Use AskUserQuestion to confirm before pushing. Show:
+   - The branch name
+   - Number of commits ahead of main
+   - Summary of changes
+
+3. Push the branch to the fork:
+   ```
+   git push -u origin <branch-name>
+   ```
+
+4. Determine the PR title emoji prefix based on the change type:
+   - `:warning:` for breaking changes
+   - `:sparkles:` for new features
+   - `:bug:` for bug fixes
+   - `:book:` for documentation
+   - `:seedling:` for everything else
+
+5. Create the PR against upstream using the project's template format:
+   ```
+   gh pr create --title "<emoji> <title>" --body "$(cat <<'EOF'
+   # Description
+
+   <Summary of changes and motivation>
+
+   ## Reviewer Checklist
+
+   - [ ] API Go Documentation
+   - [ ] Tests: Unit Tests (and E2E Tests, if appropriate)
+   - [ ] Comprehensive Commit Messages
+   - [ ] Links to related GitHub Issue(s)
+   EOF
+   )"
+   ```
+
+6. Report the PR URL when done.

AGENTS.md

@@ -342,4 +342,30 @@ Two manifest variants exist:
 
 ---
 
-**Last Updated:** 2025-12-10
+## Spec-Driven Development
+
+This project uses spec-driven development. Governing specs live in `specs/`:
+
+| Spec | Purpose |
+|---|---|
+| `specs/mission.md` | Goals, non-goals, design principles |
+| `specs/tech-stack.md` | Language, dependencies, build commands, project structure |
+| `specs/roadmap.md` | Historical phases and next steps |
+| `specs/conventions.md` | Commit, PR, and branch conventions |
+
+### Workflow Commands
+
+| Command | Purpose |
+|---|---|
+| `/sdd-plan-next-phase` | Plan the next development phase: create branch and spec directory |
+| `/sdd-implement` | Implement a phase spec: follow task groups, run checks |
+| `/sdd-review` | Review branch changes for consistency with specs and conventions |
+| `/sdd-ship` | Verify, commit, and publish: run checks, create PR with conventions |
+
+Primary check command: `make lint && make test-unit`
+
+API changes in `api/v1/` require: `make generate && make manifests && make crd-ref-docs`
+
+---
+
+**Last Updated:** 2026-04-22

specs/conventions.md

@@ -0,0 +1,88 @@
+# Conventions
+
+## Commit Messages
+
+Format:
+
+```
+<High-level description>
+
+<Optional detailed description explaining the why, not the what>
+
+Signed-off-by: Your Name <your@email.com>
+```
+
+Example:
+
+```
+Refactor Boxcutter controller to rely on kubernetes for resource cleanup
+
+Instead of manually tracking and deleting owned resources, rely on
+Kubernetes garbage collection via owner references. This simplifies
+the controller logic and eliminates a class of race conditions during
+concurrent reconciles.
+
+Signed-off-by: Jane Doe <jane@example.com>
+```
+
+Rules:
+- DCO sign-off (`Signed-off-by`) is required on all commits
+- Keep the subject line concise and descriptive
+- Use the body to explain motivation when non-obvious
+- Generated files must be committed alongside the source changes that require them
+
+## Pull Requests
+
+### Title Format
+
+PR titles must use an emoji prefix indicating the change type:
+
+| Emoji | Shortcode | Meaning |
+|---|---|---|
+| ⚠ | `:warning:` | Major/breaking change |
+| ✨ | `:sparkles:` | Minor/compatible change (new feature) |
+| 🐛 | `:bug:` | Patch/bug fix |
+| 📖 | `:book:` | Documentation |
+| 🌱 | `:seedling:` | Other (deps, chores, refactors) |
+
+Examples:
+- `:sparkles: Add support for deploying OCI helm charts in OLM v1`
+- `:bug: Fix race condition in Helm to Boxcutter migration during OLM upgrades`
+- `:warning: Remove support for annotation based config`
+- `:seedling: Upgrade boxcutter from v0.11.0 to v0.12.0`
+
+### Description Template
+
+```markdown
+# Description
+
+<Summary of changes and motivation>
+
+## Reviewer Checklist
+
+- [ ] API Go Documentation
+- [ ] Tests: Unit Tests (and E2E Tests, if appropriate)
+- [ ] Comprehensive Commit Messages
+- [ ] Links to related GitHub Issue(s)
+```
+
+### Requirements
+
+- Must pass all CI checks (unit-test, e2e, sanity, lint)
+- Must have both `approved` and `lgtm` labels (from repository approvers and reviewers)
+- Draft PRs: prefix with "WIP:" or use GitHub draft feature
+
+## Branch Naming
+
+- **Main branch:** `main` (default, protected)
+- **Release branches:** `release-v{MAJOR}.{MINOR}` (e.g., `release-v1.2`)
+- **Feature branches:** Created from `main`, typically in contributor forks, merged via PR
+
+## Git Remotes
+
+Fork-based development workflow:
+- **`origin`** — your personal fork (push here)
+- **`upstream`** — the project repository `operator-framework/operator-controller` (pull from here)
+
+To sync with upstream: `git pull upstream main`
+To push a branch: `git push -u origin <branch-name>`

specs/mission.md

@@ -0,0 +1,33 @@
+# Mission
+
+operator-controller is the central component of Operator Lifecycle Manager (OLM) v1. It extends Kubernetes with a declarative API for installing, upgrading, and managing cluster extensions. Together with catalogd, it provides a complete lifecycle management system for Kubernetes operators and, eventually, other workload types.
+
+## Goals
+
+1. Provide a declarative, GitOps-aligned API for installing and managing Kubernetes extensions
+2. Replace OLM v0 with a simpler, more secure, and more predictable lifecycle management system
+3. Give cluster admins minimal but sufficient controls to build desired cluster architectures
+4. Serve operator catalog content reliably via catalogd
+5. Support multi-arch container deployments (amd64, arm64, ppc64le, s390x)
+
+## Non-Goals
+
+- Replacing Helm or other generic package managers
+- Providing a UI or dashboard
+
+## Design Principles
+
+- **Align with Kubernetes conventions:** Follow Kubernetes API design patterns and user assumptions
+- **Declarative and GitOps-compatible:** All configuration expressed as Kubernetes resources
+- **Security by default:** Non-root containers, distroless base images, least-privilege RBAC
+- **Predictable upgrades:** Semantic versioning, phase-based rollouts, compatibility checks
+- **Minimal surface area:** Expose only what cluster admins need; avoid unnecessary abstractions
+
+## Development Practices
+
+- All changes go through PRs with CI checks (unit tests, e2e tests, linting, API/CRD compatibility)
+- DCO sign-off required on all commits
+- Generated files (CRDs, deepcopy, manifests) must be committed alongside source changes
+- Two-week cooldown on non-critical dependency updates
+- Go version lags upstream to give integrators time to adopt
+- Shell scripts and Makefiles must work on both macOS and Linux