joycraft 0.7.7 → 0.7.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +58 -319
- package/dist/{chunk-VSBOHF5Z.js → chunk-NYBX6MOT.js} +53 -46
- package/dist/chunk-NYBX6MOT.js.map +1 -0
- package/dist/{chunk-Q7TCWFTF.js → chunk-ONGWPA4M.js} +7 -2
- package/dist/chunk-ONGWPA4M.js.map +1 -0
- package/dist/{chunk-MADJOL4S.js → chunk-PBOICMDE.js} +32 -4
- package/dist/chunk-PBOICMDE.js.map +1 -0
- package/dist/{chunk-GLHRP5OB.js → chunk-RRMO5FBO.js} +2 -2
- package/dist/cli.js +6 -6
- package/dist/{init-P676ZJ4V.js → init-XX3MY75H.js} +5 -5
- package/dist/{init-autofix-V42FDZBV.js → init-autofix-K5VZEKO2.js} +3 -3
- package/dist/{upgrade-XMMV42TF.js → upgrade-WVKG2UHF.js} +5 -5
- package/dist/{version-I5I772X6.js → version-B2CCAEMC.js} +4 -2
- package/package.json +1 -1
- package/dist/chunk-MADJOL4S.js.map +0 -1
- package/dist/chunk-Q7TCWFTF.js.map +0 -1
- package/dist/chunk-VSBOHF5Z.js.map +0 -1
- /package/dist/{chunk-GLHRP5OB.js.map → chunk-RRMO5FBO.js.map} +0 -0
- /package/dist/{init-P676ZJ4V.js.map → init-XX3MY75H.js.map} +0 -0
- /package/dist/{init-autofix-V42FDZBV.js.map → init-autofix-K5VZEKO2.js.map} +0 -0
- /package/dist/{upgrade-XMMV42TF.js.map → upgrade-WVKG2UHF.js.map} +0 -0
- /package/dist/{version-I5I772X6.js.map → version-B2CCAEMC.js.map} +0 -0
package/README.md
CHANGED
|
@@ -8,243 +8,69 @@
|
|
|
8
8
|
|
|
9
9
|
## What is Joycraft?
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
### The core idea
|
|
14
|
-
|
|
15
|
-
- **The product:** Skills like `/joycraft-tune`, `/joycraft-new-feature`, and `/joycraft-interview` replace unstructured prompting with spec-driven development — you interview, you write specs, the agent executes — plus a harness (boundaries, context docs, skills) that gets better as you work.
|
|
16
|
-
- **The experimental frontier:** For teams with the budget and infrastructure to maintain it, the `/joycraft-implement-level5` skill sets up an autonomous loop with holdout scenario testing, and on Pi the workflow can run fully headless. Powerful, but genuinely expensive to run and maintain with current models — treat it as a north star, not the next step.
|
|
17
|
-
|
|
18
|
-
### What are the levels?
|
|
19
|
-
|
|
20
|
-
[Dan Shapiro's 5 Levels of Vibe Coding](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) provides the framework:
|
|
21
|
-
|
|
22
|
-
| Level | Name | What it looks like | Joycraft's role |
|
|
23
|
-
|-------|------|--------------------|-----------------|
|
|
24
|
-
| 1 | Autocomplete | Tab-complete suggestions | - |
|
|
25
|
-
| 2 | Junior Developer | Prompt → iterate → fix → repeat | `/joycraft-tune` assesses where you are |
|
|
26
|
-
| 3 | Developer as Manager | Your life is reviewing diffs | Behavioral boundaries in CLAUDE.md |
|
|
27
|
-
| 4 | Developer as PM | You write specs, agent writes code | `/joycraft-new-feature` + `/joycraft-decompose` |
|
|
28
|
-
| 5 | Software Factory | Specs in, validated software out | `/joycraft-implement-level5` (experimental) |
|
|
29
|
-
|
|
30
|
-
Most developers plateau at Level 2. Joycraft's job is to make you excellent at
|
|
31
|
-
Levels 3-4: spec-driven development with a well-maintained harness. Level 5 is
|
|
32
|
-
real — StrongDM proved it — but with current models it takes serious budget and
|
|
33
|
-
a team to maintain, so Joycraft treats it as an experimental north star rather
|
|
34
|
-
than the destination.
|
|
35
|
-
|
|
36
|
-
### Platform support
|
|
37
|
-
|
|
38
|
-
Joycraft supports **Claude Code**, **OpenAI Codex**, **Pi**, and **GitHub Copilot** out of the box. When you run `npx joycraft init`, it opens with a quick picker — choose any combination, and only the harnesses you select get installed:
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
Which AI harnesses should Joycraft install?
|
|
42
|
-
claude — Claude Code (.claude/)
|
|
43
|
-
codex — OpenAI Codex (.agents/)
|
|
44
|
-
pi — Pi (.pi/)
|
|
45
|
-
copilot — GitHub Copilot (.github/)
|
|
46
|
-
Harnesses [comma-separated, or "all"] (none): claude,pi
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
| Harness | Skills installed to | Invocation |
|
|
50
|
-
|---------|---------------------|------------|
|
|
51
|
-
| Claude Code | `.claude/skills/` | `/joycraft-*` |
|
|
52
|
-
| Codex | `.agents/skills/` (+ `AGENTS.md`) | `$joycraft-*` |
|
|
53
|
-
| Pi | `.pi/skills/` (+ pipeline runtime, see below) | `/skill:joycraft-*` |
|
|
54
|
-
| GitHub Copilot | `.github/skills/` | — |
|
|
55
|
-
|
|
56
|
-
All four get the same structured workflows, adapted for each tool's invocation model. A single-harness install carries **no footprint from the others** — pick `copilot` only and you get `.github/skills/` with no `.claude/`, `.agents/`, or `.pi/` in sight. In a non-interactive run (CI, piped, no TTY) `init` installs all available harnesses so existing scripts keep working. The shared docs (`CLAUDE.md`, `AGENTS.md`, `docs/`) are written regardless of which harnesses you pick.
|
|
57
|
-
|
|
58
|
-
### Headless spec execution (Pi)
|
|
59
|
-
|
|
60
|
-
Pi is the one harness where the workflow can run **fully autonomously** — no human keystrokes between specs. Beyond the skills, `init` installs a pipeline runtime to `.pi/scripts/joycraft/` whose driver, `joycraft-implement-loop`, runs an entire feature's spec queue end to end:
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
next-spec → pi -p "/skill:joycraft-implement <spec>" → pi -p "/skill:joycraft-spec-done <spec>" → repeat
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
Each spec runs in **one fresh OS process** (`pi -p`), so the context isolation is the process boundary itself — verified, not in-conversation trickery. The loop is fail-fast (stops and names the failing spec) and runs `session-end` exactly once when the queue is exhausted.
|
|
67
|
-
|
|
68
|
-
This is what Claude Code and Codex can't do out of the box: an unattended `interview → PR` line where the machine does everything convergent in between. It is Pi-specific by design — the driver targets Pi with a BYO API key or open-weight model (Commercial/API terms, no automation restriction); pointing a consumer Claude/ChatGPT *subscription* at an automated loop would violate those tools' terms.
|
|
69
|
-
|
|
70
|
-
On Claude Code, `/joycraft-implement-feature` gets you the in-session equivalent: one interactive invocation runs the whole queue with a fresh-context **subagent** per spec — the subagent boundary plays the role of Pi's process boundary. You're at the keyboard and it's one command, so none of the headless ToS/cost caveats apply.
|
|
71
|
-
|
|
72
|
-
## What's new in 0.7 — the living harness
|
|
73
|
-
|
|
74
|
-
Through 0.6, Joycraft was excellent at *writing things down*: interviews became
|
|
75
|
-
briefs, briefs became specs, sessions ended with discoveries and decision-log
|
|
76
|
-
rows. What nothing enforced was whether any of it stayed **true** — specs could
|
|
77
|
-
quietly invent constraints, agents re-derived decisions the project had already
|
|
78
|
-
made, and the harness only ever grew. 0.7 closes that loop; the harness now
|
|
79
|
-
audits itself:
|
|
80
|
-
|
|
81
|
-
| | Before (≤0.6) | Now (0.7) |
|
|
82
|
-
|---|---|---|
|
|
83
|
-
| **Spec constraints** | Decompose could invent numbers/conventions that looked authoritative downstream | Every constraint carries a cite — `[src: D3]`, `[src: brief "Scope"]` — or is flagged `[src: INVENTED]` and stopped at a human gate; open decisions block decomposition entirely |
|
|
84
|
-
| **Design claims** | All claims read equally confident | Load-bearing claims are self-scored against fixed anchors (0/25/50/75/100); anything ≤50 is blocked from propagating until deepened or decided |
|
|
85
|
-
| **Prior knowledge** | Agents reasoned from scratch each phase | Research/design/decompose open with a bounded retrieval pass over `docs/context/` + `docs/discoveries/` and must cite what they reused |
|
|
86
|
-
| **Boundaries** | Prose rules an agent could drift past | `joycraft-harden` converts eligible rules into machine-checked deny patterns, stamped with provenance + a probation marker |
|
|
87
|
-
| **Harness growth** | Only ever grew | `joycraft-optimize` v2 assigns every control one of six dispositions (KEEP/ONE_HOME/LOAD_LATER/MAKE_A_CHECK/PROBATION/RETIRE); its Reaper deletes shipped feature folders only after the PR verifiably merged, and archive-moves abandoned ones |
|
|
88
|
-
| **Shipped features** | Folders sat forever; deleting lost the story | Session-end extracts a one-line ledger row to `docs/context/shipped.md` + marks the folder reap-eligible before the Reaper may touch it |
|
|
89
|
-
| **Skill surface** | All skills looked alike to discovery | Skills declare `entry: human \| agent \| situational` — human doors stay discoverable, internals get terse anti-discovery descriptions |
|
|
90
|
-
| **Trust** | The gates were assumed to work | Each gate was evaluated with N=3 fresh-context agent runs graded from tool-call timelines — one gate failed 2/3, got fixed, and re-passed 3/3 |
|
|
91
|
-
|
|
92
|
-
**Side effects to expect:** new files in your knowledge layer
|
|
93
|
-
(`docs/context/shipped.md`, `docs/context/anchors.md`,
|
|
94
|
-
`docs/reference/knowledge-lifecycle.md`), `(anchor: N)` annotations in design
|
|
95
|
-
artifacts, decompose refusing to run while a brief has an open decision, and
|
|
96
|
-
hardened rules being genuinely blocked at the hook layer — including for you.
|
|
97
|
-
|
|
98
|
-
As of **0.7.1 the full pilot ring ships in the npm package** — it piloted in
|
|
99
|
-
Joycraft's own repo first (the same discipline Joycraft asks of your projects)
|
|
100
|
-
and now needs real external projects to iterate against. The full
|
|
101
|
-
before/now/side-effects record is in [CHANGELOG.md](CHANGELOG.md).
|
|
102
|
-
|
|
103
|
-
### Upgrading to 0.7
|
|
104
|
-
|
|
105
|
-
From your project root:
|
|
11
|
+
A CLI that installs spec-driven development into [Claude Code](https://code.claude.com/docs), [OpenAI Codex](https://openai.com/codex), [Pi](https://github.com/earendil-works/pi-coding-agent), and [GitHub Copilot](https://github.com/features/copilot): skills, behavioral boundaries, templates, and a docs structure that matures with your project.
|
|
106
12
|
|
|
107
13
|
```bash
|
|
108
|
-
|
|
14
|
+
cd /path/to/your/project
|
|
15
|
+
npx joycraft@latest init
|
|
109
16
|
```
|
|
110
17
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
- **Your customizations survive.** Upgrade diffs every file it installed against
|
|
114
|
-
what's on disk: unmodified files update silently, customized files show you
|
|
115
|
-
the diff and ask. Nothing is overwritten without a yes (or `--yes` in CI).
|
|
116
|
-
- **State file moves.** `.claude/.joycraft/state.json` migrates to
|
|
117
|
-
`docs/.joycraft/state.json` (gitignored, harness-neutral) automatically.
|
|
118
|
-
- **Session-end gains the extraction step.** The next time a feature finishes,
|
|
119
|
-
it writes a `docs/context/shipped.md` ledger row and marks the brief
|
|
120
|
-
`reap: eligible` — it never deletes anything.
|
|
121
|
-
- **Every skill gains `entry:` frontmatter** (human / agent / situational).
|
|
122
|
-
Purely additive; invocation is unchanged.
|
|
123
|
-
- **Harness selection is honored.** A Codex-only project stays Codex-only.
|
|
124
|
-
- **The pilot ring arrives (0.7.1).** Two new skills (`joycraft-decide`,
|
|
125
|
-
`joycraft-harden`), the retrieval pass, the decision gate + provenance-cited
|
|
126
|
-
specs, confidence anchors, and optimize v2 with the Reaper. The gates you'll
|
|
127
|
-
feel first: decompose blocks on open decisions, and invented spec premises
|
|
128
|
-
stop at a human review before any spec file is written.
|
|
129
|
-
- **Gates get succinct (0.7.6).** Every approval bookend (brief, design,
|
|
130
|
-
decompose, research, decide, plus the tune and optimize reports) renders an
|
|
131
|
-
auto-opened HTML artifact and caps its chat message at ~10 fixed slots — the
|
|
132
|
-
markdown stays the canonical record agents read. Handoffs become fenced,
|
|
133
|
-
copy-pasteable briefing prompts. `upgrade` adds an `## Execution Profile`
|
|
134
|
-
section to AGENTS.md (swarm opt-in + per-harness model/effort) that flows
|
|
135
|
-
into those briefings. And a stale CLI now re-runs itself through
|
|
136
|
-
`npx joycraft@<latest>` instead of telling you to update separately —
|
|
137
|
-
upgrade is one command again.
|
|
138
|
-
|
|
139
|
-
**Or let your agent drive it.** Paste this prompt into Claude Code, Codex, Pi,
|
|
140
|
-
or GitHub Copilot inside your project and it will run the upgrade, show you
|
|
141
|
-
what changed, and leave a reviewable commit:
|
|
142
|
-
|
|
143
|
-
```text
|
|
144
|
-
Upgrade Joycraft in this project to 0.7. Steps: (1) Create a branch
|
|
145
|
-
chore/joycraft-0.7. (2) Run `npx joycraft@latest upgrade` interactively —
|
|
146
|
-
when it shows a diff for a file I customized, summarize the diff for me in
|
|
147
|
-
one or two sentences and ask before accepting; never blanket-accept.
|
|
148
|
-
(3) After the upgrade, list every file it changed, added, or migrated
|
|
149
|
-
(including the docs/.joycraft/state.json move), and read CHANGELOG.md's
|
|
150
|
-
0.7.0 entry from the joycraft package to explain in plain terms what
|
|
151
|
-
changed about how my harness behaves — before vs. now, plus side effects
|
|
152
|
-
I should expect. (4) Confirm my harness selection and gitignore profile
|
|
153
|
-
were preserved, and that my CLAUDE.md/AGENTS.md customizations are intact.
|
|
154
|
-
(5) Run my project's test and typecheck commands to confirm nothing broke.
|
|
155
|
-
(6) Commit the result with message "chore: upgrade joycraft to 0.7" and
|
|
156
|
-
show me the diff stat — do not push or open a PR without asking.
|
|
157
|
-
```
|
|
18
|
+
## Contents
|
|
158
19
|
|
|
159
|
-
|
|
20
|
+
- [Install](#install) · [Use](#use) · [Upgrade](#upgrade)
|
|
21
|
+
- [Setup walkthrough](docs/guides/setup-walkthrough.md) — every step from install to first feature
|
|
22
|
+
- [Which skill do I need?](#which-skill-do-i-need) — the skill table and the core loop
|
|
23
|
+
- [What init creates](#what-init-creates)
|
|
24
|
+
- [Platform support](docs/guides/platform-support.md) — Claude Code, Codex, Pi, Copilot, stacks, headless Pi
|
|
25
|
+
- [Upgrading](docs/guides/upgrading.md) — `npx joycraft@latest upgrade` and what's new in 0.7
|
|
26
|
+
- [Git tracking](docs/guides/git-tracking.md) — shared vs private profiles, reviewable PRs
|
|
27
|
+
- [Migration: flat → per-feature layout](docs/guides/migration-per-feature-layout.md) — the v0.6 docs move
|
|
28
|
+
- [The levels](docs/guides/levels.md) — Dan Shapiro's 5 Levels, where Joycraft aims, and the credits
|
|
29
|
+
- [Security](SECURITY.md) · [Guides](#guides) · [Why Joycraft?](#why-joycraft)
|
|
30
|
+
- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md) · [License](LICENSE)
|
|
160
31
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
```bash
|
|
164
|
-
npm install -g joycraft
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
Then navigate to your project's root directory and initialize:
|
|
32
|
+
## Install
|
|
168
33
|
|
|
169
34
|
```bash
|
|
170
35
|
cd /path/to/your/project
|
|
171
|
-
npx joycraft init
|
|
36
|
+
npx joycraft@latest init
|
|
172
37
|
```
|
|
173
38
|
|
|
174
|
-
|
|
39
|
+
Answer two questions — which harnesses to install, and whether to commit them — and `init` does the rest: detects your stack, writes `AGENTS.md`/`CLAUDE.md` with your real build/test commands, installs the skills. Safe to re-run: it only creates missing files, never overwrites yours.
|
|
175
40
|
|
|
176
|
-
|
|
177
|
-
- **CLAUDE.md** — on a multi-tool install this is [Anthropic's documented import pattern](https://code.claude.com/docs/en/memory): `@AGENTS.md` plus a `## Claude Code` section for Claude-specific additions, so every tool reads one source and nothing drifts. A Claude-only install gets the classic full CLAUDE.md instead
|
|
178
|
-
- **22 skills** installed to the selected harnesses — `.claude/skills/` (Claude Code), `.agents/skills/` (Codex), `.pi/skills/` (Pi), and/or `.github/skills/` (GitHub Copilot) — see [Which skill do I need?](#which-skill-do-i-need) below
|
|
179
|
-
- **Pi pipeline runtime** in `.pi/scripts/joycraft/` (when Pi is selected) — the headless spec-execution driver and its helpers
|
|
180
|
-
- **Agent teams enabled** — when Claude Code is selected, `init` sets `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `.claude/settings.json` so subagent-driven skills like `/joycraft-research` work out of the box (idempotent — it never clobbers a value you already set)
|
|
181
|
-
- **docs/** structure: `docs/context/` is created up front; feature work lands in `docs/features/<slug>/{brief.md, research.md, design.md, specs/}` and deferred work in `docs/backlog/` — these are created lazily by the skills that write to them. Joycraft's own upgrade state lives hidden at `docs/.joycraft/state.json` (harness-neutral, gitignored — never committed)
|
|
182
|
-
- **Context documents** in `docs/context/`: production map, dangerous assumptions, decision log, institutional knowledge, and troubleshooting guide
|
|
183
|
-
- **Templates** including atomic spec, feature brief, implementation plan, boundary framework, and workflow templates for scenario generation and autofix loops
|
|
41
|
+
`npm install -g joycraft` if you'd rather have the command on your PATH; `npx` works without it. Every step from install to first shipped feature: [Setup walkthrough](docs/guides/setup-walkthrough.md).
|
|
184
42
|
|
|
185
|
-
|
|
43
|
+
## Use
|
|
186
44
|
|
|
187
|
-
|
|
45
|
+
Inside your AI tool, drive everything with slash commands:
|
|
188
46
|
|
|
189
|
-
|
|
47
|
+
```
|
|
48
|
+
/joycraft-setup # first run — onboarding, where to begin
|
|
49
|
+
/joycraft-new-feature # interview → Feature Brief → atomic specs
|
|
50
|
+
/joycraft-implement-feature docs/features/<slug>/ # run the whole spec queue, TDD per spec
|
|
51
|
+
/joycraft-session-end # wrap up: validate, graduate specs, push/PR
|
|
52
|
+
/joycraft-tune # score your harness, apply upgrades
|
|
53
|
+
```
|
|
190
54
|
|
|
191
|
-
|
|
192
|
-
gets the same skills and workflow. Some teams prefer to keep the harness local
|
|
193
|
-
and track only the docs. Choose a profile at init time:
|
|
55
|
+
Brainstorming first? `/joycraft-interview`. Fixing a bug? `/joycraft-bugfix`. The full table is at [Which skill do I need?](#which-skill-do-i-need); invocation syntax per tool is in [Platform support](docs/guides/platform-support.md).
|
|
194
56
|
|
|
195
|
-
|
|
196
|
-
npx joycraft init --gitignore=shared # default — commit .claude/, .agents/, .pi/, .github/
|
|
197
|
-
npx joycraft init --gitignore=private # gitignore them; track only CLAUDE.md, AGENTS.md, docs/
|
|
198
|
-
```
|
|
57
|
+
## Upgrade
|
|
199
58
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
automatically. To switch an existing project later (or decide from CI), pass the
|
|
203
|
-
same flag to upgrade: `npx joycraft upgrade --gitignore=private`. `.gitignore`
|
|
204
|
-
edits are append-only — Joycraft never rewrites or removes your existing lines.
|
|
205
|
-
|
|
206
|
-
| Profile | Tracked in git | Gitignored |
|
|
207
|
-
|---------|----------------|------------|
|
|
208
|
-
| `shared` (default) | `CLAUDE.md`, `AGENTS.md`, `docs/`, `.claude/skills/`, `.agents/`, `.pi/`, `.github/skills/` | hidden upgrade state only (`docs/.joycraft/state.json`) |
|
|
209
|
-
| `private` | `CLAUDE.md`, `AGENTS.md`, `docs/` | `.claude/`, `.agents/`, `.pi/`, `.github/skills/joycraft-*/` |
|
|
210
|
-
|
|
211
|
-
> Switching an existing project to `private` only updates `.gitignore`. If
|
|
212
|
-
> harness files were already committed, untrack them with
|
|
213
|
-
> `git rm -r --cached .claude .agents .pi .github/skills/joycraft-*` (Joycraft prints this reminder and
|
|
214
|
-
> never runs git for you).
|
|
215
|
-
>
|
|
216
|
-
> Under `private`, the harness dirs aren't committed — so a teammate who clones
|
|
217
|
-
> the repo gets `CLAUDE.md`/`AGENTS.md` but no skills until they run
|
|
218
|
-
> `npx joycraft init` to regenerate them locally. Joycraft adds a one-line
|
|
219
|
-
> reminder to your generated `CLAUDE.md` and `AGENTS.md` for exactly this reason.
|
|
220
|
-
|
|
221
|
-
### Reviewable PRs: workflow docs are collapsed
|
|
222
|
-
|
|
223
|
-
Joycraft's docs are two kinds of content. Durable knowledge — `CLAUDE.md`,
|
|
224
|
-
`AGENTS.md`, `docs/context/` — steers every future agent run and deserves review
|
|
225
|
-
eyes. Workflow exhaust — feature briefs and specs, discoveries, installed
|
|
226
|
-
templates — is historical by the time a PR is opened (the spec was reviewed in
|
|
227
|
-
conversation when it was written). To keep PRs reviewable, `init` and `upgrade`
|
|
228
|
-
write a `.gitattributes` marking the exhaust paths `linguist-generated=true`:
|
|
229
|
-
|
|
230
|
-
```gitattributes
|
|
231
|
-
docs/features/** linguist-generated=true
|
|
232
|
-
docs/bugfixes/** linguist-generated=true
|
|
233
|
-
docs/discoveries/** linguist-generated=true
|
|
234
|
-
docs/templates/** linguist-generated=true
|
|
59
|
+
```bash
|
|
60
|
+
npx joycraft@latest upgrade
|
|
235
61
|
```
|
|
236
62
|
|
|
237
|
-
|
|
238
|
-
diff stats — reviewers see your code and your durable knowledge, and any
|
|
239
|
-
collapsed doc is one click from expanding. The write is append-only and
|
|
240
|
-
idempotent (your existing `.gitattributes` lines are never touched); delete any
|
|
241
|
-
line to opt that path back into full review.
|
|
63
|
+
Refreshes skills and templates for the harnesses you selected at init. Unmodified files update automatically; files you've customized show a diff and ask first (`--yes` for CI). Details and release notes: [Upgrading](docs/guides/upgrading.md).
|
|
242
64
|
|
|
243
|
-
|
|
65
|
+
## What init creates
|
|
244
66
|
|
|
245
|
-
|
|
67
|
+
- **AGENTS.md** — behavioral boundaries (Always / Ask First / Never) plus your stack's real build/test/lint commands; the single shared instruction file when more than one tool is selected
|
|
68
|
+
- **CLAUDE.md** — on a multi-tool install, [Anthropic's documented import pattern](https://code.claude.com/docs/en/memory): `@AGENTS.md` plus a `## Claude Code` section, so every tool reads one source. A Claude-only install gets the classic full CLAUDE.md
|
|
69
|
+
- **22 skills** — installed to `.claude/skills/` (Claude Code), `.agents/skills/` (Codex), `.pi/skills/` (Pi), and/or `.github/skills/` (Copilot); Pi also gets the headless pipeline runtime in `.pi/scripts/joycraft/`
|
|
70
|
+
- **docs/** — `docs/context/` (production map, dangerous assumptions, decision log, institutional knowledge, troubleshooting) plus templates; feature folders and `docs/backlog/` are created lazily by the skills that write to them. Joycraft's own state hides at `docs/.joycraft/state.json` (gitignored)
|
|
71
|
+
- **Agent teams enabled** — with Claude Code selected, `init` sets `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `.claude/settings.json` so subagent-driven skills work out of the box (never clobbers a value you set)
|
|
246
72
|
|
|
247
|
-
|
|
73
|
+
Re-running on an existing project is covered in [Git tracking](docs/guides/git-tracking.md#re-running-init-on-an-existing-project).
|
|
248
74
|
|
|
249
75
|
## The Workflow
|
|
250
76
|
|
|
@@ -292,117 +118,30 @@ flowchart LR
|
|
|
292
118
|
style I fill:#333,stroke:#333,color:#fff,stroke-width:2px
|
|
293
119
|
```
|
|
294
120
|
|
|
295
|
-
|
|
121
|
+
## Guides
|
|
296
122
|
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
Objective research via context isolation and 200-line design checkpoints
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
A 2-3 minute risk interview generates safety boundaries, and you choose your git autonomy level. [Read the full guide →](docs/guides/tuning.md)
|
|
310
|
-
|
|
311
|
-
### Token Discipline
|
|
312
|
-
|
|
313
|
-
Joycraft produces file artifacts at every step, so your conversation context is disposable. Clear it between phases to reduce cost and improve output quality. [Read the full guide →](docs/guides/token-discipline.md)
|
|
314
|
-
|
|
315
|
-
### Level 5: The Autonomous Loop (experimental)
|
|
316
|
-
|
|
317
|
-
Level 5 is where specs go in and validated software comes out — four GitHub Actions workflows, a separate scenarios repo, and two AI agents that can never see each other's work. It works, but budget for real token costs and ongoing scenario maintenance before committing to it. [Read the full guide →](docs/guides/level-5-autonomy.md)
|
|
318
|
-
|
|
319
|
-
### Permission Modes
|
|
320
|
-
|
|
321
|
-
You do **not** need `--dangerously-skip-permissions` for autonomous development. Claude Code offers safer alternatives. [Read the full guide →](docs/guides/permission-modes.md)
|
|
322
|
-
|
|
323
|
-
### How It Works with AI Agents
|
|
324
|
-
|
|
325
|
-
Claude Code reads CLAUDE.md, Codex and Pi read AGENTS.md — and Claude Code does **not** read AGENTS.md natively. On a multi-tool install Joycraft therefore keeps one shared AGENTS.md and writes CLAUDE.md as an `@AGENTS.md` import (Anthropic's documented pattern), so every tool reads the same instructions without duplication. [Read the full guide →](docs/guides/agent-compatibility.md)
|
|
326
|
-
|
|
327
|
-
## Upgrade
|
|
328
|
-
|
|
329
|
-
When Joycraft templates and skills evolve, update without losing your customizations:
|
|
330
|
-
|
|
331
|
-
```bash
|
|
332
|
-
npx joycraft upgrade
|
|
333
|
-
```
|
|
334
|
-
|
|
335
|
-
Joycraft tracks what it installed vs. what you've customized. Unmodified files update automatically. Customized files show a diff and ask before overwriting. Use `--yes` for CI.
|
|
336
|
-
|
|
337
|
-
`upgrade` only refreshes the harnesses you installed at init — a Codex-only project stays Codex-only and never grows a `.claude/` tree. (Projects from before harness selection existed have no recorded choice, so `upgrade` refreshes all available harnesses, preserving the old behavior.)
|
|
338
|
-
|
|
339
|
-
> **Note:** If you're upgrading from an early version, deprecated skill directories (e.g., `/joy`, `/joysmith`, `/tune`) are automatically removed during upgrade.
|
|
340
|
-
|
|
341
|
-
## Why This Exists
|
|
342
|
-
|
|
343
|
-
Most developers using AI tools are at Level 2 — and [METR's research](https://metr.org/) found they're actually slower, not faster. Joycraft packages the patterns used by teams seeing transformative results into something anyone can install. [Read the full methodology →](docs/guides/methodology.md)
|
|
344
|
-
|
|
345
|
-
## Standing on the Shoulders of Giants
|
|
346
|
-
|
|
347
|
-
Joycraft synthesizes ideas and patterns from people doing extraordinary work in AI-assisted software development:
|
|
348
|
-
|
|
349
|
-
- **[Dan Shapiro](https://x.com/danshapiro)** for the [5 Levels of Vibe Coding](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) framework that Joycraft's assessment and level system is built on
|
|
350
|
-
- **[StrongDM](https://www.strongdm.com/)** / **[Justin McCarthy](https://x.com/BuiltByJustin)** for the [Software Factory](https://factory.strongdm.ai/): spec-driven autonomous development, NLSpec, external holdout scenarios, and the proof that 3 engineers can outproduce 30
|
|
351
|
-
- **[Dex Horthy](https://x.com/dexhorthy)** / **[HumanLayer](https://humanlayer.dev)** for the [RPI to CRISPY evolution](https://humanlayer.dev/blog): research isolation (hide the ticket from the researcher), the instruction budget concept (~150-200 instructions max), design discussions as high-leverage checkpoints, vertical-over-horizontal planning, and the conviction that "if your tool requires magic words, go fix the tool"
|
|
352
|
-
- **[Boris Cherny](https://x.com/bcherny)**, Head of Claude Code at Anthropic, for the interview → spec → fresh session → execute pattern and the insight that [context isolation produces better results](https://www.lennysnewsletter.com/p/head-of-claude-code-what-happens)
|
|
353
|
-
- **[Addy Osmani](https://x.com/addyosmani)** for [What makes a good spec for AI](https://addyosmani.com/blog/good-spec/): commands, testing, project structure, code style, git workflow, and boundaries
|
|
354
|
-
- **[METR](https://metr.org/)** for the [randomized control trial](https://metr.org/) that proved unstructured AI use makes experienced developers slower, validating the need for harnesses
|
|
355
|
-
- **[Nate B Jones](https://x.com/natebjones)** whose [video on the 5 Levels of Vibe Coding](https://www.youtube.com/watch?v=bDcgHzCBgmQ) made this research accessible and inspired turning Joycraft into a tool anyone can use
|
|
356
|
-
- **[Simon Willison](https://x.com/simonw)** for his [analysis of the Software Factory](https://simonwillison.net/2026/Feb/7/software-factory/) that helped contextualize StrongDM's approach for the broader community
|
|
357
|
-
- **[Anthropic](https://www.anthropic.com/)** for Claude Code's skills, hooks, and CLAUDE.md system that makes tool-native AI development possible, and the [harness patterns for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
|
|
358
|
-
|
|
359
|
-
## Migration: Flat → Per-Feature Layout (v0.6+)
|
|
360
|
-
|
|
361
|
-
Starting in v0.6, Joycraft organizes feature artifacts into per-feature folders:
|
|
362
|
-
|
|
363
|
-
- `docs/briefs/<slug>.md` → `docs/features/<slug>/brief.md`
|
|
364
|
-
- `docs/research/<slug>.md` → `docs/features/<slug>/research.md`
|
|
365
|
-
- `docs/designs/<slug>.md` → `docs/features/<slug>/design.md`
|
|
366
|
-
- `docs/specs/<feature>/` → `docs/features/<slug>/specs/` (when `<feature>` matches a brief slug)
|
|
367
|
-
|
|
368
|
-
`npx joycraft upgrade` performs this migration automatically and forcefully on the first
|
|
369
|
-
post-upgrade run — no Y/N prompt. The CLI prints a summary of every move before applying it.
|
|
370
|
-
Spec directories under `docs/specs/` whose name doesn't match any brief slug (area-level specs
|
|
371
|
-
like bugfix folders) are left in place.
|
|
372
|
-
|
|
373
|
-
### What you'll see on the first post-upgrade run
|
|
374
|
-
|
|
375
|
-
```
|
|
376
|
-
Joycraft is migrating your docs/ to the new per-feature layout:
|
|
377
|
-
|
|
378
|
-
2026-04-01-auth-redesign/
|
|
379
|
-
docs/briefs/2026-04-01-auth-redesign.md → docs/features/2026-04-01-auth-redesign/brief.md
|
|
380
|
-
docs/research/2026-04-01-auth-redesign.md → docs/features/2026-04-01-auth-redesign/research.md
|
|
381
|
-
|
|
382
|
-
Left in place — area-level specs (e.g., bugfix areas):
|
|
383
|
-
docs/specs/login-bugfix/
|
|
384
|
-
|
|
385
|
-
Migration complete. See the README section "Migration: Flat → Per-Feature Layout"
|
|
386
|
-
for context on what changed and why. If your project is a git repo, run
|
|
387
|
-
`git status` to inspect the moves before committing.
|
|
388
|
-
```
|
|
123
|
+
| Guide | What it covers |
|
|
124
|
+
|---|---|
|
|
125
|
+
| [Setup walkthrough](docs/guides/setup-walkthrough.md) | Every step from `npm install` to your first shipped feature |
|
|
126
|
+
| [The interview](docs/guides/interview-workflow.md) | The structured interview that replaces prompt-iterate-fix — the single biggest upgrade Joycraft makes |
|
|
127
|
+
| [Research and design](docs/guides/research-and-design.md) | Objective research via context isolation, and 200-line design checkpoints before decomposition |
|
|
128
|
+
| [Test-first development](docs/guides/test-first-development.md) | Tests are the mechanism to autonomy — every spec ships a test plan, failing tests come first |
|
|
129
|
+
| [Tuning: risk interview and git autonomy](docs/guides/tuning.md) | The 2–3 minute risk interview that generates your safety boundaries |
|
|
130
|
+
| [Token discipline](docs/guides/token-discipline.md) | Why file artifacts at every step make your conversation context disposable |
|
|
131
|
+
| [Permission modes](docs/guides/permission-modes.md) | Why you do **not** need `--dangerously-skip-permissions` |
|
|
132
|
+
| [Agent compatibility](docs/guides/agent-compatibility.md) | How CLAUDE.md and AGENTS.md stay one source across four tools |
|
|
133
|
+
| [Level 5: the autonomous loop](docs/guides/level-5-autonomy.md) | Experimental — workflows, holdout scenarios, and what it really costs |
|
|
134
|
+
| [Methodology](docs/guides/methodology.md) | Why this exists: METR's slowdown finding and the teams that beat it |
|
|
389
135
|
|
|
390
|
-
|
|
136
|
+
## Why Joycraft?
|
|
391
137
|
|
|
392
|
-
|
|
393
|
-
`joycraft-decompose`, etc.) write to the new per-feature paths. Supporting both layouts
|
|
394
|
-
indefinitely would mean every skill carries dual-path branches; the forced migration keeps
|
|
395
|
-
the convention single and skills small.
|
|
138
|
+
Unstructured prompting rots: instructions pile up in one file, the agent forgets what was decided, and every session starts from zero. Joycraft replaces it with spec-driven development — you interview, you approve the brief and the specs, the agent executes with TDD — and installs a harness (boundaries, context docs, skills) that matures alongside your project instead of decaying. The gates produce shareable artifacts (markdown + HTML) your team can answer in Notion, and every brief ends with a prompt an engineer pastes straight into their coding agent.
|
|
396
139
|
|
|
397
|
-
|
|
140
|
+
The name of the game is Dan Shapiro's [5 Levels of Vibe Coding](docs/guides/levels.md): Joycraft takes a project from Level 1 to a solid Level 4, with an experimental path to 5. The reasoning and the evidence live in the [Methodology guide](docs/guides/methodology.md).
|
|
398
141
|
|
|
399
|
-
|
|
400
|
-
after the migration, you can `git mv` files anywhere — Joycraft only depends on the
|
|
401
|
-
`docs/features/<slug>/` shape for skills it ships, not on every doc living there. Git
|
|
402
|
-
history follows files via `git log --follow`.
|
|
142
|
+
## Security
|
|
403
143
|
|
|
404
|
-
|
|
405
|
-
the move is skipped and reported. The migration is idempotent.
|
|
144
|
+
Joycraft scaffolds files and never runs your code. What it reads and writes, how boundaries and deny patterns constrain your AI agent, and where to report a vulnerability: [SECURITY.md](SECURITY.md).
|
|
406
145
|
|
|
407
146
|
## Contributing
|
|
408
147
|
|