godpowers 0.15.0

package/skills/god-refactor.md

@@ -0,0 +1,137 @@
+---
+name: god-refactor
+description: |
+  Safe refactor with strict TDD. Refactors are regression-heavy; this workflow
+  enforces tests-before-changes, slice-by-slice incremental change, and
+  two-stage review per slice.
+
+  Triggers on: "god refactor", "/god-refactor", "refactor this", "clean up",
+  "extract", "rename"
+---
+
+# /god-refactor
+
+Refactor without breaking things.
+
+## When to use
+
+- The feature works; you want to improve the code
+- Renaming, extracting, restructuring without behavior change
+- Performance improvements with measurable target
+
+## When NOT to use
+
+- The behavior should change: that's a feature, use /god-feature
+- The bug is in production: use /god-hotfix
+- It's a one-line rename: use /god-fast
+
+## Orchestration
+
+### Phase 1: Scope (god-explorer)
+Spawn **god-explorer** in fresh context with:
+"Help scope a refactor. The user wants to refactor X. Identify:
+- What specifically changes (files, modules)
+- What does NOT change (behavior, public API)
+- Risks: where is regression most likely
+- Existing test coverage on the affected surface"
+
+### Phase 2: Test Coverage Audit
+Before refactoring, verify:
+- All affected behavior is covered by tests
+- Run the test suite: it must currently pass
+- If gaps exist: ADD TESTS FIRST (not refactor first then test)
+- These tests are the safety net during refactor
+
+If coverage is insufficient and tests can't be added economically: STOP. The
+refactor is too risky. Spawn god-pm to write a [HYPOTHESIS] doc explaining
+why and what would unblock it.
+
+### Phase 3: Plan Slices (god-planner)
+Spawn **god-planner** with refactor-mode instructions:
+"Plan the refactor as a sequence of behavior-preserving slices. Each slice:
+- Compiles
+- All tests still pass
+- Can be reverted independently
+
+Avoid 'big leap' slices that break and re-fix in one commit."
+
+### Phase 4: Execute Slices (god-executor + reviewers)
+For each slice:
+1. Spawn **god-executor**:
+   - Make the change
+   - Run all tests
+   - All tests must pass (this is the contract)
+2. Spawn **god-spec-reviewer**:
+   - Did behavior change? (must be NO)
+   - Did public API change? (must be unchanged unless plan said so)
+3. Spawn **god-quality-reviewer**:
+   - Is the code cleaner than before? (the whole point)
+   - Any new technical debt?
+4. Atomic commit: `refactor: <description> (no behavior change)`
+
+### Phase 5: Verify
+Run full test suite one more time. Run lint. Run any benchmarks if performance
+was a goal.
+
+### Phase 6: Deploy (incrementally)
+For non-trivial refactors, deploy gradually. Watch metrics for any signal of
+regression beyond what tests caught.
+
+## On Completion
+
+```
+Refactor complete.
+Slices: N committed
+Tests: all passing
+Behavior: unchanged
+
+Suggested next: /god-status or continue with /god-feature
+```
+
+## Have-Nots
+
+Refactor FAILS if:
+- Tests didn't exist before; refactor proceeded anyway
+- Behavior changed (that's a feature, not a refactor)
+- Public API changed without explicit plan
+- Single big commit instead of slices
+- Tests skipped or disabled to make refactor pass
+
+## 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-repair.md

@@ -0,0 +1,82 @@
+---
+name: god-repair
+description: |
+  Fix detected drift between state.json and actual disk state. Drift
+  happens when files are edited outside Godpowers, when an agent crashes
+  mid-operation, or when state.json is hand-edited incorrectly. Repair
+  reconciles disk reality with state.
+
+  Triggers on: "god repair", "/god-repair", "fix drift", "reconcile
+  state", "state is broken"
+---
+
+# /god-repair
+
+Detect and fix drift between `state.json` and disk.
+
+## What it repairs
+
+| Drift kind | Fix |
+|---|---|
+| state.json says PRD done; PRD.md missing | mark PRD pending, alert user |
+| state.json says PRD pending; PRD.md exists and passes lint | mark PRD imported |
+| state.json file hash differs from current PRD.md hash | re-hash and update |
+| linkage.json entry points at deleted code file | remove entry, mark artifact for review |
+| linkage.json entry missing for an annotated code file | scan + add |
+| Schema version in state.json older than installed | migrate (if path exists) |
+| .trash/ contains items older than 30 days | offer to permanently delete |
+
+## Process
+
+1. Run `lib/drift-detector.js detect()` to enumerate drift.
+2. Categorize: safe-auto-fix vs needs-confirmation vs blocks-progress.
+3. Apply safe-auto-fix immediately (re-hashing, re-running scan).
+4. Show needs-confirmation drift to user; ask Y/N for each.
+5. For blocks-progress drift, instruct the user (e.g. "manually
+   recreate PRD.md or run /god-rollback prd").
+6. Append `op:repair` event to reflog with the fix list.
+
+## Subcommands
+
+### `/god-repair`
+Run repair across the whole project.
+
+### `/god-repair --dry-run`
+Detect drift; do nothing.
+
+### `/god-repair --category=<linkage|hashes|trash|schema>`
+Only repair one category.
+
+### `/god-repair --interactive`
+Walk every drift item with the user, even safe-auto-fixes.
+
+## Difference from related commands
+
+- `/god-doctor`: read-only diagnostic; suggests `/god-repair` for fixable items
+- `/god-scan`: rebuilds the linkage map (one specific kind of drift)
+- `/god-repair`: covers all drift categories including linkage
+
+## Implementation
+
+Built-in. Reads + writes:
+- `.godpowers/state.json`
+- `.godpowers/linkage.json`
+- `.godpowers/log` (appends repair event)
+
+Calls into `lib/drift-detector.js`, `lib/code-scanner.js`, `lib/reverse-sync.js`.
+
+
+## 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-repo.md

@@ -0,0 +1,49 @@
+---
+name: god-repo
+description: |
+  Scaffold a production-grade repository. Spawns the god-repo-scaffolder agent
+  in a fresh context. Gated on Stack.
+
+  Triggers on: "god repo", "/god-repo", "scaffold the repo", "set up the repo"
+---
+
+# /god-repo
+
+Spawn the **god-repo-scaffolder** agent in a fresh context via Task tool.
+
+## Setup
+
+1. Verify `.godpowers/stack/DECISION.md` exists. If not, tell user to run `/god-stack` first.
+2. Spawn god-repo-scaffolder with the stack DECISION path.
+3. The agent scaffolds the repo and writes `.godpowers/repo/AUDIT.md`.
+
+## Verification
+
+After god-repo-scaffolder returns:
+1. Verify AUDIT.md exists on disk
+2. Verify CI passes on the empty scaffold
+3. Update `.godpowers/PROGRESS.md`: Repo status = done
+
+## On Completion
+
+```
+Repo scaffolded: .godpowers/repo/AUDIT.md
+
+Suggested next: /god-build (start building the first milestone)
+```
+
+
+## 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-restore.md

@@ -0,0 +1,91 @@
+---
+name: god-restore
+description: |
+  Recover files from .godpowers/.trash/. Lists trash contents, lets the
+  user pick what to restore, and moves files back to their original
+  location. Pairs with /god-rollback and /god-undo, both of which
+  send files to .trash/ rather than permanently deleting.
+
+  Triggers on: "god restore", "/god-restore", "recover deleted",
+  "undo the rollback", "where did my prd go"
+---
+
+# /god-restore
+
+Recover files from `.godpowers/.trash/`.
+
+## What's in .trash/
+
+Anything that godpowers operations moved out of the active project:
+- `.trash/rollback-<id>/` - from `/god-rollback`
+- `.trash/redo-<id>/` - pre-redo snapshots
+- `.trash/undo-<id>/` - pre-undo snapshots
+- `.trash/expired-<date>/` - auto-cleanup candidates
+
+Files in `.trash/` are not deleted until explicit `/god-restore --purge`
+or after 30 days (configurable in intent.yaml).
+
+## Usage
+
+### `/god-restore`
+List trash contents grouped by operation id with timestamps. Interactive
+selection.
+
+### `/god-restore <op-id>`
+Restore everything from a specific operation, e.g.
+`/god-restore rollback-abc123`.
+
+### `/god-restore <path>`
+Restore a specific file by its trash-relative path.
+
+## Process
+
+1. Enumerate `.trash/` entries.
+2. Present user with the list (or filter by argument).
+3. For each restoration:
+   - Check whether the destination still exists. If yes: confirm overwrite.
+   - Move file from `.trash/` back to its original path.
+   - Run `/god-scan` to refresh linkage for restored artifacts.
+4. Append `op:restore` event to reflog.
+5. Optionally: re-run `/god-repair` to reconcile state.json with restored content.
+
+## Subcommands
+
+### `/god-restore --purge [<op-id>]`
+Permanently delete trash entries. Asks for typed confirmation. Use to
+free disk or to commit to a rollback decision.
+
+### `/god-restore --list`
+Show trash contents without entering interactive mode.
+
+### `/god-restore --age=<days>`
+Show only trash entries older than N days (auto-cleanup candidates).
+
+## Safety
+
+- Restore never silently overwrites without user confirmation.
+- The trash is per-project, not global. Multiple projects each have
+  their own `.godpowers/.trash/`.
+- Trash auto-cleanup is age-based and configurable; default 30 days.
+
+## Implementation
+
+Built-in. Reads `.godpowers/.trash/` directory tree. Writes restored
+files back via standard fs operations. Calls `/god-scan` after restore
+to refresh linkage map.
+
+
+## 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-resume-work.md

@@ -0,0 +1,42 @@
+---
+name: god-resume-work
+description: |
+  Resume work from a previous session. Reads .godpowers/HANDOFF.md if it
+  exists, otherwise re-derives state from PROGRESS.md and disk. Continues
+  from the last incomplete sub-step.
+
+  Triggers on: "god resume", "/god-resume-work", "resume work", "continue",
+  "pick up where I left off"
+---
+
+# /god-resume-work
+
+Load context and continue.
+
+## Process
+
+1. Check for `.godpowers/HANDOFF.md`:
+   - If exists: read it, summarize for user, ask if context is correct
+   - If not: fall back to /god-status (re-derive from disk)
+
+2. If HANDOFF.md exists:
+   - Display "Where We Were", "Active Work", "Open Threads"
+   - Confirm with user: "Pick up here?"
+   - If yes: route to the specific next action
+
+3. If only PROGRESS.md exists:
+   - Run the same logic as /god-next
+   - Suggest the next command based on state
+
+4. After resuming, archive HANDOFF.md:
+   - Move to `.godpowers/archive/HANDOFF-[timestamp].md` so the trail is preserved
+   - Reset `.godpowers/HANDOFF.md` (or delete) so future pauses start clean
+
+## On Completion
+
+```
+Resumed from [timestamp pause].
+
+Continuing: [specific action]
+Next: [/god-X command or specific work]
+```

package/skills/god-review-changes.md

@@ -0,0 +1,93 @@
+---
+name: god-review-changes
+description: |
+  Walk REVIEW-REQUIRED.md interactively. Surface each pending review
+  with affected files and suggested actions. Mark items as addressed
+  to clear them from the pending list.
+
+  Triggers on: "god review changes", "/god-review-changes", "pending reviews",
+  "what needs review", "address reviews"
+---
+
+# /god-review-changes
+
+Walk through pending review items in `REVIEW-REQUIRED.md` one batch at
+a time. For each: show what changed, which files are affected, propose
+remediation, and let the user mark addressed (or defer).
+
+## Forms
+
+| Form | Action |
+|---|---|
+| `/god-review-changes` | Walk all batches interactively |
+| `/god-review-changes --list` | List all pending items, no action |
+| `/god-review-changes --clear` | Clear `REVIEW-REQUIRED.md` (only if empty or after explicit confirm) |
+| `/god-review-changes --json` | Output structured JSON, no interaction |
+
+## Process
+
+1. Read `REVIEW-REQUIRED.md` via `lib/review-required.readEntries`.
+2. If empty: report "No pending reviews."
+3. For each batch, surface:
+   - Batch ID, source, summary, timestamp
+   - Each item with severity, ID, file path, message, suggestion
+4. For each item, ask: address now / defer / mark resolved.
+5. If addressed: open the affected file(s) for editing.
+6. After all items in a batch are addressed: prompt to clear the batch.
+7. After all batches cleared: delete `REVIEW-REQUIRED.md`.
+
+## Auto-clear policy
+
+Per plan question 3: REVIEW-REQUIRED.md does NOT auto-clear under
+--yolo. Clearing requires either:
+- Walking through and marking items
+- Explicit `--clear` flag with confirmation
+
+This forces the user to look at what changed, which is the whole point
+of the artifact.
+
+## Integration with linkage
+
+When showing "affected files," this skill cross-references
+`lib/linkage.queryByFile(projectRoot, file)` so the user sees which
+artifact IDs that file is linked to. Helps decide what to fix.
+
+## Output
+
+```
+/god-review-changes
+
+3 pending batches in REVIEW-REQUIRED.md:
+
+Batch 1: Design token change
+  Source: design-impact
+  Timestamp: 2026-05-10T14:23:11Z
+  Summary: colors.primary darkened; affects 3 files
+
+  Items (3):
+    [WARNING] [colors.primary] src/components/Button.tsx: token value changed
+       Linked to: D-button-primary
+       Suggestion: review computed contrast on Button against background
+
+    [WARNING] [colors.primary] src/components/Header.tsx: token value changed
+       Linked to: D-header
+       Suggestion: review header hierarchy
+
+    [WARNING] [colors.primary] src/styles/globals.css: token value changed
+       Linked to: (style file)
+       Suggestion: re-render visual regression test
+
+Address now / defer / mark resolved? [a/d/r]
+```
+
+## What this skill does NOT do
+
+- Modify any artifact (DESIGN.md, PRD.md, etc.)
+- Run lint or impeccable (those are separate skills)
+- Run reverse-sync (god-updater on /god-sync)
+- Auto-fix any issue (always requires human review)
+
+## Output
+
+Updates `REVIEW-REQUIRED.md` (clearing addressed items). No other
+artifact changes.

package/skills/god-review.md

@@ -0,0 +1,52 @@
+---
+name: god-review
+description: |
+  Two-stage code review. Spawns god-spec-reviewer (Stage 1) followed by
+  god-quality-reviewer (Stage 2). Both must PASS for the review to pass.
+
+  Triggers on: "god review", "/god-review", "review this", "code review"
+---
+
+# /god-review
+
+Spawn two specialist review agents in fresh contexts via Task tool.
+
+## Setup
+
+1. Gather context: what code is being reviewed? (recent diff, specific files, PR)
+2. Locate the relevant plan or PRD acceptance criteria
+3. Run Stage 1 first, then Stage 2 only if Stage 1 passes
+
+## Stage 1: Spec Compliance
+
+Spawn **god-spec-reviewer** in fresh context with:
+- The code to review
+- The plan or PRD acceptance criteria
+- The test results
+
+If FAIL: report findings and STOP. The code must be fixed before Stage 2.
+If PASS: proceed to Stage 2.
+
+## Stage 2: Code Quality
+
+Spawn **god-quality-reviewer** in fresh context with:
+- The code to review (independent of stage 1 findings)
+
+If FAIL: report findings.
+If PASS: review complete.
+
+## Output
+
+```
+## Code Review Verdict
+
+### Stage 1: Spec Compliance - [PASS/FAIL]
+[findings from god-spec-reviewer]
+
+### Stage 2: Code Quality - [PASS/FAIL]
+[findings from god-quality-reviewer]
+
+### Overall: [PASS/FAIL]
+```
+
+Both stages must PASS for the review to PASS.

package/skills/god-roadmap-check.md

@@ -0,0 +1,66 @@
+---
+name: god-roadmap-check
+description: |
+  Check if user intent overlaps with the existing ROADMAP.md before doing
+  feature work. Returns: already-done, in-progress, enhancement,
+  prerequisite-needed, new, or ambiguous. Auto-invoked by /god-next when
+  matched recipe is feature-addition category; can also run manually.
+
+  Triggers on: "god roadmap check", "/god-roadmap-check", "is this on the roadmap",
+  "does this exist", "should this be a new feature"
+---
+
+# /god-roadmap-check
+
+Reconcile intent against ROADMAP.md before adding work.
+
+## Setup
+
+1. Verify `.godpowers/roadmap/ROADMAP.md` exists. If not: nothing to reconcile against; suggest /god-roadmap or /god-feature directly.
+2. Spawn god-roadmap-reconciler with the user's intent description and the roadmap path.
+
+## Output
+
+The reconciler returns a verdict (one of 6 statuses). Display to user:
+
+```
+Roadmap reconciliation: <intent>
+
+Status: ENHANCEMENT
+Match: Milestone 2 (Now): "User can connect Stripe and see basic MRR"
+       Feature: "MRR breakdown views"
+       Match strength: high
+
+Recommendation: This should be added to Milestone 2, not done as a separate
+feature. Two options:
+
+  A: /god-feature scoped to Milestone 2
+     (extends Milestone 2 with this work)
+
+  B: /god-roadmap update
+     (amend Milestone 2's feature list, then continue building)
+
+Default: A (folds into existing milestone for cohesion)
+```
+
+For each status, the recommendation differs:
+- **already-done**: "/god-status to verify; /god-graph trace to find code"
+- **in-progress**: "/god-status; the work is underway"
+- **enhancement**: "Fold into the existing milestone"
+- **prerequisite-needed**: "Complete X first via Y, OR /god-add-backlog"
+- **new**: "4 options: add to Now / add to Next / backlog / seed"
+- **ambiguous**: "Pick from these matches"
+
+## Verification
+
+After god-roadmap-reconciler returns:
+1. Verify the verdict has a status from the canonical 6
+2. Verify recommendation has a concrete action
+3. Display to user; await decision before proceeding
+
+## When called manually
+
+User runs `/god-roadmap-check` with an intent description. Useful for:
+- Sanity check before starting feature work
+- Resolving "should this be a new milestone or part of an existing one?"
+- Reviewing whether backlog items overlap with current plan

package/skills/god-roadmap-update.md

@@ -0,0 +1,64 @@
+---
+name: god-roadmap-update
+description: |
+  After feature work, update ROADMAP.md to reflect what changed. Marks
+  milestones complete, appends new entries, moves work between Now/Next/Later,
+  records changes in a changelog section.
+
+  Triggers on: "god roadmap update", "/god-roadmap-update", "update roadmap",
+  "mark milestone complete", "amend roadmap"
+---
+
+# /god-roadmap-update
+
+Keep ROADMAP.md as a living artifact.
+
+## When to use
+
+- After completing a milestone (mark done, gate passed)
+- After adding a feature mid-arc that wasn't on the original roadmap
+- When priorities shift (move between Now / Next / Later)
+- When a planned milestone is superseded
+
+## Setup
+
+1. Verify `.godpowers/roadmap/ROADMAP.md` exists
+2. Determine the operation:
+   - Mark complete: which milestone?
+   - Append: where (Now/Next/Later) and what?
+   - Move: which milestone, where to?
+   - Remove: which milestone, why?
+
+## Process
+
+Spawn **god-roadmap-updater** in fresh context with:
+- Current ROADMAP.md
+- Description of the change
+- Optional: changeset (commits)
+
+Agent updates the roadmap and re-validates have-nots.
+
+## Verification
+
+After god-roadmap-updater returns:
+1. Verify ROADMAP.md still passes have-nots (R-01 through R-07)
+2. Verify Roadmap Changelog section is appended
+3. Update PROGRESS.md if applicable
+
+## On Completion
+
+```
+Roadmap updated: .godpowers/roadmap/ROADMAP.md
+
+Change: [description]
+Have-nots: still passing
+
+Suggested next: /god-status (see overall state)
+```
+
+## Special: PRD divergence detection
+
+If the update adds a feature not in PRD.md:
+- Surface this as a have-not (P-13: moving-target PRD)
+- Recommend `/god-redo prd` to add the requirement
+- Don't silently let roadmap diverge from PRD