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,103 @@
1
+ ---
2
+ name: joycraft-entry
3
+ description: Set up missing project guidance on first use, then turn a repair, feature, or mixed request into a context-backed brief and the next useful action.
4
+ compatibility: Setup and routing helpers require Node.js 22+ and the installed .joycraft runtime only when used; ordinary brief and context navigation has no project-stack prerequisite.
5
+ ---
6
+
7
+ Run `node .joycraft/runtime/update-check.mjs check` first, once per session. If it
8
+ prints nothing, say nothing. If it prints JSON, follow
9
+ [updates](../../../.joycraft/references/update.md).
10
+
11
+ Read existing project instructions first. During an upgrade, inspect the installed
12
+ manifest’s `legacyConflicts` and reconcile competing old skill discovery before
13
+ using routing advice; preserved custom content is not a completed migration. On first use, explicit setup/init, or
14
+ when shared guidance or its context pointers are missing, follow
15
+ [first-use setup](../../../.joycraft/references/setup.md). Establish the missing knowledge homes
16
+ from the current request and repository facts, preserving existing guidance.
17
+ On a bare project, offer the
18
+ [kickoff](../../../.joycraft/references/setup.md#kickoff-for-a-new-project)
19
+ in one line before any brief or scaffold, and run it when the user asks for it on
20
+ any project. On first entry, setup and upgrade, also run the review-loop plan in
21
+ [review loop tools](../../../.joycraft/references/setup.md#review-loop-tools);
22
+ install nothing without the user's yes.
23
+ Continue the user's work after setup; setup alone does not require a feature
24
+ brief, spec queue, app scaffold, or a new interview. A read-only request stays
25
+ read-only; report missing setup without writing it.
26
+
27
+ Before assigning work, read `.joycraft/preferences.json` when it exists. Reuse
28
+ its explicit model, effort, role, concurrency, and verification choices, then
29
+ inspect the active host's actual planner, implementer, reviewer, testing, UI,
30
+ and fixture capabilities. Preferences and fixtures marked unknown are not proof
31
+ of availability. Until isolation is observed, use no more than four workers and
32
+ one UI worker. Require a relevant inspected render and independent review for
33
+ acceptance; if either cannot run, hold only that affected acceptance claim.
34
+
35
+ Read the project's boundaries and context map, then only the relevant
36
+ decision, reference and implementation files. Reuse existing briefs and answers;
37
+ missing context permits explicit assumptions. Surface contradictions that change
38
+ scope or a consequential choice.
39
+
40
+ When an unclear state, data, or responsibility boundary could change the work,
41
+ do focused discovery before splitting it: inspect the actual owner and its
42
+ callers, readers, writers, or other coupled counterpart. Ranking can point to
43
+ sources, but does not replace that trace. Keep settled product behavior in the
44
+ brief; record only durable, source-backed navigation in the project's existing
45
+ context homes. Read `.joycraft/references/architecture.md` for this
46
+ conditional check. Do not create an architecture stage, certification, or
47
+ separate map for a simple local edit.
48
+
49
+ Keep the user's goals together. A request to repair saving and add a collection
50
+ view keeps both goals in one brief, or links their existing briefs. Do not force
51
+ the user to choose “bugfix or feature.” Separate work you can resolve by inspecting
52
+ code from decisions that need the user's intent. Continue understood authorized
53
+ work while a disjoint choice is pending.
54
+
55
+ Use `.joycraft/templates/brief.md` when no suitable brief exists. Its
56
+ frontmatter `decisions:` owns current decision state; preserve the project's
57
+ context map and existing knowledge homes. See
58
+ `.joycraft/references/workflow.md` for decision and queue rules.
59
+ Settle each goal's "Done when" with the user while writing the brief; if it
60
+ cannot be filled yet, record it as an open decision so dependent specs wait for
61
+ the answer instead of a reviewer discovering it.
62
+
63
+ **Ask answerable questions in an artifact.** When the user must choose between
64
+ options, record each choice as a brief decision and render the open decisions
65
+ with the decision artifact (`.joycraft/references/artifacts.md`). Do not list
66
+ option questions in chat: the artifact shows each question with its context and
67
+ options, and saves the answers to the brief. Plain chat is only for one quick
68
+ yes/no or an open question with no options. If you already asked option
69
+ questions in chat and they are unanswered, move them to an artifact now.
70
+
71
+ For a request to keep an artifact theme or colors from now on, record
72
+ `artifacts.theme` or `artifacts.colors` in that project's
73
+ `.joycraft/preferences.json` with the artifact CLI and add one link to the
74
+ existing context map when absent. Do not make it global or repeat the values in
75
+ the map. A one-off artifact theme stays on the render command.
76
+
77
+ Choose the next action from what is missing: inspect code for facts, use
78
+ `joycraft-ui-slice` for a consequential visual uncertainty, or use
79
+ `joycraft-decompose` for understood authorized work. Ask a short contextual
80
+ question only when its consequential answer is absent; typically one choice is
81
+ enough. Do not ask again for settled intent or routine implementation refinements.
82
+ For a small authorized tooling repair or content operation, use the project's
83
+ existing direct path when it fits the request. Do not turn routine data entry
84
+ into a code-spec factory or create per-record plans when an approved batch tool
85
+ already owns the operation. Preserve its validation, approval and readback rules.
86
+
87
+ When a native hook adds routing advice to the prompt, use it to select relevant
88
+ skills. Keep all expressed goals even when a classifier misses a signal. Do not
89
+ repeat a live routing call when the hook already provided current advice.
90
+ Routing does not approve scope, answer a decision, or establish evidence.
91
+
92
+ Use `joycraft-context` when you need to find relevant project files beyond the
93
+ context map. Its deterministic search (and optional ranking) provides pointers; read the
94
+ selected source before relying on it. For hook status, blocked edits or provider
95
+ failures, read `.joycraft/references/hooks-runtime.md`. Treat unavailable
96
+ checks as unavailable, never as approval. For a denial, compare its cited scope
97
+ with the current task and the actual human question/answer. Repair missing
98
+ source delivery once through the documented binding flow, then resume understood
99
+ authorized work. Do not ask for the same permission again, move a chat answer to
100
+ a different document as an enforcement workaround, weaken a gate, or wrap a
101
+ denied command. Ask the host for the legitimate correction when needed.
102
+ If native hooks are absent and routing is materially uncertain, the explicit adapter in `.joycraft/references/routing.md` remains available.
103
+ When requested setup includes native hooks, use [Codex hook installation](../../../.joycraft/references/hooks-install.md) or [Claude Code hook installation](../../../.joycraft/references/hooks-claude.md) for the active host. Installation and project setup do not establish host trust or execution.
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: joycraft-implement
3
+ description: Implement authorized Joycraft feature specs from a project queue, preserving dependencies and sending finished work to independent verification.
4
+ compatibility: Guarded review and completion require Node.js 22+, the installed .joycraft runtime, and Git; ordinary implementation follows the project's own stack.
5
+ ---
6
+
7
+ # Joycraft Implement
8
+
9
+ Use this skill to carry out already-authorized specs in `docs/features/<slug>/specs/.joycraft-spec-queue.json`.
10
+
11
+ Read the project's boundaries, the parent brief, the selected spec, and its declared verification inputs before changing code. Reuse current decisions and context; record assumptions when context is missing. Stop for a scope-changing contradiction or an unresolved consequential decision. Do not require a new interview for settled work.
12
+
13
+ For a change across state, data or producer/consumer boundaries, inspect the
14
+ actual counterpart code and relevant owning decisions/context when available.
15
+ Missing context permits explicit assumptions and progress on understood scope;
16
+ it does not require an architecture document. Add discovered material sources
17
+ and relevant existing decision/context paths to exact verification inputs before
18
+ review, reporting unresolved coverage. See
19
+ [focused discovery](../../../.joycraft/references/architecture.md)
20
+ when the boundary is unclear; a local repair needs no architecture review.
21
+
22
+ Work the ready authorized queue autonomously. A `todo` spec is ready when every
23
+ dependency is `done`; a merge or `in-review` status is insufficient. Dispatch
24
+ preflight checks this against the actual queue. Preserve the limits of an
25
+ explicitly owner-accepted dependency. Choose independent ready work while an
26
+ affected branch waits for review, environment repair or a recorded owner hold.
27
+ Keep unfinished independent work visible.
28
+
29
+ For normal native execution, the host launches the selected worker first. The
30
+ child bootstraps from its actual root, then runs `dispatch-start.mjs --role
31
+ implementer` with its actual native identity before any tasked edit or mutation.
32
+ The coordinator runs that start itself only when it is the implementer actor.
33
+ Use the returned packet only when `ready` is true. A hooks-disabled/manual
34
+ workflow can be ready; unavailable hook status is not a new permission gate for
35
+ all work. When startup returns unenforced, hold only that claimed enforced task,
36
+ report why, and continue unrelated authorized or manual/disabled workflow.
37
+
38
+ If existing independent reports reveal a possible recurring failure, follow [recurring failure guidance](../../../.joycraft/references/recurring-failures.md) before carrying it forward: inspect the current scoped sources and actual counterpart path or journey, then provide any proposed lesson as exact inputs through the existing dispatch flow. A verified repair may establish its local project fact; a broader method benefit remains pending later reuse.
39
+
40
+ For a spec marked `execution.parallel: true`, use a separate linked worktree for
41
+ each concurrent mutator, including its build/cache state. Its first action is
42
+ the documented project bootstrap, before edits, stateful runtime work, or packet
43
+ preparation. Dispatch from its actual root. Read [worker isolation](../../../.joycraft/references/worktrees.md)
44
+ when parallel work, integration, cleanup, or resource capacity is in play. If
45
+ isolation cannot be obtained, replan the affected wave and set the current
46
+ queue entry's `execution.parallel` to `false` before dispatch, recording why;
47
+ then run it serially. Otherwise leave it unstarted.
48
+
49
+ Implement the spec and run meaningful checks and any relevant rendered inspection during implementation. Do not defer ordinary checks to the batch boundary. Run each test command once in single-run mode with `CI=1` and a 300000 ms timeout; follow [running tests](../../../.joycraft/references/testing.md#running-tests) when one times out. Write one focused test per acceptance `Check:`, from the spec rather than the code; if a criterion or test looks wrong, report a spec gap instead of editing it to pass. When the implementation is finished, update both the queue entry and the spec's top-level frontmatter `status:` to `in-review` together. A passing test suite, commit, or empty ready set does not accept the work.
50
+
51
+ Honor the queue's commit mode. In `batch`, commit and review the independent ready
52
+ wave at its boundary before advancing its dependents; do not wait for an entire
53
+ dependency chain to be implemented. In `checkpoint`, commit each finished spec,
54
+ integrate it, and review the integrated bytes before continuing. In `isolated`,
55
+ also give each implementation spec an actual fresh agent context
56
+ (`fork_turns: "none"` when spawning; in Claude Code the `joycraft-implementer`
57
+ agent type when installed) with its raw requirements and project context. A worktree is operational isolation; it does not prove review independence.
58
+
59
+ At the review boundary, invoke `$joycraft-verify`. Use the single native
60
+ `dispatch-start.mjs --role reviewer` flow to snapshot the current subject,
61
+ verify worker delivery, prepare and bind the bounded packet. Supply only
62
+ observed host capabilities and raw current sources, including relevant coupled
63
+ sources discovered during implementation; never a desired verdict or reasoning.
64
+ It needs actual host session/agent identity and available current authority
65
+ as described in [dispatch guidance](../../../.joycraft/references/dispatch.md).
66
+ Write its packet or subject beneath a confirmed Git-ignored project-local
67
+ directory, not among reviewed sources.
68
+ If it returns unenforced, or a separate review context/capability is unavailable,
69
+ leave the spec `in-review`; do not invent an ID or prompt to continue. This holds
70
+ the claimed review, not unrelated authorized or hooks-disabled/manual work.
71
+
72
+ Only the guarded completion path can move an `in-review` spec to `done`. Use its manual snapshot/complete commands only at an explicit non-native boundary; read [completion guidance](../../../.joycraft/references/completion.md) before doing so.
73
+
74
+ When a current independent review is `FAIL` or `UNVERIFIED`, first fix
75
+ straightforward failures within the existing authorization and obtain a fresh
76
+ review. A spec gets at most three reviews; state the real round number in each
77
+ fix brief. Settled briefs and checked specs should make this rare. If a second FAIL
78
+ on the same criterion or a "decision needed" finding still occurs, send no
79
+ further fix and never amend acceptance yourself: note it under `## Decision
80
+ needed` in the spec, leave it `in-review`, and continue independent ready work. An owner can explicitly accept the
81
+ current findings and their stated limits through `accept-owner`; that is a
82
+ bounded exception, not a PASS or verified result. Do not ask merely because a
83
+ review failed. Ask only when an explicit override is needed to proceed and a
84
+ trusted human acceptance of this spec and these current findings is missing.
85
+ Make one short summary and focused choice, then persist the owner's actual
86
+ instruction and nonempty limits in the decision record. A general
87
+ "continue" or "go," another agent's direction, or authorization to add this
88
+ capability is not an acceptance of a spec. If the owner already explicitly
89
+ accepted, proceed without reconfirming. Work that depends on the result may
90
+ continue only within those accepted limits; it does not gain deployment,
91
+ security, or other blanket authority. Report it as `done, owner-accepted with
92
+ <limits>`, never as PASS or verified.
93
+
94
+ For authorized Git delivery, follow the project's verification and independent
95
+ review policy on the final integrated revision before pushing it. Use
96
+ [checked delivery](../../../.joycraft/references/delivery.md) for a
97
+ fail-stop, revision-bound verifier/push when useful. A failed verifier stops
98
+ delivery; never push with a promise to verify later or hide failure in a shell
99
+ chain. This command cannot replace independent review or authorize a push.
100
+
101
+ After review and completion, continue with the next ready authorized spec.
102
+ Report blockers and the next action first, then measured progress. Tell the user
103
+ when a run stops or planned work is omitted, with the reason and retained state;
104
+ explain any needed external setting and its effect. Give concise stage updates
105
+ during long work instead of only announcing passes. Never describe unavailable,
106
+ failed, or uninspected evidence as passing.
@@ -0,0 +1,54 @@
1
+ ---
2
+ name: joycraft-retro
3
+ description: Inspect a requested coding session for hidden friction and propose source-linked improvements to tools, checks and project guidance.
4
+ disable-model-invocation: true
5
+ compatibility: Optional JSONL evidence preparation requires Node.js 22+ and the installed .joycraft runtime; direct review of available session records needs no provider or helper.
6
+ ---
7
+
8
+ # Joycraft Retro
9
+
10
+ Use when the user requests a retrospective. Review their selected session, or
11
+ the current session when none is specified. A successful final result can conceal
12
+ expensive searches, retries, missing inputs and workarounds. This is an optional
13
+ diagnostic of how the work happened, separate from code acceptance and session
14
+ closure.
15
+
16
+ Read the session's actual record and relevant current project sources. Keep the
17
+ user's instructions, tool activity and agent claims distinct. Follow links to
18
+ necessary worker records or receipts within the requested scope; disclose missing
19
+ continuations, unsupported records and uncertain chronology. A final summary,
20
+ input hash or passing test alone does not establish what the agent understood.
21
+ For native logs, use [evidence preparation](../../../.joycraft/references/retro.md#prepare-native-session-evidence)
22
+ when it saves repeated parsing. Use explicit sources or the host's current
23
+ session, rather than searching unrelated projects or global private settings.
24
+
25
+ Find observed friction, including navigation, missing source delivery, broken or
26
+ unwired checks, overlooked reviewer judgment, expensive tools, instruction sprawl
27
+ and unavailable information. Inspect existing tooling before proposing another
28
+ check. Connect each candidate to an exact session moment and the current owning
29
+ source; distinguish an agent mistake from a stale decision, missing delivery,
30
+ missing capability or an incorrect tool. Frustration is a lead, not proof of the
31
+ cause. A quiet costly issue can outrank a loud cheap one.
32
+
33
+ Prefer the smallest supported remedy: repair a tool or check, improve a scoped
34
+ context pointer, or clarify reviewer guidance. Mechanically detectable failures
35
+ belong in deterministic checks when those checks earn their maintenance cost.
36
+ Keep implementation-critical guidance available to implementers. Retain product
37
+ choices in their existing brief authority. Removing ineffective instructions is
38
+ a candidate for a behavioral comparison, not a conclusion from one smooth run.
39
+
40
+ Present a short prioritized report: **what happened → evidence → proposed remedy
41
+ and its home → how to test it**. Separate measured cost from estimates and report
42
+ coverage limits. Keep additional supported findings available through disclosure
43
+ or linked detail. An empty candidate list is a valid result. Use a small visual
44
+ or before/after when it makes a finding easier to judge.
45
+
46
+ Recommendations stay proposals. A retrospective request does not authorize
47
+ editing skills, global instructions, permissions or project behavior. Honor any
48
+ specific remediation already authorized by the user without asking again; keep
49
+ other candidates for selection. A selected repair needs the failure case and a
50
+ legitimate counterexample checked before becoming guidance. Preserve acceptance,
51
+ archive timing and current human authority; a lesson cannot add a permission
52
+ gate or certify a PASS. Use [recurring failure guidance](../../../.joycraft/references/recurring-failures.md)
53
+ when delivering a chosen lesson to later workers. Claim general benefit only
54
+ after later independent reuse supports it.
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Joycraft Retro"
3
+ short_description: "Find session friction and propose focused improvements"
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: joycraft-session-end
3
+ description: Close an authorized Joycraft implementation session, report evidence honestly, and archive a wholly accepted feature only at the session boundary.
4
+ compatibility: Requires Node.js 22+ and the installed .joycraft runtime for the archive helper.
5
+ ---
6
+
7
+ # Joycraft Session End
8
+
9
+ Use this skill when pausing or finishing an authorized queue session.
10
+
11
+ On Claude `SessionEnd`, write only the local session summary and deduplicate the
12
+ transition record. Do not call an API or archive from that hook. On other hosts,
13
+ use their metrics/manual or portable summary path when available; never infer a
14
+ Claude lifecycle event from a generic session boundary.
15
+
16
+ Read each touched queue and report the real state of every affected spec: `todo`, `in-review`, or `done`. `done` must have either an accepted PASS report receipt or a completion-helper owner-acceptance record bound to a current failed or unverified report; a commit, PASS command, or implementer assertion is not acceptance. Keep blocked or failed dependency branches explicit while identifying independent ready work that can continue next.
17
+
18
+ If the session stops or restarts a concurrent run, report its recorded
19
+ coordinator ownership, captured refs, known worker trees, leases, locks, and
20
+ runtime processes. Release only resources demonstrably owned by that run;
21
+ retain ambiguous merges, locks, processes, and trees for diagnosis. Do not
22
+ force local state to a remote tip. Start a replacement only from the durable
23
+ run journal and a newly printed dispatch plan. This guidance describes the
24
+ project/native runtime boundary; it does not enforce lifecycle behavior.
25
+
26
+ For each completed spec, report the implementation revision, independent reviewer session ID, report and receipt paths, actual commands and outcomes, visual inspection status where required, and known limitations. For owner-accepted work, also report the owner-acceptance record and its inherited limits as `done, owner-accepted with <limits>`; preserve the original `FAIL` or `UNVERIFIED` report rather than calling it PASS or verified.
27
+
28
+ If a completion operation failed or was interrupted, do not declare success or hand-edit statuses. Retain the helper's error and journal/recovery information, then use the bounded local recovery process in [completion guidance](../../../.joycraft/references/completion.md). It only restores the two status surfaces and accepted-report receipt captured by the journal; it does not retry unrelated work.
29
+
30
+ Leave enough project-relative paths and next actions for another session to resume the autonomous ready authorized queue without recreating settled context or decisions.
31
+
32
+ Before ending the session, retain failed or blocked worker trees and their
33
+ diagnostic state. Release worker trees and project-owned resource leases only
34
+ after their changes are integrated and accepted through the required review and
35
+ completion path. See [worker isolation](../../../.joycraft/references/worktrees.md)
36
+ when the session used parallel mutable workers.
37
+
38
+ When an `UNVERIFIED` review identifies only an environment condition, record
39
+ that condition and arrange a fresh review after it is corrected. Do not create
40
+ an unchanged-code fix round. The existing completion process remains the sole
41
+ owner of acceptance and status changes.
42
+
43
+ Before archival, update the existing owning context reference and its pointers only when accepted work established reusable project knowledge: record the affected boundary, current coupled sources, observable check, and known limit. Keep accepted observations distinct from proposals, and leave product choices in the brief's decision authority rather than copying them into a competing context record. Do not create a global map or rewrite unrelated context for a local change.
44
+
45
+ When independent reports suggest a reusable failure lesson, use the compact, conditional process in [recurring failure guidance](../../../.joycraft/references/recurring-failures.md): keep only a source-linked shortlist in active task material, inspect current sources before relying on history, and route any proposed lesson as exact next-worker inputs through the existing dispatch path.
46
+
47
+ ## Session-end archival
48
+
49
+ Archive only after the host has ended active work for a feature. It is never a
50
+ completion action: do not invoke it from `complete`, `verify`, a hook, or while
51
+ a worker or unfinished dependent needs the feature paths. Read
52
+ [archive guidance](../../../.joycraft/references/archive.md) before
53
+ preparing the host attestation.
54
+
55
+ Use the archive CLI's default preview first. It requires `phase=session-end`, a
56
+ quiescent host attestation, durable constraints already carried into current
57
+ context, every queue spec `done`, accepted independent PASS reports or
58
+ historical owner-acceptance records bound to their retained failed/unverified
59
+ reports, intact historical receipts, and no completion journal. Apply is the
60
+ separate explicit step:
61
+
62
+ ```sh
63
+ node .joycraft/runtime/archive.mjs archive --feature <slug> --phase session-end --attestation <attestation.json>
64
+ node .joycraft/runtime/archive.mjs archive --feature <slug> --phase session-end --attestation <attestation.json> --apply
65
+ ```
66
+
67
+ Historical reports retain their original paths, subject revisions, and claims.
68
+ Do not rewrite them or describe old code hashes as a new current acceptance.
69
+
70
+ If post-acceptance queue/spec edits block archival, investigate the discrepancy
71
+ and use the explicit archive-reconciliation path in the archive guidance when
72
+ the owner has authorized that resolution. Record the instruction, exact affected
73
+ report/input hashes, cause, resolution and limitations; preserve every original
74
+ report and accepted version. Existing task authorization need not be requested
75
+ again. Do not rewrite acceptance hashes, roll back a queue merely to satisfy old
76
+ reports, or re-review done work solely to move a folder. Report the result as
77
+ `archived with reconciliation`, never as renewed acceptance. Unresolved product
78
+ work and corrupt or missing evidence still block closure.
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: joycraft-testing
3
+ description: Plan and collect useful test and visual evidence for changed behavior, regressions, or independent verification of a Joycraft spec.
4
+ compatibility: The optional shared evidence validator requires Node.js 22+ and the installed .joycraft runtime; visual acceptance needs rendered inspection only for visual criteria.
5
+ ---
6
+
7
+ # Useful testing evidence
8
+
9
+ Use any post-edit hook findings as candidate gaps to inspect against the active
10
+ requirements and relevant tests. A flag is not proof of a defect, and no flag is
11
+ not proof of coverage. Keep valid gaps visible until a useful assertion or
12
+ observed interaction resolves them; missing tests during intermediate edits do
13
+ not require stopping understood implementation.
14
+
15
+ Read the active requirements and relevant existing tests. Choose the smallest
16
+ boundary that can establish each claim: real function inputs for arithmetic,
17
+ composed transitions for stateful behavior, rendered interaction for UI behavior.
18
+ Use representative values and assert observable results. A pure-function change
19
+ need not acquire an end-to-end suite; a source scan cannot establish runtime
20
+ behavior. Keep useful source-contract checks for structural requirements.
21
+
22
+ For a new regression assertion, establish that it detects the intended fault
23
+ when practical, then verify the fix. Existing passing characterization tests
24
+ remain valid; only assertions intended to detect the new behavior need meaningful
25
+ red/green. If a red check was not run, say so. Do not weaken assertions to obtain
26
+ green or alter unrelated tests to manufacture universal failure.
27
+
28
+ For UI requirements, use the tools and commands in the `Review loop` section of
29
+ `AGENTS.md` (also in the worker packet as `reviewLoop`); a tool it marks skipped
30
+ or missing leaves that UI claim UNVERIFIED.
31
+ Render and inspect the relevant route, state and viewport.
32
+ Perform the interactions the claim needs and observe their outcomes. Fix observed
33
+ problems within scope, then rerender and reinspect affected states. A saved
34
+ screenshot, DOM check or browser launch alone is not visual inspection. Preserve
35
+ tool access boundaries: if a check is blocked or unavailable, record UNVERIFIED
36
+ and the reason; do not route around a denial.
37
+
38
+ Write one focused test per acceptance `Check:`, derived from the spec rather
39
+ than from the code, sized like neighboring tests. Do not commit tests of one-off
40
+ run state. If a criterion or test looks wrong, or conflicts with a later owner
41
+ decision, report a spec gap; never edit it to pass.
42
+
43
+ Run each test command once in single-run mode with `CI=1` and a 300000 ms
44
+ timeout; follow [running tests](../../../.joycraft/references/testing.md#running-tests)
45
+ when one times out.
46
+
47
+ Retain the executed command, actual exit status and unfiltered output. Describe
48
+ what happened separately from what was expected. Bind observations and supporting
49
+ receipt paths/hashes to the current verification subject. One flow can cover
50
+ several criteria without repeating evidence. Scope each claim to what the check
51
+ could observe, including limitations and any unresolved FAIL/UNVERIFIED result.
52
+
53
+ Read `.joycraft/references/testing.md` when selecting evidence kinds,
54
+ writing flow records or deciding whether a check is sufficient. Shared record
55
+ shapes are in `.joycraft/contracts/types.d.ts`.
56
+
57
+ `validateEvidence(report, criteria)` in `.joycraft/runtime/evidence.mjs`
58
+ checks declared evidence sufficiency. It cannot verify truthful observation,
59
+ infer missing requirements or replace independent review. Send finished evidence
60
+ to `joycraft-verify`; acceptance and status changes use the completion helper.
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: joycraft-ui-slice
3
+ description: Resolve a consequential interface choice with a small working preview, focused feedback, and an answer saved in the feature brief before affected implementation.
4
+ compatibility: The optional preview helper requires Node.js 22+ and the installed .joycraft runtime; visual acceptance needs rendering and inspection only for visual criteria.
5
+ ---
6
+
7
+ Read the current brief and relevant project context. If the visual choice is
8
+ already settled, implement and inspect the authorized refinement without a new
9
+ interview. Otherwise show the unanswered consequential choice first in the
10
+ existing decision or review surface, when one is available. Identify the smallest
11
+ interaction that would make the choice concrete. Continue independent repairs or
12
+ other understood work.
13
+
14
+ Reuse a current inspected app/component render when it can answer the choice; a
15
+ self-contained HTML slice is an option for inexpensive exploration. A static
16
+ render or screenshot can answer an appearance-only question. Ask proactively for
17
+ the few visual details that materially affect a pixel-level choice when the
18
+ current render cannot answer them. Otherwise build or modify the smallest runnable
19
+ slice in the project's actual stack. Show the consequential state and a useful
20
+ interaction when interaction matters. One viewport is a useful starting size, not
21
+ a rule for all products. Put explanatory detail behind disclosure. The slice is
22
+ exploration, not production approval. Render and inspect it early with permitted
23
+ browser tools; record the route, state, viewport, interactions and observed
24
+ outcomes. If blocked, record UNVERIFIED and the reason; respect denials without
25
+ alternate access routes.
26
+
27
+ The optional local helper below needs the installed shared runtime. If it is
28
+ missing during first use or setup, follow
29
+ [first-use setup](../../../.joycraft/references/setup.md) before using it.
30
+
31
+ Use the existing brief's decision ID and persist the answer there. For a
32
+ self-contained HTML slice using the supplied JSON flow-array decision format,
33
+ this optional helper provides a compact preview shell and saves directly to the brief:
34
+
35
+ ```sh
36
+ node .agents/skills/joycraft-ui-slice/scripts/serve.mjs --brief docs/features/<slug>/brief.md --slice docs/features/<slug>/slice.html [--decision <id>]
37
+ ```
38
+
39
+ Read `.joycraft/references/workflow.md#interactive-slices` for the format
40
+ and helper limits. Without `--decision`, the helper opens the first unanswered
41
+ choice and advances as the current brief changes; it shows a settled state when no
42
+ choice remains. An explicit ID stays bound to that decision. The slice receives a
43
+ `choice` query parameter; make that switch the real layout/behavior being compared.
44
+ The helper serves only the supplied HTML and shell and refreshes the shell from the
45
+ current brief. Existing project formats may be retained: render their current state
46
+ and persist answers there before continuing, without a second decision store.
47
+
48
+ For several brief decisions, a screenshot comparison, or a compact review
49
+ summary, use the deterministic artifact view described in
50
+ `.joycraft/references/artifacts.md`. It is a review interface, not a
51
+ replacement for a real product slice when the decision depends on product
52
+ interaction.
53
+
54
+ Ask only for the missing material choice, using a few contextual options. Verify
55
+ the saved answer from the brief and on reload. Carry it into requirement anchors
56
+ and refresh only affected specs and evidence when the answer or relevant evidence
57
+ changes. For a changed material choice, reopen that same decision, name affected
58
+ specs/evidence, and invalidate affected commitment before proceeding. Do not
59
+ silently replace a clarified answer or treat browser storage as authority.
@@ -0,0 +1,97 @@
1
+ import { randomBytes } from 'node:crypto';
2
+ import { createServer } from 'node:http';
3
+ import { lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
4
+ import { dirname, join, resolve } from 'node:path';
5
+ import { fileURLToPath, pathToFileURL } from 'node:url';
6
+ import {
7
+ readBrief,
8
+ saveAnswer,
9
+ selectPreviewDecision
10
+ } from '../../../../.joycraft/runtime/artifacts/decisions.mjs';
11
+
12
+ export { readBrief, saveAnswer, selectPreviewDecision };
13
+
14
+ function plainFile(path) {
15
+ const stat = lstatSync(path);
16
+ if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Brief and slice must be plain files');
17
+ return stat;
18
+ }
19
+
20
+ function replaceBrief(path, original, updated) {
21
+ if (updated === original) return;
22
+ const stat = plainFile(path);
23
+ const temporary = join(dirname(path), `.slice-answer-${randomBytes(8).toString('hex')}`);
24
+ try {
25
+ writeFileSync(temporary, updated, { flag: 'wx', mode: stat.mode });
26
+ if (readFileSync(path, 'utf8') !== original) throw new Error('Brief changed. Reload before choosing.');
27
+ renameSync(temporary, path);
28
+ } finally {
29
+ try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; }
30
+ }
31
+ }
32
+
33
+ /** Serve only one author-selected brief and self-contained slice on loopback. */
34
+ export async function startPreview({ briefPath, slicePath, decisionId, port = 0 }) {
35
+ const briefFile = resolve(briefPath), sliceFile = resolve(slicePath);
36
+ plainFile(briefFile); plainFile(sliceFile);
37
+ if (decisionId) selectPreviewDecision(readBrief(readFileSync(briefFile, 'utf8')), decisionId);
38
+ const token = randomBytes(24).toString('hex');
39
+ const template = readFileSync(fileURLToPath(new URL('../../../../.joycraft/templates/ui-slice.html', import.meta.url)), 'utf8');
40
+ let origin;
41
+ const state = () => {
42
+ const brief = readBrief(readFileSync(briefFile, 'utf8'));
43
+ const decision = decisionId ? selectPreviewDecision(brief, decisionId) : selectPreviewDecision(brief);
44
+ return { decision, revision: brief.revision, settled: decision === null };
45
+ };
46
+ const server = createServer(async (request, response) => {
47
+ const send = (status, value, type = 'application/json') => {
48
+ response.writeHead(status, { 'Content-Type': `${type}; charset=utf-8`, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
49
+ response.end(type === 'application/json' ? JSON.stringify(value) : value);
50
+ };
51
+ try {
52
+ if (request.headers.host !== new URL(origin).host) return send(403, { error: 'Invalid host' });
53
+ const url = new URL(request.url, origin);
54
+ if (request.method === 'GET' && url.pathname === '/') {
55
+ response.setHeader('Content-Security-Policy', "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; frame-src 'self'; base-uri 'none'; frame-ancestors 'none'");
56
+ return send(200, template.replace('__REQUEST_TOKEN__', JSON.stringify(token)), 'text/html');
57
+ }
58
+ if (request.method === 'GET' && url.pathname === '/state') return send(200, state());
59
+ if (request.method === 'GET' && url.pathname === '/slice') {
60
+ response.setHeader('Content-Security-Policy', "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data:; base-uri 'none'");
61
+ return send(200, readFileSync(sliceFile, 'utf8'), 'text/html');
62
+ }
63
+ if (request.method === 'POST' && url.pathname === '/answer') {
64
+ if (request.headers.origin !== origin || request.headers['x-slice-token'] !== token) return send(403, { error: 'Invalid origin or token' });
65
+ let body = '';
66
+ for await (const part of request) {
67
+ body += part;
68
+ if (body.length > 8192) return send(413, { error: 'Answer too large' });
69
+ }
70
+ const answer = JSON.parse(body);
71
+ const current = state();
72
+ if (!current.decision) return send(409, { error: 'All choices are settled' });
73
+ if (answer.id !== current.decision.id) return send(409, { error: 'This preview is bound to another decision' });
74
+ const original = readFileSync(briefFile, 'utf8');
75
+ replaceBrief(briefFile, original, saveAnswer(original, answer));
76
+ return send(200, state());
77
+ }
78
+ return send(404, { error: 'Not found' });
79
+ } catch (error) { return send(409, { error: error.message }); }
80
+ });
81
+ await new Promise((accept, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', accept); });
82
+ origin = `http://127.0.0.1:${server.address().port}`;
83
+ return { server, url: origin, close: () => new Promise((accept, reject) => server.close(error => error ? reject(error) : accept())) };
84
+ }
85
+
86
+ if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
87
+ try {
88
+ const args = process.argv.slice(2), values = {};
89
+ for (let index = 0; index < args.length; index += 2) {
90
+ if (!['--brief', '--slice', '--decision'].includes(args[index]) || !args[index + 1] || values[args[index]]) throw new Error('Expected --brief <file> --slice <file> [--decision <id>]');
91
+ values[args[index]] = args[index + 1];
92
+ }
93
+ if (!values['--brief'] || !values['--slice']) throw new Error('Expected --brief <file> --slice <file> [--decision <id>]');
94
+ const preview = await startPreview({ briefPath: values['--brief'], slicePath: values['--slice'], decisionId: values['--decision'] });
95
+ console.log(`Preview: ${preview.url}\nAnswers save directly to ${values['--brief']}. Stop with Ctrl-C.`);
96
+ } catch (error) { console.error(error.message); process.exitCode = 1; }
97
+ }