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 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)
@@ -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` | Autofix loop + holdout scenario testing |
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 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)
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-G6WSFZQG.js.map
87
+ //# sourceMappingURL=chunk-GWDLD7SH.js.map