WarpOS — A development operating system for Claude Code

The goal of this project is to reduce the friction between you and a completed idea, while still allowing you to make the decisions that only you can make. Everything in this repo works together to achieve this - to find the line between the problems that can only be solved by you, and the problems that can be delegated to Claude Code. The goal here is reduce the barriers that hinder your progress so you can step back and delegate. Here, you are the architect, not the developer, and the whole design philosophy is - the architect doesn't lay bricks.

What Is Warp?

Warp is a development operating system with hardwired anti-slop guardrails that transforms Claude Code from a coding assistant into a verified engineering pipeline. Other AI coding tools say "smarter prompts" or "better models." Warp says "we don't trust the AI either — that's why the guardrails can't hallucinate." You architect. Warp engineers. Trustless verification.

Quick Start

Requirements

• Claude Code — the CLI, VS Code extension, JetBrains extension, desktop app, or claude.ai/code
• Git — for cloning and for skills that read git history

Install

npx warp-os install

One command. Works on Windows, Mac, and Linux. No symlinks, no Developer Mode, no admin required.

Copies 17 skills and 20 agent definitions to ~/.claude/, installs hook scripts and the engineering foundation to ~/.warp/, and sets up claude-mem for persistent cross-session memory. Hooks are activated per-project by /warp-setup — not globally.

Requires Node.js 18+. Run the same command anytime to upgrade.

Setup (per project)

# Open your project in Claude Code, then:
/warp-setup

Setup detects your stack, installs missing verification tools, configures hooks, sets up MCP servers, activates the orchestrator, and for existing projects automatically analyzes your codebase.

After setup, close and restart Claude Code. The orchestrator activates on the next session — it won't take effect until you restart.

Upgrade

npx warp-os install

Same command as install — detects existing installation and overwrites with the latest version. Or from inside Claude Code: /warp-upgrade. Version tracked at ~/.warp/version.

How It Works

One command (/warp-setup) configures everything — tool detection, hooks, project analysis, and the orchestrator. After a restart, the Warp orchestrator becomes your default session agent. You talk to it. It runs skills directly in your context — you collaborate in real-time on every decision. For QA, it runs dual-mode: a collaborative pass with you plus an independent adversarial pass that catches what you both missed. You make the decisions. Warp does everything else.

The guardrails are structural, not optional. Every TDD cycle hits an L1 deterministic gate (linters, type-check, credential scanning) that blocks on failure. The AI fixes the issue or it doesn't proceed. No exceptions, no reasoning around it. Figma MCP provides design specs, Chrome extension gives live visual collaboration, and Context7 prevents hallucinated APIs with live library docs.

Every skill also works standalone. You don't need the pipeline to get value. Drop /warp-plan-architect into any conversation to think through a system design. Run /warp-qa-debug when something breaks. Use /warp-plan-security before any deploy. The pipeline is there when you want it — the skills are useful the moment you install them.

How Do I Actually Use This?

After setup, the orchestrator handles routing. You don't need to memorize skill names — just tell it what you want to do.

"I have an idea." Run /warp-setup in an empty project folder. Restart. The orchestrator routes you to brainstorm, then scope, architect, design, test specs, security audit. By the time planning is done, every build cycle is mapped out. Say "let's build" and the orchestrator runs build-code directly — you collaborate on every TDD cycle.

"I have an existing project and want Warp to help." Run /warp-setup in your project folder. Setup detects your stack, configures verification hooks, and automatically analyzes your entire codebase. Restart your terminal. The orchestrator knows your project and is ready to plan, build, or debug.

"Something is broken and I've been staring at it for an hour." Tell the orchestrator "debug this" — or run /warp-qa-debug directly. It systematically isolates the root cause using binary search, hypothesis testing, and scope locks. For complex bugs with multiple theories, it uses /fork to test hypotheses in parallel.

"I just want to ship this PR." Tell the orchestrator "ship it" — or run /warp-release-update directly. Diff review, version bump, PR creation, deploy, canary monitoring, documentation update.

"I stepped away for a week." Just open Claude Code in the project. The orchestrator auto-loads, shows pipeline state, and orients you to where you left off. claude-mem captures everything automatically — every tool use, every decision, every file change — compresses it with AI, and injects relevant context from past sessions on startup.

What Makes Warp Different?

There are other great projects for Claude Code on Github — Superpowers for subagent based TDD, gstack for virtual engineering teams. Warp builds on their work (and credits them). The difference is scope and verification philosophy: Warp isn't a collection of skills thrown together — it's an operating system where skills run directly with the user present, every output is verified by deterministic tools the AI cannot influence, and dual-mode QA catches blind spots through independent adversarial review.

The Guardrails

The core premise: AI-generated code is guilty until proven innocent. Every verification layer in Warp exists because trusting AI output at face value is how slop ships.

Three bias levels. Warp classifies every verification by how much you should trust it. Level 1: deterministic tools — binary pass/fail, highest trust. Level 2: AI anchored to external sources (Context7 live docs, API contracts) — medium trust. Level 3: AI evaluating AI — lowest trust. The rule: every gate that can be Level 1 must be Level 1. Level 3 is never the only layer.

Minimal hooks — 5 hooks, not 15. Guards and QA automation were removed — with direct-first execution, the user is present and sees everything. The remaining hooks handle session bootstrap and quality enforcement:

| Hook | What it does | |---|---| | identity-foundation.sh | First-run welcome, injects foundation into orchestrator context | | identity-briefing.sh | Welcome banner with branch, pipeline state, next cycle | | consistency-check.sh | CLAUDE.md staleness + TODOS.md validation on Stop | | PowerShell blocker (inline) | Rejects PowerShell tool calls, forces Bash | | validate-askuser.sh | L1 gate: blocks AskUserQuestion if labels lack completeness scores |

Every hook sources a shared JSON parsing library (_warp_json.sh) — no jq dependency. Hooks degrade gracefully: warn visibly, never crash, never fail silently.

Project-fitted leashing. Warp doesn't ship a generic tool list. It detects your stack and builds a custom gate for your project. A Python project gets ruff, mypy, pytest. A TypeScript project gets eslint, tsc, vitest. Tools are added as your codebase grows. The leash is fitted to your project, out of the box.

Test design separation. The skill that writes test specs (testdesign) never sees the implementation. The skill that implements code (build-code) works from those specs. A fresh-context subagent verifies test independence. The exam writer and the answer checker never see each other's work. This prevents the most common AI testing failure: tests that pass because they were written to match the code, not the spec.

Live library docs via MCP + API doc registry. Context7 provides version-specific documentation for 9,000+ libraries during builds. Figma MCP bridges design-to-code with 16 tools (read design specs, write frames, extract tokens, visual diff). Every dependency is registered in warp-tools.json with a doc source. Build-code checks the registry during setup and queries docs inline — no hook needed.

Chrome as collaboration surface. During UI builds, the Chrome extension gives both user and Claude a shared live view of the app. Either party can flag issues. Console access, visual verification, and GIF capture are built into the build cycle. Adversarial QA uses headless /browse instead — different tool, different perspective.

Skills

17 skills organized into five groups. Every skill works standalone or as part of the pipeline.

| Group | Skills | What they do | |-------|--------|-------------| | Plan | brainstorm onboarding scope architect design testdesign security optimize | Figure out what to build — from idea to optimization strategy | | Build | build-code | Write code with TDD + trustless verification gates | | QA | qa-test qa-debug | Test and debug | | Release | release-update | Ship and reflect — diff review, docs, push, deploy, retro | | Root | setup upgrade orchestrate save browse | Pipeline brain, sessions, and utilities |

Plan Skills

Plan skills figure out what to build before a single line of code is written. They work like a product team in a box — brainstorming, scoping, designing architecture, creating a visual system, writing test specs, running a security audit, and optimizing the strategy. Each produces a structured artifact that the next reads. Sequential: architect → design → security → testdesign → optimize.

| Skill | What it does | |-------|-------------| | warp-plan-brainstorm | Problem discovery, user needs, constraints (new projects) | | warp-plan-onboarding | Deep codebase analysis + layer mapping (existing projects) | | warp-plan-scope | Defines scope — what to build, what to cut, 5-star product thinking | | warp-plan-architect | Component boundaries, data flow, API contracts, failure modes | | warp-plan-design | Visual system, UX strategy, screen specs, developer handoff | | warp-plan-testdesign | Test-first specification, acceptance criteria, edge case enumeration | | warp-plan-security | Secrets audit, dependency supply chain, OWASP, STRIDE threat modeling | | warp-plan-optimize | Three modes: optimize (performance + workflow), delight (UX moments), or full (both) |

Build Skills

Build-code runs direct — the user collaborates in real-time on every TDD cycle (red-green-refactor). After every green cycle, the L1 gate runs all deterministic tools. Context7 MCP provides live library docs. Chrome extension provides live visual collaboration for UI work. Figma MCP provides design specs and token extraction. For multi-cycle work, re-invoke /build or use /loop.

| Skill | What it does | |-------|-------------| | warp-build-code | One TDD cycle + L1 gate + Context7 docs + Chrome + Figma |

QA Skills

QA runs dual-mode: a direct collaborative pass + an adversarial dispatch with clean context. Findings are auto-diffed — blind spots (found only by the adversarial pass) are the highest-value output.

| Skill | What it does | |-------|-------------| | warp-qa-test | Three-tier testing with health scoring | | warp-qa-debug | Root cause investigation with parallel hypothesis testing via /fork |

Release Skills

| Skill | What it does | |-------|-------------| | warp-release-update | Ship + reflect. Diff review, docs update, push gate, version bump, deploy, canary, retro. All pushes go through this skill. |

Root Skills

| Skill | What it does | |-------|-------------| | warp-setup | One-command project setup: detection, hooks, MCP, agent activation, auto-onboarding | | warp-upgrade | One-command upgrade from inside Claude Code: pull, build, install, changelog, migration | | warp-orchestrator | Pipeline brain — auto-activates, runs skills direct, orchestrates dual-mode QA, presents gates | | warp-annotate | Reconcile CLAUDE.md files with actual project state using claude-mem observations | | warp-browse | Headless browser for screenshots and testing |

The Pipeline

Skills chain together. Each reads what the previous wrote:

flowchart TD
    subgraph PLAN["**PLAN** — Figure out what to build"]
        direction TB
        BS["brainstorm\n*new projects*"]
        OB["onboarding\n*existing (auto)*"]
        SC["scope"]
        AR["architect"]
        DE["design"]
        BP["testdesign"]
        SE["security"]
        OP["optimize"]

        BS --> SC
        OB --> SC
        SC --> AR
        AR --> DE
        DE --> SE
        SE --> BP
        BP --> OP
    end

    subgraph BUILD["**BUILD + QA** — Direct collaboration + adversarial QA"]
        direction TB
        subgraph CYCLE["Each Cycle (direct)"]
            BC["build-code\n*TDD + Chrome + Figma*"]
            QQ["L1 gate\n*linters, type-check, gitleaks*"]
            BC --> QQ
        end
        subgraph DUALQA["Dual-Mode QA"]
            QD["direct pass\n*collaborative, Chrome*"]
            QA["adversarial pass\n*clean context, /browse*"]
            QC["comparison\n*blind spots + confirmed*"]
            QD --> QC
            QA --> QC
        end

        CYCLE -.-> DUALQA
    end

    subgraph RELEASE["**RELEASE** — Ship and reflect"]
        LA["update\n*ship mode + retro mode*"]
    end

    OP --> BUILD
    PHASE --> LA

    subgraph AUTO["**BUILD (DIRECT)**"]
        direction LR
        CO["/build-code\n*TDD + Chrome + Figma*"]
    end

    subgraph ANYTIME["**ANYTIME**"]
        direction LR
        DI["debug\n*root cause + /fork*"]
        UT["setup · save · browse\nupgrade"]
    end

    style PLAN fill:#1a1a2e,stroke:#4a4a6a,color:#e0e0e0
    style BUILD fill:#16213e,stroke:#4a4a6a,color:#e0e0e0
    style RELEASE fill:#0f3460,stroke:#4a4a6a,color:#e0e0e0
    style AUTO fill:#1a1a2e,stroke:#4a4a6a,color:#e0e0e0
    style ANYTIME fill:#1a1a2e,stroke:#4a4a6a,color:#e0e0e0
    style CYCLE fill:#1b2838,stroke:#3a5a7a,color:#e0e0e0
    style SUBPHASE fill:#1b2838,stroke:#3a5a7a,color:#e0e0e0
    style PHASE fill:#1b2838,stroke:#3a5a7a,color:#e0e0e0
    style QF fill:#2d4a22,stroke:#4a7a3a,color:#e0e0e0

Settings

Warp stores preferences at ~/.warp/settings.json. All features default to ON. Disable any individually:

mkdir -p ~/.warp
echo '{"welcome_banner": false}' > ~/.warp/settings.json

Available settings: welcome_banner, completion_banner, first_run_intro, decision_tally, pipeline_progress, model_warnings, artifact_preview, help_on_request, quicksave, milestone_celebrations, pseudocode_mode

Architecture

WarpOS/
├── shared/                                   ← Shared foundation (edit here)
│   ├── tier1-engineering-constitution.md      ← Tier 1: Engineering foundation (all agents, LOCKED)
│   ├── tier2-verification.md                  ← Tier 2: Adversarial verification (4 adversarial agents only)
│   ├── artifact-schemas.md                    ← Pipeline artifact schemas
│   └── glossary-template.md                   ← Project glossary template
├── src/                            ← Skill sources (edit here)
│   ├── pipeline/                   ← 9 chained skills (plan + build + QA + release)
│   ├── standalone/                 ← 1 skill (security)
│   ├── meta/                       ← Setup, save, orchestrate, upgrade
│   ├── utils/                      ← Browse
│   └── adversarial/                ← 3 adversarial agent source files
├── agents/                         ← Generated (T1 + source; adversarial: T2 + source)
├── bin/                            ← verify.sh + warp-upgrade.sh + hooks/
│   └── hooks/                      ← 4 hook scripts + 2 shared utilities
├── dist/                           ← Generated compiled skills (DO NOT EDIT)
├── warp-*/                         ← Generated (repo root, for global install)
├── build.sh                        ← Dual output: skills (T1 + source) + agents (T1 + source; adversarial: T2 + source)
├── install.sh                      ← Skills + agents + hooks + Tier 1 + global config
├── VERSION                         ← Semantic version
├── CHANGELOG.md                    ← Release history
└── DESIGN.md                       ← Terminal output design system

Two-tier authority model:

• Tier 1 — Engineering foundation. Loads for every skill and agent. Immutable. Core principles, bias classification, quality gates, UX patterns.
• Tier 2 — Adversarial verification. Loads for the 4 adversarial agent definitions only. Bias model, verification hierarchy, severity tags, findings format.

Skill-specific content (role, phases, cognitive patterns, calibration examples) lives in src/ source files, not in tiers.

Edit in shared/ and src/. Everything in dist/, agents/, and root-level warp-*/ is generated by build.sh.

Contributing

git clone https://github.com/WolfOnWings/WarpOS.git
cd WarpOS

# Edit source files in shared/ or src/
# Build, verify, and check structural integrity
./build.sh
./build.sh --verify-only
./bin/verify.sh

A note on tokens: Warp skills are deep — thousands of lines of cognitive patterns, quality gates, and calibration examples. This is the tradeoff: shallow instructions are cheaper, but what you give is what you get.

Built On

Warp synthesizes ideas, patterns, and techniques from these projects:

Major — gstack · Superpowers · everything-claude-code

Significant — Trail of Bits (security audit methodology)

Supporting — Anthropic Cookbook · Context7 MCP

License

MIT — WolfOnWings, 2026