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
package/README.md CHANGED
@@ -4,192 +4,173 @@
4
4
  <img src="docs/joycraft-banner.png" alt="Joycraft, the craft of AI development" width="700" />
5
5
  </p>
6
6
 
7
- > The craft of AI development. With joy, not darkness.
8
-
9
- ## What is Joycraft?
10
-
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), [GitHub Copilot](https://github.com/features/copilot), and [omp](https://github.com/can1357/oh-my-pi): skills, behavioral boundaries, templates, and a docs structure that matures with your project.
12
-
13
- ```bash
14
- cd /path/to/your/project
15
- npx joycraft@latest update
7
+ Joycraft helps your coding agent do larger work without losing track. You say what
8
+ you want. The agent writes it down, splits it into small steps, and builds each step
9
+ with tests. Then a second agent checks each step before it counts as done.
10
+
11
+ ## Install: paste this into your coding agent
12
+
13
+ Open your coding agent in your project (Claude Code, Codex, Pi, Oh My Pi, GitHub
14
+ Copilot CLI or OpenCode) and paste:
15
+
16
+ ```text
17
+ Install Joycraft in this project.
18
+ 1. Run `npx joycraft@latest init . --plan --json`. Show me the files it will add in a short table. Do not change anything yet.
19
+ 2. Ask me which coding agents I use in this project (default: you). Then run
20
+ `npx joycraft@latest init . --harness <agents> --yes`.
21
+ If it finds Joycraft 0.7, stop and show me its migration plan.
22
+ 3. Use the joycraft-entry skill to set up this project. If the project is new or empty,
23
+ ask me what I want to build.
24
+ 4. Run `node .joycraft/runtime/review-tools.mjs plan --root .`. Tell me which tools
25
+ you need to check your own work, which ones I have, and which ones are missing.
26
+ Ask me before you install anything.
27
+ Do not commit, publish, or ask me for API keys.
16
28
  ```
17
29
 
18
- Existing scripts may use the equivalent alias `npx joycraft@latest init` for a
19
- fresh install.
20
-
21
- Joycraft is a **curated harness, not a memory system**. Everything it writes is in-repo, reviewed in your PRs, and reaped when it stops earning its keep — the opposite of hidden state that accretes until it misleads. Code is the truth about how your project works; the harness holds only what code cannot say (intent, decisions and their rationale, product direction), and `/joycraft-optimize`'s Reaper pass is what keeps it honest. If your agent already keeps its own automatic memory, a Joycraft project supersedes it: the same facts get one home that your whole team can see and review.
22
-
23
- ## Contents
24
-
25
- - [Install](#install) · [Use](#use) · [Upgrade](#upgrade-and-update)
26
- - [Setup walkthrough](docs/guides/setup-walkthrough.md) — every step from install to first feature
27
- - [Which skill do I need?](#which-skill-do-i-need) — the skill table and the core loop
28
- - [What init creates](#what-init-creates)
29
- - [Platform support](docs/guides/platform-support.md) — Claude Code, Codex, Pi, Copilot, omp, stacks, headless Pi
30
- - [Upgrading](docs/guides/upgrading.md) — the unified install/update command and recovery paths
31
- - [Releasing](docs/guides/releasing.md) — candidate verification, promotion, and retry recovery
32
- - [Git tracking](docs/guides/git-tracking.md) — shared vs private profiles, reviewable PRs
33
- - [Migration: flat → per-feature layout](docs/guides/migration-per-feature-layout.md) — the v0.6 docs move
34
- - [The levels](docs/guides/levels.md) — Dan Shapiro's 5 Levels, where Joycraft aims, and the credits
35
- - [Security](SECURITY.md) · [Guides](#guides) · [Why Joycraft?](#why-joycraft)
36
- - [Contributing](CONTRIBUTING.md) · [Acknowledgments](#acknowledgments) · [Changelog](CHANGELOG.md) · [License](LICENSE)
37
-
38
- ## Install
39
-
40
- ```bash
41
- cd /path/to/your/project
42
- npx joycraft@latest update
30
+ **Upgrading from 0.7?** Nothing changes until you choose. On a 0.7 project,
31
+ `npx joycraft@latest update .` shows the migration plan and stops. Read
32
+ [Migrating from 0.7](docs/migrating-from-0.7.md), or paste the
33
+ [upgrade prompt](docs/prompts.md#upgrade-from-07). To stay on 0.7:
34
+ `npx joycraft@0.7.17 update`.
35
+
36
+ ## How to use it
37
+
38
+ After the install, talk to your agent as usual. Joycraft takes over when the work is
39
+ bigger than one quick change:
40
+
41
+ 1. **You say what you want.** The agent asks a few questions. Then it writes a short
42
+ brief that ends with "Done when": the result you will accept. You approve it.
43
+ 2. **The agent splits the brief into specs.** A spec is one small step that it can
44
+ build and test alone.
45
+ 3. **The agent builds each spec with tests.**
46
+ 4. **A second agent checks each spec.** It did not write the code. It reads the spec,
47
+ runs the checks, and says PASS or FAIL. Only a PASS completes the spec. For a
48
+ screen or page, it looks at the real result in a browser or simulator, if you
49
+ installed those tools in step 4 of the install.
50
+ 5. **The agent wraps up.** It records what it learned for the next session.
51
+
52
+ On a new, empty project, the agent first asks what you want to build. It writes your
53
+ answers to `docs/context/project.md`. It does not choose a stack or write app code at
54
+ this step.
55
+
56
+ ## The context map: your project's memory
57
+
58
+ `AGENTS.md` holds a short context map. Each line links one project document and
59
+ says when to read it. The documents live in `docs/context/`: what the project is,
60
+ who it is for, the decisions you made and why. Before each piece of work, the agent
61
+ uses the map to find the documents and the code that apply.
62
+
63
+ The map grows with the project:
64
+
65
+ - **New facts go to one home.** When you decide something, the agent records it in
66
+ the decision log. It updates an existing document; it does not make a copy.
67
+ - **Finished work becomes history.** A completed feature moves to `docs/archive/`.
68
+ The agent can check it later to catch a regression.
69
+ - **Mistakes become lessons.** When the checking agent fails a spec, the cause can
70
+ become a short note for the next agent.
71
+ - **Ideas for later stay visible.** A choice you put off is marked "backlogged". It
72
+ stays out of the current work, but it is not lost.
73
+
74
+ You can feed it too. Give your agent meeting notes, a photo of a whiteboard or a
75
+ screenshot, and ask it to add what matters to the project context. This gives the
76
+ agent both views: the whole project and the detail of the current step.
77
+
78
+ ## Answering questions: the decision page
79
+
80
+ When the agent needs you to choose between options, it shows the questions on a
81
+ decision page instead of in chat. Each question shows its context, its options and
82
+ what it affects. You pick an answer, add a note if you want, and save. The answers
83
+ go into the brief, so the agent does not ask again.
84
+
85
+ Sometimes the agent forgets and lists the options in chat. Then say:
86
+
87
+ ```text
88
+ Put these questions in a Joycraft decision artifact so I can answer them there.
43
89
  ```
44
90
 
45
- Answer a few questions — which harnesses to install, whether to commit them, and (with Claude Code) whether to turn off auto-memory for this project — and `update` does the rest: detects your stack, writes `AGENTS.md`/`CLAUDE.md` with your real build/test commands, installs the skills. On later runs, unmodified vendor files refresh while customizations are preserved for review.
46
-
47
- `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).
48
-
49
- ## Use
50
-
51
- Inside your AI tool, drive everything with slash commands:
91
+ **Colors.** The page uses a light or dark theme. To match your project, ask:
52
92
 
53
- ```
54
- /joycraft-setup # first run — onboarding, where to begin
55
- /joycraft-new-feature # interview → Feature Brief → atomic specs
56
- /joycraft-implement-feature docs/features/<slug>/ # run the whole spec queue, TDD per spec
57
- /joycraft-session-end # wrap up: validate, graduate specs, push/PR
58
- /joycraft-tune # score your harness, apply upgrades
93
+ ```text
94
+ Use our design system's colors for Joycraft artifacts.
59
95
  ```
60
96
 
61
- 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).
97
+ The agent reads your project's color tokens and saves them in
98
+ `.joycraft/preferences.json`. You can also give it your own colors. Joycraft
99
+ refuses colors that make text or buttons hard to read.
62
100
 
63
- ## Upgrade and update
101
+ ## What Joycraft is
64
102
 
65
- ```bash
66
- npx joycraft@latest update
67
- ```
103
+ Joycraft is a set of agent skills and a small set of scripts. It installs into your
104
+ project:
68
105
 
69
- Run this from the project root. In a fresh interactive project it asks which harnesses to install. In CI or another unattended fresh project, provide an explicit selection, for example `--harnesses codex --non-interactive`. On an existing project it reads the shared or private installation manifest and preserves the selected harnesses, local content, unrelated configuration, and unknown state fields. `--yes` applies safe changes while preserving customized files; it is not blanket permission to overwrite them. Use `--preview` to review the actual plan, `--replace-customized <paths...>` for reviewed replacements, and `--repair <paths...>` for explicitly restoring missing managed files. Details, policies, bridge behavior, and exit codes are in [Upgrading](docs/guides/upgrading.md).
106
+ - Skills in `.claude/skills/` (Claude Code) or `.agents/skills/` (all other agents)
107
+ - Scripts and templates in `.joycraft/`
108
+ - Project notes in `AGENTS.md`, `CLAUDE.md` and `docs/`. These are yours: Joycraft
109
+ adds to them and never removes them.
70
110
 
71
- `init` and `upgrade` remain supported aliases into the same update engine. `init` is the friendly fresh-install entry point; `upgrade` keeps older automation working. If npm fails with `ETARGET` before Joycraft starts, retry with an online npm metadata refresh:
111
+ All of it lives in your repository. Joycraft collects no data and does not call an AI
112
+ model itself. Its only network use is the version check below. Joycraft 1.0 adds no
113
+ hooks and changes no agent settings.
72
114
 
73
- ```bash
74
- npm --prefer-online exec --yes -- joycraft@latest update
75
- ```
115
+ ## Updates
76
116
 
77
- The launcher resolves one exact candidate. The executing bundle does not silently resolve `latest` again. After a successful update, reinvoke the active skill or restart the agent session so it loads the new instructions.
117
+ At the start of a session, your agent checks npm for a newer Joycraft, at most once a
118
+ day. The check sends no project data. If there is a new version, the agent tells you
119
+ what changed and asks: update now, not now, or turn off. On a yes, it does the update
120
+ for you, checks the result, and tells you what is different. A new major version is
121
+ always your choice.
78
122
 
79
- Update checks are local to each project. The default `notify` policy keeps a 24-hour cache, uses a short bounded request, and stays quiet when offline or unavailable. `auto-safe` is an explicit local opt-in and still requires the reviewed candidate descriptor and every safety gate; `off` disables notices. See [Upgrading](docs/guides/upgrading.md#update-checks-and-policies).
123
+ This is an instruction the agent follows, so it can forget. To check yourself, ask:
80
124
 
81
- ```bash
82
- npx joycraft@latest telemetry
125
+ ```text
126
+ Check for a Joycraft update.
83
127
  ```
84
128
 
85
- Scans your Claude Code, Pi, omp, and (best-effort) Codex session transcripts and records which knowledge-layer docs your agents actually read. The result is a gitignored, machine-local file at `docs/.joycraft/telemetry.json` — paths and counters only, never transcript content. `/joycraft-session-end` runs this scan for you; `/joycraft-optimize` cites the counts when it judges which docs earn their place.
86
-
87
- ## What init creates
88
-
89
- - **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
90
- - **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
91
- - **22 skills** — installed to `.claude/skills/` (Claude Code), `.agents/skills/` (Codex), `.pi/skills/` (Pi), `.github/skills/` (Copilot), and/or `.omp/skills/` (omp, invoked as `/skill:joycraft-*`); Pi also gets the headless pipeline runtime in `.pi/scripts/joycraft/`
92
- - **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 records shared installation identity in `docs/.joycraft/manifest.json` and the shared checker in `docs/.joycraft/check.mjs`. Private manifests, personal preferences, and caches stay in the gitignored `docs/.joycraft/local/` directory. Read telemetry stays local too
93
- - **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)
129
+ ## Hosts
94
130
 
95
- Re-running on an existing project is covered in [Git tracking](docs/guides/git-tracking.md#re-running-init-on-an-existing-project).
96
-
97
- ## The Workflow
98
-
99
- ### Which skill do I need?
100
-
101
- | You want to... | Use | What happens |
131
+ | Host | Skills | Tested |
102
132
  |---|---|---|
103
- | Brainstorm an idea before committing to building it | `/joycraft-interview` | Free-form conversation → structured draft brief |
104
- | Build a new feature from scratch | `/joycraft-new-feature` | Guided interview → Feature Brief → Atomic Specs |
105
- | Understand existing code before building on it | `/joycraft-research` | Objective codebase research — facts only, no opinions |
106
- | Align on approach before writing code | `/joycraft-design` | Design discussion → ~200-line artifact for human review |
107
- | Break a feature into small, independent tasks | `/joycraft-decompose` | Feature Brief → testable Atomic Specs |
108
- | Fix a bug with a structured workflow | `/joycraft-bugfix` | Reproduce → isolate → fix → verify loop |
109
- | Implement a spec with TDD | `/joycraft-implement` | Read spec → failing tests → implement until green → wrap up → continue the queue |
110
- | Run a feature's whole spec queue from one command | `/joycraft-implement-feature` | Fresh-context subagent per spec → fail-fast → session-end once |
111
- | Run specs autonomously without hand-holding | `/joycraft-implement-level5` | Experimental — autofix loop + holdout scenario testing |
112
- | Verify an implementation independently | `/joycraft-verify` | Read-only subagent checks work against the spec |
113
- | Wrap up when a feature's specs are done | `/joycraft-session-end` | Consolidate discoveries → validate → graduate specs → ledger row → telemetry scan → push/PR |
114
- | Assess and mature your harness | `/joycraft-tune` | Score 7 dimensions → apply fixes → maturity roadmap; flags folder-map drift and auto-memory graduation |
115
- | Audit harness overhead and prune | `/joycraft-optimize` | Six-disposition self-audit backed by read telemetry; its Reaper pass retires shipped/abandoned feature folders |
116
- | Set up Joycraft for a team | `/joycraft-collaborative-setup` | Scaffold `docs/areas/`, owner conventions, a team CONTRIBUTING doc |
117
-
118
- The core loop:
119
-
120
- ```mermaid
121
- flowchart LR
122
- A[Interview] --> B[Feature Brief]
123
- B --> C{Complex?}
124
- C -- "Simple" --> F[Decompose]
125
- C -- "Complex" --> D[Research]
126
- D --> E[Design]
127
- E --> F
128
- F --> G[Atomic Specs]
129
- G --> H[Implement]
130
- H --> I[Session End]
131
-
132
- style A fill:#fff,stroke:#333,stroke-width:2px
133
- style B fill:#fff,stroke:#333,stroke-width:2px
134
- style C fill:#fff,stroke:#333,stroke-width:2px
135
- style D fill:#e8e8e8,stroke:#333,stroke-width:2px
136
- style E fill:#e8e8e8,stroke:#333,stroke-width:2px
137
- style F fill:#fff,stroke:#333,stroke-width:2px
138
- style G fill:#fff,stroke:#333,stroke-width:2px
139
- style H fill:#333,stroke:#333,color:#fff,stroke-width:2px
140
- style I fill:#333,stroke:#333,color:#fff,stroke-width:2px
141
- ```
133
+ | Claude Code | `.claude/skills/` | Yes |
134
+ | Codex | `.agents/skills/` | Yes |
135
+ | Pi | `.agents/skills/` | Yes |
136
+ | Oh My Pi | `.agents/skills/` | Yes |
137
+ | GitHub Copilot CLI | `.agents/skills/` | Installs; full run not tested yet |
138
+ | OpenCode | `.agents/skills/` | Installs; full run not tested yet |
142
139
 
143
- ## Guides
140
+ "Tested" means: we installed Joycraft in a test project, one agent built a spec, and
141
+ a second, separate agent checked it and passed it.
144
142
 
145
- | Guide | What it covers |
146
- |---|---|
147
- | [Setup walkthrough](docs/guides/setup-walkthrough.md) | Every step from `npm install` to your first shipped feature |
148
- | [The interview](docs/guides/interview-workflow.md) | The structured interview that replaces prompt-iterate-fix — the single biggest upgrade Joycraft makes |
149
- | [Research and design](docs/guides/research-and-design.md) | Objective research via context isolation, and 200-line design checkpoints before decomposition |
150
- | [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 |
151
- | [Tuning: risk interview and git autonomy](docs/guides/tuning.md) | The 2–3 minute risk interview that generates your safety boundaries |
152
- | [Token discipline](docs/guides/token-discipline.md) | Why file artifacts at every step make your conversation context disposable |
153
- | [Permission modes](docs/guides/permission-modes.md) | Why you do **not** need `--dangerously-skip-permissions` |
154
- | [Agent compatibility](docs/guides/agent-compatibility.md) | How CLAUDE.md and AGENTS.md stay one source across every supported tool |
155
- | [Level 5: the autonomous loop](docs/guides/level-5-autonomy.md) | Experimental — workflows, holdout scenarios, and what it really costs |
156
- | [Methodology](docs/guides/methodology.md) | Why this exists: METR's slowdown finding and the teams that beat it |
143
+ ## Commands
157
144
 
158
- ## Why Joycraft?
145
+ Your agent runs these for you. They are here if you want them:
159
146
 
160
- 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.
161
-
162
- 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).
163
-
164
- ## Security
165
-
166
- 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).
167
-
168
- ## Contributing
169
-
170
- Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
171
-
172
- The short version:
147
+ ```bash
148
+ npx joycraft@latest init . --harness claude,codex --yes # install
149
+ npx joycraft@latest update . --yes # update (backs up files you edited first)
150
+ npx joycraft@latest doctor . # check the install
151
+ npx joycraft@latest update . --migrate --archive-custom --yes # move a 0.7 project to 1.0
152
+ npx joycraft@latest rollback --yes # undo the move to 1.0
153
+ ```
173
154
 
174
- 1. Fork, branch from `main`
175
- 2. `pnpm install && pnpm test` to verify your setup
176
- 3. Write tests first, then implement
177
- 4. `pnpm test && pnpm typecheck && pnpm build`
178
- 5. Open a PR (one approval required)
155
+ Add `--plan --json` to see the changes without making them. Without `--yes`, and
156
+ outside a terminal, a command shows its plan and stops. It never waits for input.
179
157
 
180
- Look for [`good first issue`](https://github.com/maksutovic/joycraft/labels/good%20first%20issue) labels if you're new. Areas we'd especially love help with: stack detection for new languages, skill improvements, and documentation.
158
+ More: [Install guide](docs/install.md) · [Migrating from 0.7](docs/migrating-from-0.7.md) ·
159
+ [Prompts](docs/prompts.md) · [Changelog](CHANGELOG.md) · [Security](SECURITY.md) ·
160
+ [Contributing](CONTRIBUTING.md) · [License](LICENSE)
181
161
 
182
162
  ## Acknowledgments
183
163
 
184
- The curated-harness stance above was shaped by people thinking out loud about what agents should and shouldn't remember:
164
+ These people shaped how Joycraft decides what an agent should keep and what it
165
+ should forget:
185
166
 
186
- - **Mario Zechner** (creator of [Pi](https://github.com/earendil-works/pi-coding-agent)) and **Armin Ronacher** (creator of Flask) — "code is truth" and the minimal-harness thesis: no separate memory system for knowledge the code already carries.
187
- - **Theo Browne** ([t3.gg](https://t3.gg)) — the write-vs-read memory audit that turned decay into something measurable, and the case for directional rather than rule-heavy AGENTS.md content.
188
- - **Lauren** (Cursor) — the intervention-elimination hierarchy: architecture beats lint and CI, which beat skills and rules, which beat asking a human.
189
- - **Robert C. Martin** — impose values, not disciplines.
167
+ - **Mario Zechner** (creator of [Pi](https://github.com/earendil-works/pi-coding-agent)) and **Armin Ronacher** (creator of Flask): "code is truth". Do not keep a separate memory of what the code already says.
168
+ - **Theo Browne** ([t3.gg](https://t3.gg)): measure which notes an agent actually reads, and keep `AGENTS.md` short and directional.
169
+ - **Lauren** (Cursor): prefer fixes in this order: architecture, then lint and CI, then skills and rules, then asking a human.
170
+ - **Robert C. Martin**: impose values, not disciplines.
190
171
 
191
- The levels this project aims at are Dan Shapiro's; those credits live in [The levels](docs/guides/levels.md).
172
+ The levels this project aims at are Dan Shapiro's. See [The levels](docs/guides/levels.md).
192
173
 
193
174
  ## License
194
175
 
195
- MIT. See [LICENSE](LICENSE) for details.
176
+ MIT. See [LICENSE](LICENSE).