Agent skill

Devflow

by ambient-code in ambient-code/platform

End-to-end development workflow for the Ambient Code Platform.

MITAuto-check passedDevelopment

Install Devflow

skills CLI
$ npx skills add ambient-code/platform --skill devflow -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ambient-code/platform devflow --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ambient-code/platform.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/devflow .claude/skills/devflow && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
devflow
GitHub stars
131
Token cost
~3.2k tokens
SKILL.md length
1,008 words
Files
1
Skills in repo
18
Repo updated
First seen
Licence
MIT

At a glance

End-to-end development workflow for the Ambient Code Platform.

  • Works in 5 steps: Ticket & Branch → Spec Change → Implementation → …
  • Tasks that involve Pull requests
  • SKILL.md covers Turn Counter, Workflow Overview, Phase 1: Ticket & Branch and Phase 2: Spec Change, plus 5 more sections
  • Calls git, go and make

What it does

Devflow is an agent skill from ambient-code/platform. 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.

Its SKILL.md is about 3.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Pull requests and Git workflow. The repository describes itself as: Vision/Mission https://ambient-code.ai : Virtual team management and collaboration platform. User guides: https://ambient-code.github.io/platform/. The licence is MIT.

When your agent uses it

  • Tasks that involve Pull requests
  • Tasks that involve Git workflow

Example prompts

  • “/devflow”

Requirements

  • Python 3
  • Node.js
  • Docker

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Ticket & Branch
  2. Spec Change
  3. Implementation
  4. Review
  5. Post-Merge Deployment

What it can do on your machine

Read from SKILL.md and the folder at commit e15afd3. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git
    • go
    • make
    • podman
    • gh
    • uv
    • kubectl
    • npm
    • npx
    • python
    • kind

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, gh, uv, kubectl, npm and npx, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Devflow loads about 3.2k tokens when it runs. Until then it costs about 70 tokens; SKILL.md has 1,008 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~70
When it runs · the whole SKILL.md, loaded when a task matches
~3.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ambient-code/platform at commit e15afd3, republished under its MIT licence (© ambient-code). 1,008 words, ~3,165 tokens.

Download SKILL.mdSave it as .claude/skills/devflow/SKILL.md (or your agent's skills folder).
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.

Devflow Skill

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

Turn Counter

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."

Then re-read this file before continuing.


Workflow Overview

text
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)

Phase 1: Ticket & Branch

1a. File a Ticket (optional)

If there is a Jira or GitHub issue, note the ticket ID. If not, proceed without one.

1b. Create a Branch
bash
# With ticket
git checkout -b <ticket-id>/<short-description>

# Without ticket
git checkout -b <type>/<short-description>
# type: feat, fix, refactor, docs, chore

Phase 2: Spec Change

2a. Load the Spec

Every component has a spec file. Load the spec for the component being changed:

ComponentSpecGuide
Data Model / API / CLI / RBACspecs/api/ambient-model.spec.mdworkflows/sessions/ambient-model.workflow.md
2b. Modify the Spec

Edit the spec to reflect the desired change. The spec is the source of truth — code is reconciled against it.

2c. Commit Spec Change
bash
git add specs/
git commit -m "spec(<component>): <description of spec change>"
2d. Push and Create PR
bash
git push origin <branch-name> -u
gh pr create --base main --title "spec(<component>): <description>" --body "Spec change for review."
  • Agentic workflow: thorough review occurs in the PR. Feedback is incorporated. On approval/merge, the spec change becomes requirements.
  • Human workflow: review is desired but spec commit doesn't need to be merged before code work begins.

Phase 3: Implementation

3a. Load the Guide

After spec acceptance (or in parallel for human workflow), load the implementation guide for the component:

ComponentGuideContext
Data Model / APIworkflows/sessions/ambient-model.workflow.mdspecs/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
bash
# 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)
3c. Commit Order

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 commit -m "chore(skills): self-improvement updates from <context>"
    • Agentic workflow: this is the first commit on the branch.
    • Human workflow: this is the second commit (behind the spec change), or first if spec is on a separate branch.
  2. Code changes, grouped by component:

    bash
    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>"
3d. Push and Create PR
bash
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

Phase 4: Review

  • Human and bot comments on the PR.
  • Conduct local reviews as well.
  • Incorporate feedback → push additional commits.

Phase 5: Post-Merge Deployment

5a. Await Image Build

After merge to main, images are built and pushed to quay.io/ambient_code/. Watch for the image:

bash
# Check if image exists for a given SHA
skopeo inspect docker://quay.io/ambient_code/vteam_api_server:<sha-or-tag>
5b. Update GitOps Repository

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.

5c. Verify Deployment

After deployment, run all available tests. E2E test suite TBD.


Component Build & Test Quick Reference

API Server (components/ambient-api-server/)
bash
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
CLI (components/ambient-cli/)
bash
cd components/ambient-cli
go build ./...
go fmt ./...
go vet ./...
golangci-lint run
SDK (components/ambient-sdk/)
bash
cd components/ambient-sdk
make generate    # regenerate from openapi
cd go-sdk && go build ./...
Frontend (components/frontend/)
bash
cd components/frontend
npm run build    # must pass with 0 errors, 0 warnings
npx vitest run --coverage
Runner (components/runners/ambient-runner/)
bash
cd components/runners/ambient-runner
uv venv && uv pip install -e .
python -m pytest tests/
Control Plane (components/ambient-control-plane/)
bash
cd components/ambient-control-plane
go build ./...
go fmt ./...
go vet ./...
golangci-lint run

Known Pitfalls (Self-Improving Section)

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.

Show full SKILL.md (429 more words)Show less
API Server Tests Require Podman + RYUK Disabled

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:

bash
systemctl --user start podman.socket
export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
export TESTCONTAINERS_RYUK_DISABLED=true
make test
Kind Image Loading with Podman

Dead end: kind load docker-image fails with podman localhost/ prefix images. Correct path: Use podman save | ctr import:

bash
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 Builds

Dead 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.

Generated Code Middleware Import

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.

Nested Route mux.Vars Keys

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.

Go SDK Streaming Endpoints

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.

CLI Dependencies

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.

gRPC Port Conflict

Dead end: Assuming port 9000 is available locally. What happens: MinIO or another service occupies 9000. gRPC streaming fails silently. Correct path:

bash
kubectl port-forward svc/ambient-api-server 19000:9000 -n ambient-code &
export AMBIENT_GRPC_URL=127.0.0.1:19000
Pre-commit Hooks

The project uses pre-commit hooks (.pre-commit-config.yaml). If hooks block a commit:

bash
git commit --no-verify    # skip pre-commit hooks (use sparingly)

But prefer fixing the lint/format issue instead.


Skill/ContextWhen to use
skills/sessions/ambient-api-server/SKILL.mdWorking in components/ambient-api-server/
skills/control-plane/dev-cluster/SKILL.mdManaging kind clusters for testing
skills/integrations/grpc-dev/SKILL.mdgRPC streaming, AG-UI events
skills/control-plane/ambient-pr-test/SKILL.mdPR validation on MPP dev cluster
specs/standards/backend/conventions.spec.mdAPI server plugin architecture, OpenAPI, testing
specs/standards/backend/conventions.spec.mdCLI command patterns
specs/standards/backend/conventions.spec.mdSDK generation
specs/standards/control-plane/conventions.spec.mdCP fan-out, runner contract
specs/standards/frontend/conventions.spec.mdFrontend build, React Query
specs/api/ambient-model.spec.mdData model spec (source of truth)
workflows/sessions/ambient-model.workflow.mdImplementation workflow (wave-based)

Self-Improvement Log

Record every correction here with a date stamp. This section grows over time.

2026-04-10 — Initial creation
  • 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.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.

© ambient-code, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/devflow of ambient-code/platform.

Open the folder on GitHubat commit e15afd3

Compare with similar skills

Devflow next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Devflow compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Devflow this skillambient-code/platform131—~3.2kAutomated safety check: PassMIT
Ansible Backport Creatoransible/ansible71k—~1.2kAutomated safety check: PassGPL-3.0
ZCF Release AutomationUfoMiao/zcf6.1k—~3.4kAutomated safety check: PassMIT
Finishing a Development Branchobra/superpowers296k5 repos~1.9kAutomated safety check: PassMIT
Contributor-First PR MergeHKUDS/OpenHarness16k1 repos~847Automated safety check: PassMIT
Create Pull Requestcline/cline70k1 repos~1.6kAutomated safety check: PassApache-2.0

Similar skills

  • Creates backports of a merged Ansible devel pull request onto the right stable branches by cherry-picking its merge commit onto new backport branches.

    71k GitHub stars~1.2k tokensUpdated today
    DevelopmentAuto-check passed
  • Automates a version release with changesets: analyzes code changes, writes a bilingual CHANGELOG, bumps the version and commits through a release branch and pull request.

    6.1k GitHub stars~3.4k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.

    296k GitHub starsUsed in 5 repos~1.9k tokens
    DevelopmentAuto-check passed
  • Merges external GitHub pull requests while keeping the original author credited, and fixes conflicts after the merge instead of rewriting the contribution.

    16k GitHub starsUsed in 1 repo~847 tokens
    DevelopmentAuto-check passed
  • Opens a GitHub pull request from your current branch with the gh CLI, after reviewing the commits and diff and gathering the details the PR needs.

    70k GitHub starsUsed in 1 repo~1.6k tokens
    DevelopmentAuto-check passed
  • Git Branch Naming

    makeplane/plane

    Names a new Git branch with a type prefix, the lowercased work item ID and a short kebab-case description, so the ID can be extracted later from the branch name.

    60k GitHub stars~594 tokensUpdated yesterday
    DevelopmentAuto-check passed

More from ambient-code/platform

All 18 skills in this repo
  • Align

    ambient-code/platform

    Run a convention alignment check across the codebase to measure adherence to documented standards.

    131 GitHub stars~754 tokensUpdated yesterday
    Auto-check passed
  • Amber Review

    ambient-code/platform

    Perform a comprehensive code review using repository-specific standards.

    131 GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed
  • Cypress Demo

    ambient-code/platform

    Create a Cypress-based video demo for a feature branch with cursor, click effects, and captions.

    131 GitHub stars~879 tokensUpdated yesterday
    Auto-check: notes
  • Deploy

    ambient-code/platform

    Deploy, update manifests, and troubleshoot the ambient-ui component.

    131 GitHub stars~2.6k tokensUpdated yesterday
    Auto-check passed
  • Discover

    ambient-code/platform

    Discover domain-specific skills and context before starting any coding or spec work.

    131 GitHub stars~747 tokensUpdated yesterday
    Auto-check passed
  • Frontend Development

    ambient-code/platform

    Required context for all frontend work. An agent skill from ambient-code/platform.

    131 GitHub stars~525 tokensUpdated yesterday
    Auto-check passed

Questions about Devflow

What does Devflow do?

End-to-end development workflow for the Ambient Code Platform. Devflow is an agent skill from ambient-code/platform. End-to-end development workflow for the Ambient Code Platform.

When should I use Devflow?

Devflow fits situations like: tasks that involve Pull requests; tasks that involve Git workflow.

How do I install Devflow in Claude Code?

Run `npx skills add ambient-code/platform --skill devflow -a claude-code`. Or copy the skill folder (skills/devflow in ambient-code/platform) into .claude/skills/devflow in your project. Claude Code loads it when a task matches its description.

How do I install Devflow in Codex?

Run `npx skills add ambient-code/platform --skill devflow -a codex`. Or copy the skill folder (skills/devflow in ambient-code/platform) into .agents/skills/devflow in your project. Codex loads it when a task matches its description.

Can I use Devflow in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ambient-code/platform --skill devflow -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/devflow, .gemini/skills/devflow, .github/skills/devflow and .opencode/skills/devflow in your project.

What does Devflow need to run?

Going by SKILL.md and its folder, Devflow needs the command-line tools its instructions call (git, go, make, podman, gh and uv). Our summary lists: Python 3; Node.js; Docker.

Does Devflow access the network?

SKILL.md contains no URLs. Its commands use git, gh, uv, npm and npx, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Devflow safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Devflow use?

Devflow is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Devflow use?

About 3.2k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Devflow?

Skills that share tags, products or a category with Devflow: Ansible Backport Creator (ansible/ansible, 71k stars), ZCF Release Automation (UfoMiao/zcf, 6.1k stars), Finishing a Development Branch (obra/superpowers, 296k stars) and Contributor-First PR Merge (HKUDS/OpenHarness, 16k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Devflow?

ambient-code (a GitHub organization) maintains it in ambient-code/platform, which has 131 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on October 6, 2026.

Source: ambient-code/platform on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.