joycraft 1.1.1 → 1.2.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 +57 -16
- package/dist/cli.js +50 -9
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +3 -3
- package/payload/.agents/skills/joycraft-cleanup/SKILL.md +81 -34
- package/payload/.agents/skills/joycraft-context/SKILL.md +30 -4
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +5 -1
- package/payload/.agents/skills/joycraft-entry/SKILL.md +35 -8
- package/payload/.agents/skills/joycraft-implement/SKILL.md +16 -0
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +9 -4
- package/payload/.agents/skills/joycraft-testing/SKILL.md +7 -5
- package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +4 -3
- package/payload/.agents/skills/joycraft-verify/SKILL.md +1 -1
- package/payload/.claude/agents/joycraft-reviewer.md +7 -2
- package/payload/.joycraft/assets/artifacts/kit.css +8 -0
- package/payload/.joycraft/assets/artifacts/kit.js +163 -21
- package/payload/.joycraft/assets/artifacts/transports.js +14 -3
- package/payload/.joycraft/contracts/types.d.ts +22 -0
- package/payload/.joycraft/references/archive.md +4 -2
- package/payload/.joycraft/references/artifacts.md +21 -2
- package/payload/.joycraft/references/cleanup.md +109 -3
- package/payload/.joycraft/references/completion.md +55 -2
- package/payload/.joycraft/references/context.md +64 -2
- package/payload/.joycraft/references/dispatch.md +12 -0
- package/payload/.joycraft/references/doc-cleanup-LICENSE.md +23 -0
- package/payload/.joycraft/references/knowledge.md +58 -0
- package/payload/.joycraft/references/setup.md +165 -151
- package/payload/.joycraft/references/testing.md +14 -7
- package/payload/.joycraft/references/update.md +13 -3
- package/payload/.joycraft/references/workflow.md +3 -2
- package/payload/.joycraft/runtime/archive.mjs +19 -4
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +16 -5
- package/payload/.joycraft/runtime/artifacts/server.mjs +14 -1
- package/payload/.joycraft/runtime/cleanup.mjs +95 -8
- package/payload/.joycraft/runtime/completion.mjs +210 -10
- package/payload/.joycraft/runtime/config.mjs +5 -3
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +16 -3
- package/payload/.joycraft/runtime/evidence.mjs +4 -0
- package/payload/.joycraft/runtime/identity.mjs +11 -0
- package/payload/.joycraft/runtime/review-tools.json +110 -30
- package/payload/.joycraft/runtime/review-tools.mjs +702 -131
- package/payload/.joycraft/runtime/status.mjs +1 -1
- package/payload/.joycraft/runtime/update-check.mjs +38 -8
- package/payload/.joycraft/runtime/wiring.mjs +156 -0
- package/payload/.joycraft/runtime/worktrees.mjs +1 -1
- package/payload/.joycraft/templates/joycraft.yaml +2 -0
- package/payload/.joycraft/templates/project-context.md +6 -1
- package/payload/PIN +45 -42
|
@@ -1,4 +1,11 @@
|
|
|
1
|
-
# Project context
|
|
1
|
+
# Project context
|
|
2
|
+
|
|
3
|
+
## Contents
|
|
4
|
+
|
|
5
|
+
- [Finding context](#finding-context)
|
|
6
|
+
- [Changing context](#changing-context)
|
|
7
|
+
|
|
8
|
+
## Finding context
|
|
2
9
|
|
|
3
10
|
From the consumer Git project root:
|
|
4
11
|
|
|
@@ -81,5 +88,60 @@ advise reading order and never approve intent, authorize work or certify evidenc
|
|
|
81
88
|
|
|
82
89
|
Treat only the context homes as current authority. `docs/features/` is working
|
|
83
90
|
material that can be stale until its feature is archived, and `docs/archive/` is
|
|
84
|
-
history; see
|
|
91
|
+
history; see [knowledge guidance](knowledge.md) for which home holds what. Joycraft ships no wiki. Skills
|
|
85
92
|
do not need to be named by the user: pick the step from the request.
|
|
93
|
+
|
|
94
|
+
## Changing context
|
|
95
|
+
|
|
96
|
+
The same skill writes project knowledge when the user asks: "add this to the
|
|
97
|
+
project context", "remember that ...", "forget that rule", or a meeting note,
|
|
98
|
+
screenshot or pasted text to capture. `knowledge.md` owns the rule (one home per
|
|
99
|
+
fact, current state only, reasons in the decision log, history in the archive);
|
|
100
|
+
these steps apply it to a request.
|
|
101
|
+
|
|
102
|
+
**Read the map and homes.** Start from the context map in `AGENTS.md` (or the
|
|
103
|
+
project's own map). Search the live homes, not `docs/features/` or
|
|
104
|
+
`docs/archive/`, for the subject of each fact: a different wording of the same
|
|
105
|
+
rule counts as the same fact.
|
|
106
|
+
|
|
107
|
+
**Turn input into facts.** A meeting note, screenshot or pasted thread usually
|
|
108
|
+
holds several facts and some noise. Keep each statement that was settled or
|
|
109
|
+
observed: a decision and its reason, a trap and how to avoid it, a reference, a
|
|
110
|
+
production fact. Leave out action items, open questions, ideas nobody decided
|
|
111
|
+
on, attendance and opinions; name them in the proposal as left out, so the user
|
|
112
|
+
can correct the cut. For a screenshot, read the facts from what it shows and
|
|
113
|
+
say which ones you could not read. Do not copy the raw note into the project,
|
|
114
|
+
and do not keep a link to it as a source: the homes state the facts themselves.
|
|
115
|
+
|
|
116
|
+
**Add.** Route each fact by the table in `knowledge.md` to the home the map
|
|
117
|
+
already names for that kind. When the map has no home for it, create a focused
|
|
118
|
+
page under the context folder with the fact and add a map row whose "read when"
|
|
119
|
+
names the work that needs it, not the page's title. Write a decision's current
|
|
120
|
+
choice in the home that owns its area and its reason and rejected options as a
|
|
121
|
+
decision-log entry. A widened home keeps a "read when" that covers its new
|
|
122
|
+
content.
|
|
123
|
+
|
|
124
|
+
**Change.** Rewrite the existing statement in place. Add a decision-log entry
|
|
125
|
+
that names the old choice, the new one and why. Leave no dated addendum,
|
|
126
|
+
"previously" note or struck-through text in the live home.
|
|
127
|
+
|
|
128
|
+
**Remove.** Delete the statement from every live home that holds it, including
|
|
129
|
+
copies in `AGENTS.md`. Add a decision-log entry headed with what was removed,
|
|
130
|
+
with the user's reason; when the user gives none, ask, and in a pre-approved
|
|
131
|
+
non-interactive run write that it was removed at the user's request. An older
|
|
132
|
+
decision-log entry that chose the rule stays as history; the new entry records
|
|
133
|
+
that it no longer applies. When the page that held it has no facts left, delete
|
|
134
|
+
the page, its map row and every link or backticked mention of it. Do not leave
|
|
135
|
+
an empty page, a row to a missing file or a "removed" note in a live home.
|
|
136
|
+
|
|
137
|
+
**Approve, then write.** Before writing, show each affected file and the change
|
|
138
|
+
as a unified diff (or the new file in full), the home chosen for each fact, and
|
|
139
|
+
anything left out. Write only after the user says yes, and only what they
|
|
140
|
+
approved. A prompt that already approves the change, as in a scripted run, is
|
|
141
|
+
that yes; still show what you wrote afterwards.
|
|
142
|
+
|
|
143
|
+
**Check the map.** Run `node .joycraft/runtime/cleanup.mjs`. The change must not
|
|
144
|
+
add a `missing-path`, `unmapped`, `orphan`, `broken-link` or `working-link`
|
|
145
|
+
finding; fix any it did. Report findings that were already there without fixing
|
|
146
|
+
them unless the user asks. Every page you created or edited must be reachable
|
|
147
|
+
from the map.
|
|
@@ -10,6 +10,9 @@ For a mutable worker or stateful runtime check, first apply the conditional
|
|
|
10
10
|
worktree or a resource lease. A `read-only` workspace keeps declared source
|
|
11
11
|
inputs frozen; it may still write declared review reports and receipts outside
|
|
12
12
|
those inputs. Cache-mutating runtime work needs separate mutable state.
|
|
13
|
+
Reviewer preflight refuses a queue whose feature `waiver.json` covers
|
|
14
|
+
`no-review` ([completion guidance](completion.md#feature-waiver)); complete
|
|
15
|
+
those specs with `accept-waiver` instead.
|
|
13
16
|
|
|
14
17
|
## Contents
|
|
15
18
|
|
|
@@ -93,6 +96,11 @@ more, alone, with a fresh packet path. If it fails again, stop that spec's
|
|
|
93
96
|
review and tell the user its printed reason; never continue as if the review
|
|
94
97
|
started. Do not retry a `Task startup stopped:` refusal unchanged; fix its cause.
|
|
95
98
|
|
|
99
|
+
A worker that holds a spec for a tool break reports the spec, the tool, the
|
|
100
|
+
cause and the repair it tried. The coordinator tells the user at the first hold,
|
|
101
|
+
in the conversation, while other workers keep running; it does not wait for the
|
|
102
|
+
session end. The session-end summary lists every held spec again.
|
|
103
|
+
|
|
96
104
|
The return is `ready: true` for an available valid startup path, including a
|
|
97
105
|
hooks-disabled/manual path. It is not a cryptographic attestation. Missing human
|
|
98
106
|
prompt history for an enforced startup is explicit
|
|
@@ -158,6 +166,10 @@ decisions. Without a selector, the packet conservatively carries every current
|
|
|
158
166
|
answered decision from that brief. The packet retains its whole-brief reference
|
|
159
167
|
so workers can read each decision in context. Its inputs include any current
|
|
160
168
|
coupled counterpart required to review the requested behavior.
|
|
169
|
+
When `AGENTS.md` has a `## Review loop` section or this machine has
|
|
170
|
+
`.joycraft/local/review-loop.json`, the packet carries `reviewLoop`:
|
|
171
|
+
`{ path, section, local? }`, the shared section plus, when present,
|
|
172
|
+
`local: { path, record }` with this machine's host tools.
|
|
161
173
|
|
|
162
174
|
## Bind the hook source view
|
|
163
175
|
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
License for the doc-cleanup method adapted in joycraft-cleanup, from https://github.com/aka-luan/doc-cleanup (commit 69dcb95):
|
|
2
|
+
|
|
3
|
+
MIT License
|
|
4
|
+
|
|
5
|
+
Copyright (c) 2026 aka-luan
|
|
6
|
+
|
|
7
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
8
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
9
|
+
in the Software without restriction, including without limitation the rights
|
|
10
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
11
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
12
|
+
furnished to do so, subject to the following conditions:
|
|
13
|
+
|
|
14
|
+
The above copyright notice and this permission notice shall be included in all
|
|
15
|
+
copies or substantial portions of the Software.
|
|
16
|
+
|
|
17
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
18
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
19
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
20
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
21
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
22
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
23
|
+
SOFTWARE.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Project knowledge stays current
|
|
2
|
+
|
|
3
|
+
The context map in `AGENTS.md` (or the project's own map) is the index of project
|
|
4
|
+
memory. Each row points to one home for one kind of knowledge and says when to
|
|
5
|
+
read it. An agent that starts fresh, after a compaction or in a new session,
|
|
6
|
+
reads the homes as the current state of the project. It must never have to replay
|
|
7
|
+
a chain of past decisions to learn how things are today.
|
|
8
|
+
|
|
9
|
+
## The rule
|
|
10
|
+
|
|
11
|
+
- **One home per fact.** Other pages link to it; they do not copy it.
|
|
12
|
+
- **Homes state what is true now.** When a fact changes, rewrite the statement in
|
|
13
|
+
place. Do not add a dated addendum, a "superseded by" or "previously" note,
|
|
14
|
+
struck-through text, or a footnote that corrects a stale table.
|
|
15
|
+
- **Why goes to the decision log.** The reason and the rejected options go in an
|
|
16
|
+
entry in the decision log (default `docs/context/decision-log.md`). A changed
|
|
17
|
+
decision gets a new entry that names the choice it replaces. The live home
|
|
18
|
+
carries only the current statement.
|
|
19
|
+
- **History stays out of live homes.** The old value of a changed fact lives in
|
|
20
|
+
its decision-log entry and in Git. Finished features go to the archive at
|
|
21
|
+
session end (`archive.md`); they stay there for regression checks and are never
|
|
22
|
+
read as current truth.
|
|
23
|
+
- **Check before you restore.** Do not copy a statement from the archive or from
|
|
24
|
+
an old decision-log entry back into a live home until you have checked it
|
|
25
|
+
against the code.
|
|
26
|
+
- Record what the work established or observed. Keep proposals and guesses out.
|
|
27
|
+
|
|
28
|
+
## Routing a fact at session end
|
|
29
|
+
|
|
30
|
+
A reusable fact is one a later session needs and cannot cheaply get from the
|
|
31
|
+
code. Use the home the map already names for that kind. Use the default only when
|
|
32
|
+
the map has no home for it.
|
|
33
|
+
|
|
34
|
+
| Fact | Home |
|
|
35
|
+
|---|---|
|
|
36
|
+
| What the project is (purpose, users, owners, constraints), and the areas setup has not mapped yet | `docs/context/project.md` (from `.joycraft/templates/project-context.md`) |
|
|
37
|
+
| Navigation across code boundaries (where a flow lives) | A focused reference page linked by the map, e.g. `docs/context/architecture.md` |
|
|
38
|
+
| Decision | Current choice in the home that owns that area; reason and rejected options in the decision log |
|
|
39
|
+
| Trap (something that misleads or breaks, and how to avoid it) | The project's troubleshooting or gotchas page, default `docs/context/traps.md` |
|
|
40
|
+
| Reference (where something lives, how to run or look it up) | A focused reference page linked by the map |
|
|
41
|
+
| Production fact (deploy, environments, data, external services) | The production page, default `docs/context/production.md` |
|
|
42
|
+
| Feature intent and product choices for live work | The feature brief; do not copy them into a context home |
|
|
43
|
+
|
|
44
|
+
For each fact:
|
|
45
|
+
|
|
46
|
+
1. Find its home through the map. If the home already states it, rewrite that
|
|
47
|
+
statement in place.
|
|
48
|
+
2. If no home holds that kind of fact, create the page with the fact and add a
|
|
49
|
+
map row with a "read when". Do not create empty pages.
|
|
50
|
+
3. If a change widens or narrows what a home covers, edit its row so the "read
|
|
51
|
+
when" stays true.
|
|
52
|
+
|
|
53
|
+
Then check that every page you created or edited is reachable from the map, that
|
|
54
|
+
no link points into `docs/features/` or `docs/archive/`, and that no live home
|
|
55
|
+
holds a dated addendum or "superseded" note (`node .joycraft/runtime/cleanup.mjs`
|
|
56
|
+
reports unmapped pages and broken or working-material links).
|
|
57
|
+
|
|
58
|
+
A session with nothing reusable changes no context file.
|
|
@@ -1,21 +1,17 @@
|
|
|
1
1
|
# First-use project setup
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
It reads only plain target-local repository facts; it never reads `.env.local`,
|
|
12
|
-
Keychain, sibling projects, or private directories. Its `ready` and `partial`
|
|
13
|
-
status describes context discovery, never hook trust or a successful command.
|
|
3
|
+
Run this after every install from the prompt, when the user asks ("set up
|
|
4
|
+
Joycraft", "check the context map"), and whenever
|
|
5
|
+
`node .joycraft/runtime/wiring.mjs --root .` exits 2. The CLI knows nothing
|
|
6
|
+
about the project, so it writes nothing to `AGENTS.md` or `CLAUDE.md`; you build
|
|
7
|
+
the context map from the repository and a short interview with the user. Many
|
|
8
|
+
installs land in existing, sometimes large, projects, so the interview is part
|
|
9
|
+
of every setup, not only a new project's. Work inside the current project. A
|
|
10
|
+
read-only request gets the findings reported, not written.
|
|
14
11
|
|
|
15
12
|
## Contents
|
|
16
13
|
|
|
17
|
-
- [
|
|
18
|
-
- [Small shared entry point](#small-shared-entry-point)
|
|
14
|
+
- [Set up the context map](#set-up-the-context-map)
|
|
19
15
|
- [Kickoff for a new project](#kickoff-for-a-new-project)
|
|
20
16
|
- [Review loop tools](#review-loop-tools)
|
|
21
17
|
- [Project-owned worktrees](#project-owned-worktrees)
|
|
@@ -23,87 +19,99 @@ status describes context discovery, never hook trust or a successful command.
|
|
|
23
19
|
- [Finish setup and continue](#finish-setup-and-continue)
|
|
24
20
|
- [Upgrade and agent onboarding](#upgrade-and-agent-onboarding)
|
|
25
21
|
|
|
26
|
-
##
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
22
|
+
## Set up the context map
|
|
23
|
+
|
|
24
|
+
The context map in `AGENTS.md` is the project's memory index. Each row points to
|
|
25
|
+
one home for one kind of knowledge and says when to read it, so an agent loads
|
|
26
|
+
only what its work needs; the map then grows with every decision, trap and
|
|
27
|
+
feature ([knowledge.md](knowledge.md)). A project without a real map gets
|
|
28
|
+
nothing from Joycraft, so build it from the project, never from a template.
|
|
29
|
+
|
|
30
|
+
**Nothing new, nothing done.** When `wiring.mjs` exits 0, every doc worth
|
|
31
|
+
reading already has a row, and nothing the user told you or the audit found is
|
|
32
|
+
unrecorded, say in one line that Joycraft is already set up. Write nothing,
|
|
33
|
+
render nothing, ask nothing: a repeated setup must leave the project unchanged.
|
|
34
|
+
|
|
35
|
+
1. **Read and audit.** Read `AGENTS.md`, `CLAUDE.md`, the README and every doc
|
|
36
|
+
they point to, then the other Markdown docs (skip dependencies, generated
|
|
37
|
+
files, `.joycraft/` and installed skills). Run `joycraft-cleanup` steps 1–2
|
|
38
|
+
(inventory and diagnose) on what you read: it gives each doc a
|
|
39
|
+
[role](cleanup.md#doc-roles) and hands its findings back to you, with no
|
|
40
|
+
report page and no stop of its own. Check claims in entry and required docs
|
|
41
|
+
against the code; in reference docs, check only the claims the interview or
|
|
42
|
+
an audit finding touches. Inspect manifests, scripts and CI only to
|
|
43
|
+
establish the stack and real commands; a declared command is unrun until
|
|
44
|
+
executed. In a large repo, read the entry docs and their pointers first,
|
|
45
|
+
then one area at a time; propose each area you did not read as an item of
|
|
46
|
+
a `## Not yet mapped` list in `docs/context/project.md` (current areas
|
|
47
|
+
only, no history), so a later session maps it when work reaches it. Do
|
|
48
|
+
not scan neighboring projects or credential files, and do not run
|
|
49
|
+
installs, deployments or destructive commands.
|
|
50
|
+
2. **Interview.** Ask only what the repository cannot tell you: purpose, users,
|
|
51
|
+
who owns what, constraints, decisions already made and why, which docs are
|
|
52
|
+
trusted, and each audit finding that needs a human. Ask in short rounds of
|
|
53
|
+
at most three questions, each one that changes what you will write. Write
|
|
54
|
+
each choice with options as a decision in a setup brief at
|
|
55
|
+
`.joycraft/local/setup/brief.md` (format of `.joycraft/templates/brief.md`,
|
|
56
|
+
`feature: setup`; give `.joycraft/local/` a `.gitignore` of `*` when it has
|
|
57
|
+
none, so nothing there becomes a project change) and serve the decision
|
|
58
|
+
artifact on it ([artifacts.md](artifacts.md)); plain chat is only for one
|
|
59
|
+
quick yes/no or an open question with no options. The brief is scratch:
|
|
60
|
+
each answer then goes to its home in step 3. Stop when the user says enough. Never ask again
|
|
61
|
+
what the user answered or a home already states. Keep the user's words apart
|
|
62
|
+
from your observations and assumptions. On a bare project, offer the
|
|
63
|
+
[kickoff](#kickoff-for-a-new-project) instead.
|
|
64
|
+
3. **Propose.** Draft every change:
|
|
65
|
+
- **Joycraft lines** in `AGENTS.md`, each only when missing:
|
|
66
|
+
“First action in each session: run
|
|
67
|
+
`node .joycraft/runtime/update-check.mjs check`. If it prints JSON, follow
|
|
68
|
+
`.joycraft/references/update.md`.” and “Show every document a person must
|
|
69
|
+
read, review or answer (a brief, plan, spec set, review or set of
|
|
70
|
+
questions) as a rendered page, never only as Markdown in chat: use the
|
|
71
|
+
decision artifact (`node .joycraft/runtime/artifacts/cli.mjs`, see
|
|
72
|
+
`.joycraft/references/artifacts.md`) for a brief or questions, or an HTML
|
|
73
|
+
page for any other document. Show it where the person works (see
|
|
74
|
+
`.joycraft/references/artifacts.md#showing-a-page`) and say where it is.”
|
|
75
|
+
- **The map**: one `## Context Map` table (`| Document | Read when |`). One
|
|
76
|
+
row per real home: each required or reference doc, and each home you
|
|
77
|
+
create. A read-when names the work that needs the doc ("Changing how counts
|
|
78
|
+
are stored"), not its topic. Add a row for
|
|
79
|
+
`.joycraft/references/artifacts.md`, read when "showing a document or
|
|
80
|
+
questions to a person". Historical docs get no row. In an existing map,
|
|
81
|
+
append rows below the user's rows; never edit, reorder or reformat theirs.
|
|
82
|
+
Every row targets a file that exists after the write.
|
|
83
|
+
- **Homes**, only with content, routed by [knowledge.md](knowledge.md).
|
|
84
|
+
- **`CLAUDE.md`**, only when `.joycraft/installation.json` lists the
|
|
85
|
+
`claude` host: missing → create it as `@AGENTS.md` followed by an empty
|
|
86
|
+
`## Claude Code` section; present without an `@AGENTS.md` line → add
|
|
87
|
+
`@AGENTS.md` as line 1; present with it → leave it alone. When `AGENTS.md`
|
|
88
|
+
already imports or defers to `CLAUDE.md`, add no reciprocal import.
|
|
89
|
+
- **Audit fixes** for the findings the user agreed to in the interview, made
|
|
90
|
+
as joycraft-cleanup step 4 says.
|
|
91
|
+
|
|
92
|
+
Add lines, rows and pages. Do not reword, reformat, reorder or delete user
|
|
93
|
+
content: every existing line of `AGENTS.md` and `CLAUDE.md` survives. With
|
|
94
|
+
no `AGENTS.md`, create one with the purpose (or "unknown"), established
|
|
95
|
+
constraints, commands with their source, the Joycraft lines and the map. Keep
|
|
96
|
+
generic coding advice and tentative product ideas out; feature intent stays
|
|
97
|
+
in its brief. Respect symlinks and managed files.
|
|
98
|
+
4. **Show, then write.** Render the diff of every file you would change or
|
|
99
|
+
create, audit fixes included, as one HTML page under
|
|
100
|
+
`.joycraft/local/setup/`. Show it as [showing a page](artifacts.md#showing-a-page)
|
|
101
|
+
says, give its path, and write only on the
|
|
102
|
+
user's yes; this page is setup's only approval stop. A request that
|
|
103
|
+
already approves the files you propose counts as the yes.
|
|
104
|
+
5. **Check.** `wiring.mjs` exits 0. `node .joycraft/runtime/cleanup.mjs`
|
|
105
|
+
reports no `missing-path`, `unmapped`, `orphan` or `broken-link` for the
|
|
106
|
+
files you touched. Every original line of `AGENTS.md` and `CLAUDE.md` is
|
|
107
|
+
still there. Fix what fails, then tell the user in a few lines which docs the
|
|
108
|
+
map now reaches, which homes you created and what you have not read or do
|
|
109
|
+
not know yet. Continue the original request.
|
|
110
|
+
|
|
111
|
+
When the work exposes an unclear state, data, or responsibility boundary,
|
|
112
|
+
inspect the owner and its actual counterparts before recording guidance; read
|
|
113
|
+
`architecture.md` for that focused check. Do not create an architecture phase,
|
|
114
|
+
architecture-complete marker, or empty map during setup.
|
|
107
115
|
|
|
108
116
|
## Kickoff for a new project
|
|
109
117
|
|
|
@@ -158,26 +166,54 @@ Pass `--host-tools browser`, `simulator` or `computer-use` only for tools the
|
|
|
158
166
|
active host actually reports; they can stand in for a missing install. The plan
|
|
159
167
|
detects each package from its manifests, probes versions read-only, and prints
|
|
160
168
|
one table and at most one question. It never installs. When it prints
|
|
161
|
-
`Review loop unchanged.`, ask nothing.
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
the
|
|
169
|
+
`Review loop unchanged.`, ask nothing. Packages come from declared workspaces;
|
|
170
|
+
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 hold
|
|
172
|
+
the apps and pass them as `--packages <dir,dir>` to `plan`, `install` and
|
|
173
|
+
`record`.
|
|
174
|
+
|
|
175
|
+
Show the table: what the plan found per package. Ask the user to confirm it or
|
|
176
|
+
name a tool the plan missed, together with its one question. For a gap, say
|
|
177
|
+
plainly that automated review of that package needs a tool that can show the
|
|
178
|
+
work. Recommend one from the hint list (`review-tools.json`), with its
|
|
179
|
+
trade-offs: size, what it can show, cost and licence. Say you are happy to
|
|
180
|
+
research other options. Explain what the install runs and where, then wait for
|
|
181
|
+
the user's yes in this conversation before you run
|
|
182
|
+
`review-tools.mjs install --root . --yes` (add `--tools <ids>` for a per-tool
|
|
183
|
+
choice or a hint the user picked). It adds project-local tools with the
|
|
184
|
+
project's own package manager and lockfile. It also runs a user-scope CLI
|
|
185
|
+
install (`npm install -g`, `brew install`) when the hint marks no `sudo`,
|
|
186
|
+
licence or sign-in. Never run `sudo`, a licence acceptance or a sign-in: give
|
|
187
|
+
the user the printed `steps`. Then record the choice:
|
|
169
188
|
|
|
170
189
|
```sh
|
|
171
|
-
node .joycraft/runtime/review-tools.mjs record --root . --skip <
|
|
190
|
+
node .joycraft/runtime/review-tools.mjs record --root . [--choose <package>=<tool>] [--command <package>=<command>] [--skip <tool>|<package>:<tool>|<package>] [--host <name> --host-tools <observed host tools>]
|
|
172
191
|
```
|
|
173
192
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
193
|
+
`--choose` records the tool the user picked for a package (a hint id, or a
|
|
194
|
+
found script with its `--command`); `'apps/*'=<tool>` records one shared harness
|
|
195
|
+
for those packages. `--skip <tool>` skips that missing tool in every package;
|
|
196
|
+
`--skip apps/lab:<tool>` or `--skip apps/lab` skips only that package. Repeat
|
|
197
|
+
`--command` per value. This writes or replaces only the `## Review loop` section
|
|
198
|
+
of `AGENTS.md`: one row per package with its tool, what it can show, the command
|
|
199
|
+
that starts the app and the command that takes the evidence. Recording again
|
|
200
|
+
keeps earlier choices and skips for packages the call does not name. Host tools
|
|
201
|
+
go to the git-ignored `.joycraft/local/review-loop.json`, never `AGENTS.md`.
|
|
202
|
+
Worker packets carry both. A skipped package's row says it is not reviewed
|
|
203
|
+
(user skipped). With no network, the probes still run; offer the install later. For a CI-only project, record the CI job as the evidence
|
|
179
204
|
source when the user picks it.
|
|
180
205
|
|
|
206
|
+
**Change a tool.** Talk about the review loop only here: at install, at
|
|
207
|
+
setup and upgrade when the plan reports a change, and when the user asks to
|
|
208
|
+
try, switch, add or remove a tool ("try Maestro for the iOS app"). For a
|
|
209
|
+
request, confirm or research the tool, install it as above, and re-record only
|
|
210
|
+
that package with `--choose <package>=<tool>` (or `--skip` to remove one);
|
|
211
|
+
other rows stay. When the plan's `Changed since the recorded Review loop` names
|
|
212
|
+
a newly detected tool, offer to switch that package to it. When it reports
|
|
213
|
+
`recorded with v1; re-record to keep it`, confirm the table with the user and run
|
|
214
|
+
record again, repeating any `--choose` or `--skip` the table shows; a v1 record
|
|
215
|
+
does not carry them over. An unchanged project asks nothing.
|
|
216
|
+
|
|
181
217
|
`review-tools.json` also lists `optIn` tools that detection never plans. Offer
|
|
182
218
|
one only when it fits the project. Example: Doc Detective, for docs that are
|
|
183
219
|
step-by-step procedures. Say what it does not cover and that it is AGPL-3.0 with a
|
|
@@ -230,23 +266,9 @@ explicit manual Git-worktree workflow.
|
|
|
230
266
|
|
|
231
267
|
## Knowledge grows with the work
|
|
232
268
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
Create its parent directory and link it from the context map. Omit empty sections
|
|
237
|
-
and private contact details that are unnecessary for the work. If nothing is
|
|
238
|
-
known yet, create only the instruction files; gather the first useful fact before
|
|
239
|
-
creating a context document. Do not manufacture a directory tree of empty files.
|
|
240
|
-
|
|
241
|
-
Create additional homes only when they have content:
|
|
242
|
-
|
|
243
|
-
| Content | Default home when no existing convention applies |
|
|
244
|
-
|---|---|
|
|
245
|
-
| Durable project knowledge | `docs/context/project.md` or a focused reference linked by the map |
|
|
246
|
-
| Source-backed cross-boundary navigation | The existing context map or a focused reference linked by it |
|
|
247
|
-
| Reusable decision rationale | `docs/context/decision-log.md`, linking to the owning decision |
|
|
248
|
-
| Current feature or mixed change | `docs/features/<slug>/brief.md` |
|
|
249
|
-
| Authorized implementation queue | `docs/features/<slug>/specs/` |
|
|
269
|
+
Which home holds which kind of fact, and when to create one, is in
|
|
270
|
+
[knowledge guidance](knowledge.md). A current feature lives in
|
|
271
|
+
`docs/features/<slug>/brief.md` and its queue in `docs/features/<slug>/specs/`.
|
|
250
272
|
|
|
251
273
|
A project can move these folders, add an after-archive hook and map code to
|
|
252
274
|
context pages in an optional root `joycraft.yaml`. It is project-owned: create it
|
|
@@ -263,16 +285,16 @@ and links it from the context map.
|
|
|
263
285
|
|
|
264
286
|
The brief retains decision authority under `workflow.md`; the context document
|
|
265
287
|
and decision log must not become competing answer stores. Later accepted facts
|
|
266
|
-
update their existing home.
|
|
288
|
+
update their existing home; [knowledge.md](knowledge.md) owns how each fact is
|
|
289
|
+
routed, changed in place and kept current. Repeating entry with no new knowledge should make
|
|
267
290
|
no setup edits, create no duplicate links, and ask no repeated questions. There
|
|
268
291
|
is no setup-complete sentinel: useful source content, not a flag, determines
|
|
269
292
|
whether context is available.
|
|
270
293
|
|
|
271
|
-
|
|
272
|
-
Prefer one short contextual question and continue
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
an imagined app.
|
|
294
|
+
Outside setup's interview, ask only for missing human knowledge that materially
|
|
295
|
+
changes the next action. Prefer one short contextual question and continue
|
|
296
|
+
independent work while it is pending. Do not generate a questionnaire or start
|
|
297
|
+
building an imagined app.
|
|
276
298
|
|
|
277
299
|
Use the project’s existing interaction home for a choice. A question with
|
|
278
300
|
options goes in the decision artifact; only one quick yes/no or an open question
|
|
@@ -281,28 +303,20 @@ owning brief and do not ask it again.
|
|
|
281
303
|
|
|
282
304
|
## Finish setup and continue
|
|
283
305
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
homes were created or extended and any important unknown; then continue the
|
|
287
|
-
original request. Setup does not approve hooks, change credentials, install
|
|
306
|
+
Step 5 of [Set up the context map](#set-up-the-context-map) is the finish
|
|
307
|
+
check; also check that command claims match their cited source. Setup does not approve hooks, change credentials, install
|
|
288
308
|
dependencies, or replace the user's workflow. Read `hooks-install.md` only when
|
|
289
309
|
hook activation is part of the requested setup.
|
|
290
310
|
|
|
291
311
|
## Upgrade and agent onboarding
|
|
292
312
|
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
the worker to read existing project preferences before work, reuse explicit
|
|
304
|
-
model/effort/role/concurrency/verification choices, and inspect the host's
|
|
305
|
-
currently available planner, implementer, reviewer, testing, UI, and fixture
|
|
306
|
-
capabilities rather than claiming a hardcoded model is available. State
|
|
307
|
-
unavailable roles and native-hook checks plainly. Do not alter accepted queues,
|
|
308
|
-
decision state, user guidance, or credentials during setup or upgrade.
|
|
313
|
+
Updates go through the Joycraft CLI; follow [update guidance](update.md). The
|
|
314
|
+
installation manifest `.joycraft/installation.json` records the installed bytes;
|
|
315
|
+
it is dispatch input, not proof that hooks ran or that a review was independent.
|
|
316
|
+
|
|
317
|
+
A new worker reads `.joycraft/preferences.json` before work, reuses explicit
|
|
318
|
+
model, effort, role, concurrency and verification choices, and inspects the
|
|
319
|
+
host's available planner, implementer, reviewer, testing, UI and fixture
|
|
320
|
+
capabilities instead of assuming a model. It states unavailable roles plainly.
|
|
321
|
+
Setup and upgrade never change accepted queues, decision state, user guidance or
|
|
322
|
+
credentials.
|