Metadata-Version: 2.4
Name: specstamp
Version: 0.11.0
Summary: A local-first, spec-driven development CLI for AI coding agents
Author: muyuqingqiu
License-Expression: Apache-2.0
Project-URL: Homepage, https://muyuqingqiu.github.io/specstamp/
Project-URL: Documentation, https://muyuqingqiu.github.io/specstamp/
Project-URL: Repository, https://github.com/muyuqingqiu/specstamp.git
Project-URL: Issues, https://github.com/muyuqingqiu/specstamp/issues
Project-URL: Discussions, https://github.com/muyuqingqiu/specstamp/discussions
Project-URL: Changelog, https://github.com/muyuqingqiu/specstamp/blob/main/CHANGELOG.md
Keywords: specstamp,sdlc,ai-coding-agent,coding-agent,agentic-coding,ai-coding-agents,local-first,spec-driven-development,document-first,codex,claude-code,requirements,requirements-management,task-management,workflow-automation,developer-tools,traceability,cli,design,acceptance
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: jsonschema<5,>=4.18
Requires-Dist: pypdf<7,>=6
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-cov<8,>=5; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: setuptools>=77; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.6; extra == "docs"
Dynamic: license-file

<p align="right"><strong>English</strong> · <a href="README.zh-CN.md">简体中文</a></p>

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muyuqingqiu/specstamp/main/assets/brand/specstamp-logo-dark.svg">
    <img src="https://raw.githubusercontent.com/muyuqingqiu/specstamp/main/assets/brand/specstamp-logo.svg" alt="SpecStamp" width="640">
  </picture>
</p>

<p align="center">
  <strong>Give AI coding agents a workflow that survives the chat.</strong><br>
  Keep requirements, designs, tasks, changes, and acceptance evidence local, traceable, and recoverable.
</p>

<p align="center">
  <a href="https://pypi.org/project/specstamp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/specstamp?color=F5B942"></a>
  <a href="https://github.com/muyuqingqiu/specstamp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/muyuqingqiu/specstamp/actions/workflows/ci.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/muyuqingqiu/specstamp/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/muyuqingqiu/specstamp/actions/workflows/codeql.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/muyuqingqiu/specstamp/actions/workflows/full-tests.yml"><img alt="Full test suite" src="https://github.com/muyuqingqiu/specstamp/actions/workflows/full-tests.yml/badge.svg?branch=main"></a>
  <a href="https://codecov.io/gh/muyuqingqiu/specstamp"><img alt="Coverage" src="https://codecov.io/gh/muyuqingqiu/specstamp/branch/main/graph/badge.svg"></a>
  <a href="https://github.com/muyuqingqiu/specstamp/blob/main/pyproject.toml"><img alt="Python 3.10 to 3.13" src="https://img.shields.io/badge/Python-3.10--3.13-3776AB?logo=python&logoColor=white"></a>
  <a href="https://github.com/muyuqingqiu/specstamp/blob/main/LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/github/license/muyuqingqiu/specstamp?color=F5B942"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="#why-specstamp">Why SpecStamp</a> ·
  <a href="#workflow">Workflow</a> ·
  <a href="https://muyuqingqiu.github.io/specstamp/">Documentation</a> ·
  <a href="#community">Community</a>
</p>

# 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:

```bash
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](https://muyuqingqiu.github.io/specstamp/quick-start/) to install Agent skills and use SpecStamp in a real project.

## Why SpecStamp

| Common problem | Chat-only workflow | With SpecStamp |
| --- | --- | --- |
| A model or session changes | Context must be explained again | Resume from formal project state |
| Requirements change midway | Design, tasks, and acceptance drift apart | Apply an explicit, versioned change |
| An agent says a task is done | The claim is difficult to verify | Record commands, exit codes, files, and hashes |
| Source material is scattered | Requirements, code, and tests lose their links | Preserve references from source material to acceptance |

## 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

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

| Stage | Common commands | Result |
| --- | --- | --- |
| Initialize and orient | `init`, `init-plain`, `status`, `next` | Establish project state and identify the next step |
| Requirements | `material`, `discuss`, `capture`, `grill` | Preserve source material, structured requirements, and decisions |
| Design and formalize | `design`, `draft`, `start --file` | Create a reviewed requirement and design version |
| Plan and execute | `tasks`, `plan`, `task` | Define task scope, dependencies, tests, and acceptance |
| Verify and finish | `task-evidence`, `task-done`, `regression` | Complete work with reproducible evidence |
| Change and recover | `change-*`, `backup`, `restore`, `handoff` | Handle change explicitly and resume interrupted work |

## Agent integration

```bash
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](https://muyuqingqiu.github.io/specstamp/philosophy/) for the full rationale and project boundaries.

## Documentation

- [Documentation home](https://muyuqingqiu.github.io/specstamp/)
- [Quick Start](https://muyuqingqiu.github.io/specstamp/quick-start/)
- [User Guide](https://muyuqingqiu.github.io/specstamp/user-guide/)
- [FAQ](https://muyuqingqiu.github.io/specstamp/faq/)
- [Philosophy and Inspiration](https://muyuqingqiu.github.io/specstamp/philosophy/)
- [Quality and Security](https://muyuqingqiu.github.io/specstamp/quality-and-security/)
- [中文文档](https://muyuqingqiu.github.io/specstamp/zh-CN/)

## Community

- Ask usage questions and share workflows in [GitHub Discussions](https://github.com/muyuqingqiu/specstamp/discussions).
- Report reproducible problems through [GitHub Issues](https://github.com/muyuqingqiu/specstamp/issues/new/choose).
- Read the [contribution guide](CONTRIBUTING.md) before opening a pull request.
- Report security-sensitive issues through [private vulnerability reporting](https://github.com/muyuqingqiu/specstamp/security/advisories/new).

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](LICENSE). See the [changelog](CHANGELOG.md) for release history.
