Local Development

Guide for contributing to the Maistik Spec Kit CLI.

Setup

git clone https://gitlab.com/maistik-studio/tools/spec-kit.git
cd spec-kit

Run the CLI Directly

No install needed — run via module entrypoint:

python -m src.specify_cli --help
python -m src.specify_cli init demo-project --ai claude --ignore-agent-tools

Editable Install

For a development environment with the specify command available:

uv venv
source .venv/bin/activate  # or .venv\Scripts\Activate.ps1 on Windows

uv pip install -e .
specify --help

Changes to source code are reflected immediately (no reinstall needed).

Test with uvx

Simulate end-user flows:

# From repo root
uvx --from . specify init demo-uvx --ai claude --ignore-agent-tools

# From a specific branch
git push origin my-feature
uvx --from git+ssh://git@gitlab.com/maistik-studio/tools/spec-kit.git@my-feature specify init demo-branch-test

Testing

# Full test suite
make test

# Quick tests (no slow markers)
make test-quick

# Lint
make lint

# Lint with auto-fix
make lint-fix

Build

uv build
ls dist/

Documentation

cd docs
npm install
npm run docs:dev      # Dev server at localhost:5173
npm run docs:build    # Build for production
npm run docs:preview  # Preview built site

Verify Scripts

After running init, check that shell scripts are executable:

ls -l .specify/scripts/bash/ | grep .sh
# Expect -rwxr-xr-x

Project Structure

src/specify_cli/
├── __init__.py       # Main CLI (typer app, commands, GitLab API)
└── extensions.py     # Extension system, agent configs, catalog

templates/
├── commands/         # Slash command definitions
├── *-template.md     # Spec templates

scripts/
├── bash/             # Shell scripts
└── powershell/       # PowerShell scripts

docs/                 # VitePress documentation

Common Issues

Symptom	Fix
ModuleNotFoundError: typer	uv pip install -e .
Scripts not executable	chmod +x .specify/scripts/bash/*.sh
TLS errors	--skip-tls (dev only)
Wrong script type	Pass --script sh or --script ps

Submitting Changes

1. Create a feature branch
2. Make your changes
3. Run tests: make test
4. Run lints: make lint
5. Push and create a merge request on GitLab