From 7bfba11c312a6004081bed6a59335a5c0c1aadff Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:12:04 -0400
Subject: [PATCH 01/16] refactor: move design specs to specs/{domain}/

Move *.spec.md files from docs/internal/design/ into capability domain
directories under specs/: sessions/, control-plane/, integrations/, agents/.

Update all cross-references in devflow skill, guide files, and within
the moved specs themselves. Historical metrics data in
scripts/coderabbit-triage/ intentionally left unchanged.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills/devflow/SKILL.md                      | 12 ++++++------
 docs/internal/design/ambient-model.guide.md          |  6 +++---
 docs/internal/design/mcp-server.guide.md             |  6 +++---
 .../internal/design => specs/agents}/runner.spec.md  |  2 +-
 .../control-plane}/control-plane.spec.md             |  2 +-
 .../design => specs/integrations}/mcp-server.spec.md |  2 +-
 .../design => specs/sessions}/ambient-model.spec.md  |  2 +-
 7 files changed, 16 insertions(+), 16 deletions(-)
 rename {docs/internal/design => specs/agents}/runner.spec.md (99%)
 rename {docs/internal/design => specs/control-plane}/control-plane.spec.md (99%)
 rename {docs/internal/design => specs/integrations}/mcp-server.spec.md (99%)
 rename {docs/internal/design => specs/sessions}/ambient-model.spec.md (99%)

diff --git a/.claude/skills/devflow/SKILL.md b/.claude/skills/devflow/SKILL.md
index bef64acde..b9af7c34f 100644
--- a/.claude/skills/devflow/SKILL.md
+++ b/.claude/skills/devflow/SKILL.md
@@ -78,7 +78,7 @@ Every component has a spec file. Load the spec for the component being changed:
 
 | Component | Spec | Guide |
 |-----------|------|-------|
-| Data Model / API / CLI / RBAC | `docs/internal/design/ambient-model.spec.md` | `docs/internal/design/ambient-model.guide.md` |
+| Data Model / API / CLI / RBAC | `specs/sessions/ambient-model.spec.md` | `workflows/sessions/ambient-model.workflow.md` |
 
 ### 2b. Modify the Spec
 
@@ -87,7 +87,7 @@ Edit the spec to reflect the desired change. The spec is the source of truth —
 ### 2c. Commit Spec Change
 
 ```bash
-git add docs/internal/design/
+git add specs/
 git commit -m "spec(<component>): <description of spec change>"
 ```
 
@@ -111,7 +111,7 @@ After spec acceptance (or in parallel for human workflow), load the implementati
 
 | Component | Guide | Context |
 |-----------|-------|---------|
-| Data Model / API | `docs/internal/design/ambient-model.guide.md` | `.claude/context/api-server-development.md` |
+| Data Model / API | `workflows/sessions/ambient-model.workflow.md` | `.claude/context/api-server-development.md` |
 | SDK | (guide section in ambient-model.guide.md Wave 3) | `.claude/context/sdk-development.md` |
 | CLI | (guide section Wave 5) | `.claude/context/cli-development.md` |
 | Control Plane | (guide section Wave 4) | `.claude/context/control-plane-development.md` |
@@ -134,7 +134,7 @@ Commits are ordered deliberately:
 
 1. **Self-improvement commit (first).** Any changes to guides, skills, workflows, or this devflow skill. Group all such changes into one commit:
    ```bash
-   git add .claude/skills/ .claude/context/ docs/internal/design/*.guide.md
+   git add skills/ workflows/
    git commit -m "chore(skills): self-improvement updates from <context>"
    ```
    - Agentic workflow: this is the first commit on the branch.
@@ -354,8 +354,8 @@ But prefer fixing the lint/format issue instead.
 | `.claude/context/sdk-development.md` | SDK generation |
 | `.claude/context/control-plane-development.md` | CP fan-out, runner contract |
 | `.claude/context/frontend-development.md` | Frontend build, React Query |
-| `docs/internal/design/ambient-model.spec.md` | Data model spec (source of truth) |
-| `docs/internal/design/ambient-model.guide.md` | Implementation guide (wave-based workflow) |
+| `specs/sessions/ambient-model.spec.md` | Data model spec (source of truth) |
+| `workflows/sessions/ambient-model.workflow.md` | Implementation workflow (wave-based) |
 
 ---
 
diff --git a/docs/internal/design/ambient-model.guide.md b/docs/internal/design/ambient-model.guide.md
index b4036e50d..7af854715 100755
--- a/docs/internal/design/ambient-model.guide.md
+++ b/docs/internal/design/ambient-model.guide.md
@@ -64,7 +64,7 @@ Checklist:
 
 ### Step 2 — Read the Spec
 
-Read `docs/internal/design/ambient-model.spec.md` in full.
+Read `specs/sessions/ambient-model.spec.md` in full.
 
 Extract and hold in working memory:
 
@@ -453,8 +453,8 @@ The old Gin/K8s backend (`components/backend/`) is covered by `.claude/context/b
 
 | Artifact              | Location                                             | Owner             |
 | --------------------- | ---------------------------------------------------- | ----------------- |
-| Spec                  | `docs/internal/design/ambient-model.spec.md`         | Human / consensus |
-| This guide            | `docs/internal/design/ambient-model.guide.md`        | Updated each run  |
+| Spec                  | `specs/sessions/ambient-model.spec.md`               | Human / consensus |
+| This workflow         | `workflows/sessions/ambient-model.workflow.md`       | Updated each run  |
 | OpenAPI spec          | `components/ambient-api-server/openapi/openapi.yaml` | API wave          |
 | Generated SDK         | `components/ambient-sdk/go-sdk/`                     | SDK wave          |
 | Wave PRs              | GitHub, tagged by wave and component                 | Per wave          |
diff --git a/docs/internal/design/mcp-server.guide.md b/docs/internal/design/mcp-server.guide.md
index 501293d35..7806b48a8 100644
--- a/docs/internal/design/mcp-server.guide.md
+++ b/docs/internal/design/mcp-server.guide.md
@@ -255,7 +255,7 @@ Checklist:
 
 ### Step 2 — Read the Full Tool Spec
 
-Read `docs/internal/design/mcp-server.spec.md` in full for the complete per-tool input schemas, return shapes, and error tables.
+Read `specs/integrations/mcp-server.spec.md` in full for the complete per-tool input schemas, return shapes, and error tables.
 
 Read `docs/internal/proposals/agent-fleet-state-schema.md` for the annotation key conventions that all `patch_*_annotations` tools must honor.
 
@@ -458,8 +458,8 @@ Lessons learned:
 
 ## References
 
-- Full per-tool schemas, return shapes, and error tables: `docs/internal/design/mcp-server.spec.md`
+- Full per-tool schemas, return shapes, and error tables: `specs/integrations/mcp-server.spec.md`
 - Annotation key conventions and fleet state protocol: `docs/internal/proposals/agent-fleet-state-schema.md`
 - Agent visual language (how purple SEND/WAIT blocks map to MCP tools): `docs/internal/proposals/agent-script-visual-language.md`
 - Platform data model: `docs/internal/design/ambient-data-model.md`
-- Component pipeline and wave pattern: `docs/internal/design/ambient-model.guide.md`
+- Component pipeline and wave pattern: `workflows/sessions/ambient-model.workflow.md`
diff --git a/docs/internal/design/runner.spec.md b/specs/agents/runner.spec.md
similarity index 99%
rename from docs/internal/design/runner.spec.md
rename to specs/agents/runner.spec.md
index 385e3ab74..f35099455 100644
--- a/docs/internal/design/runner.spec.md
+++ b/specs/agents/runner.spec.md
@@ -2,7 +2,7 @@
 
 **Date:** 2026-04-05
 **Status:** Living Document — current state documented
-**Related:** `control-plane.spec.md` — CP provisioning, token endpoint, start context assembly
+**Related:** `../control-plane/control-plane.spec.md` — CP provisioning, token endpoint, start context assembly
 
 ---
 
diff --git a/docs/internal/design/control-plane.spec.md b/specs/control-plane/control-plane.spec.md
similarity index 99%
rename from docs/internal/design/control-plane.spec.md
rename to specs/control-plane/control-plane.spec.md
index b4ab61058..753fc8cb1 100755
--- a/docs/internal/design/control-plane.spec.md
+++ b/specs/control-plane/control-plane.spec.md
@@ -2,7 +2,7 @@
 
 **Date:** 2026-03-22
 **Status:** Living Document — current state documented; proposed changes marked
-**Guide:** `control-plane.guide.md` — implementation waves, gap table, build commands
+**Workflow:** `../../workflows/control-plane/control-plane.workflow.md` — implementation waves, gap table, build commands
 
 ---
 
diff --git a/docs/internal/design/mcp-server.spec.md b/specs/integrations/mcp-server.spec.md
similarity index 99%
rename from docs/internal/design/mcp-server.spec.md
rename to specs/integrations/mcp-server.spec.md
index 8645fae3a..47b7d53be 100644
--- a/docs/internal/design/mcp-server.spec.md
+++ b/specs/integrations/mcp-server.spec.md
@@ -2,7 +2,7 @@
 
 **Date:** 2026-03-22
 **Status:** Design
-**Guide:** `mcp-server.guide.md` — implementation waves, gap table, build commands, run log
+**Workflow:** `../../workflows/integrations/mcp-server.workflow.md` — implementation waves, gap table, build commands, run log
 
 ---
 
diff --git a/docs/internal/design/ambient-model.spec.md b/specs/sessions/ambient-model.spec.md
similarity index 99%
rename from docs/internal/design/ambient-model.spec.md
rename to specs/sessions/ambient-model.spec.md
index f1054ea68..b17f6a003 100755
--- a/docs/internal/design/ambient-model.spec.md
+++ b/specs/sessions/ambient-model.spec.md
@@ -3,7 +3,7 @@
 **Date:** 2026-03-20
 **Status:** Proposed — Pending Consensus
 **Last Updated:** 2026-04-28 — added `ScheduledSession` Kind; added session operational sub-resources (workspace, files, git, repos, tasks, runner protocol); added generic proxy surface for backend passthrough; updated coverage matrix: all ScheduledSession commands implemented; session sub-resources (workspace/files/git/repos/operational/runner protocol) implemented in API server; generic proxy plugin implemented
-**Guide:** `ambient-model.guide.md` — implementation waves, gap table, build commands, run log
+**Workflow:** `../../workflows/sessions/ambient-model.workflow.md` — implementation waves, gap table, build commands, run log
 **Design:** `credentials-session.md` — full Credential Kind design spec and rationale
 
 ---

From 6e01be8ba5dccea2932058c94473ae8194848603 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:14:39 -0400
Subject: [PATCH 02/16] refactor: move standards to specs/standards/{domain}/
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move conventions, patterns, and standards files into domain-organized
directories under specs/standards/:
- backend/ — conventions, error handling, K8s client patterns
- frontend/ — conventions, React Query patterns
- control-plane/ — operator conventions
- security/ — security standards
- platform/ — cross-cutting conventions (CodeRabbit-derived)

Update all references in agent definitions, amber-review skill,
CLAUDE.md, and BOOKMARKS.md.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/agents/backend-review.md                 |  6 +++---
 .claude/agents/convention-eval.md                | 14 +++++++-------
 .claude/agents/frontend-review.md                |  4 ++--
 .claude/agents/operator-review.md                |  6 +++---
 .claude/agents/security-review.md                |  2 +-
 .claude/skills/amber-review/SKILL.md             | 14 +++++++-------
 BOOKMARKS.md                                     | 16 ++++++++--------
 CLAUDE.md                                        |  8 ++++----
 docs/pr-1307-impact-analysis.md                  |  2 +-
 .../standards/backend/conventions.spec.md        |  0
 .../standards/backend/error-handling.spec.md     |  0
 .../standards/backend/k8s-client.spec.md         |  0
 .../standards/control-plane/conventions.spec.md  |  0
 .../standards/frontend/conventions.spec.md       |  0
 .../standards/frontend/react-query.spec.md       |  0
 .../standards/platform/cross-cutting.spec.md     |  0
 .../standards/security/security.spec.md          |  0
 17 files changed, 36 insertions(+), 36 deletions(-)
 rename components/backend/DEVELOPMENT.md => specs/standards/backend/conventions.spec.md (100%)
 rename components/backend/ERROR_PATTERNS.md => specs/standards/backend/error-handling.spec.md (100%)
 rename components/backend/K8S_CLIENT_PATTERNS.md => specs/standards/backend/k8s-client.spec.md (100%)
 rename components/operator/DEVELOPMENT.md => specs/standards/control-plane/conventions.spec.md (100%)
 rename components/frontend/DEVELOPMENT.md => specs/standards/frontend/conventions.spec.md (100%)
 rename components/frontend/REACT_QUERY_PATTERNS.md => specs/standards/frontend/react-query.spec.md (100%)
 rename docs/coderabbit-derived-conventions.md => specs/standards/platform/cross-cutting.spec.md (100%)
 rename docs/security-standards.md => specs/standards/security/security.spec.md (100%)

diff --git a/.claude/agents/backend-review.md b/.claude/agents/backend-review.md
index e52475c91..d77d8c101 100644
--- a/.claude/agents/backend-review.md
+++ b/.claude/agents/backend-review.md
@@ -19,9 +19,9 @@ Review backend Go code against documented conventions.
 
 Load these files before running checks:
 
-1. `components/backend/DEVELOPMENT.md`
-2. `components/backend/ERROR_PATTERNS.md`
-3. `components/backend/K8S_CLIENT_PATTERNS.md`
+1. `specs/standards/backend/conventions.spec.md`
+2. `specs/standards/backend/error-handling.spec.md`
+3. `specs/standards/backend/k8s-client.spec.md`
 
 ## Checks
 
diff --git a/.claude/agents/convention-eval.md b/.claude/agents/convention-eval.md
index 77c1af78d..8a4573b21 100644
--- a/.claude/agents/convention-eval.md
+++ b/.claude/agents/convention-eval.md
@@ -18,13 +18,13 @@ Evaluate codebase adherence to documented conventions. Produce a scored report.
 
 Load these before running checks:
 
-1. `components/backend/DEVELOPMENT.md`
-2. `components/backend/ERROR_PATTERNS.md`
-3. `components/backend/K8S_CLIENT_PATTERNS.md`
-4. `components/frontend/DEVELOPMENT.md`
-5. `components/frontend/REACT_QUERY_PATTERNS.md`
-6. `components/operator/DEVELOPMENT.md`
-7. `docs/security-standards.md`
+1. `specs/standards/backend/conventions.spec.md`
+2. `specs/standards/backend/error-handling.spec.md`
+3. `specs/standards/backend/k8s-client.spec.md`
+4. `specs/standards/frontend/conventions.spec.md`
+5. `specs/standards/frontend/react-query.spec.md`
+6. `specs/standards/control-plane/conventions.spec.md`
+7. `specs/standards/security/security.spec.md`
 
 ## Checks by Category
 
diff --git a/.claude/agents/frontend-review.md b/.claude/agents/frontend-review.md
index 988ff504f..b1b275e9a 100644
--- a/.claude/agents/frontend-review.md
+++ b/.claude/agents/frontend-review.md
@@ -19,8 +19,8 @@ Review frontend code against documented conventions.
 
 Load these files before running checks:
 
-1. `components/frontend/DEVELOPMENT.md`
-2. `components/frontend/REACT_QUERY_PATTERNS.md`
+1. `specs/standards/frontend/conventions.spec.md`
+2. `specs/standards/frontend/react-query.spec.md`
 3. `components/frontend/DESIGN_GUIDELINES.md` (if it exists)
 
 ## Checks
diff --git a/.claude/agents/operator-review.md b/.claude/agents/operator-review.md
index cbad8e4ec..4ae2e4a45 100644
--- a/.claude/agents/operator-review.md
+++ b/.claude/agents/operator-review.md
@@ -19,9 +19,9 @@ Review operator Go code against documented conventions.
 
 Load these files before running checks:
 
-1. `components/operator/DEVELOPMENT.md`
-2. `components/backend/K8S_CLIENT_PATTERNS.md`
-3. `components/backend/ERROR_PATTERNS.md`
+1. `specs/standards/control-plane/conventions.spec.md`
+2. `specs/standards/backend/k8s-client.spec.md`
+3. `specs/standards/backend/error-handling.spec.md`
 
 ## Checks
 
diff --git a/.claude/agents/security-review.md b/.claude/agents/security-review.md
index 4f5f3b64f..2c72b5139 100644
--- a/.claude/agents/security-review.md
+++ b/.claude/agents/security-review.md
@@ -19,7 +19,7 @@ Cross-cutting security review against documented security standards.
 
 Load these files before running checks:
 
-1. `docs/security-standards.md`
+1. `specs/standards/security/security.spec.md`
 
 ## Checks
 
diff --git a/.claude/skills/amber-review/SKILL.md b/.claude/skills/amber-review/SKILL.md
index fc7882740..cb5223e31 100644
--- a/.claude/skills/amber-review/SKILL.md
+++ b/.claude/skills/amber-review/SKILL.md
@@ -26,13 +26,13 @@ Consider the user input before proceeding (if not empty). The input may specify
 Read all of the following files to build your review context. Do not skip any.
 
 1. `CLAUDE.md` (master project instructions)
-2. `components/backend/DEVELOPMENT.md` (Go backend, Gin, K8s integration)
-3. `components/frontend/DEVELOPMENT.md` (NextJS, Shadcn UI, React Query)
-4. `docs/security-standards.md` (auth, RBAC, token handling, container security)
-5. `components/backend/K8S_CLIENT_PATTERNS.md` (user token vs service account)
-6. `components/backend/ERROR_PATTERNS.md` (consistent error patterns)
-7. `components/frontend/REACT_QUERY_PATTERNS.md` (data fetching patterns)
-8. `components/operator/DEVELOPMENT.md` (K8s operator, reconciliation, OwnerReferences)
+2. `specs/standards/backend/conventions.spec.md` (Go backend, Gin, K8s integration)
+3. `specs/standards/frontend/conventions.spec.md` (NextJS, Shadcn UI, React Query)
+4. `specs/standards/security/security.spec.md` (auth, RBAC, token handling, container security)
+5. `specs/standards/backend/k8s-client.spec.md` (user token vs service account)
+6. `specs/standards/backend/error-handling.spec.md` (consistent error patterns)
+7. `specs/standards/frontend/react-query.spec.md` (data fetching patterns)
+8. `specs/standards/control-plane/conventions.spec.md` (K8s operator, reconciliation, OwnerReferences)
 
 ### 2. Identify Changes to Review
 
diff --git a/BOOKMARKS.md b/BOOKMARKS.md
index ed91ee466..b5156ce70 100644
--- a/BOOKMARKS.md
+++ b/BOOKMARKS.md
@@ -43,7 +43,7 @@ Progressive disclosure for task-specific documentation and references.
 
 | Document | Purpose |
 |----------|---------|
-| [CodeRabbit-Derived Conventions](docs/coderabbit-derived-conventions.md) | Image consistency, reconciliation patterns, error propagation, namespace-scoped keys, SecurityContext — derived from 971 CodeRabbit review comments |
+| [CodeRabbit-Derived Conventions](specs/standards/platform/cross-cutting.spec.md) | Image consistency, reconciliation patterns, error propagation, namespace-scoped keys, SecurityContext — derived from 971 CodeRabbit review comments |
 
 ## Component Development Guides
 
@@ -51,13 +51,13 @@ Convention documentation for each component. Loaded by review agents on demand.
 
 | Guide | Scope |
 |-------|-------|
-| [Backend Development](components/backend/DEVELOPMENT.md) | Go patterns, K8s integration, handler conventions, user-scoped clients |
-| [Backend Error Patterns](components/backend/ERROR_PATTERNS.md) | Consistent error patterns across backend and operator |
-| [Backend K8s Client Patterns](components/backend/K8S_CLIENT_PATTERNS.md) | User token vs. service account — critical for RBAC compliance |
-| [Frontend Development](components/frontend/DEVELOPMENT.md) | NextJS patterns, Shadcn, React Query, component guidelines |
-| [Frontend React Query Patterns](components/frontend/REACT_QUERY_PATTERNS.md) | Data fetching hooks, mutations, cache invalidation |
-| [Operator Development](components/operator/DEVELOPMENT.md) | OwnerReferences, reconciliation patterns, SecurityContext, resource limits |
-| [Security Standards](docs/security-standards.md) | Auth flows, RBAC, token handling, container security |
+| [Backend Conventions](specs/standards/backend/conventions.spec.md) | Go patterns, K8s integration, handler conventions, user-scoped clients |
+| [Backend Error Handling](specs/standards/backend/error-handling.spec.md) | Consistent error patterns across backend and operator |
+| [Backend K8s Client](specs/standards/backend/k8s-client.spec.md) | User token vs. service account — critical for RBAC compliance |
+| [Frontend Conventions](specs/standards/frontend/conventions.spec.md) | NextJS patterns, Shadcn, React Query, component guidelines |
+| [Frontend React Query](specs/standards/frontend/react-query.spec.md) | Data fetching hooks, mutations, cache invalidation |
+| [Operator Conventions](specs/standards/control-plane/conventions.spec.md) | OwnerReferences, reconciliation patterns, SecurityContext, resource limits |
+| [Security Standards](specs/standards/security/security.spec.md) | Auth flows, RBAC, token handling, container security |
 
 ## Component Guides
 
diff --git a/CLAUDE.md b/CLAUDE.md
index d1672f5f1..120570576 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -123,10 +123,10 @@ component DEVELOPMENT.md files (see [BOOKMARKS.md](BOOKMARKS.md) > Component Dev
 - **Restricted SecurityContext on all containers**: `runAsNonRoot`, drop `ALL` capabilities, `readOnlyRootFilesystem`
 
 Component-specific conventions:
-- Backend: [DEVELOPMENT.md](components/backend/DEVELOPMENT.md), [ERROR_PATTERNS.md](components/backend/ERROR_PATTERNS.md), [K8S_CLIENT_PATTERNS.md](components/backend/K8S_CLIENT_PATTERNS.md)
-- Frontend: [DEVELOPMENT.md](components/frontend/DEVELOPMENT.md), [REACT_QUERY_PATTERNS.md](components/frontend/REACT_QUERY_PATTERNS.md)
-- Operator: [DEVELOPMENT.md](components/operator/DEVELOPMENT.md)
-- Security: [security-standards.md](docs/security-standards.md)
+- Backend: [conventions](specs/standards/backend/conventions.spec.md), [error handling](specs/standards/backend/error-handling.spec.md), [K8s client](specs/standards/backend/k8s-client.spec.md)
+- Frontend: [conventions](specs/standards/frontend/conventions.spec.md), [React Query](specs/standards/frontend/react-query.spec.md)
+- Operator: [conventions](specs/standards/control-plane/conventions.spec.md)
+- Security: [security standards](specs/standards/security/security.spec.md)
 
 ## Pre-commit Hooks
 
diff --git a/docs/pr-1307-impact-analysis.md b/docs/pr-1307-impact-analysis.md
index 79388f59d..8b41856e6 100644
--- a/docs/pr-1307-impact-analysis.md
+++ b/docs/pr-1307-impact-analysis.md
@@ -12,7 +12,7 @@ This document demonstrates the impact of PR #1307 (Claude Code automation overha
 | **backend/ERROR_PATTERNS.md** | HTTP status code conventions (404 vs 400 vs 502) | After the signature fix, `ConnectCodeRabbit` now returns 502 on network errors vs 400 on invalid keys — a distinction this doc requires. |
 | **frontend/DEVELOPMENT.md** | Zero-tolerance rules (no `any`, Shadcn only, React Query for all data) | Connection card uses only `Card`, `Button`, `Input`, `Label` from `@/components/ui/*`. API client is pure functions in `services/api/`, hooks in `services/queries/`. No manual `fetch()` in components. |
 | **frontend/REACT_QUERY_PATTERNS.md** | Query/mutation hook structure, cache invalidation | `useConnectCodeRabbit` and `useDisconnectCodeRabbit` invalidate both `['coderabbit', 'status']` and `['integrations', 'status']` on success — the dual-invalidation pattern from this doc. |
-| **docs/security-standards.md** | Token handling, RBAC enforcement, input validation | API keys never logged (only `len(token)` pattern initially, then simplified). `validateCodeRabbitAPIKeyImpl` uses `networkError()` to strip URLs from error messages — preventing credential leakage. |
+| **specs/standards/security/security.spec.md** | Token handling, RBAC enforcement, input validation | API keys never logged (only `len(token)` pattern initially, then simplified). `validateCodeRabbitAPIKeyImpl` uses `networkError()` to strip URLs from error messages — preventing credential leakage. |
 | **settings.json hooks** | Real-time enforcement during edits (Shadcn reminder, React Query reminder, K8s client reminder, no-panic reminder) | These hooks fired during subagent implementation, keeping each subagent on-pattern even without full codebase context. The Shadcn hook ensures no raw `<button>` or `<input>` elements snuck in. |
 | **Review agents** (backend, frontend, security) | Structured review checklists with severity levels | The `/simplify` code quality review used these severity categories (Blocker/Critical/Major/Minor). The critical finding (validator signature) maps directly to backend-review check B2 and the consistent-signature expectation. |
 | **CLAUDE.md convention authority section** | Establishes hierarchy: CLAUDE.md > Constitution > everything else | Ensured the integration followed CLAUDE.md conventions (no `any`, no `panic`, OwnerReferences) rather than inventing its own patterns. |
diff --git a/components/backend/DEVELOPMENT.md b/specs/standards/backend/conventions.spec.md
similarity index 100%
rename from components/backend/DEVELOPMENT.md
rename to specs/standards/backend/conventions.spec.md
diff --git a/components/backend/ERROR_PATTERNS.md b/specs/standards/backend/error-handling.spec.md
similarity index 100%
rename from components/backend/ERROR_PATTERNS.md
rename to specs/standards/backend/error-handling.spec.md
diff --git a/components/backend/K8S_CLIENT_PATTERNS.md b/specs/standards/backend/k8s-client.spec.md
similarity index 100%
rename from components/backend/K8S_CLIENT_PATTERNS.md
rename to specs/standards/backend/k8s-client.spec.md
diff --git a/components/operator/DEVELOPMENT.md b/specs/standards/control-plane/conventions.spec.md
similarity index 100%
rename from components/operator/DEVELOPMENT.md
rename to specs/standards/control-plane/conventions.spec.md
diff --git a/components/frontend/DEVELOPMENT.md b/specs/standards/frontend/conventions.spec.md
similarity index 100%
rename from components/frontend/DEVELOPMENT.md
rename to specs/standards/frontend/conventions.spec.md
diff --git a/components/frontend/REACT_QUERY_PATTERNS.md b/specs/standards/frontend/react-query.spec.md
similarity index 100%
rename from components/frontend/REACT_QUERY_PATTERNS.md
rename to specs/standards/frontend/react-query.spec.md
diff --git a/docs/coderabbit-derived-conventions.md b/specs/standards/platform/cross-cutting.spec.md
similarity index 100%
rename from docs/coderabbit-derived-conventions.md
rename to specs/standards/platform/cross-cutting.spec.md
diff --git a/docs/security-standards.md b/specs/standards/security/security.spec.md
similarity index 100%
rename from docs/security-standards.md
rename to specs/standards/security/security.spec.md

From 23120d33a0718095029e1322ab84b810587aa762 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:16:00 -0400
Subject: [PATCH 03/16] refactor: move guide files to workflows/{domain}/

Rename *.guide.md to *.workflow.md and move from docs/internal/design/
to workflows/{domain}/:
- sessions/ambient-model.workflow.md
- control-plane/control-plane.workflow.md
- integrations/mcp-server.workflow.md

Fix pre-existing broken reference to ambient-data-model.md. Update
cross-references in devflow skill, manifests README, and design README.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills/devflow/SKILL.md                        |  6 +++---
 components/manifests/overlays/mpp-openshift/README.md  |  2 +-
 docs/internal/design/README.md                         | 10 +++++-----
 .../control-plane/control-plane.workflow.md            |  0
 .../integrations/mcp-server.workflow.md                |  2 +-
 .../sessions/ambient-model.workflow.md                 |  0
 6 files changed, 10 insertions(+), 10 deletions(-)
 rename docs/internal/design/control-plane.guide.md => workflows/control-plane/control-plane.workflow.md (100%)
 rename docs/internal/design/mcp-server.guide.md => workflows/integrations/mcp-server.workflow.md (99%)
 rename docs/internal/design/ambient-model.guide.md => workflows/sessions/ambient-model.workflow.md (100%)

diff --git a/.claude/skills/devflow/SKILL.md b/.claude/skills/devflow/SKILL.md
index b9af7c34f..197c7ad81 100644
--- a/.claude/skills/devflow/SKILL.md
+++ b/.claude/skills/devflow/SKILL.md
@@ -112,7 +112,7 @@ After spec acceptance (or in parallel for human workflow), load the implementati
 | Component | Guide | Context |
 |-----------|-------|---------|
 | Data Model / API | `workflows/sessions/ambient-model.workflow.md` | `.claude/context/api-server-development.md` |
-| SDK | (guide section in ambient-model.guide.md Wave 3) | `.claude/context/sdk-development.md` |
+| SDK | (workflow section in ambient-model.workflow.md Wave 3) | `.claude/context/sdk-development.md` |
 | CLI | (guide section Wave 5) | `.claude/context/cli-development.md` |
 | Control Plane | (guide section Wave 4) | `.claude/context/control-plane-development.md` |
 | Operator | (guide section Wave 5) | `.claude/context/operator-development.md` |
@@ -368,7 +368,7 @@ Record every correction here with a date stamp. This section grows over time.
 - Established devflow skill from user requirements.
 - Seeded Known Pitfalls from existing context files and guide lessons learned.
 - Documented TESTCONTAINERS_RYUK_DISABLED requirement (discovered in api-server-development.md).
-- Documented podman `--no-cache` and `ctr import` workarounds (discovered in ambient-model.guide.md).
-- Documented gRPC port 19000 workaround (discovered in ambient-model.guide.md).
+- Documented podman `--no-cache` and `ctr import` workarounds (discovered in ambient-model.workflow.md).
+- Documented gRPC port 19000 workaround (discovered in ambient-model.workflow.md).
 - GitOps deployment step marked as TBD — will be formalized as the workflow runs.
 - E2E test suite marked as TBD.
diff --git a/components/manifests/overlays/mpp-openshift/README.md b/components/manifests/overlays/mpp-openshift/README.md
index 08eb914bc..5698f7f51 100644
--- a/components/manifests/overlays/mpp-openshift/README.md
+++ b/components/manifests/overlays/mpp-openshift/README.md
@@ -78,7 +78,7 @@ The api-server must know the static token so it can recognise the runner as a se
 # The token value must match what was set in Step B
 ```
 
-> **Note:** Step C is currently pending implementation — see the open gap `WatchSessionMessages PERMISSION_DENIED` in `docs/internal/design/control-plane.guide.md`.
+> **Note:** Step C is currently pending implementation — see the open gap `WatchSessionMessages PERMISSION_DENIED` in `workflows/control-plane/control-plane.workflow.md`.
 
 ## Files in This Overlay
 
diff --git a/docs/internal/design/README.md b/docs/internal/design/README.md
index 04afb849a..9c6da9c60 100644
--- a/docs/internal/design/README.md
+++ b/docs/internal/design/README.md
@@ -65,9 +65,9 @@ Guides are **living documents**. Every time the workflow runs and something is d
 
 | Guide | Paired spec |
 |---|---|
-| `ambient-model.guide.md` | `ambient-model.spec.md` |
-| `control-plane.guide.md` | `control-plane.spec.md` |
-| `mcp-server.guide.md` | `mcp-server.spec.md` |
+| `workflows/sessions/ambient-model.workflow.md` | `specs/sessions/ambient-model.spec.md` |
+| `workflows/control-plane/control-plane.workflow.md` | `specs/control-plane/control-plane.spec.md` |
+| `workflows/integrations/mcp-server.workflow.md` | `specs/integrations/mcp-server.spec.md` |
 
 ### Component context files (`.claude/context/*-development.md`)
 
@@ -133,6 +133,6 @@ Every time the loop stops because something was wrong, the documents get better.
 ## Reading Order for a New Contributor
 
 1. This README — the why
-2. `ambient-model.spec.md` — what the platform is
-3. `ambient-model.guide.md` — how changes are made
+2. `specs/sessions/ambient-model.spec.md` — what the platform is
+3. `workflows/sessions/ambient-model.workflow.md` — how changes are made
 4. The context file for the component you are working on
diff --git a/docs/internal/design/control-plane.guide.md b/workflows/control-plane/control-plane.workflow.md
similarity index 100%
rename from docs/internal/design/control-plane.guide.md
rename to workflows/control-plane/control-plane.workflow.md
diff --git a/docs/internal/design/mcp-server.guide.md b/workflows/integrations/mcp-server.workflow.md
similarity index 99%
rename from docs/internal/design/mcp-server.guide.md
rename to workflows/integrations/mcp-server.workflow.md
index 7806b48a8..2bb747b0c 100644
--- a/docs/internal/design/mcp-server.guide.md
+++ b/workflows/integrations/mcp-server.workflow.md
@@ -461,5 +461,5 @@ Lessons learned:
 - Full per-tool schemas, return shapes, and error tables: `specs/integrations/mcp-server.spec.md`
 - Annotation key conventions and fleet state protocol: `docs/internal/proposals/agent-fleet-state-schema.md`
 - Agent visual language (how purple SEND/WAIT blocks map to MCP tools): `docs/internal/proposals/agent-script-visual-language.md`
-- Platform data model: `docs/internal/design/ambient-data-model.md`
+- Platform data model: `specs/sessions/ambient-model.spec.md`
 - Component pipeline and wave pattern: `workflows/sessions/ambient-model.workflow.md`
diff --git a/docs/internal/design/ambient-model.guide.md b/workflows/sessions/ambient-model.workflow.md
similarity index 100%
rename from docs/internal/design/ambient-model.guide.md
rename to workflows/sessions/ambient-model.workflow.md

From b341bdc61624fa0f272b871e78757f3111759444 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:19:46 -0400
Subject: [PATCH 04/16] refactor: move skills to top-level skills/ with domain
 organization
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move .claude/skills/ to top-level skills/ directory with capability
domain organization:
- Cross-cutting skills flat at root: devflow, align, amber-review,
  scaffold, memory, pr-fixer
- Domain-nested: sessions/, control-plane/, frontend/, integrations/

Create .claude/skills symlink → ../skills/ for Claude Code discovery.
Update convention-guard.sh to match both paths. Fix pre-existing
broken .claude/context/ references in devflow skill.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills                                |  1 +
 .../developer/local-development/openshift.md  |  6 ++--
 .../proposals/alpha-to-main-migration.md      |  2 +-
 scripts/claude-hooks/convention-guard.sh      |  2 +-
 {.claude/skills => skills}/align/SKILL.md     |  0
 .../skills => skills}/align/evals/evals.json  |  0
 .../skills => skills}/amber-review/SKILL.md   |  0
 .../amber-review/evals/evals.json             |  0
 .../control-plane}/ambient-pr-test/SKILL.md   |  2 +-
 .../control-plane}/ambient/SKILL.md           |  0
 .../control-plane}/dev-cluster/README.md      |  0
 .../control-plane}/dev-cluster/SKILL.md       |  0
 .../dev-cluster/evals/evals.json              |  0
 {.claude/skills => skills}/devflow/SKILL.md   | 34 +++++++++----------
 .../frontend}/cypress-demo/SKILL.md           |  0
 .../frontend}/cypress-demo/evals/evals.json   |  0
 .../integrations}/grpc-dev/SKILL.md           |  0
 .../integrations}/unleash-flag/SKILL.md       |  0
 .../unleash-flag/evals/evals.json             |  0
 {.claude/skills => skills}/memory/SKILL.md    |  0
 .../skills => skills}/memory/evals/evals.json |  0
 {.claude/skills => skills}/pr-fixer/SKILL.md  |  0
 .../pr-fixer/evals/evals.json                 |  0
 {.claude/skills => skills}/scaffold/SKILL.md  |  0
 .../scaffold/evals/evals.json                 |  0
 .../sessions}/ambient-api-server/SKILL.md     |  0
 .../control-plane/control-plane.workflow.md   |  2 +-
 27 files changed, 25 insertions(+), 24 deletions(-)
 create mode 120000 .claude/skills
 rename {.claude/skills => skills}/align/SKILL.md (100%)
 rename {.claude/skills => skills}/align/evals/evals.json (100%)
 rename {.claude/skills => skills}/amber-review/SKILL.md (100%)
 rename {.claude/skills => skills}/amber-review/evals/evals.json (100%)
 rename {.claude/skills => skills/control-plane}/ambient-pr-test/SKILL.md (99%)
 rename {.claude/skills => skills/control-plane}/ambient/SKILL.md (100%)
 rename {.claude/skills => skills/control-plane}/dev-cluster/README.md (100%)
 rename {.claude/skills => skills/control-plane}/dev-cluster/SKILL.md (100%)
 rename {.claude/skills => skills/control-plane}/dev-cluster/evals/evals.json (100%)
 rename {.claude/skills => skills}/devflow/SKILL.md (89%)
 rename {.claude/skills => skills/frontend}/cypress-demo/SKILL.md (100%)
 rename {.claude/skills => skills/frontend}/cypress-demo/evals/evals.json (100%)
 rename {.claude/skills => skills/integrations}/grpc-dev/SKILL.md (100%)
 rename {.claude/skills => skills/integrations}/unleash-flag/SKILL.md (100%)
 rename {.claude/skills => skills/integrations}/unleash-flag/evals/evals.json (100%)
 rename {.claude/skills => skills}/memory/SKILL.md (100%)
 rename {.claude/skills => skills}/memory/evals/evals.json (100%)
 rename {.claude/skills => skills}/pr-fixer/SKILL.md (100%)
 rename {.claude/skills => skills}/pr-fixer/evals/evals.json (100%)
 rename {.claude/skills => skills}/scaffold/SKILL.md (100%)
 rename {.claude/skills => skills}/scaffold/evals/evals.json (100%)
 rename {.claude/skills => skills/sessions}/ambient-api-server/SKILL.md (100%)

diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 000000000..42c5394a1
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+../skills
\ No newline at end of file
diff --git a/docs/internal/developer/local-development/openshift.md b/docs/internal/developer/local-development/openshift.md
index 4834c8421..d24627823 100644
--- a/docs/internal/developer/local-development/openshift.md
+++ b/docs/internal/developer/local-development/openshift.md
@@ -2,9 +2,9 @@
 
 This guide covers deploying Ambient Code on an OpenShift cluster using the **OpenShift internal image registry**. This is useful when iterating on local builds against a dev cluster without pushing to quay.io.
 
-> **Standard deployment (quay.io images):** See the [Ambient installer skill](../../../../.claude/skills/ambient/SKILL.md) — it covers secrets, kustomize deploy, rollout verification, and troubleshooting for any OpenShift namespace.
+> **Standard deployment (quay.io images):** See the [Ambient installer skill](../../../../skills/control-plane/ambient/SKILL.md) — it covers secrets, kustomize deploy, rollout verification, and troubleshooting for any OpenShift namespace.
 
-> **PR test instances:** See the [ambient-pr-test skill](../../../../.claude/skills/ambient-pr-test/SKILL.md).
+> **PR test instances:** See the [ambient-pr-test skill](../../../../skills/control-plane/ambient-pr-test/SKILL.md).
 
 ---
 
@@ -109,4 +109,4 @@ Without this, runner pods fail with `ErrImagePull` / `authentication required`.
 
 ## Next Steps
 
-Once deployed, follow the verification and access steps in the [ambient skill](../../../../.claude/skills/ambient/SKILL.md#step-6-verify-installation).
+Once deployed, follow the verification and access steps in the [ambient skill](../../../../skills/control-plane/ambient/SKILL.md#step-6-verify-installation).
diff --git a/docs/internal/proposals/alpha-to-main-migration.md b/docs/internal/proposals/alpha-to-main-migration.md
index 48a894c4b..48c4766a3 100644
--- a/docs/internal/proposals/alpha-to-main-migration.md
+++ b/docs/internal/proposals/alpha-to-main-migration.md
@@ -40,7 +40,7 @@ removes this file.
 
 - [x] Analyze alpha→main delta and component dependencies
 - [x] Write migration plan (`docs/internal/proposals/alpha-to-main-migration.md`)
-- [x] Fix alpha→main branch references in `.claude/skills/devflow/SKILL.md`
+- [x] Fix alpha→main branch references in `skills/devflow/SKILL.md`
 - [x] Merge to main
 
 ### PR 2 — ambient-api-server: OpenAPI Specs, Generated Client, New Kinds ✅ Merged
diff --git a/scripts/claude-hooks/convention-guard.sh b/scripts/claude-hooks/convention-guard.sh
index 358cef973..0bd9ea77c 100755
--- a/scripts/claude-hooks/convention-guard.sh
+++ b/scripts/claude-hooks/convention-guard.sh
@@ -72,7 +72,7 @@ if [[ "$FILE_PATH" == */components/backend/*.go || "$FILE_PATH" == */components/
 fi
 
 # --- Skills: remind about standards ---
-if [[ "$FILE_PATH" == */.claude/skills/* ]]; then
+if [[ "$FILE_PATH" == */.claude/skills/* || "$FILE_PATH" == */skills/* ]]; then
   warn "Follow the Anthropic skill-creator standard. Required: pushy description, under 500 lines, explanation over rigidity, evals in evals/evals.json."
 fi
 
diff --git a/.claude/skills/align/SKILL.md b/skills/align/SKILL.md
similarity index 100%
rename from .claude/skills/align/SKILL.md
rename to skills/align/SKILL.md
diff --git a/.claude/skills/align/evals/evals.json b/skills/align/evals/evals.json
similarity index 100%
rename from .claude/skills/align/evals/evals.json
rename to skills/align/evals/evals.json
diff --git a/.claude/skills/amber-review/SKILL.md b/skills/amber-review/SKILL.md
similarity index 100%
rename from .claude/skills/amber-review/SKILL.md
rename to skills/amber-review/SKILL.md
diff --git a/.claude/skills/amber-review/evals/evals.json b/skills/amber-review/evals/evals.json
similarity index 100%
rename from .claude/skills/amber-review/evals/evals.json
rename to skills/amber-review/evals/evals.json
diff --git a/.claude/skills/ambient-pr-test/SKILL.md b/skills/control-plane/ambient-pr-test/SKILL.md
similarity index 99%
rename from .claude/skills/ambient-pr-test/SKILL.md
rename to skills/control-plane/ambient-pr-test/SKILL.md
index d44a8408a..7716361e2 100644
--- a/.claude/skills/ambient-pr-test/SKILL.md
+++ b/skills/control-plane/ambient-pr-test/SKILL.md
@@ -12,7 +12,7 @@ You are an expert in running ephemeral PR validation environments on the Ambient
 
 **Invoke this skill with a PR URL:**
 ```
-with .claude/skills/ambient-pr-test  https://github.com/ambient-code/platform/pull/1005
+with skills/control-plane/ambient-pr-test  https://github.com/ambient-code/platform/pull/1005
 ```
 
 Optional modifiers the user may specify:
diff --git a/.claude/skills/ambient/SKILL.md b/skills/control-plane/ambient/SKILL.md
similarity index 100%
rename from .claude/skills/ambient/SKILL.md
rename to skills/control-plane/ambient/SKILL.md
diff --git a/.claude/skills/dev-cluster/README.md b/skills/control-plane/dev-cluster/README.md
similarity index 100%
rename from .claude/skills/dev-cluster/README.md
rename to skills/control-plane/dev-cluster/README.md
diff --git a/.claude/skills/dev-cluster/SKILL.md b/skills/control-plane/dev-cluster/SKILL.md
similarity index 100%
rename from .claude/skills/dev-cluster/SKILL.md
rename to skills/control-plane/dev-cluster/SKILL.md
diff --git a/.claude/skills/dev-cluster/evals/evals.json b/skills/control-plane/dev-cluster/evals/evals.json
similarity index 100%
rename from .claude/skills/dev-cluster/evals/evals.json
rename to skills/control-plane/dev-cluster/evals/evals.json
diff --git a/.claude/skills/devflow/SKILL.md b/skills/devflow/SKILL.md
similarity index 89%
rename from .claude/skills/devflow/SKILL.md
rename to skills/devflow/SKILL.md
index 197c7ad81..f2089d1f0 100644
--- a/.claude/skills/devflow/SKILL.md
+++ b/skills/devflow/SKILL.md
@@ -23,7 +23,7 @@ You are executing the Ambient Code Platform development workflow. This skill is
 
 **Remind the human every 10 turns to re-read this skill.** Context compaction can lose workflow state. At turns 10, 20, 30, etc., say:
 
-> "Reminder: we are on turn N. Re-reading `.claude/skills/devflow/SKILL.md` to refresh workflow state."
+> "Reminder: we are on turn N. Re-reading `skills/devflow/SKILL.md` to refresh workflow state."
 
 Then re-read this file before continuing.
 
@@ -111,13 +111,13 @@ After spec acceptance (or in parallel for human workflow), load the implementati
 
 | Component | Guide | Context |
 |-----------|-------|---------|
-| Data Model / API | `workflows/sessions/ambient-model.workflow.md` | `.claude/context/api-server-development.md` |
-| SDK | (workflow section in ambient-model.workflow.md Wave 3) | `.claude/context/sdk-development.md` |
-| CLI | (guide section Wave 5) | `.claude/context/cli-development.md` |
-| Control Plane | (guide section Wave 4) | `.claude/context/control-plane-development.md` |
-| Operator | (guide section Wave 5) | `.claude/context/operator-development.md` |
-| Frontend | (guide section Wave 6) | `.claude/context/frontend-development.md` |
-| Backend (V1) | — | `.claude/context/backend-development.md` |
+| Data Model / API | `workflows/sessions/ambient-model.workflow.md` | `specs/standards/backend/conventions.spec.md` |
+| SDK | (workflow section in ambient-model.workflow.md Wave 3) | `specs/standards/backend/conventions.spec.md` |
+| CLI | (guide section Wave 5) | `specs/standards/backend/conventions.spec.md` |
+| Control Plane | (guide section Wave 4) | `specs/standards/control-plane/conventions.spec.md` |
+| Operator | (guide section Wave 5) | `specs/standards/control-plane/conventions.spec.md` |
+| Frontend | (guide section Wave 6) | `specs/standards/frontend/conventions.spec.md` |
+| Backend (V1) | — | `specs/standards/backend/conventions.spec.md` |
 
 ### 3b. Create Implementation Branch
 
@@ -345,15 +345,15 @@ But prefer fixing the lint/format issue instead.
 
 | Skill/Context | When to use |
 |---------------|-------------|
-| `.claude/skills/ambient-api-server/SKILL.md` | Working in `components/ambient-api-server/` |
-| `.claude/skills/dev-cluster/SKILL.md` | Managing kind clusters for testing |
-| `.claude/skills/grpc-dev/SKILL.md` | gRPC streaming, AG-UI events |
-| `.claude/skills/ambient-pr-test/SKILL.md` | PR validation on MPP dev cluster |
-| `.claude/context/api-server-development.md` | API server plugin architecture, OpenAPI, testing |
-| `.claude/context/cli-development.md` | CLI command patterns |
-| `.claude/context/sdk-development.md` | SDK generation |
-| `.claude/context/control-plane-development.md` | CP fan-out, runner contract |
-| `.claude/context/frontend-development.md` | Frontend build, React Query |
+| `skills/sessions/ambient-api-server/SKILL.md` | Working in `components/ambient-api-server/` |
+| `skills/control-plane/dev-cluster/SKILL.md` | Managing kind clusters for testing |
+| `skills/integrations/grpc-dev/SKILL.md` | gRPC streaming, AG-UI events |
+| `skills/control-plane/ambient-pr-test/SKILL.md` | PR validation on MPP dev cluster |
+| `specs/standards/backend/conventions.spec.md` | API server plugin architecture, OpenAPI, testing |
+| `specs/standards/backend/conventions.spec.md` | CLI command patterns |
+| `specs/standards/backend/conventions.spec.md` | SDK generation |
+| `specs/standards/control-plane/conventions.spec.md` | CP fan-out, runner contract |
+| `specs/standards/frontend/conventions.spec.md` | Frontend build, React Query |
 | `specs/sessions/ambient-model.spec.md` | Data model spec (source of truth) |
 | `workflows/sessions/ambient-model.workflow.md` | Implementation workflow (wave-based) |
 
diff --git a/.claude/skills/cypress-demo/SKILL.md b/skills/frontend/cypress-demo/SKILL.md
similarity index 100%
rename from .claude/skills/cypress-demo/SKILL.md
rename to skills/frontend/cypress-demo/SKILL.md
diff --git a/.claude/skills/cypress-demo/evals/evals.json b/skills/frontend/cypress-demo/evals/evals.json
similarity index 100%
rename from .claude/skills/cypress-demo/evals/evals.json
rename to skills/frontend/cypress-demo/evals/evals.json
diff --git a/.claude/skills/grpc-dev/SKILL.md b/skills/integrations/grpc-dev/SKILL.md
similarity index 100%
rename from .claude/skills/grpc-dev/SKILL.md
rename to skills/integrations/grpc-dev/SKILL.md
diff --git a/.claude/skills/unleash-flag/SKILL.md b/skills/integrations/unleash-flag/SKILL.md
similarity index 100%
rename from .claude/skills/unleash-flag/SKILL.md
rename to skills/integrations/unleash-flag/SKILL.md
diff --git a/.claude/skills/unleash-flag/evals/evals.json b/skills/integrations/unleash-flag/evals/evals.json
similarity index 100%
rename from .claude/skills/unleash-flag/evals/evals.json
rename to skills/integrations/unleash-flag/evals/evals.json
diff --git a/.claude/skills/memory/SKILL.md b/skills/memory/SKILL.md
similarity index 100%
rename from .claude/skills/memory/SKILL.md
rename to skills/memory/SKILL.md
diff --git a/.claude/skills/memory/evals/evals.json b/skills/memory/evals/evals.json
similarity index 100%
rename from .claude/skills/memory/evals/evals.json
rename to skills/memory/evals/evals.json
diff --git a/.claude/skills/pr-fixer/SKILL.md b/skills/pr-fixer/SKILL.md
similarity index 100%
rename from .claude/skills/pr-fixer/SKILL.md
rename to skills/pr-fixer/SKILL.md
diff --git a/.claude/skills/pr-fixer/evals/evals.json b/skills/pr-fixer/evals/evals.json
similarity index 100%
rename from .claude/skills/pr-fixer/evals/evals.json
rename to skills/pr-fixer/evals/evals.json
diff --git a/.claude/skills/scaffold/SKILL.md b/skills/scaffold/SKILL.md
similarity index 100%
rename from .claude/skills/scaffold/SKILL.md
rename to skills/scaffold/SKILL.md
diff --git a/.claude/skills/scaffold/evals/evals.json b/skills/scaffold/evals/evals.json
similarity index 100%
rename from .claude/skills/scaffold/evals/evals.json
rename to skills/scaffold/evals/evals.json
diff --git a/.claude/skills/ambient-api-server/SKILL.md b/skills/sessions/ambient-api-server/SKILL.md
similarity index 100%
rename from .claude/skills/ambient-api-server/SKILL.md
rename to skills/sessions/ambient-api-server/SKILL.md
diff --git a/workflows/control-plane/control-plane.workflow.md b/workflows/control-plane/control-plane.workflow.md
index 61b0fe58a..69cb88fad 100755
--- a/workflows/control-plane/control-plane.workflow.md
+++ b/workflows/control-plane/control-plane.workflow.md
@@ -845,7 +845,7 @@ GET /sessions/{id}/events (proxy)            api-server   open
 acpctl session events <id>                   CLI          open
 ```
 
-**Next:** Investigate `WatchSessionMessages` authorization in api-server — check `@.claude/skills/ambient-api-server/` or `components/ambient-api-server/plugins/sessions/` for watch auth logic. The push succeeds with the same token so the issue is specific to the watch handler's authorization check.
+**Next:** Investigate `WatchSessionMessages` authorization in api-server — check `@skills/sessions/ambient-api-server/` or `components/ambient-api-server/plugins/sessions/` for watch auth logic. The push succeeds with the same token so the issue is specific to the watch handler's authorization check.
 
 ---
 

From 561e03c24a0535f972d314372d63feab9ced3778 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:20:01 -0400
Subject: [PATCH 05/16] chore: remove ephemeral spec artifacts

Delete plan.md, tasks.md, research.md, quickstart.md, and checklists/
from numbered spec directories. These are stale development artifacts
that don't belong alongside specs (desired state descriptions).

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../checklists/requirements.md                |  32 ----
 specs/001-auto-doc-screenshots/plan.md        |  73 --------
 specs/001-auto-doc-screenshots/quickstart.md  |  58 ------
 specs/001-auto-doc-screenshots/research.md    |  56 ------
 specs/001-auto-doc-screenshots/tasks.md       | 166 ------------------
 .../checklists/requirements.md                |  34 ----
 specs/010-advanced-sdk-options/plan.md        |  88 ----------
 specs/010-advanced-sdk-options/tasks.md       |  96 ----------
 specs/011-session-options-menu/plan.md        |  22 ---
 specs/011-session-options-menu/tasks.md       |  40 -----
 10 files changed, 665 deletions(-)
 delete mode 100644 specs/001-auto-doc-screenshots/checklists/requirements.md
 delete mode 100644 specs/001-auto-doc-screenshots/plan.md
 delete mode 100644 specs/001-auto-doc-screenshots/quickstart.md
 delete mode 100644 specs/001-auto-doc-screenshots/research.md
 delete mode 100644 specs/001-auto-doc-screenshots/tasks.md
 delete mode 100644 specs/001-coderabbit-integration/checklists/requirements.md
 delete mode 100644 specs/010-advanced-sdk-options/plan.md
 delete mode 100644 specs/010-advanced-sdk-options/tasks.md
 delete mode 100644 specs/011-session-options-menu/plan.md
 delete mode 100644 specs/011-session-options-menu/tasks.md

diff --git a/specs/001-auto-doc-screenshots/checklists/requirements.md b/specs/001-auto-doc-screenshots/checklists/requirements.md
deleted file mode 100644
index f783627c4..000000000
--- a/specs/001-auto-doc-screenshots/checklists/requirements.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# Specification Quality Checklist: Automated Documentation Screenshots
-
-**Purpose**: Validate specification completeness and quality before proceeding to planning
-**Created**: 2026-04-15
-**Feature**: [spec.md](../spec.md)
-
-## Content Quality
-
-- [x] No implementation details (languages, frameworks, APIs)
-- [x] Focused on user value and business needs
-- [x] Written for non-technical stakeholders
-- [x] All mandatory sections completed
-
-## Requirement Completeness
-
-- [x] No [NEEDS CLARIFICATION] markers remain
-- [x] Requirements are testable and unambiguous
-- [x] Success criteria are measurable
-- [x] All acceptance scenarios are defined
-- [x] Edge cases are identified
-- [x] Scope is clearly bounded
-- [x] Dependencies and assumptions identified
-
-## Feature Readiness
-
-- [x] All functional requirements have clear acceptance criteria
-- [x] User scenarios cover primary flows
-- [x] No implementation details leak into specification
-
-## Notes
-
-- All items pass. Spec ready for `/speckit.plan`.
diff --git a/specs/001-auto-doc-screenshots/plan.md b/specs/001-auto-doc-screenshots/plan.md
deleted file mode 100644
index c3e7a02ac..000000000
--- a/specs/001-auto-doc-screenshots/plan.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Implementation Plan: Automated Documentation Screenshots
-
-**Branch**: `001-auto-doc-screenshots` | **Date**: 2026-04-15 | **Spec**: [spec.md](spec.md)
-
-## Summary
-
-Build a manifest-driven Cypress screenshot pipeline that captures the web UI in both light and dark themes against a kind cluster, embeds paired PNGs in Astro Starlight docs with CSS-based theme auto-switching, and automates the flow via a daily GHA workflow that opens PRs when screenshots change. Split docs hosting: Netlify deploys main continuously, GitHub Pages deploys release tags only.
-
-## Technical Context
-
-**Language/Version**: TypeScript (Cypress 15), CSS, YAML (GHA), Bash (Makefile), Astro/Starlight 0.34
-**Primary Dependencies**: Cypress 15, Astro Starlight 0.34, next-themes (existing frontend), kind 0.27
-**Storage**: PNG files in `docs/public/images/screenshots/` committed to git (~5-10MB total)
-**Testing**: Cypress spec validation against kind cluster in mock SDK mode
-**Target Platform**: GitHub Actions (Ubuntu), local macOS (kind + Docker)
-**Project Type**: Tooling/CI — no new services, APIs, or CRDs
-**Performance Goals**: Daily CI workflow completes within 30 minutes
-**Constraints**: Screenshots must be 1x DPI for cross-platform consistency; no MDX conversion; no system-level package installs on Netlify
-**Scale/Scope**: 10 screenshot entries (20 PNGs), 6 docs pages modified
-
-## Constitution Check
-
-*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
-
-| Principle | Applicable? | Status | Notes |
-|-----------|-------------|--------|-------|
-| I. K8s-Native | No | N/A | No new CRDs, operators, or K8s resources created |
-| II. Security | Minimal | PASS | No secrets, tokens, or auth changes. GHA uses `GITHUB_TOKEN` (default) |
-| III. Type Safety | Yes | PASS | Cypress spec uses typed interfaces; no `any` types |
-| IV. TDD | Partial | PASS | Screenshot spec IS the test — it validates screenshot capture works. No business logic to unit test |
-| V. Modularity | Yes | PASS | Single Cypress spec file (~150 lines), single manifest JSON, single CSS block |
-| VI. Observability | No | N/A | No new services or endpoints |
-| VII. Resource Lifecycle | No | N/A | No K8s child resources |
-| VIII. Context Engineering | No | N/A | No AI prompts or agent changes |
-| IX. Data Access | No | N/A | No RAG/MCP/RLHF changes |
-| X. Commit Discipline | Yes | PASS | Plan targets ~7 focused commits, each under 300 lines |
-
-No constitution violations. No complexity justifications required.
-
-## Project Structure
-
-### Documentation (this feature)
-
-```text
-specs/001-auto-doc-screenshots/
-├── spec.md
-├── plan.md              # This file
-├── research.md          # Phase 0
-└── checklists/
-    └── requirements.md
-```
-
-### Source Code (repository root)
-
-```text
-# New files
-e2e/cypress/e2e/screenshots.cy.ts          # Manifest-driven capture spec
-e2e/cypress/screenshots/manifest.json       # Screenshot targets
-.github/workflows/screenshots.yml           # Daily cron + auto-PR
-docs/netlify.toml                           # Netlify build config
-docs/public/images/screenshots/             # Committed PNG outputs
-
-# Modified files
-docs/src/styles/custom.css                  # Theme-switching CSS
-docs/astro.config.mjs                       # Env-aware site/base
-.github/workflows/docs.yml                  # Release-tag trigger
-e2e/cypress.config.ts                       # Screenshot output dir, DPI
-e2e/.gitignore                              # Exclude output/
-Makefile                                    # Screenshot targets
-docs/src/content/docs/**/*.md               # 6 pages get screenshot embeds
-```
-
-**Structure Decision**: This feature touches existing directories only. No new top-level directories. Cypress screenshots live alongside existing E2E tests. Docs images go in the standard Starlight `public/` assets directory.
diff --git a/specs/001-auto-doc-screenshots/quickstart.md b/specs/001-auto-doc-screenshots/quickstart.md
deleted file mode 100644
index f3166b429..000000000
--- a/specs/001-auto-doc-screenshots/quickstart.md
+++ /dev/null
@@ -1,58 +0,0 @@
-# Quickstart: Documentation Screenshots
-
-## Capture screenshots locally
-
-```bash
-# 1. Start a kind cluster (if not already running)
-make kind-up CONTAINER_ENGINE=docker
-
-# 2. Capture all screenshots (light + dark)
-make screenshots
-
-# 3. Preview in docs dev server
-cd docs && npm run dev
-# Visit http://localhost:4321/platform/getting-started/quickstart-ui/
-# Toggle theme to verify switching works
-
-# 4. Clean up
-make kind-down
-```
-
-## Add a new screenshot
-
-1. Add entry to `e2e/cypress/screenshots/manifest.json`:
-```json
-{
-  "id": "my-new-page",
-  "page": "/projects/{workspace}/my-page",
-  "waitFor": "Page Title",
-  "setupSteps": []
-}
-```
-
-2. Add HTML to the target docs page:
-```html
-<figure class="screenshot-pair">
-  <img class="screenshot-light" src="/platform/images/screenshots/my-new-page-light.png" alt="Description" />
-  <img class="screenshot-dark" src="/platform/images/screenshots/my-new-page-dark.png" alt="Description" />
-</figure>
-```
-
-3. Run `make screenshots` to capture.
-
-## Add a setup step
-
-If a screenshot needs navigation before capture (e.g., clicking a tab), add a named step:
-
-1. Add `"setupSteps": ["myStep"]` to the manifest entry
-2. Add a case to `runSetupStep()` in `e2e/cypress/e2e/screenshots.cy.ts`
-
-## CI workflow
-
-The `screenshots.yml` workflow runs daily at 6AM UTC. It:
-1. Pulls latest images from Quay.io
-2. Spins up a kind cluster
-3. Runs the screenshot Cypress spec
-4. Opens a PR if any images changed
-
-Trigger manually: Actions > "Update Documentation Screenshots" > "Run workflow"
diff --git a/specs/001-auto-doc-screenshots/research.md b/specs/001-auto-doc-screenshots/research.md
deleted file mode 100644
index 61d8a5fbc..000000000
--- a/specs/001-auto-doc-screenshots/research.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Research: Automated Documentation Screenshots
-
-## Decision 1: Theme Switching in Starlight Docs
-
-**Decision**: Use CSS `data-theme` selectors with paired `<img>` elements in plain markdown.
-
-**Rationale**: Starlight uses `data-theme="light|dark"` on `<html>`. CSS rules can show/hide images based on this attribute. This works in standard `.md` files without MDX conversion. Zero JS overhead — pure CSS display toggling.
-
-**Alternatives considered**:
-- MDX components with conditional rendering — requires converting all `.md` to `.mdx`, disruptive
-- `<picture>` with `prefers-color-scheme` media queries — doesn't track Starlight's manual theme override, only OS preference
-- CSS filter (invert) on single images — produces poor quality for UI screenshots
-
-## Decision 2: Screenshot Architecture
-
-**Decision**: Single Cypress spec file driven by JSON manifest.
-
-**Rationale**: Screenshots are captures, not tests. A manifest decouples "what to capture" from "how to capture." Adding a screenshot is a JSON entry + HTML snippet, not Cypress code. The existing E2E suite uses a single large spec (`sessions.cy.ts`, 2134 lines) — one file is the project convention.
-
-**Alternatives considered**:
-- Per-page Cypress spec files — duplicates setup/teardown, harder to maintain
-- Playwright-based (already a docs dep) — would duplicate the test harness; Cypress E2E infra is proven
-- Storybook + Chromatic — requires adding Storybook, overkill for full-page screenshots
-
-## Decision 3: Image Path Strategy (Dual Hosting)
-
-**Decision**: Use `/platform/` prefix in all image paths. Netlify redirects `/platform/*` to `/:splat`.
-
-**Rationale**: GitHub Pages serves at `/platform/` base. Netlify serves at `/`. Using a single path prefix with a Netlify redirect avoids maintaining two sets of paths. The `astro.config.mjs` detects `process.env.NETLIFY` to set the correct `site`/`base` for link generation.
-
-**Alternatives considered**:
-- Relative paths — fragile, different nesting depths per page
-- Astro `<Image>` components — requires MDX
-- Two separate image directories — double storage, sync nightmares
-
-## Decision 4: CI Cadence
-
-**Decision**: Daily cron (6AM UTC) with `workflow_dispatch` for on-demand runs. Auto-PR on change, no direct commits to main.
-
-**Rationale**: UI changes are frequent enough that weekly misses drift. Daily catches changes promptly. The PR-based flow ensures human review of visual changes. The kind cluster spin-up cost (~10 min) is acceptable for a daily run.
-
-**Alternatives considered**:
-- Weekly — misses UI changes for too long
-- On every push to main — wasteful, most pushes don't change UI
-- Direct commit to main — no human review of visual changes
-
-## Decision 5: DPI Normalization
-
-**Decision**: Force 1x device scale factor via Chrome launch arg when `CYPRESS_SCREENSHOT_MODE` is set.
-
-**Rationale**: macOS Retina displays capture at 2x by default, producing images twice the size of CI (Linux 1x). Forcing 1x ensures identical output across platforms.
-
-**Alternatives considered**:
-- Post-process resize — adds complexity, lossy
-- Accept 2x everywhere — doubles file sizes unnecessarily
-- Only capture in CI — blocks local iteration
diff --git a/specs/001-auto-doc-screenshots/tasks.md b/specs/001-auto-doc-screenshots/tasks.md
deleted file mode 100644
index c46ddde5e..000000000
--- a/specs/001-auto-doc-screenshots/tasks.md
+++ /dev/null
@@ -1,166 +0,0 @@
-# Tasks: Automated Documentation Screenshots
-
-**Input**: Design documents from `/specs/001-auto-doc-screenshots/`
-**Prerequisites**: plan.md, spec.md, research.md, quickstart.md
-
-**Tests**: Not explicitly requested. The screenshot Cypress spec IS the validation mechanism.
-
-## Format: `[ID] [P?] [Story] Description`
-
-- **[P]**: Can run in parallel (different files, no dependencies)
-- **[Story]**: Which user story this task belongs to (US1, US2, US3)
-- Exact file paths included in descriptions
-
----
-
-## Phase 1: Setup
-
-**Purpose**: Create directories and config scaffolding
-
-- [x] T001 Create screenshots directory `docs/public/images/screenshots/.gitkeep`
-- [x] T002 [P] Add `cypress/screenshots/output/` to `e2e/.gitignore`
-
----
-
-## Phase 2: Foundational
-
-**Purpose**: CSS and Cypress infrastructure that all stories depend on
-
-- [x] T003 Add screenshot theme-switching CSS rules to `docs/src/styles/custom.css`
-- [x] T004 [P] Create screenshot manifest at `e2e/cypress/screenshots/manifest.json` with all 10 entries
-- [x] T005 Create Cypress screenshot spec at `e2e/cypress/e2e/screenshots.cy.ts` with manifest-driven capture, theme toggling, workspace/session setup, and setup step handlers
-- [x] T006 [P] Add `screenshotsFolder` and DPI normalization (`CYPRESS_SCREENSHOT_MODE`) to `e2e/cypress.config.ts`
-- [x] T007 Add `screenshots`, `screenshots-headed`, `screenshots-clean` targets to `Makefile`
-- [x] T007a Create Netlify config at `docs/netlify.toml` with build command (`npm ci && npx playwright install chromium && npm run build`), `/platform/*` redirect
-- [x] T007b Update `docs/astro.config.mjs` for environment-aware `site`/`base` using `process.env.NETLIFY`
-
-**Checkpoint**: `make screenshots` can run against a kind cluster; Netlify site renders with correct CSS
-
----
-
-## Phase 3: User Story 1 — Theme-Aware Screenshots in Docs (Priority: P1)
-
-**Goal**: Documentation pages display screenshots that auto-switch with the reader's theme.
-
-**Independent Test**: Open docs dev server, navigate to quickstart page, toggle Starlight theme — correct screenshot variant displays.
-
-- [x] T008 [US1] Embed screenshot HTML in `docs/src/content/docs/getting-started/quickstart-ui.md` (workspaces-page, integrations-page, new-session-dialog, session-page)
-- [x] T009 [P] [US1] Embed screenshot HTML in `docs/src/content/docs/concepts/sessions.md` (session-list, session-page, new-session-dialog)
-- [x] T010 [P] [US1] Embed screenshot HTML in `docs/src/content/docs/concepts/integrations.md` (integrations-page)
-- [x] T011 [P] [US1] Embed screenshot HTML in `docs/src/content/docs/concepts/workspaces.md` (workspace-settings, workspace-sharing, api-keys)
-- [x] T012 [P] [US1] Embed screenshot HTML in `docs/src/content/docs/concepts/scheduled-sessions.md` (scheduled-sessions)
-- [x] T013 [P] [US1] Embed screenshot HTML in `docs/src/content/docs/concepts/context-and-artifacts.md` (file-browser)
-- [x] T014 [US1] Verify docs build succeeds: `cd docs && npm run build`
-- [x] T015 [US1] Capture screenshots locally: `make kind-up CONTAINER_ENGINE=docker && make screenshots`
-- [x] T016 [US1] Verify theme switching in docs dev server: `cd docs && npm run dev`, toggle themes
-- [x] T017 [US1] Commit captured screenshots in `docs/public/images/screenshots/`
-
-**Checkpoint**: Docs pages show theme-aware screenshots locally
-
----
-
-## Phase 4: User Story 2 — Daily Automated Screenshot Capture (Priority: P1)
-
-**Goal**: CI workflow captures screenshots daily and opens PRs when images change.
-
-**Independent Test**: Trigger workflow via `workflow_dispatch`, confirm it completes and creates a PR.
-
-- [x] T018 [US2] Create GHA workflow at `.github/workflows/screenshots.yml` with daily cron, kind setup, Cypress capture, change detection, and auto-PR creation
-- [ ] T019 [US2] Push branch and trigger workflow via `workflow_dispatch` to validate
-
-**Checkpoint**: CI pipeline captures screenshots and opens PRs autonomously
-
----
-
-## Phase 5: User Story 3 — Two-Tier Documentation Hosting (Priority: P2)
-
-**Goal**: Netlify deploys main continuously, GitHub Pages deploys release tags only.
-
-**Independent Test**: Push docs change to main — appears on Netlify, not on GitHub Pages.
-
-- [x] T020 [US3] Change `.github/workflows/docs.yml` trigger from `push: branches: [main]` to `push: tags: ['v*']`
-- [x] T021 [US3] Verify local docs build: `cd docs && npm run build`
-- [ ] T022 [US3] Push to main, verify Netlify deploys with correct CSS and screenshot paths
-
-**Checkpoint**: Two-tier hosting operational — Netlify for main, GitHub Pages for releases
-
----
-
-## Phase 6: Polish
-
-- [x] T025 Verify all 9 screenshot pairs exist in `docs/public/images/screenshots/`
-- [ ] T026 Run quickstart.md validation — follow all steps, confirm they work
-- [ ] T027 Clean up kind cluster: `make kind-down`
-
----
-
-## Dependencies & Execution Order
-
-### Phase Dependencies
-
-- **Setup (Phase 1)**: No dependencies
-- **Foundational (Phase 2)**: Depends on Phase 1
-- **US1 (Phase 3)**: Depends on Phase 2 (needs CSS + Cypress spec)
-- **US2 (Phase 4)**: Depends on Phase 2 (needs Cypress spec + manifest)
-- **US3 (Phase 5)**: No dependency on US1 or US2 — can run in parallel
-- **Polish (Phase 6)**: Depends on all stories complete
-
-### User Story Dependencies
-
-- **US1 (P1)**: Needs kind cluster running for T015. Foundational phase must be done.
-- **US2 (P1)**: Independent of US1. Can start after Foundational.
-- **US3 (P2)**: Fully independent — only touches docs config and GHA, no Cypress dependency.
-
-### Parallel Opportunities
-
-- T001 and T002 can run in parallel (Phase 1)
-- T004 and T006 can run in parallel with T003 (Phase 2)
-- T009, T010, T011, T012, T013 can all run in parallel (Phase 3 — different files)
-- US2 and US3 can run in parallel (different files, no shared state)
-
----
-
-## Parallel Example: Phase 3 (US1) Doc Embeds
-
-```bash
-# All doc page embeds can be done simultaneously:
-Task: "Embed screenshots in quickstart-ui.md"   # T008
-Task: "Embed screenshots in sessions.md"         # T009
-Task: "Embed screenshots in integrations.md"     # T010
-Task: "Embed screenshots in workspaces.md"       # T011
-Task: "Embed screenshots in scheduled-sessions.md" # T012
-Task: "Embed screenshots in context-and-artifacts.md" # T013
-```
-
----
-
-## Implementation Strategy
-
-### MVP First (US1 Only)
-
-1. Complete Phase 1 + 2: Setup + Foundational
-2. Complete Phase 3: Embed screenshots + capture locally
-3. **STOP and VALIDATE**: Theme switching works in docs dev server
-4. Demo to stakeholders
-
-### Incremental Delivery
-
-1. Setup + Foundational → Cypress spec works
-2. US1 → Screenshots in docs, theme switching works (MVP)
-3. US2 → Daily automation keeps screenshots fresh
-4. US3 → Two-tier hosting separates stable from current
-5. Polish → Final validation
-
----
-
-## Metrics
-
-- **Total tasks**: 27
-- **Phase 1 (Setup)**: 2
-- **Phase 2 (Foundational)**: 5
-- **Phase 3 (US1)**: 10
-- **Phase 4 (US2)**: 2
-- **Phase 5 (US3)**: 5
-- **Phase 6 (Polish)**: 3
-- **Parallel opportunities**: 12 tasks marked [P] or parallelizable within phase
-- **MVP scope**: Phases 1-3 (17 tasks)
diff --git a/specs/001-coderabbit-integration/checklists/requirements.md b/specs/001-coderabbit-integration/checklists/requirements.md
deleted file mode 100644
index f4837ba9b..000000000
--- a/specs/001-coderabbit-integration/checklists/requirements.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# Specification Quality Checklist: CodeRabbit Integration
-
-**Purpose**: Validate specification completeness and quality before proceeding to planning
-**Created**: 2026-04-14
-**Feature**: [spec.md](../spec.md)
-
-## Content Quality
-
-- [x] No implementation details (languages, frameworks, APIs)
-- [x] Focused on user value and business needs
-- [x] Written for non-technical stakeholders
-- [x] All mandatory sections completed
-
-## Requirement Completeness
-
-- [x] No [NEEDS CLARIFICATION] markers remain
-- [x] Requirements are testable and unambiguous
-- [x] Success criteria are measurable
-- [x] Success criteria are technology-agnostic (no implementation details)
-- [x] All acceptance scenarios are defined
-- [x] Edge cases are identified
-- [x] Scope is clearly bounded
-- [x] Dependencies and assumptions identified
-
-## Feature Readiness
-
-- [x] All functional requirements have clear acceptance criteria
-- [x] User scenarios cover primary flows
-- [x] Feature meets measurable outcomes defined in Success Criteria
-- [x] No implementation details leak into specification
-
-## Notes
-
-- All items pass validation. Spec is ready for `/speckit.plan`.
diff --git a/specs/010-advanced-sdk-options/plan.md b/specs/010-advanced-sdk-options/plan.md
deleted file mode 100644
index 87f1dc5bf..000000000
--- a/specs/010-advanced-sdk-options/plan.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Implementation Plan: Advanced SDK Options
-
-**Branch**: `010-advanced-sdk-options` | **Date**: 2026-04-15 | **Spec**: [spec.md](spec.md)
-**Input**: Feature specification from `/specs/010-advanced-sdk-options/spec.md`
-
-## Summary
-
-Expose Claude Agent SDK options (temperature, tokens, tools, system prompt, etc.) in the session creation UI. Options flow from a React form through Go backend validation to a Python runner, where they merge into `ClaudeAgentOptions`. Defense-in-depth via backend allowlist + runner denylist. A weekly GHA workflow detects SDK drift.
-
-## Technical Context
-
-**Language/Version**: Go 1.22+ (backend), TypeScript/Next.js 14 (frontend), Python 3.12 (runner)
-**Primary Dependencies**: Gin (backend HTTP), React + Shadcn/ui (frontend), claude-agent-sdk (runner)
-**Storage**: Kubernetes CRDs — options travel as JSON string in existing `environmentVariables` map (no CRD changes)
-**Testing**: go test (backend), vitest (frontend), pytest (runner)
-**Target Platform**: Kubernetes cluster (OpenShift/kind)
-**Project Type**: Web application (Go API + React frontend + Python runner)
-
-## Constitution Check
-
-| Principle | Status | Notes |
-|-----------|--------|-------|
-| I. K8s-Native | PASS | Uses existing CR env vars, no new CRDs |
-| II. Security | PASS | Allowlist + denylist + append-only system prompt |
-| III. Type Safety | PASS | Backend type validation per key, no `any` in frontend |
-| IV. TDD | ENFORCED | Tests required for each component |
-| V. Modularity | PASS | Single-file component, handler functions, bridge method |
-| X. Commit Discipline | PASS | Feature split into backend/frontend/runner commits |
-
-## Project Structure
-
-### Documentation (this feature)
-
-```text
-specs/010-advanced-sdk-options/
-├── spec.md              # Feature specification
-├── plan.md              # This file
-└── tasks.md             # Task breakdown
-```
-
-### Source Code (files to create or modify)
-
-```text
-components/backend/
-├── handlers/sessions.go          # MODIFY: add filterSdkOptions, validateSdkOptionValue, allowlist
-└── types/session.go              # MODIFY: add SdkOptions field to request types
-
-components/frontend/src/
-├── components/
-│   └── advanced-sdk-options.tsx   # CREATE: collapsible SDK options form
-├── app/projects/[name]/
-│   ├── new/page.tsx               # MODIFY: wire sdkOptions into create call
-│   └── sessions/[sessionName]/components/
-│       └── new-session-view.tsx   # MODIFY: add AdvancedSdkOptions + feature flag gate
-└── types/api/sessions.ts         # MODIFY: add SdkOptions type
-
-components/runners/ambient-runner/
-├── ambient_runner/bridges/claude/bridge.py  # MODIFY: parse SDK_OPTIONS, denylist, merge
-├── sdk-options-manifest.json               # CREATE: canonical SDK field list
-└── tests/test_sdk_options.py               # CREATE: SDK_OPTIONS parsing tests
-
-components/manifests/base/core/flags.json   # MODIFY: add advanced-sdk-options flag
-
-.github/workflows/
-└── claude-sdk-options-drift.yml            # CREATE: weekly drift detection
-
-components/backend/handlers/
-└── sessions_sdk_options_test.go            # CREATE: backend filterSdkOptions tests
-
-components/frontend/src/components/__tests__/
-└── advanced-sdk-options.test.tsx           # CREATE: frontend component tests
-```
-
-## Design Decisions
-
-1. **Reuse existing form components** — `claude-agent-options/` already exists on main with schema, options-form, and 11 field editors covering all SDK fields. `advanced-sdk-options.tsx` is a thin collapsible wrapper around `AgentOptionsFields`.
-
-2. **Backend allowlist as map literal** — `allowedSdkOptionKeys map[string]bool` at package level. Keys derived from `claudeAgentOptionsSchema` minus platform-internal keys. Backend does key filtering only — JSON marshal handles type serialization.
-
-3. **Runner denylist as frozenset** — `_SDK_OPTIONS_DENYLIST` at module level. Blocks platform-internal keys (`cwd`, `api_key`, `mcp_servers`, `setting_sources`, `stderr`, `resume`, `continue_conversation`, `add_dirs`) even if backend is bypassed.
-
-4. **SDK_OPTIONS as JSON string in env var** — Avoids CRD changes. The `environmentVariables` map already exists on the CR spec.
-
-5. **System prompt append-only** — User text appended under `## Custom Instructions` heading. Prevents users from stripping platform security instructions.
-
-6. **Feature flag UI-only** — Backend always accepts `sdkOptions` for API callers. Flag gates the form in the frontend only.
-
-7. **Rename agentOptions → sdkOptions** — Frontend types already have `agentOptions?: Record<string, unknown>` on the request type. Rename to `sdkOptions` for clarity (matches SDK wire format).
diff --git a/specs/010-advanced-sdk-options/tasks.md b/specs/010-advanced-sdk-options/tasks.md
deleted file mode 100644
index 2adebc1de..000000000
--- a/specs/010-advanced-sdk-options/tasks.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# Tasks: Advanced SDK Options
-
-**Input**: Design documents from `/specs/010-advanced-sdk-options/`
-**Prerequisites**: plan.md (required), spec.md (required)
-
-**Execution skill**: `superpowers:subagent-driven-development` (one subagent per phase, review between phases)
-
-## Phase 1: Setup
-
-- [ ] T001 Add `advanced-sdk-options` feature flag to `components/manifests/base/core/flags.json` with `scope:workspace` tag
-
-### Commit: `feat(flags): add advanced-sdk-options workspace feature flag`
-
----
-
-## Phase 2: Backend — SDK Options Filtering (TDD)
-
-**Goal**: Backend accepts `sdkOptions` on session create, filters through allowlist, validates types, serializes to `SDK_OPTIONS` env var on the CR.
-
-- [ ] T010 [US1] Add `SdkOptions map[string]interface{}` field with `json:"sdkOptions,omitempty"` to `CreateAgenticSessionRequest` in `components/backend/types/session.go`
-- [ ] T011 [US1] Create `components/backend/handlers/sessions_sdk_options_test.go` (TDD — tests first, then implement). Tests: valid keys pass through, unknown keys silently dropped, empty map returns nil, string/numeric/bool/slice type checks, invalid type returns error
-- [ ] T012 [US1] Implement `allowedSdkOptionKeys` map and `filterSdkOptions` in `components/backend/handlers/sessions.go`. Allowlist keys: all fields from `claudeAgentOptionsSchema` minus denylisted keys (`cwd`, `resume`, `mcp_servers`, `setting_sources`, `continue_conversation`, `add_dirs`, `cli_path`, `settings`, `permission_prompt_tool_name`, `fork_session`). Include `validateSdkOptionValue` for basic type checks on primitives (string, float, int, bool, slice). Complex objects (hooks, agents, sandbox, thinking, mcp_servers) pass through as-is — JSON marshal handles them.
-- [ ] T013 [US1] Wire into `CreateAgenticSession` handler: if `req.SdkOptions` is non-empty, call `filterSdkOptions`, return 400 on error, JSON-serialize into `envVars["SDK_OPTIONS"]`
-- [ ] T014 [US1] Run backend tests: `cd components/backend && go test -tags test -run TestSdkOptions ./handlers/`
-
-### Commit: `feat(backend): add sdkOptions allowlist and type validation`
-
----
-
-## Phase 3: Runner — SDK_OPTIONS Parsing (TDD)
-
-**Goal**: Runner parses `SDK_OPTIONS` env var, applies denylist, merges system_prompt append-only, passes remaining options to adapter.
-
-- [ ] T020 [US1] Create `components/runners/ambient-runner/tests/test_sdk_options.py` (TDD). Tests: valid JSON parsed, malformed JSON returns empty dict, JSON array returns empty dict, denylisted keys blocked with warning, non-denylisted keys pass, system_prompt appended under `## Custom Instructions` heading
-- [ ] T021 [US1] Implement `_SDK_OPTIONS_DENYLIST` frozenset and SDK_OPTIONS parsing in `components/runners/ambient-runner/ambient_runner/bridges/claude/bridge.py`. In `_ensure_adapter`: parse env var, apply denylist with per-key warning logs, handle system_prompt append, merge remaining keys into options dict
-- [ ] T022 [US1] Run runner tests: `cd components/runners/ambient-runner && python -m pytest tests/test_sdk_options.py -v`
-
-### Commit: `feat(runner): parse SDK_OPTIONS env var with denylist and system prompt merge`
-
----
-
-## Phase 4: Frontend — Wire Form into Session Creation (TDD)
-
-**Goal**: Wrap existing `claude-agent-options/` form in a collapsible container, gate behind feature flag, wire into session create flow.
-
-**Existing on main**: `components/frontend/src/components/claude-agent-options/` has `AgentOptionsFields`, `claudeAgentOptionsSchema`, `claudeAgentOptionsDefaults`, and 11 field editors. Reuse these.
-
-- [ ] T030 [US1] Rename `agentOptions` to `sdkOptions` in `components/frontend/src/types/api/sessions.ts` and `components/frontend/src/types/agentic-session.ts`
-- [ ] T031 [US1] Create `components/frontend/src/components/__tests__/advanced-sdk-options.test.tsx` (TDD). Tests: not rendered when flag is disabled, renders collapsed by default when flag enabled, expands on click, form fields visible when expanded
-- [ ] T032 [US1] Create `components/frontend/src/components/advanced-sdk-options.tsx` — collapsible wrapper using Shadcn `Collapsible`. Imports `AgentOptionsFields` from `claude-agent-options`. Props: `projectName`, `form: UseFormReturn<ClaudeAgentOptionsForm>`, `disabled?`. Uses `useWorkspaceFlag(projectName, "advanced-sdk-options")` to gate visibility
-- [ ] T033 [US1] Wire into `components/frontend/src/app/projects/[name]/sessions/[sessionName]/components/new-session-view.tsx`: add `useForm<ClaudeAgentOptionsForm>` with defaults, render `<AdvancedSdkOptions>`, pass non-empty form values as `sdkOptions` in `onCreateSession` callback
-- [ ] T034 [US1] Wire into `components/frontend/src/app/projects/[name]/new/page.tsx`: accept `sdkOptions` in config, spread into create mutation payload
-- [ ] T035 [US1] Run frontend tests and build: `cd components/frontend && npx vitest run && npm run build`
-
-### Commit: `feat(frontend): add collapsible AdvancedSdkOptions gated by workspace flag`
-
----
-
-## Phase 5: Drift Detection (US2)
-
-**Goal**: Weekly GHA workflow introspects `ClaudeAgentOptions` from PyPI, compares against manifest, opens PR on drift.
-
-- [ ] T040 [US2] Generate `components/runners/ambient-runner/sdk-options-manifest.json` by introspecting the current `claude-agent-sdk` package: install via `uv pip install claude-agent-sdk`, extract fields from `ClaudeAgentOptions.model_fields` (Pydantic), write `{"generatedFrom": "claude-agent-sdk", "generatedAt": "<ISO>", "sdkVersion": "<version>", "options": {"field_name": {"type": "<annotation>", "required": <bool>}}}`
-- [ ] T041 [US2] Create `scripts/sdk-options-drift-check.py`: import `ClaudeAgentOptions`, introspect via `model_fields`, compare against manifest, exit 0 (no drift), exit 1 (drift found — write updated manifest), exit 2 (error). Must handle: `ImportError` (hard fail), Pydantic v1 vs v2 (check for `model_fields` vs `__fields__`)
-- [ ] T042 [US2] Add drift check step to `.github/workflows/sdk-version-bump.yml`: after "Apply updates" step, `pip install claude-agent-sdk`, run `scripts/sdk-options-drift-check.py`, include updated manifest in the commit if drift found. No standalone workflow — drift detection runs as part of the daily SDK version bump.
-- [ ] T043 [US2] Test drift detection end-to-end: run `python scripts/sdk-options-drift-check.py` locally, verify clean exit with current manifest
-
-### Commit: `refactor(ci): consolidate drift detection into sdk-version-bump workflow`
-
----
-
-## Phase 6: Verify
-
-- [ ] T050 Run all component test suites: backend (`make test`), frontend (`npx vitest run --coverage`), runner (`python -m pytest tests/ -v`)
-- [ ] T051 Run `npm run build` in frontend (must pass with 0 errors, 0 warnings)
-- [ ] T052 Run `make lint` (pre-commit hooks on all changed files)
-- [ ] T053 Grep changed `.tsx`/`.ts` files for `: any` or `as any` — must be zero
-- [ ] T054 Cross-reference spec acceptance scenarios SC-001 through SC-005 against test coverage
-
-### Commit (if fixes needed): `chore: lint and polish for advanced SDK options`
-
----
-
-## Dependencies
-
-- **Phase 1** → Phases 2, 3, 4 (flag must exist before frontend gate works)
-- **Phase 2** → Phase 4 (backend must accept `sdkOptions` before frontend sends it)
-- **Phase 3** → independent (runner reads env var, no compile-time dependency on backend)
-- **Phase 4** → depends on Phase 2 (API contract)
-- **Phase 5** → independent (drift workflow has no code dependency on other phases)
-- **Phase 6** → all phases complete
-
-### Parallel opportunities
-
-- **Phases 2 + 3 + 5** can run in parallel (backend, runner, drift are independent)
-- Within Phase 4: T030 (types) must precede T031-T035
diff --git a/specs/011-session-options-menu/plan.md b/specs/011-session-options-menu/plan.md
deleted file mode 100644
index 17c07d901..000000000
--- a/specs/011-session-options-menu/plan.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Implementation Plan: Session Options Menu Infrastructure
-
-**Branch**: `011-session-options-menu` | **Date**: 2026-04-16 | **Spec**: [spec.md](spec.md)
-
-## Summary
-
-Add a separator and discovery dot to the `+` dropdown in `new-session-view.tsx`. Frontend-only change. One file modified, one test file updated.
-
-## Technical Context
-
-**Language**: TypeScript/React (Next.js 14)
-**Dependencies**: Shadcn/ui (`DropdownMenuSeparator`, `DropdownMenuCheckboxItem`), localStorage
-**Testing**: vitest
-**Target**: `components/frontend/src/app/projects/[name]/sessions/[sessionName]/components/new-session-view.tsx`
-
-## Files
-
-```
-components/frontend/src/app/projects/[name]/sessions/[sessionName]/components/
-├── new-session-view.tsx                    # MODIFY: add separator, discovery dot, imports
-└── __tests__/new-session-view.test.tsx     # MODIFY: add tests for separator and dot
-```
diff --git a/specs/011-session-options-menu/tasks.md b/specs/011-session-options-menu/tasks.md
deleted file mode 100644
index 5c5cf43d2..000000000
--- a/specs/011-session-options-menu/tasks.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Tasks: Session Options Menu Infrastructure
-
-**Input**: Design documents from `/specs/011-session-options-menu/`
-
-## Phase 1: Separator + Imports
-
-- [ ] T001 [US1] In `new-session-view.tsx`, import `DropdownMenuSeparator` and `DropdownMenuCheckboxItem` from `@/components/ui/dropdown-menu`
-- [ ] T002 [US1] Add `<DropdownMenuSeparator />` after the Upload File menu item in the `+` dropdown
-
-### Commit: `feat(frontend): add separator to + dropdown for session options`
-
----
-
-## Phase 2: Discovery Dot (TDD)
-
-- [ ] T010 [US2] Add `MENU_VERSION` constant (e.g., `"2026-04-16"`) to `new-session-view.tsx`
-- [ ] T011 [US2] Add state + effect for discovery dot: compare `MENU_VERSION` against `localStorage.getItem("acp-menu-seen-version")`, set `showDot` state. Wrap in try/catch for localStorage unavailability.
-- [ ] T012 [US2] On `DropdownMenu` `onOpenChange(open)`: when `open` is true, clear the dot and write `MENU_VERSION` to localStorage
-- [ ] T013 [US2] Render the dot: when `showDot` is true, render a `<span className="absolute -top-0.5 -right-0.5 h-2 w-2 rounded-full bg-primary" />` inside the `+` button wrapper (make wrapper `relative`)
-- [ ] T014 [US2] Add tests in `__tests__/new-session-view.test.tsx`: dot visible when localStorage version is old, dot clears on menu open, dot hidden when versions match
-
-### Commit: `feat(frontend): add discovery dot to + button for new menu items`
-
----
-
-## Phase 3: Verify
-
-- [ ] T020 Run frontend tests: `cd components/frontend && npx vitest run`
-- [ ] T021 Run frontend build: `cd components/frontend && npm run build`
-- [ ] T022 Grep for `any` types in changed files
-
-### Commit (if fixes needed): `chore: lint fixes`
-
----
-
-## Dependencies
-
-- Phase 1 → independent
-- Phase 2 → independent (but logically follows Phase 1)
-- Phase 3 → depends on Phases 1 + 2

From fcf1b7ae1f9c09be92073043b3c08ade3a8fa401 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:21:11 -0400
Subject: [PATCH 06/16] docs: rewrite CLAUDE.md and BOOKMARKS.md for new
 structure

Add specs/, workflows/, skills/ to CLAUDE.md structure section. Update
BOOKMARKS.md with new Specs, Workflows, and Standards sections replacing
the old Component Development Guides and Cross-Cutting Conventions
sections. Fix stale .claude/patterns/ and .claude/context/ references.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 BOOKMARKS.md | 62 ++++++++++++++++++++++++++++++++++------------------
 CLAUDE.md    |  7 ++++--
 2 files changed, 46 insertions(+), 23 deletions(-)

diff --git a/BOOKMARKS.md b/BOOKMARKS.md
index b5156ce70..d2db657e3 100644
--- a/BOOKMARKS.md
+++ b/BOOKMARKS.md
@@ -4,9 +4,11 @@ Progressive disclosure for task-specific documentation and references.
 
 ## Table of Contents
 
+- [Specs](#specs)
+- [Workflows](#workflows)
+- [Standards](#standards)
 - [Governance](#governance)
 - [Architecture Decisions](#architecture-decisions)
-- [Component Development Guides](#component-development-guides)
 - [Component Guides](#component-guides)
 - [Development Environment](#development-environment)
 - [Testing](#testing)
@@ -17,6 +19,44 @@ Progressive disclosure for task-specific documentation and references.
 
 ---
 
+## Specs
+
+Desired state of the system, organized by capability domain.
+
+| Spec | Domain | Purpose |
+|------|--------|---------|
+| [Ambient Data Model](specs/sessions/ambient-model.spec.md) | sessions | Platform-wide data model: projects, agents, sessions, credentials, RBAC |
+| [Control Plane](specs/control-plane/control-plane.spec.md) | control-plane | CP architecture, runner structure, K8s provisioning |
+| [Runner](specs/agents/runner.spec.md) | agents | Runner subprocess lifecycle, bridges, gRPC/HTTP endpoints |
+| [MCP Server](specs/integrations/mcp-server.spec.md) | integrations | MCP tool definitions, sidecar and public endpoint modes |
+
+Feature specs remain in numbered directories under `specs/` (e.g., `specs/001-*/spec.md`).
+
+## Workflows
+
+Agent-consumable procedures — step-by-step implementation workflows.
+
+| Workflow | Domain | Purpose |
+|----------|--------|---------|
+| [Ambient Model](workflows/sessions/ambient-model.workflow.md) | sessions | Spec-driven implementation pipeline for data model changes |
+| [Control Plane](workflows/control-plane/control-plane.workflow.md) | control-plane | CP + Runner implementation workflow |
+| [MCP Server](workflows/integrations/mcp-server.workflow.md) | integrations | MCP server implementation workflow |
+
+## Standards
+
+Component-specific conventions loaded by review agents on demand.
+
+| Standard | Domain | Scope |
+|----------|--------|-------|
+| [Backend Conventions](specs/standards/backend/conventions.spec.md) | backend | Go patterns, K8s integration, handler conventions, user-scoped clients |
+| [Backend Error Handling](specs/standards/backend/error-handling.spec.md) | backend | Consistent error patterns across backend and operator |
+| [Backend K8s Client](specs/standards/backend/k8s-client.spec.md) | backend | User token vs. service account — critical for RBAC compliance |
+| [Frontend Conventions](specs/standards/frontend/conventions.spec.md) | frontend | NextJS patterns, Shadcn, React Query, component guidelines |
+| [Frontend React Query](specs/standards/frontend/react-query.spec.md) | frontend | Data fetching hooks, mutations, cache invalidation |
+| [Operator Conventions](specs/standards/control-plane/conventions.spec.md) | control-plane | OwnerReferences, reconciliation patterns, SecurityContext, resource limits |
+| [Security Standards](specs/standards/security/security.spec.md) | security | Auth flows, RBAC, token handling, container security |
+| [Cross-Cutting Conventions](specs/standards/platform/cross-cutting.spec.md) | platform | Image consistency, reconciliation, error propagation, namespace-scoped keys |
+
 ## Governance
 
 | Document | Purpose |
@@ -39,26 +79,6 @@ Progressive disclosure for task-specific documentation and references.
 | [ADR-0008](docs/internal/adr/0008-automate-code-reviews.md) | Automated inner-loop code review |
 | [ADR-0009](docs/internal/adr/0009-rest-api-postgresql-trex-foundation.md) | REST API + PostgreSQL via rh-trex-ai |
 
-## Cross-Cutting Conventions
-
-| Document | Purpose |
-|----------|---------|
-| [CodeRabbit-Derived Conventions](specs/standards/platform/cross-cutting.spec.md) | Image consistency, reconciliation patterns, error propagation, namespace-scoped keys, SecurityContext — derived from 971 CodeRabbit review comments |
-
-## Component Development Guides
-
-Convention documentation for each component. Loaded by review agents on demand.
-
-| Guide | Scope |
-|-------|-------|
-| [Backend Conventions](specs/standards/backend/conventions.spec.md) | Go patterns, K8s integration, handler conventions, user-scoped clients |
-| [Backend Error Handling](specs/standards/backend/error-handling.spec.md) | Consistent error patterns across backend and operator |
-| [Backend K8s Client](specs/standards/backend/k8s-client.spec.md) | User token vs. service account — critical for RBAC compliance |
-| [Frontend Conventions](specs/standards/frontend/conventions.spec.md) | NextJS patterns, Shadcn, React Query, component guidelines |
-| [Frontend React Query](specs/standards/frontend/react-query.spec.md) | Data fetching hooks, mutations, cache invalidation |
-| [Operator Conventions](specs/standards/control-plane/conventions.spec.md) | OwnerReferences, reconciliation patterns, SecurityContext, resource limits |
-| [Security Standards](specs/standards/security/security.spec.md) | Auth flows, RBAC, token handling, container security |
-
 ## Component Guides
 
 | Guide | Purpose |
diff --git a/CLAUDE.md b/CLAUDE.md
index 120570576..4c4e4be25 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -18,6 +18,9 @@ Kubernetes-native AI automation platform that orchestrates agentic sessions thro
 - `components/manifests/` - Kustomize-based deployment manifests and overlays
 - `e2e/` - Cypress end-to-end tests
 - `docs/` - Astro Starlight documentation site
+- `specs/` - Desired state of the system ([sessions](specs/sessions/), [agents](specs/agents/), [control-plane](specs/control-plane/), [integrations](specs/integrations/), [standards](specs/standards/))
+- `workflows/` - Agent-consumable procedures ([sessions](workflows/sessions/), [control-plane](workflows/control-plane/), [integrations](workflows/integrations/))
+- `skills/` - [Agent Skills](https://agentskills.io) (`.claude/skills` symlinks here)
 
 ## Key Files
 
@@ -91,7 +94,7 @@ Benchmark notes:
 ## Critical Conventions
 
 Cross-cutting rules that apply across ALL components. Component-specific conventions live in
-component DEVELOPMENT.md files (see [BOOKMARKS.md](BOOKMARKS.md) > Component Development Guides).
+[specs/standards/](specs/standards/) (see [BOOKMARKS.md](BOOKMARKS.md) > Component Standards).
 
 - **User token auth required**: All user-facing API ops use `GetK8sClientsForRequest(c)`, never the backend service account
 - **No tokens in logs/errors/responses**: Use `len(token)` for logging, generic messages to users
@@ -141,7 +144,7 @@ Configured in `.pre-commit-config.yaml`. Install: `make setup-hooks`. Run all: `
 Before running `gh pr create`, agents MUST self-review their changes:
 
 1. Review the diff against conventions in this file and [BOOKMARKS.md](BOOKMARKS.md)
-2. Verify the changes follow patterns documented in `.claude/patterns/` and `.claude/context/`
+2. Verify the changes follow patterns documented in `specs/standards/`
 3. Check that no `panic()` calls exist in production Go code (use `fmt.Errorf`)
 4. Check that no `any` types exist in frontend TypeScript (use proper types, `unknown`, or generics)
 5. Ensure all new API endpoints have corresponding frontend proxy routes

From c4d40fffd5dc1ba7ddd2f132a1e31fdc6fb70eb3 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:50:58 -0400
Subject: [PATCH 07/16] refactor: pivot skills and workflows to .agents/
 directory
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move skills/ and workflows/ under .agents/ to follow the agentskills.io
convention:
- .agents/skills/ — domain-nested storage (sessions/, control-plane/,
  frontend/, integrations/) with cross-cutting skills flat at root
- .agents/workflows/ — domain-nested agent procedures
- .claude/skills symlinks to .agents/skills/ for Claude Code discovery
  (top-level only: cross-cutting skills)
- specs/{domain}/.agents/skills symlinks to .agents/skills/{domain}/
  for domain-scoped skill discovery

Update all references across CLAUDE.md, BOOKMARKS.md, devflow skill,
convention guard, spec files, design docs, and workflow files.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 {skills => .agents/skills}/align/SKILL.md      |  0
 .../skills}/align/evals/evals.json             |  0
 .../skills}/amber-review/SKILL.md              |  0
 .../skills}/amber-review/evals/evals.json      |  0
 .../control-plane/ambient-pr-test/SKILL.md     |  0
 .../skills}/control-plane/ambient/SKILL.md     |  0
 .../control-plane/dev-cluster/README.md        |  0
 .../skills}/control-plane/dev-cluster/SKILL.md |  0
 .../control-plane/dev-cluster/evals/evals.json |  0
 {skills => .agents/skills}/devflow/SKILL.md    | 18 +++++++++---------
 .../skills}/frontend/cypress-demo/SKILL.md     |  0
 .../frontend/cypress-demo/evals/evals.json     |  0
 .../skills}/integrations/grpc-dev/SKILL.md     |  0
 .../skills}/integrations/unleash-flag/SKILL.md |  0
 .../integrations/unleash-flag/evals/evals.json |  0
 {skills => .agents/skills}/memory/SKILL.md     |  0
 .../skills}/memory/evals/evals.json            |  0
 {skills => .agents/skills}/pr-fixer/SKILL.md   |  0
 .../skills}/pr-fixer/evals/evals.json          |  0
 {skills => .agents/skills}/scaffold/SKILL.md   |  0
 .../skills}/scaffold/evals/evals.json          |  0
 .../sessions/ambient-api-server/SKILL.md       |  0
 .../control-plane/control-plane.workflow.md    |  2 +-
 .../integrations/mcp-server.workflow.md        |  2 +-
 .../sessions/ambient-model.workflow.md         |  2 +-
 .claude/skills                                 |  2 +-
 BOOKMARKS.md                                   |  6 +++---
 CLAUDE.md                                      |  4 ++--
 .../manifests/overlays/mpp-openshift/README.md |  2 +-
 docs/internal/design/README.md                 |  8 ++++----
 .../developer/local-development/openshift.md   |  6 +++---
 .../proposals/alpha-to-main-migration.md       |  2 +-
 scripts/claude-hooks/convention-guard.sh       |  2 +-
 specs/control-plane/.agents/skills             |  1 +
 specs/control-plane/control-plane.spec.md      |  2 +-
 specs/integrations/.agents/skills              |  1 +
 specs/integrations/mcp-server.spec.md          |  2 +-
 specs/sessions/.agents/skills                  |  1 +
 specs/sessions/ambient-model.spec.md           |  2 +-
 39 files changed, 34 insertions(+), 31 deletions(-)
 rename {skills => .agents/skills}/align/SKILL.md (100%)
 rename {skills => .agents/skills}/align/evals/evals.json (100%)
 rename {skills => .agents/skills}/amber-review/SKILL.md (100%)
 rename {skills => .agents/skills}/amber-review/evals/evals.json (100%)
 rename {skills => .agents/skills}/control-plane/ambient-pr-test/SKILL.md (100%)
 rename {skills => .agents/skills}/control-plane/ambient/SKILL.md (100%)
 rename {skills => .agents/skills}/control-plane/dev-cluster/README.md (100%)
 rename {skills => .agents/skills}/control-plane/dev-cluster/SKILL.md (100%)
 rename {skills => .agents/skills}/control-plane/dev-cluster/evals/evals.json (100%)
 rename {skills => .agents/skills}/devflow/SKILL.md (93%)
 rename {skills => .agents/skills}/frontend/cypress-demo/SKILL.md (100%)
 rename {skills => .agents/skills}/frontend/cypress-demo/evals/evals.json (100%)
 rename {skills => .agents/skills}/integrations/grpc-dev/SKILL.md (100%)
 rename {skills => .agents/skills}/integrations/unleash-flag/SKILL.md (100%)
 rename {skills => .agents/skills}/integrations/unleash-flag/evals/evals.json (100%)
 rename {skills => .agents/skills}/memory/SKILL.md (100%)
 rename {skills => .agents/skills}/memory/evals/evals.json (100%)
 rename {skills => .agents/skills}/pr-fixer/SKILL.md (100%)
 rename {skills => .agents/skills}/pr-fixer/evals/evals.json (100%)
 rename {skills => .agents/skills}/scaffold/SKILL.md (100%)
 rename {skills => .agents/skills}/scaffold/evals/evals.json (100%)
 rename {skills => .agents/skills}/sessions/ambient-api-server/SKILL.md (100%)
 rename {workflows => .agents/workflows}/control-plane/control-plane.workflow.md (99%)
 rename {workflows => .agents/workflows}/integrations/mcp-server.workflow.md (99%)
 rename {workflows => .agents/workflows}/sessions/ambient-model.workflow.md (99%)
 create mode 120000 specs/control-plane/.agents/skills
 create mode 120000 specs/integrations/.agents/skills
 create mode 120000 specs/sessions/.agents/skills

diff --git a/skills/align/SKILL.md b/.agents/skills/align/SKILL.md
similarity index 100%
rename from skills/align/SKILL.md
rename to .agents/skills/align/SKILL.md
diff --git a/skills/align/evals/evals.json b/.agents/skills/align/evals/evals.json
similarity index 100%
rename from skills/align/evals/evals.json
rename to .agents/skills/align/evals/evals.json
diff --git a/skills/amber-review/SKILL.md b/.agents/skills/amber-review/SKILL.md
similarity index 100%
rename from skills/amber-review/SKILL.md
rename to .agents/skills/amber-review/SKILL.md
diff --git a/skills/amber-review/evals/evals.json b/.agents/skills/amber-review/evals/evals.json
similarity index 100%
rename from skills/amber-review/evals/evals.json
rename to .agents/skills/amber-review/evals/evals.json
diff --git a/skills/control-plane/ambient-pr-test/SKILL.md b/.agents/skills/control-plane/ambient-pr-test/SKILL.md
similarity index 100%
rename from skills/control-plane/ambient-pr-test/SKILL.md
rename to .agents/skills/control-plane/ambient-pr-test/SKILL.md
diff --git a/skills/control-plane/ambient/SKILL.md b/.agents/skills/control-plane/ambient/SKILL.md
similarity index 100%
rename from skills/control-plane/ambient/SKILL.md
rename to .agents/skills/control-plane/ambient/SKILL.md
diff --git a/skills/control-plane/dev-cluster/README.md b/.agents/skills/control-plane/dev-cluster/README.md
similarity index 100%
rename from skills/control-plane/dev-cluster/README.md
rename to .agents/skills/control-plane/dev-cluster/README.md
diff --git a/skills/control-plane/dev-cluster/SKILL.md b/.agents/skills/control-plane/dev-cluster/SKILL.md
similarity index 100%
rename from skills/control-plane/dev-cluster/SKILL.md
rename to .agents/skills/control-plane/dev-cluster/SKILL.md
diff --git a/skills/control-plane/dev-cluster/evals/evals.json b/.agents/skills/control-plane/dev-cluster/evals/evals.json
similarity index 100%
rename from skills/control-plane/dev-cluster/evals/evals.json
rename to .agents/skills/control-plane/dev-cluster/evals/evals.json
diff --git a/skills/devflow/SKILL.md b/.agents/skills/devflow/SKILL.md
similarity index 93%
rename from skills/devflow/SKILL.md
rename to .agents/skills/devflow/SKILL.md
index f2089d1f0..5f8542c23 100644
--- a/skills/devflow/SKILL.md
+++ b/.agents/skills/devflow/SKILL.md
@@ -23,7 +23,7 @@ You are executing the Ambient Code Platform development workflow. This skill is
 
 **Remind the human every 10 turns to re-read this skill.** Context compaction can lose workflow state. At turns 10, 20, 30, etc., say:
 
-> "Reminder: we are on turn N. Re-reading `skills/devflow/SKILL.md` to refresh workflow state."
+> "Reminder: we are on turn N. Re-reading `.agents/skills/devflow/SKILL.md` to refresh workflow state."
 
 Then re-read this file before continuing.
 
@@ -78,7 +78,7 @@ Every component has a spec file. Load the spec for the component being changed:
 
 | Component | Spec | Guide |
 |-----------|------|-------|
-| Data Model / API / CLI / RBAC | `specs/sessions/ambient-model.spec.md` | `workflows/sessions/ambient-model.workflow.md` |
+| Data Model / API / CLI / RBAC | `specs/sessions/ambient-model.spec.md` | `.agents/workflows/sessions/ambient-model.workflow.md` |
 
 ### 2b. Modify the Spec
 
@@ -111,7 +111,7 @@ After spec acceptance (or in parallel for human workflow), load the implementati
 
 | Component | Guide | Context |
 |-----------|-------|---------|
-| Data Model / API | `workflows/sessions/ambient-model.workflow.md` | `specs/standards/backend/conventions.spec.md` |
+| Data Model / API | `.agents/workflows/sessions/ambient-model.workflow.md` | `specs/standards/backend/conventions.spec.md` |
 | SDK | (workflow section in ambient-model.workflow.md Wave 3) | `specs/standards/backend/conventions.spec.md` |
 | CLI | (guide section Wave 5) | `specs/standards/backend/conventions.spec.md` |
 | Control Plane | (guide section Wave 4) | `specs/standards/control-plane/conventions.spec.md` |
@@ -134,7 +134,7 @@ Commits are ordered deliberately:
 
 1. **Self-improvement commit (first).** Any changes to guides, skills, workflows, or this devflow skill. Group all such changes into one commit:
    ```bash
-   git add skills/ workflows/
+   git add .agents/skills/ .agents/workflows/
    git commit -m "chore(skills): self-improvement updates from <context>"
    ```
    - Agentic workflow: this is the first commit on the branch.
@@ -345,17 +345,17 @@ But prefer fixing the lint/format issue instead.
 
 | Skill/Context | When to use |
 |---------------|-------------|
-| `skills/sessions/ambient-api-server/SKILL.md` | Working in `components/ambient-api-server/` |
-| `skills/control-plane/dev-cluster/SKILL.md` | Managing kind clusters for testing |
-| `skills/integrations/grpc-dev/SKILL.md` | gRPC streaming, AG-UI events |
-| `skills/control-plane/ambient-pr-test/SKILL.md` | PR validation on MPP dev cluster |
+| `.agents/skills/sessions/ambient-api-server/SKILL.md` | Working in `components/ambient-api-server/` |
+| `.agents/skills/control-plane/dev-cluster/SKILL.md` | Managing kind clusters for testing |
+| `.agents/skills/integrations/grpc-dev/SKILL.md` | gRPC streaming, AG-UI events |
+| `.agents/skills/control-plane/ambient-pr-test/SKILL.md` | PR validation on MPP dev cluster |
 | `specs/standards/backend/conventions.spec.md` | API server plugin architecture, OpenAPI, testing |
 | `specs/standards/backend/conventions.spec.md` | CLI command patterns |
 | `specs/standards/backend/conventions.spec.md` | SDK generation |
 | `specs/standards/control-plane/conventions.spec.md` | CP fan-out, runner contract |
 | `specs/standards/frontend/conventions.spec.md` | Frontend build, React Query |
 | `specs/sessions/ambient-model.spec.md` | Data model spec (source of truth) |
-| `workflows/sessions/ambient-model.workflow.md` | Implementation workflow (wave-based) |
+| `.agents/workflows/sessions/ambient-model.workflow.md` | Implementation workflow (wave-based) |
 
 ---
 
diff --git a/skills/frontend/cypress-demo/SKILL.md b/.agents/skills/frontend/cypress-demo/SKILL.md
similarity index 100%
rename from skills/frontend/cypress-demo/SKILL.md
rename to .agents/skills/frontend/cypress-demo/SKILL.md
diff --git a/skills/frontend/cypress-demo/evals/evals.json b/.agents/skills/frontend/cypress-demo/evals/evals.json
similarity index 100%
rename from skills/frontend/cypress-demo/evals/evals.json
rename to .agents/skills/frontend/cypress-demo/evals/evals.json
diff --git a/skills/integrations/grpc-dev/SKILL.md b/.agents/skills/integrations/grpc-dev/SKILL.md
similarity index 100%
rename from skills/integrations/grpc-dev/SKILL.md
rename to .agents/skills/integrations/grpc-dev/SKILL.md
diff --git a/skills/integrations/unleash-flag/SKILL.md b/.agents/skills/integrations/unleash-flag/SKILL.md
similarity index 100%
rename from skills/integrations/unleash-flag/SKILL.md
rename to .agents/skills/integrations/unleash-flag/SKILL.md
diff --git a/skills/integrations/unleash-flag/evals/evals.json b/.agents/skills/integrations/unleash-flag/evals/evals.json
similarity index 100%
rename from skills/integrations/unleash-flag/evals/evals.json
rename to .agents/skills/integrations/unleash-flag/evals/evals.json
diff --git a/skills/memory/SKILL.md b/.agents/skills/memory/SKILL.md
similarity index 100%
rename from skills/memory/SKILL.md
rename to .agents/skills/memory/SKILL.md
diff --git a/skills/memory/evals/evals.json b/.agents/skills/memory/evals/evals.json
similarity index 100%
rename from skills/memory/evals/evals.json
rename to .agents/skills/memory/evals/evals.json
diff --git a/skills/pr-fixer/SKILL.md b/.agents/skills/pr-fixer/SKILL.md
similarity index 100%
rename from skills/pr-fixer/SKILL.md
rename to .agents/skills/pr-fixer/SKILL.md
diff --git a/skills/pr-fixer/evals/evals.json b/.agents/skills/pr-fixer/evals/evals.json
similarity index 100%
rename from skills/pr-fixer/evals/evals.json
rename to .agents/skills/pr-fixer/evals/evals.json
diff --git a/skills/scaffold/SKILL.md b/.agents/skills/scaffold/SKILL.md
similarity index 100%
rename from skills/scaffold/SKILL.md
rename to .agents/skills/scaffold/SKILL.md
diff --git a/skills/scaffold/evals/evals.json b/.agents/skills/scaffold/evals/evals.json
similarity index 100%
rename from skills/scaffold/evals/evals.json
rename to .agents/skills/scaffold/evals/evals.json
diff --git a/skills/sessions/ambient-api-server/SKILL.md b/.agents/skills/sessions/ambient-api-server/SKILL.md
similarity index 100%
rename from skills/sessions/ambient-api-server/SKILL.md
rename to .agents/skills/sessions/ambient-api-server/SKILL.md
diff --git a/workflows/control-plane/control-plane.workflow.md b/.agents/workflows/control-plane/control-plane.workflow.md
similarity index 99%
rename from workflows/control-plane/control-plane.workflow.md
rename to .agents/workflows/control-plane/control-plane.workflow.md
index 69cb88fad..bd510e48e 100755
--- a/workflows/control-plane/control-plane.workflow.md
+++ b/.agents/workflows/control-plane/control-plane.workflow.md
@@ -845,7 +845,7 @@ GET /sessions/{id}/events (proxy)            api-server   open
 acpctl session events <id>                   CLI          open
 ```
 
-**Next:** Investigate `WatchSessionMessages` authorization in api-server — check `@skills/sessions/ambient-api-server/` or `components/ambient-api-server/plugins/sessions/` for watch auth logic. The push succeeds with the same token so the issue is specific to the watch handler's authorization check.
+**Next:** Investigate `WatchSessionMessages` authorization in api-server — check `@.agents/skills/sessions/ambient-api-server/` or `components/ambient-api-server/plugins/sessions/` for watch auth logic. The push succeeds with the same token so the issue is specific to the watch handler's authorization check.
 
 ---
 
diff --git a/workflows/integrations/mcp-server.workflow.md b/.agents/workflows/integrations/mcp-server.workflow.md
similarity index 99%
rename from workflows/integrations/mcp-server.workflow.md
rename to .agents/workflows/integrations/mcp-server.workflow.md
index 2bb747b0c..bc95aebab 100644
--- a/workflows/integrations/mcp-server.workflow.md
+++ b/.agents/workflows/integrations/mcp-server.workflow.md
@@ -462,4 +462,4 @@ Lessons learned:
 - Annotation key conventions and fleet state protocol: `docs/internal/proposals/agent-fleet-state-schema.md`
 - Agent visual language (how purple SEND/WAIT blocks map to MCP tools): `docs/internal/proposals/agent-script-visual-language.md`
 - Platform data model: `specs/sessions/ambient-model.spec.md`
-- Component pipeline and wave pattern: `workflows/sessions/ambient-model.workflow.md`
+- Component pipeline and wave pattern: `.agents/workflows/sessions/ambient-model.workflow.md`
diff --git a/workflows/sessions/ambient-model.workflow.md b/.agents/workflows/sessions/ambient-model.workflow.md
similarity index 99%
rename from workflows/sessions/ambient-model.workflow.md
rename to .agents/workflows/sessions/ambient-model.workflow.md
index 7af854715..b3170c9c6 100755
--- a/workflows/sessions/ambient-model.workflow.md
+++ b/.agents/workflows/sessions/ambient-model.workflow.md
@@ -454,7 +454,7 @@ The old Gin/K8s backend (`components/backend/`) is covered by `.claude/context/b
 | Artifact              | Location                                             | Owner             |
 | --------------------- | ---------------------------------------------------- | ----------------- |
 | Spec                  | `specs/sessions/ambient-model.spec.md`               | Human / consensus |
-| This workflow         | `workflows/sessions/ambient-model.workflow.md`       | Updated each run  |
+| This workflow         | `.agents/workflows/sessions/ambient-model.workflow.md` | Updated each run  |
 | OpenAPI spec          | `components/ambient-api-server/openapi/openapi.yaml` | API wave          |
 | Generated SDK         | `components/ambient-sdk/go-sdk/`                     | SDK wave          |
 | Wave PRs              | GitHub, tagged by wave and component                 | Per wave          |
diff --git a/.claude/skills b/.claude/skills
index 42c5394a1..2b7a412b8 120000
--- a/.claude/skills
+++ b/.claude/skills
@@ -1 +1 @@
-../skills
\ No newline at end of file
+../.agents/skills
\ No newline at end of file
diff --git a/BOOKMARKS.md b/BOOKMARKS.md
index d2db657e3..f176ae71b 100644
--- a/BOOKMARKS.md
+++ b/BOOKMARKS.md
@@ -38,9 +38,9 @@ Agent-consumable procedures — step-by-step implementation workflows.
 
 | Workflow | Domain | Purpose |
 |----------|--------|---------|
-| [Ambient Model](workflows/sessions/ambient-model.workflow.md) | sessions | Spec-driven implementation pipeline for data model changes |
-| [Control Plane](workflows/control-plane/control-plane.workflow.md) | control-plane | CP + Runner implementation workflow |
-| [MCP Server](workflows/integrations/mcp-server.workflow.md) | integrations | MCP server implementation workflow |
+| [Ambient Model](.agents/workflows/sessions/ambient-model.workflow.md) | sessions | Spec-driven implementation pipeline for data model changes |
+| [Control Plane](.agents/workflows/control-plane/control-plane.workflow.md) | control-plane | CP + Runner implementation workflow |
+| [MCP Server](.agents/workflows/integrations/mcp-server.workflow.md) | integrations | MCP server implementation workflow |
 
 ## Standards
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 4c4e4be25..6b2365fa2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,8 +19,8 @@ Kubernetes-native AI automation platform that orchestrates agentic sessions thro
 - `e2e/` - Cypress end-to-end tests
 - `docs/` - Astro Starlight documentation site
 - `specs/` - Desired state of the system ([sessions](specs/sessions/), [agents](specs/agents/), [control-plane](specs/control-plane/), [integrations](specs/integrations/), [standards](specs/standards/))
-- `workflows/` - Agent-consumable procedures ([sessions](workflows/sessions/), [control-plane](workflows/control-plane/), [integrations](workflows/integrations/))
-- `skills/` - [Agent Skills](https://agentskills.io) (`.claude/skills` symlinks here)
+- `.agents/workflows/` - Agent-consumable procedures ([sessions](.agents/workflows/sessions/), [control-plane](.agents/workflows/control-plane/), [integrations](.agents/workflows/integrations/))
+- `.agents/skills/` - [Agent Skills](https://agentskills.io) (`.claude/skills` symlinks here; domain symlinks in `specs/{domain}/.agents/skills`)
 
 ## Key Files
 
diff --git a/components/manifests/overlays/mpp-openshift/README.md b/components/manifests/overlays/mpp-openshift/README.md
index 5698f7f51..7dc8e43a4 100644
--- a/components/manifests/overlays/mpp-openshift/README.md
+++ b/components/manifests/overlays/mpp-openshift/README.md
@@ -78,7 +78,7 @@ The api-server must know the static token so it can recognise the runner as a se
 # The token value must match what was set in Step B
 ```
 
-> **Note:** Step C is currently pending implementation — see the open gap `WatchSessionMessages PERMISSION_DENIED` in `workflows/control-plane/control-plane.workflow.md`.
+> **Note:** Step C is currently pending implementation — see the open gap `WatchSessionMessages PERMISSION_DENIED` in `.agents/workflows/control-plane/control-plane.workflow.md`.
 
 ## Files in This Overlay
 
diff --git a/docs/internal/design/README.md b/docs/internal/design/README.md
index 9c6da9c60..0f98df654 100644
--- a/docs/internal/design/README.md
+++ b/docs/internal/design/README.md
@@ -65,9 +65,9 @@ Guides are **living documents**. Every time the workflow runs and something is d
 
 | Guide | Paired spec |
 |---|---|
-| `workflows/sessions/ambient-model.workflow.md` | `specs/sessions/ambient-model.spec.md` |
-| `workflows/control-plane/control-plane.workflow.md` | `specs/control-plane/control-plane.spec.md` |
-| `workflows/integrations/mcp-server.workflow.md` | `specs/integrations/mcp-server.spec.md` |
+| `.agents/workflows/sessions/ambient-model.workflow.md` | `specs/sessions/ambient-model.spec.md` |
+| `.agents/workflows/control-plane/control-plane.workflow.md` | `specs/control-plane/control-plane.spec.md` |
+| `.agents/workflows/integrations/mcp-server.workflow.md` | `specs/integrations/mcp-server.spec.md` |
 
 ### Component context files (`.claude/context/*-development.md`)
 
@@ -134,5 +134,5 @@ Every time the loop stops because something was wrong, the documents get better.
 
 1. This README — the why
 2. `specs/sessions/ambient-model.spec.md` — what the platform is
-3. `workflows/sessions/ambient-model.workflow.md` — how changes are made
+3. `.agents/workflows/sessions/ambient-model.workflow.md` — how changes are made
 4. The context file for the component you are working on
diff --git a/docs/internal/developer/local-development/openshift.md b/docs/internal/developer/local-development/openshift.md
index d24627823..20a4b636d 100644
--- a/docs/internal/developer/local-development/openshift.md
+++ b/docs/internal/developer/local-development/openshift.md
@@ -2,9 +2,9 @@
 
 This guide covers deploying Ambient Code on an OpenShift cluster using the **OpenShift internal image registry**. This is useful when iterating on local builds against a dev cluster without pushing to quay.io.
 
-> **Standard deployment (quay.io images):** See the [Ambient installer skill](../../../../skills/control-plane/ambient/SKILL.md) — it covers secrets, kustomize deploy, rollout verification, and troubleshooting for any OpenShift namespace.
+> **Standard deployment (quay.io images):** See the [Ambient installer skill](../../../../.agents/skills/control-plane/ambient/SKILL.md) — it covers secrets, kustomize deploy, rollout verification, and troubleshooting for any OpenShift namespace.
 
-> **PR test instances:** See the [ambient-pr-test skill](../../../../skills/control-plane/ambient-pr-test/SKILL.md).
+> **PR test instances:** See the [ambient-pr-test skill](../../../../.agents/skills/control-plane/ambient-pr-test/SKILL.md).
 
 ---
 
@@ -109,4 +109,4 @@ Without this, runner pods fail with `ErrImagePull` / `authentication required`.
 
 ## Next Steps
 
-Once deployed, follow the verification and access steps in the [ambient skill](../../../../skills/control-plane/ambient/SKILL.md#step-6-verify-installation).
+Once deployed, follow the verification and access steps in the [ambient skill](../../../../.agents/skills/control-plane/ambient/SKILL.md#step-6-verify-installation).
diff --git a/docs/internal/proposals/alpha-to-main-migration.md b/docs/internal/proposals/alpha-to-main-migration.md
index 48c4766a3..e9343a1b5 100644
--- a/docs/internal/proposals/alpha-to-main-migration.md
+++ b/docs/internal/proposals/alpha-to-main-migration.md
@@ -40,7 +40,7 @@ removes this file.
 
 - [x] Analyze alpha→main delta and component dependencies
 - [x] Write migration plan (`docs/internal/proposals/alpha-to-main-migration.md`)
-- [x] Fix alpha→main branch references in `skills/devflow/SKILL.md`
+- [x] Fix alpha→main branch references in `.agents/skills/devflow/SKILL.md`
 - [x] Merge to main
 
 ### PR 2 — ambient-api-server: OpenAPI Specs, Generated Client, New Kinds ✅ Merged
diff --git a/scripts/claude-hooks/convention-guard.sh b/scripts/claude-hooks/convention-guard.sh
index 0bd9ea77c..efbcf1a48 100755
--- a/scripts/claude-hooks/convention-guard.sh
+++ b/scripts/claude-hooks/convention-guard.sh
@@ -72,7 +72,7 @@ if [[ "$FILE_PATH" == */components/backend/*.go || "$FILE_PATH" == */components/
 fi
 
 # --- Skills: remind about standards ---
-if [[ "$FILE_PATH" == */.claude/skills/* || "$FILE_PATH" == */skills/* ]]; then
+if [[ "$FILE_PATH" == */.claude/skills/* || "$FILE_PATH" == */.agents/skills/* ]]; then
   warn "Follow the Anthropic skill-creator standard. Required: pushy description, under 500 lines, explanation over rigidity, evals in evals/evals.json."
 fi
 
diff --git a/specs/control-plane/.agents/skills b/specs/control-plane/.agents/skills
new file mode 120000
index 000000000..b5950a2ac
--- /dev/null
+++ b/specs/control-plane/.agents/skills
@@ -0,0 +1 @@
+../../../.agents/skills/control-plane
\ No newline at end of file
diff --git a/specs/control-plane/control-plane.spec.md b/specs/control-plane/control-plane.spec.md
index 753fc8cb1..4bf99df7b 100755
--- a/specs/control-plane/control-plane.spec.md
+++ b/specs/control-plane/control-plane.spec.md
@@ -2,7 +2,7 @@
 
 **Date:** 2026-03-22
 **Status:** Living Document — current state documented; proposed changes marked
-**Workflow:** `../../workflows/control-plane/control-plane.workflow.md` — implementation waves, gap table, build commands
+**Workflow:** `../../.agents/workflows/control-plane/control-plane.workflow.md` — implementation waves, gap table, build commands
 
 ---
 
diff --git a/specs/integrations/.agents/skills b/specs/integrations/.agents/skills
new file mode 120000
index 000000000..28fe815fa
--- /dev/null
+++ b/specs/integrations/.agents/skills
@@ -0,0 +1 @@
+../../../.agents/skills/integrations
\ No newline at end of file
diff --git a/specs/integrations/mcp-server.spec.md b/specs/integrations/mcp-server.spec.md
index 47b7d53be..32b96d22c 100644
--- a/specs/integrations/mcp-server.spec.md
+++ b/specs/integrations/mcp-server.spec.md
@@ -2,7 +2,7 @@
 
 **Date:** 2026-03-22
 **Status:** Design
-**Workflow:** `../../workflows/integrations/mcp-server.workflow.md` — implementation waves, gap table, build commands, run log
+**Workflow:** `../../.agents/workflows/integrations/mcp-server.workflow.md` — implementation waves, gap table, build commands, run log
 
 ---
 
diff --git a/specs/sessions/.agents/skills b/specs/sessions/.agents/skills
new file mode 120000
index 000000000..7909405ca
--- /dev/null
+++ b/specs/sessions/.agents/skills
@@ -0,0 +1 @@
+../../../.agents/skills/sessions
\ No newline at end of file
diff --git a/specs/sessions/ambient-model.spec.md b/specs/sessions/ambient-model.spec.md
index b17f6a003..178998a46 100755
--- a/specs/sessions/ambient-model.spec.md
+++ b/specs/sessions/ambient-model.spec.md
@@ -3,7 +3,7 @@
 **Date:** 2026-03-20
 **Status:** Proposed — Pending Consensus
 **Last Updated:** 2026-04-28 — added `ScheduledSession` Kind; added session operational sub-resources (workspace, files, git, repos, tasks, runner protocol); added generic proxy surface for backend passthrough; updated coverage matrix: all ScheduledSession commands implemented; session sub-resources (workspace/files/git/repos/operational/runner protocol) implemented in API server; generic proxy plugin implemented
-**Workflow:** `../../workflows/sessions/ambient-model.workflow.md` — implementation waves, gap table, build commands, run log
+**Workflow:** `../../.agents/workflows/sessions/ambient-model.workflow.md` — implementation waves, gap table, build commands, run log
 **Design:** `credentials-session.md` — full Credential Kind design spec and rationale
 
 ---

From f4bc437f3b53c4b2b09487e7bf1af7425e925f7c Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 15:57:39 -0400
Subject: [PATCH 08/16] chore: add .claude/skills symlinks in spec domain
 directories

Add .claude/skills symlinks alongside .agents/skills in each spec
domain directory so Claude Code discovers domain-specific skills
when working within a domain context.

Chain: specs/{domain}/.claude/skills -> ../.agents/skills ->
       ../../../.agents/skills/{domain}

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 specs/control-plane/.claude/skills | 1 +
 specs/integrations/.claude/skills  | 1 +
 specs/sessions/.claude/skills      | 1 +
 3 files changed, 3 insertions(+)
 create mode 120000 specs/control-plane/.claude/skills
 create mode 120000 specs/integrations/.claude/skills
 create mode 120000 specs/sessions/.claude/skills

diff --git a/specs/control-plane/.claude/skills b/specs/control-plane/.claude/skills
new file mode 120000
index 000000000..2b7a412b8
--- /dev/null
+++ b/specs/control-plane/.claude/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/specs/integrations/.claude/skills b/specs/integrations/.claude/skills
new file mode 120000
index 000000000..2b7a412b8
--- /dev/null
+++ b/specs/integrations/.claude/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/specs/sessions/.claude/skills b/specs/sessions/.claude/skills
new file mode 120000
index 000000000..2b7a412b8
--- /dev/null
+++ b/specs/sessions/.claude/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file

From 5402034a2d836b8dfc265eb06c0e00d435e269b0 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:03:45 -0400
Subject: [PATCH 09/16] feat: add discover skill for domain context discovery

Mandatory first step for all coding and spec work. The skill walks
agents through identifying relevant capability domains, cd'ing into
specs/{domain}/ to discover domain-specific skills via .claude/skills
symlinks, loading relevant specs, and checking applicable standards.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .agents/skills/discover/SKILL.md         | 90 ++++++++++++++++++++++++
 .agents/skills/discover/evals/evals.json | 26 +++++++
 2 files changed, 116 insertions(+)
 create mode 100644 .agents/skills/discover/SKILL.md
 create mode 100644 .agents/skills/discover/evals/evals.json

diff --git a/.agents/skills/discover/SKILL.md b/.agents/skills/discover/SKILL.md
new file mode 100644
index 000000000..ca87bacae
--- /dev/null
+++ b/.agents/skills/discover/SKILL.md
@@ -0,0 +1,90 @@
+---
+name: discover
+description: >
+  Discover domain-specific skills and context before starting any coding or
+  spec work. This is the mandatory first step for every task — no matter how
+  trivial. Triggers on: any code change, spec change, implementation task,
+  bug fix, refactor, feature work, or documentation update that touches
+  component code or specs.
+---
+
+# Discover Domain Skills
+
+Before writing or changing anything, discover what skills and context are available for the domains you're about to work in.
+
+## When to Use
+
+Every time. This skill is the entry point for all coding and spec work. Do not skip it, even for one-line fixes.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+If provided, use the input to narrow which domains to check. Otherwise, infer from the task context.
+
+## Steps
+
+### 1. Identify Relevant Domains
+
+Map the work to one or more capability domains:
+
+| Domain | When working on |
+|--------|----------------|
+| `sessions` | Session lifecycle, data model, API resources, messages, events |
+| `control-plane` | Operator, reconciliation, scheduling, runner provisioning |
+| `agents` | Agent model, runner, runtime registry, prompts |
+| `integrations` | MCP server, Gerrit, external services, feature flags |
+| `frontend` | UI components, pages, React Query hooks |
+| `auth` | OAuth, credentials, RBAC, tokens |
+| `projects` | Project management, settings, workspaces |
+| `cli` | TUI, acpctl commands |
+
+If unsure, check which `specs/` subdirectories exist:
+
+```bash
+ls -d specs/*/
+```
+
+### 2. Visit Each Domain
+
+For every relevant domain, `cd` into its spec directory and list available skills:
+
+```bash
+cd specs/{domain}
+ls .claude/skills/ 2>/dev/null
+ls .agents/skills/ 2>/dev/null
+```
+
+Read the SKILL.md of any discovered skill that looks relevant to the task at hand.
+
+### 3. Load Domain Specs
+
+While in the domain directory, check for specs that describe the desired state of what you're about to change:
+
+```bash
+ls *.spec.md 2>/dev/null
+```
+
+Read the relevant spec before implementing — code reconciles against specs, not the other way around.
+
+### 4. Check Standards
+
+Load the standards for the component you're modifying:
+
+```bash
+ls specs/standards/*/
+```
+
+Pick the relevant domain (backend, frontend, control-plane, security, platform).
+
+### 5. Report and Proceed
+
+Summarize what you found:
+- Which domains are involved
+- Which domain skills were discovered (if any)
+- Which specs describe the area being changed
+- Which standards apply
+
+Then proceed with the task, using the discovered skills and context.
diff --git a/.agents/skills/discover/evals/evals.json b/.agents/skills/discover/evals/evals.json
new file mode 100644
index 000000000..bf93094a8
--- /dev/null
+++ b/.agents/skills/discover/evals/evals.json
@@ -0,0 +1,26 @@
+[
+  {
+    "input": "/discover",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "discover" },
+    "description": "Direct slash command to discover domain skills"
+  },
+  {
+    "input": "I need to fix a bug in the session status handling",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "discover" },
+    "description": "Implementation task should trigger domain discovery first"
+  },
+  {
+    "input": "update the runner spec to add a new field",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "discover" },
+    "description": "Spec change should trigger domain discovery first"
+  },
+  {
+    "input": "/discover sessions control-plane",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "discover", "args": "sessions control-plane" },
+    "description": "Explicit multi-domain discovery"
+  }
+]

From bb4d448e8159222e6fd418924d3bad10e534d64a Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:17:09 -0400
Subject: [PATCH 10/16] docs: add specs/index.spec.md defining spec ethos and
 format

Establishes the principles, format, and organization conventions for
specs: desired state (not issue tracking), living documents (amended or
deleted, never archived), behavior contracts with RFC 2119 keywords,
and Given/When/Then scenarios.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 specs/index.spec.md | 87 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 specs/index.spec.md

diff --git a/specs/index.spec.md b/specs/index.spec.md
new file mode 100644
index 000000000..cd0e298f1
--- /dev/null
+++ b/specs/index.spec.md
@@ -0,0 +1,87 @@
+# Specs
+
+Specs describe the **desired state** of the system. Code is the actual state. Development work reconciles the two.
+
+## Principles
+
+1. **Desired state, not issue tracking.** A spec says "the system SHALL do X" — not "here's a bug, here's my proposed fix." If the system doesn't match the spec, the code is wrong.
+
+2. **Living documents.** Specs are never archived or superseded. They are amended, replaced, or deleted. A spec that no longer reflects desired behavior is removed, not moved to a graveyard.
+
+3. **Behavior contracts, not implementation plans.** Specs describe observable behavior — inputs, outputs, error conditions, constraints. Implementation details (class names, library choices, execution plans) belong in `.agents/workflows/`.
+
+4. **Organized by capability domain.** Add domains when existing ones become too broad, not preemptively.
+
+5. **Named descriptively.** Filenames follow `<descriptive-title>.spec.md`. Specs exceeding ~300 words or covering multiple distinct topics should be split into files within a containing directory.
+
+## Format
+
+Specs contain requirements, and each requirement has scenarios.
+
+```markdown
+# <Domain> Specification
+
+## Purpose
+High-level description of this spec's domain.
+
+## Requirements
+
+### Requirement: <Name>
+The system SHALL <observable behavior>.
+
+#### Scenario: <Name>
+- GIVEN <precondition>
+- WHEN <action>
+- THEN <expected outcome>
+- AND <additional outcome>
+```
+
+### Elements
+
+| Element | Purpose |
+|---------|---------|
+| `## Purpose` | High-level description of the spec's domain |
+| `### Requirement:` | A specific behavior the system must have |
+| `#### Scenario:` | A concrete example of the requirement in action |
+| `SHALL` / `MUST` | Absolute requirement (RFC 2119) |
+| `SHOULD` | Recommended, but exceptions exist |
+| `MAY` | Optional |
+
+### What belongs in a spec
+
+- Observable behavior users or downstream systems rely on
+- Inputs, outputs, and error conditions
+- External constraints (security, privacy, reliability, compatibility)
+- Scenarios that can be tested or explicitly validated
+
+### What does not belong in a spec
+
+- Internal class/function names
+- Library or framework choices
+- Step-by-step implementation details
+- Execution plans (those belong in `.agents/workflows/`)
+
+**Quick test:** if the implementation can change without changing externally visible behavior, it does not belong in the spec.
+
+## Directory Structure
+
+```
+specs/
+  index.spec.md                    # This file
+  {capability-domain}/             # One directory per domain
+    *.spec.md                      # Domain specs
+    .agents/skills -> symlink      # Domain-specific skills
+    .claude/skills -> symlink      # Claude Code discovery
+  standards/                       # Cross-cutting engineering constraints
+    {domain}/*.spec.md
+```
+
+### Current Domains
+
+| Domain | Covers |
+|--------|--------|
+| `sessions/` | Lifecycle, initialization, status, messages, events, data model |
+| `agents/` | Agent model, runtime registry, prompts, runners |
+| `control-plane/` | Reconciliation, operator, scheduling |
+| `integrations/` | MCP, Gerrit, external services |
+| `standards/` | Cross-cutting engineering constraints by component |

From 01ff42079566356cc6ee2fca93d16536fc483a4a Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:22:10 -0400
Subject: [PATCH 11/16] feat: add spec skill for writing and modifying specs

Guides agents through creating specs that follow the project's format
and conventions. Requires reading specs/index.spec.md before proceeding,
enforces behavior-contract focus over implementation details, and walks
through domain identification, context discovery, and RFC 2119 usage.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .agents/skills/spec/SKILL.md         | 83 ++++++++++++++++++++++++++++
 .agents/skills/spec/evals/evals.json | 26 +++++++++
 2 files changed, 109 insertions(+)
 create mode 100644 .agents/skills/spec/SKILL.md
 create mode 100644 .agents/skills/spec/evals/evals.json

diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md
new file mode 100644
index 000000000..171f117a7
--- /dev/null
+++ b/.agents/skills/spec/SKILL.md
@@ -0,0 +1,83 @@
+---
+name: spec
+description: >
+  Create or modify a spec following the project's spec format and conventions.
+  Use when the user wants to write a new spec, add requirements or scenarios
+  to an existing spec, or restructure spec content. Triggers on: "write a spec",
+  "create a spec", "add a requirement", "spec this out", "define the behavior",
+  "what should the spec look like", "new spec for", "update the spec".
+---
+
+# Write or Modify a Spec
+
+Help the user create or change a spec that describes desired system behavior.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Before Anything Else
+
+Read `specs/index.spec.md` in full. It defines what a spec is, the required format, naming conventions, and what does and does not belong. Do not proceed until you have read it.
+
+## Steps
+
+### 1. Understand the Desired Behavior
+
+Ask the user what behavior they want to describe. Focus on:
+- What should the system do? (not how it should be built)
+- Who or what observes this behavior? (user, API consumer, downstream system)
+- What are the constraints? (security, performance, compatibility)
+
+If the user describes implementation details (class names, library choices, execution steps), redirect: those belong in `.agents/workflows/`, not in a spec.
+
+### 2. Identify the Domain
+
+Determine which capability domain this spec belongs to:
+
+```bash
+ls -d specs/*/
+```
+
+If no existing domain fits, propose a new one — but only if existing domains are genuinely too broad.
+
+### 3. Discover Domain Context
+
+`cd` into the target domain and check for existing specs and skills:
+
+```bash
+cd specs/{domain}
+ls *.spec.md 2>/dev/null
+ls .claude/skills/ 2>/dev/null
+```
+
+Read any existing specs in the domain to understand what's already covered and avoid duplication.
+
+### 4. Write the Spec
+
+Follow the format from `specs/index.spec.md`:
+
+- **Purpose section** — one paragraph describing the domain or feature
+- **Requirements** — each states an observable behavior using RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
+- **Scenarios** — concrete Given/When/Then examples for each requirement that could be turned into tests
+
+Quick checks before writing:
+- Every requirement describes externally observable behavior
+- Every scenario is testable
+- No implementation details leaked in (class names, frameworks, step-by-step plans)
+- RFC 2119 keywords are used deliberately, not decoratively
+
+### 5. Name and Place the File
+
+- Filename: `<descriptive-title>.spec.md`
+- If the spec exceeds ~300 words or covers multiple distinct topics, split into a directory with multiple files
+- Place in `specs/{domain}/`
+
+### 6. Review with the User
+
+Present the spec and ask:
+- Does this capture the desired behavior?
+- Are any scenarios missing (edge cases, error conditions)?
+- Is the requirement strength right (MUST vs SHOULD vs MAY)?
diff --git a/.agents/skills/spec/evals/evals.json b/.agents/skills/spec/evals/evals.json
new file mode 100644
index 000000000..f37e177fd
--- /dev/null
+++ b/.agents/skills/spec/evals/evals.json
@@ -0,0 +1,26 @@
+[
+  {
+    "input": "/spec",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "spec" },
+    "description": "Direct slash command to create a spec"
+  },
+  {
+    "input": "write a spec for session timeout behavior",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "spec" },
+    "description": "Natural language request to create a spec"
+  },
+  {
+    "input": "spec this out: MCP server should retry on transient errors",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "spec" },
+    "description": "Shorthand spec request with behavior description"
+  },
+  {
+    "input": "add a requirement to the runner spec for graceful shutdown",
+    "expected_tool_call": "Skill",
+    "expected_args": { "skill": "spec" },
+    "description": "Modify an existing spec with a new requirement"
+  }
+]

From dcd36d25f9cdf6d347db692338cffc30a8384092 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:24:04 -0400
Subject: [PATCH 12/16] chore: refine discover skill and index.spec.md

Add brevity instruction to discover skill output. Clarify that
implementation invariants (not plans) may appear in specs, and remove
redundant "execution plans" bullet from the avoid list.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .agents/skills/discover/SKILL.md | 4 ++++
 specs/index.spec.md              | 3 +--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/discover/SKILL.md b/.agents/skills/discover/SKILL.md
index ca87bacae..5fbc22d6c 100644
--- a/.agents/skills/discover/SKILL.md
+++ b/.agents/skills/discover/SKILL.md
@@ -40,6 +40,7 @@ Map the work to one or more capability domains:
 | `auth` | OAuth, credentials, RBAC, tokens |
 | `projects` | Project management, settings, workspaces |
 | `cli` | TUI, acpctl commands |
+| `specs` | specs |
 
 If unsure, check which `specs/` subdirectories exist:
 
@@ -87,4 +88,7 @@ Summarize what you found:
 - Which specs describe the area being changed
 - Which standards apply
 
+Do not output irrelivant context. Be extremely brief, like:
+> I will use skills `x` and `y` for this task.
+
 Then proceed with the task, using the discovered skills and context.
diff --git a/specs/index.spec.md b/specs/index.spec.md
index cd0e298f1..b85561f58 100644
--- a/specs/index.spec.md
+++ b/specs/index.spec.md
@@ -8,7 +8,7 @@ Specs describe the **desired state** of the system. Code is the actual state. De
 
 2. **Living documents.** Specs are never archived or superseded. They are amended, replaced, or deleted. A spec that no longer reflects desired behavior is removed, not moved to a graveyard.
 
-3. **Behavior contracts, not implementation plans.** Specs describe observable behavior — inputs, outputs, error conditions, constraints. Implementation details (class names, library choices, execution plans) belong in `.agents/workflows/`.
+3. **Behavior contracts, not implementation plans.** Specs describe observable behavior — inputs, outputs, error conditions, constraints. Implementation invariants, such as library choices, etc. (NOTE: NOT IMPLEMENTATION PLANS. THIS IS A DEVELOPMENT CONCERN.) belong in `.agents/workflows/`.
 
 4. **Organized by capability domain.** Add domains when existing ones become too broad, not preemptively.
 
@@ -59,7 +59,6 @@ The system SHALL <observable behavior>.
 - Internal class/function names
 - Library or framework choices
 - Step-by-step implementation details
-- Execution plans (those belong in `.agents/workflows/`)
 
 **Quick test:** if the implementation can change without changing externally visible behavior, it does not belong in the spec.
 

From 4561a9069c2ccdf57c416cd830ae708c6263bc4e Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:26:13 -0400
Subject: [PATCH 13/16] feat: add spec-change workflow, wire into spec skill

Add .agents/workflows/specs/spec-change.workflow.md defining the full
7-phase spec change process: frame, draft, critic pass, synthesize,
design questions, apply fixes, second critic pass.

Update spec skill to require reading both specs/index.spec.md and the
workflow before proceeding, and restructure steps to follow the
workflow phases.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .agents/skills/spec/SKILL.md                  | 56 +++++++++++-------
 .../workflows/specs/spec-change.workflow.md   | 57 +++++++++++++++++++
 2 files changed, 91 insertions(+), 22 deletions(-)
 create mode 100644 .agents/workflows/specs/spec-change.workflow.md

diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md
index 171f117a7..1f21ad1bd 100644
--- a/.agents/skills/spec/SKILL.md
+++ b/.agents/skills/spec/SKILL.md
@@ -20,20 +20,24 @@ $ARGUMENTS
 
 ## Before Anything Else
 
-Read `specs/index.spec.md` in full. It defines what a spec is, the required format, naming conventions, and what does and does not belong. Do not proceed until you have read it.
+Read these two files in full before proceeding:
+
+1. `specs/index.spec.md` — what a spec is, the required format, naming conventions, and what does and does not belong
+2. `.agents/workflows/specs/spec-change.workflow.md` — the full spec change workflow (framing, drafting, critic passes, synthesis)
 
 ## Steps
 
-### 1. Understand the Desired Behavior
+Follow the phases defined in `.agents/workflows/specs/spec-change.workflow.md`:
+
+### Phase 1 — Frame
 
-Ask the user what behavior they want to describe. Focus on:
-- What should the system do? (not how it should be built)
-- Who or what observes this behavior? (user, API consumer, downstream system)
-- What are the constraints? (security, performance, compatibility)
+Establish the framing before writing anything:
 
-If the user describes implementation details (class names, library choices, execution steps), redirect: those belong in `.agents/workflows/`, not in a spec.
+- **Desired state only.** Ask the user what the system should do, not what's currently broken. If they describe a bug, redirect: "What should the correct behavior be?"
+- **Scope boundary.** Which components does this change touch? (schema, gRPC, runner, operator, CLI, frontend, SDK, RBAC)
+- **Reserved terms check.** Verify no collision with Ambient domain model terms (Inbox, Session, Agent, Project, Credential, SessionMessage, etc.)
 
-### 2. Identify the Domain
+### Phase 2 — Identify Domain and Discover Context
 
 Determine which capability domain this spec belongs to:
 
@@ -41,10 +45,6 @@ Determine which capability domain this spec belongs to:
 ls -d specs/*/
 ```
 
-If no existing domain fits, propose a new one — but only if existing domains are genuinely too broad.
-
-### 3. Discover Domain Context
-
 `cd` into the target domain and check for existing specs and skills:
 
 ```bash
@@ -53,9 +53,9 @@ ls *.spec.md 2>/dev/null
 ls .claude/skills/ 2>/dev/null
 ```
 
-Read any existing specs in the domain to understand what's already covered and avoid duplication.
+Read existing specs in the domain to understand what's already covered and avoid duplication. If no existing domain fits, propose a new one — but only if existing domains are genuinely too broad.
 
-### 4. Write the Spec
+### Phase 3 — Draft the Spec
 
 Follow the format from `specs/index.spec.md`:
 
@@ -63,21 +63,33 @@ Follow the format from `specs/index.spec.md`:
 - **Requirements** — each states an observable behavior using RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
 - **Scenarios** — concrete Given/When/Then examples for each requirement that could be turned into tests
 
+Include: data model, write paths, read paths, RBAC, migration plan for all existing consumers.
+
 Quick checks before writing:
 - Every requirement describes externally observable behavior
 - Every scenario is testable
 - No implementation details leaked in (class names, frameworks, step-by-step plans)
 - RFC 2119 keywords are used deliberately, not decoratively
 
-### 5. Name and Place the File
+### Phase 4 — Critic Pass
+
+Spawn critics in parallel per the workflow. Standard critics (every spec change):
+- Schema / migration
+- RBAC / auth
+- Ambient terminology
+
+Plus scope-driven critics based on the components identified in Phase 1.
+
+### Phase 5 — Synthesize and Present
+
+Separate findings into factual errors (fix directly) and design decisions (present to user). Present design decisions one at a time with 2–3 concrete options and tradeoffs.
+
+### Phase 6 — Apply and Verify
+
+Apply all fixes. Run a second critic pass. Stop when the second pass produces only MINORs.
+
+### Phase 7 — Name and Place the File
 
 - Filename: `<descriptive-title>.spec.md`
 - If the spec exceeds ~300 words or covers multiple distinct topics, split into a directory with multiple files
 - Place in `specs/{domain}/`
-
-### 6. Review with the User
-
-Present the spec and ask:
-- Does this capture the desired behavior?
-- Are any scenarios missing (edge cases, error conditions)?
-- Is the requirement strength right (MUST vs SHOULD vs MAY)?
diff --git a/.agents/workflows/specs/spec-change.workflow.md b/.agents/workflows/specs/spec-change.workflow.md
new file mode 100644
index 000000000..eaf1ddc62
--- /dev/null
+++ b/.agents/workflows/specs/spec-change.workflow.md
@@ -0,0 +1,57 @@
+# Ambient Spec Change Workflow
+
+## Phase 1 — Frame before writing
+
+Before drafting, establish:
+
+- **Desired state only.** The spec describes where things should be, not where they are. Code divergence from the spec is expected and intentional.
+- **Scope boundary.** Which components does this change touch? (schema, gRPC, runner, operator, CLI, frontend, SDK, RBAC) — this drives which critics to spawn.
+- **Reserved terms check.** Ambient has a specific domain model (Inbox, Session, Agent, Project, Credential, SessionMessage, etc.). Don't repurpose these terms.
+
+## Phase 2 — Draft
+
+Write the spec. Include: data model, write paths, read paths, RBAC, migration plan for all existing consumers.
+
+## Phase 3 — Critic pass
+
+Spawn critics in parallel. Critics are always evidence-based (read actual code, cite file:line) and assigned narrow mandates. Two categories of critics:
+
+### Standard critics (every spec change)
+
+- **Schema / migration** — DDL correctness, index semantics, rollback, migration registration
+- **RBAC / auth** — correct mechanism (not aspirational), all endpoints covered
+- **Ambient terminology** — no reserved term collision
+
+### Scope-driven critics (based on Phase 1 scope boundary)
+
+- One critic per major consumer: runner, operator, CLI, frontend, SDK, gRPC proto
+- One critic per major concern in the spec: write paths, read paths, compaction/lifecycle
+
+Each critic reports **BLOCKER** / **MAJOR** / **MINOR** with citations.
+
+## Phase 4 — Synthesize and separate
+
+Collapse duplicates. Split findings:
+
+- **Factual errors** — one right answer (wrong SQL semantics, wrong path, wrong auth mechanism, missing enum value) → fix directly
+- **Design decisions** — valid tradeoffs exist → ask the author
+
+## Phase 5 — Design questions to author
+
+Present only design decisions. For each: 2–3 concrete options with tradeoffs, one question at a time. Do not ask the author to validate factual correctness.
+
+## Phase 6 — Apply fixes
+
+One pass: all factual corrections + design decisions resolved. Commit with a category-per-line message so the diff is auditable.
+
+## Phase 7 — Second critic pass
+
+Run the same critics again against the updated spec. First-round fixes introduce new surface; the second pass catches what the first missed or created. Stop when the second pass produces only MINORs.
+
+## Heuristics
+
+- **Critics should outnumber reviewers.** Ten parallel critics for 45 minutes beats one sequential review over a day.
+- **The author's time is for design decisions only.** Everything with a right answer should never reach them.
+- **"Desired state" framing eliminates the largest class of false positives** (current code ≠ spec). Establish it before the first critic pass, not after.
+- **The Ambient domain model is a minefield of reserved terms.** A dedicated terminology critic is cheaper than discovering the collision during implementation.
+- **Migration path completeness is the most common gap:** for every existing consumer of what you're changing, the spec must say what happens to it.

From 06620ad292d47faab07bd5f281240446e53ef06e Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:26:31 -0400
Subject: [PATCH 14/16] refactor(workflow): specify subagents

---
 .agents/workflows/specs/spec-change.workflow.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.agents/workflows/specs/spec-change.workflow.md b/.agents/workflows/specs/spec-change.workflow.md
index eaf1ddc62..9edd50e9f 100644
--- a/.agents/workflows/specs/spec-change.workflow.md
+++ b/.agents/workflows/specs/spec-change.workflow.md
@@ -14,7 +14,7 @@ Write the spec. Include: data model, write paths, read paths, RBAC, migration pl
 
 ## Phase 3 — Critic pass
 
-Spawn critics in parallel. Critics are always evidence-based (read actual code, cite file:line) and assigned narrow mandates. Two categories of critics:
+Spawn subagents as critics in parallel. Critics are always evidence-based (read actual code, cite file:line) and assigned narrow mandates. Two categories of critics:
 
 ### Standard critics (every spec change)
 

From c396303c1dd7f07f31fe807fe085a7a16e6e4a63 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:32:46 -0400
Subject: [PATCH 15/16] feat: add Phase 2 (ground in codebase) to spec-change
 workflow

Insert a codebase grounding phase between framing and drafting. The
agent reads existing specs and code in affected areas, summarizes its
understanding back to the user in 3-5 sentences, and only asks
questions where the codebase is genuinely ambiguous. Saves the user
from answering things the agent can verify itself.

Renumber subsequent phases (now 8 total). Update spec skill to match.

Part of #1478

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .agents/skills/spec/SKILL.md                  | 43 +++++++------------
 .../workflows/specs/spec-change.workflow.md   | 23 +++++++---
 2 files changed, 32 insertions(+), 34 deletions(-)

diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md
index 1f21ad1bd..787d25fc7 100644
--- a/.agents/skills/spec/SKILL.md
+++ b/.agents/skills/spec/SKILL.md
@@ -23,11 +23,11 @@ $ARGUMENTS
 Read these two files in full before proceeding:
 
 1. `specs/index.spec.md` — what a spec is, the required format, naming conventions, and what does and does not belong
-2. `.agents/workflows/specs/spec-change.workflow.md` — the full spec change workflow (framing, drafting, critic passes, synthesis)
+2. `.agents/workflows/specs/spec-change.workflow.md` — the full spec change workflow (framing, grounding, drafting, critic passes, synthesis)
 
-## Steps
+Then follow the workflow phases in order.
 
-Follow the phases defined in `.agents/workflows/specs/spec-change.workflow.md`:
+## Steps
 
 ### Phase 1 — Frame
 
@@ -37,23 +37,16 @@ Establish the framing before writing anything:
 - **Scope boundary.** Which components does this change touch? (schema, gRPC, runner, operator, CLI, frontend, SDK, RBAC)
 - **Reserved terms check.** Verify no collision with Ambient domain model terms (Inbox, Session, Agent, Project, Credential, SessionMessage, etc.)
 
-### Phase 2 — Identify Domain and Discover Context
+### Phase 2 — Ground in the codebase
 
-Determine which capability domain this spec belongs to:
+Read actual code and existing specs in the affected areas. Confirm your understanding without wasting the user's time:
 
-```bash
-ls -d specs/*/
-```
+- Read existing specs in the target domain
+- Grep the components identified in Phase 1
+- Summarize back in 3–5 sentences: what you found, what you believe they want, what's ambiguous
+- Ask only where the codebase doesn't give a clear answer
 
-`cd` into the target domain and check for existing specs and skills:
-
-```bash
-cd specs/{domain}
-ls *.spec.md 2>/dev/null
-ls .claude/skills/ 2>/dev/null
-```
-
-Read existing specs in the domain to understand what's already covered and avoid duplication. If no existing domain fits, propose a new one — but only if existing domains are genuinely too broad.
+Do not proceed to drafting until the user confirms.
 
 ### Phase 3 — Draft the Spec
 
@@ -65,12 +58,6 @@ Follow the format from `specs/index.spec.md`:
 
 Include: data model, write paths, read paths, RBAC, migration plan for all existing consumers.
 
-Quick checks before writing:
-- Every requirement describes externally observable behavior
-- Every scenario is testable
-- No implementation details leaked in (class names, frameworks, step-by-step plans)
-- RFC 2119 keywords are used deliberately, not decoratively
-
 ### Phase 4 — Critic Pass
 
 Spawn critics in parallel per the workflow. Standard critics (every spec change):
@@ -80,15 +67,15 @@ Spawn critics in parallel per the workflow. Standard critics (every spec change)
 
 Plus scope-driven critics based on the components identified in Phase 1.
 
-### Phase 5 — Synthesize and Present
+### Phase 5–6 — Synthesize and Present
 
-Separate findings into factual errors (fix directly) and design decisions (present to user). Present design decisions one at a time with 2–3 concrete options and tradeoffs.
+Separate findings into factual errors (fix directly) and design decisions (present to user with 2–3 concrete options each, one at a time).
 
-### Phase 6 — Apply and Verify
+### Phase 7 — Apply and Verify
 
-Apply all fixes. Run a second critic pass. Stop when the second pass produces only MINORs.
+Apply all fixes. Run a second critic pass (Phase 8). Stop when only MINORs remain.
 
-### Phase 7 — Name and Place the File
+### Final — Name and Place the File
 
 - Filename: `<descriptive-title>.spec.md`
 - If the spec exceeds ~300 words or covers multiple distinct topics, split into a directory with multiple files
diff --git a/.agents/workflows/specs/spec-change.workflow.md b/.agents/workflows/specs/spec-change.workflow.md
index 9edd50e9f..10bd5ad37 100644
--- a/.agents/workflows/specs/spec-change.workflow.md
+++ b/.agents/workflows/specs/spec-change.workflow.md
@@ -8,11 +8,22 @@ Before drafting, establish:
 - **Scope boundary.** Which components does this change touch? (schema, gRPC, runner, operator, CLI, frontend, SDK, RBAC) — this drives which critics to spawn.
 - **Reserved terms check.** Ambient has a specific domain model (Inbox, Session, Agent, Project, Credential, SessionMessage, etc.). Don't repurpose these terms.
 
-## Phase 2 — Draft
+## Phase 2 — Ground in the codebase
+
+Before drafting, read the actual code and specs in the affected areas. The goal is to confirm your understanding of the user's intent without wasting their time on things you can answer yourself.
+
+1. **Read existing specs** in the target domain — what's already specified? Is this an amendment to an existing spec or a new one?
+2. **Read the current implementation** — grep for the components identified in Phase 1. Understand what exists today so the spec's migration plan is grounded in reality.
+3. **Summarize back to the user** in 3–5 sentences: what you found, what you believe they want to change, and what you're unsure about. Be specific — cite files and current behavior.
+4. **Ask only where the codebase is ambiguous.** If the code answers a question, don't ask the user. If two valid interpretations exist, surface it now — not after a full draft.
+
+Do not proceed to drafting until the user confirms the framing is right.
+
+## Phase 3 — Draft
 
 Write the spec. Include: data model, write paths, read paths, RBAC, migration plan for all existing consumers.
 
-## Phase 3 — Critic pass
+## Phase 4 — Critic pass
 
 Spawn subagents as critics in parallel. Critics are always evidence-based (read actual code, cite file:line) and assigned narrow mandates. Two categories of critics:
 
@@ -29,22 +40,22 @@ Spawn subagents as critics in parallel. Critics are always evidence-based (read
 
 Each critic reports **BLOCKER** / **MAJOR** / **MINOR** with citations.
 
-## Phase 4 — Synthesize and separate
+## Phase 5 — Synthesize and separate
 
 Collapse duplicates. Split findings:
 
 - **Factual errors** — one right answer (wrong SQL semantics, wrong path, wrong auth mechanism, missing enum value) → fix directly
 - **Design decisions** — valid tradeoffs exist → ask the author
 
-## Phase 5 — Design questions to author
+## Phase 6 — Design questions to author
 
 Present only design decisions. For each: 2–3 concrete options with tradeoffs, one question at a time. Do not ask the author to validate factual correctness.
 
-## Phase 6 — Apply fixes
+## Phase 7 — Apply fixes
 
 One pass: all factual corrections + design decisions resolved. Commit with a category-per-line message so the diff is auditable.
 
-## Phase 7 — Second critic pass
+## Phase 8 — Second critic pass
 
 Run the same critics again against the updated spec. First-round fixes introduce new surface; the second pass catches what the first missed or created. Stop when the second pass produces only MINORs.
 

From 23ce45a1cd981155062cecccb1153e1a3f2272f0 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Thu, 30 Apr 2026 16:37:05 -0400
Subject: [PATCH 16/16] refactor: spelling

---
 .agents/skills/discover/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.agents/skills/discover/SKILL.md b/.agents/skills/discover/SKILL.md
index 5fbc22d6c..43dc22fd8 100644
--- a/.agents/skills/discover/SKILL.md
+++ b/.agents/skills/discover/SKILL.md
@@ -88,7 +88,7 @@ Summarize what you found:
 - Which specs describe the area being changed
 - Which standards apply
 
-Do not output irrelivant context. Be extremely brief, like:
+Do not output irrelevant context. Be extremely brief, like:
 > I will use skills `x` and `y` for this task.
 
 Then proceed with the task, using the discovered skills and context.