diff --git a/.claude/skills/align/SKILL.md b/.agents/skills/align/SKILL.md similarity index 100% rename from .claude/skills/align/SKILL.md rename to .agents/skills/align/SKILL.md diff --git a/.claude/skills/align/evals/evals.json b/.agents/skills/align/evals/evals.json similarity index 100% rename from .claude/skills/align/evals/evals.json rename to .agents/skills/align/evals/evals.json diff --git a/.claude/skills/amber-review/SKILL.md b/.agents/skills/amber-review/SKILL.md similarity index 89% rename from .claude/skills/amber-review/SKILL.md rename to .agents/skills/amber-review/SKILL.md index fc7882740..cb5223e31 100644 --- a/.claude/skills/amber-review/SKILL.md +++ b/.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 diff --git a/.claude/skills/amber-review/evals/evals.json b/.agents/skills/amber-review/evals/evals.json similarity index 100% rename from .claude/skills/amber-review/evals/evals.json rename to .agents/skills/amber-review/evals/evals.json diff --git a/.claude/skills/ambient-pr-test/SKILL.md b/.agents/skills/control-plane/ambient-pr-test/SKILL.md similarity index 99% rename from .claude/skills/ambient-pr-test/SKILL.md rename to .agents/skills/control-plane/ambient-pr-test/SKILL.md index d44a8408a..7716361e2 100644 --- a/.claude/skills/ambient-pr-test/SKILL.md +++ b/.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: diff --git a/.claude/skills/ambient/SKILL.md b/.agents/skills/control-plane/ambient/SKILL.md similarity index 100% rename from .claude/skills/ambient/SKILL.md rename to .agents/skills/control-plane/ambient/SKILL.md diff --git a/.claude/skills/dev-cluster/README.md b/.agents/skills/control-plane/dev-cluster/README.md similarity index 100% rename from .claude/skills/dev-cluster/README.md rename to .agents/skills/control-plane/dev-cluster/README.md diff --git a/.claude/skills/dev-cluster/SKILL.md b/.agents/skills/control-plane/dev-cluster/SKILL.md similarity index 100% rename from .claude/skills/dev-cluster/SKILL.md rename to .agents/skills/control-plane/dev-cluster/SKILL.md diff --git a/.claude/skills/dev-cluster/evals/evals.json b/.agents/skills/control-plane/dev-cluster/evals/evals.json similarity index 100% rename from .claude/skills/dev-cluster/evals/evals.json rename to .agents/skills/control-plane/dev-cluster/evals/evals.json diff --git a/.claude/skills/devflow/SKILL.md b/.agents/skills/devflow/SKILL.md similarity index 84% rename from .claude/skills/devflow/SKILL.md rename to .agents/skills/devflow/SKILL.md index bef64acde..5f8542c23 100644 --- a/.claude/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 `.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(): " ``` @@ -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 " ``` - 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. diff --git a/.agents/skills/discover/SKILL.md b/.agents/skills/discover/SKILL.md new file mode 100644 index 000000000..43dc22fd8 --- /dev/null +++ b/.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. 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" + } +] diff --git a/.claude/skills/cypress-demo/SKILL.md b/.agents/skills/frontend/cypress-demo/SKILL.md similarity index 100% rename from .claude/skills/cypress-demo/SKILL.md rename to .agents/skills/frontend/cypress-demo/SKILL.md diff --git a/.claude/skills/cypress-demo/evals/evals.json b/.agents/skills/frontend/cypress-demo/evals/evals.json similarity index 100% rename from .claude/skills/cypress-demo/evals/evals.json rename to .agents/skills/frontend/cypress-demo/evals/evals.json diff --git a/.claude/skills/grpc-dev/SKILL.md b/.agents/skills/integrations/grpc-dev/SKILL.md similarity index 100% rename from .claude/skills/grpc-dev/SKILL.md rename to .agents/skills/integrations/grpc-dev/SKILL.md diff --git a/.claude/skills/unleash-flag/SKILL.md b/.agents/skills/integrations/unleash-flag/SKILL.md similarity index 100% rename from .claude/skills/unleash-flag/SKILL.md rename to .agents/skills/integrations/unleash-flag/SKILL.md diff --git a/.claude/skills/unleash-flag/evals/evals.json b/.agents/skills/integrations/unleash-flag/evals/evals.json similarity index 100% rename from .claude/skills/unleash-flag/evals/evals.json rename to .agents/skills/integrations/unleash-flag/evals/evals.json diff --git a/.claude/skills/memory/SKILL.md b/.agents/skills/memory/SKILL.md similarity index 100% rename from .claude/skills/memory/SKILL.md rename to .agents/skills/memory/SKILL.md diff --git a/.claude/skills/memory/evals/evals.json b/.agents/skills/memory/evals/evals.json similarity index 100% rename from .claude/skills/memory/evals/evals.json rename to .agents/skills/memory/evals/evals.json diff --git a/.claude/skills/pr-fixer/SKILL.md b/.agents/skills/pr-fixer/SKILL.md similarity index 100% rename from .claude/skills/pr-fixer/SKILL.md rename to .agents/skills/pr-fixer/SKILL.md diff --git a/.claude/skills/pr-fixer/evals/evals.json b/.agents/skills/pr-fixer/evals/evals.json similarity index 100% rename from .claude/skills/pr-fixer/evals/evals.json rename to .agents/skills/pr-fixer/evals/evals.json diff --git a/.claude/skills/scaffold/SKILL.md b/.agents/skills/scaffold/SKILL.md similarity index 100% rename from .claude/skills/scaffold/SKILL.md rename to .agents/skills/scaffold/SKILL.md diff --git a/.claude/skills/scaffold/evals/evals.json b/.agents/skills/scaffold/evals/evals.json similarity index 100% rename from .claude/skills/scaffold/evals/evals.json rename to .agents/skills/scaffold/evals/evals.json diff --git a/.claude/skills/ambient-api-server/SKILL.md b/.agents/skills/sessions/ambient-api-server/SKILL.md similarity index 100% rename from .claude/skills/ambient-api-server/SKILL.md rename to .agents/skills/sessions/ambient-api-server/SKILL.md diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md new file mode 100644 index 000000000..787d25fc7 --- /dev/null +++ b/.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: `.spec.md` +- If the spec exceeds ~300 words or covers multiple distinct topics, split into a directory with multiple files +- Place in `specs/{domain}/` 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" + } +] diff --git a/docs/internal/design/control-plane.guide.md b/.agents/workflows/control-plane/control-plane.workflow.md similarity index 99% rename from docs/internal/design/control-plane.guide.md rename to .agents/workflows/control-plane/control-plane.workflow.md index 61b0fe58a..bd510e48e 100755 --- a/docs/internal/design/control-plane.guide.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 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. --- diff --git a/docs/internal/design/mcp-server.guide.md b/.agents/workflows/integrations/mcp-server.workflow.md similarity index 98% rename from docs/internal/design/mcp-server.guide.md rename to .agents/workflows/integrations/mcp-server.workflow.md index 501293d35..bc95aebab 100644 --- a/docs/internal/design/mcp-server.guide.md +++ b/.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` diff --git a/docs/internal/design/ambient-model.guide.md b/.agents/workflows/sessions/ambient-model.workflow.md similarity index 99% rename from docs/internal/design/ambient-model.guide.md rename to .agents/workflows/sessions/ambient-model.workflow.md index b4036e50d..b3170c9c6 100755 --- a/docs/internal/design/ambient-model.guide.md +++ b/.agents/workflows/sessions/ambient-model.workflow.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 | `.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/.agents/workflows/specs/spec-change.workflow.md b/.agents/workflows/specs/spec-change.workflow.md new file mode 100644 index 000000000..10bd5ad37 --- /dev/null +++ b/.agents/workflows/specs/spec-change.workflow.md @@ -0,0 +1,68 @@ +# 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 — 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 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: + +### 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 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 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 7 — Apply fixes + +One pass: all factual corrections + design decisions resolved. Commit with a category-per-line message so the diff is auditable. + +## 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. + +## 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. 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 b/.claude/skills new file mode 120000 index 000000000..2b7a412b8 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file diff --git a/BOOKMARKS.md b/BOOKMARKS.md index ed91ee466..f176ae71b 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](.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 + +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](docs/coderabbit-derived-conventions.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 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 | - ## Component Guides | Guide | Purpose | diff --git a/CLAUDE.md b/CLAUDE.md index d1672f5f1..6b2365fa2 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/)) +- `.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 @@ -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 @@ -123,10 +126,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 @@ -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 diff --git a/components/manifests/overlays/mpp-openshift/README.md b/components/manifests/overlays/mpp-openshift/README.md index 08eb914bc..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 `docs/internal/design/control-plane.guide.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 04afb849a..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 | |---|---| -| `ambient-model.guide.md` | `ambient-model.spec.md` | -| `control-plane.guide.md` | `control-plane.spec.md` | -| `mcp-server.guide.md` | `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`) @@ -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. `.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 4834c8421..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](../../../../.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](../../../../.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](../../../../.claude/skills/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](../../../../.claude/skills/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 48a894c4b..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 `.claude/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/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 `