Work packages
- Status
- Review
- Version
- 0.1.3
- Authority
- UASK standard
- Applies to
- Core
Summary
A work package is the unit one builder takes during Build: one goal, one branch, one pull request. This item says what a package carries before it starts (a brief), how it is built (checks first), who checks it (a verifier who did not build it, from the standard tier up) and what lets it merge (one gate, the same locally and in CI). A package is reported with a commit and the output of the checks; without both it is reported as “not verified”. It sits between the release spec, which lists the packages, and the release, which collects them.
Rules
The brief
- R1. A work package MUST have a brief in a file before the builder starts. The brief MUST state the goal, the id of the
package in the release spec (
process.release-spec#R11), the files it may touch and the files it must not, the checks to write first, the Done criterion that someone else can check, the estimate, and any decision that stays with the owner (mgmt.roles-and-decision-rights#R9). - R2. A package MUST be small enough for one builder, one branch and one pull request. A package whose estimate is more than two agent-days SHOULD be split, and the brief MUST say why when it is not.
- R3. The lead MUST check the brief against the Definition of Ready (
process.definition-of-ready) before the builder starts. A package that does not meet it MUST be clarified, split or marked blocked; it MUST NOT start.
Building
- R4. Each package MUST be built on its own branch, named with the type and the issue as the project’s rules say
(
config.conventional-commits), and MUST reach the main branch only through a pull request. The main branch MUST stay releasable. - R5. The builder MUST write or name the checks that prove the Done criterion before changing the product, and MUST
see them fail (red) first; for a defect the first check is a regression test that reproduces it
(
quality.quality-release#R8). A check that was never seen to fail does not count as evidence. - R6. The builder MUST NOT change the scope, an accepted ADR or a file the brief forbids, and MUST NOT take an
owner-level decision. When the work needs one, the builder MUST stop and give the lead the options and a default
(
mgmt.roles-and-decision-rights#R5,mgmt.roles-and-decision-rights#R12).
Reporting and verifying
- R7. The builder MUST report each package with the commit hash, the command that runs the checks and its output, and the Definition of Done lines with their evidence. A package without a commit hash and check output MUST be reported as “not verified”, not as done.
- R8. At the standard tier and above (
mgmt.governance-tiers#R7, and for the high-assurance tiermgmt.governance-tiers#R8) a verifier who did not build the package MUST re-run the checks itself and review the change against the Definition of Done (process.definition-of-done). The verifier MUST report findings with a severity and MUST NOT fix what it reviews (mgmt.roles-and-decision-rights#R6). At the lightweight tier the builder MUST check its own work against the Definition of Done and say so. - R9. A finding of the verifier at the severity the project calls blocking MUST be fixed and the checks run again before the merge. The same verifier or a new one MUST check the fix.
The merge gate
- R10. A package MUST merge only when the gate script passes locally and in CI (
quality.quality-release#R5,quality.quality-release#R6), the Definition of Done is met, and, where R8 applies, the verifier has passed it. A red gate MUST NOT be bypassed (quality.quality-release#R7). - R11. The lead merges, or the builder where the project’s rules give it that right; neither MUST merge a package that touches what R6 reserves for the owner
before the owner has decided. Merging into production is the release’s business and has its own gate (
process.project-lifecycle#R8).
Afterwards
- R12. Each merged package MUST leave one line in the project’s log: the package id, the branch, the commit, the verdict of the verifier, and the time spent against the estimate. The lines are the input for the estimates of the next release spec.
- R13. A defect that escapes into a release MUST become a check: the package that fixes it carries a regression test (R5) and, where the defect shows that the Definition of Ready or of Done missed something, a reviewed change to them.
Guidance
The package in the release
The release spec lists the packages and compares their sum with the appetite (process.release-spec#R11). A package is a row of that table
made into a brief. Cut packages by outcome that someone can check, not by layer of the system: “the order mail names the delivery date” is a package,
“change the database” is not. When a package grows beyond its estimate, the lead decides whether to split it, drop it or end the release at the appetite
(the circuit breaker of the release spec).
The brief in practice
A brief is half a page. The one that works has five lines: the goal in one sentence; the paths it may touch and the paths it must not; the check command
that will say “done”; what to do when the check cannot be written first; and the question to ask the lead rather than decide alone. Keep it as a file in
the repository (for example work/WP-012.md), so that a second agent with no memory of the chat can take it.
Checks first
Writing the check first is what keeps “done” from meaning “I finished typing”. Where the change is documentation, the check is a script or a validator that the page must pass; where it is a user-visible result, it is a test or a scripted demonstration. If no check can be written, say so in the brief and give the verifier the manual steps; do not skip the red step silently.
The verifier
The verifier gets the brief, the diff and the check command, and nothing of the builder’s reasoning. That is why it can see what the author does not. At the standard tier it is another person or a separate session. It re-runs the checks, because a pasted result shows only that the command once passed on the builder’s copy.
How the old “done” texts map to this item
Before this item “done” was written in several places. They now point here, and the lines live in two checklists.
| Where it was said | What it said | Now |
|---|---|---|
| The project rules file (AGENTS.md of a Hub project), testing section | done means verified, with the command and its result | R7; the rules file points to the project’s Definition of Done, which names process.definition-of-done |
templates/definition-of-done.md and a project’s copy |
a list of lines for every change | the lines are the rules of process.definition-of-done; the template is its copy form |
templates/definition-of-ready.md |
a list of conditions to start | the rules of process.definition-of-ready; the template is its copy form |
quality.quality-release (R1, R2 and the stage “Build a change”) |
a project keeps a Definition of Done and of Ready | stays as the duty to keep them; what the lines are is in the two checklists |
process.project-lifecycle (R6, R7) and process.release-spec (work packages) |
the gates and the unit of work | point to this item for the unit and to the checklists for the lines |
Common mistakes
- A brief that says what to build but not how it will be checked.
- A verifier who is the builder in a new chat with the same notes.
- “Done” reported from memory of a command that was run before the last edit.
- A package that quietly takes an owner-level decision because it was easier than asking.
- A gate that was green at the author’s desk and not in CI; the cause is usually a file that was never committed.
Explanation
Why a brief and a branch. A package that lives in a chat has no edges: nobody can say what it was allowed to touch or when it was finished. A file brief and a branch give it edges that another person or agent can read, and keep the main branch releasable while work is half done.
Why checks first, and why seen red. A test written after the code passes by construction. Seeing it fail first shows that it can fail, which is the whole value of a check. A reviewer is asked the same question: will the tests actually fail when the code is broken? Google’s reviewer guide asks it of every change, and adds that tests belong in the same change as the code.
Why a separate verifier. The author reads the code they meant to write. Google’s guide defines a code review as an examination by someone other than the author; the Hub asks it from the standard tier up, and lets the lightweight tier keep its speed.
Why one gate. A merge gate that differs between the author’s machine and CI produces “works for me”. One script, run in both places, gives the same answer, and a protected branch that requires the checks makes the answer binding.
Examples
Good. A small UK online shop, release spec RS-004 “delivery dates in order emails”, appetite three agent-days, three packages. Package WP-2 has a half-page
brief: goal “the order mail names the estimated delivery date”; may touch the mail template and its test; must not touch the checkout or the stock module; check
first: a test that renders the mail for a Friday order and expects Tuesday; estimate one agent-day. The builder shows the test failing, then passing, reports
3f9a1c2 and the output of bash tests/run.sh, and a second session reruns it, finds that a bank holiday is not handled, and the builder adds a case. The package
merges; the log line reads “WP-2, docs/rs-004-wp2, 3f9a1c2, pass after one finding, 1.3 agent-days of 1”.
Bad. “Add delivery dates to the emails.” There is no brief, no list of files and no check. The builder changes the checkout to carry the date, the tests that exist still pass, and the work is reported as done from a chat message. A week later an order placed on a bank holiday gets the wrong date, nothing fails, and nobody can say which package was meant to cover it.
Sources
- Google Engineering Practices, The Code Review Developer Guide — CC BY 3.0; a review is an examination by someone other than the author. Accessed 2026-11-21.
- Google Engineering Practices, What to look for in a code review — CC BY 3.0; tests are added with the change and must fail when the code is broken. Accessed 2026-11-21.
- GitHub Docs, About protected branches — CC BY 4.0; required status checks and reviews bind the merge. Accessed 2026-11-21.
- Agile Alliance, Definition of Done — Agile Alliance; the meaning of the term, used for the checklists. Accessed 2026-11-21.
- ISO/IEC/IEEE 12207:2017 (software life cycle processes) — referenced by name only.
- The Hub’s own practice and that of the owner’s projects: a gate script that decides a merge, and a report of “a commit hash plus check output, otherwise not verified”, described here as a pattern, without paths or client data.