devspec

devspec is a spec-driven development framework for teams using GitHub Copilot and other AI coding agents.

It stores planning, implementation, review, and recovery state in Git-tracked files instead of relying on chat history. Use it when you want agents to follow the same workflow for project context, engineering standards, work-item intake, implementation, review, and session recovery.

Quick Start

Install with the devspec CLI from the target repository. The recommended one-off path is uvx, which avoids a permanent global install and works well on restricted developer machines.

uvx devspec init --target . --profile all --repo-state existing
uvx devspec doctor --target . --profile all

Use --repo-state new for a new repository. After validation, commit the copied framework files, run the foundation flow, then start the first work item.

For the full setup manual, see docs/how-to/README.md.

Setup Options

Install profiles let you choose which AI coding agent files to copy. Most multi-agent teams can start with --profile all; single-tool teams can use a smaller profile such as copilot, codex, cursor, claude, gemini, or antigravity.

Core Workflow

devspec has two workflow layers.

For a new project:

/devspec.projectcontext
/devspec.techstack
/devspec.codebase-structure
/devspec.coding-standards
/devspec.rules

For an existing project:

/devspec.extract
/devspec.projectcontext
/devspec.techstack
/devspec.codebase-structure
/devspec.coding-standards
/devspec.rules

Then run the work-item flow:

/devspec.story
/devspec.finalize
/devspec.tasks
/devspec.implement
/devspec.review

For a missed related requirement after finalization, use the append-only change-request route:

/devspec.changerequest -> /devspec.finalize -> /devspec.tasks -> /devspec.implement -> /devspec.review

Use /devspec.clarify only when a work item records a blocking question. Use /devspec.changerequest for a missed related requirement after finalization; it appends to existing work-item Markdown artifacts rather than creating a separate CR file. Use /devspec.diagram when a diagram would clarify architecture, workflow, state, sequence, or domain behavior.

AI Tool Support

GitHub Copilot prompt and agent files are the reference implementation. Other adapters are thin wrappers around the same command registry and Git-tracked artifacts.

Canonical command names remain /devspec.*. Some adapters expose host-native shortcuts such as /devspec:story or /devspec-story; see Command Invocation by Agent.

More Documentation

License

This repository is released under the Apache License 2.0.