Devspec Lite is a compact, resumable spec-driven workflow for AI coding agents. Git-tracked devspec/ artifacts are the canonical project state.
| Your situation | Use this guide |
|---|---|
| No installer, Python, package manager, or CLI | Manual copy from main |
| Python is available; one-off or persistent CLI use | Python and uvx |
| Windows package-manager installation | WinGet |
| macOS/Linux package-manager installation | Homebrew |
| Already installed the CLI; need init, upgrade, or profile changes | CLI lifecycle |
Manual copying and CLI installation produce the same canonical devspec/ content and agent wrappers, once the manual route resets the project records listed in its guide. In either route, set the target repository's repository-state.md to new or existing. Choose one setup route; the CLI is optional.
uvx devspec init --target . --profile all --repo-state existing
uvx devspec doctor --target . --profile allUse --repo-state new for a repository with no source yet. The CLI quick start covers both routes and the first command to run.
init copies the canonical contracts, protocols, and templates plus the wrappers for the selected agent profile, generates devspec/foundation/repository-state.md from --repo-state, and seeds empty devspec/architecture/overview.md and artifact-queue.md. Those two and devspec/constitution.md are project-owned: init and sync never overwrite them, even with --force.
Before a framework upgrade, inspect drift with devspec diff --target . and preview it with devspec sync --target . --profile all --dry-run.
Use the developer workflow guide for concrete quickfix, refinement, clarification, and change-request examples.
Follow the scenario-based how-to guide to choose the right command, establish a baseline, deliver a story, work across repositories, or route a small fix safely. The beginner command examples give a first prompt for every command.
Two rules apply throughout. Confirm single-repository or multi-repository scope before every devspec.* command, unless current canonical evidence already records it. After starting a story, run the work-item commands or continue without repeating its ID: private per-worktree context resumes only the recorded next action.