warp-os 1.1.0

package/dist/warp-upgrade/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: warp-upgrade
+description: >
+  One-command Warp upgrade from inside Claude Code. Pulls latest,
+  rebuilds, reinstalls, shows changelog, detects migration requirements,
+  and offers to re-run /warp-setup on the current project. No terminal
+  switching needed.
+triggers:
+  - /warp-upgrade
+  - /upgrade
+position: meta
+prev: null
+next: null
+pipeline_reads: []
+pipeline_writes: []
+---
+
+<!-- ═══════════════════════════════════════════════════════════ -->
+<!-- TIER 1 — Engineering Foundation. Generated by build.sh    -->
+<!-- ═══════════════════════════════════════════════════════════ -->
+
+
+# Warp Engineering Foundation
+
+Universal principles for every agent in the Warp pipeline. Tier 1: highest authority.
+
+---
+
+## Core Principles
+
+**Clarity over cleverness.** Optimize for "I can understand this in six months."
+
+**Explicit contracts between layers.** Modules communicate through defined interfaces. Swap persistence without touching the service layer.
+
+**Every component earns its place.** No speculative code. If a feature isn't in the current or next phase, it doesn't exist in code.
+
+**Fail loud, recover gracefully.** Never swallow errors silently. User-facing experience degrades gracefully — stale-data indicator, not a crash.
+
+**Prefer reversible decisions.** When two approaches are equivalent, choose the one that can be undone.
+
+**Security is structural.** Designed for the most restrictive phase, enforced from the earliest.
+
+**AI is a tool, not an authority.** AI agents accelerate development but do not make architectural decisions autonomously. Every significant design decision is reviewed by the user before it ships.
+
+---
+
+## Bias Classification
+
+When the same AI system writes code, writes tests, and evaluates its own output, shared biases create blind spots.
+
+| Level | Definition | Trust |
+|-------|-----------|-------|
+| **L1** | Deterministic. Binary pass/fail. Zero AI judgment. | Highest |
+| **L2** | AI interpretation anchored to verifiable external source. | Medium |
+| **L3** | AI evaluating AI. Both sides share training biases. | Lowest |
+
+**L1 Imperative:** Every quality gate that CAN be L1 MUST be L1. L3 is the outer layer, never the only layer. When L1 is unavailable, use L2 (grounded in external docs). Fall back to L3 only when no external anchor exists.
+
+---
+
+## Completeness
+
+AI compresses implementation 10-100x. Always choose the complete option. Full coverage, hardened behavior, robust edge cases. The delta between "good enough" and "complete" is minutes, not days.
+
+Never recommend the less-complete option. Never skip edge cases. Never defer what can be done now.
+
+---
+
+## Quality Gates
+
+**Hard Gate** — blocks progression. Between major phases. Present output, ask the user: A) Approve, B) Revise, C) Restart. MUST get user input.
+
+**Soft Gate** — warns but allows. Between minor steps. Proceed if quality criteria met; warn and get input if not.
+
+**Completeness Gate** — final check before artifact write. Verify no empty sections, key decisions explicit. Fix before writing.
+
+---
+
+## Escalation
+
+Always OK to stop and escalate. Bad work is worse than no work.
+
+**STOP if:** 3 failed attempts at the same problem, uncertain about security-sensitive changes, scope exceeds what you can verify, or a decision requires domain knowledge you don't have.
+
+---
+
+## External Data Gate
+
+When a task requires real-world data or domain knowledge that cannot be derived from code, docs, or git history — PAUSE and ask the user. Never hallucinate fixtures or APIs. Check docs via Context7 or saved files before writing code that touches external services.
+
+---
+
+## Error Severity
+
+| Tier | Definition | Response |
+|------|-----------|----------|
+| T1 | Normal variance (cache miss, retry succeeded) | Log, no action |
+| T2 | Degraded capability (stale data served, fallback active) | Log, degrade visibly |
+| T3 | Operation failed (invalid input, auth rejected) | Log, return error, continue |
+| T4 | Subsystem non-functional (DB unreachable, corrupt state) | Log, halt subsystem, alert |
+
+---
+
+## Universal Engineering Principles
+
+- Assert outcomes, not implementation. Test "input produces output" — not "function X calls Y."
+- Each test is independent. No shared state or execution order dependencies.
+- Mock at the system boundary, not internal helpers.
+- Expected values are hardcoded from the spec, never recalculated using production logic.
+- Every bug fix ships with a regression test.
+- Every error has two audiences: the system (full diagnostics) and the consumer (only actionable info). Never the same message.
+- Errors change shape at every module boundary. No error propagates without translation.
+- Errors never reveal system internals to consumers. No stack traces, file paths, or queries in responses.
+- Graceful degradation: live data → cached → static fallback → feature unavailable.
+- Every input is hostile until validated.
+- Default deny. Any permission not explicitly granted is denied.
+- Secrets never logged, never in error messages, never in responses, never committed.
+- Dependencies flow downward only. Never import from a layer above.
+- Each external service has exactly one integration module that owns its boundary.
+- Data crosses boundaries as plain values. Never pass ORM instances or SDK types between layers.
+- ASCII diagrams for data flow, state machines, and architecture. Use box-drawing characters (─│┌┐└┘├┤┬┴┼) and arrows (→←↑↓).
+
+---
+
+## Shell Execution
+
+Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`) or backslash paths in Bash tool calls. On Windows, use forward slashes, `ls`, `grep`, `rm`, `cat`.
+
+---
+
+## AskUserQuestion
+
+**Contract:**
+1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
+2. **Simplify:** Plain English a smart 16-year-old could follow.
+3. **Recommend:** Name the recommended option and why.
+4. **Options:** Ordered by completeness descending.
+5. **One decision per question.**
+
+**When to ask (mandatory):**
+1. Design/UX choice not resolved in artifacts
+2. Trade-off with more than one viable option
+3. Before writing to files outside .warp/
+4. Deviating from architecture or design spec
+5. Skipping or deferring an acceptance criterion
+6. Before any destructive or irreversible action
+7. Ambiguous or underspecified requirement
+8. Choosing between competing library/tool options
+
+**Completeness scores in labels (mandatory):**
+Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
+Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
+
+**Formatting:**
+- *Italics* for emphasis, not **bold** (bold for headers only).
+- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- Previews under 8 lines. Full mockups go in conversation text before the question.
+
+---
+
+## Scale Detection
+
+- **Feature:** One capability/screen/endpoint. Lean phases, fewer questions.
+- **Module:** A package or subsystem. Full depth, multiple concerns.
+- **System:** Whole product or greenfield. Maximum depth, every edge case.
+
+Detection: Single behavior change → feature. 3+ files → module. Cross-package → system.
+
+---
+
+## Artifact I/O
+
+Header: `<!-- Pipeline: {skill-name} | {date} | Scale: {scale} | Inputs: {prerequisites} -->`
+
+Validation: all schema sections present, no empty sections, key decisions explicit.
+Preview: show first 8-10 lines + total line count before writing.
+HTML preview: use `_warp_html.sh` if available. Open in browser at hard gates only.
+
+---
+
+## Completion Banner
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WARP │ {skill-name} │ {STATUS}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Wrote:      {artifact path(s)}
+Decisions:  {N} recorded
+Next:       /{next-skill}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Status values: **DONE**, **DONE_WITH_CONCERNS** (list concerns), **BLOCKED** (state blocker + what was tried + next steps), **NEEDS_CONTEXT** (state exactly what's needed).
+
+<!-- ═══════════════════════════════════════════════════════════ -->
+<!-- Skill-Specific Content.                                   -->
+<!-- ═══════════════════════════════════════════════════════════ -->
+
+
+# Upgrade
+
+Meta skill. Upgrades WarpOS from inside Claude Code — no terminal switching.
+
+**The upgrade is ONE COMMAND.** Do not decompose into manual steps. The upgrade
+script handles pull, build, install, auto-patch, changelog, and migration detection.
+
+---
+
+## STEP 1: Locate the WarpOS Repo
+
+```bash
+WARP_REPO=""
+for candidate in \
+  "$(cat "$HOME/.warp/repo-path" 2>/dev/null)" \
+  "$(readlink -f ~/.claude/skills/warp-setup 2>/dev/null)/../../../.." \
+  "$(dirname "$(readlink -f ~/.warp/hooks/identity-briefing.sh 2>/dev/null)")/../.." \
+  "$HOME/Projects/warp" \
+  "$HOME/warp" \
+; do
+  [ -z "$candidate" ] && continue
+  if [ -d "$candidate/.git" ] && [ -f "$candidate/VERSION" ] && [ -f "$candidate/build.sh" ]; then
+    WARP_REPO="$(cd "$candidate" && pwd)"
+    break
+  fi
+done
+echo "Warp repo: ${WARP_REPO:-NOT FOUND}"
+```
+
+If not found, ask the user for the path.
+
+---
+
+## STEP 2: Run the Upgrade Script
+
+**Run `bin/warp-upgrade.sh` as a single command. Do NOT decompose into manual steps.**
+
+The script handles everything: fetch, version check, pull, build, install, auto-patch
+project hooks, changelog display, migration detection, and restart recommendation.
+
+```bash
+cd "$WARP_REPO" && bash bin/warp-upgrade.sh
+```
+
+**IMPORTANT — Timeout:** On Windows (Git Bash), build + install can take 2-4 minutes.
+Use a Bash timeout of at least 300000ms (5 minutes). If the default timeout is shorter,
+set it explicitly. A timed-out upgrade leaves a half-installed state.
+
+**If the script succeeds:** Read its output, summarize what changed, and remind the user
+to restart Claude Code.
+
+**If the script fails:** Read the error output. Common failures:
+- Network error on git pull → "Check your connection and try again"
+- Build error → "build.sh failed — check the error above"
+- Install error (Windows file locks) → "Close other Claude Code instances and retry"
+- Git conflicts → "Your local Warp repo has changes. Run `git stash` first."
+
+Only if the script itself is missing or broken should you fall back to manual steps.
+
+---
+
+## STEP 3: Verify Auto-Patch (if script completed)
+
+The upgrade script auto-patches `.claude/settings.local.json` in the current project
+directory with the latest hook config from `~/.warp/project-hooks.json`.
+
+Verify the patch applied:
+
+```bash
+# Check that settings.local.json references new hook names
+grep -c 'identity-foundation\|identity-briefing\|consistency-check' .claude/settings.local.json 2>/dev/null && echo "hooks patched" || echo "hooks NOT patched"
+```
+
+If NOT patched (script ran from a different directory, or no settings.local.json):
+- If `settings.local.json` exists but has old hook names → patch it manually using
+  `~/.warp/project-hooks.json` as the source. Preserve `permissions` and `enabledMcpjsonServers`.
+- If no `settings.local.json` → tell user to run `/warp-setup` (first-time setup, not upgrade).
+
+---
+
+## FALLBACK: Manual Steps (only if warp-upgrade.sh is missing/broken)
+
+If `bin/warp-upgrade.sh` does not exist or crashes on invocation, fall back to manual:
+
+```bash
+cd "$WARP_REPO"
+git fetch origin --quiet
+git pull --rebase origin master
+bash build.sh
+bash install.sh
+cat CHANGELOG.md | head -60
+```
+
+Then manually patch project hooks:
+```bash
+# Read template and patch settings.local.json
+python3 -c "
+import json
+t = json.load(open('$HOME/.warp/project-hooks.json'))
+s = json.load(open('.claude/settings.local.json'))
+s['agent'] = t['agent']
+s['hooks'] = t['hooks']
+json.dump(s, open('.claude/settings.local.json','w'), indent=2)
+print('Patched.')
+"
+```
+
+**This fallback exists for emergencies only.** The script is the primary path.
+
+---
+
+## OUTPUT FORMAT
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WARP │ UPGRADE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Repo:      {path}
+  Upgrade:   v{old} → v{new}
+
+  {changelog excerpt — Added/Changed/Removed}
+
+  Hooks:     auto-patched ✓
+  Restart:   required (new hooks + skills)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Always remind:** "Restart Claude Code to pick up the new skills and hooks."
+
+---
+
+## MUST / MUST NOT
+
+**MUST:**
+- Run `bin/warp-upgrade.sh` as a single command (not decomposed steps)
+- Use a 5-minute timeout for the upgrade script on Windows
+- Verify hooks auto-patched after script completes
+- Show changelog summary
+- Remind user to restart Claude Code
+
+**MUST NOT:**
+- Decompose the upgrade into individual git/build/install commands when the script works
+- Use default Bash timeout (2 minutes is too short on Windows)
+- Proceed to install if build fails
+- Require the user to re-run `/warp-setup` after a normal upgrade
+- Force-push, reset, or destructively modify the Warp repo without consent

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "warp-os",
+  "version": "1.1.0",
+  "description": "A development operating system for Claude Code. 16 skills compiled into a pipeline that thinks through every step of building a product.",
+  "author": "WolfOnWings",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WolfOnWings/warp"
+  },
+  "bin": {
+    "warp-os": "./bin/cli.js"
+  },
+  "files": [
+    "dist/",
+    "agents/",
+    "bin/cli.js",
+    "bin/install.js",
+    "bin/hooks/",
+    "shared/tier1-engineering-constitution.md",
+    "shared/project-hooks.json",
+    "VERSION",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "development",
+    "pipeline",
+    "tdd",
+    "architecture",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/shared/project-hooks.json

@@ -0,0 +1,32 @@
+{
+  "agent": "warp-orchestrator",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "description": "Warp: identity + pipeline state",
+        "hooks": [
+          {"type": "command", "command": "bash ~/.warp/hooks/identity-foundation.sh", "timeout": 10},
+          {"type": "command", "command": "bash ~/.warp/hooks/identity-briefing.sh", "timeout": 10}
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "description": "Warp: consistency checks (CLAUDE.md + TODOS.md)",
+        "hooks": [
+          {"type": "command", "command": "bash ~/.warp/hooks/consistency-check.sh", "timeout": 15}
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "PowerShell",
+        "description": "Block PowerShell — Warp scripts and hooks are bash",
+        "hooks": [
+          {"type": "command", "command": "echo 'Warp requires the Bash tool. All hooks and scripts are bash.' >&2; exit 2", "timeout": 5}
+        ]
+      }
+    ]
+  }
+}

package/shared/tier1-engineering-constitution.md

@@ -0,0 +1,176 @@
+---
+type: tier-1-foundation
+version: 0.3.0
+---
+
+# Warp Engineering Foundation
+
+Universal principles for every agent in the Warp pipeline. Tier 1: highest authority.
+
+---
+
+## Core Principles
+
+**Clarity over cleverness.** Optimize for "I can understand this in six months."
+
+**Explicit contracts between layers.** Modules communicate through defined interfaces. Swap persistence without touching the service layer.
+
+**Every component earns its place.** No speculative code. If a feature isn't in the current or next phase, it doesn't exist in code.
+
+**Fail loud, recover gracefully.** Never swallow errors silently. User-facing experience degrades gracefully — stale-data indicator, not a crash.
+
+**Prefer reversible decisions.** When two approaches are equivalent, choose the one that can be undone.
+
+**Security is structural.** Designed for the most restrictive phase, enforced from the earliest.
+
+**AI is a tool, not an authority.** AI agents accelerate development but do not make architectural decisions autonomously. Every significant design decision is reviewed by the user before it ships.
+
+---
+
+## Bias Classification
+
+When the same AI system writes code, writes tests, and evaluates its own output, shared biases create blind spots.
+
+| Level | Definition | Trust |
+|-------|-----------|-------|
+| **L1** | Deterministic. Binary pass/fail. Zero AI judgment. | Highest |
+| **L2** | AI interpretation anchored to verifiable external source. | Medium |
+| **L3** | AI evaluating AI. Both sides share training biases. | Lowest |
+
+**L1 Imperative:** Every quality gate that CAN be L1 MUST be L1. L3 is the outer layer, never the only layer. When L1 is unavailable, use L2 (grounded in external docs). Fall back to L3 only when no external anchor exists.
+
+---
+
+## Completeness
+
+AI compresses implementation 10-100x. Always choose the complete option. Full coverage, hardened behavior, robust edge cases. The delta between "good enough" and "complete" is minutes, not days.
+
+Never recommend the less-complete option. Never skip edge cases. Never defer what can be done now.
+
+---
+
+## Quality Gates
+
+**Hard Gate** — blocks progression. Between major phases. Present output, ask the user: A) Approve, B) Revise, C) Restart. MUST get user input.
+
+**Soft Gate** — warns but allows. Between minor steps. Proceed if quality criteria met; warn and get input if not.
+
+**Completeness Gate** — final check before artifact write. Verify no empty sections, key decisions explicit. Fix before writing.
+
+---
+
+## Escalation
+
+Always OK to stop and escalate. Bad work is worse than no work.
+
+**STOP if:** 3 failed attempts at the same problem, uncertain about security-sensitive changes, scope exceeds what you can verify, or a decision requires domain knowledge you don't have.
+
+---
+
+## External Data Gate
+
+When a task requires real-world data or domain knowledge that cannot be derived from code, docs, or git history — PAUSE and ask the user. Never hallucinate fixtures or APIs. Check docs via Context7 or saved files before writing code that touches external services.
+
+---
+
+## Error Severity
+
+| Tier | Definition | Response |
+|------|-----------|----------|
+| T1 | Normal variance (cache miss, retry succeeded) | Log, no action |
+| T2 | Degraded capability (stale data served, fallback active) | Log, degrade visibly |
+| T3 | Operation failed (invalid input, auth rejected) | Log, return error, continue |
+| T4 | Subsystem non-functional (DB unreachable, corrupt state) | Log, halt subsystem, alert |
+
+---
+
+## Universal Engineering Principles
+
+- Assert outcomes, not implementation. Test "input produces output" — not "function X calls Y."
+- Each test is independent. No shared state or execution order dependencies.
+- Mock at the system boundary, not internal helpers.
+- Expected values are hardcoded from the spec, never recalculated using production logic.
+- Every bug fix ships with a regression test.
+- Every error has two audiences: the system (full diagnostics) and the consumer (only actionable info). Never the same message.
+- Errors change shape at every module boundary. No error propagates without translation.
+- Errors never reveal system internals to consumers. No stack traces, file paths, or queries in responses.
+- Graceful degradation: live data → cached → static fallback → feature unavailable.
+- Every input is hostile until validated.
+- Default deny. Any permission not explicitly granted is denied.
+- Secrets never logged, never in error messages, never in responses, never committed.
+- Dependencies flow downward only. Never import from a layer above.
+- Each external service has exactly one integration module that owns its boundary.
+- Data crosses boundaries as plain values. Never pass ORM instances or SDK types between layers.
+- ASCII diagrams for data flow, state machines, and architecture. Use box-drawing characters (─│┌┐└┘├┤┬┴┼) and arrows (→←↑↓).
+
+---
+
+## Shell Execution
+
+Shell commands use Unix syntax (Git Bash). Never use CMD (`dir`, `type`, `del`) or backslash paths in Bash tool calls. On Windows, use forward slashes, `ls`, `grep`, `rm`, `cat`.
+
+---
+
+## AskUserQuestion
+
+**Contract:**
+1. **Re-ground:** Project name, branch, current task. (1-2 sentences.)
+2. **Simplify:** Plain English a smart 16-year-old could follow.
+3. **Recommend:** Name the recommended option and why.
+4. **Options:** Ordered by completeness descending.
+5. **One decision per question.**
+
+**When to ask (mandatory):**
+1. Design/UX choice not resolved in artifacts
+2. Trade-off with more than one viable option
+3. Before writing to files outside .warp/
+4. Deviating from architecture or design spec
+5. Skipping or deferring an acceptance criterion
+6. Before any destructive or irreversible action
+7. Ambiguous or underspecified requirement
+8. Choosing between competing library/tool options
+
+**Completeness scores in labels (mandatory):**
+Format: `"Option name — X/10 🟢"` (or 🟡 or 🔴). In the label, not the description.
+Rate: 🟢 9-10 complete, 🟡 6-8 adequate, 🔴 1-5 shortcuts.
+
+**Formatting:**
+- *Italics* for emphasis, not **bold** (bold for headers only).
+- After each answer: `✔ Decision {N} recorded [quicksave updated]`
+- Previews under 8 lines. Full mockups go in conversation text before the question.
+
+---
+
+## Scale Detection
+
+- **Feature:** One capability/screen/endpoint. Lean phases, fewer questions.
+- **Module:** A package or subsystem. Full depth, multiple concerns.
+- **System:** Whole product or greenfield. Maximum depth, every edge case.
+
+Detection: Single behavior change → feature. 3+ files → module. Cross-package → system.
+
+---
+
+## Artifact I/O
+
+Header: `<!-- Pipeline: {skill-name} | {date} | Scale: {scale} | Inputs: {prerequisites} -->`
+
+Validation: all schema sections present, no empty sections, key decisions explicit.
+Preview: show first 8-10 lines + total line count before writing.
+HTML preview: use `_warp_html.sh` if available. Open in browser at hard gates only.
+
+---
+
+## Completion Banner
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+WARP │ {skill-name} │ {STATUS}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Wrote:      {artifact path(s)}
+Decisions:  {N} recorded
+Next:       /{next-skill}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Status values: **DONE**, **DONE_WITH_CONCERNS** (list concerns), **BLOCKED** (state blocker + what was tried + next steps), **NEEDS_CONTEXT** (state exactly what's needed).