pilot-shell

Analyzes user intent via the /spec command, automatically classifies tasks as features or bugfixes, and generates structured implementation plans using a state machine dispatcher that routes to feature or bugfix workflows. The planning phase uses Claude to decompose requirements into atomic steps with estimated complexity, then presents a human-reviewable plan before implementation begins. This enforces upfront design thinking and prevents Claude Code from diverging into ad-hoc implementations.

During the implementation phase of /spec workflows, generates test cases before code is written, then validates that all generated code passes those tests before marking tasks complete. The system uses a verification agent that runs test suites and blocks code merges if coverage or assertions are insufficient. This is enforced via hooks that intercept code changes and validate test presence before allowing commits.

Pilot Shell injects project-specific context into Claude's system prompt at session start, including extracted conventions, relevant code patterns, and project rules from the semantic index. The context injection is selective and respects Claude's token budget — only the most relevant patterns are injected based on the current task, preventing context window overflow. The system uses a context monitor to track which files are most relevant to the current task and prioritizes injection of related patterns.

The verification phase includes an automated code review agent that checks for style violations, architectural inconsistencies, and deviations from project conventions. The agent uses the extracted project rules and conventions to validate that generated code follows established patterns. Code that violates style or architectural rules is flagged and can block merges, providing automated enforcement of code quality standards without requiring manual review.

Pilot Shell persists session state (current task, implementation progress, test results, verification status) to disk, enabling recovery if a session crashes or is interrupted. The worker service maintains a session state file that tracks the current /spec task, implementation phase, and verification results. If a session is interrupted, the next session can resume from the last checkpoint, preventing loss of work and enabling recovery from failures.

The /sync command builds a semantic search index of the entire codebase using embeddings, then stores project-specific context (architecture patterns, naming conventions, dependencies, test patterns) in a persistent memory store that survives across sessions. This context is automatically injected into Claude's context window at the start of each session, enabling Claude to understand project conventions without requiring manual context setup. The context monitor continuously tracks changes to key files and updates the index incrementally.

The /learn command captures non-obvious discoveries from the current session (e.g., 'this project uses a custom logger instead of console.log', 'all async functions must have timeout handling') and converts them into reusable skill files stored in ~/.pilot/skills/. These skills are automatically loaded into Claude's context for future sessions on the same project, and can be shared across teams via the /vault command. The system uses Claude to extract generalizable patterns from session interactions and format them as structured rules.

The /vault command shares rules, commands, skills, hooks, and agents across a team by syncing them to a private Git repository. Each team member's local ~/.pilot/ and ~/.claude/ directories can be configured to pull from a shared vault repository, enabling centralized management of project conventions, custom hooks, and reusable agents. The system uses Git as the backing store and provides conflict resolution via simple merge strategies (last-write-wins or manual resolution).

A pre-commit and post-change hooks pipeline that intercepts code modifications and enforces quality standards before code can be committed or merged. The pipeline includes a file checker hook (validates syntax, linting, formatting), a context monitor hook (tracks changes to key files), and a tool redirect hook (intercepts Claude's tool calls and validates them against project rules). Hooks are defined in project-specific or team-wide configuration and are automatically applied to all code changes, making quality enforcement non-optional.

Each /spec task executes in an isolated Git worktree (a separate working directory linked to the same repository), preventing concurrent tasks from interfering with each other and enabling safe rollback if a task fails. The worktree is created at task start, code changes are made in isolation, and the worktree is merged back to the main branch only after verification passes. This architectural pattern enables safe parallel task execution and provides a natural rollback mechanism if verification fails.

After implementation completes, a verification agent runs the full test suite, checks for regressions, and validates that the implementation meets the original specification. For bugfixes, the agent specifically checks that the bug is fixed and no new bugs are introduced. For features, the agent validates that all acceptance criteria are met. The agent can block code merges if verification fails, providing a quality gate before code reaches the main branch.

Pilot Shell exposes a Model Context Protocol (MCP) server that provides Claude Code with access to Pilot Shell commands (/spec, /sync, /learn, /vault) and project-specific tools via a standardized function-calling interface. The MCP server runs as a background service and handles tool schema registration, argument validation, and execution. This enables Claude Code to invoke Pilot Shell workflows programmatically rather than requiring manual slash command invocation.

For tasks classified as low-complexity, Pilot Shell automatically activates Quick Mode, which bypasses the planning phase and approval gate, allowing direct implementation with quality hooks and TDD enforcement still active. Quick Mode is triggered automatically based on task complexity heuristics (e.g., single-file changes, simple bug fixes) and can be manually invoked with /spec --quick. This provides a fast path for simple tasks while maintaining quality standards.