Pipekit

A structured way to ship software with AI — from idea to production, with a quality gate at every stage.

v5.3.2 — Last updated: 2026-10-31. Release history and per-version notes: CHANGELOG.md. MIT licensed.

What is Pipekit?

Pipekit takes a project from a raw idea to production through a fixed sequence of stages, each with a gate the work must pass before it moves on. You run it inside Claude Code; it tracks every piece of work in Linear.

Pipekit is the structure around an executor, not the executor itself. It does not write your code directly. The build step runs on Claude Code's own Workflow primitive, and Pipekit owns everything around it: how a feature gets specified, how the work is reviewed, where a human signs off, and how the change reaches production.

The one rule above all others: no stage may introduce guesswork into the next stage. A spec must be complete enough to plan from; a plan complete enough to build from. When a stage finds ambiguity, the work goes backward to be clarified, not forward into a guess.

Pipekit bets on enforcement, not memory. A more capable model produces more plausible mistakes, and one agent doing everything in a long session has no independent check on its own judgment. The gates exist for exactly that: a spec a separate reviewer must pass, a plan an independent agent stress-tests, a verify step that reads the acceptance criteria rather than the executor's narration, an antagonistic review that approaches the diff cold. A bigger context window changes how much an agent can hold; it does not change whether an agent can independently judge work it helped produce.

Requirements

Optional, used only if present: the Supabase CLI (migration checks in pk done), 1Password op + direnv (secrets into worktrees), Semgrep and a CLAUDE_CODE_OAUTH_TOKEN repo secret (the CI review templates in templates/ci/), cmux (orchestrating worker sessions). None of these is needed for the daily loop.

Install — the first fifteen minutes

1. Pull Pipekit into your repo. No local clone needed; the script pulls from GitHub.

cd ~/Projects/my-project            # an existing repo, or `git init` a new one
mkdir -p scripts
curl -fsSL https://raw.githubusercontent.com/withpiper/pipekit/main/scripts/sync-method.sh -o scripts/sync-method.sh
chmod +x scripts/sync-method.sh
./scripts/sync-method.sh            # --dry-run to preview; --help for flags

This writes .claude/skills/ (the skills), .claude/rules/pipekit-*.md, .claude/workflows/, pipekit/ (SOPs, templates, the methodology docs), bin/pk, engineering/RUNBOOK.md, and a method.config.md from the template.

2. Put pk on your PATH.

./bin/pk install                    # symlinks pk into /usr/local/bin or ~/.local/bin

3. Give pk your Linear key. Export it, or put it in .env.local (gitignored):

export LINEAR_API_KEY=lin_api_…     # the variable name is configurable in method.config.md

4. Create the workflow states Pipekit moves issues through. In Linear → Settings → your team → Workflow, add these states (names matter; the full list with meanings is in sop/Linear_SOP.md § Workflow States):

• Required: Needs Spec, Specced, Approved, In Progress, UAT, Done, and one In <Env> per non-production environment (e.g. In Dev for a dev → main project).
• Recommended: Triage (enable it in team settings), Ideas, Future Initiatives, On Deck, Building.

A stock Linear team has none of the required states; pk doctor lists the ones still missing.

5. Fill in method.config.md, then check the setup.

pk init                             # detects your stack and walks you through the config
pk doctor                           # deps, key, team, workflow states, the binary in use

pk doctor is green when the Linear team resolves, the states exist, and the pk you are running is this project's bin/pk.

6. Bootstrap the project. Inside Claude Code:

/startup

It captures the idea, writes the definition and strategy docs, chooses a stack, authors the roadmap into Linear as i1., i2. initiatives, and queues the first batch of issues. Each step checks whether it is already done, so you can stop and resume. Adopting Pipekit on an existing codebase: /startup --mode=brownfield skips the concept and definition steps. Already have docs? /concept --docs docs/ proposal/ reads them and asks only about the gaps.

From here the daily loop below takes over. pk next tells you what to do at any moment.

Key terms

The pipeline

Stage 0: Foundation (run once)

A contract — the artifacts the dev pipeline requires — not a rigid script. Three entry modes satisfy it:

The daily loop (run per issue)

In a worktree? pk done runs from the parent repo and deletes the worktree. Run /pk-exit inside the worktree session first, then leave it and run pk done from the parent.

Seeing where you stand

Fast lanes

What is portable, and what assumes a stack

The daily loop (pk next → pk done, /work, /verify, the spec skills) needs only Claude Code, Linear and GitHub. Some of the rest was built on a Next.js + Supabase + Vercel stack and still shows it:

What syncs vs. what stays

Synced from Pipekit every time you run sync-method.sh: .claude/skills/ (portable skills), .claude/rules/pipekit-*.md, .claude/workflows/, .claude/agents/, pipekit/ (SOPs, templates, method.md, GUIDE.md, STARTUP.md), bin/pk + bin/pk-init/, and the How we run block of engineering/RUNBOOK.md.

Yours, never overwritten: method.config.md, CLAUDE.md, .claude/rules/ (your own files), .claude/skills/{project-specific}/, .claude/overrides/ (sync-safe customization of synced files — method.md § Sync-Safe Overrides), concept-brief.md, project-definition.md, Strategy/, the rest of engineering/RUNBOOK.md, and engineering/WEEKLY_PLAN.md once it exists.

Update with /pipekit-update from inside Claude Code, or ./scripts/sync-method.sh from a terminal; restart Claude Code afterward to load the new skills. Pin a release with ./scripts/sync-method.sh vX.Y.Z (any tag in CHANGELOG.md).

Which doc to read

Versioning

Semver-ish: minor bumps for new capability, patch for fixes and docs. A tag is created automatically when a PR titled with a vX.Y.Z token merges to main.

Origin and license

Extracted from a production finance platform, where the daily loop ran for the better part of a year before it was split out. MIT — see LICENSE.