@marver-design/marver 0.22.0 → 0.23.0
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/CHANGELOG.md +106 -0
- package/README.md +13 -9
- package/dist/agent-BsieQGTD.mjs +99 -0
- package/dist/{bake-BSX4XR_U.mjs → bake-l6N12qgx.mjs} +1 -1
- package/dist/{board-status-CWGHIdo_.mjs → board-status-D_lHZZ09.mjs} +69 -610
- package/dist/{boards-BTGNPVMx.mjs → boards-CahYhF5B.mjs} +3 -1
- package/dist/boards-DbVJlbd5.mjs +612 -0
- package/dist/{build-Dd2Qm3OG.mjs → build-CuRhHXcY.mjs} +10 -6
- package/dist/cli.mjs +22 -12
- package/dist/{comments-ClVgfQib.mjs → comments-0d3e274b.mjs} +71 -9
- package/dist/{config-DJxMRVD8.mjs → config-g-J8NrPn.mjs} +5 -97
- package/dist/{context-DUAENlJ6.mjs → context-fAtQLHt2.mjs} +3 -2
- package/dist/{daemon-BmkwErpC.mjs → daemon-DZ367fiM.mjs} +75 -17
- package/dist/{dev-BW7a5kDF.mjs → dev-R6zvwbqX.mjs} +55 -9
- package/dist/{init-NJ3xjLVu.mjs → init-DAnBlt-V.mjs} +6 -4
- package/dist/{ledger-Bu0BjqIe.mjs → ledger-BNXW14Xw.mjs} +1 -6
- package/dist/link-CcfAfKY-.mjs +132 -0
- package/dist/{manifest-BqBcMJcd.mjs → manifest-BkjJ5OQk.mjs} +73 -5
- package/dist/{plugin-8XntSCx_.mjs → plugin-C1avHL7g.mjs} +357 -31
- package/dist/{poster-DRZDszTI.mjs → poster-Bc4-3DlQ.mjs} +1 -1
- package/dist/{profile-BjAPAJSb.mjs → profile-CrZohD6g.mjs} +1 -1
- package/dist/{publish-bakes-CCWRV9iX.mjs → publish-bakes-DQWn14IY.mjs} +2 -2
- package/dist/{share--bdSc4G5.mjs → share-BD-wcDQq.mjs} +1 -1
- package/dist/{shot-BFEuYbaz.mjs → shot-C1YR_Sqx.mjs} +1 -1
- package/dist/{shot-C22Ues04.mjs → shot-CVOlQHUr.mjs} +2 -2
- package/dist/{sync-BZaCWqK-.mjs → sync-DoA1vf4u.mjs} +15 -1
- package/dist/{work-0YopuMt9.mjs → work-CJ8OIpBD.mjs} +9 -3
- package/dist/{work-CLrmY-vQ.mjs → work-CiUvBVa6.mjs} +72 -1
- package/docs/boards-and-folders.md +54 -6
- package/docs/context.md +10 -2
- package/docs/live-jam.md +11 -0
- package/package.json +1 -1
- package/src/client/content/diagram.tsx +7 -1
- package/src/client/content/img-lod.ts +12 -2
- package/src/client/content/index.tsx +69 -6
- package/src/client/frame-host/inspect.js +23 -0
- package/src/client/shell/App.tsx +19 -9
- package/src/client/shell/BoardList.tsx +21 -6
- package/src/client/shell/LockedApp.tsx +2 -2
- package/src/client/shell/Play.tsx +5 -1
- package/src/client/shell/StatusPicker.tsx +12 -5
- package/src/client/shell/Tip.tsx +25 -5
- package/src/client/shell/board-icons.tsx +15 -1
- package/src/client/shell/canvas/Canvas.tsx +42 -6
- package/src/client/shell/canvas/anchor.ts +41 -0
- package/src/client/shell/canvas/ctl.ts +6 -0
- package/src/client/shell/comments-store.ts +8 -5
- package/src/client/shell/goto.ts +52 -3
- package/src/client/shell/hash.ts +24 -3
- package/src/client/shell/store.ts +242 -28
- package/src/client/shell/styles.css +19 -2
- package/src/shared/board-types.ts +10 -6
- package/src/shared/status.ts +17 -8
- package/templates/AGENTS-embedded.md +54 -8
- package/templates/AGENTS-studio.md +54 -8
- package/templates/instructions/boards.md +15 -3
- package/templates/instructions/context.md +20 -7
- package/templates/instructions/iterate.md +29 -16
- package/templates/instructions/jam.md +9 -2
- package/templates/instructions/reference/deck-layouts.md +2 -1
- package/templates/instructions/reference/deck-story.md +2 -1
package/src/shared/status.ts
CHANGED
|
@@ -5,22 +5,23 @@
|
|
|
5
5
|
*
|
|
6
6
|
* 1-3 the board says archived, paused or blocked (with its reason) - a decision, by hand
|
|
7
7
|
* 4 the evidence it needs cannot be read - Unknown, never a stale Done
|
|
8
|
-
* 5 an open plan names the capability -
|
|
8
|
+
* 5 an open plan names the capability - Building when it says `stage: build`,
|
|
9
|
+
* else In progress, filling by phase
|
|
9
10
|
* 6 the shipped record shows it available, `confirmed` - Done
|
|
10
11
|
* 7 ... `reported` only - Done, reported
|
|
11
12
|
* 8 an accepted contract (`state: current`), no availability - To do
|
|
12
13
|
* 9 anything else - Backlog
|
|
13
14
|
*
|
|
14
|
-
* Without `context/`, a board may also say in-progress, todo or backlog by hand. Done is never
|
|
15
|
+
* Without `context/`, a board may also say in-progress, building, todo or backlog by hand. Done is never
|
|
15
16
|
* set by hand: `"status": "done"` is ignored here and reported by `marver context check`.
|
|
16
17
|
*/
|
|
17
18
|
import { DECISIONS, HAS_STATUS, type BoardType, type StatusWord } from './board-types.ts'
|
|
18
19
|
import { strictest, type Audience, type Level } from './context.ts'
|
|
19
20
|
|
|
20
|
-
export type Status = 'archived' | 'paused' | 'blocked' | 'unknown' | 'in-progress' | 'done' | 'done-reported' | 'todo' | 'backlog'
|
|
21
|
+
export type Status = 'archived' | 'paused' | 'blocked' | 'unknown' | 'in-progress' | 'building' | 'done' | 'done-reported' | 'todo' | 'backlog'
|
|
21
22
|
export const STATUS_LABEL: Record<Status, string> = {
|
|
22
23
|
archived: 'Archived', paused: 'Paused', blocked: 'Blocked', unknown: 'Unknown', 'in-progress': 'In progress',
|
|
23
|
-
done: 'Done', 'done-reported': 'Done, reported', todo: 'To do', backlog: 'Backlog',
|
|
24
|
+
building: 'Building', done: 'Done', 'done-reported': 'Done, reported', todo: 'To do', backlog: 'Backlog',
|
|
24
25
|
}
|
|
25
26
|
|
|
26
27
|
/** A phase, as the fill reads it: 1 spec, 2 lo-fi, 3 hi-fi. */
|
|
@@ -37,8 +38,8 @@ export interface ContextFacts {
|
|
|
37
38
|
shipped: Map<string, { levels: Level[]; where: string; audience: Audience }>
|
|
38
39
|
/** capability -> its contract's state, where, and its audience */
|
|
39
40
|
contracts: Map<string, { state: string; where: string; audience: Audience }>
|
|
40
|
-
/** capability -> its open plans, each with its audience */
|
|
41
|
-
plans: Map<string, { where: string; audience: Audience }[]>
|
|
41
|
+
/** capability -> its open plans, each with its audience - and `stage: 'build'` once its code is underway */
|
|
42
|
+
plans: Map<string, { where: string; audience: Audience; stage?: 'build' }[]>
|
|
42
43
|
}
|
|
43
44
|
export const NO_CONTEXT: ContextFacts = { present: false, unreadable: new Map(), shipped: new Map(), contracts: new Map(), plans: new Map() }
|
|
44
45
|
|
|
@@ -107,6 +108,7 @@ export function resolveStatus(b: BoardInput, ctx: ContextFacts): StatusResult |
|
|
|
107
108
|
const f = fillOf(capability, b.scenes)
|
|
108
109
|
return out('in-progress', 5, [`design/boards/${b.name}.json: by hand`, ...f.evidence], strictest('publishable', ...f.audience), f.fill)
|
|
109
110
|
}
|
|
111
|
+
if (b.status === 'building') return out('building', 5, [`design/boards/${b.name}.json: by hand`], 'publishable')
|
|
110
112
|
if (b.status === 'todo') return out('todo', 8, [`design/boards/${b.name}.json: by hand`], 'publishable')
|
|
111
113
|
return out('backlog', 9, [b.status === 'backlog' ? `design/boards/${b.name}.json: by hand` : 'no context/ - nothing records it'], 'publishable')
|
|
112
114
|
}
|
|
@@ -118,9 +120,16 @@ export function resolveStatus(b: BoardInput, ctx: ContextFacts): StatusResult |
|
|
|
118
120
|
const row = ctx.shipped.get(capability)
|
|
119
121
|
const live = row?.levels.includes('confirmed') ? 'confirmed' : row?.levels.includes('reported') ? 'reported' : null
|
|
120
122
|
|
|
121
|
-
// 5: an open plan - work on a shipped capability is version two being built, and says so
|
|
123
|
+
// 5: an open plan - work on a shipped capability is version two being built, and says so. A plan
|
|
124
|
+
// whose code is underway (`stage: build`) makes it Building: the design agreed, the code being written
|
|
122
125
|
const plans = ctx.plans.get(capability)
|
|
123
126
|
if (plans?.length) {
|
|
127
|
+
const building = plans.filter((p) => p.stage === 'build')
|
|
128
|
+
if (building.length) {
|
|
129
|
+
const ev = building.map((p) => `${p.where}: stage build`)
|
|
130
|
+
if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`)
|
|
131
|
+
return out('building', 5, ev, strictest(...building.map((p) => p.audience), ...(live && row ? [row.audience] : [])))
|
|
132
|
+
}
|
|
124
133
|
const f = fillOf(capability, b.scenes)
|
|
125
134
|
const ev = [...plans.map((p) => `${p.where}: an open plan`), ...f.evidence]
|
|
126
135
|
if (live && row) ev.push(`${row.where}: available, \`${live}\` - this is the next version`)
|
|
@@ -154,4 +163,4 @@ export function publishableStatus(r: { status: Status; row?: number; fill?: Phas
|
|
|
154
163
|
return { status: r.status, ...(r.fill ? { fill: r.fill } : {}) }
|
|
155
164
|
}
|
|
156
165
|
/** The statuses rows 5-9 produce - the only ones a published canvas may show. */
|
|
157
|
-
export const PUBLISHABLE: ReadonlySet<Status> = new Set(['in-progress', 'done', 'done-reported', 'todo', 'backlog'])
|
|
166
|
+
export const PUBLISHABLE: ReadonlySet<Status> = new Set(['in-progress', 'building', 'done', 'done-reported', 'todo', 'backlog'])
|
|
@@ -5,6 +5,17 @@ Never drive or automate the canvas UI; read and write files only. (Starting
|
|
|
5
5
|
`npx marver dev` so the human has a live canvas - first session, or on request -
|
|
6
6
|
is the one allowed touch.)
|
|
7
7
|
|
|
8
|
+
## Before the method: a project with no `context/`
|
|
9
|
+
|
|
10
|
+
This repository has no `context/` directory? Then **every reply in which you made, specced or changed
|
|
11
|
+
a feature or project board ends with this line**, word for word, until the human answers it:
|
|
12
|
+
|
|
13
|
+
> This project has no `context/` yet, so every feature board reads Backlog and nothing records what
|
|
14
|
+
> shipped. Want me to set it up? A few questions, then a draft from the code and the deploy history.
|
|
15
|
+
|
|
16
|
+
A yes: instructions/context.md, "Setting up". A no stands for the session - stop asking. Never set
|
|
17
|
+
it up unasked.
|
|
18
|
+
|
|
8
19
|
## The method (binding)
|
|
9
20
|
|
|
10
21
|
Design work moves through phases. BEFORE working in a phase, read its instruction
|
|
@@ -78,19 +89,50 @@ planning. The human should see the request land on the canvas within the first m
|
|
|
78
89
|
JSON - adding is always yours, only rearranging belongs to the shell; auto boards pick
|
|
79
90
|
new frames up on their own). Changing existing frames only? Skip this step.
|
|
80
91
|
2. **Light them up**: `npx marver work start <scene/frame ...>` - each frame wears the
|
|
81
|
-
live working shimmer
|
|
82
|
-
lit frame, never before one.
|
|
83
|
-
3.
|
|
92
|
+
live working shimmer, and its board's icon in the sidebar. Only now do research,
|
|
93
|
+
discovery, and planning begin - under a lit frame, never before one.
|
|
94
|
+
3. **Make the board's status true.** The glow says someone is on it now; the status says
|
|
95
|
+
where it stands when nobody is - so a feature or project board you work on never stays
|
|
96
|
+
Backlog or To do. With `context/`: an open plan in `context/plans/` names its capability -
|
|
97
|
+
In progress. None does? Write one, in the form of the plans already there - it opens with
|
|
98
|
+
front matter (`---`, `state: proposed`, `capability: <slug>`, `---`), then what you are
|
|
99
|
+
building and why, a few lines; a plan without front matter leaves every status Unknown.
|
|
100
|
+
Once its code starts, add `stage: build` to that front matter - Building. No `context/`:
|
|
101
|
+
once the human has answered the context line, `"status": "in-progress"` (or `"building"`)
|
|
102
|
+
on the board. `work start` names any board still behind; `npx marver boards` shows every
|
|
103
|
+
status.
|
|
104
|
+
4. Build. Independent frames can go in parallel - one subagent per frame, each marking
|
|
84
105
|
its own; frames that depend on one another go in order.
|
|
85
|
-
|
|
106
|
+
5. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
|
|
86
107
|
`--all`) renders the frames headless in one go - one PNG path per line - and you READ
|
|
87
108
|
the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
|
|
88
|
-
|
|
109
|
+
6. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
|
|
89
110
|
self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
|
|
90
|
-
and never lean on expiry instead of `done`.
|
|
111
|
+
and never lean on expiry instead of `done`. `done` prints the canvas link to the
|
|
112
|
+
frames it cleared (`on the canvas: ...`).
|
|
113
|
+
|
|
114
|
+
## Hand it back on the canvas
|
|
115
|
+
|
|
116
|
+
The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
91
117
|
|
|
92
|
-
|
|
93
|
-
|
|
118
|
+
- **Every reply in which you created or changed frames ends with their canvas link**, on its
|
|
119
|
+
own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
|
|
120
|
+
scene ...>` for any set. It opens the board they sit on with them selected and in view -
|
|
121
|
+
the human finds the work at once on a board of fifty frames. Never a full-screen focus link
|
|
122
|
+
(`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
|
|
123
|
+
`npx marver dev` instead - the link carries its port.
|
|
124
|
+
- **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
|
|
125
|
+
<thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
|
|
126
|
+
the human started it posts as Marver and pings them on the frame.
|
|
127
|
+
- **A question or a decision about a frame goes ON that frame**, not only in the chat:
|
|
128
|
+
`npx marver comments new <scene/frame> --body "..." [--on "<words on screen>"]` pins it where
|
|
129
|
+
it applies, so the human answers in place. Also for a judgment call you took that they should
|
|
130
|
+
check, or a change they would not spot. Nothing else - never a changelog, at most one note per
|
|
131
|
+
frame per turn; the chat keeps the summary and can say "question on the form". Never resolve
|
|
132
|
+
your own notes: the human resolves them as they review, and a reply in one comes back to you
|
|
133
|
+
(Live Jam).
|
|
134
|
+
- A comment-born (`@marver`) job hands back through its reply block alone
|
|
135
|
+
(instructions/jam.md): no link, no CLI reply to its own thread.
|
|
94
136
|
|
|
95
137
|
## Frames
|
|
96
138
|
- A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
|
|
@@ -187,6 +229,10 @@ Report where the request came from: chat requests get chat replies; only comment
|
|
|
187
229
|
- The screen already lives in src/features/. Implementation wires routes, data, and handlers
|
|
188
230
|
into the same component - fixtures are the only thing replaced. The frame stays, so the
|
|
189
231
|
canvas remains living documentation of every screen and state.
|
|
232
|
+
- **The feature board turns Building** (blue) when its code starts: write `stage: build` in the
|
|
233
|
+
front matter of the open plan in `context/plans/` that names the capability - write the plan if
|
|
234
|
+
none does. No `context/`: `"status": "building"` on the board. Done still comes only from
|
|
235
|
+
`context/shipped.md`, when it ships.
|
|
190
236
|
|
|
191
237
|
## Boards (curated canvases)
|
|
192
238
|
|
|
@@ -5,6 +5,17 @@ Never drive or automate the canvas UI; read and write files only. (Starting
|
|
|
5
5
|
`npx marver dev` so the human has a live canvas - first session, or on request -
|
|
6
6
|
is the one allowed touch.)
|
|
7
7
|
|
|
8
|
+
## Before the method: a project with no `context/`
|
|
9
|
+
|
|
10
|
+
This repository has no `context/` directory? Then **every reply in which you made, specced or changed
|
|
11
|
+
a feature or project board ends with this line**, word for word, until the human answers it:
|
|
12
|
+
|
|
13
|
+
> This project has no `context/` yet, so every feature board reads Backlog and nothing records what
|
|
14
|
+
> shipped. Want me to set it up? A few questions, then a draft from the code and the deploy history.
|
|
15
|
+
|
|
16
|
+
A yes: instructions/context.md, "Setting up". A no stands for the session - stop asking. Never set
|
|
17
|
+
it up unasked.
|
|
18
|
+
|
|
8
19
|
## The method (binding)
|
|
9
20
|
|
|
10
21
|
Design work moves through phases. BEFORE working in a phase, read its instruction
|
|
@@ -78,19 +89,50 @@ planning. The human should see the request land on the canvas within the first m
|
|
|
78
89
|
JSON - adding is always yours, only rearranging belongs to the shell; auto boards pick
|
|
79
90
|
new frames up on their own). Changing existing frames only? Skip this step.
|
|
80
91
|
2. **Light them up**: `npx marver work start <scene/frame ...>` - each frame wears the
|
|
81
|
-
live working shimmer
|
|
82
|
-
lit frame, never before one.
|
|
83
|
-
3.
|
|
92
|
+
live working shimmer, and its board's icon in the sidebar. Only now do research,
|
|
93
|
+
discovery, and planning begin - under a lit frame, never before one.
|
|
94
|
+
3. **Make the board's status true.** The glow says someone is on it now; the status says
|
|
95
|
+
where it stands when nobody is - so a feature or project board you work on never stays
|
|
96
|
+
Backlog or To do. With `context/`: an open plan in `context/plans/` names its capability -
|
|
97
|
+
In progress. None does? Write one, in the form of the plans already there - it opens with
|
|
98
|
+
front matter (`---`, `state: proposed`, `capability: <slug>`, `---`), then what you are
|
|
99
|
+
building and why, a few lines; a plan without front matter leaves every status Unknown.
|
|
100
|
+
Once its code starts, add `stage: build` to that front matter - Building. No `context/`:
|
|
101
|
+
once the human has answered the context line, `"status": "in-progress"` (or `"building"`)
|
|
102
|
+
on the board. `work start` names any board still behind; `npx marver boards` shows every
|
|
103
|
+
status.
|
|
104
|
+
4. Build. Independent frames can go in parallel - one subagent per frame, each marking
|
|
84
105
|
its own; frames that depend on one another go in order.
|
|
85
|
-
|
|
106
|
+
5. **Look before you say done**: `npx marver shot --scene <scene>` (or `<scene/frame ...>`,
|
|
86
107
|
`--all`) renders the frames headless in one go - one PNG path per line - and you READ
|
|
87
108
|
the PNGs. No shell? instructions/jam.md has the file-drop way (`{"scene":"..."}`).
|
|
88
|
-
|
|
109
|
+
6. **Clear as you finish**: `npx marver work done <scene/frame ...>` (or `--all`). Marks
|
|
89
110
|
self-expire (default 10 min; `--ttl <min>` up to 30) - re-run `start` on long jobs,
|
|
90
|
-
and never lean on expiry instead of `done`.
|
|
111
|
+
and never lean on expiry instead of `done`. `done` prints the canvas link to the
|
|
112
|
+
frames it cleared (`on the canvas: ...`).
|
|
113
|
+
|
|
114
|
+
## Hand it back on the canvas
|
|
115
|
+
|
|
116
|
+
The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
91
117
|
|
|
92
|
-
|
|
93
|
-
|
|
118
|
+
- **Every reply in which you created or changed frames ends with their canvas link**, on its
|
|
119
|
+
own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
|
|
120
|
+
scene ...>` for any set. It opens the board they sit on with them selected and in view -
|
|
121
|
+
the human finds the work at once on a board of fifty frames. Never a full-screen focus link
|
|
122
|
+
(`#/f/...`) unless they ask for full screen. No `marver dev` running? End with
|
|
123
|
+
`npx marver dev` instead - the link carries its port.
|
|
124
|
+
- **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
|
|
125
|
+
<thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
|
|
126
|
+
the human started it posts as Marver and pings them on the frame.
|
|
127
|
+
- **A question or a decision about a frame goes ON that frame**, not only in the chat:
|
|
128
|
+
`npx marver comments new <scene/frame> --body "..." [--on "<words on screen>"]` pins it where
|
|
129
|
+
it applies, so the human answers in place. Also for a judgment call you took that they should
|
|
130
|
+
check, or a change they would not spot. Nothing else - never a changelog, at most one note per
|
|
131
|
+
frame per turn; the chat keeps the summary and can say "question on the form". Never resolve
|
|
132
|
+
your own notes: the human resolves them as they review, and a reply in one comes back to you
|
|
133
|
+
(Live Jam).
|
|
134
|
+
- A comment-born (`@marver`) job hands back through its reply block alone
|
|
135
|
+
(instructions/jam.md): no link, no CLI reply to its own thread.
|
|
94
136
|
|
|
95
137
|
## Frames
|
|
96
138
|
- A frame = one file: design/scenes/<scene>/<name>.tsx or .html. One frame, one surface.
|
|
@@ -187,6 +229,10 @@ Report where the request came from: chat requests get chat replies; only comment
|
|
|
187
229
|
- Move the screen from design/screens/ into the app (src/features/...), replace fixture
|
|
188
230
|
props with live data/handlers, replace data-goto with the router's navigation.
|
|
189
231
|
- Leave the frame in place, importing from its new home, so the canvas stays true.
|
|
232
|
+
- **The feature board turns Building** (blue) when its code starts: write `stage: build` in the
|
|
233
|
+
front matter of the open plan in `context/plans/` that names the capability - write the plan if
|
|
234
|
+
none does. No `context/`: `"status": "building"` on the board. Done still comes only from
|
|
235
|
+
`context/shipped.md`, when it ships.
|
|
190
236
|
|
|
191
237
|
## Boards (curated canvases)
|
|
192
238
|
|
|
@@ -15,6 +15,12 @@ viewport and lays it out:
|
|
|
15
15
|
"nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
+
Never write `w`/`h` on a content frame's node (a `Doc`): its height is measured, and
|
|
19
|
+
`design/boards/_sizes.json` - machine-written, committed, never edited by hand - keeps it so
|
|
20
|
+
the board opens at its final size (a board's `laidOut` is the canvas's note of the heights its
|
|
21
|
+
rows were laid out around - leave it too). Commit it with your changes; a merge conflict in it
|
|
22
|
+
is safe to resolve either way.
|
|
23
|
+
|
|
18
24
|
- **The file name is the board's identity** - what you, `publish.json`, URLs and
|
|
19
25
|
comment threads address (`board: checkout-compare`). It is a slug
|
|
20
26
|
(`^[a-z0-9][a-z0-9-]*$`) and never moves on a rename.
|
|
@@ -176,11 +182,17 @@ boards fall back to the parent folder's type). Moving a board changes an inherit
|
|
|
176
182
|
capability is the board's name, or `"capability": "<slug>"`. You may decide only three things on
|
|
177
183
|
the board: `"status": "archived"`, `"paused"`, or `"blocked"` with `"reason": "<one sentence>"`.
|
|
178
184
|
**Never write `"status": "done"`** - Done comes from `context/shipped.md`, and the check fails it.
|
|
179
|
-
|
|
185
|
+
**No `context/`? Your reply ends with the context line** from design/AGENTS.md ("Before the method")
|
|
186
|
+
- every feature board reads Backlog until there is one. Only when the human declines may a board
|
|
187
|
+
say `"todo"`, `"backlog"`, `"in-progress"` or `"building"` by hand.
|
|
180
188
|
A person sets the same from the sidebar (right-click, Change status…) - it rewrites only `status`
|
|
181
|
-
and `reason
|
|
189
|
+
and `reason`; with `context/`, its In progress and Building rewrite the `stage:` line of every open
|
|
190
|
+
plan naming the capability instead (and clear the board's decision). So re-read a board, and its
|
|
191
|
+
plan, before you edit them.
|
|
182
192
|
- In progress fills by phase: the phase scenes above, or `phase: spec | lofi | hifi` in a scene's
|
|
183
|
-
`_brief.md` front matter - never by where a row sits.
|
|
193
|
+
`_brief.md` front matter - never by where a row sits. **Building** (blue) follows it: the design
|
|
194
|
+
agreed, the code underway - `stage: build` in the open plan (instructions/context.md). While you
|
|
195
|
+
work on a board's frames (`marver work start`), its sidebar icon shimmers blue on its own.
|
|
184
196
|
- `npx marver boards` prints every board's type and status with what decided it.
|
|
185
197
|
|
|
186
198
|
## The default composition: one horizontal band
|
|
@@ -62,6 +62,9 @@ proposed; and `## Availability` pointing at its row in `shipped.md`.
|
|
|
62
62
|
|
|
63
63
|
- **Behaviour** - update its contract in the same change. A change that leaves behaviour alone says
|
|
64
64
|
`no-contract-change: <capability> - <why>` in the pull request body.
|
|
65
|
+
- **Work starting on a feature** - an open plan in `plans/` names its capability (In progress on its
|
|
66
|
+
board); `stage: build` in it once the code starts (Building). The board's status is how anyone
|
|
67
|
+
who is not watching knows; never leave a feature you are working on reading Backlog.
|
|
65
68
|
- **A deploy** - write its row in `shipped.md` with the run that proves it (`playbooks/` usually
|
|
66
69
|
has the release recipe).
|
|
67
70
|
- **A decision** - in the project's decision log, numbered, with what it applies to.
|
|
@@ -74,8 +77,9 @@ proposed; and `## Availability` pointing at its row in `shipped.md`.
|
|
|
74
77
|
|
|
75
78
|
Feature and project boards wear a status read from these files (the first that matches wins):
|
|
76
79
|
the board's own `"status"` - `archived`, `paused`, or `blocked` with a `"reason"`; Unknown when the
|
|
77
|
-
evidence cannot be read;
|
|
78
|
-
|
|
80
|
+
evidence cannot be read; when an open plan in `plans/` names the capability, Building if the plan
|
|
81
|
+
says `stage: build` (its code is underway - write it as you start implementing), else In progress
|
|
82
|
+
(filling by phase: `<cap>-specs`, `<cap>-lofi`, `<cap>`); Done when `shipped.md` shows it `confirmed` in an
|
|
79
83
|
availability clause (one per `;`) with no negation or pending word ("nowhere", "not yet", "rolled
|
|
80
84
|
back", "planned") and no pre-production place (staging, preview, dev, local, testing) unless it also
|
|
81
85
|
names production; Done, reported when only `reported`; To do when its contract is `state: current`; else Backlog.
|
|
@@ -98,11 +102,20 @@ Context starts with people. Ask, in one message:
|
|
|
98
102
|
3. What is private, and who may see what?
|
|
99
103
|
4. How is this project named in shared spaces - keywords, tags?
|
|
100
104
|
|
|
101
|
-
Then
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
105
|
+
Then, in order - this is the whole recipe; "set up our context" asks for all of it:
|
|
106
|
+
1. `npx marver context init --kind product` - or `--kind knowledge` when the work is deliverables
|
|
107
|
+
for clients rather than a product people use. Record the answers in `context/people.md`.
|
|
108
|
+
2. Draft from evidence: the shipped record from deploy runs and the changelog (`unknown` where
|
|
109
|
+
nothing proves it), a map from the code, contracts for the capabilities that matter now.
|
|
110
|
+
3. Let the canvas read it: `npx marver init --kind <the same kind>` adds the typed folders (it never
|
|
111
|
+
moves a board); put each feature board in Features (a project in Projects), named after its
|
|
112
|
+
capability or saying `"capability": "<slug>"`; then `npx marver boards new home --type start
|
|
113
|
+
--folder start-here`.
|
|
114
|
+
4. Put the check in ci - a step running `npx marver context check` on a full-history checkout
|
|
115
|
+
(`fetch-depth: 0`) - and make it pass before you hand over.
|
|
116
|
+
|
|
117
|
+
**Context that exists but is scattered** - specs out of date, nobody sure what is live - is a job
|
|
118
|
+
for `context/playbooks/reorganize-context/PLAYBOOK.md`, not for a rewrite.
|
|
106
119
|
|
|
107
120
|
## The check
|
|
108
121
|
|
|
@@ -75,13 +75,18 @@ to step 4.
|
|
|
75
75
|
```
|
|
76
76
|
4. **Now do the round on the live scene**, in place - the snapshot is the
|
|
77
77
|
before. Keep each anchored element's tag, `data-testid` and visible text
|
|
78
|
-
where you can, so pins self-heal
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
resolve with `--addressed-in <scene>/<frame>`;
|
|
84
|
-
you never resolve - the owner does
|
|
78
|
+
where you can, so pins self-heal. Reply per thread with one line: what
|
|
79
|
+
changed, and that `v<N>` is on the archive board. Who closes the thread
|
|
80
|
+
depends on who started it: a thread the owner started (`comments reply`
|
|
81
|
+
printed "as Marver") stays OPEN - the owner reviews your change on the
|
|
82
|
+
canvas, in the thread, and resolves it; a collaborator's thread (the reply
|
|
83
|
+
printed "in your voice") you resolve with `--addressed-in <scene>/<frame>`;
|
|
84
|
+
from a comment-born jam job you never resolve - the owner does
|
|
85
|
+
(instructions/jam.md). A change that removes an anchored element: a
|
|
86
|
+
collaborator's thread is replied to and resolved FIRST, then the change
|
|
87
|
+
(resolve first, restructure second); the owner's stays open - say in the
|
|
88
|
+
reply what replaced the element (its pin parks at the frame's corner, still
|
|
89
|
+
in view).
|
|
85
90
|
|
|
86
91
|
Never wait for the human to ask for this. They should be able to say "make the
|
|
87
92
|
cards denser", "drop the sidebar", "try a warmer palette" three times in a row
|
|
@@ -140,6 +145,7 @@ the open list as a queue:
|
|
|
140
145
|
npx marver comments list --open --json # what needs you (anchors included)
|
|
141
146
|
npx marver comments reply <thread> --body "…"
|
|
142
147
|
npx marver comments resolve <thread> --addressed-in <scene/frame>
|
|
148
|
+
npx marver comments new <scene/frame> --body "…" [--on "<words on screen>"] # a note where you need them
|
|
143
149
|
```
|
|
144
150
|
|
|
145
151
|
The discipline:
|
|
@@ -164,10 +170,14 @@ The discipline:
|
|
|
164
170
|
iterate the live frames in place. A single frame going in a new direction:
|
|
165
171
|
fork a variant (the letter convention) and iterate there - the commented
|
|
166
172
|
frame stays as the before, your variant is the after.
|
|
167
|
-
4. **
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
173
|
+
4. **Reply where they look, resolve with the receipt.** Reply in the thread -
|
|
174
|
+
one line, what changed. The owner's own threads stay open after your reply:
|
|
175
|
+
they review the change on the canvas and close it (a resolved thread leaves
|
|
176
|
+
the canvas, and your reply with it). A collaborator's thread, you resolve:
|
|
177
|
+
`--addressed-in <the-new-variant>` records WHICH frame answered the feedback -
|
|
178
|
+
the thread becomes an auditable link from complaint to fix. `comments reply`
|
|
179
|
+
says which it was: "as Marver" (the owner's) or "in your voice" (a
|
|
180
|
+
collaborator's - the voice that reaches them on the published canvas).
|
|
171
181
|
5. **Never resolve what you didn't address.** Disagree? Reply with your
|
|
172
182
|
reasoning and leave the thread open - the human closes debates, you close
|
|
173
183
|
completed work.
|
|
@@ -176,9 +186,12 @@ The discipline:
|
|
|
176
186
|
frame and the anchors strand (a dead anchor parks the pin at the frame
|
|
177
187
|
edge; deleting the whole frame strands the thread off-canvas entirely -
|
|
178
188
|
never lost from the log, but invisible until the frame returns). So: with a
|
|
179
|
-
version snapshot taken, edit the live frame and
|
|
180
|
-
after its change
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
189
|
+
version snapshot taken, edit the live frame and close out each thread right
|
|
190
|
+
after its change - a collaborator's resolved, the owner's replied to and left
|
|
191
|
+
open for them (step 4 above); without one, fork the variant and iterate
|
|
192
|
+
THERE, leave the commented frame untouched as the before, and only once its
|
|
193
|
+
threads are closed (`resolve --addressed-in <variant>` for a collaborator's;
|
|
194
|
+
the owner's, once the owner has resolved them after your reply naming the
|
|
195
|
+
variant) may it move to `archive/`. Answer first, restructure second - never
|
|
196
|
+
the reverse. Check `comments list --board <b>` (no `--open`) to see resolved
|
|
184
197
|
threads too; the full history lives in the append-only log and in git.
|
|
@@ -184,8 +184,15 @@ tells you which mode you are in - when it says to work on a single agent, do tha
|
|
|
184
184
|
`jam.subagents` is off, or your CLI has no subagents to spawn).
|
|
185
185
|
|
|
186
186
|
## Reading comments without the daemon
|
|
187
|
-
`npx marver comments list [<board>]` prints the threads on demand - use it to catch up or
|
|
188
|
-
a one-off question without the live jam loop.
|
|
187
|
+
`npx marver comments list [--board <board>]` prints the threads on demand - use it to catch up or
|
|
188
|
+
answer a one-off question without the live jam loop.
|
|
189
|
+
|
|
190
|
+
## Notes Marver pinned from chat
|
|
191
|
+
A chat agent leaves notes on frames it changed (`marver comments new`, design/AGENTS.md "Hand it
|
|
192
|
+
back on the canvas"). The owner's reply in one of those threads is a job like any other - no tag
|
|
193
|
+
needed, the same as a reply to Marver - and the note is the context: it says what was changed
|
|
194
|
+
and what the agent wanted from them. While a chat agent has that frame lit (`marver work start`)
|
|
195
|
+
the job waits, so two agents never edit one file at once.
|
|
189
196
|
|
|
190
197
|
## When jam misbehaves - diagnose, fix, report upstream
|
|
191
198
|
|
|
@@ -146,7 +146,8 @@ mode - and default to faithful:
|
|
|
146
146
|
|
|
147
147
|
- **Faithful** - their order, their words, exactly. You may normalise
|
|
148
148
|
punctuation and number formats; you may not change a word. Suggested
|
|
149
|
-
rewrites go in a
|
|
149
|
+
rewrites go in a note on the frame (`npx marver comments new <scene/frame>
|
|
150
|
+
--on "<their words>" --body "Suggest: ..."`), never on the slide.
|
|
150
151
|
- **Editorial** (opt-in) - order kept, copy passed through the slides
|
|
151
152
|
guide's words: jargon, hedges and filler out; numbers, names and dates
|
|
152
153
|
verbatim; titles turned into claims where the source supports them.
|
|
@@ -82,7 +82,8 @@ one-sentence slides on the canvas) a missing fact is a visible `[PLACEHOLDER:
|
|
|
82
82
|
what belongs here]`. In the build, a factual placeholder BLOCKS its slide -
|
|
83
83
|
answered, or the slide is cut - never filled with plausible prose. Editorial
|
|
84
84
|
gaps (a tagline, a caption, a transition line) you DO draft, labelled as
|
|
85
|
-
proposed in the frame
|
|
85
|
+
proposed in a note on the frame (`npx marver comments new <scene/frame>`) - that
|
|
86
|
+
is writing, not invention.
|
|
86
87
|
|
|
87
88
|
## Writing that carries
|
|
88
89
|
|