Skip to content

Commit f53b352

Browse files
V3RONV3RON
committed
docs(delivery): DELIVERY.md — the maintainer's walkthrough of the issue model
1 parent 4c22fda commit f53b352

2 files changed

Lines changed: 140 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ Useful documentation lives in [docs/](docs/):
3838
- [ABOUT.md](docs/ABOUT.md) — what the tool is and the problem it solves
3939
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — high-level architecture overview
4040
- [CLI.md](docs/CLI.md) — the expected CLI command surface (user manual)
41+
- [DELIVERY.md](docs/DELIVERY.md) — how work flows through GitHub Issues:
42+
the three walkthroughs, what is automated, where ADRs fit
4143
- [EVENTS.md](docs/EVENTS.md) — catalog of business events
4244
- [IDEAS.md](docs/IDEAS.md) — post-v1 ideas; don't implement these unless asked
4345
- [known-pitfalls.md](docs/known-pitfalls.md) — accepted gaps and their planned fixes

‎docs/DELIVERY.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# How work flows
2+
3+
GitHub Issues is the specification and the queue. An issue's body is what an
4+
agent builds against; its label is the only thing that tells an agent whether
5+
it may act. This page is the maintainer's manual for that model. The binding
6+
rules are in [agent-rules/delivery.md](agent-rules/delivery.md); this page
7+
explains how they fit together in practice.
8+
9+
## The model in five sentences
10+
11+
Every issue carries exactly one `<kind>:<state>` label, and the prefix is the
12+
kind. Agents act only on `bug:triage`, `bug:ready`, `feature:ready` and
13+
`task:ready`; everything else is either an unread claim from outside or an
14+
unfinished spec. The body is the spec and comments are discussion, so a
15+
comment changes nothing until a spec session folds it into the body. A
16+
reporter's issue is never rewritten: bugs are triaged in a comment, and a
17+
feature that came from a request is a new issue the maintainer owns. What
18+
happens after `ready` is read from GitHub itself — assignee, linked pull
19+
request, closed — not from a label.
20+
21+
| Label | Meaning |
22+
| ----------------- | -------------------------------------------------------- |
23+
| `request:new` | Inbox. Never picked up, body never edited. |
24+
| `bug:new` | Reported. Nobody has looked yet. |
25+
| `bug:triage` | An agent may reproduce it and write the triage report. |
26+
| `bug:needs-info` | Could not reproduce. Waiting on the reporter. |
27+
| `bug:ready` | An agent may fix it. |
28+
| `feature:spec` | Business or technical spec in progress. |
29+
| `feature:ready` | No sub-issues; one PR delivers the whole feature. |
30+
| `feature:planned` | Split into tasks. Never picked up itself. |
31+
| `task:draft` | Scope written; technical spec, approval or deps missing. |
32+
| `task:ready` | An agent may implement it. |
33+
34+
## A bug, from report to fix
35+
36+
1. Someone opens a bug through the form. It arrives as `bug:new`. Nothing
37+
happens.
38+
2. The maintainer reads it. If it sounds real, they add `bug:triage`. That is
39+
the whole delegation.
40+
3. An agent running `triage-bug` assigns itself, reproduces the bug as a
41+
failing test whose title states the claim, finds the root cause, pushes
42+
only the test to `bug/<n>-repro`, and posts one comment with five
43+
sections: Reproduction, Root cause, Simplest fix, Alternatives rejected,
44+
Risk. It opens no pull request, and it unassigns itself when done.
45+
4. If it could not reproduce, it swaps the label to `bug:needs-info` and says
46+
exactly what is missing. A reply from the reporter moves the issue back to
47+
`bug:triage` on its own; two weeks of silence closes it.
48+
5. The maintainer reads the report. Agree: add `bug:ready`. Disagree: reply
49+
with what is wrong and re-add `bug:triage`; the next agent starts from
50+
that reply.
51+
6. An agent running `deliver` claims the `bug:ready` issue, branches from the
52+
repro branch, and opens a PR that closes the issue. The triage test is now
53+
the regression test. Merge closes the bug.
54+
55+
## A feature, delivered as one PR
56+
57+
1. The maintainer creates a `feature:spec` issue, or an outside request
58+
arrives as `request:new` and the maintainer decides to take it up. Nothing
59+
happens to a request by default.
60+
2. First spec session. The agent interviews the maintainer and writes the
61+
business half of [templates/feature.md](templates/feature.md): Problem,
62+
Who it is for, Outcome, Non-goals, Completion conditions, Open questions.
63+
It says what a user can do afterwards, never how. If the feature came from
64+
a request, the session creates the feature issue, links it to the request,
65+
and comments on the request so the reporter knows where to look. The
66+
request stays open until the feature ships.
67+
3. Discussion happens, on the feature or on the request, in comments. Nobody
68+
edits the body by hand.
69+
4. Second spec session. The agent first lists every comment posted since the
70+
body was last edited, on both threads, as a set of proposed changes; the
71+
maintainer accepts or rejects each. Then it interviews for the Technical
72+
spec section. Any decision that constrains more than one future change or
73+
would be expensive to reverse becomes an ADR at _Proposed_, listed under
74+
Decisions. The session ends by editing the body and leaving a one-line
75+
"Spec updated" comment.
76+
5. Once Open questions is empty and every linked ADR is accepted, the
77+
maintainer adds `feature:ready`. The ADRs move to _Accepted — not yet
78+
implemented_.
79+
6. An agent running `deliver` claims it and opens a PR whose body walks every
80+
completion condition. Merge closes the feature, and its ADRs flip to
81+
_Accepted_.
82+
83+
## A feature, split into tasks
84+
85+
Steps 1 to 4 are the same, but the second session ends differently: instead
86+
of a Technical spec section on the feature, it produces sub-issues.
87+
88+
5. Each task is a native sub-issue of the feature, labelled `task:draft`, with
89+
a body from [templates/task.md](templates/task.md): Scope, Technical spec,
90+
Done when, Out of scope, Depends on, and an approval checkbox. The feature
91+
becomes `feature:planned` and keeps only its business spec, Decisions and
92+
the task list.
93+
6. The maintainer ticks the approval box on each task, once, at planning
94+
time. From then on the automation promotes a task to `task:ready` the
95+
moment its box is ticked, its Technical spec has content, and every issue
96+
under Depends on is closed. Nobody re-reads the dependency graph by hand.
97+
7. Agents claim `task:ready` issues one PR each. As tasks close, the ones they
98+
unblocked become ready on their own.
99+
8. When the last sub-issue closes, the automation comments on the feature
100+
that completion conditions are due. An agent proves them against `main`,
101+
usually with an end-to-end run, and reports in a comment. The maintainer
102+
closes the feature.
103+
104+
## What is automated and what is not
105+
106+
The workflow in `.github/workflows/issue-state.yml` handles the transitions
107+
that are mechanical: adding a state label removes the previous one, so every
108+
transition is a single add; `task:draft` becomes `task:ready` when approved,
109+
specified and unblocked; a reporter's reply moves `bug:needs-info` back to
110+
`bug:triage`; a silent `bug:needs-info` closes after two weeks; a feature
111+
whose last sub-issue closed gets the completion-conditions note. The repo's
112+
skills — `spec-session`, `triage-bug`, `deliver` — handle the transitions an
113+
agent makes as part of its own procedure.
114+
115+
Four transitions are judgments and stay manual on purpose: `bug:new` to
116+
`bug:triage`, `bug:triage` to `bug:ready`, `feature:spec` to
117+
`feature:ready`, and the approval box on each task. Each is one click.
118+
119+
## Where ADRs fit
120+
121+
A feature answers _what_ and _why_ in business terms. An ADR answers _how_,
122+
but only for choices that constrain more than one task or would be expensive
123+
to reverse. A task answers _how_ for exactly one PR. Most features never need
124+
an ADR; the ones that fix a protocol shape or an ownership model do. An ADR
125+
is born in a spec session, is _Proposed_ while the feature is `feature:spec`,
126+
_Accepted — not yet implemented_ while the feature is open, and _Accepted_
127+
when it closes. See [adr/README.md](adr/README.md).
128+
129+
## Pointers
130+
131+
- Rules: [agent-rules/delivery.md](agent-rules/delivery.md)
132+
- Templates: [templates/feature.md](templates/feature.md),
133+
[templates/task.md](templates/task.md)
134+
- Reporter forms: `.github/ISSUE_TEMPLATE/`
135+
- Labels: `.github/labels.json`, synced by `.github/workflows/labels.yml`
136+
- Automation: `.github/workflows/issue-state.yml`
137+
- Skills: `.claude/skills/spec-session`, `.claude/skills/triage-bug`,
138+
`.claude/skills/deliver`

0 commit comments

Comments
 (0)