joycraft 0.6.17 → 0.6.19

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,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 autonomous spec-driven development — and on Pi, to fully headless spec execution.
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
- - **Levels 1-4:** 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.
16
- - **Level 5:** The `/joycraft-implement-level5` skill sets up the autonomous loop where specs go in and validated software comes out, with holdout scenario testing that prevents the agent from gaming its own tests.
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` sets up the autonomous loop |
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 move you up.
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
- - **CLAUDE.md** with behavioral boundaries (Always / Ask First / Never) and correct build/test/lint commands
84
- - **AGENTS.md** for Codex/Pi compatibility
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` | Autofix loop + holdout scenario testing |
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 reads AGENTS.md — both get the same guardrails and workflow. [Read the full guide →](docs/guides/agent-compatibility.md)
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"]}