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.28 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/aggregate for explicit, audited work attempts and bounded retry/concurrency summaries. Execution starts also transition the issue through a contract-declared work state before recording; an audited continuation path preserves non-blocking recovery when that transition cannot be made. 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.

pitcrew issue review adds a bounded advisory readiness view and non-blocking review handoff built from the same recorded issue and execution context. When an independent-review attempt has reviewer metadata for another contract version, it remains visible as role-version-mismatch with advisory readiness; it is not treated as missing evidence or a completion gate.

Pitcrew v0.8 adds explicit oversized-effort assessment for issue sizing and a reproducible local benchmark for execution-capture overhead.

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.28.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 \
  --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 an optional positive integer effort; 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. Values above 8 are reported as oversized: non-feature issues receive a decomposition recommendation, while features remain valid and are flagged for review.

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
pitcrew brief --role coordinator --format json

Explore interactively

pitcrew tui opens a terminal explorer over the selected SQLite control plane. Its dashboard, project, issue, dependency, relationship, search, Audit, and Knowledge views are read-only; the Harness brief screen is the deliberate exception for editing the current repository's local brief override. 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. The project's Issues tab queries the complete unarchived catalog in pages of 50. Use n/p for next/previous pages and f for exact contract IDs, for example state:open type:task priority:high; omit a field for any value or clear the line to remove structured filters. / searches a literal substring in issue keys, titles and descriptions across the full filtered catalog (ASCII case-insensitive; Unicode case matching is literal). The global Issues screen's / remains a filter of its loaded records only. Press h to include closed unarchived issues and again to return to unarchived nonterminal work. Press o for priority or newest issue order. Changing filters, text, history scope or order starts at page 1. Matched totals are distinct from loaded page records and visible grouped placements; requirements reached through links remain page context. Grouping and direct-link trays retain their existing controls and indicate partial relationships. Pages are live reads, so concurrent changes do not form a snapshot. Refresh and return from issue detail retain the page and selected issue/occurrence. Opened issues use a compact metadata header and full-width Overview, Links, Activity, and Executions 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. Issue lists use aligned Key, State, Priority, Membership and Title columns, with Type and Effort added when space permits. Compact layouts keep the full record available in issue detail. Group headers span the ledger; shared and partial membership and the bottom direct-link tray remain explicit. Key chips such as [enter] open describe keyboard actions; ? opens the full context help. Inputs and validation errors are bordered and keep apply/cancel visible. Executions uses the same ledger with ID, Purpose, Result and Executor columns, and aligned labels in detail.

Executions lists read-only attempts in ascending ID order, 20 per page. Use n/p for pages and Enter for full evidence and model provenance. In detail, line/page/Home/End keys scroll, t follows only a recorded retry parent, and Esc returns to the prior execution or list. Refresh retains the selected execution ID. An unfinished record does not establish host liveness; a recorded review outcome does not establish approval when reviewer-role classification is absent. Project Attention is a read-only inbox across the complete relevant project, with live bounded pages. It lists declared nonterminal pending-approval and changes-requested states using each issue's own era/type contract, unresolved direct dependencies and explicit unknown context. State names are not guessed. Counts distinguish reason occurrences from unique source issues. Terminal targets resolve dependencies according to their own contract, including cancelled states; archived nonterminal targets remain unresolved and are marked archived. This is informational, not approval or an execution gate. Enter opens the source issue, t opens a recorded known target, and v toggles scrollable full reason and source/target context. n/p change pages; refresh and return preserve occurrence identity. A missing reader or context is reported explicitly. On narrow terminals, … marks hidden project tabs; Tab/Shift+Tab still reaches every section.

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.

Press b from the dashboard or issue detail to view the Harness brief. Tab switches between the core and coordinator parts; e edits the selected part, Ctrl+S saves it, and R resets it to the embedded default. See the Harness brief guide for delivery roles, modules, export/import bundles, optimistic revision checks, and activation semantics.

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.
• Harness brief delivery and overrides — core and coordinator delivery, modules, TUI/CLI editing, export/import bundles, revision checks, reset, and activation behavior.
• 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
• Software-development contract v5
• Forward migration v1 to v2
• Forward migration v2 to v3
• Forward migration v3 to v4
• Forward migration v4 to v5

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