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 CHANGED
@@ -8,243 +8,69 @@
8
8
 
9
9
  ## What is Joycraft?
10
10
 
11
- Joycraft is a CLI tool that installs structured development skills into [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [OpenAI Codex](https://openai.com/codex), [Pi](https://github.com/earendil-works/pi-coding-agent), and [GitHub Copilot](https://github.com/features/copilot), along with behavioral boundaries, templates, and documentation structure. It takes any project from unstructured prompting to an excellent spec-driven development system with a harness that matures alongside your project.
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
- npx joycraft@latest upgrade
14
+ cd /path/to/your/project
15
+ npx joycraft@latest init
109
16
  ```
110
17
 
111
- What this does to an existing setup:
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
- ## Quick Start
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
- First, install the CLI:
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
- `init` first asks which harnesses to install (see [Platform support](#platform-support) above), then auto-detects your tech stack and creates:
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
- - **AGENTS.md** with behavioral boundaries (Always / Ask First / Never) and correct build/test/lint commands — the single shared instruction file when more than one tool is selected
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
- > Pick nothing at the harness prompt and `init` installs nothing — it tells you to re-run and choose at least one harness.
43
+ ## Use
186
44
 
187
- **`init` only creates *missing* files.** It is safe to run on a project that already has Joycraft (or a hand-tuned `CLAUDE.md`): an existing `CLAUDE.md`, `AGENTS.md`, template, or skill file is **skipped, never regenerated** — your customizations are left untouched. Only `--force` overwrites existing files. The run summary lists what it skipped (`Skipped N file(s) (already exist, use --force to overwrite)`) so you can see exactly what was preserved. This makes `init` the right command to **fill in a private-profile clone**: a teammate who clones a `private` repo gets the committed `CLAUDE.md`/`AGENTS.md`/`docs/` but not the gitignored harness dirs — running `npx joycraft init` regenerates the missing skill files locally and leaves the committed files alone.
45
+ Inside your AI tool, drive everything with slash commands:
188
46
 
189
- ### Git tracking: shared vs private
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
- By default Joycraft assumes you want to **commit** the harness so your whole team
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
- ```bash
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
- Run interactively without the flag and `init` asks (right after the harness
201
- picker). The choice is saved, so `npx joycraft upgrade` re-applies it
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
- GitHub collapses these files in the Files Changed view and excludes them from
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
- ### Supported Stacks
65
+ ## What init creates
244
66
 
245
- Node.js (npm/pnpm/yarn/bun), Python (poetry/pip/uv), Rust, Go, Swift, and generic (Makefile/Dockerfile).
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
- Frameworks auto-detected: Next.js, FastAPI, Django, Flask, Actix, Axum, Express, Remix, and more.
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
- ### The Interview
121
+ ## Guides
296
122
 
297
- The single biggest upgrade Joycraft makes is replacing prompt-iterate-fix with a structured interview. [Read the full guide →](docs/guides/interview-workflow.md)
298
-
299
- ### Research Isolation & Design Checkpoints
300
-
301
- Objective research via context isolation and 200-line design checkpoints for human review before decomposition. [Read the full guide →](docs/guides/research-and-design.md)
302
-
303
- ### Test-First Development
304
-
305
- Tests are the mechanism to autonomy — every spec includes a test plan, and the agent writes failing tests before implementing. [Read the full guide →](docs/guides/test-first-development.md)
306
-
307
- ### Tuning: Risk Interview & Git Autonomy
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
- ### Why forced (not opt-in)
136
+ ## Why Joycraft?
391
137
 
392
- All doc-producing skills (`joycraft-new-feature`, `joycraft-research`, `joycraft-design`,
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
- ### Recovering / customizing
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
- Every move is a plain filesystem move (no `git mv`). If you want a different organization
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
- If a brief and its destination already exist (re-running upgrade after a partial migration),
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