qualia-framework-v2 2.1.2 → 2.3.0

package/skills/qualia/SKILL.md

@@ -1,50 +1,58 @@
 ---
 name: qualia
-description: "Router — reads STATE.md and tells you the exact next command. Use whenever you type /qualia, 'what next', 'next', or are lost."
+description: "Smart router — reads project state, classifies your situation, tells you the exact next command. Use whenever you type /qualia, 'what next', 'next', 'idk', 'what now', 'what should I do', 'I'm stuck', 'help me decide', 'lost', 'confused', or are unsure about your next step."
 ---
 
 # /qualia — What's Next?
 
-Read project state. Tell the employee the exact next command. No analysis, no advice — just routing.
+Read project state. Classify your situation. Tell you the exact next command.
 
 ## Process
 
-### 1. Read State
+### 1. Get State
 
 ```bash
-echo "---STATE---"
-cat .planning/STATE.md 2>/dev/null || echo "NO_STATE"
-echo "---TRACKING---"
-cat .planning/tracking.json 2>/dev/null || echo "NO_TRACKING"
-echo "---PHASE_PLANS---"
+node ~/.claude/bin/state.js check 2>/dev/null
+```
+
+Also gather context:
+```bash
+test -f .continue-here.md && echo "HANDOFF_EXISTS" && head -20 .continue-here.md || echo "NO_HANDOFF"
+git status --short 2>/dev/null | head -10
+git log --oneline -3 2>/dev/null
 ls .planning/phase-*-plan.md 2>/dev/null || echo "NO_PLANS"
-echo "---VERIFICATIONS---"
 ls .planning/phase-*-verification.md 2>/dev/null || echo "NO_VERIFICATIONS"
 ```
 
-### Task Routing (size-based)
+Read conversation context — what has the user been doing, what errors occurred.
 
-- Single file change, config tweak, typo fix, bug with known cause → `/qualia-quick`
-- One feature, 1-5 files, clear scope, under 2 hours → `/qualia-task`
-- Multi-feature, 5+ files, needs architecture decisions, or part of a roadmap phase → `/qualia-plan`
+### 2. Classify and Route
 
-### 2. Route (state-based)
+Use the state.js JSON output plus gathered context:
 
-| Condition | Command |
-|-----------|---------|
-| No `.planning/` | → `/qualia-new` |
-| Phase N has no plan | → `/qualia-plan {N}` |
-| Phase N has plan, not built | → `/qualia-build {N}` |
-| Phase N built, not verified | → `/qualia-verify {N}` |
-| Phase N verified with FAIL | → `/qualia-plan {N} --gaps` |
-| Phase N verified PASS, more phases | → `/qualia-plan {N+1}` |
-| All phases verified PASS | → `/qualia-polish` |
-| Polish done | → `/qualia-ship` |
-| Shipped | → `/qualia-handoff` |
-| Handed off | → Done. Run `/qualia-report` |
+| Situation | Detection | Route |
+|-----------|-----------|-------|
+| `no-project` | state.js returns NO_PROJECT | → `/qualia-new` |
+| `handoff` | `.continue-here.md` exists | → Read it, summarize, route to next step |
+| `mid-work` | Uncommitted changes + phase in progress | → Continue or `/qualia-pause` |
+| `ready-to-plan` | status == "setup" | → `/qualia-plan {N}` |
+| `ready-to-build` | status == "planned" | → `/qualia-build {N}` |
+| `ready-to-verify` | status == "built" | → `/qualia-verify {N}` |
+| `gaps-found` | status == "verified", verification == "fail", gap_cycles < 2 | → `/qualia-plan {N} --gaps` |
+| `gap-limit` | status == "verified", verification == "fail", gap_cycles >= 2 | → Escalate to Fawzi or re-plan from scratch |
+| `phase-complete` | state.js auto-advanced (status == "setup", phase > 1) | → `/qualia-plan {N}` |
+| `all-verified` | last phase verified pass, status == "verified" | → `/qualia-polish` |
+| `polished` | status == "polished" | → `/qualia-ship` |
+| `shipped` | status == "shipped" | → `/qualia-handoff` |
+| `handed-off` | status == "handed_off" | → `/qualia-report` then done |
+| `blocked` | STATE.md lists blockers or same error 3+ times | → Analyze, suggest `/qualia-debug` |
+| `bug-loop` | Same files edited 3+ times, user frustrated | → Different approach, `/qualia-debug` |
+
+**Employee escalation:** If role is EMPLOYEE and situation is `gap-limit` or `bug-loop`, suggest: "Want to flag this for Fawzi?"
 
 ### 3. Display
 
+**Clear next step:**
 ```
 ◆ QUALIA
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -54,7 +62,22 @@ ls .planning/phase-*-verification.md 2>/dev/null || echo "NO_VERIFICATIONS"
   Progress   {bar} {percent}%
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  → Run: /qualia-{next command}
+  → Run: {next_command from state.js}
+```
+
+**Ambiguous situation (multiple options):**
+```
+## Where You Are
+{1-2 sentences}
+
+## I Recommend
+**{action}** — {why}
+{command}
+
+## Other Options
+1. **{option}** — {what}
+2. **{option}** — {what}
+3. **{option}** — {what}
 ```
 
-That's it. One command. One answer.
+User can respond with a number, "just do it", or natural language.

package/skills/qualia-build/SKILL.md

@@ -85,8 +85,11 @@ If a builder subagent returns a deviation or blocker:
 
 ### 5. Update State
 
-Update STATE.md: status → "built", tasks completed
-Update tracking.json: tasks_done, wave, status
+```bash
+node ~/.claude/bin/state.js transition --to built --phase {N} --tasks-done {done} --tasks-total {total} --wave {wave}
+```
+If state.js returns an error, show it to the employee and stop.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
   → Run: /qualia-verify {N}

package/skills/qualia-debug/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: qualia-debug
+description: "Structured debugging — symptom gathering, diagnosis confirmation, root cause analysis. Trigger on 'debug', 'find bug', 'fix error', 'something is broken', 'not working', 'weird behavior', 'layout broken', 'CSS issue', 'slow page', 'performance'."
+---
+
+# /qualia-debug — Structured Debugging
+
+Systematic debugging. Don't guess — gather symptoms, confirm diagnosis, then fix.
+
+## Usage
+
+- `/qualia-debug` — Interactive (gather symptoms, diagnose, fix)
+- `/qualia-debug --frontend` — CSS/layout/visual issues
+- `/qualia-debug --perf` — Performance issues
+
+## Interactive Mode (Default)
+
+### 1. Gather Symptoms
+
+Ask:
+- What's happening? (exact error or behavior)
+- What should happen instead?
+- When did it start? (after what change?)
+- What have you tried?
+
+### 2. Confirm Diagnosis
+
+Before ANY code changes, present your diagnosis:
+
+> "Based on the symptoms, I think: [diagnosis]. I'll investigate [specific area]. Does that match what you're seeing?"
+
+Wait for confirmation. If user corrects → adjust. Never proceed on a wrong diagnosis.
+
+### 3. Investigate and Fix
+
+1. Reproduce the issue
+2. Isolate the cause (binary search: which file, which function, which line)
+3. Identify root cause (not symptoms)
+4. Implement minimal fix
+5. Verify fix works
+6. Check for related issues
+
+### 4. Commit
+
+```bash
+git add {specific files}
+git commit -m "fix: {what was broken and why}"
+```
+
+## Frontend Mode (`--frontend`)
+
+For layout breaks, z-index issues, overflow, animation glitches.
+
+**Quick diagnostics:**
+- Z-index not working → element needs `position: relative/absolute/fixed`, check parent stacking contexts
+- Horizontal scroll → use `width: 100%` not `100vw`, find overflowing element
+- Flex overflow → add `min-width: 0`
+- Grid blowout → use `minmax(0, 1fr)`
+- Janky animations → only animate `transform` and `opacity`
+- Safari → `-webkit-backdrop-filter`, `100dvh` not `100vh`
+
+## Performance Mode (`--perf`)
+
+### Investigate
+1. Profile the bottleneck (network, render, compute, database)
+2. Measure baseline
+3. Identify the hot path
+
+### Common fixes
+- Slow queries → check indexes, `EXPLAIN ANALYZE`, optimize joins
+- Large bundles → code split, lazy load, tree shake
+- Slow renders → memoize, virtualize long lists
+- API latency → cache, reduce payload, parallelize requests

package/skills/qualia-design/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: qualia-design
+description: "One-shot design transformation — critiques, fixes, polishes, hardens, makes responsive. No reports, no choices, just makes it professional. Trigger on 'fix the design', 'make it look better', 'redesign', 'design pass', 'make it modern', 'it looks ugly', 'fix the UI'."
+---
+
+# /qualia-design — One-Shot Design Transformation
+
+Read the code, understand what's wrong, fix everything, move on. No reports, no choices.
+
+## Usage
+
+- `/qualia-design` — Full transformation on all frontend files
+- `/qualia-design app/page.tsx` — Specific file(s)
+- `/qualia-design --scope=dashboard` — Transform a section
+
+## Process
+
+### 1. Read Brand Context
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+If DESIGN.md exists → use it. If not → use Qualia defaults: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
+
+### 2. Find Target Files
+
+- If specific files given: use those
+- If `--scope`: grep for matching files in `app/` and `components/`
+- If none: find all `page.tsx`, `layout.tsx`, and component files
+
+Read EVERY target file before modifying.
+
+### 3. Critique (internal — don't output)
+
+Evaluate each file on: AI slop detection, visual hierarchy, typography, color, states (loading/error/empty), motion, spacing, responsiveness, microcopy.
+
+### 4. Fix Everything
+
+**Typography:** Replace generic fonts (Inter, Arial) with distinctive ones. Proper type scale, line-height 1.5-1.7 body.
+
+**Color:** Cohesive palette from DESIGN.md or brand. Sharp accent for CTAs. WCAG AA contrast.
+
+**Layout:** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
+
+**Spacing:** Consistent scale (8px grid). Generous whitespace between sections, tight within groups.
+
+**Motion:** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
+
+**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on interactive elements.
+
+**Responsive:** Mobile-first. Touch targets 44x44px min. Stack on mobile, expand on desktop. No horizontal scroll.
+
+**Kill:** Card grids → varied layouts. Generic heroes → distinctive. Blue-purple gradients → brand colors. Static pages → purposeful motion. Fixed widths → fluid.
+
+### 5. Verify
+
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+Fix any TypeScript errors before committing.
+
+### 6. Commit
+
+```bash
+git add {modified files}
+git commit -m "style: design transformation"
+```
+
+```
+◆ Design Transformation Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Files: {N}
+  Changes:
+  - {key change 1}
+  - {key change 2}
+  - {key change 3}
+
+  Fine-tune: /bolder, /design-quieter, /colorize, /animate
+```
+
+## Rules
+
+- Read before write — understand every file before changing it
+- Don't ask — just fix
+- Respect DESIGN.md decisions
+- Don't break functionality — only change styling, never logic
+- TypeScript must pass after changes

package/skills/qualia-handoff/SKILL.md

@@ -56,8 +56,10 @@ git push
 
 ### 3. Update State
 
-Update STATE.md: "handed off"
-Update tracking.json: status → "handed_off"
+```bash
+node ~/.claude/bin/state.js transition --to handed_off
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
 ◆ QUALIA ► DELIVERED ✓

package/skills/qualia-idk/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: qualia-idk
+description: "Alias for /qualia. The smart router handles all 'idk', 'what now', 'I'm stuck' situations."
+---
+
+# /qualia-idk
+
+This is an alias for `/qualia`. Run `/qualia` — it now handles all situation classification and routing.

package/skills/qualia-new/SKILL.md

@@ -223,9 +223,13 @@ Create Supabase project (via MCP or manual).
 **`.planning/PROJECT.md`** — use template, fill from answers:
 - Client, description, requirements (from features), out of scope, stack, design direction, decisions
 
-**`.planning/STATE.md`** — use template from `templates/state.md`
+### Step 8b. Initialize State
 
-**`.planning/tracking.json`** — use template, fill in project/client/assigned_to
+```bash
+node ~/.claude/bin/state.js init --project "{name}" --client "{client}" --type "{type}" --assigned-to "{employee}" --phases '[{phases JSON array from roadmap}]'
+```
+This creates both STATE.md and tracking.json with consistent formatting.
+Do NOT manually edit these files — state.js handles both.
 
 ### Step 9. Create Roadmap
 

package/skills/qualia-pause/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: qualia-pause
+description: "Save session context for seamless handoff. Creates .continue-here.md so the next session picks up exactly where you left off. Trigger on 'pause', 'stop for now', 'save progress', 'continue later', 'pick up tomorrow'."
+---
+
+# /qualia-pause — Session Handoff
+
+Save context so the next session picks up where you left off.
+
+## Process
+
+### 1. Read State
+
+```bash
+cat .planning/STATE.md 2>/dev/null
+git status --short 2>/dev/null
+git log --oneline -5 2>/dev/null
+```
+
+### 2. Create `.continue-here.md`
+
+```markdown
+# Continue Here
+
+## Session Summary
+{What was accomplished — from conversation context + git log}
+
+## Current Phase
+Phase {N}: {name} — {status}
+
+## In Progress
+- {What's partially done}
+- {Where exactly work stopped}
+
+## Next Steps
+1. {Immediate next action}
+2. {Following action}
+
+## Decisions Made
+- {Decision and rationale}
+
+## Blockers
+- {Any unresolved issues}
+
+## Files Modified
+- {List from git status/diff}
+```
+
+### 3. Commit
+
+```bash
+git add .continue-here.md {any uncommitted work files}
+git commit -m "WIP: {phase name} — session handoff"
+```
+
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "Session paused — see .continue-here.md"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-plan/SKILL.md

@@ -76,8 +76,11 @@ If "adjust" — get feedback, re-spawn planner with revision context.
 
 ### 4. Update State
 
-Update STATE.md: status → "planned"
-Update tracking.json: status → "planned"
+```bash
+node ~/.claude/bin/state.js transition --to planned --phase {N}
+```
+If state.js returns an error, show it to the employee and stop.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
   → Run: /qualia-build {N}

package/skills/qualia-polish/SKILL.md

@@ -49,8 +49,10 @@ git add {changed files}
 git commit -m "polish: design and UX pass"
 ```
 
-Update STATE.md: "polish complete"
-Update tracking.json: status → "polished"
+```bash
+node ~/.claude/bin/state.js transition --to polished
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
   → Run: /qualia-ship

package/skills/qualia-quick/SKILL.md

@@ -22,4 +22,7 @@ git commit -m "fix: {description}"
 
 No plan file. No subagents. Just build and ship.
 
-Update STATE.md last activity. Update tracking.json notes.
+```bash
+node ~/.claude/bin/state.js transition --to note --notes "{brief description of what was done}"
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.

package/skills/qualia-report/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: qualia-report
-description: "Generate session report as DOCX and auto-upload to ERP. Mandatory before clock-out."
+description: "Generate session report and commit to repo. Mandatory before clock-out."
 ---
 
 # /qualia-report — Session Report
 
-Generate a concise DOCX report of what was done. Auto-uploads to the ERP.
+Generate a concise report of what was done. Committed to git for the ERP to read.
 
 ## Process
 
 ### 1. Gather Data
 
 ```bash
-echo "---COMMITS---"
 SINCE="8 hours ago"
+echo "---COMMITS---"
 git log --oneline --since="$SINCE" 2>/dev/null | head -20
 echo "---STATS---"
 echo "COUNT:$(git log --oneline --since="$SINCE" 2>/dev/null | wc -l)"
@@ -21,7 +21,7 @@ echo "---PROJECT---"
 echo "DIR:$(basename $(pwd))"
 echo "BRANCH:$(git branch --show-current 2>/dev/null)"
 echo "---STATE---"
-head -20 .planning/STATE.md 2>/dev/null || echo "no-state"
+node ~/.claude/bin/state.js check 2>/dev/null
 ```
 
 ### 2. Synthesize
@@ -31,44 +31,50 @@ Build a concise summary:
 - **Blockers:** Only if something is actually blocked.
 - **Next:** 1-3 clear next actions.
 
-### 3. Generate DOCX
+### 3. Generate Report
 
-```bash
-mkdir -p .planning/reports
+Write to `.planning/reports/report-{YYYY-MM-DD}.md`:
+
+```markdown
+# Session Report — {YYYY-MM-DD}
+
+**Project:** {name}
+**Employee:** {git user.name}
+**Branch:** {branch}
+**Phase:** {N} — {name} ({status})
+**Date:** {YYYY-MM-DD}
 
-cat <<'REPORT_JSON' | python3 ~/.claude/qualia-framework/bin/generate-report-docx.py ".planning/reports/report-$(date +%Y-%m-%d-%H%M).docx"
-{
-    "project": "{project-name}",
-    "user": "{git user.name}",
-    "date": "{YYYY-MM-DD}",
-    "time": "{HH:MM}",
-    "branch": "{branch}",
-    "phase": "{Phase N — name}",
-    "done": ["{accomplishment 1}", "{accomplishment 2}"],
-    "blockers": [],
-    "next": ["{next action 1}"]
-}
-REPORT_JSON
+## What Was Done
+- {accomplishment 1}
+- {accomplishment 2}
+- {accomplishment 3}
+
+## Blockers
+None. / - {blocker}
+
+## Next Steps
+1. {next action}
+2. {next action}
+
+## Commits
+{list from git log}
 ```
 
-### 4. Commit & Upload
+### 4. Commit and Push
 
 ```bash
-REPORT_FILE=$(ls -t .planning/reports/report-*.docx 2>/dev/null | head -1)
-git add "$REPORT_FILE"
-git commit -m "report: session $(date +%Y-%m-%d)"
+mkdir -p .planning/reports
+git add .planning/reports/report-{date}.md
+git commit -m "report: session {YYYY-MM-DD}"
 git push
 ```
 
-Auto-upload to ERP:
+### 5. Update State
+
 ```bash
-curl -s -X POST "https://portal.qualiasolutions.net/api/claude/report-upload" \
-  -H "x-api-key: $CLAUDE_API_KEY" \
-  -F "file=@$REPORT_FILE" \
-  -F "employee_email=$(git config user.email)" \
-  -F "project_name=$(basename $(pwd))"
+node ~/.claude/bin/state.js transition --to activity --notes "Session report generated"
 ```
 
-Employee cannot skip this. Report goes directly to the ERP.
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
-Update STATE.md last activity.
+Employee cannot skip this. Run `/qualia-report` before clock-out.

package/skills/qualia-resume/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: qualia-resume
+description: "Restore context from a previous session. Reads .continue-here.md or STATE.md, summarizes where you left off, routes to next action. Trigger on 'resume', 'continue', 'pick up where I left off', 'what was I doing'."
+---
+
+# /qualia-resume — Resume Work
+
+Restore context and route to the right next action.
+
+## Process
+
+### 1. Find Context (priority order)
+
+1. `.continue-here.md` — richest source, from `/qualia-pause`
+2. `.planning/STATE.md` — project state
+3. Git history — `git log --oneline -10` + `git diff --stat`
+
+### 2. Restore
+
+**If `.continue-here.md` exists:** Read fully. Summarize: what was done, what's in progress, next steps, blockers.
+
+**If only STATE.md:** Read STATE.md + tracking.json. Show current phase and status.
+
+**If neither:** Reconstruct from git. Present findings, ask user to confirm.
+
+### 3. Detect Incomplete Work
+
+- Phase has plan but no verification → execution may be incomplete
+- Uncommitted changes → `git status --short`
+- Phase marked in-progress in STATE.md
+
+### 4. Present and Route
+
+```
+◆ QUALIA ► RESUMING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Last session: {summary}
+  Phase: {N} — {status}
+  {Uncommitted changes if any}
+
+  → {next command}
+```
+
+Clean up `.continue-here.md` after restoration (or offer to keep it).

package/skills/qualia-review/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: qualia-review
+description: "Production audit and code review. General review, --web for web app audit, --ai for AI/voice agent audit. Trigger on 'review', 'audit', 'code review', 'security check', 'production check'."
+---
+
+# /qualia-review — Production Audit
+
+Deep review with severity-scored findings. Different from `/qualia-verify` (which checks phase goals). This checks production readiness.
+
+## Usage
+
+- `/qualia-review` — General code review
+- `/qualia-review --web` — Web app production audit
+- `/qualia-review --ai` — AI/voice agent audit
+
+## General Review (default)
+
+Spawn parallel agents analyzing:
+
+1. **Code Quality** — Clean code, TypeScript strictness, naming, readability
+2. **Security** — OWASP top 10, auth server-side, RLS policies, secrets scan
+3. **Architecture** — Component boundaries, coupling, API contracts
+4. **Performance** — N+1 queries, bundle size, caching, render performance
+5. **Test Coverage** — Gaps, edge cases, test quality
+
+## --web (Web App Audit)
+
+Full production readiness for Next.js + Supabase + Vercel:
+
+**Security:** No secrets in code, HTTPS, CORS restricted, CSP headers, rate limiting, npm audit clean.
+
+**Performance:** Core Web Vitals (LCP < 2.5s, CLS < 0.1), image optimization, bundle analysis, query performance.
+
+**Reliability:** Error boundaries, API error handling, graceful degradation, health check endpoint.
+
+**Observability:** Error tracking (Sentry), structured logging, uptime monitoring, analytics.
+
+## --ai (AI/Voice Agent Audit)
+
+Auto-detect stack (VAPI, ElevenLabs, Retell, OpenAI, Anthropic, pgvector).
+
+**Prompt Safety:** System prompts not exposed, injection defenses, no eval() on AI output, token limits.
+
+**Conversation Flow:** Off-topic handling, context window management, error recovery, human handoff.
+
+**Voice (if detected):** Latency < 500ms, interruption handling, silence timeout, webhook security.
+
+**RAG (if detected):** Embedding consistency, chunk size, retrieval relevance, index refresh.
+
+**Resilience:** Provider failover, timeout handling, cost monitoring, streaming error recovery.
+
+## Output
+
+Every finding:
+- **What** — description
+- **Where** — `file:line`
+- **Fix** — concrete suggestion
+- **Severity** — CRITICAL / HIGH / MEDIUM / LOW
+
+Write to `.planning/REVIEW.md`. CRITICAL or HIGH findings are deploy blockers — `/qualia-ship` checks for them.
+
+```
+◆ Review Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Critical:  {N}
+  High:      {N}
+  Medium:    {N}
+  Low:       {N}
+
+  {If blockers: Fix CRITICAL/HIGH before /qualia-ship}
+  {If clean: Ready to ship}
+```

package/skills/qualia-ship/SKILL.md

@@ -83,8 +83,10 @@ curl -s -o /dev/null -w "%{http_code}" {domain}/api/auth/callback
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Update STATE.md: "shipped"
-Update tracking.json: status → "shipped", deployed_url
+```bash
+node ~/.claude/bin/state.js transition --to shipped --deployed-url {production url}
+```
+Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 
 ```
   → Run: /qualia-handoff