// End-to-end development workflow for the Ambient Code Platform. Covers ticket → branch → spec → code → commit → PR → review → deploy → verify. Self-improving: update this skill whenever a failure path is discovered or a shortcut is validated. Git history is the audit trail.
| name | devflow |
| description | End-to-end development workflow for the Ambient Code Platform. Covers ticket → branch → spec → code → commit → PR → review → deploy → verify. Self-improving: update this skill whenever a failure path is discovered or a shortcut is validated. Git history is the audit trail. |
You are executing the Ambient Code Platform development workflow. This skill is the literal sequence of steps performed every time code is changed — from filing a ticket to verifying a deployment.
Self-improving skill. Whenever you discover something that doesn't work, or discover something that does, update this file immediately before moving on. The next invocation of this skill benefits from every correction. Examples of self-improvement triggers:
- A build command fails and you find the right flags → add them here
- A test requires an env var you didn't know about → add it here
- A path you tried is a dead end → document the dead end and the correct path
- A review comment reveals a missing step → add the step here
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.mdto refresh workflow state."
Then re-read this file before continuing.
1. Ticket (optional)
2. Branch (from ticket name if available)
3. Spec change (load + modify the component's .spec.md)
4. Commit spec → push → PR against `main`
5. Review (agentic: thorough PR review; human: desired but optional)
6. On spec acceptance → load the component's .guide.md (the implementation workflow)
7. Branch (from ticket name if available)
8. Commit order:
a. Guide/skill/workflow self-improvement changes (1 commit)
b. Code changes grouped by component
9. Push → PR against `main`
10. Review (human + bot comments; local review too)
11. On merge → await quay.io image
12. Update gitops repository with new image SHA (Skill TBD)
13. After deployment → run tests / e2e suite (TBD)
If there is a Jira or GitHub issue, note the ticket ID. If not, proceed without one.
# With ticket
git checkout -b <ticket-id>/<short-description>
# Without ticket
git checkout -b <type>/<short-description>
# type: feat, fix, refactor, docs, chore
Every component has a spec file. Load the spec for the component being changed:
| Component | Spec | Guide |
|---|---|---|
| Data Model / API / CLI / RBAC | specs/api/ambient-model.spec.md | workflows/sessions/ambient-model.workflow.md |
Edit the spec to reflect the desired change. The spec is the source of truth — code is reconciled against it.
git add specs/
git commit -m "spec(<component>): <description of spec change>"
git push origin <branch-name> -u
gh pr create --base main --title "spec(<component>): <description>" --body "Spec change for review."
After spec acceptance (or in parallel for human workflow), load the implementation guide for the component:
| Component | Guide | Context |
|---|---|---|
| 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 |
# If separate from spec branch
git checkout -b <ticket-id>/<short-description>-impl
# Or continue on the same branch (human workflow, spec not yet merged)
Commits are ordered deliberately:
Self-improvement commit (first). Any changes to guides, skills, workflows, or this devflow skill. Group all such changes into one commit:
git add skills/ workflows/
git commit -m "chore(skills): self-improvement updates from <context>"
Code changes, grouped by component:
git add components/ambient-api-server/
git commit -m "feat(api-server): <description>"
git add components/ambient-cli/
git commit -m "feat(cli): <description>"
git add components/ambient-sdk/
git commit -m "feat(sdk): <description>"
git push origin <branch-name> -u
# Agentic: new PR against main
gh pr create --base main --title "feat(<component>): <description>" --body "Implementation of <spec change>."
# Human: push adds to existing PR, or create new PR
After merge to main, images are built and pushed to quay.io/ambient_code/. Watch for the image:
# Check if image exists for a given SHA
skopeo inspect docker://quay.io/ambient_code/vteam_api_server:<sha-or-tag>
Skill TBD. This step will be formalized as experience accumulates.
Get the image SHA from quay.io and update the gitops repository's image references. Due to lack of autodeploy, this is a manual step.
After deployment, run all available tests. E2E test suite TBD.
components/ambient-api-server/)cd components/ambient-api-server
# CRITICAL: podman, not docker. And RYUK must be disabled.
systemctl --user start podman.socket
export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
export TESTCONTAINERS_RYUK_DISABLED=true
make generate # after openapi changes
make proto # after .proto changes
make binary # compile
make test # integration tests (testcontainer Postgres)
go fmt ./...
go vet ./...
golangci-lint run
components/ambient-cli/)cd components/ambient-cli
go build ./...
go fmt ./...
go vet ./...
golangci-lint run
components/ambient-sdk/)cd components/ambient-sdk
make generate # regenerate from openapi
cd go-sdk && go build ./...
components/frontend/)cd components/frontend
npm run build # must pass with 0 errors, 0 warnings
npx vitest run --coverage
components/runners/ambient-runner/)cd components/runners/ambient-runner
uv venv && uv pip install -e .
python -m pytest tests/
components/ambient-control-plane/)cd components/ambient-control-plane
go build ./...
go fmt ./...
go vet ./...
golangci-lint run
This section is the most important part of the skill. Every dead end, every wasted cycle, every "oh, you need to do X first" gets recorded here.
Dead end: Running make test with Docker or without TESTCONTAINERS_RYUK_DISABLED=true.
What happens: Ryuk container tries to connect to /var/run/docker.sock, which doesn't exist on this system. Tests abort before running.
Correct path:
systemctl --user start podman.socket
export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
export TESTCONTAINERS_RYUK_DISABLED=true
make test
Dead end: kind load docker-image fails with podman localhost/ prefix images.
Correct path: Use podman save | ctr import:
CLUSTER=$(podman ps --format '{{.Names}}' | grep 'kind' | grep 'control-plane' | sed 's/-control-plane//')
podman build --no-cache -t localhost/vteam_api_server:latest components/ambient-api-server
podman save localhost/vteam_api_server:latest | \
podman exec -i ${CLUSTER}-control-plane ctr --namespace=k8s.io images import -
kubectl rollout restart deployment/ambient-api-server -n ambient-code
--no-cache Required for Podman BuildsDead end: Building without --no-cache when only Go source changed (go.mod/go.sum unchanged).
What happens: The go build layer hits cache and emits the old binary.
Correct path: Always podman build --no-cache for Go components.
Dead end: Using generated plugin code as-is.
What happens: Generated RegisterRoutes uses auth.JWTMiddleware — wrong.
Correct path: Replace with environments.JWTMiddleware after every generation.
Dead end: Using generated handler code for nested routes without fixing variable names.
What happens: mux.Vars(r)["id"] returns empty string because the route uses {pa_id} or {msg_id}.
Correct path: Fix mux.Vars keys to match actual route variable names after generation.
Dead end: Trying to use do() or doMultiStatus() for SSE endpoints.
What happens: These methods unmarshal and close the response body.
Correct path: Use a.client.httpClient.Do(req) directly and return resp.Body as io.ReadCloser.
Dead end: Adding a new import to CLI code without running go build immediately.
What happens: missing go.sum entry at commit time.
Correct path: Run go build ./... after adding any new import. Fix go.mod before committing.
Dead end: Assuming port 9000 is available locally. What happens: MinIO or another service occupies 9000. gRPC streaming fails silently. Correct path:
kubectl port-forward svc/ambient-api-server 19000:9000 -n ambient-code &
export AMBIENT_GRPC_URL=127.0.0.1:19000
The project uses pre-commit hooks (.pre-commit-config.yaml). If hooks block a commit:
git commit --no-verify # skip pre-commit hooks (use sparingly)
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 |
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/api/ambient-model.spec.md | Data model spec (source of truth) |
workflows/sessions/ambient-model.workflow.md | Implementation workflow (wave-based) |
Record every correction here with a date stamp. This section grows over time.
--no-cache and ctr import workarounds (discovered in ambient-model.workflow.md).Perform any development work on the ambient-ui component. Full workflow instructions.
Deploy a PR's images (api-server, control-plane, runner) to any OpenShift namespace for integration testing. Works on both standard OpenShift clusters and MPP managed clusters. Auto-detects the environment and chooses the right script.
Required context for all frontend work. Loads frontend standards (conventions, React Query patterns, adapter testing requirements) before any code changes. Use when modifying anything under components/frontend/. Triggers on: any frontend code change, UI component work, React Query hooks, API adapter work, frontend bug fix, frontend refactor.
Use when creating or updating Gerrit changes — pushing code for review, amending patch sets, setting reviewers and topics. Triggers on "push to Gerrit", "create a Gerrit change", "upload for review", "update the patch set", "add reviewers to this change".
Use when reviewing a Gerrit change — fetching change details, reading diffs, posting inline comments, and voting with labels. Triggers on "review this Gerrit change", "review change 12345", "look at this Gerrit CL", "code review on Gerrit".
Use when submitting or preparing a Gerrit change for merge — checking submit requirements, rebasing, resolving comments, and submitting. Triggers on "submit this Gerrit change", "merge this CL", "is this change ready to submit", "check submit requirements".