dev-ready 0.6.0

Scaffold AI-development-ready FastAPI projects: pinned upstream template plus Claude Code skills, MCP config, and design docs

dev-ready

Scaffold a production-grade, AI-development-ready FastAPI + React project in one command:

uvx dev-ready init my-app

The upstream template is pinned to a CI-verified commit (never an untested "latest"), and generation is all-or-nothing — if any step fails, your target directory is never touched.

What you get

A generated project based on fastapi/full-stack-fastapi-template (FastAPI, React, SQLModel, PostgreSQL, Docker Compose), plus an AI tooling overlay so it works well with coding agents out of the box:

• CLAUDE.md — project instructions for Claude Code, including Karpathy-derived development guardrails (MIT, per the upstream README)
• Claude Code skills — nine pre-configured skills selectable at generation time:
  • project-orientation (built-in) — codebase orientation helper
  • react-doctor (pinned devDependency) — frontend dependency health checks
  • caveman (vendored, MIT) — token-discipline communication mode
  • tdd (vendored, MIT) — test-driven development loop
  • diagnosing-bugs (vendored, MIT) — diagnosis loop for hard bugs
  • code-review (vendored, MIT) — review against coding standards and spec
  • security-audit (vendored, MIT) — multi-phase security audit
  • webapp-testing (vendored, Apache-2.0) — browser-automation end-to-end testing
  • frontend-design (vendored, Apache-2.0) — frontend UI design methodology
• MCP server configuration (mcp.json)
• Design-doc templates (architecture.md, requirements.md)
• Agent-team handoff scaffold (docs/handoffs/ — a document-driven multi-agent workflow: Tech Lead → Senior → Junior → QA/Security/SRE)
• Generation stamp — every generated project gets a .dev-ready.json recording the dev-ready version, selected components/items, and pinned upstream commit
• Pinned tool integrations — optional, selectable MCP and skill items: a codebase-memory MCP server (uvx codebase-memory-mcp) and a react-doctor frontend wrapper skill + devDependency
• Item-level selection — pick individual skills (including vendored ones) and MCP items; vendored skills include their upstream provenance in .dev-ready.json

Every generated project also gets its own README.md (the upstream template's repo README and other repo-maintenance files — CONTRIBUTING.md, release notes, deploy workflows, screenshots — are pruned, so nothing template-repo-specific leaks into your project).

Requirements

• Python >= 3.12 (uv can install this for you automatically)
• git (Copier fetches the pinned template via git)
• Network access to github.com (to fetch the pinned template snapshot)
• Docker is not required to generate a project — only to run the generated one

Installation

No install needed with uv (any recent version):

uvx dev-ready init my-app

Or install with pip (requires Python >= 3.12):

pip install dev-ready
dev-ready init my-app

Usage

# Interactive: prompts for anything not given on the command line
uvx dev-ready init

# Non-interactive: accept all defaults, no prompts
uvx dev-ready init my-app --yes

# Options
uvx dev-ready init my-app \
  --dir path/to/target \    # default: ./my-app
  --skills <ids|all|none> \ # choose individual skills (default: all)
  --mcp <ids|all|none> \    # choose individual MCP servers (default: all)
  --no-skills \             # skip the Claude Code skills overlay
  --no-mcp \                # skip the MCP configuration overlay
  --no-docs \               # skip the design-doc templates
  --no-agents               # skip the agent-team handoff scaffold

# Inspect a generated project against its stamp and the current CLI (read-only)
uvx dev-ready check path/to/project
uvx dev-ready check path/to/project --json  # machine-readable report

# Re-apply managed overlay files to an existing project (never touches app code)
uvx dev-ready upgrade path/to/project
uvx dev-ready upgrade path/to/project --dry-run  # preview; writes nothing

check is read-only and offline. upgrade re-applies only overlay-managed whole files, skips and reports user-modified or shared files, and applies its planned writes all-or-nothing. Both commands default to the current directory when PATH is omitted.

Then follow the printed next steps (typically docker compose watch inside the generated project).

Exit codes: 0 success; 1 unexpected error or user abort; 2 argument error; 3 network/fetch failure; 4 target directory conflict; 5 structural verification failure; 6 stamp missing or invalid; 7 drift detected; 8 upgrade not supported (pre-v3 stamp; projects generated before v0.6); 9 upgrade failed (rolled back).

How it works

The CLI ships with a lockfile (manifest.json) pinning the upstream template commit. Generation fetches that exact snapshot, applies the overlay with variable substitution, verifies the result structurally — all inside a staging directory — and only then moves it into the target. The pin is kept current by a weekly CI job that opens bump PRs, each validated by actually generating and booting a project with Docker Compose.

Links

• Source & issues: https://github.com/MoofonLi/dev-ready
• CLI spec, architecture, and ADRs: https://github.com/MoofonLi/dev-ready/tree/main/docs

License

MIT. Generated projects include content derived from fastapi/full-stack-fastapi-template (MIT); see THIRD_PARTY_NOTICES.md.