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.
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
[
|
|
37
|
-
|
|
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
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
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
|
-
|
|
129
|
-
`node .joycraft/runtime/config.mjs` to see the settings in effect.
|
|
118
|
+
### Settings
|
|
130
119
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
-
|
|
145
|
-
|
|
146
|
-
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|
-
-
|
|
157
|
-
|
|
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.
|
|
239
|
-
|
|
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
|
-
##
|
|
270
|
+
## Everything else: ask your agent
|
|
274
271
|
|
|
275
|
-
|
|
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
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
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
|
-
|
|
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) ·
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "joycraft",
|
|
3
|
-
"version": "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.
|
|
17
|
-
"summary": "
|
|
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,
|
|
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-
|
|
5
|
-
"commit": "
|
|
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": "
|
|
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",
|