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 issue mutations 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, project knowledge, execution attempts, and audit history.

Status: v0.7 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.

Shared project knowledge

pitcrew knowledge create/list/search/show/update provides Markdown pages addressed by project and stable slug, with human/JSON output and audited, revision-checked updates. Knowledge provides guidance, not issue workflow gates. Existing repository documents can be referenced without copying or synchronizing another source of truth. See the knowledge guide. Bounded Unicode-aware lexical search finds current title/body content within one explicit project. The read-only TUI Knowledge tab browses that index, runs the same search, and opens complete current pages without interpreting Markdown.

Bounded lookup and execution evidence

Pitcrew v0.6 adds pitcrew issue query for bounded metadata-only issue lookup and pitcrew execution start/finish/show/list for explicit, audited work attempts. Model requests remain separate from effective observations; unknown telemetry stays unknown. See issue queries and execution records.

Pitcrew v0.7 adds pitcrew issue recover for source-linked task context and pitcrew repo conventions for convention-source discovery at initialization and handoff. Both preserve explicit omissions and unresolved applicability. See focused issue recovery and convention sources.

Bug reports in the example development contract

examples/contracts/software-development-v3.yaml adds a lightweight bug type with optional reproduction steps and implementation notes, using the task workflow. Existing version 2 projects can adopt it through the supplied v2-to-v3 migration; no binary upgrade is required. See the bug report guide.

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.7.4

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 \
  --effort 3 \
  --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

Every issue can independently carry optional Fibonacci effort of 1, 2, 3, 5, or 8 points; omit it for an unestimated issue or clear it later with pitcrew issue update --project payments --issue PAY-1 --effort none. Effort is planning metadata, not time tracking, scheduling, or a workflow gate.

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

Explore interactively

pitcrew tui opens a read-only terminal explorer over the selected SQLite control plane. It provides an adaptive dashboard, project and issue explorers, dependency/relationship graphs, global search, and cursor-paginated Audit history. A project Knowledge tab browses, searches, and reads current guidance. Deep-link directly to a project or issue when investigating a result:

pitcrew tui
pitcrew tui --project PAY
pitcrew tui --issue PAY-1

Use arrow keys or j/k to move, Enter to open, Esc to go back, Tab to change sections, Ctrl+K to search, a for Audit, ? for contextual help, and q to quit. Press y to copy the selected key or ID through OSC52. Set PITCREW_NO_OSC52=1 when terminal clipboard integration is disabled. Opened issues use a compact metadata header and full-width Overview, Links, and Activity panels; Esc restores the project, issue-list, search, or Audit context they were opened from, including the active search query, results, and selection. The framed header identifies the current view/project and executable version. The dashboard stacks a compact project selector above full-width recent activity; project tabs use the full width without a redundant project selector. Issue Overview renders Markdown and separates custom field labels from their values. Within Knowledge, / searches only the current project, Enter opens a page, the usual line/page/Home/End keys scroll it, and y copies PROJECT/slug.

The TUI honors NO_COLOR and automatically uses ASCII UI glyphs for TERM=dumb; set PITCREW_ASCII=1 to force that fallback in any terminal. A missing, inaccessible, or outdated database is reported inside the TUI with its path and recovery guidance. Refresh failures retain the last good frame and mark it STALE.

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
• Software-development contract v3
• Software-development contract v4
• Forward migration v1 to v2
• Forward migration v2 to v3
• Forward migration v3 to v4

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