Quick Start

Goal: complete your first SpecStamp run in about ten minutes.

The installation and bootstrap commands in this guide run in a terminal, so they use specstamp. After Agent synchronization, use $sdlc-* inside Codex and /sdlc-* inside Claude Code.

Requirements

macOS, Linux, or another POSIX system
Python 3.10 or newer
Network access to install specstamp, jsonschema, and pypdf

1. Install from PyPI

Create a temporary virtual environment so the first run does not write to global Agent directories:

python3 -m venv /tmp/specstamp-demo/venv
/tmp/specstamp-demo/venv/bin/pip install specstamp

Everything in this example stays under /tmp/specstamp-demo/.

2. Initialize a project

mkdir -p /tmp/specstamp-demo/project
cd /tmp/specstamp-demo/project
/tmp/specstamp-demo/venv/bin/specstamp init-plain

Use specstamp init inside a Git repository. Initialization creates .codex-sdlc/ and project support files; it does not create requirements or tasks automatically.

3. Ask for the next step

/tmp/specstamp-demo/venv/bin/specstamp next

specstamp next recommends one formal next step based on current project state. Use specstamp status for a broader status summary.

Record a requirement

Requirements and decisions are stored as structured JSON rather than free-form CLI text. A coding agent normally turns the conversation into the required JSON, then imports it:

/tmp/specstamp-demo/venv/bin/specstamp discuss --file requirement-record.json

Capture an intermediate conclusion with:

/tmp/specstamp-demo/venv/bin/specstamp capture --file decision-record.json

Synchronize Agent skills

Preview all global changes first:

/tmp/specstamp-demo/venv/bin/specstamp agent-sync --dry-run

When the plan is correct, synchronize and verify managed entries:

/tmp/specstamp-demo/venv/bin/specstamp agent-sync --confirm
/tmp/specstamp-demo/venv/bin/specstamp agent-sync --check

This can write managed entries to Codex, shared Agent, and Claude Code directories. The preview command remains read-only.

Use SpecStamp in Codex

Open Codex in the initialized project and invoke the synchronized skills:

$sdlc-status
$sdlc-next

Use SpecStamp in Claude Code

Open Claude Code in the initialized project and use the synchronized commands:

/sdlc-status
/sdlc-next

Do not replace these client-specific examples with specstamp ...: that form is the terminal CLI, not the Codex or Claude Code invocation syntax.

Verify the installation

/tmp/specstamp-demo/venv/bin/specstamp --help
/tmp/specstamp-demo/venv/bin/specstamp version
/tmp/specstamp-demo/venv/bin/specstamp doctor-install

specstamp doctor-install checks command entry points, dependencies, and Agent skill sources without modifying them.

Managed source installation

Contributors or users who want the repository-managed .venv and $HOME/.local/bin links can clone the repository and run its installer:

git clone https://github.com/muyuqingqiu/specstamp.git
cd specstamp
python3 scripts/install_specstamp.py --dry-run-agent-sync
python3 scripts/install_specstamp.py --confirm-agent-sync
export PATH="$HOME/.local/bin:$PATH"

Cleanup

Project data: preview with specstamp clean, then explicitly run specstamp clean-confirm.
Global installation: remove only the managed command links and entries created by the installer or specstamp agent-sync; do not delete entire Codex, Agent, or Claude directories.

Common installation problems

Command not found: ensure the virtual environment or $HOME/.local/bin is on PATH.
Managed environment missing: rerun the repository installer.
Invalid CODEX_SDLC_PYTHON: run unset CODEX_SDLC_PYTHON, then reinstall or use the virtual environment command directly.