joycraft 0.4.0 → 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maximilian Maksutovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,18 +1,68 @@
 # Joycraft
 
+<p align="center">
+  <img src="docs/joycraft-banner.png" alt="Joycraft — the craft of AI development" width="700" />
+</p>
+
 > The craft of AI development — with joy, not darkness.
 
-**Joycraft** is a CLI tool and Claude Code plugin that takes any project from Level 1 to Level 4 on [Dan Shapiro's 5 Levels of Vibe Coding](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/). One command gives you behavioral boundaries, atomic spec workflows, skill-driven development, and structured knowledge capture.
+## What is Joycraft?
+
+Joycraft is a CLI tool and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin that upgrades your AI development workflow. It installs skills, behavioral boundaries, templates, and documentation structure into any project — taking you from unstructured prompting to autonomous spec-driven development.
+
+If you've been using Claude Code (or any AI coding tool) and your workflow looks like this:
+
+> Prompt → wait → read output → "no, not that" → re-prompt → fix hallucination → re-prompt → manually fix → "ok close enough" → commit
+
+...then Joycraft is for you.
+
+This project started as a personal exploration by [@maksutovic](https://github.com/maksutovic). I was working across multiple client projects, spending more time wrestling with prompts than building software. I knew Claude Code was capable of extraordinary work, but my *process* was holding it back. I was vibe coding — and vibe coding doesn't scale.
+
+The spark was [Nate B Jones' video on the 5 Levels of Vibe Coding](https://www.youtube.com/watch?v=bDcgHzCBgmQ). It mapped out a progression I hadn't seen articulated before — from "spicy autocomplete" to fully autonomous development — and lit my brain up to the potential of what Claude Code could do with the right harness around it. Joycraft is the result of that exploration: a tool that encodes the patterns, boundaries, and workflows that make AI-assisted development actually deterministic.
+
+### The core idea
+
+Joycraft is simple. It's a set of **skills** (slash commands for Claude Code) and **instructions** (CLAUDE.md boundaries) that guide you and your agent through a structured development process:
+
+- **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. No back-and-forth.
+- **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.
+
+StrongDM calls their Level 5 fully autonomous loop a "Dark Factory" — which, albeit a cool name, the world has so much darkness in it right now. I wanted a name that extolled more of what I believe tools like this can provide: joy and craftsmanship. Hence "Joycraft."
+
+### What are the levels?
+
+[Dan Shapiro's 5 Levels of Vibe Coding](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) provides the framework:
+
+| Level | Name | What it looks like | Joycraft's role |
+|-------|------|--------------------|-----------------|
+| 1 | Autocomplete | Tab-complete suggestions | — |
+| 2 | Junior Developer | Prompt → iterate → fix → repeat | `/joycraft-tune` assesses where you are |
+| 3 | Developer as Manager | Your life is reviewing diffs | Behavioral boundaries in CLAUDE.md |
+| 4 | Developer as PM | You write specs, agent writes code | `/joycraft-new-feature` + `/joycraft-decompose` |
+| 5 | Software Factory | Specs in, validated software out | `/joycraft-implement-level5` sets up the autonomous loop |
 
-The name is a deliberate counter-narrative to "dark factory." Autonomous software development should bring craft and joy to engineering, not darkness.
+Most developers plateau at Level 2. Joycraft's job is to move you up.
+
+### Platform support
+
+Joycraft is currently focused on making the Claude Code experience state-of-the-art. Better [Codex](https://openai.com/codex) support is coming — `AGENTS.md` generation is already included, and deeper integration is on the roadmap.
 
 ## Quick Start
 
+First, install the CLI:
+
+```bash
+npm install -g joycraft
+```
+
+Then navigate to your project's root directory and initialize:
+
 ```bash
+cd /path/to/your/project
 npx joycraft init
 ```
 
-That's it. Joycraft auto-detects your tech stack and creates:
+Joycraft auto-detects your tech stack and creates:
 
 - **CLAUDE.md** with behavioral boundaries (Always / Ask First / Never) and correct build/test/lint commands
 - **AGENTS.md** for Codex compatibility
@@ -22,8 +72,11 @@ That's it. Joycraft auto-detects your tech stack and creates:
   - `/joycraft-interview` — Lightweight brainstorm — yap about ideas, get a structured summary
   - `/joycraft-decompose` — Break a brief into small, testable specs
   - `/joycraft-session-end` — Capture discoveries, verify, commit
+  - `/joycraft-implement-level5` — Set up Level 5: autofix loop, holdout scenarios, scenario evolution
 - **docs/** structure — `briefs/`, `specs/`, `discoveries/`, `contracts/`, `decisions/`
-- **Templates** — Atomic spec, feature brief, implementation plan, boundary framework
+- **Templates** — Atomic spec, feature brief, implementation plan, boundary framework, and workflow templates for scenario generation and autofix loops
+
+Once you reach Level 4, you can set up the autonomous loop with `/joycraft-implement-level5`. See [Level 5: The Autonomous Loop](#level-5-the-autonomous-loop) below.
 
 ### Supported Stacks
 
@@ -41,6 +94,7 @@ After init, open Claude Code and use the installed skills:
 /joycraft-new-feature           # Interview → Feature Brief → Atomic Specs → ready to execute
 /joycraft-decompose             # Break any feature into small, independent specs
 /joycraft-session-end           # Wrap up — discoveries, verification, commit
+/joycraft-implement-level5     # Set up Level 5 — autofix, holdout scenarios, evolution
 ```
 
 The core loop:
@@ -49,6 +103,54 @@ The core loop:
 Interview → Spec → Fresh Session → Execute → Discoveries → Ship
 ```
 
+## The Interview: Why It Matters
+
+The single biggest upgrade Joycraft makes to your workflow is replacing the prompt-iterate-fix cycle with a **structured interview**.
+
+Here's the problem with how most of us use AI coding tools: we open a session and start typing. "Build me a notification system." The agent starts writing code immediately. It makes assumptions about your data model, your UI framework, your error handling strategy, your deployment target. You catch some of these mid-flight, correct them, the agent adjusts, introduces new assumptions. Three hours later you have something that *kind of* works but is built on a foundation of guesses.
+
+Joycraft flips this. Before the agent writes a single line of code, you have a conversation about *what you're building and why*.
+
+### Two interview modes
+
+**`/joycraft-interview`** — The lightweight brainstorm. You yap about an idea, the agent asks clarifying questions, and you get a structured summary saved to `docs/briefs/`. Good for early-stage thinking when you're not ready to commit to building anything yet. No pressure, no specs — just organized thought.
+
+**`/joycraft-new-feature`** — The full workflow. This is the structured interview that produces a **Feature Brief** (the what and why) and then decomposes it into **Atomic Specs** (small, testable, independently executable units of work). Each spec is self-contained — an agent in a fresh session can pick it up and execute without reading anything else.
+
+### Why this works
+
+The insight comes from [Boris Cherny](https://www.lennysnewsletter.com/p/head-of-claude-code-what-happens) (Head of Claude Code at Anthropic): interview in one session, write the spec, then execute in a *fresh session* with clean context. The interview captures your intent. The spec is the contract. The execution session has only the spec — no baggage from the conversation, no accumulated misunderstandings, no context window full of abandoned approaches.
+
+This is what separates Level 2 (back-and-forth prompting) from Level 4 (spec-driven development). You stop being a typist correcting an agent's guesses and start being a PM defining what needs to be built.
+
+```mermaid
+flowchart LR
+    A["/joycraft-interview<br/>(brainstorm)"] --> B["Draft Brief<br/>docs/briefs/"]
+    B --> C["/joycraft-new-feature<br/>(structured interview)"]
+    C --> D["Feature Brief<br/>(what & why)"]
+    D --> E["/joycraft-decompose"]
+    E --> F["Atomic Specs<br/>docs/specs/"]
+    F --> G["Fresh Session<br/>Execute each spec"]
+    G --> H["/joycraft-session-end<br/>(discoveries + commit)"]
+
+    style A fill:#e8f4fd,stroke:#369
+    style C fill:#e8f4fd,stroke:#369
+    style F fill:#cfc,stroke:#393
+    style G fill:#ffd,stroke:#993
+```
+
+### What a good spec looks like
+
+An atomic spec produced by `/joycraft-decompose` has:
+
+- **What** — One paragraph. A developer with zero context understands the change in 15 seconds.
+- **Why** — One sentence. What breaks or is missing without this?
+- **Acceptance criteria** — Checkboxes. Testable. No ambiguity.
+- **Affected files** — Exact paths, what changes in each.
+- **Edge cases** — Table of scenarios and expected behavior.
+
+The agent doesn't guess. It reads the spec and executes. If something's unclear, the spec is wrong — fix the spec, not the conversation.
+
 ## Upgrade
 
 When Joycraft templates and skills evolve, update without losing your customizations:
@@ -59,9 +161,311 @@ npx joycraft upgrade
 
 Joycraft tracks what it installed vs. what you've customized. Unmodified files update automatically. Customized files show a diff and ask before overwriting. Use `--yes` for CI.
 
-## Git Autonomy
+> **Note:** If you're upgrading from an early version, deprecated skill directories (e.g., `/joy`, `/joysmith`, `/tune`) are automatically removed during upgrade.
+
+## Level 5: The Autonomous Loop
+
+> **A note on complexity:** Setting up Level 5 does have some moving parts and, depending on the complexity of your stack (software vs. hardware, monorepo vs. single app, etc.), this will require a good amount of prompting and trial-and-error to get right. I've done my best to make this as painless as possible, but just note — this is not a one-shot-prompt-done-in-5-minutes kind of thing. For small projects and simple stacks it will be easy, but any level of complexity is going to take some iteration, so plan ahead. Full step-by-step guides along with a video coming soon.
 
-When `/joycraft-tune` runs for the first time, it asks one question: **how autonomous should git be?**
+Level 5 is where specs go in and validated software comes out. Joycraft implements this as four interlocking GitHub Actions workflows, a separate scenarios repository, and two independent AI agents that can never see each other's work.
+
+Run `/joycraft-implement-level5` in Claude Code for a guided setup, or use the CLI directly:
+
+```bash
+npx joycraft init-autofix --scenarios-repo my-project-scenarios --app-id 3180156
+```
+
+### Architecture Overview
+
+Level 5 has four moving parts. Each is a GitHub Actions workflow that communicates via `repository_dispatch` events — no custom servers, no webhooks, no external services.
+
+```mermaid
+graph TB
+    subgraph "Main Repository"
+        A[Push specs to docs/specs/] -->|push to main| B[Spec Dispatch Workflow]
+        C[PR opened] --> D[CI runs]
+        D -->|CI fails| E[Autofix Workflow]
+        D -->|CI passes| F[Scenarios Dispatch Workflow]
+        G[Scenarios Re-run Workflow]
+    end
+
+    subgraph "Scenarios Repository (private)"
+        H[Scenario Generation Workflow]
+        I[Scenario Run Workflow]
+        J[Holdout Tests]
+        K[Specs Mirror]
+    end
+
+    B -->|repository_dispatch: spec-pushed| H
+    H -->|reads specs, writes tests| J
+    H -->|repository_dispatch: scenarios-updated| G
+    G -->|repository_dispatch: run-scenarios| I
+    F -->|repository_dispatch: run-scenarios| I
+    I -->|posts PASS/FAIL comment| C
+    E -->|Claude fixes code, pushes| D
+
+    style J fill:#f9f,stroke:#333
+    style K fill:#bbf,stroke:#333
+```
+
+### The Four Workflows
+
+#### 1. Autofix Workflow (`autofix.yml`)
+
+Triggered when CI **fails** on a PR. Claude Code CLI reads the failure logs and attempts a fix.
+
+```mermaid
+sequenceDiagram
+    participant CI as CI Workflow
+    participant AF as Autofix Workflow
+    participant Claude as Claude Code CLI
+    participant PR as Pull Request
+
+    CI->>AF: workflow_run (conclusion: failure)
+    AF->>AF: Generate GitHub App token
+    AF->>AF: Checkout PR branch
+    AF->>AF: Count previous autofix attempts
+
+    alt attempts >= 3
+        AF->>PR: Comment: "Human review needed"
+    else attempts < 3
+        AF->>AF: Fetch CI failure logs
+        AF->>AF: Strip ANSI codes
+        AF->>Claude: claude -p "Fix this CI failure..." <br/> --dangerously-skip-permissions --max-turns 20
+        Claude->>Claude: Read logs, edit code, run tests
+        Claude->>AF: Exit (changes committed locally)
+        AF->>PR: Push fix (commit prefix: "autofix:")
+        AF->>PR: Comment: summary of fix
+        Note over CI,PR: CI re-runs automatically on push
+    end
+```
+
+**Key details:**
+- Uses a GitHub App identity for pushes — avoids GitHub's anti-recursion protection
+- Concurrency group per PR — only one autofix runs at a time per PR
+- Max 3 iterations — posts "human review needed" if it can't fix it
+- No `--model` flag — Claude CLI handles model selection
+- Strips ANSI escape codes from logs so Claude gets clean text
+
+#### 2. Scenarios Dispatch Workflow (`scenarios-dispatch.yml`)
+
+Triggered when CI **passes** on a PR. Fires a `repository_dispatch` to the scenarios repo to run holdout tests against the PR branch.
+
+```mermaid
+sequenceDiagram
+    participant CI as CI Workflow
+    participant SD as Scenarios Dispatch
+    participant SR as Scenarios Repo
+
+    CI->>SD: workflow_run (conclusion: success, PR)
+    SD->>SD: Generate GitHub App token
+    SD->>SR: repository_dispatch: run-scenarios<br/>payload: {pr_number, branch, sha, repo}
+```
+
+#### 3. Spec Dispatch Workflow (`spec-dispatch.yml`)
+
+Triggered when spec files are pushed to `main`. Sends the spec content to the scenarios repo so the scenario agent can write tests.
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant Main as Main Repo (push to main)
+    participant SPD as Spec Dispatch Workflow
+    participant SR as Scenarios Repo
+
+    Dev->>Main: Push specs to docs/specs/
+    Main->>SPD: push event (docs/specs/** changed)
+    SPD->>SPD: git diff --diff-filter=AM (added/modified only)
+
+    loop For each changed spec
+        SPD->>SR: repository_dispatch: spec-pushed<br/>payload: {spec_filename, spec_content, commit_sha, branch, repo}
+    end
+
+    Note over SPD: Deleted specs are ignored —<br/>existing scenario tests remain
+```
+
+#### 4. Scenarios Re-run Workflow (`scenarios-rerun.yml`)
+
+Triggered when the scenarios repo updates its tests. Re-dispatches all open PRs to the scenarios repo so they get tested with the latest holdout tests.
+
+```mermaid
+sequenceDiagram
+    participant SR as Scenarios Repo
+    participant RR as Re-run Workflow
+    participant SRun as Scenarios Run
+
+    SR->>RR: repository_dispatch: scenarios-updated
+    RR->>RR: List open PRs via GitHub API
+
+    alt No open PRs
+        RR->>RR: Exit (no-op)
+    else Has open PRs
+        loop For each open PR
+            RR->>SRun: repository_dispatch: run-scenarios<br/>payload: {pr_number, branch, sha, repo}
+        end
+    end
+```
+
+**Why this exists:** There's a race condition. The implementation agent might open a PR before the scenario agent finishes writing new tests. The re-run workflow handles this — when new tests land, all open PRs get re-tested. Worst case: a PR merges before the re-run, and the new tests protect the very next PR. You're never more than one cycle behind.
+
+### The Holdout Wall
+
+The core safety mechanism. Two agents, two repos, one shared interface (specs):
+
+```mermaid
+graph LR
+    subgraph "Implementation Agent (main repo)"
+        IA_sees["Can see:<br/>Source code<br/>Internal tests<br/>Specs"]
+        IA_cant["Cannot see:<br/>Scenario tests<br/>Scenario repo"]
+    end
+
+    subgraph "Specs (shared interface)"
+        Specs["docs/specs/*.md<br/>Describes WHAT should happen<br/>Never describes HOW it's tested"]
+    end
+
+    subgraph "Scenario Agent (scenarios repo)"
+        SA_sees["Can see:<br/>Specs (via dispatch)<br/>Scenario tests<br/>Specs mirror"]
+        SA_cant["Cannot see:<br/>Source code<br/>Internal tests"]
+    end
+
+    IA_sees --> Specs
+    Specs --> SA_sees
+
+    style IA_cant fill:#fcc,stroke:#933
+    style SA_cant fill:#fcc,stroke:#933
+    style Specs fill:#cfc,stroke:#393
+```
+
+This is the same principle as a holdout set in machine learning. If the implementation agent could see the scenario tests, it would optimize to pass them specifically — not to build correct software. By keeping the wall intact, scenario tests catch real behavioral regressions, not test-gaming.
+
+### Scenario Evolution
+
+Scenarios aren't static. When you push new specs, the scenario agent automatically triages them and writes new holdout tests.
+
+```mermaid
+flowchart TD
+    A[New spec pushed to main] --> B[Spec Dispatch sends to scenarios repo]
+    B --> C[Scenario Agent reads spec]
+    C --> D{Triage: is this user-facing?}
+
+    D -->|Internal refactor, CI, dev tooling| E[Skip — commit note: 'No scenario changes needed']
+    D -->|New user-facing behavior| F[Write new scenario test file]
+    D -->|Modified existing behavior| G[Update existing scenario tests]
+
+    F --> H[Commit to scenarios main]
+    G --> H
+    H --> I[Dispatch scenarios-updated to main repo]
+    I --> J[Re-run workflow tests open PRs with new scenarios]
+
+    style D fill:#ffd,stroke:#993
+    style E fill:#ddd,stroke:#999
+    style F fill:#cfc,stroke:#393
+    style G fill:#cfc,stroke:#393
+```
+
+**The scenario agent's prompt instructs it to:**
+- Act as a QA engineer, never a developer
+- Write only behavioral tests (invoke the built artifact, assert on output)
+- Never import source code or reference internal implementation
+- Use a triage decision tree: SKIP / NEW / UPDATE
+- Err on the side of writing a test if the spec is ambiguous
+
+**The specs mirror:** The scenarios repo maintains a `specs/` folder that mirrors every spec it receives. This gives the scenario agent historical context ("what features already exist?") without access to the main repo's codebase.
+
+### The Complete Loop
+
+Here's the full lifecycle from spec to shipped, validated code:
+
+```mermaid
+sequenceDiagram
+    participant Human as Human (writes specs)
+    participant Main as Main Repo
+    participant ScAgent as Scenario Agent
+    participant ScRepo as Scenarios Repo
+    participant ImplAgent as Implementation Agent
+    participant Autofix as Autofix Workflow
+
+    Human->>Main: Push spec to docs/specs/
+    Main->>ScAgent: spec-pushed dispatch
+
+    par Scenario Generation
+        ScAgent->>ScAgent: Triage spec
+        ScAgent->>ScRepo: Write/update holdout tests
+        ScRepo->>Main: scenarios-updated dispatch
+    and Implementation
+        Human->>ImplAgent: Execute spec (fresh session)
+        ImplAgent->>Main: Open PR
+    end
+
+    Main->>Main: CI runs on PR
+
+    alt CI fails
+        Main->>Autofix: Autofix workflow triggers
+        Autofix->>Main: Push fix, CI re-runs
+    end
+
+    alt CI passes
+        Main->>ScRepo: run-scenarios dispatch
+        ScRepo->>ScRepo: Clone PR branch, build, run holdout tests
+        ScRepo->>Main: Post PASS/FAIL comment on PR
+    end
+
+    alt Scenarios PASS
+        Note over Human,Main: Ready for human review and merge
+    else Scenarios FAIL
+        Main->>Autofix: Autofix attempts fix
+        Note over Autofix,ScRepo: Loop continues (max 3 iterations)
+    end
+```
+
+### What Gets Installed
+
+| Where | File | Purpose |
+|-------|------|---------|
+| Main repo | `.github/workflows/autofix.yml` | CI failure → Claude fix → push |
+| Main repo | `.github/workflows/scenarios-dispatch.yml` | CI pass → trigger holdout tests |
+| Main repo | `.github/workflows/spec-dispatch.yml` | Spec push → trigger scenario generation |
+| Main repo | `.github/workflows/scenarios-rerun.yml` | New tests → re-test open PRs |
+| Scenarios repo | `workflows/run.yml` | Clone PR, build, run tests, post results |
+| Scenarios repo | `workflows/generate.yml` | Receive spec, run scenario agent |
+| Scenarios repo | `prompts/scenario-agent.md` | Scenario agent prompt template |
+| Scenarios repo | `example-scenario.test.ts` | Example holdout test |
+| Scenarios repo | `package.json` | Minimal vitest setup |
+| Scenarios repo | `README.md` | Explains holdout pattern to contributors |
+
+### Prerequisites
+
+- **GitHub App** — Provides a separate identity for autofix pushes (avoids GitHub's anti-recursion protection). You can install the shared [Joycraft Autofix](https://github.com/apps/joycraft-autofix) app (App ID: `3180156`) or create your own.
+- **Secrets** — `JOYCRAFT_APP_PRIVATE_KEY` and `ANTHROPIC_API_KEY` on both the main and scenarios repos.
+- **Scenarios repo** — A private repository where holdout tests live. Created during setup.
+
+### Cost
+
+Validated in the Pipit trial (~3 minutes, one iteration, zero human intervention). With Claude Sonnet + `--max-turns 20` + max 3 iterations per PR:
+- **Autofix:** ~$0.50 per attempt, worst case ~$1.50 per PR (3 iterations)
+- **Scenario generation:** ~$0.20 per spec dispatch
+- **Solo dev with ~10 PRs/month:** ~$5-10/month for the full loop
+
+The iteration guard and max-turns cap prevent runaway costs.
+
+## Tuning: Risk Interview & Git Autonomy
+
+When `/joycraft-tune` runs for the first time, it does two things:
+
+### Risk interview
+
+3-5 targeted questions about what's dangerous in your project — production databases, live APIs, secrets, files that should be off-limits. From your answers, Joycraft generates:
+
+- **NEVER rules** for CLAUDE.md (e.g., "NEVER connect to production DB")
+- **Deny patterns** for `.claude/settings.json` (blocks dangerous bash commands)
+- **`docs/context/production-map.md`** — what's real vs. safe to touch
+- **`docs/context/dangerous-assumptions.md`** — "Agent might assume X, but actually Y"
+
+This takes 2-3 minutes and dramatically reduces the chance of your agent doing something catastrophic.
+
+### Git autonomy
+
+One question: **how autonomous should git be?**
 
 - **Cautious** (default) — commits freely, asks before pushing or opening PRs. Good for learning the workflow.
 - **Autonomous** — commits, pushes to feature branches, and opens PRs without asking. Good for spec-driven development where you want full send.
@@ -107,7 +511,7 @@ Joycraft's approach is synthesized from several sources:
 
 **Knowledge capture over session notes.** Most session notes are never re-read. Joycraft's `/joycraft-session-end` skill captures only *discoveries* — assumptions that were wrong, APIs that behaved unexpectedly, decisions made during implementation that aren't in the spec. If nothing surprising happened, you capture nothing. This keeps the signal-to-noise ratio high.
 
-**External holdout scenarios.** [StrongDM's Software Factory](https://factory.strongdm.ai/) proved that AI agents will [actively game visible test suites](https://palisaderesearch.org/blog/specification-gaming). Their solution: scenarios that live *outside* the codebase, invisible to the agent during development. Like a holdout set in ML, this prevents overfitting. Joycraft provides the template for building these.
+**External holdout scenarios.** [StrongDM's Software Factory](https://factory.strongdm.ai/) proved that AI agents will [actively game visible test suites](https://palisaderesearch.org/blog/specification-gaming). Their solution: scenarios that live *outside* the codebase, invisible to the agent during development. Like a holdout set in ML, this prevents overfitting. Joycraft now implements this directly — `init-autofix` sets up the holdout wall, the scenario agent, and the GitHub App integration, not just provides templates for it.
 
 **The 5-level framework.** [Dan Shapiro's levels](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) give you a map. Level 2 (Junior Developer) is where most teams plateau. Level 3 (Developer as Manager) means your life is diffs. Level 4 (Developer as PM) means you write specs, not code. Level 5 (Dark Factory) means specs in, software out. Joycraft's `/joycraft-tune` assessment tells you where you are and what to do next.
 
@@ -115,15 +519,29 @@ Joycraft's approach is synthesized from several sources:
 
 Joycraft synthesizes ideas and patterns from people doing extraordinary work in AI-assisted software development:
 
-- **[Dan Shapiro](https://www.danshapiro.com/)** ([@danshapiro](https://github.com/danshapiro)) — The [5 Levels of Vibe Coding](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) framework that Joycraft's assessment and level system is built on
-- **[StrongDM](https://www.strongdm.com/)** / **Justin McCarthy** ([@justinmccarthy](https://github.com/justinmccarthy)) — The [Software Factory](https://factory.strongdm.ai/): spec-driven autonomous development, NLSpec, external holdout scenarios, and the proof that 3 engineers can outproduce 30
-- **[Boris Cherny](https://performancejs.com/)** ([@bcherny](https://github.com/bcherny)) — Head of Claude Code at Anthropic. The interview → spec → fresh session → execute pattern, and the insight that [context isolation produces better results](https://www.lennysnewsletter.com/p/head-of-claude-code-what-happens)
-- **[Addy Osmani](https://addyosmani.com/)** ([@addyosmani](https://github.com/addyosmani)) — [What makes a good spec for AI](https://addyosmani.com/blog/good-spec/): commands, testing, project structure, code style, git workflow, and boundaries
+- **[Dan Shapiro](https://x.com/danshapiro)** — The [5 Levels of Vibe Coding](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) framework that Joycraft's assessment and level system is built on
+- **[StrongDM](https://www.strongdm.com/)** / **[Justin McCarthy](https://x.com/BuiltByJustin)** — The [Software Factory](https://factory.strongdm.ai/): spec-driven autonomous development, NLSpec, external holdout scenarios, and the proof that 3 engineers can outproduce 30
+- **[Boris Cherny](https://x.com/bcherny)** — Head of Claude Code at Anthropic. The interview → spec → fresh session → execute pattern, and the insight that [context isolation produces better results](https://www.lennysnewsletter.com/p/head-of-claude-code-what-happens)
+- **[Addy Osmani](https://x.com/addyosmani)** — [What makes a good spec for AI](https://addyosmani.com/blog/good-spec/): commands, testing, project structure, code style, git workflow, and boundaries
 - **[METR](https://metr.org/)** — The [randomized control trial](https://metr.org/) that proved unstructured AI use makes experienced developers slower, validating the need for harnesses
-- **[Nate B Jones](https://www.youtube.com/@natebj)** ([@nateBJ](https://github.com/nateBJ)) — His [video on the 5 Levels of Vibe Coding](https://www.youtube.com/watch?v=bDcgHzCBgmQ) made this research accessible and inspired turning Joycraft into a tool anyone can use
-- **[Simon Willison](https://simonwillison.net/)** ([@simonw](https://github.com/simonw)) — [Analysis of the Software Factory](https://simonwillison.net/2026/Feb/7/software-factory/) that helped contextualize StrongDM's approach for the broader community
+- **[Nate B Jones](https://x.com/natebjones)** — His [video on the 5 Levels of Vibe Coding](https://www.youtube.com/watch?v=bDcgHzCBgmQ) made this research accessible and inspired turning Joycraft into a tool anyone can use
+- **[Simon Willison](https://x.com/simonw)** — [Analysis of the Software Factory](https://simonwillison.net/2026/Feb/7/software-factory/) that helped contextualize StrongDM's approach for the broader community
 - **[Anthropic](https://www.anthropic.com/)** — Claude Code's skills, hooks, and CLAUDE.md system that makes tool-native AI development possible, and the [harness patterns for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
 
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+The short version:
+
+1. Fork, branch from `main`
+2. `pnpm install && pnpm test --run` to verify your setup
+3. Write tests first, then implement
+4. `pnpm test --run && pnpm typecheck && pnpm build`
+5. Open a PR — one approval required
+
+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, documentation, and Codex integration.
+
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE) for details.

package/dist/chunk-2S7KP7FU.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+// src/version.ts
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { createHash } from "crypto";
+var VERSION_FILE = ".joycraft-version";
+function hashContent(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function readVersion(dir) {
+  const filePath = join(dir, VERSION_FILE);
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version === "string" && typeof parsed.files === "object") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function writeVersion(dir, version, files) {
+  const filePath = join(dir, VERSION_FILE);
+  const data = { version, files };
+  writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+export {
+  hashContent,
+  readVersion,
+  writeVersion
+};
+//# sourceMappingURL=chunk-2S7KP7FU.js.map

package/dist/chunk-2S7KP7FU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["import { readFileSync, writeFileSync, existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { createHash } from 'node:crypto';\n\nconst VERSION_FILE = '.joycraft-version';\n\nexport interface VersionInfo {\n  version: string;\n  files: Record<string, string>;\n}\n\nexport function hashContent(content: string): string {\n  return createHash('sha256').update(content).digest('hex');\n}\n\nexport function readVersion(dir: string): VersionInfo | null {\n  const filePath = join(dir, VERSION_FILE);\n  if (!existsSync(filePath)) return null;\n  try {\n    const raw = readFileSync(filePath, 'utf-8');\n    const parsed = JSON.parse(raw);\n    if (typeof parsed.version === 'string' && typeof parsed.files === 'object') {\n      return parsed as VersionInfo;\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\nexport function writeVersion(dir: string, version: string, files: Record<string, string>): void {\n  const filePath = join(dir, VERSION_FILE);\n  const data: VersionInfo = { version, files };\n  writeFileSync(filePath, JSON.stringify(data, null, 2) + '\\n', 'utf-8');\n}\n"],"mappings":";;;AAAA,SAAS,cAAc,eAAe,kBAAkB;AACxD,SAAS,YAAY;AACrB,SAAS,kBAAkB;AAE3B,IAAM,eAAe;AAOd,SAAS,YAAY,SAAyB;AACnD,SAAO,WAAW,QAAQ,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK;AAC1D;AAEO,SAAS,YAAY,KAAiC;AAC3D,QAAM,WAAW,KAAK,KAAK,YAAY;AACvC,MAAI,CAAC,WAAW,QAAQ,EAAG,QAAO;AAClC,MAAI;AACF,UAAM,MAAM,aAAa,UAAU,OAAO;AAC1C,UAAM,SAAS,KAAK,MAAM,GAAG;AAC7B,QAAI,OAAO,OAAO,YAAY,YAAY,OAAO,OAAO,UAAU,UAAU;AAC1E,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,aAAa,KAAa,SAAiB,OAAqC;AAC9F,QAAM,WAAW,KAAK,KAAK,YAAY;AACvC,QAAM,OAAoB,EAAE,SAAS,MAAM;AAC3C,gBAAc,UAAU,KAAK,UAAU,MAAM,MAAM,CAAC,IAAI,MAAM,OAAO;AACvE;","names":[]}