couch-potator 0.0.0-stage → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +759 -2
- package/dist/assets/app.js +994 -0
- package/dist/assets/index.html +41 -0
- package/dist/assets/style.css +1161 -0
- package/dist/assets/vendor/marked.umd.js +75 -0
- package/dist/assets/vendor/purify.min.js +7 -0
- package/dist/cli.js +5131 -0
- package/package.json +42 -4
package/README.md
CHANGED
|
@@ -1,3 +1,760 @@
|
|
|
1
|
-
#
|
|
1
|
+
# couch-potator
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**A spec board that lives in your repository.**
|
|
4
|
+
|
|
5
|
+
Plain-markdown cards, a read-only viewer, and OpenCode skills that take an idea
|
|
6
|
+
from discovery to a verified, squash-merged change — without a database, a
|
|
7
|
+
server, or a background process.
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
board/
|
|
11
|
+
├── todo/*.md
|
|
12
|
+
├── in-progress/*.md
|
|
13
|
+
├── blocked/*.md
|
|
14
|
+
└── done/*.md
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The folder is the status. The file name is the id. The frontmatter is the
|
|
18
|
+
metadata. The body is the spec. Your editor, `git diff` and `grep` all work on
|
|
19
|
+
it, and so does an agent.
|
|
20
|
+
|
|
21
|
+
## Contents
|
|
22
|
+
|
|
23
|
+
- [Why couch-potator](#why-couch-potator)
|
|
24
|
+
- [Install](#install)
|
|
25
|
+
- [Five-minute tour](#five-minute-tour)
|
|
26
|
+
- [How a card works](#how-a-card-works)
|
|
27
|
+
- [Planning with an agent](#planning-with-an-agent)
|
|
28
|
+
- [Unblocking a card](#unblocking-a-card)
|
|
29
|
+
- [Implementing with an agent](#implementing-with-an-agent)
|
|
30
|
+
- [Command reference](#command-reference)
|
|
31
|
+
- [Recipes](#recipes)
|
|
32
|
+
- [Milestones](#milestones)
|
|
33
|
+
- [Ready cards and the implement queue](#ready-cards-and-the-implement-queue)
|
|
34
|
+
- [Verification checks](#verification-checks)
|
|
35
|
+
- [The viewer](#the-viewer)
|
|
36
|
+
- [Dependency graph](#dependency-graph)
|
|
37
|
+
- [Configuration](#configuration)
|
|
38
|
+
- [Shell completions](#shell-completions)
|
|
39
|
+
- [Design notes](#design-notes)
|
|
40
|
+
- [Development](#development)
|
|
41
|
+
- [License](#license)
|
|
42
|
+
|
|
43
|
+
## Why couch-potator
|
|
44
|
+
|
|
45
|
+
Most project trackers are a database with a web UI. Your specs live somewhere
|
|
46
|
+
else, your agents cannot read them, and the board drifts from the code.
|
|
47
|
+
|
|
48
|
+
couch-potator keeps the board in the same repository as the code:
|
|
49
|
+
|
|
50
|
+
- **One project, one board.** No workspaces, no slugs, no multi-tenant config.
|
|
51
|
+
The board and the app share one git history.
|
|
52
|
+
- **The board is the source of truth.** Cards are written in plain language:
|
|
53
|
+
what the owner will see and how to check it. No framework names, no file
|
|
54
|
+
layout, no implementation detail.
|
|
55
|
+
- **Agents get a contract.** Four OpenCode skills (mechanics, planning,
|
|
56
|
+
unblocking, implementation) and two subagents read the same board you do. The
|
|
57
|
+
implementer works in a git worktree, verifies acceptance criteria and merges
|
|
58
|
+
one card at a time.
|
|
59
|
+
- **Nothing to run.** `view` writes one self-contained HTML file; everything
|
|
60
|
+
else is a short-lived CLI command.
|
|
61
|
+
|
|
62
|
+
If it is not on the board, it is not planned. If it is not verified, it is not
|
|
63
|
+
done.
|
|
64
|
+
|
|
65
|
+
## Install
|
|
66
|
+
|
|
67
|
+
This is a local release: it is **not on the npm registry yet**. Install it from
|
|
68
|
+
a checkout:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
git clone <this-repo> couch-potator
|
|
72
|
+
cd couch-potator
|
|
73
|
+
npm install
|
|
74
|
+
npm run build
|
|
75
|
+
npm link # exposes the `couch-potator` command on your PATH
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Then run `couch-potator init` inside the project you are building. To skip the
|
|
79
|
+
global link, use `node /path/to/couch-potator/dist/cli.js <command>`.
|
|
80
|
+
|
|
81
|
+
Once published, `npm install -g couch-potator` and `npx couch-potator` will work
|
|
82
|
+
as usual.
|
|
83
|
+
|
|
84
|
+
Node 20 or newer.
|
|
85
|
+
|
|
86
|
+
## Five-minute tour
|
|
87
|
+
|
|
88
|
+
This walkthrough builds a tiny reading-list app. Every command runs inside the
|
|
89
|
+
project you are building.
|
|
90
|
+
|
|
91
|
+
### 1. Start the board
|
|
92
|
+
|
|
93
|
+
```sh
|
|
94
|
+
mkdir reading-list && cd reading-list
|
|
95
|
+
git init
|
|
96
|
+
couch-potator init --name "Reading List"
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
`init` scaffolds the board, the brief, the config, the viewer target, the
|
|
100
|
+
`.gitignore` entries and the OpenCode agent files:
|
|
101
|
+
|
|
102
|
+
```text
|
|
103
|
+
board/{todo,in-progress,blocked,done}/
|
|
104
|
+
PROJECT.md # name, milestone, brief
|
|
105
|
+
.couch-potator/config.json # paths and verification checks
|
|
106
|
+
.couch-potator/templates/card.md # default spec body for `add`
|
|
107
|
+
.opencode/skills/couch-potator-board/SKILL.md # board mechanics
|
|
108
|
+
.opencode/skills/couch-potator-planner/SKILL.md # product planning
|
|
109
|
+
.opencode/skills/couch-potator-unblock/SKILL.md # re-planning a blocked card
|
|
110
|
+
.opencode/skills/couch-potator-implement/SKILL.md # implementation orchestration
|
|
111
|
+
.opencode/commands/unblock.md # /unblock prompt
|
|
112
|
+
.opencode/commands/implement.md # /implement prompt
|
|
113
|
+
.opencode/agents/couch-potator-implementer.md # one-card worker subagent
|
|
114
|
+
.opencode/agents/couch-potator-integrator.md # rebase triage subagent
|
|
115
|
+
AGENTS.md # managed board block
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`.couch-potator/viewer/` and `.couch-potator/worktrees/` are appended to
|
|
119
|
+
`.gitignore`. Commit `board/`, `PROJECT.md` and the config; leave the generated
|
|
120
|
+
page and the implementation worktrees out.
|
|
121
|
+
|
|
122
|
+
### 2. Add a few cards
|
|
123
|
+
|
|
124
|
+
A card is one observable outcome. Give it a kind, a milestone, a priority and
|
|
125
|
+
the surface it changes:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
couch-potator add "Reading list page" -k foundation -m 1 -p must -s list-screen
|
|
129
|
+
couch-potator add "Add a book" -k feature -m 1 -p must -s add-form
|
|
130
|
+
couch-potator add "Mark a book as read" -k feature -m 1 -p should -s list-screen
|
|
131
|
+
couch-potator add "Remember books between launches" -k foundation -m 1 -p must
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Then record what waits for what:
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
couch-potator dep add add-a-book reading-list-page
|
|
138
|
+
couch-potator dep add mark-a-book-as-read add-a-book
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`list` shows the board:
|
|
142
|
+
|
|
143
|
+
```text
|
|
144
|
+
COLUMN ID KIND M TITLE
|
|
145
|
+
Todo reading-list-page foundation 1 Reading list page
|
|
146
|
+
Todo add-a-book feature 1 Add a book
|
|
147
|
+
Todo mark-a-book-as-read feature 1 Mark a book as read
|
|
148
|
+
Todo remember-books-between-launches foundation 1 Remember books between launches
|
|
149
|
+
|
|
150
|
+
4 of 4 cards · 1 milestone
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### 3. Write the spec
|
|
154
|
+
|
|
155
|
+
`add` seeds the full spec body from `.couch-potator/templates/card.md`. Fill one
|
|
156
|
+
in with your editor:
|
|
157
|
+
|
|
158
|
+
```sh
|
|
159
|
+
couch-potator edit reading-list-page
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Or replace the body from a file or stdin:
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
couch-potator body reading-list-page --file specs/reading-list-page.md
|
|
166
|
+
couch-potator body reading-list-page --file - < specs/reading-list-page.md
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
A finished card looks like this:
|
|
170
|
+
|
|
171
|
+
```markdown
|
|
172
|
+
---
|
|
173
|
+
id: reading-list-page
|
|
174
|
+
title: Reading list page
|
|
175
|
+
kind: foundation
|
|
176
|
+
milestone: 1
|
|
177
|
+
priority: must
|
|
178
|
+
order: 10
|
|
179
|
+
depends_on: []
|
|
180
|
+
related: []
|
|
181
|
+
surfaces: [list-screen]
|
|
182
|
+
created: 2026-11-16
|
|
183
|
+
updated: 2026-11-16
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Summary
|
|
187
|
+
|
|
188
|
+
Opening the app shows every saved book as a list.
|
|
189
|
+
|
|
190
|
+
## Why
|
|
191
|
+
|
|
192
|
+
It is the home screen. Without it there is nothing to add a book to.
|
|
193
|
+
|
|
194
|
+
## User story
|
|
195
|
+
|
|
196
|
+
As a reader, I want to see the books I have saved so that I can pick one up.
|
|
197
|
+
|
|
198
|
+
## Acceptance criteria
|
|
199
|
+
|
|
200
|
+
- [ ] Opening the app shows a list of saved books, newest first.
|
|
201
|
+
- [ ] Each row shows the title, the author and whether it is finished.
|
|
202
|
+
- [ ] An empty list explains how to add the first book.
|
|
203
|
+
|
|
204
|
+
## Out of scope
|
|
205
|
+
|
|
206
|
+
- Search, sorting and filters.
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### 4. Check, queue and view
|
|
210
|
+
|
|
211
|
+
```sh
|
|
212
|
+
couch-potator check # ids, links, cycles, orders, surface collisions
|
|
213
|
+
couch-potator next # what is ready to build, in what order
|
|
214
|
+
couch-potator view # generate and open the board
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
`next` reads the current milestone and prints a build plan:
|
|
218
|
+
|
|
219
|
+
```text
|
|
220
|
+
Reading List — milestone 1
|
|
221
|
+
Milestone: 0 done · 0 in progress · 0 blocked · 4 todo
|
|
222
|
+
Parallel: 1 slot(s), 1 free
|
|
223
|
+
Next: reading-list-page — Reading list page (must)
|
|
224
|
+
|
|
225
|
+
Batch (1 of 1 free slot(s))
|
|
226
|
+
- reading-list-page — Reading list page (must) [list-screen]
|
|
227
|
+
|
|
228
|
+
Held back
|
|
229
|
+
- remember-books-between-launches — does not declare surfaces; add them to run it alongside another card
|
|
230
|
+
|
|
231
|
+
Waiting
|
|
232
|
+
- add-a-book — Add a book; waiting on reading-list-page (todo)
|
|
233
|
+
- mark-a-book-as-read — Mark a book as read; waiting on add-a-book (todo)
|
|
234
|
+
|
|
235
|
+
Blocked
|
|
236
|
+
- none
|
|
237
|
+
|
|
238
|
+
In progress
|
|
239
|
+
- none
|
|
240
|
+
|
|
241
|
+
Done
|
|
242
|
+
- none
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
### 5. Build it
|
|
246
|
+
|
|
247
|
+
In an OpenCode session in the project:
|
|
248
|
+
|
|
249
|
+
```text
|
|
250
|
+
/implement
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
The skill asks for your verification commands once, then builds the ready cards
|
|
254
|
+
one at a time, verifying each against its acceptance criteria. When it finishes,
|
|
255
|
+
the card has moved to `done/` with a verification note and the code is merged.
|
|
256
|
+
|
|
257
|
+
Refresh the viewer and the card is in the last column.
|
|
258
|
+
|
|
259
|
+
## How a card works
|
|
260
|
+
|
|
261
|
+
```markdown
|
|
262
|
+
---
|
|
263
|
+
id: add-a-book
|
|
264
|
+
title: Add a book
|
|
265
|
+
kind: feature # foundation | design | feature | quality | release | fix
|
|
266
|
+
milestone: 1
|
|
267
|
+
priority: must # must | should | could
|
|
268
|
+
order: 20 # position inside a column
|
|
269
|
+
depends_on: [reading-list-page]
|
|
270
|
+
related: [book-details]
|
|
271
|
+
surfaces: [add-form] # what the owner can point at
|
|
272
|
+
blocked_reason:
|
|
273
|
+
completed:
|
|
274
|
+
resolution:
|
|
275
|
+
created: 2026-11-16
|
|
276
|
+
updated: 2026-11-16
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## Summary
|
|
280
|
+
## Why
|
|
281
|
+
## User story
|
|
282
|
+
## What
|
|
283
|
+
## Acceptance criteria
|
|
284
|
+
## Out of scope
|
|
285
|
+
## Dependencies
|
|
286
|
+
## Decisions
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
| Field | Meaning |
|
|
290
|
+
| --- | --- |
|
|
291
|
+
| `kind` | `foundation`, `design`, `feature`, `quality`, `release` or `fix`. Used for colour, ordering and filtering. |
|
|
292
|
+
| `milestone` | Whole number. Only the current milestone is built. |
|
|
293
|
+
| `priority` | `must`, `should` or `could`. Drives the implement queue. |
|
|
294
|
+
| `order` | Position inside a column; `move` renumbers both columns. |
|
|
295
|
+
| `depends_on` | Cards that must be `done/` first. Cycles are rejected. |
|
|
296
|
+
| `related` | Loose links shown as chips; not a build dependency. |
|
|
297
|
+
| `surfaces` | What the owner can point at (`list-screen`, `settings`, `billing`). Two cards that share one never build at the same time. |
|
|
298
|
+
| `blocked_reason` | Why the card sits in `blocked/`. |
|
|
299
|
+
| `completed` / `resolution` | Filled by the implementer when the card lands. |
|
|
300
|
+
|
|
301
|
+
A surface is one token: `-s list-screen`. Pass `-s` once per surface
|
|
302
|
+
(`-s list-screen -s add-form`) or comma-separate them
|
|
303
|
+
(`-s list-screen,add-form`).
|
|
304
|
+
|
|
305
|
+
`status` is never stored: the folder is the status. Unknown frontmatter keys are
|
|
306
|
+
preserved on every write, so custom fields survive `set`, `move` and `body`.
|
|
307
|
+
|
|
308
|
+
The body is a plain-language contract:
|
|
309
|
+
|
|
310
|
+
- **Summary** — the outcome in one or two sentences.
|
|
311
|
+
- **Why** — the problem and who feels it.
|
|
312
|
+
- **User story** — the person, the outcome and the reason, plus a short narrative.
|
|
313
|
+
- **What** — observable behaviour only. No frameworks, no file layout.
|
|
314
|
+
- **Acceptance criteria** — 3–7 things a person can check.
|
|
315
|
+
- **Out of scope** — what this card deliberately does not do.
|
|
316
|
+
- **Dependencies** — the card ids it waits for, if the graph is not enough.
|
|
317
|
+
- **Decisions** — dated answers the owner gave.
|
|
318
|
+
|
|
319
|
+
Edit `.couch-potator/templates/card.md` to change the default body for new
|
|
320
|
+
cards.
|
|
321
|
+
|
|
322
|
+
## Planning with an agent
|
|
323
|
+
|
|
324
|
+
`init` installs four OpenCode skills:
|
|
325
|
+
|
|
326
|
+
| Skill | Job |
|
|
327
|
+
| --- | --- |
|
|
328
|
+
| `couch-potator-board` | Board mechanics: read, add, body, move, link, validate, view. |
|
|
329
|
+
| `couch-potator-planner` | Product planning: discovery, specs, milestones, questions, review. |
|
|
330
|
+
| `couch-potator-unblock` | Unblocking: explain the block, ask the open questions, record the answers, return the card to `todo`. |
|
|
331
|
+
| `couch-potator-implement` | Implementation: pick ready cards, run one worker per card in its own worktree, verify, merge one at a time. |
|
|
332
|
+
|
|
333
|
+
The planner is the product manager. It does not write your product's code. It:
|
|
334
|
+
|
|
335
|
+
- reads `PROJECT.md` and the board before every session;
|
|
336
|
+
- asks the owner questions in small batches through OpenCode's `question` tool,
|
|
337
|
+
with concrete options and a recommendation;
|
|
338
|
+
- writes cards and the brief as the answers arrive, not at the end;
|
|
339
|
+
- uses `couch-potator` for every card change;
|
|
340
|
+
- puts ready cards in `todo/` and cards with an open question in `blocked/`;
|
|
341
|
+
- stops when the owner agrees the current milestone is enough.
|
|
342
|
+
|
|
343
|
+
It discusses only *what* and *why*. Frameworks, libraries, file layout and code
|
|
344
|
+
belong to the implementer, not the planner.
|
|
345
|
+
|
|
346
|
+
To start, open an OpenCode session in the project and ask:
|
|
347
|
+
|
|
348
|
+
```text
|
|
349
|
+
Use the couch-potator-planner skill. This is a reading-list app for one person.
|
|
350
|
+
Plan milestone 1 with me, a few questions at a time.
|
|
351
|
+
```
|
|
352
|
+
|
|
353
|
+
If the board is missing, run `couch-potator init` first. The planner will tell
|
|
354
|
+
you the same.
|
|
355
|
+
|
|
356
|
+
The planner fills `PROJECT.md` with vision, audience, journeys, non-goals,
|
|
357
|
+
constraints, stack decisions, design direction, glossary, milestones, decisions,
|
|
358
|
+
open questions, working state and later ideas. It never overwrites an existing
|
|
359
|
+
brief.
|
|
360
|
+
|
|
361
|
+
## Unblocking a card
|
|
362
|
+
|
|
363
|
+
A blocked card carries a `blocked_reason` and a `## Decision needed` section
|
|
364
|
+
with the owner's open questions. Start an unblock session with:
|
|
365
|
+
|
|
366
|
+
```text
|
|
367
|
+
/unblock # list the blocked cards and ask which one
|
|
368
|
+
/unblock <card> # unblock one card
|
|
369
|
+
/unblock all # every blocked card, one at a time, in id order
|
|
370
|
+
/unblock all -m 2 # only milestone 2
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
The `couch-potator-unblock` skill shows the reason and the open questions before
|
|
374
|
+
asking anything, then asks in small batches through OpenCode's `question` tool,
|
|
375
|
+
with a recommendation for each. It writes every answer to the card's
|
|
376
|
+
`## Decisions` and, when the answer is project-wide, to the decision log in
|
|
377
|
+
`PROJECT.md`. It then clears `blocked_reason`, removes the answered
|
|
378
|
+
`## Decision needed` section, and moves the card to `todo/` once it meets the
|
|
379
|
+
Definition of Ready. If an answer is still missing, the card stays in
|
|
380
|
+
`blocked/` with only the remaining question.
|
|
381
|
+
|
|
382
|
+
It never builds. The skill is hidden from automatic selection; `/unblock` loads
|
|
383
|
+
it explicitly.
|
|
384
|
+
|
|
385
|
+
## Implementing with an agent
|
|
386
|
+
|
|
387
|
+
`couch-potator-implement` is the build counterpart to the planner. It reads the
|
|
388
|
+
board, picks the next ready cards, gives each one to a **fresh implementer
|
|
389
|
+
subagent** in its own git worktree, verifies the acceptance criteria, and merges
|
|
390
|
+
the cards into the base branch one at a time.
|
|
391
|
+
|
|
392
|
+
```text
|
|
393
|
+
/implement # build the current milestone, one card at a time
|
|
394
|
+
/implement --parallel 2 # up to two cards at once (the hard cap is 3)
|
|
395
|
+
/implement --one # stop after one batch is integrated
|
|
396
|
+
/implement --dry-run # print the plan and change nothing
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
It never writes your product's code itself, never invents product behaviour and
|
|
400
|
+
never starts the next milestone. If the board is ambiguous it stops and asks,
|
|
401
|
+
through the same `question` tool the planner uses.
|
|
402
|
+
|
|
403
|
+
Before the first run it asks for the verification commands once and stores them
|
|
404
|
+
with `couch-potator checks` (see [Verification checks](#verification-checks)).
|
|
405
|
+
`fast` commands run on every card branch, after every rebase and after every
|
|
406
|
+
merge; `full` commands run once when the milestone is built.
|
|
407
|
+
|
|
408
|
+
How a run works:
|
|
409
|
+
|
|
410
|
+
1. It reads `PROJECT.md` and the board, and refuses to start on validation
|
|
411
|
+
errors, a dirty git tree or a non-`active` project.
|
|
412
|
+
2. `couch-potator next` picks the batch: current milestone only, dependencies
|
|
413
|
+
done, ordered by priority, board order, kind and id, with cards that share a
|
|
414
|
+
`surface` kept apart.
|
|
415
|
+
3. Each card moves to `in-progress/` and gets a branch `spec/<card-id>` and a
|
|
416
|
+
worktree at `.couch-potator/worktrees/spec-<card-id>`.
|
|
417
|
+
4. One worker per card implements **one** card, runs the fast checks and returns
|
|
418
|
+
a `STATUS: DONE` or `STATUS: BLOCKED` report.
|
|
419
|
+
5. The orchestrator reviews the diff, runs the fast checks, checks every
|
|
420
|
+
acceptance criterion and rebases onto the current base. A conflicted rebase
|
|
421
|
+
goes to the `couch-potator-integrator` subagent, which may only make
|
|
422
|
+
*mechanical* adaptations; a product conflict blocks the card.
|
|
423
|
+
6. The card is squash-merged as one commit, moved to `done/` with a
|
|
424
|
+
`## Verification` section, and the worktree and branch are removed.
|
|
425
|
+
7. Blocked cards go to `blocked/` with a `## Decision needed` section; the
|
|
426
|
+
branch is kept so the work survives.
|
|
427
|
+
|
|
428
|
+
It never pushes, never forces, never merges two branches at once, and never
|
|
429
|
+
marks a card done without verification. Only a single-worker run may launch the
|
|
430
|
+
app for visual checks; with more workers, the orchestrator does it after the
|
|
431
|
+
batch returns.
|
|
432
|
+
|
|
433
|
+
If the project root is not a git repository yet, the skill initializes one
|
|
434
|
+
automatically — but it stops and asks if the staged files look like secrets or
|
|
435
|
+
build output, or if no git identity is configured.
|
|
436
|
+
|
|
437
|
+
## Command reference
|
|
438
|
+
|
|
439
|
+
Global flags work anywhere: `--root <path>`, `--help`, `--version`.
|
|
440
|
+
|
|
441
|
+
Exit codes: `0` success, `1` invalid board or failed validation, `2` usage error
|
|
442
|
+
(unknown card, unknown column, bad flag).
|
|
443
|
+
|
|
444
|
+
### Scaffold and inspect
|
|
445
|
+
|
|
446
|
+
| Command | Effect |
|
|
447
|
+
| --- | --- |
|
|
448
|
+
| `couch-potator init [--name <n>] [--no-skill] [--force]` | Scaffold a board in the current folder. Idempotent; never overwrites `PROJECT.md`. `--no-skill` skips the agent files; `--force` rewrites them. |
|
|
449
|
+
| `couch-potator list [-c <col>] [-m <n>] [-k <kind>] [--all] [--json] [--ids]` | List cards, sorted by status, then `order`, then title. |
|
|
450
|
+
| `couch-potator show <card> [--raw\|--path\|--json]` | Print a spec, its file path or its JSON. `<card>` may be an id or a unique prefix. |
|
|
451
|
+
| `couch-potator check [--strict] [--json]` | Validate ids, links, cycles, orders, columns and in-progress surface collisions. Exit 1 on errors; `--strict` also fails on warnings. |
|
|
452
|
+
| `couch-potator next [--parallel <1-3>] [--json]` | Pick the next ready cards, in dependency/priority/order/kind order, and report the batch, held-back, waiting, blocked and in-progress cards. |
|
|
453
|
+
| `couch-potator graph [--format text\|mermaid\|dot] [-m <n>]` | Print the dependency graph without a browser. |
|
|
454
|
+
| `couch-potator view [--watch] [--no-open] [--milestone <n\|all>] [--out <path>]` | Generate and open the read-only viewer. |
|
|
455
|
+
|
|
456
|
+
### Cards
|
|
457
|
+
|
|
458
|
+
| Command | Effect |
|
|
459
|
+
| --- | --- |
|
|
460
|
+
| `couch-potator add "<title>" [-c todo] [-k feature] [-m 1] [-p must] [-o 10] [-s <surface>]... [-d <card>]... [-r <card>]... [--body <file\|->] [--json]` | Create a card. `-c` accepts `wip`/`inprogress` for `in-progress`. Repeat `-d` and `-r`; `-s` may repeat or be comma-separated. |
|
|
461
|
+
| `couch-potator body <card> --file <file\|->` | Replace a card body. Use `-` to read stdin. |
|
|
462
|
+
| `couch-potator move <card> <column> [--top\|--bottom\|--before <card>\|--after <card>]` | Move a card and renumber both columns. |
|
|
463
|
+
| `couch-potator set <card> <field> <value>` | Set `kind`, `milestone`, `priority`, `order`, `title`, `surfaces`, `blocked_reason`, `resolution` or `completed`. Use `-` to clear. |
|
|
464
|
+
| `couch-potator edit <card>` | Open the spec in `$VISUAL`/`$EDITOR`. |
|
|
465
|
+
| `couch-potator rm <card> [--force]` | Delete a card. |
|
|
466
|
+
|
|
467
|
+
### Relationships
|
|
468
|
+
|
|
469
|
+
| Command | Effect |
|
|
470
|
+
| --- | --- |
|
|
471
|
+
| `couch-potator dep add\|rm <card> <card>` / `dep <card>` | Edit or list `depends_on`. Cycles are rejected. |
|
|
472
|
+
| `couch-potator rel add\|rm <card> <card>` / `rel <card>` | Edit or list `related`. |
|
|
473
|
+
|
|
474
|
+
### Agents and shell
|
|
475
|
+
|
|
476
|
+
| Command | Effect |
|
|
477
|
+
| --- | --- |
|
|
478
|
+
| `couch-potator checks [--json]` / `checks set <fast\|full> <name> "<command>"` / `checks clear <fast\|full> [name]` | Show or edit the verification commands the implement skill runs. |
|
|
479
|
+
| `couch-potator skill install [--force]` | (Re)install every OpenCode agent file and the `AGENTS.md` block. |
|
|
480
|
+
| `couch-potator completion [install] [bash\|zsh\|fish] [--print] [--no-rc]` | Print or install shell completions (`sh` maps to bash). |
|
|
481
|
+
|
|
482
|
+
## Recipes
|
|
483
|
+
|
|
484
|
+
```sh
|
|
485
|
+
# Add a card that waits for another, on a surface it changes
|
|
486
|
+
couch-potator add "Checkout" -k feature -m 1 -p must -d cart -s checkout
|
|
487
|
+
|
|
488
|
+
# Move a card to the top of its column
|
|
489
|
+
couch-potator move checkout in-progress --top
|
|
490
|
+
|
|
491
|
+
# Read the raw markdown, or just the path, for an agent or a diff
|
|
492
|
+
couch-potator show checkout --raw
|
|
493
|
+
couch-potator show checkout --path
|
|
494
|
+
|
|
495
|
+
# Every todo id in the current milestone, one per line
|
|
496
|
+
couch-potator list -c todo -m 1 --ids
|
|
497
|
+
|
|
498
|
+
# The whole board as JSON
|
|
499
|
+
couch-potator list --json
|
|
500
|
+
|
|
501
|
+
# A milestone's dependency graph as Mermaid or Graphviz
|
|
502
|
+
couch-potator graph -m 1 --format mermaid
|
|
503
|
+
couch-potator graph -m 1 --format dot
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
## Milestones
|
|
507
|
+
|
|
508
|
+
Milestones are whole numbers. The set in the viewer is the union of the values in
|
|
509
|
+
`PROJECT.md` (`current_milestone` and the optional `milestones: [1, 2]` list) and
|
|
510
|
+
the `milestone` of every card, so you can declare a milestone before its first
|
|
511
|
+
card.
|
|
512
|
+
|
|
513
|
+
Only `current_milestone` is built. When every card in it is `done/`, the
|
|
514
|
+
implement skill runs the full checks once and stops for review. It never moves
|
|
515
|
+
the pointer to the next milestone — that is a planning decision.
|
|
516
|
+
|
|
517
|
+
The viewer opens on `current_milestone`, falling back to the newest milestone.
|
|
518
|
+
The header dropdown filters cards and graph together; the choice is kept in the
|
|
519
|
+
URL hash. Cards with no milestone only appear under **All milestones**.
|
|
520
|
+
|
|
521
|
+
```sh
|
|
522
|
+
couch-potator list -m 2 # one milestone
|
|
523
|
+
couch-potator view -m all # every card
|
|
524
|
+
couch-potator graph -m 2 # the milestone's dependency graph
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
## Ready cards and the implement queue
|
|
528
|
+
|
|
529
|
+
`couch-potator next` is the implementation planner. It reads the current
|
|
530
|
+
milestone from `PROJECT.md` and picks the cards that are ready to build:
|
|
531
|
+
|
|
532
|
+
- a card is ready when it is in `todo/` for the current milestone, has no open
|
|
533
|
+
question, and every card in its `depends_on` is `done/`;
|
|
534
|
+
- ready cards are ordered by priority (`must`, `should`, `could`), then the
|
|
535
|
+
board order, then kind (`foundation`, `feature`, `design`, `quality`, `fix`,
|
|
536
|
+
`release`), then id;
|
|
537
|
+
- at most `--parallel` cards are offered (`1` by default, `3` at most), and two
|
|
538
|
+
cards that share a surface never appear in the same batch;
|
|
539
|
+
- a card with no `surfaces` is treated as unknown and offered alone;
|
|
540
|
+
- cards already in `in-progress/` are resumed first and take both a slot and
|
|
541
|
+
their surfaces.
|
|
542
|
+
|
|
543
|
+
A batch is a ceiling, not a target: a single card at width three is normal.
|
|
544
|
+
`--parallel 9` runs three and says so in the warnings.
|
|
545
|
+
|
|
546
|
+
```sh
|
|
547
|
+
couch-potator next --parallel 2
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
```text
|
|
551
|
+
Reading List — milestone 1
|
|
552
|
+
Milestone: 0 done · 0 in progress · 0 blocked · 4 todo
|
|
553
|
+
Parallel: 2 slot(s), 2 free
|
|
554
|
+
Next: reading-list-page — Reading list page (must)
|
|
555
|
+
|
|
556
|
+
Batch (1 of 2 free slot(s))
|
|
557
|
+
- reading-list-page — Reading list page (must) [list-screen]
|
|
558
|
+
|
|
559
|
+
Held back
|
|
560
|
+
- remember-books-between-launches — does not declare surfaces; add them to run it alongside another card
|
|
561
|
+
|
|
562
|
+
Waiting
|
|
563
|
+
- add-a-book — Add a book; waiting on reading-list-page (todo)
|
|
564
|
+
- mark-a-book-as-read — Mark a book as read; waiting on add-a-book (todo)
|
|
565
|
+
…
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
`--json` returns the same information for an agent: `batch`, `held_back` with a
|
|
569
|
+
reason each, `waiting` with the unresolved dependencies, `blocked`, `done`,
|
|
570
|
+
`in_progress`, `eligible`, `slots`, `errors` and `warnings`. The command exits
|
|
571
|
+
`1` when the board has validation errors, so an implementer can stop before
|
|
572
|
+
building.
|
|
573
|
+
|
|
574
|
+
`couch-potator check` validates the board. `couch-potator next` only reads it.
|
|
575
|
+
|
|
576
|
+
## Verification checks
|
|
577
|
+
|
|
578
|
+
`couch-potator check` (singular) validates the board. `couch-potator checks`
|
|
579
|
+
(plural) is the list of commands the implement skill runs to verify a card.
|
|
580
|
+
They live in `.couch-potator/config.json` and are grouped by when they run:
|
|
581
|
+
|
|
582
|
+
- **fast** — install, test, lint and typecheck. Run on every card branch, after
|
|
583
|
+
every rebase and after every merge.
|
|
584
|
+
- **full** — build and package. Run once on the base branch when the milestone
|
|
585
|
+
is complete, not per card.
|
|
586
|
+
|
|
587
|
+
```sh
|
|
588
|
+
couch-potator checks
|
|
589
|
+
couch-potator checks --json
|
|
590
|
+
couch-potator checks set fast install "npm ci"
|
|
591
|
+
couch-potator checks set fast test "npm test"
|
|
592
|
+
couch-potator checks set fast lint "npm run lint"
|
|
593
|
+
couch-potator checks set fast typecheck "npm run typecheck"
|
|
594
|
+
couch-potator checks set full build "npm run build"
|
|
595
|
+
couch-potator checks clear fast lint
|
|
596
|
+
couch-potator checks clear full
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
A stack that does not need a step simply leaves it out; an empty phase is not a
|
|
600
|
+
failed check. `--json` prints `{ "fast": { ... }, "full": { ... } }` for an
|
|
601
|
+
agent. The implement skill asks for the commands once, writes them here, and
|
|
602
|
+
reuses them.
|
|
603
|
+
|
|
604
|
+
## The viewer
|
|
605
|
+
|
|
606
|
+
`couch-potator view` writes one self-contained file to
|
|
607
|
+
`.couch-potator/viewer/board.html`:
|
|
608
|
+
|
|
609
|
+
- cards grouped into the four columns, titles only, coloured by `kind`
|
|
610
|
+
- clicking a card opens the rendered spec with metadata chips, clickable
|
|
611
|
+
`depends_on` / `related` links, `surfaces` chips and the file path
|
|
612
|
+
- `Brief` opens `PROJECT.md`
|
|
613
|
+
- `Cards` / `Graph` toggle
|
|
614
|
+
- `Reload` re-reads the file after you regenerate it
|
|
615
|
+
|
|
616
|
+
```sh
|
|
617
|
+
couch-potator view # write and open
|
|
618
|
+
couch-potator view --no-open # write only
|
|
619
|
+
couch-potator view --watch # rebuild on board changes, then Reload
|
|
620
|
+
```
|
|
621
|
+
|
|
622
|
+
It is structurally read-only: there is no server, no `fetch`, no write endpoint
|
|
623
|
+
and no drag handler. Markdown is rendered with marked and sanitised with
|
|
624
|
+
DOMPurify, both inlined into the page. The page works over `file://`, so it can
|
|
625
|
+
be emailed or committed as a build artifact if you really want to.
|
|
626
|
+
|
|
627
|
+
## Dependency graph
|
|
628
|
+
|
|
629
|
+
`A depends_on B` draws an arrow from `B` to `A` — the arrow points at the
|
|
630
|
+
dependent card. The viewer layers the graph left to right by longest path, and
|
|
631
|
+
hovering a node dims everything except its neighbours.
|
|
632
|
+
|
|
633
|
+
When a milestone is selected, specs from other milestones that a visible card
|
|
634
|
+
depends on (or that depend on it) stay in the graph, drawn faded with dashed
|
|
635
|
+
edges, so cross-milestone dependencies remain traceable.
|
|
636
|
+
|
|
637
|
+
`related` and `surfaces` are not drawn as edges; they appear as chips in the spec
|
|
638
|
+
modal.
|
|
639
|
+
|
|
640
|
+
Without a browser:
|
|
641
|
+
|
|
642
|
+
```sh
|
|
643
|
+
couch-potator graph # indented text
|
|
644
|
+
couch-potator graph -m 1 --format mermaid # paste into a Markdown renderer
|
|
645
|
+
couch-potator graph --format dot # pipe into Graphviz
|
|
646
|
+
```
|
|
647
|
+
|
|
648
|
+
## Configuration
|
|
649
|
+
|
|
650
|
+
`.couch-potator/config.json` is committed to the repository:
|
|
651
|
+
|
|
652
|
+
```json
|
|
653
|
+
{
|
|
654
|
+
"version": 1,
|
|
655
|
+
"board": "board",
|
|
656
|
+
"brief": "PROJECT.md",
|
|
657
|
+
"viewer": {
|
|
658
|
+
"out": ".couch-potator/viewer/board.html"
|
|
659
|
+
},
|
|
660
|
+
"checks": {
|
|
661
|
+
"fast": {
|
|
662
|
+
"test": "npm test",
|
|
663
|
+
"typecheck": "npm run typecheck"
|
|
664
|
+
},
|
|
665
|
+
"full": {
|
|
666
|
+
"build": "npm run build"
|
|
667
|
+
}
|
|
668
|
+
}
|
|
669
|
+
}
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
`board` and `brief` are relative to the project root. Missing keys fall back to
|
|
673
|
+
the defaults above, so an older config keeps working. `checks` is managed by
|
|
674
|
+
`couch-potator checks`; edit it by hand only if you must.
|
|
675
|
+
|
|
676
|
+
`--root <path>` points any command at a different project. Otherwise the CLI
|
|
677
|
+
walks up from the current folder to the nearest board.
|
|
678
|
+
|
|
679
|
+
## Shell completions
|
|
680
|
+
|
|
681
|
+
Install completions for the shell you use:
|
|
682
|
+
|
|
683
|
+
```sh
|
|
684
|
+
couch-potator completion install fish
|
|
685
|
+
couch-potator completion install zsh
|
|
686
|
+
couch-potator completion install bash
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
`completion` with no `install` prints the script instead, and `--print` forces
|
|
690
|
+
printing even with `install`. Use `--no-rc` to write the script without touching
|
|
691
|
+
your shell startup files.
|
|
692
|
+
|
|
693
|
+
| Shell | File | Wiring |
|
|
694
|
+
| --- | --- | --- |
|
|
695
|
+
| fish | `~/.config/fish/completions/couch-potator.fish` | Loaded automatically by fish. |
|
|
696
|
+
| zsh | `~/.config/couch-potator/completion.zsh` | Managed block in `~/.zshrc`. |
|
|
697
|
+
| bash | `~/.local/share/bash-completion/completions/couch-potator` | Managed block in `~/.bashrc`. |
|
|
698
|
+
|
|
699
|
+
The install is idempotent: rerunning it rewrites the script but keeps a single
|
|
700
|
+
managed block, delimited by `# >>> couch-potator completions >>>` and
|
|
701
|
+
`# <<< couch-potator completions <<<`. Restart the shell (or open a new tab)
|
|
702
|
+
after installing.
|
|
703
|
+
|
|
704
|
+
Completions are dynamic: the scripts call a hidden `__complete` command, so card
|
|
705
|
+
ids, milestones, columns, kinds, formats and flags come from the board you are
|
|
706
|
+
standing in. A missing or broken board never breaks the shell; you simply get
|
|
707
|
+
commands and flags.
|
|
708
|
+
|
|
709
|
+
To wire a script by hand:
|
|
710
|
+
|
|
711
|
+
```sh
|
|
712
|
+
source <(couch-potator completion bash)
|
|
713
|
+
source <(couch-potator completion zsh)
|
|
714
|
+
couch-potator completion fish > ~/.config/fish/completions/couch-potator.fish
|
|
715
|
+
```
|
|
716
|
+
|
|
717
|
+
## Design notes
|
|
718
|
+
|
|
719
|
+
- **No SQLite.** The directory tree is the index and frontmatter is the metadata.
|
|
720
|
+
Thousands of cards scan in milliseconds, and there is nothing to invalidate.
|
|
721
|
+
- **No web server.** A generated single-file page does the same job over
|
|
722
|
+
`file://`, with no ports, no daemon, no "already running" state and no
|
|
723
|
+
stale-server failure mode. The cost is that regeneration is explicit.
|
|
724
|
+
- **Files are the source of truth.** The viewer never writes. The CLI can rewrite
|
|
725
|
+
a spec body only through the explicit `body` command.
|
|
726
|
+
- **One project.** A board describes one app. Multi-project layouts are not
|
|
727
|
+
supported on purpose: they make the queue, the milestone pointer and the
|
|
728
|
+
implementer's worktree ambiguous.
|
|
729
|
+
- **The board and the code share one history.** The board-start commit, the
|
|
730
|
+
squash-merge commit and the card's verification note all land together, so a
|
|
731
|
+
`git log` reads as a build log.
|
|
732
|
+
|
|
733
|
+
## Development
|
|
734
|
+
|
|
735
|
+
```sh
|
|
736
|
+
npm install
|
|
737
|
+
npm run build # esbuild bundle to dist/ and copy viewer assets
|
|
738
|
+
npm test # Node's test runner over tests/*.test.ts
|
|
739
|
+
npm run typecheck
|
|
740
|
+
npm run check # typecheck + tests + build
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
The bundle is one `esbuild` invocation (`scripts/build.mjs`). Tests are bundled
|
|
744
|
+
with the same esbuild and executed by `node --test` (`scripts/test.mjs`), so the
|
|
745
|
+
dev toolchain is esbuild plus TypeScript — no separate bundler or test framework
|
|
746
|
+
to keep patched.
|
|
747
|
+
|
|
748
|
+
The viewer assets live in `src/viewer/assets/`; `scripts/build-assets.mjs` copies
|
|
749
|
+
them and the marked/DOMPurify bundles into `dist/assets/` so the published
|
|
750
|
+
package has no runtime frontend dependency.
|
|
751
|
+
|
|
752
|
+
Generated agent files (skills, commands, subagents and the `AGENTS.md` block) are
|
|
753
|
+
templates in `src/templates.ts`. Edit the template, never a generated copy in a
|
|
754
|
+
target project, and update the tests and this README in the same commit.
|
|
755
|
+
|
|
756
|
+
## License
|
|
757
|
+
|
|
758
|
+
MIT — see [LICENSE](LICENSE).
|
|
759
|
+
|
|
760
|
+
Copyright (c) 2026 Fernando Martinez.
|