← Lesson 1: The shape of the workflow
Reference · agentpm workflow
The words this repo uses for its own work. Each term gives the meaning and the doc that states it.
| Term | Meaning | Source |
|---|---|---|
| Acceptance criteria | The proof that a story is done. Three are enough: the observable outcome, the negative or safety case, and the recorded evidence. Do not restate a standing gate. | AGENTS.md § Sprint conventions |
| Sprint | One goal. It opens when you plan it. It closes the moment its named proof-of-done ships. A sprint gets no date range and no duration. | AGENTS.md § Sprint conventions |
| Sprint goal | The volatile part of the plan. You rewrite it at every re-scope, so it cannot drift away from the truth on its own. | AGENTS.md § Sprint conventions |
| Story | One unit of work in the hierarchy Epic → Story → Task. Its description holds the stable outcome. A story owns a list of files. | README.md § Phase 1 scope; AGENTS.md § Sprint conventions |
| Term | Meaning | Source |
|---|---|---|
| Browser entrypoint | One of four browser source files: web/src/call.js, chrome.js, setup.js and theme.js. These files collide easily, so they get a special rule. |
AGENTS.md § Invariants |
| Change-set | A group of stories that ship together. It has no story limit. File ownership sets its size. It promises either the SERIAL or the PARALLEL model. | AGENTS.md § How an agent runs |
| File ownership | 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 gets re-cut. | AGENTS.md § How an agent runs |
| Integration story | The one named story in a PARALLEL change-set that merges the branches, gates each merge cheaply, runs the full suite once, and owns the bisect. Only it merges into development. |
AGENTS.md § Where the work happens |
| Main checkout | The shared tree at /root/GitHub/agentpm, with development checked out. A SERIAL change-set works here. A PARALLEL change-set does not share it. |
AGENTS.md § Where the work happens |
| PARALLEL | The exception model, and it needs the owner's word. One agent per worktree, one branch per agent, all cut from the same prefactor commit. It promises green once, at the integration story. A red suite mid-flight is expected. | AGENTS.md § Where the work happens |
| Prefactor story | The first story of a PARALLEL change-set. It lands the shared dependencies and publishes the contracts the other stories code against. All branches cut from its commit. | AGENTS.md § How an agent runs |
| SERIAL | The default model, and what almost every change-set is. All work happens in the main checkout on development. No worktree, no feature branch. It promises green after every story. |
AGENTS.md § Where the work happens |
| Single writer | Only one agent may edit a browser entrypoint at a time. Git once auto-merged two const dv declarations into JavaScript that would not parse, and the board died in production. |
AGENTS.md § Invariants |
| Worktree | A second working tree of the same repo, made with git worktree add, or given by an agent with worktree isolation. It is for PARALLEL work only. Remove it after the merge. |
AGENTS.md § Invariants |
| Term | Meaning | Source |
|---|---|---|
| Dependency budget | The Python runtime keeps six dependencies: mcp, fastapi, uvicorn, asyncpg, pydantic and httpx. A seventh needs the owner's sign-off. Browser libraries are a separate budget. |
CODE_STANDARDS.md § Dependency budget |
Gate / make gates |
The one command that runs every build, test and lint inside Docker. It is the only gate. Run it in the foreground, and run it again on the merged result. | DEV_WORKFLOW.md § 3 |
| Hollow test | A test whose only assertion says a thing is absent, empty or refused. It passes just as well when the feature is completely broken. | CODE_STANDARDS.md § A test must be able to fail |
| Local gates hook | A git hook that fires the gates in the background at git push. Install it once with bash scripts/install_hooks.sh. Treat its banner as a hint only. |
DEV_WORKFLOW.md § 3 |
| Positive control | An assertion in the same test that proves the mechanism works at all. Every negative assertion needs one, before you prove the bad case is excluded. | CODE_STANDARDS.md § A test must be able to fail |
| The ratchet / hollow test baseline | make audit counts the hollow tests and compares the count with scripts/hollow_test_baseline.txt. It fails only when the count goes up. To lower the baseline is progress. To raise it is a decision. |
CODE_STANDARDS.md § A test must be able to fail |
| Term | Meaning | Source |
|---|---|---|
| Changelog fragment | A file changelog.d/<story-id>.<section>.md that a story writes instead of editing CHANGELOG.md. The release commit collects the fragments and deletes them. |
DEV_WORKFLOW.md § 6 |
development |
The branch where stories land. Fetch before you push, and merge if it moved. Never force-push. It reaches main through one pull request. |
AGENTS.md § Where the work happens |
main |
The branch you release from. A commit ships only after it is on main. The owner ships by tagging main after the merge. |
AGENTS.md § Where the work happens; agentpm-release SKILL.md § Steps |
| Merge per story | A story lands on development the moment its own gates pass. Do not bundle branches. A SERIAL change-set also releases per story. A PARALLEL one releases once. |
DEV_WORKFLOW.md, opening; AGENTS.md § Building a sprint |
| Term | Meaning | Source |
|---|---|---|
| Digest pin | The deploy names an image by its digest, not by a tag. A moving image tag never deploys, and an image from a different run never deploys. | agentpm-release SKILL.md § Facts a release depends on |
| Dry run | bash scripts/release.sh <lane> --tag <tag> --dry-run. It prints the lane, the tag, the sha and the version in one line. A version older than the tag means the bump is not on main yet. |
agentpm-release SKILL.md § Steps |
| Lane (fe / be / px) | One service, one image, one version, one tag prefix. fe is the edge with the UI and MCP. be is the IAM-only backend. px is the Bun proxy. No argument ships fe and be, backend first. |
agentpm-release SKILL.md § Lanes |
| Release commit | The commit that sets __version__ in src/pm/__init__.py and adds the matching ## [x.y.z] section to CHANGELOG.md. It must be on main, and it must be the commit you tag. |
agentpm-release SKILL.md § Steps; DEV_WORKFLOW.md § 6 |
| Serving revision | The Cloud Run revision that takes the traffic. It is the traffic entry with percent == 100, never simply the first one. Read it with scripts/verify_serving_revision.py. |
agentpm-release SKILL.md § Facts a release depends on |
| Tag prefix | The letters that put a git tag in a lane: fe-v*, be-v* and px-v*. One tag carries one lane. A tag is immutable, so a wrong tag costs a patch bump. |
agentpm-release SKILL.md § Lanes |
| Term | Meaning | Source |
|---|---|---|
| Existence oracle | A response that tells an attacker a hidden thing exists. Unreadable must look byte-identical to missing: answer 404, never 403, and drop a redacted key instead of setting it to null. |
AGENTS.md § Invariants; CODE_STANDARDS.md § Security shapes |
_vis |
The single visibility predicate, in src/pm/repo.py. Do not copy its logic anywhere else. A copy drifts, and the drift is a security hole. |
CODE_STANDARDS.md § One definition per rule |
Is a word here still unclear? Ask your agent (Claude) to explain it, and to show you the place in the repo where the rule bites.