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.
Files changed (109) hide show
  1. package/README.md +148 -140
  2. package/dist/cli.js +1593 -373
  3. package/dist/cli.js.map +1 -1
  4. package/dist/joycraft-release.json +1 -1
  5. package/package.json +9 -3
  6. package/payload/.agents/skills/joycraft-context/SKILL.md +36 -0
  7. package/payload/.agents/skills/joycraft-decompose/SKILL.md +68 -0
  8. package/payload/.agents/skills/joycraft-entry/SKILL.md +109 -0
  9. package/payload/.agents/skills/joycraft-implement/SKILL.md +118 -0
  10. package/payload/.agents/skills/joycraft-retro/SKILL.md +54 -0
  11. package/payload/.agents/skills/joycraft-retro/agents/openai.yaml +5 -0
  12. package/payload/.agents/skills/joycraft-session-end/SKILL.md +82 -0
  13. package/payload/.agents/skills/joycraft-testing/SKILL.md +60 -0
  14. package/payload/.agents/skills/joycraft-ui-slice/SKILL.md +59 -0
  15. package/payload/.agents/skills/joycraft-ui-slice/scripts/serve.mjs +97 -0
  16. package/payload/.agents/skills/joycraft-verify/SKILL.md +103 -0
  17. package/payload/.claude/agents/joycraft-implementer.md +36 -0
  18. package/payload/.claude/agents/joycraft-reviewer.md +35 -0
  19. package/payload/.joycraft/assets/artifacts/kit.css +102 -0
  20. package/payload/.joycraft/assets/artifacts/kit.js +301 -0
  21. package/payload/.joycraft/assets/artifacts/transports.js +236 -0
  22. package/payload/.joycraft/contracts/types.d.ts +185 -0
  23. package/payload/.joycraft/references/architecture.md +90 -0
  24. package/payload/.joycraft/references/archive.md +211 -0
  25. package/payload/.joycraft/references/artifacts.md +176 -0
  26. package/payload/.joycraft/references/completion.md +109 -0
  27. package/payload/.joycraft/references/context.md +85 -0
  28. package/payload/.joycraft/references/delivery.md +32 -0
  29. package/payload/.joycraft/references/dispatch.md +231 -0
  30. package/payload/.joycraft/references/recurring-failures.md +33 -0
  31. package/payload/.joycraft/references/retro.md +94 -0
  32. package/payload/.joycraft/references/setup.md +295 -0
  33. package/payload/.joycraft/references/testing.md +120 -0
  34. package/payload/.joycraft/references/update.md +44 -0
  35. package/payload/.joycraft/references/workflow.md +113 -0
  36. package/payload/.joycraft/references/worktrees.md +174 -0
  37. package/payload/.joycraft/runtime/archive.mjs +463 -0
  38. package/payload/.joycraft/runtime/artifacts/cli.mjs +61 -0
  39. package/payload/.joycraft/runtime/artifacts/decisions.mjs +214 -0
  40. package/payload/.joycraft/runtime/artifacts/model.mjs +161 -0
  41. package/payload/.joycraft/runtime/artifacts/preferences.mjs +127 -0
  42. package/payload/.joycraft/runtime/artifacts/render.mjs +21 -0
  43. package/payload/.joycraft/runtime/artifacts/server.mjs +40 -0
  44. package/payload/.joycraft/runtime/completion.mjs +300 -0
  45. package/payload/.joycraft/runtime/context/cli.mjs +75 -0
  46. package/payload/.joycraft/runtime/context/index.mjs +29 -0
  47. package/payload/.joycraft/runtime/context/search.mjs +149 -0
  48. package/payload/.joycraft/runtime/coordinator.mjs +169 -0
  49. package/payload/.joycraft/runtime/delivery.mjs +142 -0
  50. package/payload/.joycraft/runtime/dispatch-preflight.mjs +535 -0
  51. package/payload/.joycraft/runtime/dispatch-start.mjs +106 -0
  52. package/payload/.joycraft/runtime/evidence.mjs +137 -0
  53. package/payload/.joycraft/runtime/identity.mjs +486 -0
  54. package/payload/.joycraft/runtime/kickoff.mjs +174 -0
  55. package/payload/.joycraft/runtime/redact.mjs +9 -0
  56. package/payload/.joycraft/runtime/retro.mjs +151 -0
  57. package/payload/.joycraft/runtime/review-tools.json +34 -0
  58. package/payload/.joycraft/runtime/review-tools.mjs +331 -0
  59. package/payload/.joycraft/runtime/scope.mjs +129 -0
  60. package/payload/.joycraft/runtime/status.mjs +96 -0
  61. package/payload/.joycraft/runtime/update-check.mjs +142 -0
  62. package/payload/.joycraft/runtime/worktrees.mjs +201 -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 +77 -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-K4AI6FKB.js +0 -417
  83. package/dist/chunk-K4AI6FKB.js.map +0 -1
  84. package/dist/chunk-KKDKC4FM.js +0 -115
  85. package/dist/chunk-KKDKC4FM.js.map +0 -1
  86. package/dist/chunk-OMFGDJW4.js +0 -97
  87. package/dist/chunk-OMFGDJW4.js.map +0 -1
  88. package/dist/chunk-YLWBDXF4.js +0 -3999
  89. package/dist/chunk-YLWBDXF4.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-O2QC5X57.js +0 -60
  93. package/dist/init-O2QC5X57.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-LYHS4FBH.js +0 -21
  105. package/dist/update-LYHS4FBH.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-GMP6JQ52.js +0 -28
  109. 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.