warp-os 1.1.0

package/README.md

@@ -0,0 +1,308 @@
+# 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
+
+```bash
+npx warp-os install
+```
+
+One command. Works on Windows, Mac, and Linux. No symlinks, no Developer Mode, no admin required.
+
+Copies 16 skills and 19 agent definitions to `~/.claude/`, installs hook scripts and the engineering foundation to `~/.warp/`, and sets up [claude-mem](https://github.com/thedotmack/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)
+
+```bash
+# 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
+
+```bash
+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](https://github.com/thedotmack/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](https://github.com/obra/superpowers) for subagent based TDD, [gstack](https://garryslist.org) 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 — 4 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 only:
+
+| 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 |
+
+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
+
+16 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-browse` | Headless browser for screenshots and testing |
+
+## The Pipeline
+
+Skills chain together. Each reads what the previous wrote:
+
+```mermaid
+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:
+
+```bash
+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/                      ← 3 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
+
+```bash
+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](https://garryslist.org) · [Superpowers](https://github.com/obra/superpowers) · [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
+
+**Significant** — [Trail of Bits](https://github.com/trailofbits) (security audit methodology)
+
+**Supporting** — [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) · [Context7 MCP](https://github.com/upstash/context7)
+
+## License
+
+[MIT](LICENSE) — WolfOnWings, 2026

package/VERSION

@@ -0,0 +1 @@
+1.1.0