A strict Spec Agent workflow for spec-driven development
Project description
Spec Agent CLI
Spec Agent turns unclear feature requests into approved, product-only specifications
before any implementation planning begins. It installs the same three Agent Skills
for both the open .agents/skills convention and Claude Code's .claude/skills
convention. Specification evolution and code drift observation remain available
without mixing them into implementation work.
Install
Python 3.11 or newer is required.
uv tool install spec-agent-cli
Alternatives:
pipx install spec-agent-cli
pip install spec-agent-cli
Initialize a repository
cd /path/to/your-project
spec-agent init
This creates only missing project files and installs:
.agents/skills/spec-request-flow/
.agents/skills/spec-drift-sync/
.agents/skills/spec-evolution/
AGENTS.md # managed rules block; user content is preserved
.claude/skills/spec-request-flow/
.claude/skills/spec-drift-sync/
.claude/skills/spec-evolution/
CLAUDE.md # managed Claude rules block; user content is preserved
SPEC.md # created only when absent
spec/packets/
spec/evolution/events.jsonl
spec/evolution/timeline.md
spec/traceability.json
Use spec-agent init --check for a read-only status check. Use
spec-agent init --force to refresh locally modified managed skill files after a CLI
upgrade. Both skill trees come from one canonical packaged source, so their behavior
cannot evolve independently. --force never replaces project specifications or
history.
Start a feature
Ask a compatible agent, including Claude Code:
Use spec-request-flow to define feature X. Do not implement it.
The Spec Agent repeatedly clarifies blocking product questions, compares meaningful
product approaches, writes spec.md and acceptance.md, asks for approval, records
the approved product evolution, and then gives you the prompt for a separate Code
Agent. That handoff requires spec: BEHAVIOR-ID backlinks in relevant production code
and tests.
Validate implementation traceability
After an approved implementation, the Code Agent establishes the derived baseline and then validates it:
spec-agent traceability-sync --repo .
spec-agent validate --repo .
validate is read-only and returns failure for missing, unknown, unbaselined, moved,
or changed backlink evidence. traceability-sync is used only after approved
implementation or explicit reconciliation; it must not be used to hide unexplained
drift.
Open the local workspace
After initializing a repository, launch the read-only Potpie-inspired dashboard:
spec-agent ui --repo .
Use --no-open in headless environments. The dashboard reads SPEC.md, packet
specifications, acceptance scenarios, evolution events, Git history, drift results,
and derived traceability without modifying the repository.
The UI is a small React app compiled into static assets and bundled with the CLI, so end users do not need Node.js. To change the dashboard during development:
cd dashboard
npm install
npm run build
Then restart spec-agent ui.
License
MIT
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file spec_agent_cli-0.4.0.tar.gz.
File metadata
- Download URL: spec_agent_cli-0.4.0.tar.gz
- Upload date:
- Size: 185.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ab1bcd84501c726648533426265b992612278a38eaa2572da85ab3b99ddebd99
|
|
| MD5 |
f4074007c134f479897958913e4d0cd8
|
|
| BLAKE2b-256 |
d81e064db32b1362c62333197ea72959df609e675ce108bfeb527edff2516a74
|
File details
Details for the file spec_agent_cli-0.4.0-py3-none-any.whl.
File metadata
- Download URL: spec_agent_cli-0.4.0-py3-none-any.whl
- Upload date:
- Size: 123.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.11.30 {"installer":{"name":"uv","version":"0.11.30","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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
62bedc085aea794d6a396290f608439542796a937c27e707978f3339475644a6
|
|
| MD5 |
7314f98f0bcf6c9d32c221375bd9fd5c
|
|
| BLAKE2b-256 |
7958c18052ede98594ef134a5a766721d182b194f94c73cb484db2c407272b56
|
