joycraft 0.7.17 → 1.0.1
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 +148 -140
- package/dist/cli.js +1593 -373
- package/dist/cli.js.map +1 -1
- package/dist/joycraft-release.json +1 -1
- package/package.json +9 -3
- package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
- package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
- package/payload/.agents/skills/joycraft-entry/SKILL.md +109 -0
- package/payload/.agents/skills/joycraft-implement/SKILL.md +118 -0
- package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
- package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
- package/payload/.agents/skills/joycraft-session-end/SKILL.md +82 -0
- package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
- package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
- package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
- package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
- package/payload/.claude/agents/joycraft-implementer.md +36 -0
- package/payload/.claude/agents/joycraft-reviewer.md +35 -0
- package/payload/.joycraft/assets/artifacts/kit.css +102 -0
- package/payload/.joycraft/assets/artifacts/kit.js +301 -0
- package/payload/.joycraft/assets/artifacts/transports.js +236 -0
- package/payload/.joycraft/contracts/types.d.ts +185 -0
- package/payload/.joycraft/references/architecture.md +90 -0
- package/payload/.joycraft/references/archive.md +211 -0
- package/payload/.joycraft/references/artifacts.md +176 -0
- package/payload/.joycraft/references/completion.md +109 -0
- package/payload/.joycraft/references/context.md +85 -0
- package/payload/.joycraft/references/delivery.md +32 -0
- package/payload/.joycraft/references/dispatch.md +231 -0
- package/payload/.joycraft/references/recurring-failures.md +33 -0
- package/payload/.joycraft/references/retro.md +94 -0
- package/payload/.joycraft/references/setup.md +295 -0
- package/payload/.joycraft/references/testing.md +120 -0
- package/payload/.joycraft/references/update.md +44 -0
- package/payload/.joycraft/references/workflow.md +113 -0
- package/payload/.joycraft/references/worktrees.md +174 -0
- package/payload/.joycraft/runtime/archive.mjs +463 -0
- package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
- package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
- package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
- package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
- package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
- package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
- package/payload/.joycraft/runtime/completion.mjs +300 -0
- package/payload/.joycraft/runtime/context/cli.mjs +75 -0
- package/payload/.joycraft/runtime/context/index.mjs +29 -0
- package/payload/.joycraft/runtime/context/search.mjs +149 -0
- package/payload/.joycraft/runtime/coordinator.mjs +169 -0
- package/payload/.joycraft/runtime/delivery.mjs +142 -0
- package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
- package/payload/.joycraft/runtime/dispatch-start.mjs +106 -0
- package/payload/.joycraft/runtime/evidence.mjs +137 -0
- package/payload/.joycraft/runtime/identity.mjs +486 -0
- package/payload/.joycraft/runtime/kickoff.mjs +174 -0
- package/payload/.joycraft/runtime/redact.mjs +9 -0
- package/payload/.joycraft/runtime/retro.mjs +151 -0
- package/payload/.joycraft/runtime/review-tools.json +34 -0
- package/payload/.joycraft/runtime/review-tools.mjs +331 -0
- package/payload/.joycraft/runtime/scope.mjs +129 -0
- package/payload/.joycraft/runtime/status.mjs +96 -0
- package/payload/.joycraft/runtime/update-check.mjs +142 -0
- package/payload/.joycraft/runtime/worktrees.mjs +201 -0
- package/payload/.joycraft/templates/README.md +7 -0
- package/payload/.joycraft/templates/artifact.json +33 -0
- package/payload/.joycraft/templates/brief.md +35 -0
- package/payload/.joycraft/templates/decisions.md +13 -0
- package/payload/.joycraft/templates/project-context.md +36 -0
- package/payload/.joycraft/templates/queue.json +27 -0
- package/payload/.joycraft/templates/spec.md +39 -0
- package/payload/.joycraft/templates/ui-slice.html +71 -0
- package/payload/PIN +77 -0
- package/payload/scripts/export.mjs +301 -0
- package/payload/scripts/hook-paths.mjs +35 -0
- package/payload/scripts/legacy-hooks.mjs +128 -0
- package/payload/scripts/legacy-inventory.json +117 -0
- package/dist/chunk-35RQLGKM.js +0 -2167
- package/dist/chunk-35RQLGKM.js.map +0 -1
- package/dist/chunk-7BPB2IKY.js +0 -255
- package/dist/chunk-7BPB2IKY.js.map +0 -1
- package/dist/chunk-B73DPYYC.js +0 -377
- package/dist/chunk-B73DPYYC.js.map +0 -1
- package/dist/chunk-K4AI6FKB.js +0 -417
- package/dist/chunk-K4AI6FKB.js.map +0 -1
- package/dist/chunk-KKDKC4FM.js +0 -115
- package/dist/chunk-KKDKC4FM.js.map +0 -1
- package/dist/chunk-OMFGDJW4.js +0 -97
- package/dist/chunk-OMFGDJW4.js.map +0 -1
- package/dist/chunk-YLWBDXF4.js +0 -3999
- package/dist/chunk-YLWBDXF4.js.map +0 -1
- package/dist/chunk-Z5JFEGWG.js +0 -563
- package/dist/chunk-Z5JFEGWG.js.map +0 -1
- package/dist/init-O2QC5X57.js +0 -60
- package/dist/init-O2QC5X57.js.map +0 -1
- package/dist/init-autofix-2DMBO4QN.js +0 -122
- package/dist/init-autofix-2DMBO4QN.js.map +0 -1
- package/dist/install-manifest-EQHT4474.js +0 -37
- package/dist/install-manifest-EQHT4474.js.map +0 -1
- package/dist/release-artifact-4TL5L2ZY.js +0 -14
- package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
- package/dist/release-resolver-P2H46QTU.js +0 -293
- package/dist/release-resolver-P2H46QTU.js.map +0 -1
- package/dist/telemetry-store-IBO5GRTA.js +0 -14
- package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
- package/dist/update-LYHS4FBH.js +0 -21
- package/dist/update-LYHS4FBH.js.map +0 -1
- package/dist/update-check-YT765NE7.js +0 -36
- package/dist/update-check-YT765NE7.js.map +0 -1
- package/dist/upgrade-GMP6JQ52.js +0 -28
- package/dist/upgrade-GMP6JQ52.js.map +0 -1
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
# Worker delivery preflight
|
|
2
|
+
|
|
3
|
+
For normal native work, the host launches the worker and the child then uses the
|
|
4
|
+
dispatch-start entry point from its actual root before any tasked edit. A
|
|
5
|
+
coordinator uses it itself only when it is the worker actor. It validates delivery
|
|
6
|
+
and returns a ready/unenforced decision plus the bounded packet and hook-binding
|
|
7
|
+
instructions; it never launches a worker, alters queue status, or accepts work.
|
|
8
|
+
For a mutable worker or stateful runtime check, first apply the conditional
|
|
9
|
+
[worker-isolation policy](worktrees.md); this preflight does not create a
|
|
10
|
+
worktree or a resource lease. A `read-only` workspace keeps declared source
|
|
11
|
+
inputs frozen; it may still write declared review reports and receipts outside
|
|
12
|
+
those inputs. Cache-mutating runtime work needs separate mutable state.
|
|
13
|
+
|
|
14
|
+
## Contents
|
|
15
|
+
|
|
16
|
+
- [Start a native dispatch](#start-a-native-dispatch)
|
|
17
|
+
- [Call the portable dispatch API](#call-the-portable-dispatch-api)
|
|
18
|
+
- [Bind the hook source view](#bind-the-hook-source-view)
|
|
19
|
+
- [Validate capabilities before dispatch](#validate-capabilities-before-dispatch)
|
|
20
|
+
- [Check the reviewer report](#check-the-reviewer-report)
|
|
21
|
+
|
|
22
|
+
## Start a native dispatch
|
|
23
|
+
|
|
24
|
+
Prepare packets from the same current, raw sources that define the work: the
|
|
25
|
+
brief, spec, queue, exact declared inputs, and only the scoped owning decisions
|
|
26
|
+
or context records needed to interpret them. Each delivered decision is its
|
|
27
|
+
exact current brief record plus the brief hash and
|
|
28
|
+
`frontmatter.decisions.<id>` anchor. A `clarified` or `assigned` record is
|
|
29
|
+
current only with an actual nonempty `answer`. `open`,
|
|
30
|
+
`backlogged`, and `discarded` records never become current because an `answer`
|
|
31
|
+
field is present. Unknown, malformed, missing, or unresolved selected records
|
|
32
|
+
remain explicit `decisionLimitations`. When a change crosses a material
|
|
33
|
+
UI/state/storage or producer/consumer boundary, include the actual coupled
|
|
34
|
+
counterpart source as an exact input. If the implementer or coordinator finds a
|
|
35
|
+
material omitted counterpart, update the declared inputs before reviewer
|
|
36
|
+
preparation and make a fresh packet; do not rely on a broad architecture map,
|
|
37
|
+
an automatic crawl, or an implementer's summary. This applies only when the
|
|
38
|
+
boundary matters to the requested behavior.
|
|
39
|
+
|
|
40
|
+
Reconcile the declared scope with the actual Git diff from a captured base to
|
|
41
|
+
the reviewed revision; a hand-written file list can omit the changed path.
|
|
42
|
+
Deliver relevant owner picks, reference renders and environment/fixture recipes
|
|
43
|
+
when they govern acceptance. Keep evidence available at the review boundary:
|
|
44
|
+
commit permitted receipts or a sanitized index, and deliver approved local
|
|
45
|
+
sensitive evidence through the existing scoped path. A private screenshot need
|
|
46
|
+
not become a tracked asset, and an inaccessible gitignored path is not evidence.
|
|
47
|
+
|
|
48
|
+
Use the child command for ordinary new work. Once the host has launched a worker
|
|
49
|
+
and its root is known, the child derives the current queue, spec, brief (or explicit `--brief`) and
|
|
50
|
+
declared input hashes, prepares and binds the current packet, and writes it to a
|
|
51
|
+
project-relative parent directory. Write packets and subjects under
|
|
52
|
+
`.joycraft/local/packets/` so they do not become unrelated scope paths; startup
|
|
53
|
+
creates that directory and refuses an output Git would track, so do not create
|
|
54
|
+
or check it yourself. For an auto-created worktree whose
|
|
55
|
+
path is unknown until launch, the child bootstraps and starts from its actual
|
|
56
|
+
root before mutation; never start against a guessed path:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
node .joycraft/runtime/dispatch-start.mjs \
|
|
60
|
+
--worker-root <absolute-worker-root> --expected-manifest <absolute-pinned-manifest> \
|
|
61
|
+
--queue <queue-path> --spec <id> --role implementer \
|
|
62
|
+
--implementer-session <actual-session-id> \
|
|
63
|
+
--capabilities filesystem:read,filesystem:write-report,agent:separate-context \
|
|
64
|
+
--out .joycraft/local/packets/<packet.json> \
|
|
65
|
+
--native-session <actual-host-session-id> \
|
|
66
|
+
--native-agent <actual-host-child-agent-id> \
|
|
67
|
+
--native-host <host> \
|
|
68
|
+
--coordinator-session <coordinator-session-id>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
`--coordinator-session` is required while the queue has a coordinator lease
|
|
72
|
+
(`coordinator.mjs claim`) and must equal the holder; startup output then names
|
|
73
|
+
the coordinator. Omit it only for an unclaimed queue.
|
|
74
|
+
|
|
75
|
+
Run each `git` command and each Joycraft runtime call (`node
|
|
76
|
+
.joycraft/runtime/…`, `pnpm joycraft:…`) as its own plain shell
|
|
77
|
+
command: never chain them with `&&`, `;` or `|`, and never use `$(git …)`. To
|
|
78
|
+
pass a root or revision, run `pwd` or `git rev-parse HEAD` alone first and paste
|
|
79
|
+
the literal value. A worktree-isolated host refuses Git inside a compound command.
|
|
80
|
+
|
|
81
|
+
`--native-agent` is present only when the host issued a child identity;
|
|
82
|
+
`--native-host` is optional. Use actual host-issued values only. The start flow
|
|
83
|
+
consumes the existing `--coordinator`, `--parallel`, `--access`,
|
|
84
|
+
`--base-revision`, `--implementer-host`, and `--implementer-agent` options.
|
|
85
|
+
Startup never writes `verification.changeScope`; a spec opts in by recording
|
|
86
|
+
it before the first implementer mutation, and startup preserves it. The separate
|
|
87
|
+
workspace `--base-revision` option keeps its documented topology check.
|
|
88
|
+
Implementer dispatch requires each dependency to be `done`; reviewer dispatch
|
|
89
|
+
does not require the target itself to be done. Unknown roles are rejected.
|
|
90
|
+
|
|
91
|
+
When a reviewer startup exits non-zero or returns `ready: false`, run it once
|
|
92
|
+
more, alone, with a fresh packet path. If it fails again, stop that spec's
|
|
93
|
+
review and tell the user its printed reason; never continue as if the review
|
|
94
|
+
started. Do not retry a `Task startup stopped:` refusal unchanged; fix its cause.
|
|
95
|
+
|
|
96
|
+
The return is `ready: true` for an available valid startup path, including a
|
|
97
|
+
hooks-disabled/manual path. It is not a cryptographic attestation. Missing human
|
|
98
|
+
prompt history for an enforced startup is explicit
|
|
99
|
+
`ready: false`, exit code 2, and `unenforced`; it is not a permission request,
|
|
100
|
+
an invented prompt, or a substitute session ID. Continue discovery and other
|
|
101
|
+
unrelated authorized work, including manual/disabled workflows, but do not
|
|
102
|
+
dispatch the claimed enforced worker. Do not
|
|
103
|
+
select an arbitrary task to make a native relationship appear valid. A child
|
|
104
|
+
binding uses its own root and a real prompt; it may inherit the same native
|
|
105
|
+
parent session authority only when an observed linked coordinator relationship
|
|
106
|
+
is valid. A unique new root session needs its own actual prompt.
|
|
107
|
+
|
|
108
|
+
When the host reports a native agent/invocation ID, also pass
|
|
109
|
+
`--implementer-host <host> --implementer-agent <actual-agent-id>`. For a root
|
|
110
|
+
session, `--implementer-host <host>` may be used without a child agent ID.
|
|
111
|
+
Record the returned reviewer actor after launch; never invent it before dispatch.
|
|
112
|
+
Claude's plain Agent worker can share the parent session while having its own
|
|
113
|
+
native agent ID. It can review in the same checkout when a separate context is
|
|
114
|
+
observed and the reviewed inputs stay fixed. A worktree alone proves neither
|
|
115
|
+
independent context nor current evidence. Reports carry both actor records or
|
|
116
|
+
neither; see `completion.md` for the legacy fallback.
|
|
117
|
+
|
|
118
|
+
The setup/export flow writes `.joycraft/installation.json` with the
|
|
119
|
+
actual exported file paths and SHA-256 values. Give the helper an explicit
|
|
120
|
+
absolute `workerRoot` and an explicit pinned expected manifest path; it compares
|
|
121
|
+
role/shared files against both. A worker's own manifest cannot attest that an
|
|
122
|
+
old, internally consistent installation is the intended export.
|
|
123
|
+
Include the reviewer skill, every reference it needs, and every runtime module
|
|
124
|
+
it needs in `delivery.roles`. A matching path is insufficient when the bytes
|
|
125
|
+
are from an older install.
|
|
126
|
+
|
|
127
|
+
The low-level `preflightDispatch`/`nativeDispatch` API and `prepare` command
|
|
128
|
+
remain legacy/manual binding tools. They are not the normal path for new
|
|
129
|
+
startup. Calls that omit `expectedManifestPath` validate only the worker's own
|
|
130
|
+
bundle and do not attest the intended release. Do not claim release delivery
|
|
131
|
+
from a legacy self-attested call.
|
|
132
|
+
|
|
133
|
+
## Call the portable dispatch API
|
|
134
|
+
|
|
135
|
+
Call the portable API from a Codex, Claude, Pi, OMP, or Copilot adapter. Normal
|
|
136
|
+
native startup calls `startDispatch(options, nativeEvent)` so the runtime can
|
|
137
|
+
validate the observed session, agent relationship, and prompt authority before
|
|
138
|
+
it returns a packet:
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
import { startDispatch } from './.joycraft/runtime/dispatch-start.mjs';
|
|
142
|
+
|
|
143
|
+
const started = await startDispatch(options, nativeEvent);
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Use the returned packet only when `started.ready` is true. `nativeEvent` is
|
|
147
|
+
observed host data, not caller-filled identity or authority. The older
|
|
148
|
+
`nativeDispatch(request, native)` API is retained for portable/manual callers;
|
|
149
|
+
it does not make an unbound startup valid.
|
|
150
|
+
|
|
151
|
+
`request` is schema-v1 and contains `workerRoot`, optional `manifestPath`,
|
|
152
|
+
`delivery`, and `claims`. `delivery.sourceView` has hashed `brief`, `spec`,
|
|
153
|
+
`queue`, `inputs`, exact anchored `decisions`, and any `decisionLimitations`.
|
|
154
|
+
A decision record is raw authority, not a review instruction; do not put an
|
|
155
|
+
expected verdict, conclusion, or implementer reasoning in another delivery
|
|
156
|
+
field. A requirement input can use `scope.decisionIds` to select brief
|
|
157
|
+
decisions. Without a selector, the packet conservatively carries every current
|
|
158
|
+
answered decision from that brief. The packet retains its whole-brief reference
|
|
159
|
+
so workers can read each decision in context. Its inputs include any current
|
|
160
|
+
coupled counterpart required to review the requested behavior.
|
|
161
|
+
|
|
162
|
+
## Bind the hook source view
|
|
163
|
+
|
|
164
|
+
Dispatch-start prepares and binds its hash-bound `hookSourceView` with actual
|
|
165
|
+
native IDs. The lower-level manual bind command remains only for an explicit
|
|
166
|
+
non-native boundary. It uses the actual native session ID reported at startup,
|
|
167
|
+
never a generated UUID:
|
|
168
|
+
|
|
169
|
+
```sh
|
|
170
|
+
node .joycraft/runtime/hooks/cli.mjs bind-source \
|
|
171
|
+
--session <actual-native-session-id> --packet <project-relative-packet.json>
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Bind a known parent session before launching children when the host exposes
|
|
175
|
+
parent inheritance. Otherwise, bind the child after it reports its own actual
|
|
176
|
+
session ID. For children sharing a parent session but working on different
|
|
177
|
+
specs, add `--agent <actual-native-child-id>` when binding each child. Its task
|
|
178
|
+
view remains separate while human prompts still inherit from the parent.
|
|
179
|
+
Rebind after the brief changes. The hook view currently receives only
|
|
180
|
+
hash-checked brief and decision pointers; the worker packet retains the exact
|
|
181
|
+
decision records. An unknown ID leaves the dependent
|
|
182
|
+
Jev check advisory and unverified; it does not permit a substitute ID. The view
|
|
183
|
+
makes selected saved answers available to Jev, but never grants permission or
|
|
184
|
+
an expected review outcome.
|
|
185
|
+
|
|
186
|
+
## Validate capabilities before dispatch
|
|
187
|
+
|
|
188
|
+
`claims.capabilities` must include `filesystem:read`,
|
|
189
|
+
`filesystem:write-report`, and each role's `requiredCapabilities`; its claimed
|
|
190
|
+
report destination must be project-relative and writable in the worker root.
|
|
191
|
+
Pass only capabilities the host actually observed. A reviewer additionally needs
|
|
192
|
+
`agent:separate-context`; an implementer does not. For work that will create new
|
|
193
|
+
files, prepare the implementer packet before those files exist; prepare the
|
|
194
|
+
reviewer packet after implementation from the current files. Unknown capability
|
|
195
|
+
is a hold on the dependent dispatch or acceptance, never a reason to invent a
|
|
196
|
+
claim.
|
|
197
|
+
|
|
198
|
+
## Check the reviewer report
|
|
199
|
+
|
|
200
|
+
After the independent reviewer returns a report, run:
|
|
201
|
+
|
|
202
|
+
```sh
|
|
203
|
+
node .joycraft/runtime/dispatch-preflight.mjs check-report \
|
|
204
|
+
--worker-root <absolute-worker-root> --queue <queue-path> --spec <id> --report <report-path>
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
This uses completion's existing report and evidence validators, but it cannot
|
|
208
|
+
move a spec to `done`. Send a rejected report back to the same reviewer for
|
|
209
|
+
correction. Missing observations remain missing; do not manufacture them.
|
|
210
|
+
Only `completion.mjs finalize-review` can accept a PASS report (`complete` is
|
|
211
|
+
the strict compatibility alias). Preserve FAIL or
|
|
212
|
+
UNVERIFIED reports; a trusted owner's explicit acceptance of their current
|
|
213
|
+
findings uses the separate `accept-owner` path in
|
|
214
|
+
[completion guidance](completion.md#explicit-owner-acceptance-of-current-findings).
|
|
215
|
+
|
|
216
|
+
## Change scope and review startup
|
|
217
|
+
|
|
218
|
+
Opt into scope checks per spec with
|
|
219
|
+
`verification.changeScope: { baseRevision, exclusions? }`. The base is a full
|
|
220
|
+
available commit SHA captured before the first implementer mutation. The runtime
|
|
221
|
+
infers relevant paths from verification inputs, the brief, spec, queue, and
|
|
222
|
+
criteria. Review startup does not require a scope; when one is recorded, never
|
|
223
|
+
substitute current `HEAD` for its base. If unrelated files changed after the base, give each an
|
|
224
|
+
exact `exclusions: [{ path, reason }]` disposition. Do not add the whole branch
|
|
225
|
+
or broad directories just to silence a scope failure.
|
|
226
|
+
|
|
227
|
+
Inputs normally describe files that must be present. A deliberate deletion
|
|
228
|
+
requires `state: 'absent'` on an explicit non-requirement input. A rename needs
|
|
229
|
+
the new present input and the prior path as an absent input. Requirement inputs
|
|
230
|
+
cannot be absent. This keeps absence an explicit claim instead of an accidental
|
|
231
|
+
coverage hole.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Recurring failure guidance
|
|
2
|
+
|
|
3
|
+
Use this reference only when a coordinator sees a possible reusable lesson in
|
|
4
|
+
existing independent `FAIL`, `UNVERIFIED`, or later verified-repair reports.
|
|
5
|
+
Keep a compact, source-linked shortlist in the active task material, not a new
|
|
6
|
+
state store. An empty shortlist is useful when the reports do not support one.
|
|
7
|
+
|
|
8
|
+
## Select and inspect
|
|
9
|
+
|
|
10
|
+
Treat distinct tasks or incidents as separate evidence; repeated attempts at one
|
|
11
|
+
failure are not independent episodes. A single verified repair can establish a
|
|
12
|
+
project fact about that repaired behavior, without waiting for two episodes.
|
|
13
|
+
For each candidate, inspect the current owning sources before repeating any
|
|
14
|
+
historical claim: a past report may be stale. Keep its report/receipt path, the
|
|
15
|
+
scoped trigger or counterexample, and the actual counterpart paths or journey
|
|
16
|
+
that distinguish the affected behavior. First check whether existing guidance
|
|
17
|
+
and relevant sources were declared, delivered to the worker, and actually read
|
|
18
|
+
where the transcript establishes that. Repair missing delivery before adding
|
|
19
|
+
more instructions; an input hash proves delivery, not comprehension.
|
|
20
|
+
Do not turn a local observation into a
|
|
21
|
+
global rule, rewrite unrelated guidance, or add an approval, blocker, schema,
|
|
22
|
+
runtime, provider call, or automatic rewrite.
|
|
23
|
+
|
|
24
|
+
## Deliver and assess
|
|
25
|
+
|
|
26
|
+
Frame an unverified generalization as a proposed lesson. Send a reviewed
|
|
27
|
+
proposal to the next worker through the existing [dispatch guidance](dispatch.md):
|
|
28
|
+
include its report links, current source paths, trigger/counterexample, actual
|
|
29
|
+
counterpart path or journey, and the concrete check to perform as exact worker
|
|
30
|
+
inputs. After one verified repair, link the outcome as a project fact about that
|
|
31
|
+
fix. Context and proposed lessons do not create product decisions, permission,
|
|
32
|
+
binding constraints, or an expected review verdict. Claim a broader method benefit only after later independent reuse confirms
|
|
33
|
+
it; until then, keep that benefit pending rather than presenting it as evidence.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Retrospective evidence
|
|
2
|
+
|
|
3
|
+
Use `joycraft-retro` on a requested session worth learning from, including a
|
|
4
|
+
successful session with unexpected friction. It proposes environment improvements;
|
|
5
|
+
it does not run on every session end, change acceptance or add Jev calls.
|
|
6
|
+
|
|
7
|
+
## Prepare native session evidence
|
|
8
|
+
|
|
9
|
+
If current host context or an already-cleaned record is sufficient, read it
|
|
10
|
+
directly. For a native Claude or Codex JSONL transcript, use the deterministic
|
|
11
|
+
local helper with an explicit source and a new private output directory:
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
node .joycraft/runtime/retro.mjs prepare --source /absolute/path/session.jsonl --out /absolute/path/new-retro-evidence
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
An optional physical line range selects a known episode; review coverage before
|
|
18
|
+
treating it as complete:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
node .joycraft/runtime/retro.mjs prepare --source /absolute/path/session.jsonl --out /absolute/path/new-retro-episode --from-line 120 --to-line 380
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Line selection reduces the prepared context, not source-read memory: this small
|
|
25
|
+
helper reads the supplied file into memory. Use an existing episode export or
|
|
26
|
+
the evidence collector for sources too large for that approach, retaining the
|
|
27
|
+
original source references and any selection limits.
|
|
28
|
+
|
|
29
|
+
Read `coverage.json` first, then `conversation.md` and `tools.jsonl`. The source
|
|
30
|
+
hash and physical line references let you return to exact raw evidence. The
|
|
31
|
+
conversation preserves selected human and assistant text; tool calls/results
|
|
32
|
+
stay in the compact ledger. Tool previews are partial; full results remain in
|
|
33
|
+
the original record. Reasoning and routine transport metadata are disclosed as
|
|
34
|
+
omitted rather than mixed with the human conversation. Unsupported or malformed
|
|
35
|
+
content is reported as a gap. Inspect needed raw lines before concluding that a
|
|
36
|
+
brief preview, missing result or incomplete transcript proves a failure.
|
|
37
|
+
|
|
38
|
+
The helper reads only the supplied file and writes the explicitly requested new
|
|
39
|
+
output directory. It performs no discovery, provider call, classification or
|
|
40
|
+
edits to existing project sources. Choosing an output inside a checkout creates
|
|
41
|
+
new untracked files there; keep raw and prepared records in a private directory
|
|
42
|
+
outside tracked project documentation. Pattern redaction is a
|
|
43
|
+
precaution, not a guarantee of anonymity or comprehensive secret removal;
|
|
44
|
+
inspect material before sharing it. It creates no permission or decision state.
|
|
45
|
+
Other harness formats can be read directly; do not describe an unsupported
|
|
46
|
+
format as normalized or invent native coverage.
|
|
47
|
+
|
|
48
|
+
Keep any linked session/worker files, hook receipts and final review reports as
|
|
49
|
+
separate sources. A single file may not contain all workers or continuations.
|
|
50
|
+
Existing hook metrics can summarize explicit receipts without replaying paid
|
|
51
|
+
checks:
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
node .joycraft/runtime/hooks/metrics.mjs --log /absolute/path/events.jsonl
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Provider-reported usage is not an invoice; absent calls, timing or usage remain
|
|
58
|
+
unknown. Do not equate a missing receipt with a free or absent call.
|
|
59
|
+
|
|
60
|
+
## Judge a candidate
|
|
61
|
+
|
|
62
|
+
For each supported finding, retain its event/line reference, actual observation,
|
|
63
|
+
current owning source, proposed destination and a concrete validation. Check
|
|
64
|
+
whether the source was absent, stale, delivered but ignored, or incorrect. This
|
|
65
|
+
distinction matters before changing a skill.
|
|
66
|
+
|
|
67
|
+
| Observed problem | Smallest useful destination |
|
|
68
|
+
|---|---|
|
|
69
|
+
| Repeated search for the same responsibility | A pointer in the existing scoped context home |
|
|
70
|
+
| Existing lint/test command was broken or unwired | Repair/connect that command |
|
|
71
|
+
| Repeated mechanically detectable mistake | A tested repository-native check |
|
|
72
|
+
| Reviewer missed a genuine judgment issue | Existing scoped review guidance |
|
|
73
|
+
| Tool output or retry behavior wasted work | The tool's output/implementation/configuration |
|
|
74
|
+
| Guidance appears ineffective or contradictory | A focused comparison or correction at its source |
|
|
75
|
+
| Required logs, fixtures or capability were unavailable | The project's bootstrap or evidence access |
|
|
76
|
+
| Intent changed without reaching a worker | Existing brief and source-delivery path |
|
|
77
|
+
|
|
78
|
+
These are possible remedies, not categories that must all produce findings.
|
|
79
|
+
Missing CI alone is a lead; evaluate the task's actual feedback path. Avoid
|
|
80
|
+
adding tests that mirror implementation or guards that reject authorized ordinary
|
|
81
|
+
work. Test a proposed control on its motivating failure and a legitimate allowed
|
|
82
|
+
case. Existing human authorization may supersede an older scoped instruction.
|
|
83
|
+
|
|
84
|
+
Show the user only the context necessary to assess each candidate. Keep full
|
|
85
|
+
evidence behind references. A chosen, verified repair establishes a local fact;
|
|
86
|
+
effectiveness on other tasks remains unproven. Session-end archival still moves
|
|
87
|
+
only wholly accepted features at the session boundary, retaining historical
|
|
88
|
+
evidence and promoting continuing facts through the existing context path.
|
|
89
|
+
|
|
90
|
+
## Attribution
|
|
91
|
+
|
|
92
|
+
Inspired by Matt Pocock's [retro](https://github.com/mattpocock/skills/blob/4588b32ecab9ecc9fc8cc6b6c5e7d675b6004b0d/skills/engineering/retro/SKILL.md)
|
|
93
|
+
and his [v1.3 walkthrough](https://www.youtube.com/watch?v=BsJGo1wFTvQ&t=579s).
|
|
94
|
+
Joycraft retains its own source-delivery, authority and evidence contracts.
|
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
# First-use project setup
|
|
2
|
+
|
|
3
|
+
Use this on first entry, an explicit setup/init request, or a missing context
|
|
4
|
+
home. It is an agent-guided part of `joycraft-entry`, not an installer side
|
|
5
|
+
effect or a separate interview; the one exception is the opt-in
|
|
6
|
+
[kickoff for a new project](#kickoff-for-a-new-project). Work inside the current project. Read-only
|
|
7
|
+
requests do not authorize setup writes.
|
|
8
|
+
|
|
9
|
+
For a reviewed clone, `node scripts/setup.mjs --target <project>` previews the
|
|
10
|
+
smallest missing knowledge homes. Add `--write` only after reviewing the preview.
|
|
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.
|
|
14
|
+
|
|
15
|
+
## Contents
|
|
16
|
+
|
|
17
|
+
- [Discover before writing](#discover-before-writing)
|
|
18
|
+
- [Small shared entry point](#small-shared-entry-point)
|
|
19
|
+
- [Kickoff for a new project](#kickoff-for-a-new-project)
|
|
20
|
+
- [Review loop tools](#review-loop-tools)
|
|
21
|
+
- [Project-owned worktrees](#project-owned-worktrees)
|
|
22
|
+
- [Knowledge grows with the work](#knowledge-grows-with-the-work)
|
|
23
|
+
- [Finish setup and continue](#finish-setup-and-continue)
|
|
24
|
+
- [Upgrade and agent onboarding](#upgrade-and-agent-onboarding)
|
|
25
|
+
|
|
26
|
+
## Discover before writing
|
|
27
|
+
|
|
28
|
+
Read applicable instructions, root `AGENTS.md` and `CLAUDE.md` if present, README,
|
|
29
|
+
and the relevant existing context links. Inspect manifests, lockfiles, task
|
|
30
|
+
scripts and CI only as needed to establish the stack and actual commands. Follow
|
|
31
|
+
the project's documentation conventions instead of migrating them into ours.
|
|
32
|
+
Do not scan neighboring projects or credential files. Do not run installs,
|
|
33
|
+
deployments, destructive commands, or application setup just to populate a table.
|
|
34
|
+
|
|
35
|
+
Use the current conversation for intended users, purpose, stakeholders and
|
|
36
|
+
constraints. Separate user-stated intent from repository observations and your
|
|
37
|
+
assumptions. A declared command is not a verified successful command: cite its
|
|
38
|
+
manifest/script source and mark it unrun until actually executed. On a bare
|
|
39
|
+
project, say the stack and commands are not established; do not choose them for
|
|
40
|
+
the sake of setup. Offer the kickoff below instead.
|
|
41
|
+
|
|
42
|
+
When the current authorized work exposes an unclear state, data, or
|
|
43
|
+
responsibility boundary, inspect the relevant owner and its actual counterparts
|
|
44
|
+
before recording guidance. Preserve source-backed navigation in the existing
|
|
45
|
+
context map or reference home; keep product behavior in the current brief. Read
|
|
46
|
+
`architecture.md` for this focused, conditional discovery. Do not create an
|
|
47
|
+
architecture phase, architecture-complete marker, or empty map during setup.
|
|
48
|
+
|
|
49
|
+
## Small shared entry point
|
|
50
|
+
|
|
51
|
+
If `AGENTS.md` is missing, create a concise project-specific file with:
|
|
52
|
+
|
|
53
|
+
- Project purpose supported by the request or repository; if unknown, say so.
|
|
54
|
+
- Existing commands, their source and execution status, when available.
|
|
55
|
+
- Only established project constraints, preserving their scope.
|
|
56
|
+
- A context map with project-relative links and a short “read when” for each.
|
|
57
|
+
- This line: “First action in each session: run
|
|
58
|
+
`node .joycraft/runtime/update-check.mjs check`. If it prints JSON, follow
|
|
59
|
+
`.joycraft/references/update.md`.”
|
|
60
|
+
- This line: “Show every document a person must read, review or answer (a brief,
|
|
61
|
+
plan, spec set, review or set of questions) as a rendered page, never only as
|
|
62
|
+
Markdown in chat: use the decision artifact
|
|
63
|
+
(`node .joycraft/runtime/artifacts/cli.mjs`, see `.joycraft/references/artifacts.md`)
|
|
64
|
+
for a brief or questions, or an HTML page for any other document. Open it for
|
|
65
|
+
the person and say where it is.”
|
|
66
|
+
- A context-map row for `.joycraft/references/artifacts.md`, read when “showing a
|
|
67
|
+
document or questions to a person”.
|
|
68
|
+
|
|
69
|
+
Do not copy prototype-maintainer rules or fill it with generic coding advice.
|
|
70
|
+
Link detail rather than duplicating it. Do not encode a tentative product idea
|
|
71
|
+
as a permanent boundary. Keep current feature intent in its brief.
|
|
72
|
+
|
|
73
|
+
If `AGENTS.md` already exists, preserve its content and add only missing facts,
|
|
74
|
+
useful context pointers, the update-check line, the rendered-documents line and its
|
|
75
|
+
context-map row above with a targeted edit. Reuse an existing context map
|
|
76
|
+
rather than adding another. Read linked content before deciding it is missing.
|
|
77
|
+
When its map names a project-context home, use that exact project-relative home;
|
|
78
|
+
use `docs/context/project.md` only when no context home exists. Do not link a
|
|
79
|
+
context document that setup did not create or find. This keeps a bare project
|
|
80
|
+
free of dangling links.
|
|
81
|
+
Do not reformat, delete, or replace user instructions. Surface consequential
|
|
82
|
+
contradictions rather than silently resolving them. Respect symlinks and managed
|
|
83
|
+
files; do not replace them or write outside the project through them.
|
|
84
|
+
|
|
85
|
+
For a missing `CLAUDE.md`, create a thin pointer after `AGENTS.md` exists:
|
|
86
|
+
|
|
87
|
+
```md
|
|
88
|
+
@AGENTS.md
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
For an existing `CLAUDE.md`, preserve all guidance. Add the import only if there
|
|
92
|
+
is no equivalent link and it would not create a reference cycle. If CLAUDE.md is
|
|
93
|
+
already the shared authority, keep it there and let the new AGENTS.md point to
|
|
94
|
+
it; do not create reciprocal imports or duplicate its rules. This shared context
|
|
95
|
+
pointer does not itself install skills or hooks; the exporter must use
|
|
96
|
+
`--harness claude` to place those in Claude discovery paths.
|
|
97
|
+
|
|
98
|
+
Before assigning workers, read an existing `.joycraft/preferences.json`. Reuse
|
|
99
|
+
explicit model, effort, role, concurrency, and verification choices. Then inspect
|
|
100
|
+
the active host for the actual planner, implementer, reviewer, testing, UI, and
|
|
101
|
+
fixture capabilities. Generated defaults and an `unknown` fixture status do not
|
|
102
|
+
prove capability. Until actual isolation is established, use at most four workers
|
|
103
|
+
and one UI worker. Relevant acceptance requires both an inspected rendered UI
|
|
104
|
+
and independent review; if one is unavailable, hold only the claim it would
|
|
105
|
+
support. Ask one short combined question only when a consequential choice remains
|
|
106
|
+
after that inspection.
|
|
107
|
+
|
|
108
|
+
## Kickoff for a new project
|
|
109
|
+
|
|
110
|
+
A bare project has no source outside `docs/`, `README*`, `LICENSE*`, host entry
|
|
111
|
+
files and dotfiles. The founder's context is then only in their head, so on first
|
|
112
|
+
entry offer a kickoff in one line, before any brief or scaffold:
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
node .joycraft/runtime/kickoff.mjs detect --root .
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Offer it only when `offer` is true; on an existing codebase run it only when the
|
|
119
|
+
user asks ("kickoff", "let me tell you about this project", `--requested`). The
|
|
120
|
+
user can decline; then continue as usual.
|
|
121
|
+
|
|
122
|
+
1. `kickoff.mjs start --root .` records what exists, so the check can prove what
|
|
123
|
+
the kickoff changed.
|
|
124
|
+
2. Ask the user to talk freely; voice-to-text dumps are fine. Pipe each message,
|
|
125
|
+
verbatim, to `kickoff.mjs note --root .`. It appends to
|
|
126
|
+
`docs/context/kickoff-notes.md`, so nothing is lost to summarizing.
|
|
127
|
+
3. Decide which topics the dump answered and run
|
|
128
|
+
`kickoff.mjs round --root . --answered <topics>`. Ask only the topics it
|
|
129
|
+
returns (at most 3 a round), each as one short question that would change a
|
|
130
|
+
decision. Pipe each answer to `note`. Repeat until `done`; pass `--enough`
|
|
131
|
+
when the user says enough or wants to start right away.
|
|
132
|
+
4. Write the knowledge homes, following the rules above: `AGENTS.md` (purpose,
|
|
133
|
+
established constraints, stack and commands marked `decided`, `proposed` or
|
|
134
|
+
`not established`, context map), the `CLAUDE.md` pointer, `docs/context/project.md`
|
|
135
|
+
from `.joycraft/templates/project-context.md`, and, when there is a
|
|
136
|
+
decision, `docs/context/decision-log.md` from `templates/decisions.md`, with
|
|
137
|
+
reasons and rejected options. Keep the user's words apart from assumptions.
|
|
138
|
+
A stated stack preference stays `proposed` until the user confirms it.
|
|
139
|
+
5. Run `kickoff.mjs check --root .` and fix every problem it reports: no
|
|
140
|
+
scaffold, manifest or source file; no empty file; no dangling link; every
|
|
141
|
+
existing guidance line kept.
|
|
142
|
+
6. Show `kickoff.mjs summary --root .` and apply the user's corrections.
|
|
143
|
+
7. Then write the first brief for the first outcome, with its "Done when"
|
|
144
|
+
settled. Choosing the stack and scaffolding the app are normal work after
|
|
145
|
+
that: a brief, specs and review.
|
|
146
|
+
|
|
147
|
+
## Review loop tools
|
|
148
|
+
|
|
149
|
+
The review loop needs tools that can show the work: a browser for a web app, a
|
|
150
|
+
simulator or emulator for a mobile app, an HTTP check for an API. On first entry,
|
|
151
|
+
setup and every upgrade, run the read-only plan:
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
node .joycraft/runtime/review-tools.mjs plan --root . --host-tools <observed host tools>
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Pass `--host-tools browser`, `simulator` or `computer-use` only for tools the
|
|
158
|
+
active host actually reports; they can stand in for a missing install. The plan
|
|
159
|
+
detects each package from its manifests, probes versions read-only, and prints
|
|
160
|
+
one table and at most one question. It never installs. When it prints
|
|
161
|
+
`Review loop unchanged.`, ask nothing.
|
|
162
|
+
|
|
163
|
+
Show the table and ask its one question. Only after the user's yes in this
|
|
164
|
+
conversation, run `review-tools.mjs install --root . --yes` (add
|
|
165
|
+
`--tools <ids>` for a per-tool choice); it adds project-local tools with the
|
|
166
|
+
project's own package manager and lockfile. Never run a system install, `sudo`,
|
|
167
|
+
a license acceptance or a sign-in: give the user the printed steps. Then record
|
|
168
|
+
the choice, with `--skip <ids>` for declined tools:
|
|
169
|
+
|
|
170
|
+
```sh
|
|
171
|
+
node .joycraft/runtime/review-tools.mjs record --root . --skip <ids>
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
This writes or replaces only the `## Review loop` section of `AGENTS.md`: each
|
|
175
|
+
tool, the command that starts the app and the command that takes the evidence.
|
|
176
|
+
Worker packets carry that section. For a skipped UI tool, say in one line that
|
|
177
|
+
its UI claims stay `UNVERIFIED`. With no network, the probes still run; offer
|
|
178
|
+
the install later. For a CI-only project, record the CI job as the evidence
|
|
179
|
+
source when the user picks it.
|
|
180
|
+
|
|
181
|
+
## Project-owned worktrees
|
|
182
|
+
|
|
183
|
+
For an observed Git project with a parallel-worker preference, keep bootstrap
|
|
184
|
+
guidance in the existing `docs/context/worktrees.md` home or another mapped
|
|
185
|
+
worktree/bootstrap home. If neither exists, setup may create
|
|
186
|
+
`docs/context/worktrees.md` and add one concise `AGENTS.md` context-map link.
|
|
187
|
+
Preserve an existing equivalent home and its conventions. Do not create a
|
|
188
|
+
worktree document for a non-Git or explicitly serial project, and do not use it
|
|
189
|
+
to turn setup into a questionnaire.
|
|
190
|
+
|
|
191
|
+
Create a worker worktree before setup. Its first action, before editing or UI
|
|
192
|
+
work, is to inspect the manifest, lockfile, and documented commands from inside
|
|
193
|
+
that new worktree. A manifest command or observed lockfile can identify an
|
|
194
|
+
appropriate dependency bootstrap such as `pnpm install --frozen-lockfile`, but
|
|
195
|
+
setup never runs it automatically. Run a dependency command only when the
|
|
196
|
+
current request authorizes it. Do not infer that a package manager, cache, port,
|
|
197
|
+
browser, or other host feature exists because another worktree had one.
|
|
198
|
+
|
|
199
|
+
Use a gitignored file only when its path appears in an explicit project
|
|
200
|
+
allowlist. Begin with an empty allowlist when no project policy exists. The
|
|
201
|
+
project owner may authorize copying an allowed path from the same project's
|
|
202
|
+
coordinator through native `.worktreeinclude` or an explicit manual equivalent.
|
|
203
|
+
Do not copy files by default, including secrets, credentials, browser profiles,
|
|
204
|
+
or host configuration.
|
|
205
|
+
|
|
206
|
+
Keep each worker's `node_modules`, build caches such as `.next`, runtime state,
|
|
207
|
+
development-server port, and browser session separate. An immutable
|
|
208
|
+
package-manager download/store cache may be shared when the project allows it.
|
|
209
|
+
Before concurrent workers use a scarce project resource, follow the project's
|
|
210
|
+
resource-lease convention and record the owner, resource, and release condition.
|
|
211
|
+
If no lease convention or isolated alternative exists, treat the shared resource
|
|
212
|
+
as unavailable until the project owner establishes one.
|
|
213
|
+
|
|
214
|
+
Do not silently write host configuration. Verify that the active host created an
|
|
215
|
+
isolated worktree from the intended base before worker start. In Claude Code,
|
|
216
|
+
the default base is its default branch; use an observed `worktree.baseRef: head`
|
|
217
|
+
policy or verify the captured current commit. A Claude `.worktreeinclude` copies
|
|
218
|
+
only matched gitignored files for native isolated workers; a `WorktreeCreate`
|
|
219
|
+
hook replaces creation and disables that automatic include. `CLAUDE_PROJECT_DIR`
|
|
220
|
+
is the original project while the event working directory is the active
|
|
221
|
+
worktree. On other hosts, use an observed native-isolation capability or an
|
|
222
|
+
explicit manual Git-worktree workflow.
|
|
223
|
+
|
|
224
|
+
## Knowledge grows with the work
|
|
225
|
+
|
|
226
|
+
Reuse existing documents for project facts. If none exists and there are durable
|
|
227
|
+
facts worth retaining, create `docs/context/project.md` with the known purpose,
|
|
228
|
+
users/stakeholders and constraints, their source, and any consequential unknowns.
|
|
229
|
+
Create its parent directory and link it from the context map. Omit empty sections
|
|
230
|
+
and private contact details that are unnecessary for the work. If nothing is
|
|
231
|
+
known yet, create only the instruction files; gather the first useful fact before
|
|
232
|
+
creating a context document. Do not manufacture a directory tree of empty files.
|
|
233
|
+
|
|
234
|
+
Create additional homes only when they have content:
|
|
235
|
+
|
|
236
|
+
| Content | Default home when no existing convention applies |
|
|
237
|
+
|---|---|
|
|
238
|
+
| Durable project knowledge | `docs/context/project.md` or a focused reference linked by the map |
|
|
239
|
+
| Source-backed cross-boundary navigation | The existing context map or a focused reference linked by it |
|
|
240
|
+
| Reusable decision rationale | `docs/context/decision-log.md`, linking to the owning decision |
|
|
241
|
+
| Current feature or mixed change | `docs/features/<slug>/brief.md` |
|
|
242
|
+
| Authorized implementation queue | `docs/features/<slug>/specs/` |
|
|
243
|
+
|
|
244
|
+
Only the context homes are current project knowledge. `docs/features/` is working
|
|
245
|
+
material: a brief or spec there can be out of date until the feature is archived,
|
|
246
|
+
and `docs/archive/` is history. Context retrieval and any project wiki or doc audit
|
|
247
|
+
should treat both as non-authoritative and must not link to them as current
|
|
248
|
+
truth. Joycraft ships no wiki; a project that keeps one keeps it in its own home
|
|
249
|
+
and links it from the context map.
|
|
250
|
+
|
|
251
|
+
The brief retains decision authority under `workflow.md`; the context document
|
|
252
|
+
and decision log must not become competing answer stores. Later accepted facts
|
|
253
|
+
update their existing home. Repeating entry with no new knowledge should make
|
|
254
|
+
no setup edits, create no duplicate links, and ask no repeated questions. There
|
|
255
|
+
is no setup-complete sentinel: useful source content, not a flag, determines
|
|
256
|
+
whether context is available.
|
|
257
|
+
|
|
258
|
+
Ask only for missing human knowledge that materially changes the next action.
|
|
259
|
+
Prefer one short contextual question and continue independent work while it is
|
|
260
|
+
pending. An explicit setup-only request with no product context may end with that
|
|
261
|
+
question or the kickoff offer; do not generate a questionnaire or start building
|
|
262
|
+
an imagined app.
|
|
263
|
+
|
|
264
|
+
Use the project’s existing interaction home for a choice. A question with
|
|
265
|
+
options goes in the decision artifact; only one quick yes/no or an open question
|
|
266
|
+
with no options stays in native chat. Retain a chat answer in the
|
|
267
|
+
owning brief and do not ask it again.
|
|
268
|
+
|
|
269
|
+
## Finish setup and continue
|
|
270
|
+
|
|
271
|
+
Check that newly added links resolve, command claims match their cited source,
|
|
272
|
+
and existing guidance survived the diff. Briefly tell the user which knowledge
|
|
273
|
+
homes were created or extended and any important unknown; then continue the
|
|
274
|
+
original request. Setup does not approve hooks, change credentials, install
|
|
275
|
+
dependencies, or replace the user's workflow. Read `hooks-install.md` only when
|
|
276
|
+
hook activation is part of the requested setup.
|
|
277
|
+
|
|
278
|
+
## Upgrade and agent onboarding
|
|
279
|
+
|
|
280
|
+
Use `node scripts/export.mjs --target <project> --check --upgrade` to preview an
|
|
281
|
+
upgrade. It names only recognized old Joycraft files that would be replaced.
|
|
282
|
+
Applying without `--check` copies those replaced bytes to `.joycraft-backups/`
|
|
283
|
+
first and writes `.joycraft/installation.json`, whose hashes attest to
|
|
284
|
+
the actual installed skill, reference, and runtime bytes. A changed file absent
|
|
285
|
+
from the prior installation manifest remains a conflict; there is no blanket
|
|
286
|
+
force flag. The manifest is dispatch input, not proof that hooks ran or that a
|
|
287
|
+
review was independent.
|
|
288
|
+
|
|
289
|
+
For a new worker, copy the onboarding prompt from the setup preview. It directs
|
|
290
|
+
the worker to read existing project preferences before work, reuse explicit
|
|
291
|
+
model/effort/role/concurrency/verification choices, and inspect the host's
|
|
292
|
+
currently available planner, implementer, reviewer, testing, UI, and fixture
|
|
293
|
+
capabilities rather than claiming a hardcoded model is available. State
|
|
294
|
+
unavailable roles and native-hook checks plainly. Do not alter accepted queues,
|
|
295
|
+
decision state, user guidance, or credentials during setup or upgrade.
|