joycraft 1.2.1 → 1.3.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/README.md CHANGED
@@ -23,17 +23,18 @@ 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. Run `node .joycraft/runtime/review-tools.mjs plan --root .`. Tell me which tools
27
- you need to check your own work, which ones I have, and which ones are missing.
28
- Ask me before you install anything.
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
 
32
- **Upgrading from 0.7?** Nothing changes until you choose. On a 0.7 project,
33
- `npx joycraft@latest update .` shows the migration plan and stops. Read
34
- [Migrating from 0.7](docs/migrating-from-0.7.md), or paste the
35
- [upgrade prompt](docs/prompts.md#upgrade-from-07). To stay on 0.7:
36
- `npx joycraft@0.7.17 update`.
33
+ **Upgrading from 0.7?** Nothing changes until you choose. Paste the
34
+ [upgrade prompt](docs/prompts.md#upgrade-from-07): your agent shows you the migration
35
+ plan and waits for your yes. To stay on 0.7, paste the
36
+ [stay on 0.7 prompt](docs/prompts.md#stay-on-07). More:
37
+ [Migrating from 0.7](docs/migrating-from-0.7.md).
37
38
 
38
39
  ## How to use it
39
40
 
@@ -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 in a browser or simulator, if you
51
- installed those tools in step 4 of the install.
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
@@ -103,57 +104,54 @@ agent both views: the whole project and the detail of the current step.
103
104
  (`.joycraft-spec-queue.json`) is the status of record, not the text.
104
105
  - **`docs/archive/` is history.** Finished features move there.
105
106
 
106
- Joycraft does not ship a wiki. If you keep one, link it from the context map, and
107
- treat `docs/features/` and `docs/archive/` as non-authoritative in your doc audits.
108
-
109
- ### Settings: `joycraft.yaml`
110
-
111
- Joycraft works with no settings. To change its folders, run a command after a
112
- feature is archived, or tell cleanup which code each context page describes, add a
113
- `joycraft.yaml` at the project root (template: `.joycraft/templates/joycraft.yaml`):
114
-
115
- ```yaml
116
- paths:
117
- features: working/features # default docs/features
118
- archive: working/archive # default docs/archive
119
- hooks:
120
- afterArchive: node scripts/wiki-sync.mjs
121
- cleanup:
122
- impact:
123
- - source: src/auction/**
124
- docs: [docs/context/auction-rules.md]
107
+ **Your wiki.** Joycraft works with the wiki you already keep. Tell your agent where
108
+ it is: the agent links it from the context map and can update it each time a
109
+ feature is archived. In doc audits, `docs/features/` and `docs/archive/` are
110
+ working material and history, not current knowledge. A built-in wiki is under
111
+ consideration ([decision D6](docs/context/decision-log.md)).
112
+
113
+ ```text
114
+ We keep a wiki in <where>. Link it from the context map, and keep it up to date
115
+ each time a feature is archived.
125
116
  ```
126
117
 
127
- The file is yours: Joycraft reads it and never rewrites it. Run
128
- `node .joycraft/runtime/config.mjs` to see the settings in effect.
118
+ ### Settings
119
+
120
+ Joycraft works with no settings. To change one, say what you want:
121
+
122
+ ```text
123
+ Keep Joycraft's briefs and specs in working/features.
124
+ Whenever a feature is archived, run our wiki sync script.
125
+ The page docs/context/auction-rules.md describes src/auction. Flag it when that code changes.
126
+ ```
129
127
 
130
- The `afterArchive` command gets `JOYCRAFT_FEATURE`, `JOYCRAFT_ARCHIVE_PATH` and
131
- `JOYCRAFT_SOURCE_PATH` in its environment. Use it to update a wiki or run a doc
132
- audit. If the command fails, the archive stays done and the archive CLI exits 3.
128
+ The agent writes the change to `joycraft.yaml` at the project root, shows it to you
129
+ first, and checks it. Ask "What are my Joycraft settings?" to see what is in effect.
130
+ The file is yours: Joycraft changes it only when you ask. If a command run after an
131
+ archive fails, the archive still counts as done.
133
132
 
134
133
  ### Keeping the workspace clean
135
134
 
136
- At the end of a session the agent runs these checks for you:
137
-
138
- - `node .joycraft/runtime/status.mjs` finds specs whose text disagrees with the queue,
139
- and features that are finished but not archived.
140
- - `node .joycraft/runtime/worktrees.mjs prune` removes the agent's worker worktrees
141
- once their spec is done and merged. It keeps anything unfinished, unmerged or not
142
- made by Joycraft, and says why. `worktrees.mjs list` shows what is left and its size.
143
- - `node .joycraft/runtime/coordinator.mjs` keeps one coordinating session per queue,
144
- so a second session's instructions do not reach the first session's workers.
145
- - `node .joycraft/runtime/cleanup.mjs` reports stale or unreachable project
146
- knowledge: finished features not archived, context pages that link to working
147
- material, broken, missing or unmapped pages, an AGENTS.md over its word budget,
148
- and pages whose code changed.
135
+ At the end of a session the agent checks the workspace for you. You do not run
136
+ anything:
137
+
138
+ - **Status.** It finds specs whose text disagrees with the queue, and features that
139
+ are finished but not archived.
140
+ - **Worktrees.** It removes its worker worktrees once their spec is done and merged.
141
+ It keeps anything unfinished, unmerged or not made by Joycraft, and says why.
142
+ - **One coordinator.** One session coordinates each queue, so a second session's
143
+ instructions do not reach the first session's workers.
144
+ - **Stale knowledge.** It reports finished features not archived, context pages that
145
+ link to working material, broken, missing or unmapped pages, an AGENTS.md over its
146
+ word budget, and pages whose code changed.
149
147
  - The doc audit, based on [doc-cleanup](https://github.com/aka-luan/doc-cleanup),
150
148
  runs at every session end without being asked. It covers AGENTS.md, CLAUDE.md, the
151
149
  docs the session changed and the pages they link; after a feature is archived, the
152
150
  whole project. It checks each claim against the code, keeps your rules and traps,
153
151
  puts its findings on the session-end page, and changes nothing until you approve.
154
152
  Ask your agent to "clean up the docs" for a full audit at any time.
155
- - `node .joycraft/runtime/wiring.mjs` reports whether AGENTS.md has the Joycraft
156
- lines and a real context map, and whether CLAUDE.md imports it.
153
+ - **Wiring.** It checks that AGENTS.md has the Joycraft lines and a real context map,
154
+ and that CLAUDE.md imports it.
157
155
 
158
156
  Tests name the acceptance criterion they check, `[AC:<criterion-id>]`, so the
159
157
  reviewing agent can see which criteria have a test. A criterion with no test is a
@@ -163,6 +161,35 @@ If your docs are step-by-step procedures, the agent can offer
163
161
  [Doc Detective](https://docs.doc-detective.com) to run them as tests. It is opt-in:
164
162
  the agent says what it does not cover and installs nothing without your yes.
165
163
 
164
+ ## The review loop
165
+
166
+ The reviewing agent needs a tool that shows the real result: a browser for a web
167
+ app, a simulator for a mobile app, an HTTP check for an API. Joycraft decides what
168
+ counts as evidence; your project keeps its own tools.
169
+
170
+ - **Setup finds your tools.** For each package it looks for the tool you already
171
+ use (Playwright, Cypress, WebdriverIO, Maestro, Newman, an e2e script, a CI job
172
+ and others) and records one row per package in AGENTS.md, with what that tool can
173
+ show. Tools that belong to this machine, such as your agent's built-in browser, go
174
+ to `.joycraft/local/`. Packages that are not declared workspaces are found too, or
175
+ name them with `--packages`.
176
+ - **A gap gets one recommendation.** If a package has no tool, the agent recommends
177
+ one with its trade-offs and offers to look at others. It installs only on your yes,
178
+ and never with `sudo`, a licence or a sign-in. A project with no app records that
179
+ once and is not asked again.
180
+ - **Limits you agreed to are not failures.** A claim the recorded tool cannot show,
181
+ or a package you skipped, is reported as a limit. `UNVERIFIED` means a check that
182
+ should have run and did not.
183
+ - **Skipping review for one feature.** Say "skip review" in the feature interview.
184
+ The feature's `waiver.json` records your words, and no reviewer runs for it. A
185
+ waiver never hides a FAIL, and a new install keeps every check on.
186
+ - **A broken tool holds one spec.** If the browser or server breaks, the agent
187
+ tries one repair (restart, free the port, relaunch). Then it holds that spec as
188
+ `UNVERIFIED`, tells you, and keeps the rest of the queue going.
189
+
190
+ After an update, the agent checks the review loop again and asks only about what
191
+ changed.
192
+
166
193
  ## Answering questions: the decision page
167
194
 
168
195
  When the agent needs you to choose between options, it asks in your question
@@ -205,8 +232,8 @@ project:
205
232
 
206
233
  All of it lives in your repository. Joycraft collects no data and does not call an AI
207
234
  model itself. Its only network use is the version check below. Joycraft adds no
208
- agent hooks and changes no agent settings. The `afterArchive` command above runs only
209
- if you set it.
235
+ agent hooks and changes no agent settings. A command after an archive runs only if
236
+ you asked for one.
210
237
 
211
238
  ## Updates
212
239
 
@@ -215,7 +242,9 @@ day. The check sends no project data. If there is a new version, the agent tells
215
242
  whether it is a patch, a minor release or a migration, lists each release since
216
243
  yours, and asks: update now, not now, or turn off. Automatic updates apply only
217
244
  patches. On a yes, it does the update
218
- for you, checks the result, and tells you what is different. A new major version is
245
+ for you, checks the result, and tells you what is different. After a minor release
246
+ it names what you can now do, and asks how you want questions if you have not said
247
+ yet. A new major version is
219
248
  always your choice.
220
249
 
221
250
  This is an instruction the agent follows, so it can forget. To check yourself, ask:
@@ -238,20 +267,22 @@ Check for a Joycraft update.
238
267
  "Tested" means: we installed Joycraft in a test project, one agent built a spec, and
239
268
  a second, separate agent checked it and passed it.
240
269
 
241
- ## Commands
270
+ ## Everything else: ask your agent
242
271
 
243
- Your agent runs these for you. They are here if you want them:
272
+ You never need to run a Joycraft command yourself. Each of these is a short prompt
273
+ in [Prompts](docs/prompts.md):
244
274
 
245
- ```bash
246
- npx joycraft@latest init . --harness claude,codex --yes # install
247
- npx joycraft@latest update . --yes # update (backs up files you edited first)
248
- npx joycraft@latest doctor . # check the install
249
- npx joycraft@latest update . --migrate --archive-custom --yes # move a 0.7 project to 1.0
250
- npx joycraft@latest rollback --yes # undo the move to 1.0
251
- ```
275
+ | You want to | Say |
276
+ |---|---|
277
+ | Update Joycraft | "Check for a Joycraft update." |
278
+ | Check the install | "Check my Joycraft install." |
279
+ | Change a setting | "Keep Joycraft's specs in working/features." |
280
+ | Connect your wiki | "Link our wiki and keep it up to date." |
281
+ | Clean up | "Clean up the docs and the workspace." |
282
+ | Undo the 1.0 upgrade | "Undo this project's upgrade to Joycraft 1.0." |
283
+ | Remove Joycraft | "Remove Joycraft from this project." |
252
284
 
253
- Add `--plan --json` to see the changes without making them. Without `--yes`, and
254
- outside a terminal, a command shows its plan and stops. It never waits for input.
285
+ The CLI commands behind them are in the [install guide](docs/install.md#cli-reference).
255
286
 
256
287
  More: [Install guide](docs/install.md) · [Migrating from 0.7](docs/migrating-from-0.7.md) ·
257
288
  [Prompts](docs/prompts.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) ·
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "releaseVersion": "1.2.1",
3
+ "releaseVersion": "1.3.0",
4
4
  "manifestSchemas": [
5
5
  1
6
6
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "joycraft",
3
- "version": "1.2.1",
3
+ "version": "1.3.0",
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.1",
17
- "summary": "Joycraft asks questions your way: one at a time or as a page, in chat or on the decision page, set at setup and changeable per feature; each question gives context, options with an example and a trade-off, and a recommendation.",
16
+ "release": "1.3.0",
17
+ "summary": "Ask your agent instead of running commands: it changes Joycraft settings, connects your wiki and removes Joycraft on request, and the docs give a prompt for every step.",
18
18
  "autoSafeEligible": false
19
19
  },
20
20
  "scripts": {
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: joycraft-entry
3
- description: Start any Joycraft work. After Joycraft is installed, or when asked to "set up Joycraft" or "check the context map", read the project, interview the user and build the context map in AGENTS.md; then turn a repair, feature, or mixed request into a context-backed brief and the next useful action.
3
+ description: Start any Joycraft work. After Joycraft is installed, when asked to "set up Joycraft", "check the context map", change Joycraft settings or remove Joycraft, read the project, interview the user and build the context map in AGENTS.md; then turn a repair, feature, or mixed request into a context-backed brief and the next useful action.
4
4
  compatibility: Setup and routing helpers require Node.js 22+ and the installed .joycraft runtime only when used; ordinary brief and context navigation has no project-stack prerequisite.
5
5
  ---
6
6
 
@@ -103,6 +103,12 @@ with no options.
103
103
  `node .joycraft/runtime/config.mjs` and use its `paths` wherever Joycraft guidance
104
104
  says `docs/features`, `docs/archive` or `docs/context`.
105
105
 
106
+ **Change settings when asked.** When the user asks to move Joycraft's folders, run
107
+ something after a feature is archived (such as a wiki sync), map code to a context
108
+ page, connect their wiki, see their settings or remove Joycraft, follow
109
+ [settings](../../../.joycraft/references/settings.md). The user never edits
110
+ `joycraft.yaml` or runs a Joycraft command by hand.
111
+
106
112
  **Show documents as pages.** A brief, plan, spec set or review that the user must
107
113
  read or approve is also rendered, never left as Markdown in chat: the decision
108
114
  artifact for a brief, an HTML page for anything else. Show it as
@@ -0,0 +1,57 @@
1
+ # Settings by request
2
+
3
+ The user never edits Joycraft settings or runs Joycraft commands by hand. They
4
+ say what they want; you make the change, show it, and check it.
5
+
6
+ ## `joycraft.yaml`
7
+
8
+ The file is the user's. Joycraft only reads it. Change it only when the user asks,
9
+ and keep their comments and order. Map plain requests to settings:
10
+
11
+ | The user says | Setting |
12
+ |---|---|
13
+ | "Keep briefs and specs in `working/features`" | `paths.features` |
14
+ | "Put finished features in `working/archive`" | `paths.archive` |
15
+ | "Our project knowledge lives in `knowledge/`" | `paths.context` |
16
+ | "After each feature is archived, sync our wiki" / "run `<command>`" | `hooks.afterArchive` |
17
+ | "This page describes `src/auction`" / "flag the auction page when that code changes" | `cleanup.impact` |
18
+ | "Let AGENTS.md be up to 1500 words" | `cleanup.entryWords` |
19
+
20
+ 1. Read `joycraft.yaml`. If it does not exist, start from
21
+ `.joycraft/templates/joycraft.yaml` and keep only the settings the user changes.
22
+ 2. For `hooks.afterArchive`, find the command in the project first: a wiki or doc
23
+ script, a `package.json` script, or the tool the user named. If none exists, ask
24
+ what should run; do not write a script unless the user asks for one. The command
25
+ gets `JOYCRAFT_FEATURE`, `JOYCRAFT_ARCHIVE_PATH` and `JOYCRAFT_SOURCE_PATH`.
26
+ 3. For `cleanup.impact`, check that each `docs` page exists and each `source` glob
27
+ matches files.
28
+ 4. Moving `paths.*` does not move existing files. Say which folders hold files now,
29
+ and offer to move them in the same change.
30
+ 5. Show the change as a short diff and write it on the user's yes.
31
+ 6. Run `node .joycraft/runtime/config.mjs`. If it stops, fix the file and run it
32
+ again. Tell the user the settings now in effect, in one or two lines.
33
+
34
+ To answer "what are my Joycraft settings?", run `config.mjs` and say what differs
35
+ from the defaults.
36
+
37
+ ## A wiki the user keeps
38
+
39
+ Joycraft has no wiki of its own, and it works with one. When the user mentions their
40
+ wiki, offer two things: a context-map row that says when to read it, and an
41
+ `afterArchive` command that updates it when a feature is archived (above). In a doc
42
+ audit, the wiki is a context home; `paths.features` and `paths.archive` are
43
+ working material and history, not current knowledge.
44
+
45
+ ## Remove Joycraft
46
+
47
+ On "uninstall Joycraft" or "remove Joycraft":
48
+
49
+ 1. Read `.joycraft/installation.json`. Its `files` list holds each installed path
50
+ and the `sha256` it had at install.
51
+ 2. Show the user what goes: the listed files, with each file whose bytes changed
52
+ since install marked as edited, and `.joycraft/` itself. Say what stays:
53
+ `AGENTS.md`, `CLAUDE.md`, `docs/` and `joycraft.yaml` are theirs.
54
+ 3. Offer to remove the Joycraft lines from `AGENTS.md` and `CLAUDE.md` (the context
55
+ map rows that point into `.joycraft/`, and the Joycraft rules). Show that diff
56
+ separately.
57
+ 4. On the user's yes, delete the files, then `.joycraft/`. Do not commit.
@@ -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
package/payload/PIN CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "source": "joycraft-prototype",
4
- "tag": "field-16",
5
- "commit": "91bd7db1f2ac5ddaa587f81bf3c5db636d60e584",
4
+ "tag": "field-18",
5
+ "commit": "880583a33d5c4562b4da02c5897f9ff81cb1edb6",
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": "6b2ac0e52f0751c7b7587b495349c29f707c61421312dc9ad8d3821aec936855",
10
+ ".agents/skills/joycraft-entry/SKILL.md": "390b0a0b3d4fcbc8c962259abfc490764871266028e49be3479224c8768b9904",
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",
@@ -34,9 +34,10 @@
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/settings.md": "7c3e383634ff68522c45460056fd5ef120a5565a62c01f14aac7b060a41804cf",
37
38
  ".joycraft/references/setup.md": "a9bd9072adc9f021b46287ff0422281ddb2285ac34738b6e29ad11cc60e8a6e5",
38
39
  ".joycraft/references/testing.md": "ddbc0e69212f4bf29f32f65e139c016b12eb40c29f621a99510129bedf292950",
39
- ".joycraft/references/update.md": "b6ca2f6f4073ed9a566ae467cbe4c60bf79baead845cc45138eec4c4ae28891e",
40
+ ".joycraft/references/update.md": "36af36ab3d47b5ea46a8f71090333771e5e1deaa6ca19739a75c9fd4aea14eba",
40
41
  ".joycraft/references/workflow.md": "5b330debc6759b8f7975b159632f51074802067291fe4f4bebfb344f5b60cc52",
41
42
  ".joycraft/references/worktrees.md": "fb18af0cd76d4e3c5d5b892a7ae10946f21f189e642243235c188b571635f735",
42
43
  ".joycraft/runtime/archive.mjs": "82b4d9567942a4abd21594ea299c4d323a8306ec7545cb0030431c87bd37f8b2",