anspar-wf 0.2.1
Development toolchain for requirement-traceable software projects
License: MIT
Requires Python: >=3.10
Keywords: requirements, traceability, compliance, workflow, development-tools

# anspar-wf

Add standardized git hooks, linting, and development workflow to any project.

anspar-wf generates config-driven git hooks (pre-commit, commit-msg, pre-push) tailored to your project's languages and tools. It auto-detects your stack, installs the right linters and scanners at pinned versions, and keeps everything up to date as your config or anspar-wf itself evolves.

## Quick Start

```bash
pip install anspar-wf
cd ~/your-project
anspar-wf init
```

That's it. `init` will:

1. Detect your project's languages (Python, Dart, TypeScript, Docker)
2. Generate a `.anspar-wf.toml` config file
3. Create git hooks in `.githooks/` and point `core.hooksPath` to them
4. Offer to install any missing external tools at pinned versions
5. Optionally set up Claude Code integration (session-start hook, plugins)

Edit `.anspar-wf.toml` to customize, then run `anspar-wf upgrade` to regenerate hooks.

## Commands

| Command | Description |
|---------|-------------|
| `anspar-wf init [PATH]` | First-time project setup: config, hooks, tools |
| `anspar-wf upgrade [PATH]` | Update hooks after config or version changes |
| `anspar-wf version [PATH]` | Show anspar-wf and project version info |
| `anspar-wf version check [PATH]` | Health check: config, hook drift, tool versions |

## What You Get

### Git Hooks

**pre-commit** — Runs on every commit:
- Branch protection (block direct commits to main/master)
- Secret scanning via gitleaks
- Language-specific linting (ruff for Python, dart analyze, eslint, hadolint)
- Markdown linting

**commit-msg** — Validates commit messages:
- Require ticket references (e.g., `CUR-123`)
- Optionally require requirement references (e.g., `REQ-d00042`)

**pre-push** — Runs before pushing:
- PR-aware blocking (warn vs block depending on PR state)
- Full test suite execution
- Secret scanning across all commits being pushed
- Language-specific checks (ruff, pytest, dart format/analyze)

**post-commit** — Optional post-commit automation

### External Tools

Managed at pinned versions via `versions.lock`:

| Tool | Purpose |
|------|---------|
| **gitleaks** | Secret detection |
| **ruff** | Python linter |
| **elspais** | Requirement validation and traceability |
| **squawk** | PostgreSQL migration linter |
| **markdownlint-cli** | Documentation linting |

During `init`, anspar-wf checks which tools are missing or outdated and offers to install them.

## Upgrading

When you update anspar-wf or change `.anspar-wf.toml`, run:

```bash
anspar-wf upgrade
```

Upgrade uses three-way comparison (stored hash vs. on-disk vs. target) to safely update hooks while preserving any local tweaks you've made. If there's a conflict (you modified a hook *and* a new version is available), it reports the conflict and shows a diff.

## Claude Code Plugins (Optional)

Three plugins for developers using [Claude Code](https://claude.ai/code):

- **workflow** — Ticket lifecycle management, branch protection, task-switch detection
- **spec-compliance** — AI-powered content validation for spec/ files
- **plugin-wizard** — Scaffold new Claude Code plugins

Plugins are automatically registered during `init` if Claude Code is detected (`.claude/settings.json` exists), and kept in sync during `upgrade`.

## CI Integration

```yaml
- name: Setup anspar-wf
  run: |
    pip install anspar-wf
    anspar-wf init .
```

Or just verify an already-initialized project:

```yaml
- name: Check tool versions
  run: anspar-wf version check .
```

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check src/
```