pitcrew

README

Pitcrew

Pitcrew is a local-first quality-system CLI for solution-development workflows shared by humans and AI agents. A versioned declarative contract defines the allowed issue types, fields, priorities, roles, states, and transitions. Pitcrew validates every mutation against that contract and records the resulting state and audit history in SQLite.

The SQLite control plane is the portability boundary: move a safe backup of the database and you move the installed contracts, migrations, projects, issues, relationships, actor profiles, upgrade plans, resolutions, and audit history.

Status: v0.1 is an early release. The core workflows are usable, but compatibility may still evolve before v1.0. See CHANGELOG.md.

Why Pitcrew?

• One source of truth: all durable application state lives in SQLite.
• Contract-driven work: invalid fields, states, and transitions are rejected.
• Human and agent friendly: every command has contextual help and stable schemaVersion: 1 JSON output.
• Auditable: mutations retain actor attribution and immutable history.
• Safe evolution: contract upgrades are planned before they are applied and execute atomically.
• Portable binaries: release artifacts do not require CGO or an external SQLite installation.

Install

Release archive

Download the archive for your operating system and architecture from GitHub Releases, verify it against checksums.txt, and place pitcrew (or pitcrew.exe) on your PATH.

Go install

With the Go version declared in go.mod or newer:

go install github.com/feanor41/pitcrew/cmd/pitcrew@v0.1.0

Build the repository

git clone https://github.com/feanor41/pitcrew.git
cd pitcrew
make build
./bin/pitcrew --version

The build target embeds the value from VERSION. Plain go build development binaries report dev; versioned go install builds recover their module version from Go build metadata.

Ten-minute quickstart

The following walkthrough uses a database in the current directory so it is easy to inspect or remove afterward:

export PITCREW_DB="$PWD/pitcrew-demo.db"

# Install the initial contract and create its first project era.
pitcrew contract install examples/contracts/software-development-v1.yaml
pitcrew project create \
  --key PAY \
  --name payments \
  --contract software-development \
  --contract-version 1

# Work is validated against the contract bound to the active era.
pitcrew issue create \
  --project payments \
  --type feature \
  --title "Refund payments" \
  --priority high \
  --fields '{"acceptance-criteria":"A refund can be completed"}'
pitcrew issue transition --project payments --issue PAY-1 --to in-progress
pitcrew project progress --project payments

# Install v2 and its direct, forward-only migration.
pitcrew contract install examples/contracts/software-development-v2.yaml
pitcrew migration install \
  examples/migrations/software-development-v1-to-v2.yaml

# Preflight first, then atomically apply the ready plan.
pitcrew project upgrade preflight --project payments --to-version 2
pitcrew project upgrade show --plan 1
pitcrew project upgrade apply --plan 1
pitcrew project show --project payments

The example migration renames acceptance-criteria to success-criteria, so the issue can migrate automatically. Migrations that lose information or need judgment produce manual plan items instead; see the functional guide.

Discover the CLI

Help is hierarchical, exits successfully, writes to stdout, and never opens or creates the SQLite database:

pitcrew --help
pitcrew project --help
pitcrew project upgrade apply --help
pitcrew help issue create
pitcrew help project upgrade apply --format json

Use --format json on operational commands for stable machine-readable output. Agents can traverse immediate subcommands through JSON help without parsing human usage text.

pitcrew version --format json
pitcrew issue show --project payments --issue PAY-1 --format json

Data location and portability

Set PITCREW_DB to select the database explicitly. Otherwise Pitcrew uses the platform configuration directory, such as ~/.config/pitcrew/database.db on Linux.

Do not copy a live SQLite file blindly: WAL sidecars may contain committed state. Follow the backup, restore, and portability guide before moving the control plane.

Documentation

• Functional guide — concepts and end-to-end workflows.
• Architecture — boundaries, packages, persistence, transactions, and compatibility model.
• Operations — database location, backup, restore, recovery, permissions, and upgrades.
• Declarative contract specification — executable contract and migration reference.
• Release history and known limitations.
• Release procedure.
• Contributing.
• Security policy.

Example documents:

• Software-development contract v1
• Software-development contract v2
• Forward migration v1 to v2

Development

make check          # format, modules, tests, race detector, and vet
make release-dist   # cross-platform archives and SHA-256 checksums

CI also runs govulncheck and verifies release packaging. Tags must match v$(cat VERSION); pushing a matching tag builds and publishes the GitHub release archives.

License

MIT