joycraft 0.6.16 → 0.6.18
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 +39 -11
- package/dist/chunk-EBOHEHSG.js +44 -0
- package/dist/chunk-EBOHEHSG.js.map +1 -0
- package/dist/{chunk-G6WSFZQG.js → chunk-GWDLD7SH.js} +2 -1
- package/dist/{chunk-UEG5IO6Q.js → chunk-MZZDO5Q6.js} +13 -13
- package/dist/chunk-MZZDO5Q6.js.map +1 -0
- package/dist/cli.js +4 -4
- package/dist/{init-WPKDBQDN.js → init-H4D6UK4L.js} +58 -19
- package/dist/init-H4D6UK4L.js.map +1 -0
- package/dist/{init-autofix-ESN27L3W.js → init-autofix-AAVNXIQE.js} +2 -2
- package/dist/{upgrade-LKX25GTT.js → upgrade-PKMZN7UI.js} +34 -7
- package/dist/upgrade-PKMZN7UI.js.map +1 -0
- package/package.json +1 -1
- package/dist/chunk-IELXGWSH.js +0 -21
- package/dist/chunk-IELXGWSH.js.map +0 -1
- package/dist/chunk-UEG5IO6Q.js.map +0 -1
- package/dist/init-WPKDBQDN.js.map +0 -1
- package/dist/upgrade-LKX25GTT.js.map +0 -1
- /package/dist/{chunk-G6WSFZQG.js.map → chunk-GWDLD7SH.js.map} +0 -0
- /package/dist/{init-autofix-ESN27L3W.js.map → init-autofix-AAVNXIQE.js.map} +0 -0
package/README.md
CHANGED
|
@@ -8,12 +8,12 @@
|
|
|
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), and [Pi](https://github.com/earendil-works/pi-coding-agent), along with behavioral boundaries, templates, and documentation structure. It takes any project from unstructured prompting to
|
|
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), and [Pi](https://github.com/earendil-works/pi-coding-agent), 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
12
|
|
|
13
13
|
### The core idea
|
|
14
14
|
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
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
17
|
|
|
18
18
|
### What are the levels?
|
|
19
19
|
|
|
@@ -25,9 +25,13 @@ Joycraft is a CLI tool that installs structured development skills into [Claude
|
|
|
25
25
|
| 2 | Junior Developer | Prompt → iterate → fix → repeat | `/joycraft-tune` assesses where you are |
|
|
26
26
|
| 3 | Developer as Manager | Your life is reviewing diffs | Behavioral boundaries in CLAUDE.md |
|
|
27
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`
|
|
28
|
+
| 5 | Software Factory | Specs in, validated software out | `/joycraft-implement-level5` (experimental) |
|
|
29
29
|
|
|
30
|
-
Most developers plateau at Level 2. Joycraft's job is to
|
|
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.
|
|
31
35
|
|
|
32
36
|
### Platform support
|
|
33
37
|
|
|
@@ -80,8 +84,8 @@ npx joycraft init
|
|
|
80
84
|
|
|
81
85
|
`init` first asks which harnesses to install (see [Platform support](#platform-support) above), then auto-detects your tech stack and creates:
|
|
82
86
|
|
|
83
|
-
- **
|
|
84
|
-
- **
|
|
87
|
+
- **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
|
|
88
|
+
- **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
|
|
85
89
|
- **20 skills** installed to the selected harnesses — `.claude/skills/` (Claude Code), `.agents/skills/` (Codex), and/or `.pi/skills/` (Pi) — see [Which skill do I need?](#which-skill-do-i-need) below
|
|
86
90
|
- **Pi pipeline runtime** in `.pi/scripts/joycraft/` (when Pi is selected) — the headless spec-execution driver and its helpers
|
|
87
91
|
- **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)
|
|
@@ -91,6 +95,8 @@ npx joycraft init
|
|
|
91
95
|
|
|
92
96
|
> Pick nothing at the harness prompt and `init` installs nothing — it tells you to re-run and choose at least one harness.
|
|
93
97
|
|
|
98
|
+
**`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.
|
|
99
|
+
|
|
94
100
|
### Git tracking: shared vs private
|
|
95
101
|
|
|
96
102
|
By default Joycraft assumes you want to **commit** the harness so your whole team
|
|
@@ -123,6 +129,28 @@ edits are append-only — Joycraft never rewrites or removes your existing lines
|
|
|
123
129
|
> `npx joycraft init` to regenerate them locally. Joycraft adds a one-line
|
|
124
130
|
> reminder to your generated `CLAUDE.md` and `AGENTS.md` for exactly this reason.
|
|
125
131
|
|
|
132
|
+
### Reviewable PRs: workflow docs are collapsed
|
|
133
|
+
|
|
134
|
+
Joycraft's docs are two kinds of content. Durable knowledge — `CLAUDE.md`,
|
|
135
|
+
`AGENTS.md`, `docs/context/` — steers every future agent run and deserves review
|
|
136
|
+
eyes. Workflow exhaust — feature briefs and specs, discoveries, installed
|
|
137
|
+
templates — is historical by the time a PR is opened (the spec was reviewed in
|
|
138
|
+
conversation when it was written). To keep PRs reviewable, `init` and `upgrade`
|
|
139
|
+
write a `.gitattributes` marking the exhaust paths `linguist-generated=true`:
|
|
140
|
+
|
|
141
|
+
```gitattributes
|
|
142
|
+
docs/features/** linguist-generated=true
|
|
143
|
+
docs/bugfixes/** linguist-generated=true
|
|
144
|
+
docs/discoveries/** linguist-generated=true
|
|
145
|
+
docs/templates/** linguist-generated=true
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
GitHub collapses these files in the Files Changed view and excludes them from
|
|
149
|
+
diff stats — reviewers see your code and your durable knowledge, and any
|
|
150
|
+
collapsed doc is one click from expanding. The write is append-only and
|
|
151
|
+
idempotent (your existing `.gitattributes` lines are never touched); delete any
|
|
152
|
+
line to opt that path back into full review.
|
|
153
|
+
|
|
126
154
|
### Supported Stacks
|
|
127
155
|
|
|
128
156
|
Node.js (npm/pnpm/yarn/bun), Python (poetry/pip/uv), Rust, Go, Swift, and generic (Makefile/Dockerfile).
|
|
@@ -143,7 +171,7 @@ Frameworks auto-detected: Next.js, FastAPI, Django, Flask, Actix, Axum, Express,
|
|
|
143
171
|
| Fix a bug with a structured workflow | `/joycraft-bugfix` | Reproduce → isolate → fix → verify loop |
|
|
144
172
|
| Implement a spec with TDD | `/joycraft-implement` | Read spec → failing tests → implement until green → wrap up → continue the queue |
|
|
145
173
|
| Run a feature's whole spec queue from one command | `/joycraft-implement-feature` | Fresh-context subagent per spec → fail-fast → session-end once |
|
|
146
|
-
| Run specs autonomously without hand-holding | `/joycraft-implement-level5` |
|
|
174
|
+
| Run specs autonomously without hand-holding | `/joycraft-implement-level5` | Experimental — autofix loop + holdout scenario testing |
|
|
147
175
|
| Verify an implementation independently | `/joycraft-verify` | Read-only subagent checks work against the spec |
|
|
148
176
|
| Set up Joycraft for a team | `/joycraft-collaborative-setup` | Scaffold `docs/areas/`, owner conventions, a team CONTRIBUTING doc |
|
|
149
177
|
|
|
@@ -192,9 +220,9 @@ A 2-3 minute risk interview generates safety boundaries, and you choose your git
|
|
|
192
220
|
|
|
193
221
|
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)
|
|
194
222
|
|
|
195
|
-
### Level 5: The Autonomous Loop
|
|
223
|
+
### Level 5: The Autonomous Loop (experimental)
|
|
196
224
|
|
|
197
|
-
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. [Read the full guide →](docs/guides/level-5-autonomy.md)
|
|
225
|
+
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)
|
|
198
226
|
|
|
199
227
|
### Permission Modes
|
|
200
228
|
|
|
@@ -202,7 +230,7 @@ You do **not** need `--dangerously-skip-permissions` for autonomous development.
|
|
|
202
230
|
|
|
203
231
|
### How It Works with AI Agents
|
|
204
232
|
|
|
205
|
-
Claude Code reads CLAUDE.md, Codex
|
|
233
|
+
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)
|
|
206
234
|
|
|
207
235
|
## Upgrade
|
|
208
236
|
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// src/gitattributes.ts
|
|
4
|
+
import { existsSync, readFileSync, writeFileSync } from "fs";
|
|
5
|
+
import { join } from "path";
|
|
6
|
+
var GITATTRIBUTES_COMMENT = "# Joycraft: collapse generated workflow docs in PR review (expand with one click)";
|
|
7
|
+
var GITATTRIBUTES_ENTRIES = [
|
|
8
|
+
"docs/features/** linguist-generated=true",
|
|
9
|
+
"docs/bugfixes/** linguist-generated=true",
|
|
10
|
+
"docs/discoveries/** linguist-generated=true",
|
|
11
|
+
"docs/templates/** linguist-generated=true"
|
|
12
|
+
];
|
|
13
|
+
function applyGitattributes(targetDir) {
|
|
14
|
+
const gitattributesPath = join(targetDir, ".gitattributes");
|
|
15
|
+
const current = existsSync(gitattributesPath) ? readFileSync(gitattributesPath, "utf-8") : "";
|
|
16
|
+
const present = new Set(current.split("\n").map((l) => l.trim()));
|
|
17
|
+
const missing = GITATTRIBUTES_ENTRIES.filter((e) => !present.has(e.trim()));
|
|
18
|
+
if (missing.length === 0) return [];
|
|
19
|
+
const lines = present.has(GITATTRIBUTES_COMMENT) ? missing : [GITATTRIBUTES_COMMENT, ...missing];
|
|
20
|
+
const sep = current.length > 0 && !current.endsWith("\n") ? "\n" : "";
|
|
21
|
+
writeFileSync(gitattributesPath, current + sep + lines.join("\n") + "\n", "utf-8");
|
|
22
|
+
return missing;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
// src/package-version.ts
|
|
26
|
+
import { readFileSync as readFileSync2 } from "fs";
|
|
27
|
+
import { fileURLToPath } from "url";
|
|
28
|
+
import { dirname, join as join2 } from "path";
|
|
29
|
+
var __dirname = dirname(fileURLToPath(import.meta.url));
|
|
30
|
+
function getPackageVersion() {
|
|
31
|
+
const pkgPath = join2(__dirname, "..", "package.json");
|
|
32
|
+
const raw = readFileSync2(pkgPath, "utf-8");
|
|
33
|
+
const pkg = JSON.parse(raw);
|
|
34
|
+
if (typeof pkg.version !== "string" || pkg.version.length === 0) {
|
|
35
|
+
throw new Error(`Joycraft package.json at ${pkgPath} is missing a version field`);
|
|
36
|
+
}
|
|
37
|
+
return pkg.version;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export {
|
|
41
|
+
applyGitattributes,
|
|
42
|
+
getPackageVersion
|
|
43
|
+
};
|
|
44
|
+
//# sourceMappingURL=chunk-EBOHEHSG.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/gitattributes.ts","../src/package-version.ts"],"sourcesContent":["import { existsSync, readFileSync, writeFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\n/**\n * Paths Joycraft marks `linguist-generated=true` so GitHub collapses them in\n * PR review and drops them from diff stats. These are workflow exhaust —\n * briefs, specs, discoveries, installed templates — historical artifacts by\n * the time a PR is opened (the spec was reviewed conversationally when it was\n * written). Reviewers can still expand any of them with one click.\n *\n * Deliberately NOT listed (durable knowledge that deserves review eyes):\n * CLAUDE.md, AGENTS.md, docs/context/ (steers every future agent run), and\n * docs/backlog/ (human-authored idea capture).\n */\nexport const GITATTRIBUTES_COMMENT =\n '# Joycraft: collapse generated workflow docs in PR review (expand with one click)';\n\nexport const GITATTRIBUTES_ENTRIES = [\n 'docs/features/** linguist-generated=true',\n 'docs/bugfixes/** linguist-generated=true',\n 'docs/discoveries/** linguist-generated=true',\n 'docs/templates/** linguist-generated=true',\n];\n\n/**\n * Append-only, create-if-absent, idempotent .gitattributes writer — the same\n * contract as ensureGitignoreEntries: never rewrites, reorders, or removes\n * existing lines; only appends entries not already present (matched exactly,\n * after trimming). The comment header is only added when at least one entry\n * is missing, so a fully-applied file is never touched. Returns the entries\n * actually added (empty when everything was already present).\n */\nexport function applyGitattributes(targetDir: string): string[] {\n const gitattributesPath = join(targetDir, '.gitattributes');\n const current = existsSync(gitattributesPath) ? readFileSync(gitattributesPath, 'utf-8') : '';\n const present = new Set(current.split('\\n').map((l) => l.trim()));\n const missing = GITATTRIBUTES_ENTRIES.filter((e) => !present.has(e.trim()));\n if (missing.length === 0) return [];\n\n const lines = present.has(GITATTRIBUTES_COMMENT) ? missing : [GITATTRIBUTES_COMMENT, ...missing];\n const sep = current.length > 0 && !current.endsWith('\\n') ? '\\n' : '';\n writeFileSync(gitattributesPath, current + sep + lines.join('\\n') + '\\n', 'utf-8');\n return missing;\n}\n","import { readFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { dirname, join } from 'node:path';\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\n\nexport function getPackageVersion(): string {\n const pkgPath = join(__dirname, '..', 'package.json');\n const raw = readFileSync(pkgPath, 'utf-8');\n const pkg = JSON.parse(raw) as { version?: unknown };\n if (typeof pkg.version !== 'string' || pkg.version.length === 0) {\n throw new Error(`Joycraft package.json at ${pkgPath} is missing a version field`);\n }\n return pkg.version;\n}\n"],"mappings":";;;AAAA,SAAS,YAAY,cAAc,qBAAqB;AACxD,SAAS,YAAY;AAad,IAAM,wBACX;AAEK,IAAM,wBAAwB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAUO,SAAS,mBAAmB,WAA6B;AAC9D,QAAM,oBAAoB,KAAK,WAAW,gBAAgB;AAC1D,QAAM,UAAU,WAAW,iBAAiB,IAAI,aAAa,mBAAmB,OAAO,IAAI;AAC3F,QAAM,UAAU,IAAI,IAAI,QAAQ,MAAM,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAChE,QAAM,UAAU,sBAAsB,OAAO,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,KAAK,CAAC,CAAC;AAC1E,MAAI,QAAQ,WAAW,EAAG,QAAO,CAAC;AAElC,QAAM,QAAQ,QAAQ,IAAI,qBAAqB,IAAI,UAAU,CAAC,uBAAuB,GAAG,OAAO;AAC/F,QAAM,MAAM,QAAQ,SAAS,KAAK,CAAC,QAAQ,SAAS,IAAI,IAAI,OAAO;AACnE,gBAAc,mBAAmB,UAAU,MAAM,MAAM,KAAK,IAAI,IAAI,MAAM,OAAO;AACjF,SAAO;AACT;;;AC3CA,SAAS,gBAAAA,qBAAoB;AAC7B,SAAS,qBAAqB;AAC9B,SAAS,SAAS,QAAAC,aAAY;AAE9B,IAAM,YAAY,QAAQ,cAAc,YAAY,GAAG,CAAC;AAEjD,SAAS,oBAA4B;AAC1C,QAAM,UAAUA,MAAK,WAAW,MAAM,cAAc;AACpD,QAAM,MAAMD,cAAa,SAAS,OAAO;AACzC,QAAM,MAAM,KAAK,MAAM,GAAG;AAC1B,MAAI,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,WAAW,GAAG;AAC/D,UAAM,IAAI,MAAM,4BAA4B,OAAO,6BAA6B;AAAA,EAClF;AACA,SAAO,IAAI;AACb;","names":["readFileSync","join"]}
|
|
@@ -77,10 +77,11 @@ async function resolveGitignoreProfile(opts) {
|
|
|
77
77
|
}
|
|
78
78
|
|
|
79
79
|
export {
|
|
80
|
+
PRIVATE_PROFILE_IGNORES,
|
|
80
81
|
PRIVATE_DIRS_DISPLAY,
|
|
81
82
|
PRIVATE_UNTRACK_COMMAND,
|
|
82
83
|
applyGitignoreProfile,
|
|
83
84
|
validateGitignoreFlag,
|
|
84
85
|
resolveGitignoreProfile
|
|
85
86
|
};
|
|
86
|
-
//# sourceMappingURL=chunk-
|
|
87
|
+
//# sourceMappingURL=chunk-GWDLD7SH.js.map
|