joycraft 0.6.17 → 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 +37 -11
- package/dist/chunk-EBOHEHSG.js +44 -0
- package/dist/chunk-EBOHEHSG.js.map +1 -0
- package/dist/{chunk-3JVMOJTA.js → chunk-MZZDO5Q6.js} +13 -13
- package/dist/chunk-MZZDO5Q6.js.map +1 -0
- package/dist/cli.js +3 -3
- package/dist/{init-OO77DURX.js → init-H4D6UK4L.js} +35 -15
- package/dist/init-H4D6UK4L.js.map +1 -0
- package/dist/{init-autofix-6GMXHF5F.js → init-autofix-AAVNXIQE.js} +2 -2
- package/dist/{upgrade-VKQ54KRD.js → upgrade-PKMZN7UI.js} +5 -3
- package/dist/upgrade-PKMZN7UI.js.map +1 -0
- package/package.json +1 -1
- package/dist/chunk-3JVMOJTA.js.map +0 -1
- package/dist/chunk-IELXGWSH.js +0 -21
- package/dist/chunk-IELXGWSH.js.map +0 -1
- package/dist/init-OO77DURX.js.map +0 -1
- package/dist/upgrade-VKQ54KRD.js.map +0 -1
- /package/dist/{init-autofix-6GMXHF5F.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)
|
|
@@ -125,6 +129,28 @@ edits are append-only — Joycraft never rewrites or removes your existing lines
|
|
|
125
129
|
> `npx joycraft init` to regenerate them locally. Joycraft adds a one-line
|
|
126
130
|
> reminder to your generated `CLAUDE.md` and `AGENTS.md` for exactly this reason.
|
|
127
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
|
+
|
|
128
154
|
### Supported Stacks
|
|
129
155
|
|
|
130
156
|
Node.js (npm/pnpm/yarn/bun), Python (poetry/pip/uv), Rust, Go, Swift, and generic (Makefile/Dockerfile).
|
|
@@ -145,7 +171,7 @@ Frameworks auto-detected: Next.js, FastAPI, Django, Flask, Actix, Axum, Express,
|
|
|
145
171
|
| Fix a bug with a structured workflow | `/joycraft-bugfix` | Reproduce → isolate → fix → verify loop |
|
|
146
172
|
| Implement a spec with TDD | `/joycraft-implement` | Read spec → failing tests → implement until green → wrap up → continue the queue |
|
|
147
173
|
| Run a feature's whole spec queue from one command | `/joycraft-implement-feature` | Fresh-context subagent per spec → fail-fast → session-end once |
|
|
148
|
-
| 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 |
|
|
149
175
|
| Verify an implementation independently | `/joycraft-verify` | Read-only subagent checks work against the spec |
|
|
150
176
|
| Set up Joycraft for a team | `/joycraft-collaborative-setup` | Scaffold `docs/areas/`, owner conventions, a team CONTRIBUTING doc |
|
|
151
177
|
|
|
@@ -194,9 +220,9 @@ A 2-3 minute risk interview generates safety boundaries, and you choose your git
|
|
|
194
220
|
|
|
195
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)
|
|
196
222
|
|
|
197
|
-
### Level 5: The Autonomous Loop
|
|
223
|
+
### Level 5: The Autonomous Loop (experimental)
|
|
198
224
|
|
|
199
|
-
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)
|
|
200
226
|
|
|
201
227
|
### Permission Modes
|
|
202
228
|
|
|
@@ -204,7 +230,7 @@ You do **not** need `--dangerously-skip-permissions` for autonomous development.
|
|
|
204
230
|
|
|
205
231
|
### How It Works with AI Agents
|
|
206
232
|
|
|
207
|
-
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)
|
|
208
234
|
|
|
209
235
|
## Upgrade
|
|
210
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"]}
|