/ Directory / Playground / pilot-shell
← All servers ↗ GitHub
● Community maxritter ⚡ Instant

pilot-shell

by maxritter · maxritter/pilot-shell

Spec-driven Claude Code with quality gates baked in — every change goes plan → spec → implement → verify before it lands.

pilot-shell wraps Claude Code in a spec-driven loop: features start as plans, become specs, get implemented against acceptance criteria, and ship only after gates pass (lint, type, test, doc). It also persists project knowledge — invariants, decisions, gotchas — so quality holds across sessions.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

ready

Install

Author repository · Claude Skills documentation

Use Cases

Real-world ways to use pilot-shell

Ship a feature with spec-first discipline

👤 Devs tired of half-baked AI-written features ⏱ ~90 min intermediate

When to use: Vague feature request from PM; you want it shipped right, not fast.

Flow
  1. Plan
    Use pilot-shell. Plan the feature 'export usage CSV per workspace per month'. List unknowns + risks.✓ Copied
    → Plan with explicit unknowns; you fill gaps before next step
  2. Spec
    From the plan, write a spec with acceptance criteria + non-goals + edge cases.✓ Copied
    → Spec saved to /specs/<feature>.md
  3. Implement
    Implement against the spec. Tests first, then code. Stop at any unmet criterion.✓ Copied
    → Tests + impl; failing tests visible until impl passes
  4. Verify gates
    Run all gates: lint, type, tests, docs. Block PR if any red.✓ Copied
    → Gate report; only green = merge candidate

Outcome: Features that ship spec-complete, with tests and docs.

Pitfalls
  • Spec dragged out into a planning marathon — Time-box spec phase to 30 min; ship the smallest spec that locks acceptance
Combine with: filesystem

Stop opening PRs that fail CI on the first run

👤 Devs whose PRs frequently bounce on lint/type errors ⏱ ~30 min intermediate

When to use: You opened 3 PRs this week; all failed CI on basics.

Flow
  1. Wire gates
    Use pilot-shell. Configure quality gates to mirror our CI: eslint, tsc, vitest, prettier.✓ Copied
    → .pilot.config.json with gates listed
  2. Block on red
    Set policy: don't open PR until all gates green locally.✓ Copied
    → Policy applied
  3. Measure
    After 2 weeks, compare CI first-run pass rate before/after.✓ Copied
    → Pass rate up

Outcome: PRs that pass CI first try; less churn for reviewers.

Pitfalls
  • Local gates differ from CI subtly (Node version) — Pin local Node version with .nvmrc; mirror CI's exact commands
Combine with: github

Preserve project-knowledge as the team grows

👤 Project owners onboarding new collaborators ⏱ ~30 min beginner

When to use: You're handing off / sharing the project; want decisions and invariants captured.

Flow
  1. Seed the knowledge file
    Use pilot-shell. Initialize project knowledge with: architecture, key invariants, decisions log.✓ Copied
    → /.pilot/knowledge.md created with sections
  2. Capture as you go
    Whenever a decision is made (chose Postgres over MySQL), record with date + reason.✓ Copied
    → Decisions accumulate; new collaborators can read history
  3. Use in onboarding
    When a new collaborator starts, point Claude Code to this file as primary context.✓ Copied
    → Faster ramp; less 'why is it this way'

Outcome: Knowledge survives team changes.

Pitfalls
  • Knowledge file becomes a journal of trivia — Keep it terse: invariants, decisions, gotchas. Not a daily log

Combinations

Pair with other MCPs for X10 leverage

pilot-shell-skill + github

PR template auto-filled from spec; CI validates gates

When opening a PR, populate the body from the spec markdown; CI checks gates match.✓ Copied
pilot-shell-skill + filesystem

Specs and knowledge committed to repo

Persist /specs/ and /.pilot/knowledge.md in repo for review history.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
plan feature_description Step 1 of any new feature 0
spec plan_id After plan unknowns resolved 0
implement spec_id After spec approved 0
run_gates scope? Pre-PR; CI mirror 0
knowledge_update decision_or_invariant Capture project-level decision 0

Cost & Limits

What this costs to run

API quota
None — local
Tokens per call
Spec docs ~500–2000 tokens; knowledge file caps ~3000 to stay manageable
Monetary
Free
Tip
Cap knowledge.md at ~3000 tokens; consolidate older entries periodically

Security

Permissions, secrets, blast radius

Minimum scopes: filesystem-write
Credential storage: None
Data egress: None

Troubleshooting

Common errors and fixes

Gates pass locally but fail in CI

Pin Node version, OS-specific deps; mirror CI command exactly

Verify: Diff local vs CI command output
Implement step skips test-first

Set policy strict_tdd=true in .pilot.config; tool will refuse to write impl before tests

Spec phase drags

Use --time-box 30m; force decisions on unknowns instead of perfect specs

Knowledge file too long

Run knowledge_consolidate; archives old entries to /.pilot/archive/

Alternatives

pilot-shell vs others

AlternativeWhen to use it insteadTradeoff
spec-workflow-mcpYou want this as an MCP server with cross-tool reach (not a Claude Code skill)More setup; more flexible deploy
Plain CLAUDE.md + manual TDDSolo project, you don't need automationDiscipline-dependent; fewer guardrails

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills

Continue exploring

Related tools and workflows

Choose another guide for your workflow, or explore a collection.

Shared context · plans

Builder.io Agent Skills

Builder.io’s composable agent skills support visual plans, local app editing, review workflows, and agent-native tools.

Skill

Browse all topic collections → · See 29 new official additions →