Getting Started¶

Installation¶

From PyPI¶

pip install specsmith

From Source¶

git clone https://github.com/BitConcepts/specsmith.git
cd specsmith
pip install -e ".[dev]"

Verify Installation¶

specsmith --version
# specsmith, version 0.13.0

# Or via python module
python -m specsmith --version

Tutorial: Create a New Python CLI Project¶

This walkthrough creates a governed Python CLI project from scratch.

Step 1: Create the Config¶

Create scaffold.yml:

name: my-tool
type: cli-python
platforms: [windows, linux, macos]
language: python
vcs_platform: github
branching_strategy: gitflow
integrations: [agents-md, agent-skill, claude-code]

Step 2: Scaffold¶

specsmith init --config scaffold.yml --output-dir .

This creates the my-tool/ directory with ~30 files:

my-tool/
├── AGENTS.md                          # Governance hub
├── LEDGER.md                          # Change ledger
├── README.md                          # Project readme
├── CONTRIBUTING.md                    # Contribution guide
├── SECURITY.md                        # Vulnerability reporting
├── CODE_OF_CONDUCT.md                 # Contributor Covenant
├── LICENSE                            # MIT (configurable)
├── pyproject.toml                     # Python project config
├── scaffold.yml                       # specsmith config (saved)
├── .gitignore / .gitattributes
├── docs/
│   ├── governance/
│   │   ├── RULES.md                   # Hard rules H1-H9
│   │   ├── WORKFLOW.md                # Session lifecycle
│   │   ├── ROLES.md                   # Agent boundaries
│   │   ├── CONTEXT-BUDGET.md          # Token optimization
│   │   ├── VERIFICATION.md            # Tools: ruff, mypy, pytest
│   │   └── DRIFT-METRICS.md           # Health signals
│   ├── ARCHITECTURE.md
│   ├── WORKFLOW.md
│   ├── REQUIREMENTS.md
│   └── TESTS.md
├── src/my_tool/
│   ├── __init__.py
│   └── cli.py
├── tests/.gitkeep
├── scripts/
│   ├── setup.cmd / setup.sh
│   ├── run.cmd / run.sh
│   └── exec.cmd / exec.sh
├── .github/
│   ├── workflows/ci.yml               # ruff + mypy + pytest + pip-audit
│   ├── dependabot.yml                 # pip + github-actions
│   ├── PULL_REQUEST_TEMPLATE.md        # Governance-aware PR template
│   └── ISSUE_TEMPLATE/                # Bug report + feature request
├── .agents/skills/SKILL.md            # Generic agent SKILL.md (terminal-native AI runtimes)
└── CLAUDE.md                          # Claude Code governance

Step 3: Verify Governance Health¶

specsmith audit --project-dir my-tool
# Healthy. 9 checks passed.

Step 4: Check Your Tools¶

specsmith doctor --project-dir my-tool
# ✓ lint: ruff (ruff 0.4.x)
# ✓ typecheck: mypy (mypy 1.10.x)
# ✓ test: pytest (pytest 9.x)
# ...

Step 5: Set the AEE Workflow Phase¶

specsmith phase --project-dir my-tool

This shows the current phase (defaults to inception) with a readiness checklist. Advance when checks pass:

specsmith phase next --project-dir my-tool   # advance to architecture
specsmith phase list                         # show all 7 phases

Step 6: Open in Your AI Agent¶

From the project root, use the universal session start command:

/agent AGENTS.md

This works in Claude Code, Cursor, terminal-native AI agents that load .agents/skills/SKILL.md, and any agent that reads project context files. The agent reads AGENTS.md (the governance hub), loads LEDGER.md for session state, and follows the closed-loop workflow.

After the agent is loaded, use the quick command start to trigger the full session start protocol.

Or use Kairos: Launch Kairos and it automatically starts specsmith as a governance backend. The Governance panel shows your current AEE phase, compliance status, and all governance file health.

Tutorial: Import an Existing Project¶

This walkthrough adopts an existing Python project that has no specsmith governance.

Step 1: Run Import¶

specsmith import --project-dir ./my-existing-project

specsmith analyzes the project and reports:

Analyzing C:\path\to\my-existing-project...

  Files: 47
  Language: python
  Build system: pyproject
  Test framework: pytest
  CI: github
  VCS: github
  Inferred type: cli-python
  Modules: myapp
  Existing governance: (none)

Proceed with these settings? [Y/n]:

Step 2: Review Generated Files¶

After confirming, specsmith generates only the missing governance files:

AGENTS.md — populated with detected project info
LEDGER.md — initial import entry
docs/REQUIREMENTS.md — one REQ per detected module
docs/TESTS.md — one TEST per detected test file
docs/architecture.md — modules, entry points, language distribution
docs/governance/*.md — modular governance stubs
scaffold.yml — project config for future commands

If the project already has AGENTS.md (from a previous manual setup), specsmith skips it and only generates what's missing. Use --force to overwrite.

Step 3: Add Architecture (Optional)¶

specsmith import --project-dir ./my-existing-project --guided

The --guided flag prompts you to name your components, then generates richer REQ/TEST stubs and an architecture document.

Step 4: Ongoing Governance¶

Now you can use all specsmith commands:

specsmith audit --project-dir ./my-existing-project    # Health check
specsmith validate --project-dir ./my-existing-project  # Consistency
specsmith export --project-dir ./my-existing-project    # Coverage report
specsmith doctor --project-dir ./my-existing-project    # Tool check

What Happens With Different Project Types¶

The scaffold structure changes based on project type. A patent application:

specsmith init --config patent.yml

Gets: claims/, specification/, figures/, prior-art/, correspondence/ directories, claim-specific REQs (REQ-CLM-001), and governance rules about claim dependencies.

A Rust CLI project gets: src/, tests/, benches/ directories, CI with cargo clippy, cargo test, cargo audit, and rules about clippy warnings and doc comments.

See Project Types for all 30 types.