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/README.md CHANGED
@@ -1,3 +1,760 @@
1
- # Temporary Holding Version
1
+ # couch-potator
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.