godpowers 0.15.0

package/skills/god-help.md

@@ -0,0 +1,66 @@
+---
+name: god-help
+description: |
+  Discoverable contextual help for Godpowers. Lists all skills grouped
+  by category, with the current project state and what's suggested next.
+  Different from /god (front door): /god proposes a command sequence;
+  /god-help lists the catalog.
+
+  Triggers on: "god help", "/god-help", "what can godpowers do",
+  "list commands", "show help"
+---
+
+# /god-help
+
+List Godpowers commands organized by category. Show the catalog.
+
+## Output sections
+
+### 1. Where you are
+One line summary of project state from `state.json`:
+- Mode (A/B/C/E + suite flag), scale, current tier, last command
+
+### 2. Suggested next
+The same suggestion `/god-next` would make. One command.
+
+### 3. Catalog
+All installed skills grouped by category. Categories match
+`docs/reference.md` order.
+
+### 4. Where to go for more
+- Full reference: `<runtime>/godpowers-references/reference.md`
+- Concepts: `<runtime>/godpowers-references/concepts.md`
+- Roadmap: `<runtime>/godpowers-references/ROADMAP.md`
+
+## Subcommands
+
+### `/god-help`
+Full catalog with categories.
+
+### `/god-help <command>`
+Description of one specific command (reads the skill's frontmatter description).
+
+### `/god-help search <keyword>`
+Filter the catalog by keyword match against descriptions.
+
+### `/god-help --category=<name>`
+Show only one category (lifecycle, planning, building, shipping, etc.).
+
+## Implementation
+
+Built-in, no spawned agent. Reads:
+- `<runtime>/skills/*.md` frontmatter
+- `.godpowers/state.json` (for current state line)
+- `lib/recipes.js` (for suggested next)
+
+## When to use
+
+- First time using Godpowers and need an overview
+- Forgot the exact name of a command
+- Want to discover commands relevant to the current state
+
+## When NOT to use
+
+- You know exactly what you want -> just run that command
+- You want intent-to-command matching -> use `/god` (front door)
+- You want a single next-step suggestion -> use `/god-next`

package/skills/god-hotfix.md

@@ -0,0 +1,139 @@
+---
+name: god-hotfix
+description: |
+  Urgent production bug fix. Skips ALL planning. Goes: debug -> regression
+  test -> minimal fix -> two-stage review (compressed) -> expedited deploy
+  -> verify in prod -> auto-trigger postmortem.
+
+  Triggers on: "god hotfix", "/god-hotfix", "production is down", "urgent fix",
+  "hotfix", "fire drill"
+---
+
+# /god-hotfix
+
+Urgent production bug fix. Speed matters; discipline still applies.
+
+## When to use
+
+- Production is broken or degraded
+- Users are affected right now
+- Waiting for a normal /god-mode arc is unacceptable
+
+## When NOT to use
+
+- Bug found in dev: use /god-debug
+- Non-urgent issue: use /god-feature or /god-quick
+- Need root-cause investigation but no urgency: use /god-debug
+- Already fixed; need postmortem: use /god-postmortem
+
+## Orchestration
+
+### Phase 1: Debug (god-debugger)
+Spawn **god-debugger** in fresh context with the symptoms.
+Time-box: 30 minutes for diagnosis. If not root-caused in 30 min, escalate.
+
+### Phase 2: Regression Test
+Before writing the fix:
+- Write a test that reproduces the bug
+- Run it. It MUST fail.
+- This locks in the fix-verification contract.
+
+### Phase 3: Minimal Fix (god-executor)
+Spawn **god-executor** scoped to:
+- The smallest possible fix
+- The test from Phase 2 must pass
+- No refactoring, no scope creep
+- Atomic commit
+
+### Phase 4: Compressed Two-Stage Review
+Spawn **god-spec-reviewer**:
+- Question 1: Does the fix resolve the bug? (test passes)
+- Question 2: Are any regressions introduced? (full test suite green)
+- Question 3: Is the fix scoped to the bug only? (no scope creep)
+PASS or FAIL only.
+
+Spawn **god-quality-reviewer** with FAST PATH:
+- Security: any new attack surface? (one question)
+- Error handling: graceful failure? (one question)
+- No full quality review; that comes later.
+
+If both PASS: proceed.
+
+### Phase 5: Expedited Deploy
+Spawn **god-deploy-engineer** with hotfix annotation:
+- Skip canary/gradual rollout if appropriate (judgment call)
+- Deploy directly to production
+- Post-deploy smoke test against the fix-verification scenario
+
+### Phase 6: Verify in Production
+Spawn **god-observability-engineer** briefly:
+- Did the symptom stop?
+- Did any new alerts fire?
+- Confirm recovery in metrics
+
+### Phase 7: Schedule Postmortem
+Update PROGRESS.md with a TODO:
+"Run /god-postmortem within 48 hours for incident <id>"
+
+Hotfix doesn't replace postmortem; it precedes it.
+
+## On Completion
+
+```
+Hotfix shipped.
+Bug: [description]
+Root cause: [one line]
+Fix: [commit SHA]
+Verified in prod: [timestamp]
+
+REQUIRED next within 48 hours: /god-postmortem
+This investigates the class-of-bug, action items, runbook updates.
+```
+
+## Have-Nots
+
+Hotfix FAILS if:
+- No regression test written (fix could regress)
+- Fix exceeds the minimum scope
+- Two-stage review skipped entirely
+- Deploy not verified in prod
+- Postmortem not scheduled
+
+## 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-hygiene.md

@@ -0,0 +1,104 @@
+---
+name: god-hygiene
+description: |
+  Composite health check for ongoing projects. Runs audit (artifact quality)
+  + dep audit (CVEs, staleness) + docs verification (drift). Use periodically
+  (weekly/monthly) or before milestones.
+
+  Triggers on: "god hygiene", "/god-hygiene", "health check", "project health",
+  "weekly check", "audit everything"
+---
+
+# /god-hygiene
+
+Periodic health check. Three audits in one slash command.
+
+## When to use
+
+- Weekly or monthly cadence on a live project
+- Before announcing a milestone
+- After a long break from a project
+- Before handing off to a new owner
+
+## When NOT to use
+
+- Mid-incident: focus on /god-hotfix or /god-debug
+- Right after /god-mode: hygiene was already optional during arc
+
+## Orchestration
+
+Run three sub-audits in sequence. Each is independent and reports to the
+top-level summary.
+
+### 1. Artifact Quality Audit
+Spawn **god-auditor** with audit-only mode.
+Output: `.godpowers/AUDIT-REPORT.md`
+
+### 2. Dependency Audit
+Spawn **god-deps-auditor** in audit-only mode (no updates applied).
+Output: `.godpowers/deps/AUDIT.md`
+
+### 3. Docs Verification
+Spawn **god-docs-writer** in verify-only mode (no edits applied).
+Output: `.godpowers/docs/UPDATE-LOG.md` with drift list
+
+## Composite Report
+
+After all three complete, write `.godpowers/HYGIENE-REPORT.md`:
+
+```markdown
+# Project Hygiene Report
+
+Date: [ISO 8601]
+
+## Artifact Quality
+- Score: [%]
+- Passing: [N artifacts]
+- Failing: [N artifacts]
+- Top fix: [most impactful remediation]
+
+## Dependencies
+- Critical CVEs: [N]
+- Stale (>18mo): [N]
+- Major behind: [N]
+- Top action: [highest-priority update]
+
+## Documentation
+- Drift entries: [N]
+- Top drift: [most misleading claim]
+
+## Recommended Actions (prioritized)
+1. [Highest-priority action across all three audits]
+2. [Next]
+3. [Next]
+
+## Health Score
+Overall: [composite score 0-100]
+- Artifact quality: [%]
+- Dependency hygiene: [%]
+- Documentation accuracy: [%]
+```
+
+## On Completion
+
+```
+Hygiene check complete.
+Report: .godpowers/HYGIENE-REPORT.md
+
+Health score: [%]
+
+Suggested next actions (in priority order):
+  1. [highest-priority]
+  2. [next]
+  3. [next]
+
+Schedule next hygiene check in [N days] (default: 30).
+```
+
+## Have-Nots
+
+Hygiene check FAILS if:
+- Any sub-audit was skipped without justification
+- Composite report has no prioritized actions
+- Critical CVE found and not surfaced as P0
+- Doc drift "minor only" without verifying

package/skills/god-init.md

@@ -0,0 +1,161 @@
+---
+name: god-init
+description: |
+  Initialize a Godpowers project. Detects operating mode (greenfield, gap-fill,
+  audit, multi-repo) and project scale. Creates .godpowers/ directory with
+  PROGRESS.md.
+
+  Triggers on: "god init", "start a project", "new project", "initialize"
+---
+
+# God Init
+
+Initialize the Godpowers project structure.
+
+## Process
+
+This skill is a thin wrapper. Detection happens automatically; user never
+needs to specify a mode.
+
+1. Check if `.godpowers/` already exists:
+   - If yes: read PROGRESS.md, report current state, ask if user wants to
+     reset or resume
+   - If no: proceed with initialization
+
+2. **Auto-detect what kind of project this is** (background, no user prompt):
+   - Scan working directory for code presence:
+     - package.json / pyproject.toml / Cargo.toml / go.mod / Gemfile / etc.
+     - src/ or lib/ with files
+     - Existing tests
+   - Look for org-level context (current dir + parent dirs):
+     - .godpowers/org-context.yaml
+     - Workspace configs that share standards
+
+3. **Announce findings in plain English** (no jargon):
+   - Empty dir + no org context: "Detected: empty directory. Starting fresh."
+   - Empty dir + org context: "Detected: empty directory + org standards.
+     I'll respect your org's tooling/infrastructure choices."
+   - Code present + no org context: "Detected: existing codebase. I'll
+     understand it before changing anything (archaeology + reconstruction)."
+   - Code present + org context: "Detected: existing codebase + org standards.
+     I'll archaeology, reconstruct, and respect your org's standards."
+
+4. Ask the user to describe what they want to build. Accept any format.
+
+5. Spawn **god-orchestrator** in fresh context with the user's description and
+   the detected mode/context.
+
+   The orchestrator will:
+   - Run Mode Detection (announced in plain English; stored as A/B/C/E internally)
+   - Run Scale Detection (trivial/small/medium/large/enterprise)
+   - For brownfield: schedule archaeology + reconstruction as preflight
+   - For bluefield: load org-context as constraint
+   - Create directory structure
+   - Write PROGRESS.md with mode, scale, timestamp, tier states
+   - Return mode/scale/announcement to this skill
+
+4. Detect scale by analyzing the description:
+   - **Trivial**: Single file change, bug fix, config tweak
+   - **Small**: One feature, one service, <1 week
+   - **Medium**: Multiple features, 1-3 services, 1-4 weeks
+   - **Large**: Multiple services, team coordination, 1-3 months
+   - **Enterprise**: Multiple teams, compliance, 3+ months
+
+5. Create the directory structure:
+   ```
+   .godpowers/
+     PROGRESS.md
+     prd/
+     arch/
+       adr/
+     roadmap/
+     stack/
+     repo/
+     build/
+     deploy/
+     observe/
+     launch/
+     harden/
+   ```
+
+6. Write PROGRESS.md with mode, scale, timestamp, all tiers set to `pending`
+
+7. Report to the user:
+   - Detected mode and scale
+   - Which tiers and personas will activate
+   - What to run next (suggest `god prd` or `god mode`)
+
+## Scale-Adaptive Activation
+
+| Scale | Planning depth | Personas | Ceremonies |
+|-------|---------------|----------|------------|
+| Trivial | Skip to build | Dev only | None |
+| Small | Lightweight PRD, skip ARCH | Dev | None |
+| Medium | Full PRD, ARCH, Roadmap | PM, Dev, QA | None |
+| Large | Full planning, all tiers | PM, Arch, Dev, QA | Optional sprints |
+| Enterprise | Full planning, compliance | All personas | Full sprints, retros |
+
+## Output
+
+`.godpowers/PROGRESS.md` created with initial state.
+
+## AI-tool context (one-time prompt)
+
+After PROGRESS.md is written, ask the user once:
+
+```
+Tell your AI coding tools (Claude Code, Codex, Gemini, Cursor, Windsurf,
+Copilot, Cline, etc.) that this is a Godpowers project? This writes a fenced
+section to AGENTS.md (canonical) and 1-line pointers to any AI-tool config
+files detected in this project.
+
+  yes        - write fences now
+  no         - skip for now (you can run /god-context on later)
+  never-ask  - never ask again on this project
+```
+
+Persist the answer to `state.json` under `project.context-prompt-answered`.
+On `yes`, spawn `god-context-writer` in `write` mode. On `never-ask`, store
+that flag so future runs of /god-init and /god-sync skip the prompt and the
+auto-refresh.
+
+If the user later wants to enable it manually, they run `/god-context on`.
+
+## Mode D detection (multi-repo workspace)
+
+After PROGRESS.md is written, also check whether this directory is
+part of a multi-repo suite:
+
+1. Call `lib/multi-repo-detector.detect(projectRoot)`.
+2. If `isMultiRepo: true`: surface to user.
+   ```
+   This project's parent appears to be a Mode D suite hub (siblings: a, b).
+     - We're a sibling - join the suite via /god-suite-init in the hub
+     - We're the hub - run /god-suite-status to see all repos
+     - Skip - proceed as a standalone repo
+   ```
+3. If sibling .godpowers/ dirs exist nearby but no hub registered:
+   ```
+   Detected sibling .godpowers/ dirs at: [paths]
+   Want to register as a multi-repo suite (Mode D)? Run /god-suite-init.
+   ```
+4. Persist detection result to `state.json` under
+   `project.suite-detection`.
+
+Mode D registration is opt-in. Do NOT auto-create suite-config.yaml
+without explicit user invocation of /god-suite-init.
+
+## On Completion
+
+After init completes, print:
+
+```
+Godpowers initialized.
+
+Mode: [detected mode]
+Scale: [detected scale]
+AI-tool context: [enabled / skipped / never-ask]
+
+Suggested next: /god-prd (write the requirements)
+Or: /god-mode (run the full autonomous arc)
+```

package/skills/god-intel.md

@@ -0,0 +1,36 @@
+---
+name: god-intel
+description: |
+  Query, inspect, or refresh codebase intelligence in .godpowers/codebase/.
+  Lightweight alternative to /god-map-codebase; reads existing intelligence
+  rather than regenerating.
+
+  Triggers on: "god intel", "/god-intel", "codebase intel", "codebase info"
+---
+
+# /god-intel
+
+Query the codebase intelligence files.
+
+## Subcommands
+
+### `/god-intel show [focus]`
+Display contents. `focus` is one of: tech, architecture, quality, concerns.
+Default: all.
+
+### `/god-intel refresh [focus]`
+Re-run a specific mapper. Updates that file only. Faster than
+/god-map-codebase.
+
+### `/god-intel age`
+Show how stale each intel file is. Suggests refresh if >30 days old.
+
+## When to use
+
+- During /god-feature: "what's the existing pattern for auth?"
+- During /god-debug: "where might this bug live?"
+- During /god-refactor: "what's the impact surface?"
+
+## Pre-requisite
+
+`/god-map-codebase` must have run at least once.

package/skills/god-launch.md

@@ -0,0 +1,86 @@
+---
+name: god-launch
+description: |
+  Launch the product. Spawns the god-launch-strategist agent in a fresh
+  context. Gated on Harden (no unresolved Critical findings).
+
+  Triggers on: "god launch", "/god-launch", "go live", "Product Hunt", "landing page"
+---
+
+# /god-launch
+
+Spawn the **god-launch-strategist** agent in a fresh context via Task tool.
+
+## Setup
+
+1. Verify `.godpowers/harden/FINDINGS.md` exists with NO unresolved Critical findings.
+2. If Critical findings exist: REFUSE to proceed. Tell user to resolve or
+   explicitly accept the risk first.
+3. Spawn god-launch-strategist with PRD path and harden FINDINGS.md path.
+4. The agent writes `.godpowers/launch/STATE.md` plus landing copy artifacts.
+
+## Verification
+
+After god-launch-strategist returns:
+1. Verify STATE.md exists on disk
+2. Verify landing copy passes substitution test
+3. Verify OG cards rendered (not just meta tags)
+4. Update `.godpowers/PROGRESS.md`: Launch status = done
+
+## Pause Conditions
+
+Relay any pauses from god-launch-strategist. Brand voice and final headline
+approval require human input.
+
+## On Completion
+
+```
+Launch complete: .godpowers/launch/STATE.md
+
+All Godpowers tiers done. Project is live.
+
+Suggested next: /god-audit (score all artifacts retrospectively)
+Or: /god-status (see the final state)
+```
+
+
+## Re-invocation contract
+
+What happens if `/god-launch` is run when `.godpowers/launch/STATE.md` already exists:
+
+| Existing state | Behavior |
+|---|---|
+| File does not exist | Spawn god-launch-strategist; 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-launch-strategist 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-launch --force` to re-run. |
+| `--force` flag passed | Snapshot existing file to `.godpowers/.trash/god-launch-<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-launch invocation as `op:god-launch` for `/god-undo`.
+
+### Idempotency guarantees
+
+- Running `/god-launch` twice with no user input between them is a no-op
+  (second call detects the artifact and pauses).
+- Running `/god-launch --dry-run` is always read-only.
+- An interrupted `/god-launch` (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.