godpowers 0.15.0

package/skills/god-context-scan.md

@@ -0,0 +1,125 @@
+---
+name: god-context-scan
+description: |
+  Detect drift between the current AI session's mental model and
+  disk reality. The defensive cousin of /god-status. Use in long
+  sessions or when an output starts feeling wrong. Surfaces
+  hallucinated facts, missed updates, stale memories, and
+  context-rot before they cause bad commits.
+
+  Triggers on: "god context scan", "/god-context-scan", "check
+  drift", "am I out of date", "verify my context"
+---
+
+# /god-context-scan
+
+Detect when the AI's working memory has diverged from disk.
+
+## When to use
+
+- **Long sessions** (more than ~50 turns) where the AI's window
+  has had to summarize old context away.
+- **Before any commit** in a session that has been running for
+  more than 30 minutes.
+- **After a pause and resume** when the AI might have been talked
+  out of an earlier decision.
+- **Whenever an AI output starts feeling wrong** - faster than
+  re-reading state by hand.
+
+## What it does
+
+This skill is unusual: it asks the AI to dump its current
+understanding, then compares that to disk. Discrepancies are
+called drifts.
+
+### Process
+
+1. AI writes down its claimed model of state in a structured form:
+   ```yaml
+   claim:
+     project: <name>
+     mode: <A/B/C/E>
+     currentTier: <tier>
+     currentSubstep: <substep>
+     lastAction: <name>
+     lastArtifactWritten: <path>
+     openTodos: [...]
+     heldFacts: [...]
+   ```
+2. `lib/checkpoint.diff(projectRoot, claim)` compares the claim to
+   `.godpowers/CHECKPOINT.md` frontmatter + facts.
+3. `lib/state.detectDrift(projectRoot)` cross-checks artifacts on
+   disk match their recorded hashes.
+4. `lib/events.readRun(projectRoot, latestRun)` last 30 events
+   verified for hash-chain continuity (when v0.13+ event hash
+   chain is in place).
+5. Drift findings are presented with severity:
+   - **error**: claim contradicts disk (e.g. AI thinks PRD is in
+     progress, disk says done)
+   - **warn**: claim has stale data (e.g. AI doesn't know about
+     last 3 events)
+   - **info**: claim mentions facts not in CHECKPOINT held-facts
+     (might be new, worth recording)
+6. Suggested actions: `/god-locate` to re-orient, `/god-repair`
+   for state drift, or accept the new facts via `/god-checkpoint
+   --record-facts`.
+
+### Output
+
+```
+GODPOWERS CONTEXT SCAN
+
+Claims compared: 8
+Matches: 6
+Drifts: 2
+
+ERROR drifts:
+- field: currentSubstep
+  claimed: prd-in-progress
+  actual: arch-pending
+  -> the PRD was completed and you started ARCH; refresh memory
+
+WARN drifts:
+- field: openTodos
+  claimed: 3 open
+  actual: 5 open (2 were added after your last sync)
+
+Suggested next:
+1. /god-locate    (re-orient against disk)
+2. Accept the 2 new todos: /god-check-todos
+```
+
+## What this does NOT do
+
+- Does not modify state. Read-only.
+- Does not "fix" the AI's context (only the AI can do that, by
+  re-reading the relevant files).
+- Does not catch hallucinations about content the AI never claimed.
+  It can only compare what the AI explicitly states.
+
+## Subcommands
+
+### `/god-context-scan`
+Full scan: AI states model, system compares, reports drifts.
+
+### `/god-context-scan --quick`
+Compare only the top 5 highest-value fields (mode, currentTier,
+currentSubstep, lastAction, openTodoCount).
+
+### `/god-context-scan --auto`
+Skips the "AI states model" step and just compares
+CHECKPOINT.md timestamp against state.json timestamp +
+recent-events count. Useful in autonomous mode.
+
+## Implementation
+
+Built-in. Reads `lib/checkpoint.js`, `lib/state.js`,
+`lib/events.js`. The "ask AI to state its model" step is the AI's
+own work; the comparison is library code.
+
+## Related
+
+- `/god-locate` - orient a NEW session
+- `/god-status` - full state report
+- `/god-doctor` - install + state integrity
+- `/god-repair` - reconcile state drift

package/skills/god-context.md

@@ -0,0 +1,147 @@
+---
+name: god-context
+description: |
+  Manage the Godpowers fenced section in project-level AI instruction files
+  (AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules/, .windsurfrules,
+  .github/copilot-instructions.md, .clinerules, .roo/, .continue/).
+
+  Triggers on: "god context", "/god-context", "tell ai tools", "ai instructions",
+  "context off", "context status", "agents.md", "claude.md", "gemini.md"
+---
+
+# /god-context
+
+Tell your AI coding tools that this is a Godpowers project. The skill writes
+a fenced section to `AGENTS.md` (canonical) and 1-line pointer fences to any
+detected tool's instruction file (CLAUDE.md, GEMINI.md, etc.). You can turn
+it off, check status, or refresh on demand.
+
+## Subcommands
+
+| Form | What it does |
+|---|---|
+| `/god-context` (no args) | Same as `status`. |
+| `/god-context on` | Write AGENTS.md and pointers for any detected AI tools. |
+| `/god-context off` | Remove the Godpowers fence from every target file. |
+| `/god-context status` | Show which targets have a fence and which tools were detected. |
+| `/god-context refresh` | Same as `on`. Re-derives content from current state. |
+
+## Process
+
+1. Verify `.godpowers/` exists. If not, suggest `/god-init` first.
+2. Read `.godpowers/state.json`.
+3. Spawn `god-context-writer` agent with the requested mode.
+4. Report results.
+
+## What gets written
+
+**Always (canonical):**
+
+- `AGENTS.md` - full Godpowers section (under 30 lines)
+
+**Only if detected (pointer):**
+
+| Tool detected via | Pointer target |
+|---|---|
+| `.claude/` directory | `CLAUDE.md` |
+| `.gemini/` directory or existing `GEMINI.md` | `GEMINI.md` |
+| `.cursor/` directory | `.cursor/rules/godpowers.mdc` |
+| `.cursorrules` file | `.cursorrules` |
+| `.windsurf/` directory | `.windsurf/rules/godpowers.md` |
+| `.windsurfrules` file | `.windsurfrules` |
+| `.github/copilot-instructions.md` | same |
+| `.clinerules` file | same |
+| `.roo/` directory | `.roo/rules/godpowers.md` |
+| `.continue/` directory | `.continue/rules/godpowers.md` |
+
+If none of these are detected, only `AGENTS.md` is written (which is the
+universal standard).
+
+## Fence rules
+
+The Godpowers section is wrapped in:
+
+```
+<!-- godpowers:begin -->
+...
+<!-- godpowers:end -->
+```
+
+Anything outside the fence is yours and is never touched. If you have your
+own AGENTS.md content, keep it. The fence inserts itself either at the end
+of an existing file or in a new one.
+
+## Examples
+
+### First-time setup
+
+```
+$ /god-context on
+
+Detecting AI tools...
+  + Claude Code (.claude/)
+  + Cursor (.cursor/)
+
+Writing context files:
+  + AGENTS.md           (created, canonical)
+  + CLAUDE.md           (created, pointer)
+  + .cursor/rules/godpowers.mdc   (created, pointer)
+
+Done. AI tools opening this project will now see Godpowers context.
+```
+
+### Status
+
+```
+$ /god-context status
+
+AGENTS.md          fence present
+CLAUDE.md          fence present
+GEMINI.md          not detected (.gemini/ missing)
+.cursor/rules/...  fence present
+.windsurfrules     not detected
+
+Run /god-context refresh to re-derive content from current state.
+```
+
+### Off
+
+```
+$ /god-context off
+
+Removing context fences:
+  - AGENTS.md     (kept, user content remained)
+  - CLAUDE.md     (deleted, was Godpowers-only)
+
+Done. AI tools will no longer see Godpowers context on this project.
+```
+
+## Auto-refresh
+
+When `/god-sync` runs (post-arc, or any sync), `god-updater` calls this skill
+with `refresh` to keep `AGENTS.md` content aligned with the latest project
+state (mode, scale, completed tiers, active artifacts).
+
+You can disable this by running `/god-context off`. It won't be re-enabled
+without your explicit `/god-context on`.
+
+## Privacy / portability
+
+The fenced content contains:
+- Project name (from state.json)
+- Mode (greenfield/brownfield/audit) and scale
+- A short list of completed-tier artifact paths
+- Quarterback rule reminder
+- Top 4 useful slash commands
+
+It does NOT contain:
+- Secrets, credentials, API keys
+- PRD body, ARCH body, or any artifact full text
+- User PII
+
+Heavy content stays in `.godpowers/`. The fence just points to it.
+
+## Output
+
+This skill produces no new artifacts under `.godpowers/`. It modifies
+project-root files (AGENTS.md and tool-specific pointers) only.

package/skills/god-cost.md

@@ -0,0 +1,118 @@
+---
+name: god-cost
+description: |
+  Token cost + dollar accounting report. Shows spend, savings (via
+  cache hits), and breakdowns per tier / agent / model across one or
+  all runs. Use to spot expensive tiers, justify cache enablement,
+  or measure the impact of /god-budget tightening.
+
+  Triggers on: "god cost", "/god-cost", "how much did this cost",
+  "token spend", "show savings"
+---
+
+# /god-cost
+
+Report token + dollar spend across runs.
+
+## Usage
+
+### `/god-cost`
+Aggregate across every run in the project.
+
+### `/god-cost <run-id>`
+One specific run.
+
+### `/god-cost --since=<duration>`
+E.g. `--since=24h`, `--since=7d`.
+
+### `/god-cost --json`
+Machine-readable.
+
+### `/god-cost --pricing=<file>`
+Use custom pricing table (JSON) instead of the built-in approximate
+table. Useful if you have negotiated rates.
+
+### `/god-cost --strict`
+Exit non-zero if any `cost.recorded` event has `source: 'estimated'`.
+Use in CI when you have wired live token reporting and want the
+build to fail the moment estimation creeps back in.
+
+## Output
+
+```
+GODPOWERS COST REPORT
+
+Spent: $0.4823 across 18 model calls (124,500 tokens)
+  Live:      $0.4012 (15 calls, 100,400 tokens)
+  Estimated: $0.0811 (3 calls, 24,100 tokens)
+Saved: $0.1842 via 7 cache hits (47,200 tokens)
+Cache hit rate: 28.0% (7/25)
+
+Per tier:
+  tier-1: $0.2134 (8 calls, 3 hits, $0.0892 saved)
+  tier-2: $0.1542 (6 calls, 2 hits, $0.0521 saved)
+  tier-3: $0.1147 (4 calls, 2 hits, $0.0429 saved)
+
+Per agent (top 5 by spend):
+  god-architect: $0.1245 (3 calls)
+  god-pm:        $0.0889 (2 calls)
+  god-executor:  $0.0856 (5 calls)
+  god-roadmapper:$0.0445 (2 calls)
+  god-harden-auditor: $0.0388 (1 call)
+
+Per model:
+  claude-3-5-sonnet: $0.4012 (15 calls)
+  claude-3-5-haiku:  $0.0811 (3 calls)
+```
+
+## Where the data comes from
+
+- `cost.recorded` events: every LLM call records `{model, tokens_in,
+  tokens_out, cost_usd, agent, tier, source}`. Aggregated by tier /
+  agent / model.
+- `cache.hit` events: each hit records `{savings_tokens, savings_usd,
+  agent, tier}`. Counts toward savings.
+- `cache.miss` events: counted to compute hit rate.
+
+## Live vs estimated (source field)
+
+Every `cost.recorded` carries `source: 'live'` or `source: 'estimated'`:
+
+- **live**: the AI tool surfaced real per-call token counts from the
+  provider API response. Numbers reflect actual spend. Emitted by
+  `cost.recordModelCall(handle, {...})` from `lib/cost-tracker.js`.
+- **estimated** (default): the orchestrator inferred token counts from
+  byte heuristics (~4 bytes per token). Useful as a fallback when the
+  AI tool does not expose usage, but the totals are approximate and
+  should not be used for billing or budget enforcement.
+
+`--strict` exits non-zero if any record in scope is estimated. Wire it
+into CI once your tooling reliably reports live usage.
+
+## Pricing table
+
+The default pricing table is the May 2026 ballpark for major models.
+It's approximate; do not use for billing. Customize with
+`--pricing=<file>`:
+
+```json
+{
+  "claude-3-5-sonnet": { "in": 3.0,  "out": 15.0 },
+  "gpt-4o":            { "in": 2.5,  "out": 10.0 },
+  ...
+}
+```
+
+Values are USD per 1M tokens.
+
+## Implementation
+
+Built-in. Reads events.jsonl via `lib/event-reader.js`; aggregates via
+`lib/cost-tracker.js aggregate(...)`. No agent spawn.
+
+## Related
+
+- `/god-budget` - view + set context-budget caps
+- `/god-cache-clear` - invalidate cache (next run = no hits)
+- `/god-metrics` - durations + pauses + errors per tier
+- `/god-logs` - timeline of events

package/skills/god-debug.md

@@ -0,0 +1,30 @@
+---
+name: god-debug
+description: |
+  Systematic 4-phase debugging. Spawns the god-debugger agent in a fresh
+  context. Evidence-driven root cause analysis with regression tests.
+
+  Triggers on: "god debug", "/god-debug", "debug this", "why is this broken", "fix this bug"
+---
+
+# /god-debug
+
+Spawn the **god-debugger** agent in a fresh context via Task tool.
+
+## Setup
+
+1. Gather user's bug description (or use the most recent failure context)
+2. Spawn god-debugger with:
+   - Bug description
+   - Repository context
+   - Recent commits (`git log --oneline -20`)
+3. The agent runs the 4-phase process: Observe, Hypothesize, Test, Conclude
+4. The agent writes a regression test FIRST, then the fix
+5. The agent commits with explanation of root cause
+
+## Verification
+
+After god-debugger returns:
+1. Verify the regression test exists and now passes
+2. Verify the full test suite passes (no regressions)
+3. Verify the commit message explains root cause

package/skills/god-deploy.md

@@ -0,0 +1,76 @@
+---
+name: god-deploy
+description: |
+  Set up deploy pipeline. Spawns the god-deploy-engineer agent in a fresh
+  context. Gated on Build.
+
+  Triggers on: "god deploy", "/god-deploy", "deploy this", "CI/CD", "ship it"
+---
+
+# /god-deploy
+
+Spawn the **god-deploy-engineer** agent in a fresh context via Task tool.
+
+## Setup
+
+1. Verify build is complete (`.godpowers/build/STATE.md` exists with passing state).
+2. Verify all tests pass.
+3. Spawn god-deploy-engineer with ARCH and stack DECISION paths.
+4. The agent writes `.godpowers/deploy/STATE.md`.
+
+## Verification
+
+After god-deploy-engineer returns:
+1. Verify STATE.md exists on disk
+2. Verify rollback procedure has been tested (not paper-only)
+3. Update `.godpowers/PROGRESS.md`: Deploy status = done
+
+## On Completion
+
+```
+Deploy pipeline complete: .godpowers/deploy/STATE.md
+
+Suggested next: /god-observe (wire SLOs, alerts, runbooks)
+```
+
+
+## Re-invocation contract
+
+What happens if `/god-deploy` is run when `.godpowers/deploy/STATE.md` already exists:
+
+| Existing state | Behavior |
+|---|---|
+| File does not exist | Spawn god-deploy-engineer; produce file; mark sub-step done |
+| File exists, passes lint, state.json says `done` | Pause: ask user (A) re-run anyway with diff preview, (B) treat as imported (no-op), (C) cancel |
+| File exists, fails lint or have-nots | Spawn god-deploy-engineer in update mode with current file + findings as input. Diff preview before overwrite. |
+| File exists, state.json says `pending` | Treat as imported: hash + register, no agent spawn. User can `/god-deploy --force` to re-run. |
+| `--force` flag passed | Snapshot existing file to `.godpowers/.trash/god-deploy-<ts>/`. Spawn agent fresh. |
+| `--dry-run` flag passed | Show what would happen; touch nothing |
+
+Snapshots in `.trash/` are recoverable via `/god-restore` for 30 days.
+The reflog records every god-deploy invocation as `op:god-deploy` for `/god-undo`.
+
+### Idempotency guarantees
+
+- Running `/god-deploy` twice with no user input between them is a no-op
+  (second call detects the artifact and pauses).
+- Running `/god-deploy --dry-run` is always read-only.
+- An interrupted `/god-deploy` (agent crashes mid-run) leaves state.json
+  with `status: failed` and the artifact path either missing or marked
+  for `/god-repair` review. Re-running picks up cleanly.
+
+
+## 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-design-impact.md

@@ -0,0 +1,86 @@
+---
+name: god-design-impact
+description: |
+  Predict the impact of a proposed DESIGN.md change without committing.
+  Reports affected components, files, and severity. Useful for "what
+  if I make primary darker?" exploration before running god-design.
+
+  Triggers on: "god design impact", "/god-design-impact", "what changes if",
+  "impact analysis", "affected files"
+---
+
+# /god-design-impact
+
+What-if analysis on DESIGN.md changes. Does NOT modify the design;
+returns a structured report of what would be affected.
+
+## Forms
+
+| Form | Action |
+|---|---|
+| `/god-design-impact "<plain English change description>"` | Predict + analyze |
+| `/god-design-impact --file <new-design.md>` | Compare current DESIGN.md vs the proposed file |
+| `/god-design-impact --token <path> --new <value>` | Single-token change preview |
+
+## Process
+
+1. Verify `DESIGN.md` exists. If not: "no design to analyze."
+2. Compute proposed new content:
+   - Plain English: paraphrase the change into a token edit (best effort).
+     If ambiguous, ask one clarifying question.
+   - `--file`: read the candidate file.
+   - `--token X --new V`: replace token value in current DESIGN.md.
+3. Call `lib/impact.forDesign(projectRoot, oldContent, newContent)`.
+4. Format the report:
+   - Token changes (added / removed / modified)
+   - Component changes (added / removed / modified)
+   - Affected files (linked via the linkage map)
+   - Severity (error if removals, warning if modifications, info if additions)
+5. If `--depth 2` flag given: include transitive dependents via
+   `lib/impact.transitive`.
+
+## Output
+
+```
+/god-design-impact: "make primary darker"
+
+Proposed changes:
+  - colors.primary: oklch(20% 0.01 250) -> oklch(15% 0.01 250)
+
+Token changes (1):
+  modified  colors.primary  oklch(20% 0.01 250) -> oklch(15% 0.01 250)
+
+Component changes (0):
+  (none directly)
+
+Affected files (3):
+  src/components/Button.tsx
+  src/components/Header.tsx
+  src/styles/globals.css
+
+Severity: warning (modification, no removals)
+
+Transitive (depth 2):
+  src/pages/index.tsx (depends on Button, Header)
+
+Recommendation: Run /god-design with this change to apply.
+god-design-reviewer will gate via two-stage review.
+```
+
+## When this skill helps
+
+- "What if we tone down the bold accent?"
+- "Can I rename `card` to `panel`?"
+- "If I remove `colors.tertiary`, what breaks?"
+- "Show me before I commit."
+
+## What it does NOT do
+
+- Apply the change (use `/god-design` for that)
+- Run impeccable critique (that's part of the actual review gate)
+- Persist anything to disk (purely informational)
+
+## Output
+
+No artifact changes. No state.json updates. Findings to stdout (or JSON
+with `--json`).