|
| 1 | +# TABNINE.md |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +**Spec Kit** is an open-source toolkit by GitHub for **Spec-Driven Development (SDD)** — a methodology where specifications are created first and then drive implementation via AI coding agents. The project ships: |
| 6 | + |
| 7 | +- **Specify CLI** (`specify`): A Python CLI that bootstraps projects with templates, scripts, and AI agent integrations for the SDD workflow. |
| 8 | +- **Templates & Commands**: Markdown/TOML command templates for 18+ AI agents (Claude Code, Gemini, Copilot, Cursor, Windsurf, etc.). |
| 9 | +- **Extension System**: A modular plugin architecture for adding commands and functionality without bloating the core. |
| 10 | +- **Scripts**: Bash and PowerShell helpers for feature setup, prerequisite checks, and agent context updates. |
| 11 | + |
| 12 | +### Tech Stack |
| 13 | + |
| 14 | +- **Language**: Python 3.11+ |
| 15 | +- **Package Manager**: [uv](https://docs.astral.sh/uv/) (with `hatchling` build backend) |
| 16 | +- **CLI Framework**: Typer + Rich (for terminal UI) |
| 17 | +- **HTTP Client**: httpx |
| 18 | +- **YAML/Config**: PyYAML, packaging |
| 19 | +- **Linting**: Ruff (Python), markdownlint-cli2 (Markdown) |
| 20 | +- **Testing**: pytest + pytest-cov |
| 21 | + |
| 22 | +### Architecture |
| 23 | + |
| 24 | +- `src/specify_cli/__init__.py` — Main CLI entry point (~2400 lines). Contains `AGENT_CONFIG` (the single source of truth for all agent metadata), `init` and `check` commands, and all project bootstrapping logic. |
| 25 | +- `src/specify_cli/extensions.py` — Extension system (manifest validation, registry, installation/removal, command registration). |
| 26 | +- `templates/` — Spec, plan, tasks, and command templates used during project initialization. |
| 27 | +- `scripts/bash/` and `scripts/powershell/` — Shell scripts for feature creation, prerequisites, and agent context updates. |
| 28 | +- `extensions/` — Extension documentation, catalogs, and the extension template. |
| 29 | +- `tests/` — pytest test suite. |
| 30 | + |
| 31 | +## Building and Running |
| 32 | + |
| 33 | +```bash |
| 34 | +# Install dependencies |
| 35 | +uv sync |
| 36 | + |
| 37 | +# Install test dependencies |
| 38 | +uv sync --extra test |
| 39 | + |
| 40 | +# Run the CLI |
| 41 | +uv run specify --help |
| 42 | +uv run specify init <project-name> --ai claude |
| 43 | +uv run specify check |
| 44 | + |
| 45 | +# Run tests |
| 46 | +uv run pytest |
| 47 | + |
| 48 | +# Run tests with coverage |
| 49 | +uv run pytest --cov=src |
| 50 | + |
| 51 | +# Lint Python |
| 52 | +uvx ruff check src/ |
| 53 | + |
| 54 | +# Lint Markdown |
| 55 | +npx markdownlint-cli2 '**/*.md' '!extensions/**/*.md' |
| 56 | + |
| 57 | +# Build release packages locally (for testing template/command changes) |
| 58 | +./.github/workflows/scripts/create-release-packages.sh v1.0.0 |
| 59 | +``` |
| 60 | + |
| 61 | +## Development Conventions |
| 62 | + |
| 63 | +### General Rules (from AGENTS.md) |
| 64 | + |
| 65 | +- Any changes to `__init__.py` for the Specify CLI **require a version bump** in `pyproject.toml` and an entry in `CHANGELOG.md`. |
| 66 | +- When adding a new AI agent, the `AGENT_CONFIG` dictionary key **must** match the actual CLI executable name (e.g., `"cursor-agent"` not `"cursor"`). This eliminates special-case mappings. |
| 67 | +- New agents require updates across: `AGENT_CONFIG`, CLI help text, `README.md`, release scripts, and agent context update scripts (both bash and PowerShell). |
| 68 | + |
| 69 | +### Code Style |
| 70 | + |
| 71 | +- Python source follows Ruff defaults (no local ruff config — uses defaults). |
| 72 | +- Markdown follows markdownlint-cli2 rules configured in `.markdownlint-cli2.jsonc` (ATX headings, 2-space indent, line length unrestricted). |
| 73 | +- Use docstrings for modules, classes, and public functions. |
| 74 | +- Type hints are used throughout (`typing.Optional`, `typing.Dict`, etc.). |
| 75 | + |
| 76 | +### Testing |
| 77 | + |
| 78 | +- Tests live in `tests/` and follow `test_*.py` naming. |
| 79 | +- pytest is configured with `-v`, `--strict-markers`, `--tb=short`. |
| 80 | +- Tests run on Python 3.11, 3.12, and 3.13 in CI. |
| 81 | +- Use `tempfile.mkdtemp()` for test fixtures requiring filesystem isolation. |
| 82 | +- When adding features or fixing bugs, add or update corresponding tests. |
| 83 | + |
| 84 | +### CI Workflows |
| 85 | + |
| 86 | +- **`test.yml`**: Runs Ruff lint on `src/` and pytest across Python 3.11–3.13. |
| 87 | +- **`lint.yml`**: Runs markdownlint-cli2 on all Markdown files (excluding `extensions/`). |
| 88 | +- **`codeql.yml`**: CodeQL security analysis. |
| 89 | +- **`release.yml`**: Automated release pipeline. |
| 90 | + |
| 91 | +### Key Files |
| 92 | + |
| 93 | +| File | Purpose | |
| 94 | +|---|---| |
| 95 | +| `pyproject.toml` | Project metadata, dependencies, pytest config | |
| 96 | +| `src/specify_cli/__init__.py` | Main CLI (all commands, agent config) | |
| 97 | +| `src/specify_cli/extensions.py` | Extension system implementation | |
| 98 | +| `AGENTS.md` | Detailed guide for adding new AI agent support | |
| 99 | +| `CONTRIBUTING.md` | Contribution guidelines and development workflow | |
| 100 | +| `CHANGELOG.md` | Version history (update on every CLI change) | |
| 101 | +| `templates/` | Spec/plan/task/command templates | |
| 102 | +| `scripts/` | Bash and PowerShell helper scripts | |
0 commit comments