A coding agent finishes the implementation, checks a box, and moves on. The SDK still exposes the old behavior. The documentation describes a default that changed. Another session sees the checked box and assumes the feature shipped. Every individual step looks plausible; the handoffs have lost the meaning of completion.
Our repository workflow makes those handoffs explicit through three skills: /pm-brainstorm proposes work, /pm maintains a Markdown board, and /loop-worker executes a named queue milestone by milestone. The useful design is the contract between them: who can create commitments, what evidence closes them, and what the next session can reconstruct from disk.
1. Give proposal, commitment, and execution separate contracts
The three skills have different responsibilities, even when the same coding agent runs all three. A skill here is a set of repository instructions the agent reads and follows. These boundaries are procedural rules; they do not create operating-system access controls.
| Skill | Reads | Produces | Boundary |
|---|---|---|---|
/pm-brainstorm | Project constraints, current board, completed work | A text proposal with scope, dependencies, and outcomes | Does not write board files |
/pm | Proposal and canonical board conventions | Inbox notes, milestones, tasks, and synchronized status | Owns board mutations |
/loop-worker | One named workstream and its task contracts | Implementation, verification, PM-governed updates, and a ship result | Executes within the selected queue |
Brainstorming starts by reading the PM conventions, repository rules, and an anti-goals file. It also checks the current roadmap and completed milestones. That last step matters: an agent can propose something sensible that already shipped. Historical context helps distinguish a missing capability from a capability whose documentation or implementation needs repair.
The proposal names concrete tasks, rough estimates, dependencies, a definition of done, and the reason to do the work now. It ends with a numbered priority summary and exact PM commands that can materialize the chosen work. A discussion therefore produces a reviewable handoff without immediately expanding the execution queue.
The PM skill owns the canonical hierarchy, templates, sizing rules, and closing tasks. The brainstorming skill reads those conventions at runtime. This avoids maintaining two descriptions of what a milestone means and hoping they remain aligned.
There is a useful connection to Anthropic's distinction between predefined workflows and agents that choose their own tool use. Our system fixes the outer sequence while leaving room for engineering judgment inside a task. That is an architectural interpretation of our workflow, using the vocabulary in Building Effective Agents.
An anti-goals file makes product judgment persistent. In our conventions, speculative work needs a concrete problem, public API changes need an explicit user need, and milestones need an observable outcome. When an agent restarts, it can recover these constraints without reconstructing the entire conversation that produced them.
2. Make the board small enough to read and precise enough to resume
The board lives under .pm/ and uses four levels:
| Level | Example path | Purpose |
|---|---|---|
| Workstream | .pm/w1/ | A general-purpose worker queue |
| Inbox note | .pm/w1/005.md | An idea or roughly sub-hour work |
| Milestone | .pm/w1/m2/ | A shippable outcome taking multiple tasks |
| Task | .pm/w1/m2/t001.md | A bounded implementation or verification step |
Workstreams represent scheduling capacity and history. A queue that handled SDK work last week can handle documentation this week. Placement should consider capacity, dependencies, and likely file collisions; previous assignments do not establish permanent ownership.
The sizing rule keeps administrative overhead proportional to the work. A milestone should exceed roughly an hour and contain multiple tasks. Smaller work stays in a loose inbox note with a brief Why: sentence. These estimates are planning heuristics, not measured guarantees about agent speed.
That distinction prevents a typo fix from acquiring an elaborate milestone structure. It also gives early ideas a place to live before they justify implementation. One consequence deserves attention: the worker loop described here selects milestones. Draining its queue does not automatically execute every loose inbox note.
A milestone must explain its source, project-goal linkage, expected outcome, and why it belongs in the current sequence. These fields answer different questions. “Improve reliability” names an aspiration; “the installed client reports cancellation correctly under the existing command” identifies an outcome a reviewer can observe.
Each task then supplies an objective, context, steps, affected files, acceptance criteria, and explicit exclusions. Its frontmatter records its logical ID, worker, status, estimate, and dependencies. The ID must match its assigned workstream and milestone; archiving preserves that logical identity under a done/ directory.
This is enough context to restart useful work. A new session can read the milestone and open tasks, inspect the named code, and determine which dependency-ready task comes next. It still needs repository exploration, but the decision about what work was intended survives.
Anthropic's long-running agent harness report describes similar restart problems: agents attempted too much at once or declared completion prematurely. Its harness used incremental work, persistent progress artifacts, and verification. It also reported preferring JSON for its feature list because agents were less likely to alter it inappropriately. Markdown offers us convenient review and editing; that convenience does not enforce correctness.
3. Put the work required to finish into the milestone
Consider an illustrative request: make an existing timeout setting behave consistently across a CLI and its TypeScript SDK. The user-visible problem is that the same value produces different behavior depending on the entry point.
A useful milestone could define completion as matching timeout semantics across both surfaces, correct cancellation behavior, updated help and documentation, and passing behavioral checks. Implementation tasks might first reproduce the mismatch, then fix the shared behavior, then update each integration. Dependencies prevent a later task from assuming an interface that has not been established.
The PM skill appends standing closing tasks when it creates the milestone:
- Surface parity, when feature development or a fix touches the public CLI or SDK surface. Check applicable commands, arguments, accepted values, defaults, container behavior, and documentation.
- Simplify. Review the changed code for reuse, unnecessary complexity, and efficiency while preserving behavior.
- Test coverage. Verify meaningful behavior and failure modes rather than inflating a coverage number.
- Closeout. Confirm the definition of done, synchronize status, and archive the completed work.
For a milestone with no public-surface change, the parity task can be omitted, with the reason recorded. This keeps the checklist tied to the change. A pure internal refactor should not generate an unrelated public API exercise.
Closing tasks are part of the task count and dependency structure. Newly discovered implementation work is inserted before them, and their dependencies are updated. Otherwise an agent could complete a checklist, discover another change, and ship without applying the same checks to that addition.
In the timeout example, a unit test of the shared helper cannot alone establish CLI/SDK parity. The adapters may convert units differently or supply different defaults. Acceptance should include observations at the relevant boundaries: equivalent inputs, expected completion or cancellation, and consistent exposed behavior.
The general evaluation principle is to examine the resulting state as well as what the agent reports. Anthropic's agent evaluation guide distinguishes an execution transcript from its outcome and discusses grading through multiple forms of evidence. A milestone's acceptance criteria provide a small, project-specific version of that discipline.
Closeout makes the result visible on disk. Completed task files move into the milestone's done/ folder. Once all work and the definition of done hold, the whole milestone moves under the workstream's done/ directory and its checkbox is checked. The archive also becomes input for future brainstorming, helping prevent duplicate proposals.
4. Run a sequential loop with explicit stopping conditions
/loop-worker w1 means execute the pending milestones in one named queue. The skill requires a workstream argument rather than guessing, checks its branch precondition, and inspects existing changes before starting. Those checks establish the execution context and help prevent unrelated work from entering the milestone's commit.
The loop chooses the lowest-numbered unchecked milestone that still has a live directory. It cross-checks the README against task files and filesystem state. Then it reads the milestone and all open tasks, performs the work in dependency order, runs relevant checks, and maintains status through the PM conventions.
After closeout, it invokes the shipping workflow. It must receive a successful ship result, including the pushed commit, before selecting the next milestone. Each milestone gets its own shipped unit, which makes history and rollback easier to interpret.
This loop is sequential. It is not a timer that wakes up every few minutes, and it does not implicitly scan all queues for attractive work. Independent implementation subtasks can be delegated under the worker's rules, but the parent retains responsibility for integration and correctness.
Three outcomes stop execution: the selected queue has no pending milestones, a genuine blocker prevents progress, or an interruption calls for a checkpoint. If a milestone needs a user decision or unavailable access, the worker reports the specific missing input. It does not silently skip ahead to make the completion count look better.
Scope is essential to interpreting the result. “No pending milestones in w1” says nothing about loose inbox notes or another queue. Likewise, this shipping contract ends at a successful push; it does not wait for hosted CI or deployment. A useful final report states the milestones shipped, their commits, relevant local verification, and any remaining work without implying a stronger completion claim.
5. Treat status consistency and ship recovery as real engineering problems
The design is readable, but it contains duplicated state. Completion appears in task frontmatter, the milestone README, and the workstream checkbox. File location adds another signal. Updating these artifacts is a multi-step operation that can be interrupted.
The current rules require synchronization and tell the worker to flag disagreements, using task files to resolve selection drift. That is a recovery convention, not an atomic transaction. A checked box cannot establish that tests passed, and a directory move cannot establish that a commit reached the remote.
There is a particularly important interruption window between closeout and shipping. The milestone can already be archived when the push fails. On restart, a selector that only looks for pending milestones could see an empty queue even though the last milestone remains unshipped.
For teams adopting this pattern, I would add a recovery check that reconciles recently closed milestones with Git state and the last recorded ship result before selecting new work. That is a proposed improvement to this workflow, not a capability established by the existing board files. A persistent shipped-commit record would make the distinction easier to inspect.
A second limitation is concurrency. Assigning board writes to the PM skill establishes one owner for conventions; two sessions can still invoke it simultaneously. Both might choose the same next task number. Separate workstreams reduce some collisions, but shared-file edits still need coordination. A serialized mutation path or an explicit lock becomes useful when such collisions actually occur.
The operating instructions themselves also need consistency checks. In the version reviewed here, the roadmap anti-goals prohibit rebasing main, while the shipping skill prescribes a rebase-based pull. That conflict needs resolution before automated execution reaches it. Canonical board conventions prevent one category of drift; they cannot reconcile every neighboring skill automatically.
I would evaluate this system with a few concrete measures: how often completed milestones reopen, how often status disagrees across files, how much work a restart repeats, and how often local closeout lacks a confirmed push. The repository instructions alone do not establish a productivity multiplier.
Start with one queue and one meaningful milestone. Write its observable outcome, attach the tasks required to finish, and verify that a fresh session can recover both the next action and the evidence for completed work. The lasting value of the three-skill system is that proposal, commitment, verification, and shipping each leave something the next worker can inspect.