joycraft 1.2.0 → 1.2.2
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 +53 -16
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-entry/SKILL.md +12 -7
- package/payload/.joycraft/assets/artifacts/kit.css +7 -0
- package/payload/.joycraft/assets/artifacts/kit.js +23 -7
- package/payload/.joycraft/references/artifacts.md +66 -9
- package/payload/.joycraft/references/setup.md +33 -17
- package/payload/.joycraft/references/update.md +6 -1
- package/payload/.joycraft/references/workflow.md +7 -3
- package/payload/.joycraft/runtime/artifacts/cli.mjs +29 -5
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +13 -5
- package/payload/.joycraft/runtime/artifacts/model.mjs +1 -1
- package/payload/.joycraft/runtime/artifacts/preferences.mjs +95 -2
- package/payload/.joycraft/runtime/review-tools.mjs +12 -7
- package/payload/.joycraft/templates/brief.md +1 -1
- package/payload/PIN +15 -15
package/README.md
CHANGED
|
@@ -23,9 +23,10 @@ Install Joycraft in this project.
|
|
|
23
23
|
docs, interview me about what the repo cannot tell you, then show me the
|
|
24
24
|
AGENTS.md and CLAUDE.md changes on a page before you write them. If the project
|
|
25
25
|
is new or empty, ask me what I want to build.
|
|
26
|
-
4.
|
|
27
|
-
|
|
28
|
-
Ask me before you
|
|
26
|
+
4. Show me the review loop that setup found: for each package, the tool that
|
|
27
|
+
checks it and what that tool can show. If setup did not do this, run
|
|
28
|
+
`node .joycraft/runtime/review-tools.mjs plan --root .`. Ask me before you
|
|
29
|
+
install anything.
|
|
29
30
|
Do not commit, publish, or ask me for API keys.
|
|
30
31
|
```
|
|
31
32
|
|
|
@@ -47,8 +48,8 @@ bigger than one quick change:
|
|
|
47
48
|
3. **The agent builds each spec with tests.**
|
|
48
49
|
4. **A second agent checks each spec.** It did not write the code. It reads the spec,
|
|
49
50
|
runs the checks, and says PASS or FAIL. Only a PASS completes the spec. For a
|
|
50
|
-
screen or page, it looks at the real result
|
|
51
|
-
|
|
51
|
+
screen or page, it looks at the real result with the package's review tool
|
|
52
|
+
(see [The review loop](#the-review-loop)).
|
|
52
53
|
5. **The agent wraps up.** It records what it learned for the next session.
|
|
53
54
|
|
|
54
55
|
You do not need to call the Joycraft skills by name. Describe the work and the agent
|
|
@@ -163,22 +164,55 @@ If your docs are step-by-step procedures, the agent can offer
|
|
|
163
164
|
[Doc Detective](https://docs.doc-detective.com) to run them as tests. It is opt-in:
|
|
164
165
|
the agent says what it does not cover and installs nothing without your yes.
|
|
165
166
|
|
|
166
|
-
##
|
|
167
|
+
## The review loop
|
|
168
|
+
|
|
169
|
+
The reviewing agent needs a tool that shows the real result: a browser for a web
|
|
170
|
+
app, a simulator for a mobile app, an HTTP check for an API. Joycraft decides what
|
|
171
|
+
counts as evidence; your project keeps its own tools.
|
|
172
|
+
|
|
173
|
+
- **Setup finds your tools.** For each package it looks for the tool you already
|
|
174
|
+
use (Playwright, Cypress, WebdriverIO, Maestro, Newman, an e2e script, a CI job
|
|
175
|
+
and others) and records one row per package in AGENTS.md, with what that tool can
|
|
176
|
+
show. Tools that belong to this machine, such as your agent's built-in browser, go
|
|
177
|
+
to `.joycraft/local/`. Packages that are not declared workspaces are found too, or
|
|
178
|
+
name them with `--packages`.
|
|
179
|
+
- **A gap gets one recommendation.** If a package has no tool, the agent recommends
|
|
180
|
+
one with its trade-offs and offers to look at others. It installs only on your yes,
|
|
181
|
+
and never with `sudo`, a licence or a sign-in. A project with no app records that
|
|
182
|
+
once and is not asked again.
|
|
183
|
+
- **Limits you agreed to are not failures.** A claim the recorded tool cannot show,
|
|
184
|
+
or a package you skipped, is reported as a limit. `UNVERIFIED` means a check that
|
|
185
|
+
should have run and did not.
|
|
186
|
+
- **Skipping review for one feature.** Say "skip review" in the feature interview.
|
|
187
|
+
The feature's `waiver.json` records your words, and no reviewer runs for it. A
|
|
188
|
+
waiver never hides a FAIL, and a new install keeps every check on.
|
|
189
|
+
- **A broken tool holds one spec.** If the browser or server breaks, the agent
|
|
190
|
+
tries one repair (restart, free the port, relaunch). Then it holds that spec as
|
|
191
|
+
`UNVERIFIED`, tells you, and keeps the rest of the queue going.
|
|
192
|
+
|
|
193
|
+
After an update, the agent checks the review loop again and asks only about what
|
|
194
|
+
changed.
|
|
167
195
|
|
|
168
|
-
|
|
169
|
-
decision page instead of in chat. Each question shows its context, its options and
|
|
170
|
-
what it affects. You pick an answer, or "Something else" and say what you want, add
|
|
171
|
-
a note if you want, and save. You can add or change a note after saving. If the
|
|
172
|
-
brief changes while the page is open, the page names the questions that changed and
|
|
173
|
-
keeps your other answers. The answers go into the brief, so the agent does not ask
|
|
174
|
-
again.
|
|
196
|
+
## Answering questions: the decision page
|
|
175
197
|
|
|
176
|
-
|
|
198
|
+
When the agent needs you to choose between options, it asks in your question
|
|
199
|
+
style. Setup asks for it once: one decision at a time with a short talk about each
|
|
200
|
+
answer, or a page of decisions; on a decision page or as numbered prose in chat.
|
|
201
|
+
To change it for one feature, say:
|
|
177
202
|
|
|
178
203
|
```text
|
|
179
|
-
|
|
204
|
+
Ask me one question at a time, in chat, for this feature.
|
|
180
205
|
```
|
|
181
206
|
|
|
207
|
+
A consequential question gives the context, the question, two to four options each
|
|
208
|
+
with an example and a trade-off, and the agent's recommendation with its reason. On
|
|
209
|
+
the decision page, you pick an answer, or "Something else" and say what you want,
|
|
210
|
+
add a note if you want, and save. You can add or change a note after saving. If the
|
|
211
|
+
brief changes while the page is open, the page names the questions that changed and
|
|
212
|
+
keeps your other answers. In chat or on the page, the answers go into the brief, so
|
|
213
|
+
the agent does not ask again. If a question is not clear, say "wait, what?" and the
|
|
214
|
+
agent explains it again with more context.
|
|
215
|
+
|
|
182
216
|
**Colors.** The page uses a light or dark theme. To match your project, ask:
|
|
183
217
|
|
|
184
218
|
```text
|
|
@@ -211,7 +245,9 @@ day. The check sends no project data. If there is a new version, the agent tells
|
|
|
211
245
|
whether it is a patch, a minor release or a migration, lists each release since
|
|
212
246
|
yours, and asks: update now, not now, or turn off. Automatic updates apply only
|
|
213
247
|
patches. On a yes, it does the update
|
|
214
|
-
for you, checks the result, and tells you what is different.
|
|
248
|
+
for you, checks the result, and tells you what is different. After a minor release
|
|
249
|
+
it names what you can now do, and asks how you want questions if you have not said
|
|
250
|
+
yet. A new major version is
|
|
215
251
|
always your choice.
|
|
216
252
|
|
|
217
253
|
This is an instruction the agent follows, so it can forget. To check yourself, ask:
|
|
@@ -263,6 +299,7 @@ should forget:
|
|
|
263
299
|
- **Lauren** (Cursor): prefer fixes in this order: architecture, then lint and CI, then skills and rules, then asking a human.
|
|
264
300
|
- **Robert C. Martin**: impose values, not disciplines.
|
|
265
301
|
- **aka-luan** ([doc-cleanup](https://github.com/aka-luan/doc-cleanup), MIT), brought to Joycraft by **David Moshal**: Joycraft's doc audit follows its method. Treat every doc claim as a hypothesis and the code as the evidence.
|
|
302
|
+
- **David Moshal**, with his `questions-dm` skill: ask one question at a time, give the context first, and never assume the user remembers what the agent remembers. **Matt Pocock** ([`wait-what`](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what), MIT): when a message does not land, say it again in plain words with the missing context.
|
|
266
303
|
|
|
267
304
|
The levels this project aims at are Dan Shapiro's. See [The levels](docs/guides/levels.md).
|
|
268
305
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "joycraft",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.2",
|
|
4
4
|
"description": "Install and update Joycraft, a skill bundle and runtime for agent-led software work, in any project",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -13,8 +13,8 @@
|
|
|
13
13
|
"payload"
|
|
14
14
|
],
|
|
15
15
|
"joycraft": {
|
|
16
|
-
"release": "1.2.
|
|
17
|
-
"summary": "The
|
|
16
|
+
"release": "1.2.2",
|
|
17
|
+
"summary": "The README describes the 1.2 review loop, the install prompt shows what setup found, and an update names what is new and offers the question style.",
|
|
18
18
|
"autoSafeEligible": false
|
|
19
19
|
},
|
|
20
20
|
"scripts": {
|
|
@@ -86,13 +86,18 @@ screenshots-only tool). That is a tooling change: follow
|
|
|
86
86
|
[change a tool](../../../.joycraft/references/setup.md#review-loop-tools) and
|
|
87
87
|
record the answer, so it is not asked again.
|
|
88
88
|
|
|
89
|
-
**Ask
|
|
90
|
-
options, record each choice as a brief decision
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
89
|
+
**Ask in the user's question style.** When the user must choose between
|
|
90
|
+
options, record each choice as a brief decision. Then run
|
|
91
|
+
`node .joycraft/runtime/artifacts/cli.mjs questions --brief <brief>` and ask as
|
|
92
|
+
it says: one decision at a time with a short discussion after each answer, or a
|
|
93
|
+
page of decisions; in the decision artifact or as numbered prose in chat. Give
|
|
94
|
+
each consequential question its context, options with an example and a
|
|
95
|
+
trade-off, and your recommendation with the reason, in Simplified Technical
|
|
96
|
+
English. Never assume the user remembers what you remember. Save every answer
|
|
97
|
+
to the brief. Follow
|
|
98
|
+
[asking questions](../../../.joycraft/references/artifacts.md#asking-questions).
|
|
99
|
+
Plain chat with no decision is only for one quick yes/no or an open question
|
|
100
|
+
with no options.
|
|
96
101
|
|
|
97
102
|
**Use the project's folders.** If `joycraft.yaml` exists, run
|
|
98
103
|
`node .joycraft/runtime/config.mjs` and use its `paths` wherever Joycraft guidance
|
|
@@ -89,6 +89,13 @@ html[data-jca-theme] body { margin: 0; background: var(--canvas); color: var(--i
|
|
|
89
89
|
.jca-option input { margin-top: .28rem; accent-color: var(--accent); }
|
|
90
90
|
.jca-option strong, .jca-option small { display: block; }
|
|
91
91
|
.jca-option small { margin-top: .1rem; color: var(--muted); }
|
|
92
|
+
.jca-option .jca-option-line { margin-top: .3rem; }
|
|
93
|
+
.jca-option-line b, .jca-recommendation b { color: var(--ink); font-weight: 650; }
|
|
94
|
+
.jca-badge { display: inline-block; margin-left: .5rem; padding: .05rem .45rem; border-radius: 999px; background: var(--accent); color: var(--accent-text); font-size: .7rem; font-weight: 700; letter-spacing: .04em; vertical-align: .1em; }
|
|
95
|
+
.jca-option-recommended { border-color: var(--accent); }
|
|
96
|
+
.jca-context { margin: .8rem 0 0; }
|
|
97
|
+
.jca-context p { margin: .55rem 0; }
|
|
98
|
+
.jca-recommendation { margin: 0 0 1rem; padding: .7rem .8rem; border-left: 3px solid var(--accent); background: var(--accent-soft); }
|
|
92
99
|
.jca-note-label { display: block; margin-bottom: .35rem; font-size: .88rem; font-weight: 700; }
|
|
93
100
|
.jca-note { display: block; width: 100%; resize: vertical; border: 1px solid var(--control-line); border-radius: 8px; padding: .7rem; color: var(--ink); background: var(--input); font: inherit; }
|
|
94
101
|
.jca-note::placeholder { color: var(--muted); opacity: 1; }
|
|
@@ -46,8 +46,9 @@
|
|
|
46
46
|
return JSON.stringify({
|
|
47
47
|
question: question.question || '',
|
|
48
48
|
options: (question.options || []).map(function (option) {
|
|
49
|
-
return { value: option.value, label: option.label || '', description: option.description || '', requiresNote: Boolean(option.requiresNote) };
|
|
49
|
+
return { value: option.value, label: option.label || '', description: option.description || '', example: option.example || '', tradeoff: option.tradeoff || '', recommended: Boolean(option.recommended), requiresNote: Boolean(option.requiresNote) };
|
|
50
50
|
}),
|
|
51
|
+
recommendation: question.recommendation || '',
|
|
51
52
|
status: question.status || '',
|
|
52
53
|
answer: question.answer == null ? null : question.answer,
|
|
53
54
|
note: question.note == null ? '' : question.note
|
|
@@ -336,23 +337,38 @@
|
|
|
336
337
|
body.append(node('p', { class: 'jca-status jca-status-' + (question.status || 'open'), text: statusLabel(question.status) }));
|
|
337
338
|
if (question.answer) body.append(node('p', { class: 'jca-recorded', text: 'Brief record: ' + question.answer }));
|
|
338
339
|
(model.comparisons || []).filter(function (comparison) { return comparison.decisionId === question.id; }).forEach(function (comparison) { body.append(renderComparison(comparison)); });
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
340
|
+
// Context comes before the choice, never behind a click: a person should not have to remember it.
|
|
341
|
+
if (question.context || question.why) {
|
|
342
|
+
body.append(node('div', { class: 'jca-context' }, [
|
|
343
|
+
question.context ? node('p', { text: question.context }) : null,
|
|
344
|
+
question.why ? node('p', { text: question.why }) : null
|
|
345
|
+
]));
|
|
346
|
+
}
|
|
347
|
+
if (question.details || (question.affected || []).length) {
|
|
348
|
+
var detail = node('details', { class: 'jca-details' }, [node('summary', { text: 'More detail' })]);
|
|
349
|
+
if (question.details) detail.append(node('p', { text: question.details }));
|
|
343
350
|
if ((question.affected || []).length) detail.append(node('p', { text: 'Affected: ' + question.affected.join(', ') }));
|
|
344
351
|
body.append(detail);
|
|
345
352
|
}
|
|
346
353
|
var fieldset = node('fieldset', { class: 'jca-options', disabled: readOnly });
|
|
347
354
|
fieldset.append(node('legend', { text: readOnly ? 'Responses are read-only' : 'Choose one response' }));
|
|
348
|
-
|
|
355
|
+
// The recommended option leads; "Something else" always closes the list.
|
|
356
|
+
var rank = function (option) { return option.value === 'custom' ? 2 : option.recommended ? 0 : 1; };
|
|
357
|
+
var ordered = (question.options || []).map(function (option, position) { return { option: option, position: position }; })
|
|
358
|
+
.sort(function (left, right) { return rank(left.option) - rank(right.option) || left.position - right.position; })
|
|
359
|
+
.map(function (item) { return item.option; });
|
|
360
|
+
var optionLine = function (name, value) { return value ? node('small', { class: 'jca-option-line' }, [node('b', { text: name + ': ' }), text(value)]) : null; };
|
|
361
|
+
ordered.forEach(function (option) {
|
|
349
362
|
var id = 'jca-' + question.id + '-' + option.value;
|
|
350
363
|
var radio = node('input', { type: 'radio', id: id, name: 'jca-answer-' + question.id, value: option.value, checked: current.answer === option.value,
|
|
351
364
|
onchange: function () { draft[question.id] = { answer: option.value, note: (draft[question.id] || {}).note || '' }; setMessage('quiet', 'Unsaved changes.'); syncLiveUi(); syncNoteRequirement(); } });
|
|
352
|
-
var
|
|
365
|
+
var title = node('strong', { text: option.label }, [option.recommended ? node('span', { class: 'jca-badge', text: 'Recommended' }) : null]);
|
|
366
|
+
var label = node('label', { class: 'jca-option' + (option.recommended ? ' jca-option-recommended' : ''), for: id }, [radio, node('span', { class: 'jca-option-copy' }, [title, option.description ? node('small', { text: option.description }) : null, optionLine('Example', option.example), optionLine('Trade-off', option.tradeoff)])]);
|
|
353
367
|
fieldset.append(label);
|
|
354
368
|
});
|
|
355
369
|
body.append(fieldset);
|
|
370
|
+
var pick = (question.options || []).find(function (option) { return option.recommended; });
|
|
371
|
+
if (pick && question.recommendation) body.append(node('p', { class: 'jca-recommendation' }, [node('b', { text: 'Recommendation: ' + pick.label + '. ' }), text(question.recommendation)]));
|
|
356
372
|
var note = node('textarea', { class: 'jca-note', id: 'jca-note-' + question.id, rows: 3, disabled: !canEditNote(question), placeholder: 'Optional note' });
|
|
357
373
|
note.value = current.note || '';
|
|
358
374
|
function syncNoteRequirement() {
|
|
@@ -1,11 +1,64 @@
|
|
|
1
1
|
# Decision artifacts
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
for an editorial comparison of existing screenshots or
|
|
6
|
-
|
|
7
|
-
the source of truth. Do not use one for a routine native question,
|
|
8
|
-
slice whose real interaction must be explored, or a long
|
|
3
|
+
Record every choice the user must make between options as a brief decision,
|
|
4
|
+
then ask it in the user's [question style](#asking-questions): on this page or
|
|
5
|
+
in chat. Also use a page for an editorial comparison of existing screenshots or
|
|
6
|
+
a review summary. A page renders a selected view of the brief; the brief and
|
|
7
|
+
queue remain the source of truth. Do not use one for a routine native question,
|
|
8
|
+
a product UI slice whose real interaction must be explored, or a long
|
|
9
|
+
questionnaire.
|
|
10
|
+
|
|
11
|
+
## Asking questions
|
|
12
|
+
|
|
13
|
+
Do not assume the user remembers what you remember. Before you ask, run:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
node .joycraft/runtime/artifacts/cli.mjs questions --brief docs/features/<slug>/brief.md
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
It prints `pacing`, `surface` and where each came from. With `unset: true`, the
|
|
20
|
+
project has no recorded style yet: ask for it as [setup](setup.md) step 2 says,
|
|
21
|
+
then continue.
|
|
22
|
+
|
|
23
|
+
- **Pacing `one-at-a-time`.** Ask one decision. After the answer, tell the user
|
|
24
|
+
what it changes and ask if that is correct, and stop there: do not put the
|
|
25
|
+
next decision in the same message. Ask the next decision after the user
|
|
26
|
+
replies. Ask first the decision that the others depend on.
|
|
27
|
+
- **Pacing `page`.** Show the open decisions together. After the save, say in
|
|
28
|
+
one line per answer what it changes.
|
|
29
|
+
- **Surface `artifact`.** Serve the page for the decisions you ask now (the
|
|
30
|
+
view's `decisionIds`). Discuss the answers in chat.
|
|
31
|
+
- **Surface `chat`.** Write the question as prose with numbered options, in the
|
|
32
|
+
order below. Save each answer to its brief decision with the user's exact
|
|
33
|
+
words as the note. The brief stays the only record of the answer.
|
|
34
|
+
|
|
35
|
+
The user can change the style for one feature ("ask me one at a time here"):
|
|
36
|
+
`questions --brief <brief> --set pacing=one-at-a-time`. That writes a
|
|
37
|
+
`question-style:` line in that brief only. `--clear` removes it. A request to
|
|
38
|
+
change it for every feature is `questions --set ...` without `--brief`.
|
|
39
|
+
|
|
40
|
+
**Order for a consequential choice** (one that changes scope, cost or what is
|
|
41
|
+
built):
|
|
42
|
+
|
|
43
|
+
1. Context: what you are doing, the current state, and why you are blocked.
|
|
44
|
+
2. The question: one sentence, one decision.
|
|
45
|
+
3. Two to four options. Each has a short explanation, a concrete example of the
|
|
46
|
+
result, and the main trade-off.
|
|
47
|
+
4. Your recommendation: the option and the reason.
|
|
48
|
+
|
|
49
|
+
On the page, put these in `context` (and `why`), `question`, each option's
|
|
50
|
+
`description`, `example` and `tradeoff`, and `recommended: true` on one option
|
|
51
|
+
with the reason in `recommendation`. A small choice can be shorter, but still
|
|
52
|
+
give the context the user needs to answer it.
|
|
53
|
+
|
|
54
|
+
**Words.** Write questions in
|
|
55
|
+
[ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/): one
|
|
56
|
+
meaning for each word, active voice, short sentences, one idea in each sentence.
|
|
57
|
+
Use the project's terms from `GLOSSARY.md`, or the glossary that `GLOSSARY-MAP.md`
|
|
58
|
+
names, when the project has one. When the user says a question is not clear
|
|
59
|
+
("wait, what?"), do not repeat it. Write it again with the context that was
|
|
60
|
+
missing. This follows `wait-what` in
|
|
61
|
+
[mattpocock/skills](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what).
|
|
9
62
|
|
|
10
63
|
The renderer is deterministic. Agents author a short view-data file, such as
|
|
11
64
|
[`templates/artifact.json`](../templates/artifact.json), and link existing
|
|
@@ -32,9 +85,13 @@ review) is shown where they are working, and you always say its path:
|
|
|
32
85
|
## Decisions and view data
|
|
33
86
|
|
|
34
87
|
A brief decision keeps its existing `id`, `status`, `question`, `answer`,
|
|
35
|
-
`options`, and `affected` fields.
|
|
36
|
-
|
|
37
|
-
|
|
88
|
+
`options`, and `affected` fields. A decision can also have `context` and `why`
|
|
89
|
+
(shown before the options), `details` (under "More detail") and
|
|
90
|
+
`recommendation` (the reason for the recommended option). An option can have
|
|
91
|
+
`description`, `example`, `tradeoff`, `recommended: true` (one option at most;
|
|
92
|
+
not `custom`) and `requiresNote: true` when that option needs a short
|
|
93
|
+
explanation. All of these are optional, and the page lists the recommended
|
|
94
|
+
option first. Every question also offers "Something else" (value `custom`,
|
|
38
95
|
note required), so the person can always answer in their own words; do not
|
|
39
96
|
declare it unless you want different wording. The canonical answer remains an
|
|
40
97
|
option `value`, including `custom`. A saved answer keeps its note box: the
|
|
@@ -54,9 +54,18 @@ render nothing, ask nothing: a repeated setup must leave the project unchanged.
|
|
|
54
54
|
each choice with options as a decision in a setup brief at
|
|
55
55
|
`.joycraft/local/setup/brief.md` (format of `.joycraft/templates/brief.md`,
|
|
56
56
|
`feature: setup`; give `.joycraft/local/` a `.gitignore` of `*` when it has
|
|
57
|
-
none, so nothing there becomes a project change)
|
|
58
|
-
|
|
59
|
-
|
|
57
|
+
none, so nothing there becomes a project change). First, when
|
|
58
|
+
`node .joycraft/runtime/artifacts/cli.mjs questions` prints `unset: true`,
|
|
59
|
+
ask how the user wants questions, as two decisions: pacing (one decision at
|
|
60
|
+
a time with a short discussion after each answer, or a page of decisions)
|
|
61
|
+
and surface (the decision page, or numbered prose in chat). Give an example
|
|
62
|
+
of each. Ask only these two, in today's style (a page), and wait for the
|
|
63
|
+
answer before you ask any other setup question. Record it with
|
|
64
|
+
`questions --set pacing=...,surface=...` and say that the user can change it
|
|
65
|
+
for one feature later. Never ask again when a style is recorded. Then ask the
|
|
66
|
+
other setup decisions in that style ([asking questions](artifacts.md#asking-questions));
|
|
67
|
+
plain chat with no decision is only for one quick yes/no or an open question
|
|
68
|
+
with no options. The brief is scratch:
|
|
60
69
|
each answer then goes to its home in step 3. Stop when the user says enough. Never ask again
|
|
61
70
|
what the user answered or a home already states. Keep the user's words apart
|
|
62
71
|
from your observations and assumptions. On a bare project, offer the
|
|
@@ -66,12 +75,16 @@ render nothing, ask nothing: a repeated setup must leave the project unchanged.
|
|
|
66
75
|
“First action in each session: run
|
|
67
76
|
`node .joycraft/runtime/update-check.mjs check`. If it prints JSON, follow
|
|
68
77
|
`.joycraft/references/update.md`.” and “Show every document a person must
|
|
69
|
-
read
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
`.joycraft/references/artifacts.md`) for a brief
|
|
73
|
-
|
|
74
|
-
|
|
78
|
+
read or review (a brief, plan, spec set or review) as a rendered page,
|
|
79
|
+
never only as Markdown in chat: use the decision artifact
|
|
80
|
+
(`node .joycraft/runtime/artifacts/cli.mjs`, see
|
|
81
|
+
`.joycraft/references/artifacts.md`) for a brief, or an HTML page for any
|
|
82
|
+
other document. Show it where the person works (see
|
|
83
|
+
`.joycraft/references/artifacts.md#showing-a-page`) and say where it is.
|
|
84
|
+
Ask questions in the project's question style
|
|
85
|
+
(`.joycraft/references/artifacts.md#asking-questions`).” Replace an older
|
|
86
|
+
version of this line that lists a "set of questions", so it does not
|
|
87
|
+
override a chat question style.
|
|
75
88
|
- **The map**: one `## Context Map` table (`| Document | Read when |`). One
|
|
76
89
|
row per real home: each required or reference doc, and each home you
|
|
77
90
|
create. A read-when names the work that needs the doc ("Changing how counts
|
|
@@ -168,9 +181,11 @@ detects each package from its manifests, probes versions read-only, and prints
|
|
|
168
181
|
one table and at most one question. It never installs. When it prints
|
|
169
182
|
`Review loop unchanged.`, ask nothing. Packages come from declared workspaces;
|
|
170
183
|
with none and no root manifest, from the manifests below the root that git does
|
|
171
|
-
not ignore. When it prints `No packages found`, ask the user which folders
|
|
172
|
-
the apps and pass them as `--packages <dir,dir>` to `plan`, `install` and
|
|
173
|
-
`record`.
|
|
184
|
+
not ignore. When it prints `No packages found`, ask the user once which folders
|
|
185
|
+
hold the apps and pass them as `--packages <dir,dir>` to `plan`, `install` and
|
|
186
|
+
`record`. When the user says there is no app to review (for example one script
|
|
187
|
+
with no manifest), record their words with `record --none "<reason>"`; a
|
|
188
|
+
repeated setup then prints `Review loop unchanged.` and asks nothing.
|
|
174
189
|
|
|
175
190
|
Show the table: what the plan found per package. Ask the user to confirm it or
|
|
176
191
|
name a tool the plan missed, together with its one question. For a gap, say
|
|
@@ -296,10 +311,11 @@ changes the next action. Prefer one short contextual question and continue
|
|
|
296
311
|
independent work while it is pending. Do not generate a questionnaire or start
|
|
297
312
|
building an imagined app.
|
|
298
313
|
|
|
299
|
-
Use the project’s existing interaction home for a choice.
|
|
300
|
-
options
|
|
301
|
-
|
|
302
|
-
|
|
314
|
+
Use the project’s existing interaction home for a choice. Ask a question with
|
|
315
|
+
options in the user's question style ([asking questions](artifacts.md#asking-questions)),
|
|
316
|
+
in the decision artifact or in chat; only one quick yes/no or an open question
|
|
317
|
+
with no options stays in native chat without a decision. Retain a chat answer in
|
|
318
|
+
the owning brief and do not ask it again.
|
|
303
319
|
|
|
304
320
|
## Finish setup and continue
|
|
305
321
|
|
|
@@ -315,7 +331,7 @@ installation manifest `.joycraft/installation.json` records the installed bytes;
|
|
|
315
331
|
it is dispatch input, not proof that hooks ran or that a review was independent.
|
|
316
332
|
|
|
317
333
|
A new worker reads `.joycraft/preferences.json` before work, reuses explicit
|
|
318
|
-
model, effort, role, concurrency and
|
|
334
|
+
model, effort, role, concurrency, verification and question-style choices, and inspects the
|
|
319
335
|
host's available planner, implementer, reviewer, testing, UI and fixture
|
|
320
336
|
capabilities instead of assuming a model. It states unavailable roles plainly.
|
|
321
337
|
Setup and upgrade never change accepted queues, decision state, user guidance or
|
|
@@ -28,7 +28,12 @@ Use the version from `latest`:
|
|
|
28
28
|
migration plan and stops: show the plan and follow its steps with the user. Never
|
|
29
29
|
apply a migration without the user's yes.
|
|
30
30
|
3. Run `npx joycraft@<latest> doctor .`.
|
|
31
|
-
4. Tell the user in plain words what is different now.
|
|
31
|
+
4. Tell the user in plain words what is different now. For a `minor` or
|
|
32
|
+
`migration`, name what the user can now do or say, one line per release since
|
|
33
|
+
the old version, from the release summaries the check listed (and the
|
|
34
|
+
changelog, when you can read it). When
|
|
35
|
+
`node .joycraft/runtime/artifacts/cli.mjs questions` prints `unset: true`,
|
|
36
|
+
ask for the question style now, as [setup](setup.md) step 2 says.
|
|
32
37
|
5. Run the review-loop plan
|
|
33
38
|
([review loop tools](setup.md#review-loop-tools)). When it prints
|
|
34
39
|
`Review loop unchanged.`, say nothing about it. When it reports a newly
|
|
@@ -24,8 +24,10 @@ Routine refinements within the answer do not require another approval.
|
|
|
24
24
|
|
|
25
25
|
## Decision artifacts
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
[
|
|
27
|
+
Record each choice between options as a brief decision and ask it in the
|
|
28
|
+
user's question style ([asking questions](artifacts.md#asking-questions)): one
|
|
29
|
+
at a time or as a page, in the artifact or in chat. Save every answer to the
|
|
30
|
+
brief, whatever the surface. Plain chat with no decision record is only for one
|
|
29
31
|
quick yes/no or an open question with no options.
|
|
30
32
|
The brief remains authoritative; artifact data selects what to show and does not
|
|
31
33
|
copy the brief or hold independent answers.
|
|
@@ -36,7 +38,9 @@ The optional `joycraft-ui-slice/scripts/serve.mjs` helper supports a JSON flow
|
|
|
36
38
|
array under top-level `decisions:` in YAML frontmatter, as in the brief template.
|
|
37
39
|
Each displayed record has `id`, `status`, `question`, `answer` (null or an option
|
|
38
40
|
value), `options` (two or more `{value,label}` records) and `affected` (paths/IDs).
|
|
39
|
-
Options may additionally have a concise `description`
|
|
41
|
+
Options may additionally have a concise `description`, `example`, `tradeoff`,
|
|
42
|
+
`recommended: true` and `requiresNote: true`; a decision may have `context`,
|
|
43
|
+
`why`, `details` and `recommendation` ([decisions](artifacts.md#decisions-and-view-data)).
|
|
40
44
|
Other record fields and all text outside that array are preserved. Unsupported or
|
|
41
45
|
malformed frontmatter is rejected; adapt the artifact to an existing project
|
|
42
46
|
format instead of migrating it without cause. This is an authoring convention,
|
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
import { resolve } from 'node:path';
|
|
2
2
|
import { pathToFileURL } from 'node:url';
|
|
3
|
-
import { loadArtifact, persistResponses, readProjectFile, writeArtifact } from './model.mjs';
|
|
3
|
+
import { loadArtifact, persistResponses, readProjectFile, replaceBrief, writeArtifact } from './model.mjs';
|
|
4
4
|
import { renderArtifact } from './render.mjs';
|
|
5
5
|
import { startArtifact } from './server.mjs';
|
|
6
|
-
import { setArtifactColors, setArtifactTheme } from './preferences.mjs';
|
|
6
|
+
import { briefQuestionStyle, effectiveQuestionStyle, parseQuestionStyle, projectQuestionStyle, setArtifactColors, setArtifactTheme, setQuestionStyle, withBriefQuestionStyle } from './preferences.mjs';
|
|
7
7
|
|
|
8
8
|
export async function main(argv, root = process.cwd()) {
|
|
9
9
|
const [command, ...args] = argv;
|
|
10
|
-
const flags = command === 'serve' ? ['--brief', '--view', '--theme'] : command === 'build' ? ['--brief', '--view', '--out', '--mode', '--theme'] : command === 'import' ? ['--brief', '--view', '--responses', '--apply'] : command === 'theme' ? ['--set'] : command === 'colors' ? ['--set', '--reset'] : [];
|
|
11
|
-
if (!flags.length) throw new Error('Use serve --brief <path> [--view <path>] [--theme light|dark], build --brief <path> [--view <path>] --out <path> --mode claude|portable [--theme light|dark], import --brief <path> [--view <path>] --responses <path> [--apply], theme --set light|dark,
|
|
10
|
+
const flags = command === 'serve' ? ['--brief', '--view', '--theme'] : command === 'build' ? ['--brief', '--view', '--out', '--mode', '--theme'] : command === 'import' ? ['--brief', '--view', '--responses', '--apply'] : command === 'theme' ? ['--set'] : command === 'colors' ? ['--set', '--reset'] : command === 'questions' ? ['--brief', '--set', '--clear'] : [];
|
|
11
|
+
if (!flags.length) throw new Error('Use serve --brief <path> [--view <path>] [--theme light|dark], build --brief <path> [--view <path>] --out <path> --mode claude|portable [--theme light|dark], import --brief <path> [--view <path>] --responses <path> [--apply], theme --set light|dark, colors --set <colors.json> | --reset, or questions [--brief <path>] [--set pacing=one-at-a-time|page,surface=chat|artifact | --clear]');
|
|
12
12
|
const values = {};
|
|
13
13
|
for (let i = 0; i < args.length; i += 1) {
|
|
14
14
|
const flag = args[i];
|
|
15
15
|
if (!flags.includes(flag) || Object.hasOwn(values, flag)) throw new Error(`Unknown or repeated argument: ${flag}`);
|
|
16
|
-
if (flag === '--apply' || flag === '--reset') values[flag] = true;
|
|
16
|
+
if (flag === '--apply' || flag === '--reset' || flag === '--clear') values[flag] = true;
|
|
17
17
|
else { if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`Missing value for ${flag}`); values[flag] = args[++i]; }
|
|
18
18
|
}
|
|
19
19
|
if (command === 'theme') {
|
|
@@ -22,6 +22,30 @@ export async function main(argv, root = process.cwd()) {
|
|
|
22
22
|
console.log(JSON.stringify({ path: '.joycraft/preferences.json', theme: preferences.artifacts.theme }, null, 2));
|
|
23
23
|
return preferences;
|
|
24
24
|
}
|
|
25
|
+
if (command === 'questions') {
|
|
26
|
+
// With --brief, --set and --clear change only that feature; without it, --set changes the project default.
|
|
27
|
+
const briefPath = values['--brief'];
|
|
28
|
+
if (values['--set'] && values['--clear']) throw new Error('Use --set or --clear, not both');
|
|
29
|
+
if (values['--clear'] && !briefPath) throw new Error('--clear needs --brief: it removes a feature\'s own question style');
|
|
30
|
+
const change = values['--set'] ? parseQuestionStyle(values['--set']) : values['--clear'] ? null : undefined;
|
|
31
|
+
// Read the project default first: a bad stored preference must stop the command before any write.
|
|
32
|
+
const project = await projectQuestionStyle(root);
|
|
33
|
+
let brief;
|
|
34
|
+
if (briefPath) {
|
|
35
|
+
const text = (await readProjectFile(root, briefPath)).toString('utf8');
|
|
36
|
+
brief = briefQuestionStyle(text);
|
|
37
|
+
if (change !== undefined) {
|
|
38
|
+
const updated = withBriefQuestionStyle(text, change);
|
|
39
|
+
// Check the new text before the write: a failed command must leave the brief as it was.
|
|
40
|
+
brief = briefQuestionStyle(updated);
|
|
41
|
+
if (JSON.stringify(brief ?? null) !== JSON.stringify(change === null ? null : { ...(briefQuestionStyle(text) ?? {}), ...change })) throw new Error('Could not write question-style: safely; the brief is unchanged');
|
|
42
|
+
await replaceBrief(root, briefPath, text, updated);
|
|
43
|
+
}
|
|
44
|
+
} else if (change) await setQuestionStyle(root, change);
|
|
45
|
+
const style = effectiveQuestionStyle({ project: change && !briefPath ? await projectQuestionStyle(root) : project, brief });
|
|
46
|
+
console.log(JSON.stringify(style, null, 2));
|
|
47
|
+
return style;
|
|
48
|
+
}
|
|
25
49
|
if (command === 'colors') {
|
|
26
50
|
if (!values['--set'] === !values['--reset']) throw new Error('Colors needs --set <colors.json> or --reset');
|
|
27
51
|
let colors = null;
|
|
@@ -102,16 +102,25 @@ function displayedDecision(brief, id) {
|
|
|
102
102
|
!Array.isArray(decision.affected) || !decision.affected.every(nonempty)) {
|
|
103
103
|
throw new Error('Displayed decision needs question, options and affected references');
|
|
104
104
|
}
|
|
105
|
-
for (const field of ['why', 'context', 'details']) validateOptionalString(decision[field], `Decision ${field}`);
|
|
105
|
+
for (const field of ['why', 'context', 'details', 'recommendation']) validateOptionalString(decision[field], `Decision ${field}`);
|
|
106
106
|
const values = new Set();
|
|
107
|
+
let recommended = 0;
|
|
107
108
|
for (const option of decision.options) {
|
|
108
109
|
if (!option || typeof option !== 'object' || Array.isArray(option) || !nonempty(option.value) || !nonempty(option.label) || values.has(option.value)) {
|
|
109
110
|
throw new Error('Invalid decision options');
|
|
110
111
|
}
|
|
111
|
-
|
|
112
|
+
for (const field of ['description', 'example', 'tradeoff']) validateOptionalString(option[field], `Option ${field}`);
|
|
112
113
|
if (option.requiresNote !== undefined && typeof option.requiresNote !== 'boolean') throw new Error('Option requiresNote must be boolean');
|
|
114
|
+
if (option.recommended !== undefined && typeof option.recommended !== 'boolean') throw new Error('Option recommended must be boolean');
|
|
115
|
+
if (option.recommended === true) {
|
|
116
|
+
if (option.value === CUSTOM_OPTION.value) throw new Error('"Something else" cannot be the recommended option');
|
|
117
|
+
recommended += 1;
|
|
118
|
+
}
|
|
113
119
|
values.add(option.value);
|
|
114
120
|
}
|
|
121
|
+
// One recommendation at most, and a stated reason needs the option it recommends.
|
|
122
|
+
if (recommended > 1) throw new Error('Only one option can be recommended');
|
|
123
|
+
if (decision.recommendation !== undefined && recommended === 0) throw new Error('A recommendation needs a recommended option');
|
|
115
124
|
values.add(CUSTOM_OPTION.value);
|
|
116
125
|
if (!(decision.answer === null || values.has(decision.answer)) || (decision.status === 'clarified' && decision.answer === null)) {
|
|
117
126
|
throw new Error('Invalid decision answer');
|
|
@@ -127,15 +136,14 @@ function publicQuestion(decision) {
|
|
|
127
136
|
question: decision.question,
|
|
128
137
|
options: withCustomOption(decision.options).map(option => {
|
|
129
138
|
const result = { value: option.value, label: option.label };
|
|
130
|
-
if (option
|
|
131
|
-
if (option.requiresNote !== undefined) result.requiresNote = option.requiresNote;
|
|
139
|
+
for (const field of ['description', 'example', 'tradeoff', 'requiresNote', 'recommended']) if (option[field] !== undefined) result[field] = option[field];
|
|
132
140
|
return result;
|
|
133
141
|
}),
|
|
134
142
|
affected: [...decision.affected],
|
|
135
143
|
status: decision.status,
|
|
136
144
|
answer: decision.answer
|
|
137
145
|
};
|
|
138
|
-
for (const field of ['why', 'context', 'details']) if (decision[field] !== undefined) question[field] = decision[field];
|
|
146
|
+
for (const field of ['why', 'context', 'details', 'recommendation']) if (decision[field] !== undefined) question[field] = decision[field];
|
|
139
147
|
if (decision.note !== undefined) question.note = decision.note;
|
|
140
148
|
return question;
|
|
141
149
|
}
|
|
@@ -111,7 +111,7 @@ export function validateEnvelope(envelope, model) {
|
|
|
111
111
|
}
|
|
112
112
|
|
|
113
113
|
/** Cooperative lock + compare before atomic replacement; no silent stale write. */
|
|
114
|
-
async function replaceBrief(root, path, before, after) {
|
|
114
|
+
export async function replaceBrief(root, path, before, after) {
|
|
115
115
|
if (before === after) return;
|
|
116
116
|
const absolute = await checkedPath(root, path);
|
|
117
117
|
const lock = `${absolute}.joycraft-answer-lock`;
|
|
@@ -76,6 +76,7 @@ function parsePreferences(bytes) {
|
|
|
76
76
|
catch { throw new Error(`Invalid JSON: ${preferencePath}`); }
|
|
77
77
|
if (!preferences || typeof preferences !== 'object' || Array.isArray(preferences)) throw new Error(`${preferencePath} must contain an object`);
|
|
78
78
|
if (preferences.artifacts !== undefined && (!preferences.artifacts || typeof preferences.artifacts !== 'object' || Array.isArray(preferences.artifacts))) throw new Error(`${preferencePath} artifacts must be an object`);
|
|
79
|
+
if (preferences.questions !== undefined) checkedQuestionStyle(preferences.questions, `${preferencePath} questions`);
|
|
79
80
|
return preferences;
|
|
80
81
|
}
|
|
81
82
|
|
|
@@ -87,7 +88,7 @@ export async function artifactTheme(root) {
|
|
|
87
88
|
return preferences.artifacts?.theme === undefined ? undefined : checkedTheme(preferences.artifacts.theme, 'Artifact preference theme');
|
|
88
89
|
}
|
|
89
90
|
|
|
90
|
-
async function updatePreferences(root, change) {
|
|
91
|
+
async function updatePreferences(root, change, section = 'artifacts') {
|
|
91
92
|
const base = await realpath(root);
|
|
92
93
|
const directory = join(base, '.joycraft');
|
|
93
94
|
await mkdir(directory, { recursive: true });
|
|
@@ -97,7 +98,7 @@ async function updatePreferences(root, change) {
|
|
|
97
98
|
let preferences;
|
|
98
99
|
try { preferences = parsePreferences(await readFile(path)); }
|
|
99
100
|
catch (error) { if (error.code !== 'ENOENT') throw error; preferences = { schemaVersion: 1 }; }
|
|
100
|
-
const updated = { ...preferences,
|
|
101
|
+
const updated = { ...preferences, [section]: change({ ...(preferences[section] ?? {}) }) };
|
|
101
102
|
const temporary = `${path}.prefs-${randomBytes(8).toString('hex')}`;
|
|
102
103
|
const file = await open(temporary, 'wx', 0o600);
|
|
103
104
|
try { await file.writeFile(`${JSON.stringify(updated, null, 2)}\n`); await file.sync(); }
|
|
@@ -125,3 +126,95 @@ export async function setArtifactColors(root, colors) {
|
|
|
125
126
|
const checked = colors === null ? null : await checkedColors(colors);
|
|
126
127
|
return updatePreferences(root, ({ colors: _colors, ...artifacts }) => checked && Object.keys(checked).length ? { ...artifacts, colors: checked } : artifacts);
|
|
127
128
|
}
|
|
129
|
+
|
|
130
|
+
// How an agent asks the user: how many decisions at once, and where.
|
|
131
|
+
const questionValues = Object.freeze({ pacing: ['one-at-a-time', 'page'], surface: ['chat', 'artifact'] });
|
|
132
|
+
/** With no recorded style, Joycraft asks as it always has (decision `unset-default`). */
|
|
133
|
+
export const DEFAULT_QUESTION_STYLE = Object.freeze({ pacing: 'page', surface: 'artifact' });
|
|
134
|
+
const styleLine = /^question-style:[ \t]*([^\r\n]*)/gm;
|
|
135
|
+
|
|
136
|
+
export function checkedQuestionStyle(style, source = 'Question style') {
|
|
137
|
+
if (!style || typeof style !== 'object' || Array.isArray(style)) throw new Error(`${source} must be an object with pacing and/or surface`);
|
|
138
|
+
for (const [key, value] of Object.entries(style)) {
|
|
139
|
+
if (!Object.hasOwn(questionValues, key)) throw new Error(`${source} has an unknown key: ${key}. Use: ${Object.keys(questionValues).join(', ')}`);
|
|
140
|
+
if (!questionValues[key].includes(value)) throw new Error(`${source} ${key} must be ${questionValues[key].join(' or ')}`);
|
|
141
|
+
}
|
|
142
|
+
return style;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** Parse `pacing=one-at-a-time,surface=chat` from the command line. */
|
|
146
|
+
export function parseQuestionStyle(value) {
|
|
147
|
+
const style = {};
|
|
148
|
+
for (const pair of String(value).split(',')) {
|
|
149
|
+
const [key, choice, extra] = pair.split('=').map(part => part.trim());
|
|
150
|
+
if (!key || choice === undefined || extra !== undefined || Object.hasOwn(style, key)) throw new Error('Use --set key=value[,key=value], for example pacing=one-at-a-time,surface=chat');
|
|
151
|
+
style[key] = choice;
|
|
152
|
+
}
|
|
153
|
+
return checkedQuestionStyle(style, 'Question style');
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
function frontmatterBounds(text) {
|
|
157
|
+
const match = /^(---\r?\n)([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
|
|
158
|
+
if (!match) throw new Error('Brief needs YAML frontmatter');
|
|
159
|
+
const start = match[1].length;
|
|
160
|
+
return { start, end: start + match[2].length };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function styleLines(text) {
|
|
164
|
+
const { start, end } = frontmatterBounds(text);
|
|
165
|
+
return [...text.slice(start, end).matchAll(styleLine)].map(match => ({ index: start + match.index, length: match[0].length, value: match[1] }));
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/** The brief's own question style, or undefined when it keeps the project's. */
|
|
169
|
+
export function briefQuestionStyle(text) {
|
|
170
|
+
const lines = styleLines(text);
|
|
171
|
+
if (lines.length > 1) throw new Error('Expected at most one question-style: line');
|
|
172
|
+
if (!lines.length) return undefined;
|
|
173
|
+
let style;
|
|
174
|
+
try { style = JSON.parse(lines[0].value); }
|
|
175
|
+
catch { throw new Error('question-style: must be a JSON object, for example {"pacing":"one-at-a-time"}'); }
|
|
176
|
+
return checkedQuestionStyle(style, 'Brief question-style');
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/** Replace, add or (with null) remove only the brief's question-style line. */
|
|
180
|
+
export function withBriefQuestionStyle(text, style) {
|
|
181
|
+
const current = briefQuestionStyle(text);
|
|
182
|
+
const [line] = styleLines(text);
|
|
183
|
+
if (style === null) {
|
|
184
|
+
if (!line) return text;
|
|
185
|
+
// Remove the line with its own ending, whatever the rest of the file uses.
|
|
186
|
+
const next = text.indexOf('\n', line.index + line.length);
|
|
187
|
+
return text.slice(0, line.index) + text.slice(next + 1);
|
|
188
|
+
}
|
|
189
|
+
const merged = checkedQuestionStyle({ ...(current ?? {}), ...style }, 'Brief question-style');
|
|
190
|
+
const replacement = `question-style: ${JSON.stringify(merged)}`;
|
|
191
|
+
if (line) return text.slice(0, line.index) + replacement + text.slice(line.index + line.length);
|
|
192
|
+
// The new line takes the ending of the last frontmatter line, so --clear gives the same bytes back.
|
|
193
|
+
const { end } = frontmatterBounds(text);
|
|
194
|
+
const newline = text.startsWith('\r\n', end) ? '\r\n' : '\n';
|
|
195
|
+
return text.slice(0, end) + newline + replacement + text.slice(end);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
export async function projectQuestionStyle(root) {
|
|
199
|
+
let path;
|
|
200
|
+
try { path = await checkedPreferencePath(root); }
|
|
201
|
+
catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
|
|
202
|
+
return parsePreferences(await readFile(path)).questions;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
export async function setQuestionStyle(root, style) {
|
|
206
|
+
checkedQuestionStyle(style);
|
|
207
|
+
return updatePreferences(root, questions => ({ ...questions, ...style }), 'questions');
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/** Each key from the brief first, then the project, then the default; `source` says which. */
|
|
211
|
+
export function effectiveQuestionStyle({ project, brief } = {}) {
|
|
212
|
+
const result = {};
|
|
213
|
+
const source = {};
|
|
214
|
+
for (const key of Object.keys(questionValues)) {
|
|
215
|
+
[result[key], source[key]] = brief?.[key] !== undefined ? [brief[key], 'brief'] : project?.[key] !== undefined ? [project[key], 'project'] : [DEFAULT_QUESTION_STYLE[key], 'default'];
|
|
216
|
+
}
|
|
217
|
+
result.source = source;
|
|
218
|
+
if (project === undefined || Object.keys(project).length === 0) result.unset = true;
|
|
219
|
+
return result;
|
|
220
|
+
}
|
|
@@ -554,7 +554,8 @@ const roleText = { ui: 'tool that can show the UI', request: 'HTTP check', tests
|
|
|
554
554
|
export function renderPlan(plan, changes = null) {
|
|
555
555
|
if (!plan.packages.length) {
|
|
556
556
|
return ['Review loop plan', '', 'No packages found: no workspaces are declared and no project manifest was found below the root.',
|
|
557
|
-
'', 'Which folders hold the apps? Name them with `--packages <dir,dir>` on plan, install and record.'
|
|
557
|
+
'', 'Which folders hold the apps? Name them with `--packages <dir,dir>` on plan, install and record.',
|
|
558
|
+
'If the project has no app to review, record the user\'s reason with `record --none "<reason>"`, so this is not asked again.'].join('\n');
|
|
558
559
|
}
|
|
559
560
|
const lines = ['Review loop plan', '', '| Package | Kind | Tool | Status | To install | Can show |', '|---|---|---|---|---|---|'];
|
|
560
561
|
for (const entry of plan.packages) for (const item of entry.tools.filter(tool => !tool.shared)) {
|
|
@@ -781,8 +782,10 @@ const cellSafe = text => String(text).replace(/\|/g, '\\|').replace(/\n+/g, '; '
|
|
|
781
782
|
* Write the chosen setup to AGENTS.md under `## Review loop`, replacing only that section: one row per package.
|
|
782
783
|
* Earlier picks and skips stay for the packages this call does not name. Host tools go to the local record only.
|
|
783
784
|
*/
|
|
784
|
-
export function recordReviewLoop(root, plan, { skipped = [], choose = [], commands = [], canShow = [], host = null, hostTools = [] } = {}) {
|
|
785
|
-
if (!
|
|
785
|
+
export function recordReviewLoop(root, plan, { skipped = [], choose = [], commands = [], canShow = [], host = null, hostTools = [], none = null } = {}) {
|
|
786
|
+
if (none !== null && (typeof none !== 'string' || !none.trim())) throw new Error('--none takes the user\'s reason, for example --none "a single script, no app to review"');
|
|
787
|
+
if (none !== null && plan.packages.length) throw new Error(`--none records that there are no packages, but this project has ${plan.packages.map(entry => entry.path).join(', ')}`);
|
|
788
|
+
if (!plan.packages.length && none === null) throw new Error('No packages found, so there is nothing to record; name them with --packages <dir,dir>, or record the user\'s reason with --none "<reason>"');
|
|
786
789
|
if (hostTools.length && !host) throw new Error('--host-tools needs --host <name>, the host these tools belong to');
|
|
787
790
|
const picks = picksFor(root, plan, { choose, commands, canShow });
|
|
788
791
|
const skips = skipsFor(plan, skipped);
|
|
@@ -822,8 +825,8 @@ export function recordReviewLoop(root, plan, { skipped = [], choose = [], comman
|
|
|
822
825
|
const section = [sectionHeading, '',
|
|
823
826
|
'Recorded by Joycraft setup. The implementer, reviewer and UI checks use these tools and commands.',
|
|
824
827
|
`Tools a host brings itself are recorded per machine in \`${localFile}\`, not here.`, '',
|
|
825
|
-
...rows,
|
|
826
|
-
'', `<!-- joycraft:review-loop v2 ${JSON.stringify({ packages })} -->`, ''].join('\n');
|
|
828
|
+
...(none === null ? rows : [`No app packages to review. The user said: ${cellSafe(none.trim())}`]),
|
|
829
|
+
'', `<!-- joycraft:review-loop v2 ${JSON.stringify({ packages, ...(none === null ? {} : { none: none.trim() }) })} -->`, ''].join('\n');
|
|
827
830
|
const file = path.join(root, 'AGENTS.md');
|
|
828
831
|
const text = read(file);
|
|
829
832
|
let created = false;
|
|
@@ -863,6 +866,8 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
863
866
|
const repeated = new Set(['--choose', '--command', '--can-show', '--skip']);
|
|
864
867
|
for (let index = 0; index < rest.length; index += 1) {
|
|
865
868
|
if (rest[index] === '--yes') { flags['--yes'] = true; continue; }
|
|
869
|
+
// A flag's value is the next word; another flag there means the value is missing.
|
|
870
|
+
if (rest[index + 1] === undefined || rest[index + 1].startsWith('--')) throw new Error(`Missing value for ${rest[index]}`);
|
|
866
871
|
if (repeated.has(rest[index])) (flags[rest[index]] ??= []).push(rest[index + 1]);
|
|
867
872
|
else flags[rest[index]] = rest[index + 1];
|
|
868
873
|
index += 1;
|
|
@@ -889,12 +894,12 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
889
894
|
// The shared record is detected without the host's tools; those go to the local record.
|
|
890
895
|
const result = recordReviewLoop(root, reviewLoopPlan(root, { ...options, hostTools: [] }), {
|
|
891
896
|
skipped: many('--skip'), choose: many('--choose'), commands: many('--command', false), canShow: many('--can-show', false),
|
|
892
|
-
host: flags['--host'] ?? null, hostTools: options.hostTools });
|
|
897
|
+
host: flags['--host'] ?? null, hostTools: options.hostTools, none: flags['--none'] ?? null });
|
|
893
898
|
process.stdout.write(`${JSON.stringify(result)}\n`);
|
|
894
899
|
return result;
|
|
895
900
|
}
|
|
896
901
|
throw new Error('Usage: review-tools.mjs plan|install|record --root <project> [--packages apps/web,apps/api] [--host-tools browser,simulator] [--tools playwright --yes]'
|
|
897
|
-
+ ' [record: --choose <package>=<tool> --command <package>=<command> --can-show <package>=picture,run --skip <tool>|<package>:<tool>|<package> --host <name>]');
|
|
902
|
+
+ ' [record: --choose <package>=<tool> --command <package>=<command> --can-show <package>=picture,run --skip <tool>|<package>:<tool>|<package> --host <name> | --none "<reason>"]');
|
|
898
903
|
}
|
|
899
904
|
|
|
900
905
|
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
feature: example-feature
|
|
3
3
|
decisions: [
|
|
4
|
-
{"id":"presentation","status":"open","question":"Which presentation fits your task?","answer":null,"options":[{"value":"rows","label":"Compact rows"},{"value":"cards","label":"Visual cards"}],"affected":["collection-presentation"]}
|
|
4
|
+
{"id":"presentation","status":"open","question":"Which presentation fits your task?","answer":null,"context":"The collection page lists 200 items. Today it shows plain rows, and users ask for pictures.","options":[{"value":"rows","label":"Compact rows","description":"Keep the list and add a small picture to each row.","example":"About 20 items show without scrolling.","tradeoff":"Pictures are too small to compare."},{"value":"cards","label":"Visual cards","recommended":true,"description":"Show each item as a card with a large picture.","example":"About 8 items show without scrolling.","tradeoff":"More scrolling to find one item."}],"recommendation":"Users asked for pictures, and cards show them best.","affected":["collection-presentation"]}
|
|
5
5
|
]
|
|
6
6
|
---
|
|
7
7
|
# Feature intent
|
package/payload/PIN
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"source": "joycraft-prototype",
|
|
4
|
-
"tag": "field-
|
|
5
|
-
"commit": "
|
|
4
|
+
"tag": "field-17",
|
|
5
|
+
"commit": "0e88e6da3adc605a306db1ec058a4690b2eb5cb2",
|
|
6
6
|
"files": {
|
|
7
7
|
".agents/skills/joycraft-cleanup/SKILL.md": "99ce785e551be33412ac7a99ce44585a9b2be4440617caac273680383b4f7057",
|
|
8
8
|
".agents/skills/joycraft-context/SKILL.md": "e2f85baa47058fd61811fdb60d0cb41fb3f505f3957812d929db95bb99124f1b",
|
|
9
9
|
".agents/skills/joycraft-decompose/SKILL.md": "71b518d4fa8aeda5d1c0e72f34b3f7f846b3bba055adf509344b40bea35f070e",
|
|
10
|
-
".agents/skills/joycraft-entry/SKILL.md": "
|
|
10
|
+
".agents/skills/joycraft-entry/SKILL.md": "6b2ac0e52f0751c7b7587b495349c29f707c61421312dc9ad8d3821aec936855",
|
|
11
11
|
".agents/skills/joycraft-implement/SKILL.md": "65909a6e3a320d8c0591e10ea1fc26469facadc27dafd3060dd0eabaf06890d9",
|
|
12
12
|
".agents/skills/joycraft-retro/SKILL.md": "156f36cb047604c734bf273bd02822d964b6af86619ed6c2a30fa6d79eb9a986",
|
|
13
13
|
".agents/skills/joycraft-retro/agents/openai.yaml": "f0eb4732261635f41e08f0bbe9a931d62fd8ac645149d3406e6fc7e16a81750b",
|
|
@@ -18,13 +18,13 @@
|
|
|
18
18
|
".agents/skills/joycraft-verify/SKILL.md": "219f08d5f66d6c63338c7d4cc75e81fe7d2d993723728876136ab8ca5ed6f8c5",
|
|
19
19
|
".claude/agents/joycraft-implementer.md": "30b26779bd49d2d66758bcb26442e78755b018a3830ac52ff634ebf057ce1cc5",
|
|
20
20
|
".claude/agents/joycraft-reviewer.md": "d671eb39827d5139d9d458d4cb7f5ce624bd40ec8cc5479f9d285bb787b5e5c6",
|
|
21
|
-
".joycraft/assets/artifacts/kit.css": "
|
|
22
|
-
".joycraft/assets/artifacts/kit.js": "
|
|
21
|
+
".joycraft/assets/artifacts/kit.css": "9c19cc52f16eb1d1beb6222ec4e206c567daf9952ff1f5597ea4d6050b72125a",
|
|
22
|
+
".joycraft/assets/artifacts/kit.js": "c60ae4441fb20146677313b27f949598889f40e8b90167b70db04f997854966d",
|
|
23
23
|
".joycraft/assets/artifacts/transports.js": "318e97895468b47f07febc913d3a6e100b0ad19b78b3a4fc51bebc488e67c25d",
|
|
24
24
|
".joycraft/contracts/types.d.ts": "e91f6a4199c0219cda3630a27ee0281ef94d4284221910840961061ee3b30d4f",
|
|
25
25
|
".joycraft/references/architecture.md": "52eaaa4b88053481c9f8cad2418ea0f1db880184c3a50c95901f30f24be75852",
|
|
26
26
|
".joycraft/references/archive.md": "e9e662096f9e95d132c29e07d1a2624ca0826b5e9c1042f411e4ea2bf3805b67",
|
|
27
|
-
".joycraft/references/artifacts.md": "
|
|
27
|
+
".joycraft/references/artifacts.md": "7fab219f6d6d8b23ef3b44a509f637b085b551b34f28622d6dc1167a7f484c6a",
|
|
28
28
|
".joycraft/references/cleanup.md": "aa784c63442a289c67de359d82c78abca3aa8cab5b5e2d91fcd731b45c209003",
|
|
29
29
|
".joycraft/references/completion.md": "7e6b1fe95aab6d97e514995a35f0f6cc67bdea18e4570565e2eef4900e0da01b",
|
|
30
30
|
".joycraft/references/context.md": "df72d3b59d55f0d9741234d4a3d7b56532f560d787c88d5d8630d954472bc430",
|
|
@@ -34,16 +34,16 @@
|
|
|
34
34
|
".joycraft/references/knowledge.md": "a08a117a5d0ae65a45dfd8ab3f3da92dd3c7aeedaa09ae1d71ddf3d6528c7f95",
|
|
35
35
|
".joycraft/references/recurring-failures.md": "7080f6c55492bc19c2897f4f0b128a830a71cdb516678c79ff6e97ffa1dc6b86",
|
|
36
36
|
".joycraft/references/retro.md": "f359eae19747777fb4687c1bc7eb280f0319ae629ee62913346e60fc56551562",
|
|
37
|
-
".joycraft/references/setup.md": "
|
|
37
|
+
".joycraft/references/setup.md": "a9bd9072adc9f021b46287ff0422281ddb2285ac34738b6e29ad11cc60e8a6e5",
|
|
38
38
|
".joycraft/references/testing.md": "ddbc0e69212f4bf29f32f65e139c016b12eb40c29f621a99510129bedf292950",
|
|
39
|
-
".joycraft/references/update.md": "
|
|
40
|
-
".joycraft/references/workflow.md": "
|
|
39
|
+
".joycraft/references/update.md": "36af36ab3d47b5ea46a8f71090333771e5e1deaa6ca19739a75c9fd4aea14eba",
|
|
40
|
+
".joycraft/references/workflow.md": "5b330debc6759b8f7975b159632f51074802067291fe4f4bebfb344f5b60cc52",
|
|
41
41
|
".joycraft/references/worktrees.md": "fb18af0cd76d4e3c5d5b892a7ae10946f21f189e642243235c188b571635f735",
|
|
42
42
|
".joycraft/runtime/archive.mjs": "82b4d9567942a4abd21594ea299c4d323a8306ec7545cb0030431c87bd37f8b2",
|
|
43
|
-
".joycraft/runtime/artifacts/cli.mjs": "
|
|
44
|
-
".joycraft/runtime/artifacts/decisions.mjs": "
|
|
45
|
-
".joycraft/runtime/artifacts/model.mjs": "
|
|
46
|
-
".joycraft/runtime/artifacts/preferences.mjs": "
|
|
43
|
+
".joycraft/runtime/artifacts/cli.mjs": "b3472857b6f8f680dc0d8a7be6495c502a430f5d0c47c88d44b42217e541b528",
|
|
44
|
+
".joycraft/runtime/artifacts/decisions.mjs": "e54fe173ca9050d495fd20b05aaedee8c918f3074553b6b7292cb40f500cbcb2",
|
|
45
|
+
".joycraft/runtime/artifacts/model.mjs": "1349e081d9ef24b0bbcc1e3d9b220d043917a51e89a3e1798950ed241c8ab41d",
|
|
46
|
+
".joycraft/runtime/artifacts/preferences.mjs": "859c46cb9639888d0143fec7533962c22faf7accdff43e87ffd72a730b9b71e3",
|
|
47
47
|
".joycraft/runtime/artifacts/render.mjs": "488673cab94fa6bfde223c2c41650f8e183f7ac0be3840d371ee057d95ea0fa5",
|
|
48
48
|
".joycraft/runtime/artifacts/server.mjs": "0c787812ffbea22c3edb7cb7281e95f54e44da4361f57ac9906487e7b5e6f8e9",
|
|
49
49
|
".joycraft/runtime/cleanup.mjs": "9a10dfd27c12f807c71f407352f1526fdb9b4632c523a965952f65d1b7af158c",
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
".joycraft/runtime/redact.mjs": "cc8c0fe5e8d8fe78116ef126f6eee757a247739084e19c342bcf09a2b06524bc",
|
|
63
63
|
".joycraft/runtime/retro.mjs": "6f3664b0d50c12d4f2d8eef4b4d0d62897939d03e45860d4dcf35c0f5f92677c",
|
|
64
64
|
".joycraft/runtime/review-tools.json": "e0b0f5625654bba5f02d49710356aa1740fd42dd282eef6a29af361396915763",
|
|
65
|
-
".joycraft/runtime/review-tools.mjs": "
|
|
65
|
+
".joycraft/runtime/review-tools.mjs": "15d426558a3884628147debb29136a20f746c3f184c52d6474ad59c222e5d8d5",
|
|
66
66
|
".joycraft/runtime/scope.mjs": "e2cdd929596246bf24e18850698db440119badc7068a3c5beab03ded45abbd65",
|
|
67
67
|
".joycraft/runtime/status.mjs": "3c5bc62c2c0b440da37af950c28f9278c1f743ff4566d3b6c5685465075239af",
|
|
68
68
|
".joycraft/runtime/trace.mjs": "b7924f759b07991f4135698df9c32654631a325957f0f8de5c2ca1262c0a836a",
|
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
".joycraft/runtime/worktrees.mjs": "e5aaa0cfe14b42489c91ead11f12e8a016c468bf66acc07d4b8974e26878e957",
|
|
72
72
|
".joycraft/templates/README.md": "56a166d0729e8b6c3bcb098afb8145006259357087fd8b1f1f343d9a2b4d36e0",
|
|
73
73
|
".joycraft/templates/artifact.json": "fda5f7c32516d6ab094ee0e8506d84a1a0d6d4d0f49048b01aa392c619996f05",
|
|
74
|
-
".joycraft/templates/brief.md": "
|
|
74
|
+
".joycraft/templates/brief.md": "d9f08a0f77b39dca8fed0a9fa343d013c6730d297ab7111975d08fb3d529b0eb",
|
|
75
75
|
".joycraft/templates/decisions.md": "49e0c9b3efe51d1c2e87345fcefe23ef0579e524d50febef8ef43a35141c8002",
|
|
76
76
|
".joycraft/templates/joycraft.yaml": "32ec8e9987030485f2a29d9231b2b15c310470d2f1269550e56c4dde0133becf",
|
|
77
77
|
".joycraft/templates/project-context.md": "cf2455fef663e647962495175fa6a7a44301c4047eecff5811d9c91e21d9e266",
|