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 origin points 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

Flow: an idea becomes a roadmap line, a story, a build, a landing and a release

  1. Capture — a raw idea becomes a roadmap line.
  2. 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).
  3. 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).
  4. Land — the story joins main once its build is green. It carries no version.
  5. Release — a later, separate act on main gives 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 check should warn when a release touches code without touching the spec — enforcement, versus trusting the "Done when" list.