joycraft 1.2.2 → 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
@@ -30,11 +30,11 @@ Install Joycraft in this project.
30
30
  Do not commit, publish, or ask me for API keys.
31
31
  ```
32
32
 
33
- **Upgrading from 0.7?** Nothing changes until you choose. On a 0.7 project,
34
- `npx joycraft@latest update .` shows the migration plan and stops. Read
35
- [Migrating from 0.7](docs/migrating-from-0.7.md), or paste the
36
- [upgrade prompt](docs/prompts.md#upgrade-from-07). To stay on 0.7:
37
- `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).
38
38
 
39
39
  ## How to use it
40
40
 
@@ -104,57 +104,54 @@ agent both views: the whole project and the detail of the current step.
104
104
  (`.joycraft-spec-queue.json`) is the status of record, not the text.
105
105
  - **`docs/archive/` is history.** Finished features move there.
106
106
 
107
- Joycraft does not ship a wiki. If you keep one, link it from the context map, and
108
- treat `docs/features/` and `docs/archive/` as non-authoritative in your doc audits.
109
-
110
- ### Settings: `joycraft.yaml`
111
-
112
- Joycraft works with no settings. To change its folders, run a command after a
113
- feature is archived, or tell cleanup which code each context page describes, add a
114
- `joycraft.yaml` at the project root (template: `.joycraft/templates/joycraft.yaml`):
115
-
116
- ```yaml
117
- paths:
118
- features: working/features # default docs/features
119
- archive: working/archive # default docs/archive
120
- hooks:
121
- afterArchive: node scripts/wiki-sync.mjs
122
- cleanup:
123
- impact:
124
- - source: src/auction/**
125
- 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.
126
116
  ```
127
117
 
128
- The file is yours: Joycraft reads it and never rewrites it. Run
129
- `node .joycraft/runtime/config.mjs` to see the settings in effect.
118
+ ### Settings
130
119
 
131
- The `afterArchive` command gets `JOYCRAFT_FEATURE`, `JOYCRAFT_ARCHIVE_PATH` and
132
- `JOYCRAFT_SOURCE_PATH` in its environment. Use it to update a wiki or run a doc
133
- audit. If the command fails, the archive stays done and the archive CLI exits 3.
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
+ ```
127
+
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.
134
132
 
135
133
  ### Keeping the workspace clean
136
134
 
137
- At the end of a session the agent runs these checks for you:
138
-
139
- - `node .joycraft/runtime/status.mjs` finds specs whose text disagrees with the queue,
140
- and features that are finished but not archived.
141
- - `node .joycraft/runtime/worktrees.mjs prune` removes the agent's worker worktrees
142
- once their spec is done and merged. It keeps anything unfinished, unmerged or not
143
- made by Joycraft, and says why. `worktrees.mjs list` shows what is left and its size.
144
- - `node .joycraft/runtime/coordinator.mjs` keeps one coordinating session per queue,
145
- so a second session's instructions do not reach the first session's workers.
146
- - `node .joycraft/runtime/cleanup.mjs` reports stale or unreachable project
147
- knowledge: finished features not archived, context pages that link to working
148
- material, broken, missing or unmapped pages, an AGENTS.md over its word budget,
149
- 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.
150
147
  - The doc audit, based on [doc-cleanup](https://github.com/aka-luan/doc-cleanup),
151
148
  runs at every session end without being asked. It covers AGENTS.md, CLAUDE.md, the
152
149
  docs the session changed and the pages they link; after a feature is archived, the
153
150
  whole project. It checks each claim against the code, keeps your rules and traps,
154
151
  puts its findings on the session-end page, and changes nothing until you approve.
155
152
  Ask your agent to "clean up the docs" for a full audit at any time.
156
- - `node .joycraft/runtime/wiring.mjs` reports whether AGENTS.md has the Joycraft
157
- 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.
158
155
 
159
156
  Tests name the acceptance criterion they check, `[AC:<criterion-id>]`, so the
160
157
  reviewing agent can see which criteria have a test. A criterion with no test is a
@@ -235,8 +232,8 @@ project:
235
232
 
236
233
  All of it lives in your repository. Joycraft collects no data and does not call an AI
237
234
  model itself. Its only network use is the version check below. Joycraft adds no
238
- agent hooks and changes no agent settings. The `afterArchive` command above runs only
239
- 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.
240
237
 
241
238
  ## Updates
242
239
 
@@ -270,20 +267,22 @@ Check for a Joycraft update.
270
267
  "Tested" means: we installed Joycraft in a test project, one agent built a spec, and
271
268
  a second, separate agent checked it and passed it.
272
269
 
273
- ## Commands
270
+ ## Everything else: ask your agent
274
271
 
275
- 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):
276
274
 
277
- ```bash
278
- npx joycraft@latest init . --harness claude,codex --yes # install
279
- npx joycraft@latest update . --yes # update (backs up files you edited first)
280
- npx joycraft@latest doctor . # check the install
281
- npx joycraft@latest update . --migrate --archive-custom --yes # move a 0.7 project to 1.0
282
- npx joycraft@latest rollback --yes # undo the move to 1.0
283
- ```
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." |
284
284
 
285
- Add `--plan --json` to see the changes without making them. Without `--yes`, and
286
- 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).
287
286
 
288
287
  More: [Install guide](docs/install.md) · [Migrating from 0.7](docs/migrating-from-0.7.md) ·
289
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.2",
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.2",
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.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.",
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.
package/payload/PIN CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
3
  "source": "joycraft-prototype",
4
- "tag": "field-17",
5
- "commit": "0e88e6da3adc605a306db1ec058a4690b2eb5cb2",
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,6 +34,7 @@
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
40
  ".joycraft/references/update.md": "36af36ab3d47b5ea46a8f71090333771e5e1deaa6ca19739a75c9fd4aea14eba",