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.

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. 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
Bullets. Each one names the surface it touches (command, config field, doc).

## Acceptance
| Condition | Condition | Outcome |
|---|---|---|
| ... | ... | ... |

## Out of scope
What a reader might expect that this story deliberately does not do.

## Decisions
Link ADRs this story produced, or "none".

## 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 blank cell in the acceptance table is a visible gap — leave it blank rather than guess, and resolve it before implementation starts.

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

idea ──► roadmap line ──► story file + issue ──► failing test ──► code
                                                      │
                                    fork? ──► ADR ◄───┘
                                                      │
                          spec edited ◄── shipped ◄───┘
                          roadmap ticked, changelog, issue closed
  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.
  4. Close — the spec is edited so it describes the new state, the roadmap line is ticked with its version stamp, the changelog gets its line (tp release rolls [Unreleased] into the version), and the issue is closed. This is the "Done when" list; the story is not shipped until every box is ticked.

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, and 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. Still to come: tp adr, and tp release closing the stories it ships.

Open questions

  • Whether tp check should warn when a release touches code without touching the spec — enforcement, versus trusting the "Done when" list.