godpowers 0.15.0

package/skills/god-test-runtime.md

@@ -0,0 +1,144 @@
+---
+name: god-test-runtime
+description: |
+  Run headless browser verification of the running app: design audit
+  (rendered styles vs DESIGN.md tokens, real-DOM WCAG contrast) and
+  functional tests (PRD acceptance criteria as user flows). Uses
+  Playwright (local) or Vercel Browser API (cloud).
+
+  Triggers on: "god test runtime", "/god-test-runtime", "browser test",
+  "design audit", "verify rendering", "run e2e", "run tests"
+---
+
+# /god-test-runtime
+
+Drive a headless browser to verify the app actually matches what
+artifacts say it should be. The third axis of verification (after
+static lint and linkage drift).
+
+## Forms
+
+| Form | Action |
+|---|---|
+| `/god-test-runtime` | Full pipeline: audit + functional tests |
+| `/god-test-runtime audit [url]` | Design audit only |
+| `/god-test-runtime test [url]` | Functional tests only |
+| `/god-test-runtime --backend agent-browser` | Force vercel-labs/agent-browser CLI (preferred) |
+| `/god-test-runtime --backend playwright` | Force Playwright (local fallback) |
+| `/god-test-runtime --backend auto` | Default cascade: agent-browser -> Playwright |
+| `/god-test-runtime --strict` | Promote warnings to errors |
+| `/god-test-runtime --no-runtime` | Skip; surface as warning (use sparingly) |
+
+## Default URL resolution
+
+If `[url]` not given:
+1. Read `state.json.deploy.url` if present (production / preview)
+2. Else read `state.json.dev-server.url` if dev server is running
+3. Else default to `http://localhost:3000`
+
+## Process
+
+1. Verify `.godpowers/` exists.
+2. Spawn `god-browser-tester` agent in fresh context with the requested
+   mode (audit / test / both) and resolved URL.
+3. god-browser-tester:
+   - Detects backend (Playwright or Vercel Browser)
+   - Launches headless browser (NEVER `headless: false`)
+   - Navigates, extracts computed styles, runs flows, captures screenshots
+   - Aggregates findings
+   - Writes reports to `.godpowers/runtime/<run-id>/`
+   - Critical findings -> critical-finding gate (pauses default + --yolo)
+   - Other findings -> REVIEW-REQUIRED.md batch
+4. Report results to user.
+
+## Headless contract
+
+Non-negotiable. The bridge layer (`lib/browser-bridge.js`) refuses to
+pass `headless: false`. There is no opt-out flag for that. If you want
+a visual session, use a separate Playwright instance outside Godpowers.
+
+`--no-runtime` skips the entire runtime step (e.g., for backend-only
+projects with no UI to verify). It does NOT mean "show me the browser."
+
+## Output
+
+Per run, in `.godpowers/runtime/<run-id>/`:
+- `audit-report.json` - design verification findings with severity
+- `test-report.json` - functional verification with pass/fail per requirement
+- `screenshots/<name>.png` - reference screenshots
+- `summary.md` - human-readable summary
+
+State updates:
+- `state.json.runtime.last-run-id` <- runId
+- `state.json.runtime.backend` <- 'playwright' | 'vercel-browser'
+- `state.json.runtime.audit.summary` <- { errors, warnings, infos }
+- `state.json.runtime.test.summary` <- { passed, failed, total }
+
+Events to events.jsonl:
+- `runtime.start`, `runtime.audit-complete`, `runtime.test-complete`,
+  `runtime.critical`, `runtime.end`
+
+## Critical findings (gate triggers)
+
+- Any P-MUST-* requirement fails its acceptance flow
+- WCAG AA fail on text-on-background components
+- Component drift > 10% (more than 1 in 10 selectors mismatch DESIGN.md)
+
+These pause both default mode AND --yolo. Lint errors and runtime
+critical findings have the same gate semantics.
+
+## When this runs automatically
+
+| Workflow | Mode | Gate semantics |
+|---|---|---|
+| `/god-build` (post-wave, opt-in) | audit | warning |
+| `/god-launch` | full pipeline | hard gate; criticals block |
+| `/god-harden` | a11y portion | warning |
+| `/god-design` (post-change) | audit | warning |
+
+## Output to events.jsonl
+
+```json
+{ "name": "runtime.start", "url": "https://...", "backend": "playwright" }
+{ "name": "runtime.audit-complete", "errors": 0, "warnings": 2, "infos": 1 }
+{ "name": "runtime.test-complete", "passed": 5, "failed": 1, "total": 6 }
+{ "name": "runtime.critical", "trigger": "P-MUST-01-failed" }
+{ "name": "runtime.end", "runId": "..." }
+```
+
+## Backend choice in detail
+
+Three native backends supported, with a preference cascade:
+
+### 1. agent-browser (preferred) - vercel-labs/agent-browser
+
+[github.com/vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser).
+Native Rust CLI built specifically for AI agents. Features:
+
+- Accessibility-tree-first interface with stable refs (`@e1`, `@e2`)
+- Semantic locators (`find role button --name "Submit"`)
+- No Node.js daemon required (single binary)
+- Headless by default; optimized for AI workflows
+- Built-in `chat` mode for natural-language control
+
+Install:
+```bash
+npm install -g agent-browser
+agent-browser install   # Downloads Chrome from Chrome for Testing
+```
+
+This is our preferred backend. Maps better to PRD acceptance phrasing
+("user clicks Submit" -> `find role button click --name "Submit"`).
+
+### 2. Playwright - microsoft/playwright
+
+Full programmatic browser automation. Used when agent-browser absent.
+Headless launch only (`headless: true` enforced by bridge).
+
+## See also
+
+- `lib/browser-bridge.js` - cascade detection + launch (agent-browser, Playwright)
+- `lib/agent-browser-driver.js` - vercel-labs/agent-browser CLI wrapper
+- `lib/runtime-audit.js` - design verification on rendered DOM (backend-aware)
+- `lib/runtime-test.js` - PRD acceptance to user-flow assertions (backend-aware)
+- `agents/god-browser-tester.md` - lifecycle owner of runtime checks

package/skills/god-thread.md

@@ -0,0 +1,39 @@
+---
+name: god-thread
+description: |
+  Manage persistent context threads. Create, switch, list, and resume named
+  conversation threads for cross-session work on specific topics.
+
+  Triggers on: "god thread", "/god-thread", "context thread", "named thread"
+---
+
+# /god-thread
+
+Manage persistent context threads.
+
+## Subcommands
+
+### `/god-thread new <name>`
+Create a new thread. Records initial context to `.godpowers/threads/<name>.md`.
+
+### `/god-thread list`
+List all threads with last-updated timestamps.
+
+### `/god-thread switch <name>`
+Switch active thread. Loads previous context summary.
+
+### `/god-thread resume <name>`
+Resume a paused thread, loading its full context.
+
+### `/god-thread archive <name>`
+Archive a completed thread to `.godpowers/threads/archive/`.
+
+## When to use
+
+- Cross-session work on a specific topic ("auth migration", "billing refactor")
+- Multi-week threads where you want to preserve reasoning
+- Multiple parallel conversations on different parts of the project
+
+## Output
+
+Threads are markdown files with append-only context blocks per session.

package/skills/god-trace.md

@@ -0,0 +1,50 @@
+---
+name: god-trace
+description: |
+  Deep dive on one tier's events across one run. Shows every event
+  for the tier in chronological order with full attrs. Useful for
+  debugging a stuck or slow tier, or auditing what a specific
+  agent did.
+
+  Triggers on: "god trace", "/god-trace", "what happened in tier-1",
+  "debug tier", "deep dive"
+---
+
+# /god-trace
+
+Deep dive on one tier's events.
+
+## Usage
+
+### `/god-trace <tier>`
+Filter the most-recent run by tier (e.g. `tier-1`, `tier-2`).
+
+### `/god-trace <tier> <run-id>`
+Specific run.
+
+### `/god-trace <tier> --json`
+Machine-readable.
+
+## Output
+
+```
+TRACE tier-1  run=2026-05-10T21-42-00-abc12345
+
+2026-05-10T21:42:00.000Z workflow.run         attrs={workflow:full-arc}
+2026-05-10T21:42:01.234Z agent.start          agent=god-pm
+2026-05-10T21:42:08.001Z tool.call            tool=Read path=examples/...
+2026-05-10T21:42:12.456Z tool.call            tool=Write path=prd/PRD.md
+2026-05-10T21:42:42.789Z agent.end            agent=god-pm status=success
+2026-05-10T21:42:43.012Z gate.pass            gate=standards artifact=prd/PRD.md
+2026-05-10T21:42:44.111Z agent.start          agent=god-architect
+...
+```
+
+## Implementation
+
+Built-in. Calls `lib/event-reader.js trace(projectRoot, runId, tier)`.
+
+## Related
+
+- `/god-logs` - whole-run timeline
+- `/god-metrics` - aggregate stats

package/skills/god-undo.md

@@ -0,0 +1,68 @@
+---
+name: god-undo
+description: |
+  Revert the last operation via the reflog. Reads .godpowers/log, identifies
+  the most recent operation, and applies the inverse. Confirms before any
+  destructive change.
+
+  Triggers on: "god undo", "/god-undo", "revert last", "undo that"
+---
+
+# /god-undo
+
+Revert the most recent state-changing operation.
+
+## Process
+
+1. Read `.godpowers/log` (the reflog)
+2. Identify the most recent operation
+3. Compute the inverse:
+   - `op:run` -> roll back tier statuses + move artifacts to .trash
+   - `op:extension.install` -> uninstall the extension
+   - `op:agent.update` -> revert agent version
+4. Show the user what will happen, ask for confirmation
+5. Execute on confirm; append a `op:undo` event to the log
+
+## Safety
+
+Destructive operations move files to `.godpowers/.trash/` (recoverable).
+Never permanent deletion without explicit /god-restore decision.
+
+## Subcommands
+
+### `/god-undo`
+Undo the most recent operation.
+
+### `/god-undo --to=<op-id>`
+Undo back to a specific operation.
+
+### `/god-undo --dry-run`
+Show what would happen without doing it.
+
+## On Completion
+
+```
+Undone: [operation]
+Restored: [N] artifacts to .trash for review
+Reflog now points to: [previous op-id]
+
+Suggested next:
+  - /god-status to verify current state
+  - /god-restore if you want to recover something specific
+```
+
+
+## Locking
+
+The orchestrator acquires a state-lock before this skill mutates anything,
+scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
+`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
+same holder; force-reclaimable if stale via `/god-repair`.
+
+Read-only inspection commands (`/god-status`, `/god-doctor`,
+`/god-locate`) do NOT block on the lock. Concurrent writers on
+non-overlapping scopes are allowed; on overlapping scopes, the second
+writer pauses or routes elsewhere via `/god-next`.
+
+See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
+the full contract.

package/skills/god-update-deps.md

@@ -0,0 +1,134 @@
+---
+name: god-update-deps
+description: |
+  Audit and update dependencies safely. Identifies CVEs, deprecation, and
+  staleness. Plans incremental updates with regression tests between each.
+  Distinguishes patch/minor (safe to batch) from major (needs migration).
+
+  Triggers on: "god update deps", "/god-update-deps", "update dependencies",
+  "audit deps", "npm audit", "dependency upgrade"
+---
+
+# /god-update-deps
+
+Update dependencies safely.
+
+## When to use
+
+- Routine maintenance (monthly cadence recommended)
+- After a CVE alert
+- Before a major release (clean dep tree)
+- When `npm outdated` shows accumulated drift
+
+## When NOT to use
+
+- A specific dependency is part of a framework migration: use /god-upgrade
+- Single trivial bump in dev: use /god-fast
+
+## Orchestration
+
+### Phase 1: Audit (god-deps-auditor)
+Spawn **god-deps-auditor** in fresh context.
+
+The agent:
+1. Runs the appropriate audit tool for the stack (`npm audit`, `pip-audit`,
+   etc.)
+2. Lists outdated and stale dependencies
+3. Classifies each: Critical CVE / Stale / Major behind / Minor behind / OK
+4. Writes AUDIT.md
+
+### Phase 2: Triage
+The agent presents the audit. Priority order:
+1. Critical CVEs (act now)
+2. Stale + major behind (likely abandoned, plan replacement)
+3. Minor/patch updates (batch them)
+
+### Phase 3: Apply Updates
+
+For **patch updates** (X.Y.Z -> X.Y.Z+1):
+- Group by category (e.g., all eslint plugins together)
+- Spawn **god-executor** to update + run tests
+- Spawn reviewers (compressed)
+- Atomic commit
+
+For **minor updates** (X.Y -> X.Y+1):
+- One package at a time
+- Spawn **god-executor** to update + run tests + read changelog
+- Spawn reviewers
+- Atomic commit
+
+For **major updates** (X -> X+1):
+- DO NOT proceed in this workflow
+- Route to /god-upgrade for each major update
+- Defer in this AUDIT.md
+
+### Phase 4: Verify
+After all updates:
+- Full test suite must pass
+- CI must be green
+- Lockfile committed
+
+## On Completion
+
+```
+Dependency audit complete.
+
+Critical CVEs: N (all addressed)
+Patch updates: N applied
+Minor updates: N applied
+Major updates: N deferred to /god-upgrade
+
+Audit: .godpowers/deps/AUDIT.md
+
+Suggested next:
+  - For each major version deferred: /god-upgrade
+  - /god-status to verify project state
+```
+
+## Have-Nots
+
+Deps update FAILS if:
+- Critical CVE found and not addressed (without rationale)
+- Multiple major updates batched in one commit
+- No regression tests run between updates
+- Bulk update without per-package commits (loses bisect-ability)
+- Lockfile not committed
+
+## Linkage and reverse-sync
+
+Per Phase 13 of the production-ready plan, this workflow participates
+in the linkage system:
+
+- On completion of any code change, `lib/reverse-sync.run(projectRoot)`
+  is called via god-updater. This:
+  - Scans new/modified code for linkage annotations (// Implements: P-MUST-NN, etc.)
+  - Updates `.godpowers/links/{artifact-to-code,code-to-artifact}.json`
+  - Detects drift via `lib/drift-detector`
+  - Appends fenced footers to PRD/ARCH/ROADMAP/STACK/DESIGN
+  - Surfaces drift findings to REVIEW-REQUIRED.md
+
+- Stable IDs MUST be used in artifact deltas (P-MUST-NN, ADR-NNN,
+  C-{slug}, M-{slug}, S-{slug}, D-{slug}, token paths). The scanner
+  picks them up automatically via comment annotations.
+
+- For UI work: agent-browser audit may run as part of /god-build
+  post-wave or /god-launch gate (see `/god-test-runtime`).
+
+- Findings flow into the standard REVIEW-REQUIRED.md walkthrough
+  via `/god-review-changes`.
+
+
+## Locking
+
+The orchestrator acquires a state-lock before this skill mutates anything,
+scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
+`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
+same holder; force-reclaimable if stale via `/god-repair`.
+
+Read-only inspection commands (`/god-status`, `/god-doctor`,
+`/god-locate`) do NOT block on the lock. Concurrent writers on
+non-overlapping scopes are allowed; on overlapping scopes, the second
+writer pauses or routes elsewhere via `/god-next`.
+
+See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
+the full contract.

package/skills/god-upgrade.md

@@ -0,0 +1,139 @@
+---
+name: god-upgrade
+description: |
+  Framework, version, or stack migration. Uses expand-contract pattern,
+  incremental rollout with parallel paths during transition, metric-gated
+  steps. Avoids big-bang migrations.
+
+  Triggers on: "god upgrade", "/god-upgrade", "migrate framework", "upgrade version",
+  "framework migration", "stack migration", "version bump"
+---
+
+# /god-upgrade
+
+Migrate a framework, version, or stack component safely.
+
+## When to use
+
+- React 17 -> React 19
+- Node 18 -> Node 22
+- Python 3.10 -> 3.13
+- Express -> Fastify
+- Replacing one library with another
+
+## When NOT to use
+
+- Single dependency bump (patch/minor): use /god-update-deps
+- New feature, not migration: use /god-feature
+- Refactor without version change: use /god-refactor
+
+## Setup
+
+Ask the user:
+- From: current version/framework
+- To: target
+- Why: business reason (not "newer is better")
+
+## Orchestration
+
+### Phase 1: Strategy (god-migration-strategist)
+Spawn **god-migration-strategist** in fresh context with the migration target.
+
+The agent:
+1. Audits surface area (which files/modules touched)
+2. Reads upstream changelog for breaking changes
+3. Assesses test coverage on affected surface
+4. Drafts MIGRATION.md with phased plan (expand -> migrate slices -> contract)
+5. Identifies risks and rollback strategy
+
+### Phase 2: Test Coverage Gap-Fill
+If coverage is insufficient on the affected surface:
+Spawn **god-planner** to plan adding tests
+Spawn **god-executor** + reviewers per test slice
+Test coverage must be sufficient BEFORE migration starts.
+
+### Phase 3: Expand
+For each component being migrated:
+- Spawn **god-executor** to introduce the new version alongside the old
+- Add abstraction layer if needed (branch-by-abstraction)
+- Both code paths exist
+- Tests cover both
+
+### Phase 4: Migrate Slices
+For each migration slice:
+1. Spawn **god-executor** to migrate one slice
+2. Spawn **god-spec-reviewer** + **god-quality-reviewer**
+3. Atomic commit
+4. Spawn **god-deploy-engineer** with feature flag (1% -> 10% -> 50% -> 100%)
+5. Spawn **god-observability-engineer** to monitor key metrics
+6. Wait at least 24 hours before next slice (configurable)
+7. If metrics regress: rollback this slice, investigate
+
+### Phase 5: Contract
+After 100% migrated AND a monitoring window passes:
+- Spawn **god-executor** to remove old code path
+- Spawn reviewers
+- Atomic commit: `chore(migration): remove old <thing> path (100% on new)`
+
+## On Completion
+
+```
+Migration complete: <from> -> <to>
+
+Surface migrated: N files, N modules
+Slices: N (all committed and verified)
+Old code path: removed
+Monitoring window: passed
+
+Suggested next: /god-status
+Or: /god-update-deps to address any other outdated dependencies
+```
+
+## Have-Nots
+
+Upgrade FAILS if:
+- Big-bang migration (no incremental slices)
+- No expand-contract pattern
+- Tests not added before migration starts
+- Metrics not gating slice progression
+- Old code removed before 100% migrated
+- No rollback plan per slice
+
+## Linkage and reverse-sync
+
+Per Phase 13 of the production-ready plan, this workflow participates
+in the linkage system:
+
+- On completion of any code change, `lib/reverse-sync.run(projectRoot)`
+  is called via god-updater. This:
+  - Scans new/modified code for linkage annotations (// Implements: P-MUST-NN, etc.)
+  - Updates `.godpowers/links/{artifact-to-code,code-to-artifact}.json`
+  - Detects drift via `lib/drift-detector`
+  - Appends fenced footers to PRD/ARCH/ROADMAP/STACK/DESIGN
+  - Surfaces drift findings to REVIEW-REQUIRED.md
+
+- Stable IDs MUST be used in artifact deltas (P-MUST-NN, ADR-NNN,
+  C-{slug}, M-{slug}, S-{slug}, D-{slug}, token paths). The scanner
+  picks them up automatically via comment annotations.
+
+- For UI work: agent-browser audit may run as part of /god-build
+  post-wave or /god-launch gate (see `/god-test-runtime`).
+
+- Findings flow into the standard REVIEW-REQUIRED.md walkthrough
+  via `/god-review-changes`.
+
+
+## Locking
+
+The orchestrator acquires a state-lock before this skill mutates anything,
+scoped to the smallest affected unit (e.g. `tier-1.prd` for `/god-prd`,
+`linkage` for `/god-scan`). Lock TTL is 5 minutes; reentrant for the
+same holder; force-reclaimable if stale via `/god-repair`.
+
+Read-only inspection commands (`/god-status`, `/god-doctor`,
+`/god-locate`) do NOT block on the lock. Concurrent writers on
+non-overlapping scopes are allowed; on overlapping scopes, the second
+writer pauses or routes elsewhere via `/god-next`.
+
+See [ARCHITECTURE.md "Concurrency contract"](../ARCHITECTURE.md) for
+the full contract.

package/skills/god-version.md

@@ -0,0 +1,37 @@
+---
+name: god-version
+description: |
+  Print installed Godpowers version and a one-line capability summary.
+  Useful for bug reports, troubleshooting, and verifying upgrades.
+
+  Triggers on: "god version", "/god-version", "what version of godpowers"
+---
+
+# /god-version
+
+Print version and a short capability summary.
+
+## Output
+
+```
+Godpowers v0.12.0
+Install: /Users/.../.claude/  (matches package.json)
+Surface: 82 skills, 38 agents, 13 workflows, 36 recipes
+Schema: intent.v1, state.v1, events.v1, workflow.v1, routing.v1, recipe.v1
+External integrations available: impeccable, agent-browser (others lazy)
+```
+
+## Subcommands
+
+### `/god-version --json`
+Machine-readable output.
+
+### `/god-version --check-updates`
+Hit npm to see if a newer version is available (network-aware; fails
+soft if offline).
+
+## Implementation
+
+Built-in, no spawned agent. Reads:
+- `<runtime>/GODPOWERS_VERSION`
+- File counts in `<runtime>/skills/`, `<runtime>/agents/`, `workflows/`, `routing/recipes/`

package/skills/god-workstream.md

@@ -0,0 +1,61 @@
+---
+name: god-workstream
+description: |
+  Manage parallel workstreams. Create, list, switch, and merge isolated
+  workspaces for parallel development. Each workstream has its own .godpowers/
+  state and git branch.
+
+  Triggers on: "god workstream", "/god-workstream", "parallel work", "new branch",
+  "split work"
+---
+
+# /god-workstream
+
+Manage parallel workstreams for concurrent development.
+
+## Subcommands
+
+### `/god-workstream new <name>`
+Create a new workstream:
+1. Create git branch `workstream/<name>`
+2. Create `.godpowers/workstreams/<name>/` with isolated PROGRESS.md
+3. Switch to the new branch and workstream
+4. New workstream inherits PRD/ARCH/ROADMAP from main but tracks its own build state
+
+### `/god-workstream list`
+List all active workstreams:
+```
+Active workstreams:
+  * main          (current) Build: 60% complete
+    feature-x     Build: 20% complete
+    bugfix-y      Build: 90% complete (ready to merge)
+```
+
+### `/god-workstream switch <name>`
+Switch to a different workstream:
+1. Verify current workstream has no uncommitted changes (or stash them)
+2. Checkout `workstream/<name>` branch
+3. Load `.godpowers/workstreams/<name>/PROGRESS.md` as active state
+
+### `/god-workstream status`
+Show detailed status of current workstream and any conflicts with main.
+
+### `/god-workstream merge <name>`
+Merge a workstream back to main:
+1. Verify the workstream has no incomplete sub-steps (or confirm partial merge)
+2. Run /god-review on the diff
+3. If passes: merge to main, archive workstream artifacts
+4. If fails: report findings, do not merge
+
+### `/god-workstream remove <name>`
+Delete a workstream (with confirmation if not merged).
+
+## When to use
+
+- Two engineers working on different parts of the same project
+- Exploring a risky refactor without disrupting main work
+- Running /god-mode for a sub-feature in isolation while main keeps moving
+
+## On Completion
+
+Display the new active workstream and suggested next command.