# 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.** Decisions that cut across projects (a preferred
  container runtime, a primary-key pattern, a diagram tool) tend to end up
  as bare conventions in an agent instruction file, without their reasoning.
  Giving them a home is an open question below.

## 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:

```markdown
# 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):

```markdown
# 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`](issue.md) for the tracker, and
[`tp story`](story.md) — `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

- A home for cross-project ADRs, with agent instruction files reduced to a
  summary that links to them.
- Whether `tp check` should warn when a release touches code without
  touching the spec — enforcement, versus trusting the "Done when" list.