Contractor: Turn Claude Into a Disciplined Engineering Team

Here's what happens when I ask Claude to "add user authentication to this app": it immediately starts writing code. No research into how the existing app handles sessions, no design doc, no consideration of edge cases, no security review. Just straight to implementation. Ten minutes later I have 500 lines of code that work in the happy path but break the moment two users log in simultaneously, don't handle OAuth edge cases, and introduce three subtle security vulnerabilities. I catch some in review, miss others, and spend the next week debugging issues that a proper design phase would have prevented.

Contractor is an npm package that installs a structured workflow into any repo that forces Claude to work like a senior engineering contractor instead of an eager junior dev. You run npx contractor-kit, configure it once, and Claude starts following a disciplined process: Research → Plan → Execute → Review. It delegates work to specialized agents (architect, builder swarm, independent reviewers), never commits directly to your default branch, and gates every change behind adversarial review. It's not a tool — it's a methodology packaged as installable configuration that teaches Claude to think before it codes.

I haven't installed it yet, but the problem it solves is too familiar: AI assistants that rush to implementation, skip planning, and create more cleanup work than they save. If Contractor enforces the discipline I should be imposing manually but keep forgetting, it's worth testing.

What Contractor Actually Is

Contractor is an npm package (also available directly from GitHub) that installs a structured workflow into your repository. When you run npx contractor-kit, it copies two things into your project:

• CLAUDE.md — A comprehensive instruction file that defines how Claude should approach work in this repo (the "contract" with Claude).
• .claude/ directory — Agent definitions, hooks, rules, and settings that implement the workflow.

The structure includes:

• Agents: task-manager, architect, builder (swarm), reviewer, code-reviewer, security-reviewer, pr-test-analyzer, performance-reviewer, silent-failure-hunter. Each has a specific role and constraints.
• Hooks: secret scanning, dangerous-command blocking, file protection, session context preservation.
• Rules: code quality standards, naming conventions, anti-patterns to avoid.
• Settings: permission allow/deny lists, model tier mappings, workflow configuration.

Once installed and configured, you don't tell Claude how to do work — you tell the task-manager what you need, and it orchestrates the rest through a delegation chain. You're working with a structured org, not a single agent.

The Core Workflow: Research → Plan → Execute → Review

The fundamental rule Contractor enforces is: never execute first. Every task goes through four phases:

1. Research

Before writing code, the assigned agent investigates:

• What does the existing codebase do in this area?
• What patterns are already established?
• What dependencies, constraints, or edge cases exist?
• What does the spec or design source say (if applicable)?

The output is a research summary saved to the "vault" (a persistent knowledge store) so future work can reference it without re-discovering the same context.

2. Plan

The architect (design-only agent) creates a design doc:

• What components need to change?
• What's the API contract?
• What edge cases need handling?
• What tests are required?
• What's the rollout/rollback strategy?

The plan is reviewed and approved before any builder touches code. If the plan is wrong, we catch it here — before wasting time implementing a bad design.

3. Execute

The builder swarm (multiple builder agents working in parallel) implements the plan. Each builder works on an independent task in its own branch. No builder invents behavior — they follow the architect's spec. If something is unclear, they ask rather than guessing.

4. Review

Every diff passes through at least two independent reviewers before merge:

• Correctness reviewer: Does it match the spec? Does it handle edge cases?
• Silent-failure hunter: Are there error paths that fail silently?
• Performance reviewer: Are there efficiency issues (N+1 queries, unnecessary re-renders, etc.)?
• Security reviewer: Are there vulnerabilities (SQL injection, XSS, unsafe deserialization, etc.)?

The reviewers are adversarial — their job is to find problems, not rubber-stamp code. Only after passing all reviews does the orchestrator merge to the default branch.

The Delegation Org: Why It's Not Just One Agent

Contractor's key insight is that the same agent shouldn't both write code and approve it. That's a conflict of interest. Instead, it structures work through a delegation chain:

You (product owner)  ↓ Task-Manager (backlog planning, wave releases)  ↓ Architect (design only, no implementation)  ↓ Builder Swarm (parallel execution, 5+ agents)  ↓ Independent Reviewers (adversarial, no code authorship)  ↓ Orchestrator (owns git, merges only after reviews pass)

Each role has constraints:

• The architect designs but never writes implementation code.
• The builder swarm implements but never approves their own work.
• The reviewers critique but didn't write the code they're reviewing.
• The orchestrator owns git operations (branching, merging) but delegates all design and implementation.

This separation of concerns prevents the common AI failure mode: "I wrote this code, it looks good to me, ship it" (without considering edge cases the author didn't think of).

Parallel Task Waves: Keeping the Swarm Busy

Traditional AI coding workflows are serial: ask AI to do task A, wait for it to finish, ask for task B, wait again. That's slow when tasks are independent.

Contractor's task-manager releases work in parallel waves:

1. It analyzes the backlog and identifies all tasks that are independent and unblocked.
2. It releases all of them at once to the builder swarm (not one at a time).
3. As tasks complete and merge, the next wave automatically tops up, keeping the swarm busy.
4. Only true dependencies (task B depends on task A finishing) are serialized.

This means if you have 10 independent components to build, the swarm works on all 10 in parallel (each in its own branch), not sequentially. The bottleneck becomes review bandwidth, not builder availability.

Two Intake Modes: Parity vs. Planning

Contractor supports two ways to define "done":

Parity Mode (Reference-Driven)

You point it at a reference source:

• A legacy app to port
• An API contract to match
• A design file to implement
• A spec document to follow

In parity mode, an auditor agent owns "done" — it continuously compares the implementation to the reference and flags gaps. The task-manager keeps working until the auditor confirms full parity.

Planning Mode (Goal-Driven)

You give it a fresh goal with no reference (e.g., "add user authentication"). The task-manager owns "done" — it breaks the goal into tasks, plans the work, and marks tasks complete as they land. You review and approve the plan before execution starts.

The mode choice matters because it changes the definition of success. Parity mode is objective (does it match the reference?). Planning mode is subjective (does the task-manager's interpretation of "done" match your intent?). Parity mode is safer for well-defined work; planning mode is better for exploratory or greenfield projects.

Branch Safety: Never Commit to Main

Contractor enforces a strict branching model:

• Every change happens in its own feature branch.
• Every branch is gated behind a pull request and independent review.
• No agent (including the orchestrator) ever commits directly to your default branch (main/master).
• The orchestrator only merges after all reviews pass.

This prevents the common AI workflow disaster: Claude makes 20 commits directly to main, introduces a bug in commit 7, and you don't notice until commit 18. Now you're stuck bisecting or reverting a tangled history. With Contractor, every change is isolated, reviewed, and mergeable or revertable independently.

The Vault: Persistent Memory Across Sessions

One of AI's biggest weaknesses is session-based memory: every conversation starts fresh. You explain the architecture, the constraints, the gotchas — then the next session, you explain it all again.

Contractor includes a vault (a structured knowledge store, typically a directory in the repo) where agents persist:

• Research findings (how does auth work in this app?)
• Design decisions (why did we choose library X over Y?)
• Gotchas and edge cases (don't use approach Z, it breaks on Safari)
• Plans and backlogs (what's left to do?)

Every agent reads the vault before starting work. If a previous session already researched a topic, the current session doesn't redo it — it references the vault. Over time, the vault becomes the project's institutional memory, and new sessions are faster because they're not starting from zero.

Guardrail Hooks: Preventing Dangerous Operations

Contractor includes safety hooks that run automatically:

• Secret scanning: Blocks commits containing API keys, passwords, or tokens.
• Dangerous-command blocking: Prevents rm -rf /, DROP DATABASE, or other destructive commands without explicit confirmation.
• File protection: Warns or blocks edits to critical files (e.g., .git/config, production secrets).
• Large-file warnings: Alerts when a commit tries to add a multi-megabyte file that probably shouldn't be in git.

These hooks are defined in .claude/hooks/ and enforced by the orchestrator before any git operation. They're the equivalent of pre-commit hooks, but tailored for AI agents that might not "know better" about what's safe to commit.

Configurable Model Tiers

Contractor maps different agents to different model tiers based on the complexity of their role:

• Orchestrator: High-reasoning model (default: Claude Fable 5) — needs strategic thinking and git operation planning.
• Architect: Strong thinking model (Claude Opus, GPT-4, etc.) — needs deep design reasoning.
• Builder swarm: Fast model (Claude Sonnet, GPT-4o, etc.) — needs speed for parallel execution, less reasoning depth required since they follow a spec.
• Reviewers: Mixed — correctness and security reviewers need strong models; performance and silent-failure hunters can use mid-tier.

This tier mapping is cost-optimized: you pay for expensive models only where reasoning matters, and use cheaper/faster models for mechanical work. The configuration lives in contractor.config and you can override defaults per project.

Installation and Setup

From the root of your repo:

npx contractor-kit              # installs CLAUDE.md + .claude/ into the repo cp contractor.config.example contractor.config # edit contractor.config: set owner, vault path, spec/design sources npx contractor-kit fill         # fills placeholders + creates vault directory git checkout -b chore/adopt-contractor git add -A git commit -m "chore: adopt Contractor workflow"

Then set your orchestrator model in your Claude client:

/model claude-fable-5

From that point on, Claude reads CLAUDE.md and follows the Contractor workflow automatically. You interact with the task-manager to assign work, and it delegates through the org.

Potential Rough Edges (From the Docs)

I haven't tested this yet, but based on the README and thinking through the workflow, here are the likely friction points:

• Overhead for small tasks: Research → Plan → Execute → Review is great for complex features but overkill for trivial changes (fix a typo, update a README). The workflow might feel heavy for tasks that should take 30 seconds.
• Context switching across agents: The delegation org requires Claude to "switch hats" frequently (architect → builder → reviewer). If Claude doesn't maintain role separation cleanly, agents might bleed responsibilities (a builder inventing design decisions, a reviewer writing code).
• Parallel execution limits: The builder swarm works in parallel, but Claude itself is serial (one conversation at a time). To actually run parallel builds, you'd need multiple Claude instances or sessions. The workflow plans for parallelism, but execution might still be serial in practice unless you're running multiple agents concurrently.
• Configuration complexity: The setup requires filling contractor.config, understanding the vault structure, mapping model tiers, and learning the agent roles. That's more upfront investment than "just ask Claude to code."
• Vault maintenance: The vault accumulates knowledge over time, but it needs curation. Outdated research, obsolete design decisions, or conflicting information in the vault could confuse agents. Who maintains the vault? That's a new responsibility.
• Review thoroughness: The adversarial review step depends on the reviewer agents being genuinely critical, not rubber-stamping. If they default to "looks good to me," the safety gate is theater. Testing whether reviews actually catch bugs will be key.

Use Cases I'm Planning to Test

Here's how I'd validate Contractor:

Test 1: Complex Feature (Parity Mode)

Port a legacy authentication flow from an old PHP app to a new Next.js app. Point Contractor at the legacy app as the reference. Measure:

• Does the research phase actually document the legacy behavior accurately?
• Does the architect's design plan match the legacy flow correctly?
• Does the auditor catch gaps between the new implementation and the old reference?
• How many review cycles are needed before the auditor confirms parity?

Test 2: Greenfield Feature (Planning Mode)

Add a new feature with no reference: "implement a caching layer for API responses." Give the task-manager the goal and see:

• Does it break the goal into reasonable tasks?
• Does the architect design a coherent caching strategy?
• Do the builders follow the architect's spec without inventing behavior?
• Do the reviewers catch edge cases (cache invalidation, memory limits, race conditions)?

Test 3: Bug Fix (Minimal Workflow)

Report a simple bug: "the login button is misaligned on mobile." See if Contractor's workflow is flexible enough to handle trivial fixes without requiring full Research → Plan → Execute → Review, or if the overhead is unavoidable.

Test 4: Vault Evolution

Work on the same repo for a week, accumulating vault knowledge. Then start a new session and verify:

• Do agents reference the vault correctly?
• Is the vault reducing redundant research?
• Is vault content staying relevant or accumulating cruft?

If tests 1-2 show high-quality output with fewer bugs than unstructured Claude usage, Contractor is worth the setup overhead. If test 3 shows the workflow is too rigid for small tasks, I'd use Contractor selectively for complex features and bypass it for trivial changes. Test 4 determines whether the vault is a genuine productivity multiplier or just overhead.

How It Compares to Unstructured AI Coding

The traditional "ask Claude to code" workflow:

• I describe the feature in a prompt.
• Claude writes code immediately (no research, no plan).
• I review the code myself, catch some issues, miss others.
• I iterate with Claude, refining the implementation.
• I merge when it "looks good."

That works for simple tasks but breaks down for complex features. The problems:

• No research means Claude doesn't know existing patterns, so it invents new ones (inconsistency).
• No plan means I'm reviewing implementation and design simultaneously (cognitive overload).
• No adversarial review means I'm the only line of defense against bugs and security issues (I'm not perfect).

The Contractor workflow:

• I describe the feature to the task-manager.
• Task-manager → architect researches and plans.
• I review the plan (much easier than reviewing code).
• Builder swarm executes the plan in parallel.
• Independent reviewers gate the diff.
• Orchestrator merges only after reviews pass.

The tradeoff: more structure and overhead, but higher quality output and fewer bugs. For trivial tasks, unstructured is faster. For complex features, Contractor's structure should prevent more problems than it costs in time.

Pairing It With the AI Development Workflow

Contractor fits into a broader AI-assisted development stack:

• Contractor: Structures how Claude approaches feature development (research, plan, build, review).
• Aider: AI pair programming with manual commit control. Contractor could use Aider as the "builder" implementation — the orchestrator delegates to Aider, which executes and commits to feature branches.
• ReviewDog + ESLint: Automated linting and style checks that run in CI. Contractor's reviewers focus on logic and security; ReviewDog catches syntax and style.
• PR-Agent: AI-powered PR review. Contractor's independent reviewers could invoke PR-Agent for additional review layers.

The stack would be: Contractor orchestrates the workflow → Aider (or Claude Code) implements → ReviewDog lints in CI → PR-Agent adds AI review → human does final architecture and product review. Each layer catches different classes of problems.

The Provenance and Trust Question

The README mentions this is "distilled from a real, project-specific agent setup into a project-agnostic template." That's good (battle-tested, not theoretical) but raises a question: whose workflow is this, and does it generalize?

The workflow design makes strong opinionated choices:

• Always research before coding (what if the task is too simple to need research?).
• Always use a delegation org (what if I'm solo and the overhead isn't worth it?).
• Always branch and review (what if I'm prototyping and don't need that safety yet?).

These are good choices for production work on complex projects with multiple contributors. But they might be overkill for solo prototyping, learning projects, or startups moving fast. The README doesn't provide guidance on when to use Contractor vs. when to skip it.

I'd test it on a real project to see if the structure helps or hinders. If it prevents bugs and improves code quality, the overhead is justified. If it just adds ceremony without measurable quality improvement, it's not worth it.

Why This Bookmark Is High-Priority

Last month I asked Claude to refactor a 300-line module into smaller, testable functions. It did, immediately, with no planning. The result: 15 files, inconsistent naming, duplicated logic, and a test suite that didn't compile because Claude invented a new testing pattern instead of using our existing one. I spent two days cleaning it up — longer than if I'd done the refactor myself.

If Contractor had forced Claude to research our testing patterns first, design the module structure before coding, and gate every file behind review, that disaster wouldn't have happened. The refactor would have taken longer upfront (research + plan phase), but the output would have been correct the first time, saving me the two-day cleanup.

That's the value proposition: trade upfront structure for fewer post-merge bugs and cleanups. If it works, it's a huge ROI. If it doesn't — if the overhead is high and the quality improvement is marginal — I'll go back to unstructured Claude usage and just be more careful about reviewing.

I'm bookmarking it at the top of my "test next sprint" list. The methodology is sound (research before coding, separation of design and implementation, adversarial review). The question is whether packaging it as installable configuration actually works, or if Claude ignores the instructions and codes first anyway. The only way to know is to install it, assign a real feature, and measure the outcome.