A versioned documentation layer for AI-assisted development. spec maintains a separate Git repository of contextual documentation that helps AI agents understand your codebase without polluting your main Git history.
- AI-Optimized Context: Structured documentation designed for LLM consumption
- Version-Controlled Memory: AI agents can learn from past attempts and decisions
- Isolated Git History: Documentation changes don't clutter your main repository
- Scoped Context Windows: Load only relevant documentation to fit within token limits
- Rich Terminal UI: Beautiful, colorful interface with progress indicators
- Modular Architecture: Clean, testable codebase built for extensibility
pip install spec-cli# Initialize spec in your project
spec init
# Generate documentation for files
spec gen src/models.py # Single file
spec gen src/ # Directory
spec gen . # Current directory (all files)
# Track documentation changes
spec add .
spec commit -m "Document authentication flow"
# View documentation status
spec status
spec log
spec diff- Project Initialization:
spec initcreates isolated Git repository structure - Documentation Generation:
spec gencreates structured documentation with templates - Version Control: Full Git workflow (
add,commit,status,log,diff) - Template System: Customizable documentation templates via
.spectemplate - File Filtering: Smart filtering with
.specignorepatterns - Rich Terminal UI: Beautiful interface with colors, progress bars, and styling
- Batch Processing: Generate documentation for entire directories
- File Type Detection: Support for 20+ programming languages and file types
- Conflict Resolution: Interactive handling of existing documentation
- Debug Mode: Comprehensive debugging with
SPEC_DEBUG=1 - Modular Architecture: Clean, maintainable codebase with 80%+ test coverage
- AI Documentation Generation: Replace placeholder content with AI-generated documentation
- Git Hook Integration: Auto-generate documentation on code changes
- Enhanced CLI: Advanced options and configuration management
spec creates two directories:
.spec/- A bare Git repository (like.git).specs/- Working tree containing documentation
Your documentation mirrors your project structure:
project/
├── .spec/ # Bare Git repo for versioning
├── .specs/ # Documentation working tree
│ ├── src/
│ │ └── models/
│ │ ├── index.md
│ │ └── history.md
│ └── api/
│ └── users/
│ ├── index.md
│ └── history.md
├── .spectemplate # Customizable templates
├── .specignore # Ignore patterns
├── src/
│ └── models.py
└── api/
└── users.py
Each source file gets a documentation directory with:
index.md: Current understanding and specificationshistory.md: Evolution, decisions, and lessons learned
spec init- Initialize spec in current directoryspec gen <path>- Generate documentation for file(s) or directoryspec add <path>- Stage documentation changesspec commit -m "message"- Commit documentation changes
spec status- Show documentation statusspec log [path]- Show documentation historyspec diff [path]- Show uncommitted changesspec show <path>- Display documentation for a file (coming soon)
spec regen <path>- Regenerate documentation (preserves history)spec agent-scope [options]- Export scoped context for AI agents
Create a .spectemplate file to customize documentation format:
index:
template: |
# {{filename}}
**Location**: {{filepath}}
**Purpose**: {{purpose}}
**Responsibilities**: {{responsibilities}}
**Requirements**: {{requirements}}
**Example Usage**: {{example_usage}}
**Notes**: {{notes}}
history:
template: |
## {{date}} - Initial Creation
**Purpose**: Created initial specification for {{filename}}
**Context**: {{context}}
**Decisions**: {{decisions}}
**Lessons Learned**: {{lessons}}Control spec behavior with environment variables:
SPEC_DEBUG=1- Enable debug output for troubleshootingSPEC_DEBUG_LEVEL=INFO|DEBUG|WARNING|ERROR- Set debug levelSPEC_DEBUG_TIMING=1- Enable operation timing
Use .specignore to exclude files from documentation generation:
# Ignore patterns
*.log
node_modules/
build/
*.min.js
spec follows a clean, modular architecture built through a comprehensive refactoring:
spec_cli/
├── cli/ # Command-line interface layer
├── core/ # Core business logic and workflow orchestration
├── git/ # Git operations abstraction
├── templates/ # Template system for documentation generation
├── file_system/ # File system operations and path handling
├── config/ # Configuration management
├── ui/ # Rich terminal UI components
├── file_processing/ # Batch processing and conflict resolution
├── exceptions.py # Custom exception hierarchy
└── logging/ # Debug logging and timing
- Single Responsibility: Each module has a clear, focused purpose
- Dependency Injection: Services are easily testable and mockable
- Clean Interfaces: Well-defined boundaries between layers
- Rich Terminal UI: Beautiful, colorful interface throughout
- Comprehensive Testing: 80%+ test coverage across all modules
This project uses Poetry for dependency management and uv for virtual environments:
# Create virtual environment with uv
uv venv
# Activate virtual environment
source .venv/bin/activate # On Unix/macOS
# or
.venv\Scripts\activate # On Windows
# Install dependencies with poetry
poetry install
# Run tests with coverage (80% minimum required)
poetry run pytest tests/unit/ -v --cov=spec_cli --cov-report=term-missing --cov-fail-under=80
# Run type checking
poetry run mypy spec_cli/
# Run linting and formatting
poetry run ruff check --fix .
poetry run ruff format .
# Run all pre-commit hooks
poetry run pre-commit run --all-files- Provide rich context to AI coding assistants
- Track why certain approaches failed
- Maintain institutional knowledge across AI sessions
- Export scoped documentation for specific tasks
- Onboard new developers with comprehensive docs
- Document architectural decisions and trade-offs
- Track technical debt and future improvements
- Maintain living documentation that evolves with code
- Understand the "why" behind implementations
- Review documentation changes alongside code
- Ensure specs stay synchronized with reality
- Track decision history and lessons learned
Hide .spec/ and .specs/ directories in your IDE. For VSCode, add to workspace settings:
{
"files.exclude": {
".spec": true,
".specs": true
}
}pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --pre spec-aiWe follow a vertical slice development philosophy - implementing features completely through implementation, testing, and typing before moving on. See CLAUDE.md for detailed development guidelines.
MIT License - see LICENSE for details.