{"id":47676318,"url":"https://github.com/maksutovic/joycraft","last_synced_at":"2026-05-28T01:01:21.830Z","repository":{"id":346491748,"uuid":"1189861584","full_name":"maksutovic/joycraft","owner":"maksutovic","description":"CLI + Claude Code plugin that scaffolds and upgrades AI development harnesses — from vibe coding to autonomous spec-driven development","archived":false,"fork":false,"pushed_at":"2026-05-22T07:00:03.000Z","size":4020,"stargazers_count":10,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T07:41:32.972Z","etag":null,"topics":["ai-development","claude-code","cli","developer-tools","spec-driven","typescript","vibe-coding"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maksutovic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["maksutovic"]}},"created_at":"2026-03-23T18:34:17.000Z","updated_at":"2026-05-22T06:59:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maksutovic/joycraft","commit_stats":null,"previous_names":["maksutovic/joysmith"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/maksutovic/joycraft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksutovic%2Fjoycraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksutovic%2Fjoycraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksutovic%2Fjoycraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksutovic%2Fjoycraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maksutovic","download_url":"https://codeload.github.com/maksutovic/joycraft/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksutovic%2Fjoycraft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33589684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-development","claude-code","cli","developer-tools","spec-driven","typescript","vibe-coding"],"created_at":"2026-04-02T13:32:05.695Z","updated_at":"2026-05-28T01:01:21.813Z","avatar_url":"https://github.com/maksutovic.png","language":"TypeScript","funding_links":["https://github.com/sponsors/maksutovic"],"categories":[],"sub_categories":[],"readme":"# Joycraft\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/joycraft-banner.png\" alt=\"Joycraft, the craft of AI development\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n\u003e The craft of AI development. With joy, not darkness.\n\n## What is Joycraft?\n\nJoycraft is a CLI tool that installs structured development skills into [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [OpenAI Codex](https://openai.com/codex), along with behavioral boundaries, templates, and documentation structure. It takes any project from unstructured prompting to autonomous spec-driven development.\n\n### The core idea\n\n- **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.\n- **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.\n\n### What are the levels?\n\n[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:\n\n| Level | Name | What it looks like | Joycraft's role |\n|-------|------|--------------------|-----------------|\n| 1 | Autocomplete | Tab-complete suggestions | - |\n| 2 | Junior Developer | Prompt → iterate → fix → repeat | `/joycraft-tune` assesses where you are |\n| 3 | Developer as Manager | Your life is reviewing diffs | Behavioral boundaries in CLAUDE.md |\n| 4 | Developer as PM | You write specs, agent writes code | `/joycraft-new-feature` + `/joycraft-decompose` |\n| 5 | Software Factory | Specs in, validated software out | `/joycraft-implement-level5` sets up the autonomous loop |\n\nMost developers plateau at Level 2. Joycraft's job is to move you up.\n\n### Platform support\n\nJoycraft supports both **Claude Code** and **OpenAI Codex** out of the box. Running `npx joycraft init` installs skills to both `.claude/skills/` and `.agents/skills/` — no flags, no configuration. Both platforms get the same structured workflows, adapted for each tool's invocation model (`/joycraft-*` for Claude Code, `$joycraft-*` for Codex).\n\n## Quick Start\n\nFirst, install the CLI:\n\n```bash\nnpm install -g joycraft\n```\n\nThen navigate to your project's root directory and initialize:\n\n```bash\ncd /path/to/your/project\nnpx joycraft init\n```\n\nJoycraft auto-detects your tech stack and creates:\n\n- **CLAUDE.md** with behavioral boundaries (Always / Ask First / Never) and correct build/test/lint commands\n- **AGENTS.md** for Codex compatibility\n- **15 skills** installed to `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex) — see [Which skill do I need?](#which-skill-do-i-need) below\n- **docs/** structure: `docs/context/` is created up front; feature work lands in `docs/features/\u003cslug\u003e/{brief.md, research.md, design.md, specs/}` and deferred work in `docs/backlog/` — these are created lazily by the skills that write to them\n- **Context documents** in `docs/context/`: production map, dangerous assumptions, decision log, institutional knowledge, and troubleshooting guide\n- **Templates** including atomic spec, feature brief, implementation plan, boundary framework, and workflow templates for scenario generation and autofix loops\n\n### Supported Stacks\n\nNode.js (npm/pnpm/yarn/bun), Python (poetry/pip/uv), Rust, Go, Swift, and generic (Makefile/Dockerfile).\n\nFrameworks auto-detected: Next.js, FastAPI, Django, Flask, Actix, Axum, Express, Remix, and more.\n\n## The Workflow\n\n### Which skill do I need?\n\n| You want to... | Use | What happens |\n|---|---|---|\n| Brainstorm an idea before committing to building it | `/joycraft-interview` | Free-form conversation → structured draft brief |\n| Build a new feature from scratch | `/joycraft-new-feature` | Guided interview → Feature Brief → Atomic Specs |\n| Understand existing code before building on it | `/joycraft-research` | Objective codebase research — facts only, no opinions |\n| Align on approach before writing code | `/joycraft-design` | Design discussion → ~200-line artifact for human review |\n| Break a feature into small, independent tasks | `/joycraft-decompose` | Feature Brief → testable Atomic Specs |\n| Fix a bug with a structured workflow | `/joycraft-bugfix` | Reproduce → isolate → fix → verify loop |\n| Implement a spec with TDD | `/joycraft-implement` | Read spec → write failing tests → implement until green |\n| Run specs autonomously without hand-holding | `/joycraft-implement-level5` | Autofix loop + holdout scenario testing |\n| Verify an implementation independently | `/joycraft-verify` | Read-only subagent checks work against the spec |\n| Set up Joycraft for a team | `/joycraft-collaborative-setup` | Scaffold `docs/areas/`, owner conventions, a team CONTRIBUTING doc |\n\nThe core loop:\n\n```mermaid\nflowchart LR\n    A[Interview] --\u003e B[Feature Brief]\n    B --\u003e C{Complex?}\n    C -- \"Simple\" --\u003e F[Decompose]\n    C -- \"Complex\" --\u003e D[Research]\n    D --\u003e E[Design]\n    E --\u003e F\n    F --\u003e G[Atomic Specs]\n    G --\u003e H[Implement]\n    H --\u003e I[Session End]\n\n    style A fill:#fff,stroke:#333,stroke-width:2px\n    style B fill:#fff,stroke:#333,stroke-width:2px\n    style C fill:#fff,stroke:#333,stroke-width:2px\n    style D fill:#e8e8e8,stroke:#333,stroke-width:2px\n    style E fill:#e8e8e8,stroke:#333,stroke-width:2px\n    style F fill:#fff,stroke:#333,stroke-width:2px\n    style G fill:#fff,stroke:#333,stroke-width:2px\n    style H fill:#333,stroke:#333,color:#fff,stroke-width:2px\n    style I fill:#333,stroke:#333,color:#fff,stroke-width:2px\n```\n\n### The Interview\n\nThe single biggest upgrade Joycraft makes is replacing prompt-iterate-fix with a structured interview. [Read the full guide →](docs/guides/interview-workflow.md)\n\n### Research Isolation \u0026 Design Checkpoints\n\nObjective research via context isolation and 200-line design checkpoints for human review before decomposition. [Read the full guide →](docs/guides/research-and-design.md)\n\n### Test-First Development\n\nTests are the mechanism to autonomy — every spec includes a test plan, and the agent writes failing tests before implementing. [Read the full guide →](docs/guides/test-first-development.md)\n\n### Tuning: Risk Interview \u0026 Git Autonomy\n\nA 2-3 minute risk interview generates safety boundaries, and you choose your git autonomy level. [Read the full guide →](docs/guides/tuning.md)\n\n### Token Discipline\n\nJoycraft 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)\n\n### Level 5: The Autonomous Loop\n\nLevel 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)\n\n### Permission Modes\n\nYou do **not** need `--dangerously-skip-permissions` for autonomous development. Claude Code offers safer alternatives. [Read the full guide →](docs/guides/permission-modes.md)\n\n### How It Works with AI Agents\n\nClaude Code reads CLAUDE.md, Codex reads AGENTS.md — both get the same guardrails and workflow. [Read the full guide →](docs/guides/agent-compatibility.md)\n\n## Upgrade\n\nWhen Joycraft templates and skills evolve, update without losing your customizations:\n\n```bash\nnpx joycraft upgrade\n```\n\nJoycraft 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.\n\n\u003e **Note:** If you're upgrading from an early version, deprecated skill directories (e.g., `/joy`, `/joysmith`, `/tune`) are automatically removed during upgrade.\n\n## Why This Exists\n\nMost developers using AI tools are at Level 2 — and [METR's research](https://metr.org/) found they're actually slower, not faster. Joycraft packages the patterns used by teams seeing transformative results into something anyone can install. [Read the full methodology →](docs/guides/methodology.md)\n\n## Standing on the Shoulders of Giants\n\nJoycraft synthesizes ideas and patterns from people doing extraordinary work in AI-assisted software development:\n\n- **[Dan Shapiro](https://x.com/danshapiro)** for 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\n- **[StrongDM](https://www.strongdm.com/)** / **[Justin McCarthy](https://x.com/BuiltByJustin)** for the [Software Factory](https://factory.strongdm.ai/): spec-driven autonomous development, NLSpec, external holdout scenarios, and the proof that 3 engineers can outproduce 30\n- **[Dex Horthy](https://x.com/dexhorthy)** / **[HumanLayer](https://humanlayer.dev)** for the [RPI to CRISPY evolution](https://humanlayer.dev/blog): research isolation (hide the ticket from the researcher), the instruction budget concept (~150-200 instructions max), design discussions as high-leverage checkpoints, vertical-over-horizontal planning, and the conviction that \"if your tool requires magic words, go fix the tool\"\n- **[Boris Cherny](https://x.com/bcherny)**, Head of Claude Code at Anthropic, for 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)\n- **[Addy Osmani](https://x.com/addyosmani)** for [What makes a good spec for AI](https://addyosmani.com/blog/good-spec/): commands, testing, project structure, code style, git workflow, and boundaries\n- **[METR](https://metr.org/)** for the [randomized control trial](https://metr.org/) that proved unstructured AI use makes experienced developers slower, validating the need for harnesses\n- **[Nate B Jones](https://x.com/natebjones)** whose [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\n- **[Simon Willison](https://x.com/simonw)** for his [analysis of the Software Factory](https://simonwillison.net/2026/Feb/7/software-factory/) that helped contextualize StrongDM's approach for the broader community\n- **[Anthropic](https://www.anthropic.com/)** for 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)\n\n## Migration: Flat → Per-Feature Layout (v0.6+)\n\nStarting in v0.6, Joycraft organizes feature artifacts into per-feature folders:\n\n- `docs/briefs/\u003cslug\u003e.md` → `docs/features/\u003cslug\u003e/brief.md`\n- `docs/research/\u003cslug\u003e.md` → `docs/features/\u003cslug\u003e/research.md`\n- `docs/designs/\u003cslug\u003e.md` → `docs/features/\u003cslug\u003e/design.md`\n- `docs/specs/\u003cfeature\u003e/` → `docs/features/\u003cslug\u003e/specs/` (when `\u003cfeature\u003e` matches a brief slug)\n\n`npx joycraft upgrade` performs this migration automatically and forcefully on the first\npost-upgrade run — no Y/N prompt. The CLI prints a summary of every move before applying it.\nSpec directories under `docs/specs/` whose name doesn't match any brief slug (area-level specs\nlike bugfix folders) are left in place.\n\n### What you'll see on the first post-upgrade run\n\n```\nJoycraft is migrating your docs/ to the new per-feature layout:\n\n  2026-04-01-auth-redesign/\n    docs/briefs/2026-04-01-auth-redesign.md → docs/features/2026-04-01-auth-redesign/brief.md\n    docs/research/2026-04-01-auth-redesign.md → docs/features/2026-04-01-auth-redesign/research.md\n\n  Left in place — area-level specs (e.g., bugfix areas):\n    docs/specs/login-bugfix/\n\nMigration complete. See the README section \"Migration: Flat → Per-Feature Layout\"\nfor context on what changed and why. If your project is a git repo, run\n`git status` to inspect the moves before committing.\n```\n\n### Why forced (not opt-in)\n\nAll doc-producing skills (`joycraft-new-feature`, `joycraft-research`, `joycraft-design`,\n`joycraft-decompose`, etc.) write to the new per-feature paths. Supporting both layouts\nindefinitely would mean every skill carries dual-path branches; the forced migration keeps\nthe convention single and skills small.\n\n### Recovering / customizing\n\nEvery move is a plain filesystem move (no `git mv`). If you want a different organization\nafter the migration, you can `git mv` files anywhere — Joycraft only depends on the\n`docs/features/\u003cslug\u003e/` shape for skills it ships, not on every doc living there. Git\nhistory follows files via `git log --follow`.\n\nIf a brief and its destination already exist (re-running upgrade after a partial migration),\nthe move is skipped and reported. The migration is idempotent.\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.\n\nThe short version:\n\n1. Fork, branch from `main`\n2. `pnpm install \u0026\u0026 pnpm test --run` to verify your setup\n3. Write tests first, then implement\n4. `pnpm test --run \u0026\u0026 pnpm typecheck \u0026\u0026 pnpm build`\n5. Open a PR (one approval required)\n\nLook 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, and documentation.\n\n## License\n\nMIT. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaksutovic%2Fjoycraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaksutovic%2Fjoycraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaksutovic%2Fjoycraft/lists"}