devspec
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.
Choose a setup route
| 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.
CLI quick start
uvx devspec init --target . --profile all --repo-state existing
uvx devspec doctor --target . --profile all
Use --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.
Supported agent hosts
| 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.
Choose a workflow route
Use the developer workflow guide for concrete quickfix, refinement, clarification, and change-request examples.
How to
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.
Contributing and releases
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.
License
devspec is released under the Apache License 2.0.
1 maintainer
Metadata
1 maintainer
Release files for devspec 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| devspec-0.3.0.tar.gz | 94.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| devspec-0.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 219.7 kB
Release files / devspec-0.3.0.tar.gz
| Download URL | devspec-0.3.0.tar.gz |
|---|---|
| Size | 94.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c6a90c19f9b523d239d9a7e1ea1b0f12152ec60ca382f33f0e820cef96751c90
|
|
BLAKE2b-256 checksum How to use checksums |
4d22322f51bd1ff30d0c79bc69d08c0b367d417b579b703cc854ca9730c1f42b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / devspec-0.3.0-py3-none-any.whl
| Download URL | devspec-0.3.0-py3-none-any.whl |
|---|---|
| Size | 125.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
615894ec8792c524ca64d44a6425412d8606ba9a1c7b422fcce3230da47d463d
|
|
BLAKE2b-256 checksum How to use checksums |
0f250ff292f3708b3f4c182cf3125009f502173e5a95b8003e4442e90dd4081b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.21 {"installer":{"name":"uv","version":"0.12.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
