Development method
How work on a project is described, tracked, and recorded. The aim is a small set of artefacts where each one answers a single question and stays true through refactors — so a story, a spec page, and a decision record never carry each other's job. task-plus is the tool side of this; the judgement side lives in whatever agent or person does the refining.
Vocabulary
| Artefact | Answers | Lifetime | Home |
|---|---|---|---|
| Story | what changes, why it matters, how we will know it is done | until shipped | docs/stories/NNN-slug.md + a tracker issue |
| Spec | what is true now | permanent; edited by every story | docs/features.md, docs/scope.md, *.d2 |
| ADR | why X was chosen over Y, in what context | permanent; superseded, never edited | docs/adr/NNNN-slug.md |
| Roadmap | in what order | rolling | ROADMAP.md |
| Changelog | what shipped when | permanent | CHANGELOG.md |
A story is a delta, the spec is state, an ADR is rationale. When a sentence in a story describes how the system will behave, that sentence ends up in the spec once the story ships; when a story resolves a genuine fork, the fork and its reasoning go into an ADR, and the story just links to it.
The words for how a story travels are fixed too, because each names a different act with a different cost:
| Term | Means | Is not |
|---|---|---|
| Trunk | main: the one long-lived branch, releasable at every commit |
somewhere to commit directly, from code level 1 |
| Story branch | story/<issue>-<slug>, cut from the trunk and alive for days |
somewhere a version is chosen |
| Build | the check that a commit breaks nothing: the project's check task. Cheap, and run on every commit offered to the trunk |
a release: it publishes nothing and changes no tracked file |
| Land | a story joining the trunk by its own pull request, on a green build. The story is then landed | shipping: a landed story has no version |
| Fragment | changes/<issue>.<kind>.md: a story's changelog line, written on its branch and gathered by the release |
an edit to CHANGELOG.md |
| Release | making what has landed available to its users: a module version, binaries, a website. Dearer than a build and run when wanted, not per commit; always a tag on the trunk. Its stories are then shipped | landing, or a build |
| Deploy | putting a release onto a running system | a release: it changes nothing in the repository |
| Batch | the old level 1, where stories reached the trunk only inside a release, through a release branch. Retired; see the batch |
The acts are defined in Build, land, release.
Where things live
- The repo is the source of truth for a story. The forge issue is the
tracking handle: it carries the story's title, its first paragraph, and a
link back to the file. Markdown in
docs/survives a move between forges and can be read without an API token. The cost is two copies that can drift, so the issue is only ever written from the story file, never edited by hand. - Issues live on the repo's own forge — whichever
originpoints at. The story heading links its issue as#N; the roadmap links the story. - ADRs are per project, except cross-project ones. Decisions that cut across projects (a preferred container runtime, a primary-key pattern, a diagram tool) belong in this manual, so the reasoning lives next to the rule. Agent instruction files carry only a summary that links here.
Story
One story at a time. A story is small enough to ship in one release and carries its own acceptance rules as a decision table, not scenarios.
Structure goes where it pays, which is acceptance; the rest is kept light. Two parts are in every story and the others only where they earn their place, so a one-file change is not made to fill a form:
| Part | Needed | Says |
|---|---|---|
| Why | always | the problem and who hits it; a sentence is enough |
| Acceptance | always | how we will know it is done |
| What changes | when the title does not make the surfaces plain | each surface touched |
| Out of scope | when a reader would expect more than the story does | what is left out |
| Decisions | when a fork was resolved | the ADR |
| Persona | when it makes the story clearer | who, by a name used as shorthand |
A story is written to be built without a conversation, often by an agent, so what the conversation would have settled has to be on the page: that is the reason acceptance and out of scope are worth their length where a card would do for a team in one room.
Template:
# NNN — <title> (#<issue>)
**Status:** proposed | in progress | shipped (vX.Y.Z)
## Why
One or two paragraphs: the observed problem, who hits it, why now.
## What changes (optional)
Bullets. Each one names the surface it touches (command, config field, doc).
## Acceptance
| Condition | Condition | Outcome |
|---|---|---|
| ... | ... | ... |
### Judged at the merge (optional)
- What no test can express, for whoever merges to judge.
## Out of scope (optional)
What a reader might expect that this story deliberately does not do.
## Decisions (optional)
Link ADRs this story produced.
## Done when
- [ ] tests express the acceptance table and pass
- [ ] spec updated (`features.md`, `scope.md`, diagrams as needed)
- [ ] ADR written if a fork was resolved
- [ ] roadmap ticked and stamped; changelog entry
- [ ] issue closed with a link to the release
A persona is optional. "Why" has to say who hits the problem; a named persona is worth having only where it makes the story clearer, and its name is then shorthand for that user in the rest of the story. No story is held up for want of one.
A blank cell in the acceptance table is a visible gap — leave it blank rather than guess, and resolve it before implementation starts.
Hard and soft acceptance
Acceptance is hard by default: each row of the table is a condition and an outcome that a test expresses, and the build checks it. The story is not built until those tests pass.
Some outcomes no test can express: a page reads well, a diagram is legible, a command feels quick. Those are soft, and are kept apart from the table so that nobody takes them for something the build checks.
| Hard | Soft | |
|---|---|---|
| Written as | a row of the acceptance table | a line under "Judged at the merge" |
| Checked by | a test, in the build | whoever merges the pull request |
| Checked when | every build | once, at the merge |
| Says it holds | a green build | the merge itself |
A criterion that a test could express is not left soft. A story may have only soft criteria, as a page of documentation often does, but it has some acceptance: a story with neither is not ready to build.
ADR
Write one when a choice was genuinely two-sided and someone later could reasonably ask "why not the other way?". Do not write one for the obvious default. Template (MADR-lite):
# NNNN — <decision as a short sentence>
**Status:** accepted | superseded by NNNN
**Date:** YYYY-MM-DD
**Story:** #<issue> / stories/NNN-slug.md
## Context
What forced the choice; constraints that mattered.
## Options
| Option | Complexity | Testability | Domain clarity | Operational risk |
|---|---|---|---|---|
| A | | | | |
| B | | | | |
## Decision
Which, and the one-paragraph why.
## Consequences
What becomes easier, what becomes harder, what we gave up.
An accepted ADR is never edited. A change of mind is a new ADR that supersedes it, and the old one's status line points forward.
Flow
- Capture — a raw idea becomes a roadmap line.
- Refine — when it is next, it becomes a story file (
tp story new); the issue is created from it and the number written back into the heading (tp story issue). - Build — test-first against the acceptance table. A fork met on the
way is recorded as an ADR before the code that depends on it. The spec
is edited so it describes the new state, and the story writes its
changelog line as a fragment (
changes/<issue>.<kind>.md). - Land — the story joins
mainonce its build is green. It carries no version. - Release — a later, separate act on
maingives what has landed a version and a tag, and closes the issues of the stories it ships. The story is not shipped until then.
Steps 4 and 5 are defined in the next section; which commands carry them out at each level is the code-flow ladder.
Build, land, release
Three acts, kept apart because each answers a different question and only one of them is allowed to change what is tracked. Run together, as one command that integrates a story and versions it, they need a state shared between stories (who holds the next version, whose release is open), and every agent or person has to work that state out before each step.
| Act | Question | What runs | Changes tracked files | Reaches main |
|---|---|---|---|---|
| Build | is the tree at this commit sound? | the project's check task: format, vet, lint, tests, covering at least everything the change touches |
never | — |
| Land | can this story join main? |
main merged into the story branch, a build, the push, the pull request; the run waits for the build to be green and the merge to happen |
never, beyond the story's own commits | by the story's pull request |
| Release | which commit on main becomes version X.Y.Z? |
the version worked out from the landed fragments; the release commits; a full build; the merge; the tag on the merge; publication of the module, the binaries, the website | yes, on the release branch only | by the release's pull request, merged by the tool |
| Deploy | has the release reached the systems that run it? | installs, running systems | never | never |
Build
A build is fast and green or it is not a build
(fast green builds).
Fast, because it runs on every commit that is offered to main: it may be
narrowed to the parts a change touches, never below them. Green, because
main is only ever moved to a commit whose build passed.
A build reads the tree and reports. If it leaves a tracked file modified (a lock file rewritten, a page regenerated), the build has failed, since the commit it was asked about is no longer the tree it tested.
Rendering the documentation is part of the build: it is cheap, it reads the tree, and a page that no longer renders is a broken commit like any other. To keep the build fast, a page or diagram is rendered again only when something it depends on has changed: its source, a file it includes, the template. Publishing it is not: nothing is published from a story branch, and a build has no effect outside the checkout. Publishing follows the landing.
An unfinished feature lands behind a flag that is off by default. The build must pass with the flag off, which is what users get, and the feature's own tests turn it on.
Land
Landing integrates and decides nothing: no version is chosen, no changelog is edited, no tag is made. A story branch lives for days, not weeks, and is deleted by the merge.
One thing follows a landing: the documentation is published, because
that is cheap and a corrected page should not wait for a release. It is
rendered from the tip of main after the merge, never from the story
branch, and the published site records the commit it was rendered from.
That record is what lets the step be picked up. A landing whose run ended
before the merge leaves the site behind main; the query says so, and
the next landing, a release, or the publish step run by itself brings the
site to the tip. Publishing twice does no harm.
Every story has a branch of its own, story/<issue>-<slug>, cut from
main; nothing is committed to main directly. The branch is checked
out either in the project's checkout, one story at a time, or in a
worktree of its own, which is what lets several stories be open at once
without sharing a working tree.
Release
A release is the story nobody writes. Its branch is release/vX.Y.Z, cut
from main; its change is the version; its pull request is opened and
merged by the tool; its branch is destroyed when the tag is pushed.
Every release is a tag. What the tag publishes depends on what the project produces, and a project may produce more than one:
| Project produces | The release publishes | Cost |
|---|---|---|
| a module | the tag itself, fetched through the module proxy | seconds |
| binaries | the binaries built from the tag, attached to the forge release | minutes |
| a website | the site rendered from the tag, copied to its host | seconds to minutes |
| documentation beside any of these | nothing new: it was published on landing, and is published again so the site stands at the tag | seconds |
A website that is the project's product is published by the release and not on landing: its readers are its users, and the tag says which commit they are looking at. A repository whose whole output is a site, this manual among them, is a website in this sense. Documentation beside a module or binaries is the one thing published on landing (Land).
Everything that states the version changes in the release commits and nowhere else:
| Changed by the release | Example |
|---|---|
| the changelog, from the fragments, which are deleted | CHANGELOG.md, changes/ |
| files that carry the version | pyproject.toml, a version constant, the README's install line |
| files derived from those | uv.lock, generated assets that embed the version |
So at every commit on main the version files name the latest tag, and a
story never touches them. The tag goes on the merge commit and on nothing
else: a release whose pull request has not merged is not a release.
A story that lands while a release's pull request is open is not left
out of step. The release is redone over everything that has landed; a
tag is never made while fragments remain on main.
Asking before acting
Each act has a query that reads the repository and the forge, changes nothing, and names the one next step and who takes it:
| Query | Asked | Answers |
|---|---|---|
tp story query |
on a story branch or in its worktree | where this story stands (unbuilt, behind main, in conflict, in a pull request, landed) and the next step |
tp release query |
on main |
what has landed since the last tag, the version it makes, and the next step |
The query is the source of truth for what to do next. Whoever is doing the work, agent or person, runs it and does what it says, instead of inferring the state from branches and pull requests. A query needs no knowledge of the other: a story's next step never depends on a release, nor a release's on any one story.
Deploy
Deploying is not releasing. A release ends when what the tag names is published: the module can be fetched, the binaries downloaded, the website read. A deploy then puts that release onto a running system, and how carefully is the deployment ladder.
Nothing that runs after the tag, publication included, may commit, push
to main, or leave the working tree changed. Anything that wants to be
in the repository at version X.Y.Z belongs in the release commits.
Tooling split
The deterministic parts belong in task-plus, because they are the same for
every project and are testable: numbering the next story or ADR,
scaffolding from the templates above, creating the issue from a story file
and stamping the number back, closing it on release. The judgement parts —
refining an idea into a story, deciding whether a choice earns an ADR,
writing a decision table — stay with the person or agent doing the work,
typically as agent skills that call tp rather than re-implementing it in
prose.
What exists: tp issue for the tracker,
tp story — tp story new TITLE scaffolds the next story
from the template above, tp story issue NNN files its issue and stamps
the number back, tp story land lands it, tp story query says where
it stands — and
tp release, which releases what has landed and
closes the stories it ships. Still to come: tp adr, and publishing the
documentation on landing with the commit recorded on the site.
Open questions
The definition of a story will get clearer with use. Open:
- Documentation ahead of the release. Published on landing, a page can describe behaviour no tagged version has yet. Whether such a page has to say so, and how.
Also open:
- Whether
tp checkshould warn when a release touches code without touching the spec — enforcement, versus trusting the "Done when" list.