a73x

c4d2afa6

Adopt the sprint-delivery workflow, adapted for this repo

a73x   2026-09-06 08:36

Commit message
Adopt the sprint-delivery workflow, adapted for this repo
.agents/skills/sprint-delivery/SKILL.md
Old New
@@ -0,0 +1,146 @@
1 ---
2 name: sprint-delivery
3 description: Deliver one working slice of git-collab at a time, with opening and closing cleanup, adversarial review, real-boundary validation, a demonstrable result, and a durable retrospective with checkable actions. Use when the user asks for sprint delivery; ordinary isolated edits do not need it.
4 ---
5
6 # Sprint delivery
7
8 Deliver one useful, working slice at a time. Keep session continuity in the
9 repository, not in the conversation. This skill supplies a workflow; it does
10 not authorize a new sprint, a deployment, or publishing anything.
11
12 Adapted for git-collab from the maintained copy in `~/code/rad/mux`
13 (`docs/skills/sprint-delivery/SKILL.md`), which has closed 49 retrospective
14 actions this way. Differences from that copy are noted where they matter.
15
16 ## Use with any agent
17
18 This file is ordinary Markdown; a skill loader is optional. For tools without
19 automatic discovery, ask: "Read `.agents/skills/sprint-delivery/SKILL.md` and
20 use it to resume the sprint." `AGENTS.md` points here and at `CLAUDE.md`.
21
22 Do not restate rules that live in `CLAUDE.md` — invariants, working rules,
23 gates, and the context-hazard list are there, and one rule per question is
24 itself an invariant. Read it first; this file is the procedure, that file is
25 the law.
26
27 ## Resume from evidence
28
29 Read `CLAUDE.md`, `git status`, recent commits, the current spec/plan, and
30 **the open actions and retained debt in `RETRO.md`** — that file is an input,
31 not a diary. Read relevant sections rather than full history; the repo is
32 large and every token is re-billed each turn.
33
34 Report what is implemented, validated, accepted, and still open as **distinct
35 facts**. A green suite is not user acceptance; say what was verified and what
36 was only asserted.
37
38 ## Run a bounded sprint
39
40 1. **Scope and acceptance.** Choose the smallest functional deliverable within
41 the authorized plan. Define observable acceptance scenarios. Carry forward
42 applicable `RETRO.md` actions, and honour any debt whose *trigger* this
43 slice fires. Clarify material unknowns early; continue independent work
44 while waiting.
45 2. **Opening cleanup.** Inspect the touched code for small refactors that help
46 the slice; commit them separately. If the code is ready, say so — there is
47 no cleanup quota.
48 3. **Implement with adversarial review.** See the pairing below. Deliver
49 through real user interactions and system boundaries, not through unit
50 tests alone.
51 4. **Closing cleanup.** Explicitly review duplication, obsolete paths,
52 temporary scaffolding, and unnecessary state. Refactor what the slice
53 exposed — a second predicate for a question the codebase already answers is
54 the specific thing to look for. Record retained debt with its location,
55 consequence, and **next owner or trigger**.
56 5. **Validate and demonstrate.** Run the gates, then verify real behaviour
57 beyond your own agreement. Freeze the source before final checks and rerun
58 affected ones after any change. Demonstrate the result, including its
59 failure paths.
60 6. **Close and hand off.** Commit validated work. Update the spec/plan status
61 and `RETRO.md`: what was delivered, what worked, lessons, retained debt, and
62 **checkable actions for the next slice**. Promote anything that generalises
63 into `CLAUDE.md` — `RETRO.md` is not read at decision time, `CLAUDE.md` is.
64 Record demo acceptance only when it is given.
65
66 ## Plans state invariants, not just steps
67
68 A plan in `docs/superpowers/plans/` is a hypothesis, not an authority. The only
69 bug in the lease slice came from a plan step that was implemented faithfully
70 (2026-09-06: it said delete the row, which resets the fencing counter). So:
71
72 - Write the **invariant** beside the steps that must preserve it, and check new
73 steps against `CLAUDE.md`'s invariants section.
74 - A step that contradicts an invariant is a **bug in the plan**, to be fixed in
75 the plan document — not worked around in the code.
76 - Before writing the happy path, enumerate the **boundary members**: empty,
77 single, first/root, duplicate or already-seen, freed-then-reused. Five
78 file-history bugs and one lease bug were all this one shape.
79
80 ## Pairing and review
81
82 **Independent review is the goal; sequential self-review is the fallback.**
83 Where subagents are available, use one economical implementer and one capable
84 adversarial reviewer, give each the deliverable, file paths, edit ownership,
85 constraints, acceptance checks, and its partner's name, and have the reviewer
86 send concrete findings — trigger, consequence, expected behaviour — directly to
87 the implementer. Re-review changed parts, not the whole slice, each round.
88
89 Where they are not available (the common case in this repo today), implement
90 and then make a **separate, deliberately hostile review pass** over the diff,
91 and **disclose that the review was not independent**. Do not claim a check ran
92 that did not. Keep the same acceptance scenarios, gates, demo, and
93 retrospective either way.
94
95 Escalate a specific hard problem to a stronger model when justified; do not
96 silently inherit an expensive one.
97
98 ## Validation that answers the claim
99
100 Gates: `make lint` before a commit, `make ci` before delivery,
101 `cargo clippy --all-targets` silent. **The baseline is not green** — see
102 `CLAUDE.md`'s Gates section for the ten known failures and why. Consequences
103 for this workflow:
104
105 - `cargo test --no-fail-fast` is the only way to see every target.
106 - A new failure must be told apart from those ten **by name**, and named in the
107 report. "Same as before" is not a verification.
108 - Never answer "did I break this?" by touching the index or HEAD. Use
109 `git worktree add --detach /tmp/base-check <ref>`.
110
111 Ask the outside about the inside — a component reporting on itself cannot catch
112 itself being wrong. In this repo that means:
113
114 - Keys come from `ssh-keygen`, never our own encoder; SSH behaviour is asserted
115 through the real `ssh` client, and git behaviour through real `git`.
116 - Server work goes through `tests/common/mod.rs::ServerHarness`, which runs a
117 real `git-collab-server` subprocess. A claim about two principals racing
118 needs two authorized keys, not one key twice.
119 - `--json` output is the machine-checkable oracle; assert on it rather than on
120 prose. Prose abbreviates ids, JSON does not.
121 - Capture `$?` before piping: `cargo test | grep -c ok` reports grep's status.
122
123 ## Demonstrating a CLI and a web UI
124
125 git-collab has no GUI to record, so a demo is:
126
127 - **Transcripts** of the real binaries doing the real thing, including the
128 failure paths — a refused claim and a lost race, not only the happy one.
129 - **Rendered pages** from a live server for anything the web UI shows.
130 - **`README.md` checked against reality.** It is where a claim about the CLI's
131 output gets verified; writing the section is how the un-abbreviated lease ids
132 were caught. If the README and the binary disagree, one of them is a bug.
133
134 Do not quote a performance number measured in a debug build.
135
136 ## Repository hygiene
137
138 - **Branch before the first commit of a slice.** Committing onto the base
139 branch renders an empty diff in Delta's Changes view while the work piles up
140 invisibly.
141 - **Stage by path, never `git add -A`.**
142 - Commit messages are plain imperative ("Enforce one review vote per author per
143 revision"). Keep each task's commit separate; the history should tell the
144 feature's story.
145 - Do not embed current phase numbers, commit ids, or temporary URLs in this
146 skill.
.gitignore
Old New
@@ -1,3 +1,7 @@
1 /target 1 /target
2 /man 2 /man
3 /.claude/worktrees/ 3 /.claude/worktrees/
4 # Agent scratch: tool markers and brainstorm state, not project files.
5 # Untracked and unignored is how `git add -A` once swept these into a commit.
6 /.codex
7 /.superpowers/
AGENTS.md
Old New
@@ -0,0 +1,14 @@
1 # Agent instructions
2
3 Read [CLAUDE.md](CLAUDE.md) for this repository's invariants, working rules,
4 gates and context hazards; those instructions apply to every coding agent.
5 The invariants section is load-bearing — a plan step that contradicts one is a
6 bug in the plan.
7
8 When the user asks for sprint delivery, read and follow
9 [the sprint-delivery skill](.agents/skills/sprint-delivery/SKILL.md). It is
10 ordinary Markdown and can be followed without a skill loader. Ordinary
11 isolated edits do not require the sprint workflow.
12
13 Before scoping a slice, read the open actions and retained debt in
14 [RETRO.md](RETRO.md).
RETRO.md
Old New
@@ -111,9 +111,11 @@ judgement or process.
111 - [ ] Add a `make base-check REF=<ref>` target wrapping 111 - [ ] Add a `make base-check REF=<ref>` target wrapping
112 `git worktree add --detach` + test + `worktree remove`, so the safe way to 112 `git worktree add --detach` + test + `worktree remove`, so the safe way to
113 inspect a baseline is one command. A note alone demonstrably did not hold. 113 inspect a baseline is one command. A note alone demonstrably did not hold.
114 - [ ] Add the boundary-member checklist (empty, single, first/root, 114 - [x] Add the boundary-member checklist (empty, single, first/root,
115 duplicate/already-seen, freed-then-reused) to the plan-writing routine, and 115 duplicate/already-seen, freed-then-reused) to the plan-writing routine, and
116 require plans to state invariants beside steps. 116 require plans to state invariants beside steps. Evidence: the "Plans state
117 invariants, not just steps" section of
118 `.agents/skills/sprint-delivery/SKILL.md`, adopted 2026-09-06.
117 119
118 ### Retained debt 120 ### Retained debt
119 121
@@ -130,6 +132,7 @@ judgement or process.
130 at any plausible size (one row per ever-claimed issue) and deliberate — the 132 at any plausible size (one row per ever-claimed issue) and deliberate — the
131 rows carry the fencing high-water mark — but it is unbounded growth with no 133 rows carry the fencing high-water mark — but it is unbounded growth with no
132 sweeper. 134 sweeper.
133 - **Whoever tracks this file:** `RETRO.md` is still untracked in git. An 135 - **Whoever runs the next slice:** the sprint-delivery workflow is adopted but
134 untracked retro cannot be reviewed, referenced from a commit, or read by 136 unexercised — no slice has been delivered under it, and its independent-review
135 anyone else, which is part of why its lessons did not propagate. 137 step degrades to a disclosed self-review while subagents are unavailable here.
138 The first real use is also its test.