Lesson 01 · agentpm workflow

The shape of the workflow

One idea: how a sprint item becomes a live Cloud Run revision — and why merging, gating and releasing are three different acts.

You built this pipeline. You still confuse three of its steps, because most tools glue them together. In agentpm they are separate on purpose. Learn the shape first. The commands come later.

Merging is not gating. Gating is not releasing. Hold that sentence. Everything below hangs on it.

Source: DEV_WORKFLOW.md § intro — "Merging and releasing are two different things."

The pipeline

The agentpm pipeline, from sprint item to Cloud Run A sprint item becomes a change-set. The gates run locally in Docker. Each story merges onto development. One pull request takes development to main. A human tags the commit and runs the release script, which deploys a digest to Cloud Run. sprint item get_active_sprint change-set serial or parallel make gates local, in Docker merge onto development one pull request, not a stream of them pull request development to main git tag fe-v* be-v* px-v* release.sh a person runs it Cloud Run digest pinned merging deploys nothing the only step that deploys

Eight boxes. Draw them from memory before you go on to lesson two.

1 · Work comes from the active sprint

Every item you work must sit in the active sprint. Confirm it first with get_active_sprint and get_sprint. If the item is not there, add it with add_to_sprint, then work it. The scope change is recorded, and that record is the point. The sprint stays an honest account of the work.

Source: AGENTS.md § Sprint scope

2 · Then you cut a change-set

A change-set is the group of stories you build together. It promises one of two models. You must say which one.

Serial — the default

All work happens in the main checkout, with development checked out there. No worktree. No feature branch. Every agent commits to development and pushes it.

Serial promises green after every story. Run the gates between them.

Parallel — you declare it

One agent per worktree, one branch per agent, all cut from the same prefactor commit. Each branch merges into one integration branch. Only the integration story merges that into development.

Parallel promises green once, at the integration story.

Parallel is the exception and it needs your word. If nobody declared one, the change-set is serial.

Source: AGENTS.md § Where the work happens and AGENTS.md § How an agent runs

Size is set by file ownership, not by story count. A change-set has no story limit. Each story owns a list of files. No two lists overlap. No story edits a file it does not own. Two stories that share a file are one story, or one of them is re-cut.

Source: AGENTS.md § How an agent runs; DEV_WORKFLOW.md § 1

Why one writer per file In Sprint 13, five stories touched one browser entrypoint at the same time. Git auto-merged two const dv declarations into JavaScript that would not parse. The board was dead in production for hours while 849 tests passed. Tests do not catch a clean merge of two correct halves. File ownership does. Source: AGENTS.md § Invariants

3 · Gates prove the work

One command runs the gates:

make gates

That is the only gate. It runs every build, test and lint inside Docker, on your own machine. Run it in the foreground and wait for the result. There is no build CI and no deploy CI. Nothing builds on a push, on a pull request or on a tag. One GitHub Actions lint workflow runs on pull requests, and that is all.

Source: DEV_WORKFLOW.md § 3; AGENTS.md § Invariants; README.md § Local development

Gates prove code. They ship nothing.

4 · Merge lands the work

A story lands on development as soon as its own gates pass. That is merge per story. Do not bundle branches and merge them as a block — that is what killed the board. Run make gates again on the merged tree, because two branches that pass alone can still break together.

development reaches main through one pull request.

Source: DEV_WORKFLOW.md § intro and § 5; AGENTS.md § Where the work happens

A merge builds nothing and deploys nothing.

5 · Release is a separate act

A person releases from their own machine. They run scripts/release.sh, and only that run ships. The agentpm-release skill is the runbook.

Source: agentpm-release SKILL.md § Lanes, § Steps and § Facts a release depends on

A serial change-set can release per story. A parallel change-set releases once, after the integration story runs the full suite. No middle state of a parallel change-set is shippable.

Source: AGENTS.md § Building a sprint

Check yourself

What sets the size of a change-set?

Where do the gates run?

What puts new code onto Cloud Run?

What killed the board in Sprint 13?

From memory: name the eight boxes of the pipeline, in order.

sprint item · change-set · make gates · merge onto development · one pull request to main · git tag · scripts/release.sh · Cloud Run.
Six of eight is a good first pass.

Read next

One source, not five Read DEV_WORKFLOW.md in the agentpm repo. It holds the cadence you just learned, in the order you just learned it. About six minutes. Leave AGENTS.md and the release skill for later lessons.
I am your teacher. Ask me about anything here that is not clear. Good questions to bring back: "when is a change-set worth making parallel?" and "what does the integration story actually do?" and "why does the tag not set the version?"

Lesson 2 is not written yet. This is the whole course so far. The terms used above are defined in the glossary.