/devflow

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

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

# 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:

| Component | Spec | Guide | |-----------|------|-------| | Data Model / API / CLI / RBAC | `specs/api/ambient-model.spec.md` | `workflows/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

git add specs/
git commit -m "spec(<component>): <description of spec change>"

2d. Push and Create PR

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:

| 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` |

3b. Create Implementation Branch

# 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:

   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:**

   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

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:

# Check if image exis