joycraft 0.7.16 → 1.0.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.
Files changed (109) hide show
  1. package/README.md +137 -156
  2. package/dist/cli.js +1593 -373
  3. package/dist/cli.js.map +1 -1
  4. package/dist/index.d.ts +4 -0
  5. package/dist/index.js +3 -0
  6. package/dist/index.js.map +1 -1
  7. package/dist/joycraft-release.json +1 -1
  8. package/package.json +9 -3
  9. package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
  10. package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
  11. package/payload/.agents/skills/joycraft-entry/SKILL.md +103 -0
  12. package/payload/.agents/skills/joycraft-implement/SKILL.md +106 -0
  13. package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
  14. package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
  15. package/payload/.agents/skills/joycraft-session-end/SKILL.md +78 -0
  16. package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
  17. package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
  18. package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
  19. package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
  20. package/payload/.claude/agents/joycraft-implementer.md +31 -0
  21. package/payload/.claude/agents/joycraft-reviewer.md +30 -0
  22. package/payload/.joycraft/assets/artifacts/kit.css +102 -0
  23. package/payload/.joycraft/assets/artifacts/kit.js +301 -0
  24. package/payload/.joycraft/assets/artifacts/transports.js +236 -0
  25. package/payload/.joycraft/contracts/types.d.ts +185 -0
  26. package/payload/.joycraft/references/architecture.md +90 -0
  27. package/payload/.joycraft/references/archive.md +211 -0
  28. package/payload/.joycraft/references/artifacts.md +176 -0
  29. package/payload/.joycraft/references/completion.md +109 -0
  30. package/payload/.joycraft/references/context.md +80 -0
  31. package/payload/.joycraft/references/delivery.md +32 -0
  32. package/payload/.joycraft/references/dispatch.md +226 -0
  33. package/payload/.joycraft/references/recurring-failures.md +33 -0
  34. package/payload/.joycraft/references/retro.md +94 -0
  35. package/payload/.joycraft/references/setup.md +279 -0
  36. package/payload/.joycraft/references/testing.md +120 -0
  37. package/payload/.joycraft/references/update.md +44 -0
  38. package/payload/.joycraft/references/workflow.md +113 -0
  39. package/payload/.joycraft/references/worktrees.md +148 -0
  40. package/payload/.joycraft/runtime/archive.mjs +463 -0
  41. package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
  42. package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
  43. package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
  44. package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
  45. package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
  46. package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
  47. package/payload/.joycraft/runtime/completion.mjs +300 -0
  48. package/payload/.joycraft/runtime/context/cli.mjs +75 -0
  49. package/payload/.joycraft/runtime/context/index.mjs +29 -0
  50. package/payload/.joycraft/runtime/context/search.mjs +149 -0
  51. package/payload/.joycraft/runtime/delivery.mjs +142 -0
  52. package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
  53. package/payload/.joycraft/runtime/dispatch-start.mjs +98 -0
  54. package/payload/.joycraft/runtime/evidence.mjs +137 -0
  55. package/payload/.joycraft/runtime/identity.mjs +486 -0
  56. package/payload/.joycraft/runtime/kickoff.mjs +174 -0
  57. package/payload/.joycraft/runtime/redact.mjs +9 -0
  58. package/payload/.joycraft/runtime/retro.mjs +151 -0
  59. package/payload/.joycraft/runtime/review-tools.json +34 -0
  60. package/payload/.joycraft/runtime/review-tools.mjs +331 -0
  61. package/payload/.joycraft/runtime/scope.mjs +129 -0
  62. package/payload/.joycraft/runtime/update-check.mjs +142 -0
  63. package/payload/.joycraft/templates/README.md +7 -0
  64. package/payload/.joycraft/templates/artifact.json +33 -0
  65. package/payload/.joycraft/templates/brief.md +35 -0
  66. package/payload/.joycraft/templates/decisions.md +13 -0
  67. package/payload/.joycraft/templates/project-context.md +36 -0
  68. package/payload/.joycraft/templates/queue.json +27 -0
  69. package/payload/.joycraft/templates/spec.md +39 -0
  70. package/payload/.joycraft/templates/ui-slice.html +71 -0
  71. package/payload/PIN +74 -0
  72. package/payload/scripts/export.mjs +301 -0
  73. package/payload/scripts/hook-paths.mjs +35 -0
  74. package/payload/scripts/legacy-hooks.mjs +128 -0
  75. package/payload/scripts/legacy-inventory.json +117 -0
  76. package/dist/chunk-35RQLGKM.js +0 -2167
  77. package/dist/chunk-35RQLGKM.js.map +0 -1
  78. package/dist/chunk-7BPB2IKY.js +0 -255
  79. package/dist/chunk-7BPB2IKY.js.map +0 -1
  80. package/dist/chunk-B73DPYYC.js +0 -377
  81. package/dist/chunk-B73DPYYC.js.map +0 -1
  82. package/dist/chunk-GTP7Z52K.js +0 -3942
  83. package/dist/chunk-GTP7Z52K.js.map +0 -1
  84. package/dist/chunk-K4AI6FKB.js +0 -417
  85. package/dist/chunk-K4AI6FKB.js.map +0 -1
  86. package/dist/chunk-KKDKC4FM.js +0 -115
  87. package/dist/chunk-KKDKC4FM.js.map +0 -1
  88. package/dist/chunk-OMFGDJW4.js +0 -97
  89. package/dist/chunk-OMFGDJW4.js.map +0 -1
  90. package/dist/chunk-Z5JFEGWG.js +0 -563
  91. package/dist/chunk-Z5JFEGWG.js.map +0 -1
  92. package/dist/init-MUB5CC6L.js +0 -60
  93. package/dist/init-MUB5CC6L.js.map +0 -1
  94. package/dist/init-autofix-2DMBO4QN.js +0 -122
  95. package/dist/init-autofix-2DMBO4QN.js.map +0 -1
  96. package/dist/install-manifest-EQHT4474.js +0 -37
  97. package/dist/install-manifest-EQHT4474.js.map +0 -1
  98. package/dist/release-artifact-4TL5L2ZY.js +0 -14
  99. package/dist/release-artifact-4TL5L2ZY.js.map +0 -1
  100. package/dist/release-resolver-P2H46QTU.js +0 -293
  101. package/dist/release-resolver-P2H46QTU.js.map +0 -1
  102. package/dist/telemetry-store-IBO5GRTA.js +0 -14
  103. package/dist/telemetry-store-IBO5GRTA.js.map +0 -1
  104. package/dist/update-LFLQTPUA.js +0 -19
  105. package/dist/update-LFLQTPUA.js.map +0 -1
  106. package/dist/update-check-YT765NE7.js +0 -36
  107. package/dist/update-check-YT765NE7.js.map +0 -1
  108. package/dist/upgrade-L5WERK4X.js +0 -28
  109. package/dist/upgrade-L5WERK4X.js.map +0 -1
@@ -0,0 +1,226 @@
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
+ ```
69
+
70
+ Run each `git` command and each Joycraft runtime call (`node
71
+ .joycraft/runtime/…`, `pnpm joycraft:…`) as its own plain shell
72
+ command: never chain them with `&&`, `;` or `|`, and never use `$(git …)`. To
73
+ pass a root or revision, run `pwd` or `git rev-parse HEAD` alone first and paste
74
+ the literal value. A worktree-isolated host refuses Git inside a compound command.
75
+
76
+ `--native-agent` is present only when the host issued a child identity;
77
+ `--native-host` is optional. Use actual host-issued values only. The start flow
78
+ consumes the existing `--coordinator`, `--parallel`, `--access`,
79
+ `--base-revision`, `--implementer-host`, and `--implementer-agent` options.
80
+ Startup never writes `verification.changeScope`; a spec opts in by recording
81
+ it before the first implementer mutation, and startup preserves it. The separate
82
+ workspace `--base-revision` option keeps its documented topology check.
83
+ Implementer dispatch requires each dependency to be `done`; reviewer dispatch
84
+ does not require the target itself to be done. Unknown roles are rejected.
85
+
86
+ When a reviewer startup exits non-zero or returns `ready: false`, run it once
87
+ more, alone, with a fresh packet path. If it fails again, stop that spec's
88
+ review and tell the user its printed reason; never continue as if the review
89
+ started. Do not retry a `Task startup stopped:` refusal unchanged; fix its cause.
90
+
91
+ The return is `ready: true` for an available valid startup path, including a
92
+ hooks-disabled/manual path. It is not a cryptographic attestation. Missing human
93
+ prompt history for an enforced startup is explicit
94
+ `ready: false`, exit code 2, and `unenforced`; it is not a permission request,
95
+ an invented prompt, or a substitute session ID. Continue discovery and other
96
+ unrelated authorized work, including manual/disabled workflows, but do not
97
+ dispatch the claimed enforced worker. Do not
98
+ select an arbitrary task to make a native relationship appear valid. A child
99
+ binding uses its own root and a real prompt; it may inherit the same native
100
+ parent session authority only when an observed linked coordinator relationship
101
+ is valid. A unique new root session needs its own actual prompt.
102
+
103
+ When the host reports a native agent/invocation ID, also pass
104
+ `--implementer-host <host> --implementer-agent <actual-agent-id>`. For a root
105
+ session, `--implementer-host <host>` may be used without a child agent ID.
106
+ Record the returned reviewer actor after launch; never invent it before dispatch.
107
+ Claude's plain Agent worker can share the parent session while having its own
108
+ native agent ID. It can review in the same checkout when a separate context is
109
+ observed and the reviewed inputs stay fixed. A worktree alone proves neither
110
+ independent context nor current evidence. Reports carry both actor records or
111
+ neither; see `completion.md` for the legacy fallback.
112
+
113
+ The setup/export flow writes `.joycraft/installation.json` with the
114
+ actual exported file paths and SHA-256 values. Give the helper an explicit
115
+ absolute `workerRoot` and an explicit pinned expected manifest path; it compares
116
+ role/shared files against both. A worker's own manifest cannot attest that an
117
+ old, internally consistent installation is the intended export.
118
+ Include the reviewer skill, every reference it needs, and every runtime module
119
+ it needs in `delivery.roles`. A matching path is insufficient when the bytes
120
+ are from an older install.
121
+
122
+ The low-level `preflightDispatch`/`nativeDispatch` API and `prepare` command
123
+ remain legacy/manual binding tools. They are not the normal path for new
124
+ startup. Calls that omit `expectedManifestPath` validate only the worker's own
125
+ bundle and do not attest the intended release. Do not claim release delivery
126
+ from a legacy self-attested call.
127
+
128
+ ## Call the portable dispatch API
129
+
130
+ Call the portable API from a Codex, Claude, Pi, OMP, or Copilot adapter. Normal
131
+ native startup calls `startDispatch(options, nativeEvent)` so the runtime can
132
+ validate the observed session, agent relationship, and prompt authority before
133
+ it returns a packet:
134
+
135
+ ```js
136
+ import { startDispatch } from './.joycraft/runtime/dispatch-start.mjs';
137
+
138
+ const started = await startDispatch(options, nativeEvent);
139
+ ```
140
+
141
+ Use the returned packet only when `started.ready` is true. `nativeEvent` is
142
+ observed host data, not caller-filled identity or authority. The older
143
+ `nativeDispatch(request, native)` API is retained for portable/manual callers;
144
+ it does not make an unbound startup valid.
145
+
146
+ `request` is schema-v1 and contains `workerRoot`, optional `manifestPath`,
147
+ `delivery`, and `claims`. `delivery.sourceView` has hashed `brief`, `spec`,
148
+ `queue`, `inputs`, exact anchored `decisions`, and any `decisionLimitations`.
149
+ A decision record is raw authority, not a review instruction; do not put an
150
+ expected verdict, conclusion, or implementer reasoning in another delivery
151
+ field. A requirement input can use `scope.decisionIds` to select brief
152
+ decisions. Without a selector, the packet conservatively carries every current
153
+ answered decision from that brief. The packet retains its whole-brief reference
154
+ so workers can read each decision in context. Its inputs include any current
155
+ coupled counterpart required to review the requested behavior.
156
+
157
+ ## Bind the hook source view
158
+
159
+ Dispatch-start prepares and binds its hash-bound `hookSourceView` with actual
160
+ native IDs. The lower-level manual bind command remains only for an explicit
161
+ non-native boundary. It uses the actual native session ID reported at startup,
162
+ never a generated UUID:
163
+
164
+ ```sh
165
+ node .joycraft/runtime/hooks/cli.mjs bind-source \
166
+ --session <actual-native-session-id> --packet <project-relative-packet.json>
167
+ ```
168
+
169
+ Bind a known parent session before launching children when the host exposes
170
+ parent inheritance. Otherwise, bind the child after it reports its own actual
171
+ session ID. For children sharing a parent session but working on different
172
+ specs, add `--agent <actual-native-child-id>` when binding each child. Its task
173
+ view remains separate while human prompts still inherit from the parent.
174
+ Rebind after the brief changes. The hook view currently receives only
175
+ hash-checked brief and decision pointers; the worker packet retains the exact
176
+ decision records. An unknown ID leaves the dependent
177
+ Jev check advisory and unverified; it does not permit a substitute ID. The view
178
+ makes selected saved answers available to Jev, but never grants permission or
179
+ an expected review outcome.
180
+
181
+ ## Validate capabilities before dispatch
182
+
183
+ `claims.capabilities` must include `filesystem:read`,
184
+ `filesystem:write-report`, and each role's `requiredCapabilities`; its claimed
185
+ report destination must be project-relative and writable in the worker root.
186
+ Pass only capabilities the host actually observed. A reviewer additionally needs
187
+ `agent:separate-context`; an implementer does not. For work that will create new
188
+ files, prepare the implementer packet before those files exist; prepare the
189
+ reviewer packet after implementation from the current files. Unknown capability
190
+ is a hold on the dependent dispatch or acceptance, never a reason to invent a
191
+ claim.
192
+
193
+ ## Check the reviewer report
194
+
195
+ After the independent reviewer returns a report, run:
196
+
197
+ ```sh
198
+ node .joycraft/runtime/dispatch-preflight.mjs check-report \
199
+ --worker-root <absolute-worker-root> --queue <queue-path> --spec <id> --report <report-path>
200
+ ```
201
+
202
+ This uses completion's existing report and evidence validators, but it cannot
203
+ move a spec to `done`. Send a rejected report back to the same reviewer for
204
+ correction. Missing observations remain missing; do not manufacture them.
205
+ Only `completion.mjs finalize-review` can accept a PASS report (`complete` is
206
+ the strict compatibility alias). Preserve FAIL or
207
+ UNVERIFIED reports; a trusted owner's explicit acceptance of their current
208
+ findings uses the separate `accept-owner` path in
209
+ [completion guidance](completion.md#explicit-owner-acceptance-of-current-findings).
210
+
211
+ ## Change scope and review startup
212
+
213
+ Opt into scope checks per spec with
214
+ `verification.changeScope: { baseRevision, exclusions? }`. The base is a full
215
+ available commit SHA captured before the first implementer mutation. The runtime
216
+ infers relevant paths from verification inputs, the brief, spec, queue, and
217
+ criteria. Review startup does not require a scope; when one is recorded, never
218
+ substitute current `HEAD` for its base. If unrelated files changed after the base, give each an
219
+ exact `exclusions: [{ path, reason }]` disposition. Do not add the whole branch
220
+ or broad directories just to silence a scope failure.
221
+
222
+ Inputs normally describe files that must be present. A deliberate deletion
223
+ requires `state: 'absent'` on an explicit non-requirement input. A rename needs
224
+ the new present input and the prior path as an absent input. Requirement inputs
225
+ cannot be absent. This keeps absence an explicit claim instead of an accidental
226
+ 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,279 @@
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
+
61
+ Do not copy prototype-maintainer rules or fill it with generic coding advice.
62
+ Link detail rather than duplicating it. Do not encode a tentative product idea
63
+ as a permanent boundary. Keep current feature intent in its brief.
64
+
65
+ If `AGENTS.md` already exists, preserve its content and add only missing facts,
66
+ useful context pointers and the update-check line above with a targeted edit. Reuse an existing context map
67
+ rather than adding another. Read linked content before deciding it is missing.
68
+ When its map names a project-context home, use that exact project-relative home;
69
+ use `docs/context/project.md` only when no context home exists. Do not link a
70
+ context document that setup did not create or find. This keeps a bare project
71
+ free of dangling links.
72
+ Do not reformat, delete, or replace user instructions. Surface consequential
73
+ contradictions rather than silently resolving them. Respect symlinks and managed
74
+ files; do not replace them or write outside the project through them.
75
+
76
+ For a missing `CLAUDE.md`, create a thin pointer after `AGENTS.md` exists:
77
+
78
+ ```md
79
+ @AGENTS.md
80
+ ```
81
+
82
+ For an existing `CLAUDE.md`, preserve all guidance. Add the import only if there
83
+ is no equivalent link and it would not create a reference cycle. If CLAUDE.md is
84
+ already the shared authority, keep it there and let the new AGENTS.md point to
85
+ it; do not create reciprocal imports or duplicate its rules. This shared context
86
+ pointer does not itself install skills or hooks; the exporter must use
87
+ `--harness claude` to place those in Claude discovery paths.
88
+
89
+ Before assigning workers, read an existing `.joycraft/preferences.json`. Reuse
90
+ explicit model, effort, role, concurrency, and verification choices. Then inspect
91
+ the active host for the actual planner, implementer, reviewer, testing, UI, and
92
+ fixture capabilities. Generated defaults and an `unknown` fixture status do not
93
+ prove capability. Until actual isolation is established, use at most four workers
94
+ and one UI worker. Relevant acceptance requires both an inspected rendered UI
95
+ and independent review; if one is unavailable, hold only the claim it would
96
+ support. Ask one short combined question only when a consequential choice remains
97
+ after that inspection.
98
+
99
+ ## Kickoff for a new project
100
+
101
+ A bare project has no source outside `docs/`, `README*`, `LICENSE*`, host entry
102
+ files and dotfiles. The founder's context is then only in their head, so on first
103
+ entry offer a kickoff in one line, before any brief or scaffold:
104
+
105
+ ```sh
106
+ node .joycraft/runtime/kickoff.mjs detect --root .
107
+ ```
108
+
109
+ Offer it only when `offer` is true; on an existing codebase run it only when the
110
+ user asks ("kickoff", "let me tell you about this project", `--requested`). The
111
+ user can decline; then continue as usual.
112
+
113
+ 1. `kickoff.mjs start --root .` records what exists, so the check can prove what
114
+ the kickoff changed.
115
+ 2. Ask the user to talk freely; voice-to-text dumps are fine. Pipe each message,
116
+ verbatim, to `kickoff.mjs note --root .`. It appends to
117
+ `docs/context/kickoff-notes.md`, so nothing is lost to summarizing.
118
+ 3. Decide which topics the dump answered and run
119
+ `kickoff.mjs round --root . --answered <topics>`. Ask only the topics it
120
+ returns (at most 3 a round), each as one short question that would change a
121
+ decision. Pipe each answer to `note`. Repeat until `done`; pass `--enough`
122
+ when the user says enough or wants to start right away.
123
+ 4. Write the knowledge homes, following the rules above: `AGENTS.md` (purpose,
124
+ established constraints, stack and commands marked `decided`, `proposed` or
125
+ `not established`, context map), the `CLAUDE.md` pointer, `docs/context/project.md`
126
+ from `.joycraft/templates/project-context.md`, and, when there is a
127
+ decision, `docs/context/decision-log.md` from `templates/decisions.md`, with
128
+ reasons and rejected options. Keep the user's words apart from assumptions.
129
+ A stated stack preference stays `proposed` until the user confirms it.
130
+ 5. Run `kickoff.mjs check --root .` and fix every problem it reports: no
131
+ scaffold, manifest or source file; no empty file; no dangling link; every
132
+ existing guidance line kept.
133
+ 6. Show `kickoff.mjs summary --root .` and apply the user's corrections.
134
+ 7. Then write the first brief for the first outcome, with its "Done when"
135
+ settled. Choosing the stack and scaffolding the app are normal work after
136
+ that: a brief, specs and review.
137
+
138
+ ## Review loop tools
139
+
140
+ The review loop needs tools that can show the work: a browser for a web app, a
141
+ simulator or emulator for a mobile app, an HTTP check for an API. On first entry,
142
+ setup and every upgrade, run the read-only plan:
143
+
144
+ ```sh
145
+ node .joycraft/runtime/review-tools.mjs plan --root . --host-tools <observed host tools>
146
+ ```
147
+
148
+ Pass `--host-tools browser`, `simulator` or `computer-use` only for tools the
149
+ active host actually reports; they can stand in for a missing install. The plan
150
+ detects each package from its manifests, probes versions read-only, and prints
151
+ one table and at most one question. It never installs. When it prints
152
+ `Review loop unchanged.`, ask nothing.
153
+
154
+ Show the table and ask its one question. Only after the user's yes in this
155
+ conversation, run `review-tools.mjs install --root . --yes` (add
156
+ `--tools <ids>` for a per-tool choice); it adds project-local tools with the
157
+ project's own package manager and lockfile. Never run a system install, `sudo`,
158
+ a license acceptance or a sign-in: give the user the printed steps. Then record
159
+ the choice, with `--skip <ids>` for declined tools:
160
+
161
+ ```sh
162
+ node .joycraft/runtime/review-tools.mjs record --root . --skip <ids>
163
+ ```
164
+
165
+ This writes or replaces only the `## Review loop` section of `AGENTS.md`: each
166
+ tool, the command that starts the app and the command that takes the evidence.
167
+ Worker packets carry that section. For a skipped UI tool, say in one line that
168
+ its UI claims stay `UNVERIFIED`. With no network, the probes still run; offer
169
+ the install later. For a CI-only project, record the CI job as the evidence
170
+ source when the user picks it.
171
+
172
+ ## Project-owned worktrees
173
+
174
+ For an observed Git project with a parallel-worker preference, keep bootstrap
175
+ guidance in the existing `docs/context/worktrees.md` home or another mapped
176
+ worktree/bootstrap home. If neither exists, setup may create
177
+ `docs/context/worktrees.md` and add one concise `AGENTS.md` context-map link.
178
+ Preserve an existing equivalent home and its conventions. Do not create a
179
+ worktree document for a non-Git or explicitly serial project, and do not use it
180
+ to turn setup into a questionnaire.
181
+
182
+ Create a worker worktree before setup. Its first action, before editing or UI
183
+ work, is to inspect the manifest, lockfile, and documented commands from inside
184
+ that new worktree. A manifest command or observed lockfile can identify an
185
+ appropriate dependency bootstrap such as `pnpm install --frozen-lockfile`, but
186
+ setup never runs it automatically. Run a dependency command only when the
187
+ current request authorizes it. Do not infer that a package manager, cache, port,
188
+ browser, or other host feature exists because another worktree had one.
189
+
190
+ Use a gitignored file only when its path appears in an explicit project
191
+ allowlist. Begin with an empty allowlist when no project policy exists. The
192
+ project owner may authorize copying an allowed path from the same project's
193
+ coordinator through native `.worktreeinclude` or an explicit manual equivalent.
194
+ Do not copy files by default, including secrets, credentials, browser profiles,
195
+ or host configuration.
196
+
197
+ Keep each worker's `node_modules`, build caches such as `.next`, runtime state,
198
+ development-server port, and browser session separate. An immutable
199
+ package-manager download/store cache may be shared when the project allows it.
200
+ Before concurrent workers use a scarce project resource, follow the project's
201
+ resource-lease convention and record the owner, resource, and release condition.
202
+ If no lease convention or isolated alternative exists, treat the shared resource
203
+ as unavailable until the project owner establishes one.
204
+
205
+ Do not silently write host configuration. Verify that the active host created an
206
+ isolated worktree from the intended base before worker start. In Claude Code,
207
+ the default base is its default branch; use an observed `worktree.baseRef: head`
208
+ policy or verify the captured current commit. A Claude `.worktreeinclude` copies
209
+ only matched gitignored files for native isolated workers; a `WorktreeCreate`
210
+ hook replaces creation and disables that automatic include. `CLAUDE_PROJECT_DIR`
211
+ is the original project while the event working directory is the active
212
+ worktree. On other hosts, use an observed native-isolation capability or an
213
+ explicit manual Git-worktree workflow.
214
+
215
+ ## Knowledge grows with the work
216
+
217
+ Reuse existing documents for project facts. If none exists and there are durable
218
+ facts worth retaining, create `docs/context/project.md` with the known purpose,
219
+ users/stakeholders and constraints, their source, and any consequential unknowns.
220
+ Create its parent directory and link it from the context map. Omit empty sections
221
+ and private contact details that are unnecessary for the work. If nothing is
222
+ known yet, create only the instruction files; gather the first useful fact before
223
+ creating a context document. Do not manufacture a directory tree of empty files.
224
+
225
+ Create additional homes only when they have content:
226
+
227
+ | Content | Default home when no existing convention applies |
228
+ |---|---|
229
+ | Durable project knowledge | `docs/context/project.md` or a focused reference linked by the map |
230
+ | Source-backed cross-boundary navigation | The existing context map or a focused reference linked by it |
231
+ | Reusable decision rationale | `docs/context/decision-log.md`, linking to the owning decision |
232
+ | Current feature or mixed change | `docs/features/<slug>/brief.md` |
233
+ | Authorized implementation queue | `docs/features/<slug>/specs/` |
234
+
235
+ The brief retains decision authority under `workflow.md`; the context document
236
+ and decision log must not become competing answer stores. Later accepted facts
237
+ update their existing home. Repeating entry with no new knowledge should make
238
+ no setup edits, create no duplicate links, and ask no repeated questions. There
239
+ is no setup-complete sentinel: useful source content, not a flag, determines
240
+ whether context is available.
241
+
242
+ Ask only for missing human knowledge that materially changes the next action.
243
+ Prefer one short contextual question and continue independent work while it is
244
+ pending. An explicit setup-only request with no product context may end with that
245
+ question or the kickoff offer; do not generate a questionnaire or start building
246
+ an imagined app.
247
+
248
+ Use the project’s existing interaction home for a choice. A question with
249
+ options goes in the decision artifact; only one quick yes/no or an open question
250
+ with no options stays in native chat. Retain a chat answer in the
251
+ owning brief and do not ask it again.
252
+
253
+ ## Finish setup and continue
254
+
255
+ Check that newly added links resolve, command claims match their cited source,
256
+ and existing guidance survived the diff. Briefly tell the user which knowledge
257
+ homes were created or extended and any important unknown; then continue the
258
+ original request. Setup does not approve hooks, change credentials, install
259
+ dependencies, or replace the user's workflow. Read `hooks-install.md` only when
260
+ hook activation is part of the requested setup.
261
+
262
+ ## Upgrade and agent onboarding
263
+
264
+ Use `node scripts/export.mjs --target <project> --check --upgrade` to preview an
265
+ upgrade. It names only recognized old Joycraft files that would be replaced.
266
+ Applying without `--check` copies those replaced bytes to `.joycraft-backups/`
267
+ first and writes `.joycraft/installation.json`, whose hashes attest to
268
+ the actual installed skill, reference, and runtime bytes. A changed file absent
269
+ from the prior installation manifest remains a conflict; there is no blanket
270
+ force flag. The manifest is dispatch input, not proof that hooks ran or that a
271
+ review was independent.
272
+
273
+ For a new worker, copy the onboarding prompt from the setup preview. It directs
274
+ the worker to read existing project preferences before work, reuse explicit
275
+ model/effort/role/concurrency/verification choices, and inspect the host's
276
+ currently available planner, implementer, reviewer, testing, UI, and fixture
277
+ capabilities rather than claiming a hardcoded model is available. State
278
+ unavailable roles and native-hook checks plainly. Do not alter accepted queues,
279
+ decision state, user guidance, or credentials during setup or upgrade.