The pit crew for agentic coding.
A controlled workflow for agentic software development.
PitWay is an npm-distributed CLI that controls the engineering process around AI coding agents — it is not itself an agent.
- Agents drive the interaction
- PitWay controls workflow state, engineering boundaries, verification, and traceability
AI coding agents move fast — and that's exactly the problem. Left unstructured, an agent can drift from what was asked, skip verification, or quietly touch files outside its intended scope, with no durable record of what actually happened or why.
PitWay doesn't replace the agent driving your work — it gives that work a process:
- A confirmed plan before code. Every milestone starts as a contract — objective, acceptance criteria, verification checks — reviewed and approved by a human before any implementation begins.
- Boundaries an agent can't quietly cross.
write_scopemechanically limits what a task may touch. - Verification, not vibes. Every task is checked against its own declared command before it's considered done, with a mandatory full test suite gating milestone completion.
- A record that survives the conversation. Git commits carry traceable
PitWay-Milestone/PitWay-Tasktrailers — the history holds even after the AI session that produced it is gone.
The result: agents move fast, and the engineering process stays in control of where they land.
Source: docs/assets/workflow.mmd (Mermaid) — rendered to SVG so it displays on npmjs.com too, which doesn't render Mermaid.
Workflow Lifecycle:
Requirement → Milestone (Contract ⇄ Milestone Review) → Human Approval → Task Graph → [TDD ⇄ Task Verification → Task Commit]* → Final Full Test (fail ⇒ revision loop) → Milestone Complete → Milestone Merge — plus a Quick Change lane for small bounded fixes whenever no milestone is active.
- Workflow Enforcement: Validates state transitions and enforces task write boundaries.
- Two-Tier Verification: Runs targeted verification for each task, followed by a mandatory full test suite before closing the milestone.
- Durable State: Creates traceable Git checkpoints without relying on transient AI conversation memory.
- A new capability, not started yet → a Milestone (contract, task graph, human approval).
- Work discovered while a milestone is active → a Task if it belongs in the graph, or the Backlog if it doesn't.
- A small, independent fix, no milestone active → a Quick Change — bounded, single-commit.
- Running work in parallel → an execution mode (
execution.strategy: parallel_worktrees), not a separate lane — it applies within whichever of the above you're already using.
See USAGE.md for the full walkthrough of each, and Driver Roles for who runs which command when a milestone is executed.
Run once from the root of a Git repository (run git init first if needed):
npm install -g pitway
pitway init- PitWay initializes
.pitway/and installs the Claude Code integration by default. - Use
pitway init --no-claudeto opt out of the Claude Code integration. - Use
pitway init --opencodeto also install the OpenCode integration (.opencode/— commands, skills, and driver protocol documents). - Use
pitway init --codexto also install the Codex integration (.codex/— commands, skills, and driver protocol documents). - Upgraded
pitway? Runpitway init --reconfigure. A plain re-run ofpitway initonly fills in files that don't exist yet — it never updates ones you already have, so installed commands/skills/protocol docs silently go stale after an upgrade.--reconfigurerefreshes every managed integration asset to the newly installed version;.pitway/state (milestones, contracts, tasks) is always preserved. initalso creates rootAGENTS.md/CLAUDE.mdinstruction files. PitWay's content lives inside an explicit<!-- pitway:managed:start/end -->block — if you already have your ownAGENTS.mdorCLAUDE.md, the block is appended and your content is left intact; PitWay only ever owns the marked block.
Inspect or continue the current workflow at any time:
pitway resume📌 Commit Traceability: Before implementation begins, the developer reviews and confirms the milestone contract. Task commits carry
PitWay-MilestoneandPitWay-TaskGit trailers; milestone baseline and completion commits carry the milestone trailer.
📊 Progress at a Glance: Once a milestone is confirmed, routine driver updates end with a one-line progress footer (e.g.
🏎️ 54% · ✅ 7/12 · Next: T008).pitway milestone-status [id]renders the full status report — workload, task table, critical path, token breakdown, and a racing footer with progress bar — for the active milestone by default, or an explicit id for any milestone.
Run the following for the full, authoritative CLI command surface and available flags:
pitway --helpFor a hands-on walkthrough of the whole workflow — drafting a contract, confirming a milestone, working a task through to completion — see USAGE.md.
💡 Driver Support: Claude Code (installed by default), OpenCode (opt-in), and Codex (opt-in) driver integrations ship as text assets from a shared common layer — skills, protocol documents, and command docs are defined once and resolved per driver (Claude Code carries whole-file command overrides only for its own
argument-hintfrontmatter). PitWay's Core remains provider-agnostic.
⚠️ What PitWay enforces vs what relies on driver discipline. Mechanically enforced: the state machines,write_scopeboundaries, verification gates, commit trailers, and git-safety checks — no driver can bypass these through the CLI. Installed-instruction-only: stopping for human approval gates, driver-presented progress footers, and bounded worker reports are mandated by the installed protocol documents every driver loads, but PitWay cannot observe a live session's obedience — violations surface in review/audit, never at runtime.
- Command Reference: Run
pitway --helpfor the full, authoritative CLI command surface and available flags. Themilestone-*commands also answer to shorterms-*aliases (pitway ms-status,ms-confirm,ms-merge, …). - Usage Guide: See USAGE.md for a hands-on walkthrough — installation, your first milestone end to end, inspecting state, mid-flight corrections, and a full command reference table.
- Claude Code:
pitway initinstalls PitWay's commands as real Claude Code slash commands (.claude/commands/*.md, each carryingdescription/argument-hintmetadata for the/picker), alongside the driver protocol documents that explain how and when to use them. - OpenCode:
pitway init --opencodeinstalls the same command surface in OpenCode's own convention (.opencode/commands/*.md) plus the shared skills and protocol documents. Command docs, skills, and protocol content all come from the common layer — defined once, never forked per driver. - Codex:
pitway init --codexinstalls the same command surface in Codex's convention (.codex/commands/*.md) plus the shared skills and protocol documents. Command docs, skills, and protocol content all come from the common layer — defined once, never forked per driver.
PitWay's driver protocol is written for three roles. One AI session may play the first two together (the default), or two sessions may split them; workers are always separate.
- Main Agent (
protocol-driver.md) — talks to the developer, presents plans and results, and runs every gate and scope command:milestone-add,milestone-confirm(and--amend),milestone-complete,milestone-merge,milestone-cancel,task-add,task-amend, allquick-changesubcommands,milestone-review decide,verification-repair approve,auto-run enable|disable. - Orchestrator (
protocol-orchestrator.md) — plans and drives execution inside an already-confirmed milestone:task-update,task-verify,task-dispatch|integrate|discard,verify,usage-add,backlog add|promote|archive,milestone-review start|brief|record|report,verification-repair propose|commit|cancel. It surfaces every human decision to the Main Agent and never decides one itself. - Worker (
protocol-worker.md) — executes one bounded task from its context bundle and reports back; it never callspitwayor touches.pitway/.
Read-only commands (resume, milestone-status, task-status, …) belong to either role. The command-by-command partition and its rationale are recorded in docs/architecture/orchestrator-role.md. The Main/Orchestrator boundary is protocol-enforced — installed and pinned as instruction text, detected in review, never prevented at runtime — exactly like every other approval gate; what PitWay enforces at runtime (state machines, write_scope, verification-hash approval, commit trailers, git safety) is unchanged. Repositories initialised before protocol-orchestrator.md shipped receive it on the next pitway init --reconfigure.
| Boundary Property | Behavior & Scope |
|---|---|
write_scope |
Mechanically enforced task boundary to prevent unintended file modifications. |
context_files |
Limits task-context bundles supplied by PitWay (not an OS-level read sandbox). |
| Agent Runtime | PitWay does not claim control over external agent runtimes, shells, or OS tool permissions. |
| Milestone Review | Reviewers produce findings only. PitWay does not run reviews or verify reviewer independence. |
Two repository-level policies live in .pitway/config.yaml. pitway init generates them with the recommended workflow enabled (with explanatory comments in the file):
git:
branch_strategy: milestone # each milestone gets its own dedicated branch
execution:
strategy: parallel_worktrees # independent tasks dispatch concurrentlygit.branch_strategy: main | milestone—milestone(the generated default) gives each milestone its own dedicated branch, checked out for the milestone's full lifecycle; once completed,pitway milestone-merge <id>lands the branch into its base branch with full git-safety checks and idempotent re-runs. Setmainto commit milestones directly to the current branch instead.execution.strategy: sequential | parallel_worktrees—parallel_worktrees(the generated default) lets independent, dependency-free, disjoint-write_scopetasks dispatch concurrently, each into its own temporary Git worktree; PitWay validates eligibility and integrates each result as a diff-apply — never a merge — so the resulting mainline history stays indistinguishable from sequential execution. Setsequentialto run one task at a time, inline.
PitWay is developed and maintained using its own workflow:
- M001–M003: Bootstrap foundation
- M004: Crossed the self-hosting boundary
- M005+: Created, verified, and completed entirely through PitWay
All project claims are bounded strictly by evidence that survives a fresh clone: committed Git history, .pitway/ state, and the automated test suite.
Dependency updates arrive as Dependabot pull requests (weekly, grouped dev-dependencies, no auto-merge — see .github/dependabot.yml). Dependabot security alerts are a repository setting, not something this file turns on: enable them under Settings → Code security if you want them.
Static analysis runs via CodeQL (.github/workflows/codeql.yml), scanning the TypeScript/JavaScript source for common vulnerability patterns. Follows GitHub's default cadence: every push and pull request to main, plus a weekly schedule. Results appear under the repository's Security → Code scanning tab.
See SECURITY.md for how to report a vulnerability.
For changes and improvements introduced in each published version, see CHANGELOG.md.
There is a way to build with agents. This is PitWay.
MIT — see LICENSE.