refactor: unified spec, skills, and workflow organization

.claude/skills/amber-review/SKILL.md → .agents/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
 

.claude/skills/ambient-pr-test/SKILL.md → .agents/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:

.claude/skills/devflow/SKILL.md → .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 `.claude/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 | `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` | `.agents/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,13 +111,13 @@ 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` |
-| 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` |
-| 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 | `.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` |
+| 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
 
@@ -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 .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 |
 |---------------|-------------|
-| `.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 |
-| `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) |
+| `.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) |
+| `.agents/workflows/sessions/ambient-model.workflow.md` | Implementation workflow (wave-based) |
 
 ---
 
@@ -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.

.agents/skills/discover/SKILL.md

@@ -0,0 +1,94 @@
+---
+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 |
+| `specs` | specs |
+
+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
+
+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.

.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"
+  }
+]

.agents/skills/spec/SKILL.md

@@ -0,0 +1,82 @@
+---
+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 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, grounding, drafting, critic passes, synthesis)
+
+Then follow the workflow phases in order.
+
+## Steps
+
+### Phase 1 — Frame
+
+Establish the framing before writing anything:
+
+- **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.)
+
+### Phase 2 — Ground in the codebase
+
+Read actual code and existing specs in the affected areas. Confirm your understanding without wasting the user's time:
+
+- 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
+
+Do not proceed to drafting until the user confirms.
+
+### Phase 3 — Draft 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
+
+Include: data model, write paths, read paths, RBAC, migration plan for all existing consumers.
+
+### 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–6 — Synthesize and Present
+
+Separate findings into factual errors (fix directly) and design decisions (present to user with 2–3 concrete options each, one at a time).
+
+### Phase 7 — Apply and Verify
+
+Apply all fixes. Run a second critic pass (Phase 8). Stop when only MINORs remain.
+
+### 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
+- Place in `specs/{domain}/`

.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"
+  }
+]

docs/internal/design/control-plane.guide.md → .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 `@.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 `@.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.
 
 ---
 

docs/internal/design/mcp-server.guide.md → .agents/workflows/integrations/mcp-server.workflow.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`
+- Platform data model: `specs/sessions/ambient-model.spec.md`
+- Component pipeline and wave pattern: `.agents/workflows/sessions/ambient-model.workflow.md`