English · 简体中文

Give AI coding agents a workflow that survives the chat.
Keep requirements, designs, tasks, changes, and acceptance evidence local, traceable, and recoverable.

Quick start · Why SpecStamp · Workflow · Documentation · Community

SpecStamp: a local-first workflow for AI coding agents

SpecStamp is a Python CLI that brings spec-driven development to Codex, Claude Code, and other AI coding agents. It stores requirements, technical designs, task plans, changes, and acceptance evidence as structured project files, so development does not depend on one conversation or one agent.

The primary command is specstamp. The compatible codex-sdlc command remains available for existing workflows. Agent capabilities are exposed through the bundled sdlc-* skills.

Status: Beta. SpecStamp supports Python 3.10–3.13 on macOS, Linux, and other POSIX systems. Windows is not currently supported.

Quick start

The following commands install SpecStamp from PyPI in a temporary environment. They do not write to global Agent directories:

DEMO_DIR="$(mktemp -d "${TMPDIR:-/tmp}/specstamp-demo.XXXXXX")"
python3 -m venv "$DEMO_DIR/venv"
"$DEMO_DIR/venv/bin/pip" install specstamp
mkdir "$DEMO_DIR/project"
cd "$DEMO_DIR/project"
"$DEMO_DIR/venv/bin/specstamp" init-plain
"$DEMO_DIR/venv/bin/specstamp" next

next reads the current formal state and recommends the next workflow step. See the Quick Start to install Agent skills and use SpecStamp in a real project.

Why SpecStamp

Core capabilities

• Local first: project data lives in .codex-sdlc/; no cloud account or automatic upload is required.
• Cross-agent: synchronize one versioned skill set to Codex, Claude Code, and shared Agent directories.
• Traceable: keep source material, decisions, designs, tasks, and changes under stable identifiers with SHA-256 evidence.
• Evidence-based completion: require real commands, integer exit codes, source files, hashes, and acceptance results before completion.
• Recoverable: continue after a new session, branch switch, pause, or restored backup without reconstructing the project from chat history.

Who it is for

• Developers and small teams using Codex, Claude Code, or other coding agents.
• Projects adopting spec-driven development, requirements management, or auditable delivery.
• Long-running work that needs requirements, design, tasks, tests, and acceptance to remain connected.

SpecStamp is not a cloud collaboration platform and does not provide real-time multi-user editing.

Workflow

idea → source material → reviewed requirements → integrated design → formal version
→ task plan → implementation and evidence → acceptance → explicit changes

Agent integration

specstamp agent-sync --dry-run   # preview without writing
specstamp agent-sync --confirm   # synchronize managed entries
specstamp agent-sync --check     # verify the result without writing

The synchronization command supports:

• Codex: versioned sdlc-* skills.
• Claude Code: compatible /sdlc-* commands.
• Shared Agent directories: the same managed skill source for other agents.

Design principles

Files are more durable than chat history. Reproducible evidence is more reliable than an agent's claim. Explicit changes are safer than silent drift. Agents may change; project facts should not.

Read Philosophy and Inspiration for the full rationale and project boundaries.

Documentation

• Documentation home
• Quick Start
• User Guide
• FAQ
• Philosophy and Inspiration
• Quality and Security
• 中文文档

Community

• Ask usage questions and share workflows in GitHub Discussions.
• Report reproducible problems through GitHub Issues.
• Read the contribution guide before opening a pull request.
• Report security-sensitive issues through private vulnerability reporting.

If SpecStamp improves your AI coding workflow, consider starring the repository and sharing what you built with it.

License

SpecStamp is licensed under Apache-2.0. See the changelog for release history.