devspec is a compact, resumable spec-driven workflow for AI coding agents. Git-tracked devspec/ artifacts are the canonical project state, so planning, implementation, review, and recovery never depend on chat history.
| 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 |
| A repository already uses devspec 0.2.x | Upgrade from devspec 0.2.x |
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 three files 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.
| Agent host | Profile | Installed wrapper | Invoke a command |
|---|---|---|---|
| GitHub Copilot | copilot |
.github/prompts/ and .github/agents/ |
/devspec.story |
| OpenAI Codex | codex |
AGENTS.md |
Ask for devspec.story |
| Claude Code | claude |
.claude/skills/ |
/devspec-story |
| Cursor | cursor |
.cursor/rules/devspec-workflow.mdc |
Ask for devspec.story |
| Gemini CLI | gemini |
.gemini/commands/devspec/ |
/devspec:story |
| Google Antigravity | antigravity |
.agents/skills/ |
The devspec-story skill |
Each wrapper only points at its contract in devspec/contracts/, so every host runs the same workflow. The all profile installs every wrapper.
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.
Run the test suite with uv run python -m unittest discover -s tests. Release pipelines, one-time publishing setup, and the release checklist are in packaging/README.md.
devspec is released under the Apache License 2.0.