godpowers 0.15.0

package/skills/god-agent-audit.md

@@ -0,0 +1,87 @@
+---
+name: god-agent-audit
+description: |
+  Validates every `agents/*.md` against the agent contract:
+  required frontmatter, recommended sections (Have-Nots, Inputs,
+  Outputs, Handoff), hand-off targets exist, no dual-ownership of
+  output paths. Lenient by design: most issues are warnings; only
+  structural breakage errors.
+
+  Triggers on: "god agent audit", "/god-agent-audit", "audit agents",
+  "validate agent contracts"
+---
+
+# /god-agent-audit
+
+Mechanical validation of agent contracts. Backed by `lib/agent-validator.js`.
+
+## Forms
+
+| Form | Action |
+|---|---|
+| `/god-agent-audit` | Default human-readable report |
+| `/god-agent-audit --json` | Structured JSON output |
+| `/god-agent-audit --errors-only` | Skip warnings and infos |
+| `/god-agent-audit --fix` | Append placeholder for missing recommended sections (info-level only) |
+
+## What gets checked
+
+**Required (errors)**:
+- Frontmatter `name` field
+- Frontmatter `description` field
+
+**Recommended (warnings)**:
+- Frontmatter `tools` field
+- Hand-off targets that are referenced exist as agent files
+- Output paths claimed by 4+ agents (boundary review needed)
+
+**Recommended (info)**:
+- Each agent should have these sections somewhere:
+  - "Have-Nots" (or equivalent failure list)
+  - "Inputs" (what it reads)
+  - "Outputs" (what it writes)
+  - "Handoff" (where it returns / what it spawns)
+
+The info-level suggestions are non-blocking. They surface as polish
+opportunities, not failures.
+
+## Output
+
+```
+Agent audit
+
+37 agents audited
+0 errors, 2 warnings, 90 infos
+
+Errors:
+(none)
+
+Warnings:
+  [multi-ownership] STATE.md claimed by 4 agents (verify boundaries)
+  [multi-ownership] .godpowers/roadmap/ROADMAP.md claimed by 4 agents
+
+Infos: 90 missing-recommended-section suggestions across agents
+       (run with --json for full list)
+```
+
+## Backward-compatibility promise
+
+This skill never breaks existing agents that don't yet have the
+recommended sections. Errors fire only on real structural issues
+(missing required frontmatter, broken hand-off targets, conflicting
+output ownership).
+
+The `--fix` flag inserts placeholder sections so contributors can
+fill them in incrementally. It never modifies content that's already
+present.
+
+## Integration
+
+`/god-agent-audit` is part of the standard test suite (npm test).
+Agent contract violations become regression failures: contracts can
+only get tighter over time, not looser.
+
+## See also
+
+- `lib/agent-validator.js` - parser + validator
+- `docs/agent-specs.md` - per-agent specifications (canonical reference)

package/skills/god-arch.md

@@ -0,0 +1,81 @@
+---
+name: god-arch
+description: |
+  Design system architecture. Spawns the god-architect specialist agent in a
+  fresh context. Gated on PRD.
+
+  Triggers on: "god arch", "/god-arch", "design architecture", "system design"
+---
+
+# /god-arch
+
+Spawn the **god-architect** agent in a fresh context via Task tool.
+
+## Setup
+
+1. Verify `.godpowers/prd/PRD.md` exists. If not, tell user to run `/god-prd` first.
+2. Spawn god-auditor briefly to verify PRD passes have-nots. If fails, report and stop.
+3. Spawn god-architect with the PRD path and full context window
+4. The agent writes `.godpowers/arch/ARCH.md` and ADRs to `.godpowers/arch/adr/`
+
+## Verification
+
+After god-architect returns:
+1. Verify ARCH.md and ADRs exist on disk
+2. Spawn god-auditor to verify have-nots pass
+3. Update `.godpowers/PROGRESS.md`: Architecture status = done
+
+## Pause Format
+
+Relay any pauses from god-architect using the standard format (What/Why/Options/Default).
+
+## On Completion
+
+```
+Architecture complete: .godpowers/arch/ARCH.md
+
+Suggested next: /god-roadmap (sequence the work) or /god-stack (pick the tech)
+Both are gated on ARCH and can run in either order.
+```
+
+
+## Re-invocation contract
+
+What happens if `/god-arch` is run when `.godpowers/arch/ARCH.md` already exists:
+
+| Existing state | Behavior |
+|---|---|
+| File does not exist | Spawn god-architect; 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-architect 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-arch --force` to re-run. |
+| `--force` flag passed | Snapshot existing file to `.godpowers/.trash/god-arch-<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-arch invocation as `op:god-arch` for `/god-undo`.
+
+### Idempotency guarantees
+
+- Running `/god-arch` twice with no user input between them is a no-op
+  (second call detects the artifact and pauses).
+- Running `/god-arch --dry-run` is always read-only.
+- An interrupted `/god-arch` (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-archaeology.md

@@ -0,0 +1,48 @@
+---
+name: god-archaeology
+description: |
+  Deep code archaeology for brownfield projects. Goes beyond /god-map-codebase
+  by tracing history, surfacing tribal knowledge, identifying risk areas, and
+  reconstructing decisions from evidence in the code.
+
+  Triggers on: "god archaeology", "/god-archaeology", "code archaeology",
+  "understand legacy", "deep code analysis"
+---
+
+# /god-archaeology
+
+Deep brownfield code analysis.
+
+## When to use
+
+- Inheriting an existing codebase
+- Before significant refactor or migration
+- Onboarding to a complex legacy system
+- After /god-map-codebase wasn't deep enough
+
+## Setup
+
+1. Verify there's existing code to analyze (not an empty dir)
+2. Spawn god-archaeologist in fresh context
+
+## Verification
+
+- `.godpowers/archaeology/REPORT.md` exists
+- Report covers: history, decisions, conventions, risks, tribal knowledge
+- High-risk files explicitly listed
+- Recommendations are specific (not "be careful")
+
+## On Completion
+
+```
+Archaeology complete: .godpowers/archaeology/REPORT.md
+
+History analyzed: [N] commits over [time period]
+High-risk files identified: [N]
+Open tribal-knowledge questions: [N]
+
+Suggested next:
+  /god-reconstruct  - reverse-engineer planning artifacts from this code
+  /god-tech-debt    - assess and prioritize debt revealed
+  /god-feature      - now safe to add new work with archaeology in hand
+```

package/skills/god-audit.md

@@ -0,0 +1,65 @@
+---
+name: god-audit
+description: |
+  Score existing artifacts against all have-nots. Build nothing. Report gaps
+  with prioritized remediation.
+
+  Triggers on: "god audit", "audit the project", "score artifacts", "check quality"
+---
+
+# /god-audit
+
+Spawn the **god-auditor** agent in a fresh context via Task tool.
+
+## Setup
+
+1. Verify `.godpowers/` directory exists. If not: tell user there's nothing to audit.
+2. Spawn god-auditor with instructions: "Run full audit mode. Score every
+   artifact against `references/HAVE-NOTS.md`."
+3. The agent writes `.godpowers/AUDIT-REPORT.md`
+
+## Verification
+
+After god-auditor returns:
+1. Verify AUDIT-REPORT.md exists on disk
+2. Display the summary table to the user
+3. If any artifact scored below 80%: suggest re-running the failing tier
+
+## Output Format
+
+The agent produces `.godpowers/AUDIT-REPORT.md`:
+
+```markdown
+# Godpowers Audit Report
+
+Date: [timestamp]
+
+## Summary
+
+| Artifact | Have-Nots Checked | Passed | Failed | Score |
+|----------|------------------|--------|--------|-------|
+| PRD | 8 | 6 | 2 | 75% |
+| Architecture | 7 | 7 | 0 | 100% |
+| ... | ... | ... | ... | ... |
+
+Overall: 85%
+
+## Failures (prioritized by impact)
+
+### 1. PRD: Target user is generic
+- **Have-not**: Target user is "developers" with no further specificity
+- **Found**: "This is for developers who want to..." (line 14)
+- **Fix**: Replace with specific persona (e.g., "solo founders building SaaS MVPs")
+
+### 2. PRD: Success metric has no timeline
+- **Have-not**: Success metric has no timeline
+- **Found**: "1000 users" (line 28) -- no "by when"
+- **Fix**: Add timeline (e.g., "1000 users within 60 days of launch")
+```
+
+## Universal Have-Nots (checked on all artifacts)
+
+- AI-slop: passes substitution test
+- Unlabeled sentence: not decision/hypothesis/open question
+- Paper artifact: document exists, mechanism does not
+- Phantom reference: references an artifact that doesn't exist on disk

package/skills/god-budget.md

@@ -0,0 +1,103 @@
+---
+name: god-budget
+description: |
+  View or set token-budget controls in intent.yaml. Budgets cap
+  per-agent context loadout to keep token spend bounded; model
+  profiles route routine work to cheaper models; cache enable opts
+  into the agent-output cache.
+
+  Triggers on: "god budget", "/god-budget", "set token cap", "model
+  profile", "cheap mode", "enable cache"
+---
+
+# /god-budget
+
+View or set token-cost saver controls in intent.yaml.
+
+## Usage
+
+### `/god-budget`
+Show current budgets in plain English.
+
+### `/god-budget --on`
+**One-shot enable.** Writes the recommended defaults to
+`intent.yaml.budgets`:
+- `default-max-tokens: 80000`
+- `model-profile: standard`
+- `cache: true`
+- `cache-ttl-hours: 24`
+
+Use this if you want budgeting without thinking about specific
+numbers. Idempotent; running it again is a no-op.
+
+### `/god-budget --off`
+**One-shot disable.** Removes the entire `budgets` block from
+`intent.yaml`. Cache stays on disk (clear it with
+`/god-cache-clear --all` if you want to free space). Budget caps no
+longer applied; cache hits no longer consulted on subsequent runs.
+
+### `/god-budget --default-max-tokens=N`
+Set the default per-agent context cap. Example: `--default-max-tokens=80000`.
+
+### `/god-budget --agent <name> --max-tokens=N`
+Per-agent override. Example: `--agent god-architect --max-tokens=120000`
+(architect gets more context because architecture needs the full PRD).
+
+### `/god-budget --profile=<cheap|standard|expensive>`
+Set the default model-profile. cheap routes routine reads to small
+models; standard is the balanced default; expensive uses top-tier
+for everything.
+
+### `/god-budget --agent <name> --profile=<cheap|standard|expensive>`
+Per-agent profile override.
+
+### `/god-budget --cache=<on|off>`
+Enable/disable the agent-output cache. Default off.
+
+### `/god-budget --cache-ttl=<hours>`
+Set cache entry TTL.
+
+## Output (view mode)
+
+```
+GODPOWERS BUDGETS
+
+Defaults:
+  Max input tokens per agent: 80,000
+  Model profile: standard
+  Cache: off (enable with --cache=on)
+  Cache TTL: 24 hours
+
+Per-agent overrides:
+  god-architect: max-tokens=120,000
+  god-pm:        profile=expensive
+  god-status:    profile=cheap
+```
+
+## What each setting actually does
+
+| Setting | Effect |
+|---|---|
+| `default-max-tokens` | The orchestrator computes each agent's context loadout (required + optional files) and drops optional files beyond this cap. Required files are always loaded (a `budget.exceeded` event is emitted if they alone exceed the cap). |
+| `model-profile: cheap` | Orchestrator prefers haiku / gpt-4o-mini / flash for non-creative work. Creative agents (god-pm, god-architect, god-designer) still use standard or above. |
+| `cache: true` | Before spawning an agent, compute the cache key. If a non-expired entry exists for that key, emit `cache.hit` and reuse the output. Miss spawns the agent and records the result. |
+| `cache-ttl-hours` | TTL for newly written cache entries. Lower = fresher results but more re-spawns. |
+
+## Default behavior (no budget set)
+
+- Max tokens per agent: 80,000 (built-in default in `lib/context-budget.js`)
+- Model profile: standard
+- Cache: off
+- TTL: 24 hours
+
+## Implementation
+
+Built-in. Reads + writes `.godpowers/intent.yaml` against
+`schema/intent.v1.yaml.json`. No agent spawn.
+
+## Related
+
+- `/god-cost` - what you've spent and saved
+- `/god-cache-clear` - invalidate cache after rule changes
+- `/god-set-profile` - one-time profile change (similar but
+  session-scoped instead of project-scoped)

package/skills/god-build-agent.md

@@ -0,0 +1,91 @@
+---
+name: god-build-agent
+description: |
+  Create a custom specialist agent. Walks through the agent's purpose, tools,
+  spawning conditions, gates, and output contract. Generates a new file in
+  .claude/agents/ following the Godpowers agent template.
+
+  Triggers on: "god build agent", "/god-build-agent", "create custom agent",
+  "new specialist"
+---
+
+# /god-build-agent
+
+Create a custom specialist agent for this project's specific needs.
+
+## When to use
+
+- Domain-specific expertise the default agents don't cover (e.g., legal
+  reviewer, accessibility auditor, ML model evaluator)
+- Repeatable specialist work that doesn't fit existing agents
+
+## Process
+
+1. Ask the user 5 questions:
+   - **Name**: What should the agent be called? (kebab-case, prefix `god-`)
+   - **Purpose**: One sentence: what does this agent do?
+   - **Spawned by**: Which slash command(s) invoke it?
+   - **Inputs**: What artifacts/context does it read?
+   - **Outputs**: What artifact does it write?
+
+2. Optionally ask:
+   - **Gate check**: What must be true upstream before this agent runs?
+   - **Have-nots**: What failure modes should it check?
+   - **Tools needed**: Read, Write, Edit, Bash, Grep, Glob, Task, WebSearch?
+   - **Pause conditions**: When should it return to caller for human input?
+
+3. Generate the agent file at `agents/[name].md` using this template:
+
+```markdown
+---
+name: [name]
+description: |
+  [One-sentence purpose.]
+
+  [Trigger description.]
+
+  Spawned by: [/slash-command]
+tools: [comma-separated tools]
+---
+
+# [Agent Title]
+
+[Detailed instructions for the agent.]
+
+## Gate Check
+[What must exist on disk before this agent runs.]
+
+## Process
+[Step-by-step what the agent does.]
+
+## Output
+[What the agent writes, where.]
+
+## Have-Nots
+[Named failure modes specific to this agent's output.]
+
+## Pause Conditions
+[When to return to caller for human input.]
+
+## Done Criteria
+[How the agent knows it's finished.]
+```
+
+4. Show the generated file to the user for approval before saving.
+
+5. After approval, also generate a slash command skill if needed at
+   `skills/[command].md` that spawns this agent.
+
+## Output
+
+- New agent at `agents/[name].md`
+- Optionally a new skill at `skills/[command].md`
+
+## On Completion
+
+```
+Custom agent created: agents/[name].md
+
+To use: invoke from your skill or command, or run /god-build-agent again
+to create more.
+```

package/skills/god-build.md

@@ -0,0 +1,90 @@
+---
+name: god-build
+description: |
+  Build the project. Spawns god-planner first, then god-executor agents in
+  parallel waves with TDD enforcement and two-stage review. Each slice
+  commit is gated on god-spec-reviewer and god-quality-reviewer.
+
+  Triggers on: "god build", "/god-build", "build it", "implement", "start coding"
+---
+
+# /god-build
+
+Orchestrate the build via specialist agents.
+
+## Setup
+
+1. Verify gates:
+   - `.godpowers/roadmap/ROADMAP.md` exists (skip if scale is trivial)
+   - `.godpowers/stack/DECISION.md` exists (skip if scale is trivial)
+   - Repo is scaffolded
+2. If any gate fails: tell user which command to run first
+
+## Orchestration
+
+### Phase 1: Plan
+Spawn **god-planner** in fresh context with ROADMAP, ARCH, DECISION.
+Output: `.godpowers/build/PLAN.md` with vertical slices grouped into waves.
+
+### Phase 2: Execute Waves
+
+For each wave in PLAN.md:
+
+For each slice in the wave (parallel):
+1. Spawn **god-executor** in fresh context with:
+   - The slice plan only (not the whole PLAN.md)
+   - Relevant ARCH context for this slice
+   - Stack DECISION
+2. Wait for executor to complete (TDD enforced)
+3. Spawn **god-spec-reviewer** in fresh context (independent of executor)
+   - If FAIL: return slice to god-executor with findings
+   - If PASS: proceed to stage 2
+4. Spawn **god-quality-reviewer** in fresh context (independent)
+   - If FAIL: return slice to god-executor with findings
+   - If PASS: commit the slice atomically
+5. Update `.godpowers/build/STATE.md`
+
+Move to next wave only when current wave is fully committed.
+
+## Verification
+
+After all waves:
+1. Run full test suite. All pass.
+2. Run linter. All clean.
+3. Update PROGRESS.md: Build status = done
+
+## Pause Conditions
+
+Pause for user ONLY if:
+- A requirement is genuinely ambiguous (two valid implementations)
+- A test reveals a gap in PRD or ARCH that needs human resolution
+
+## On Completion
+
+```
+Build complete: .godpowers/build/STATE.md
+[N] slices delivered. [N] commits. All tests passing.
+
+Suggested next: /god-harden (adversarial review, gates Launch)
+Alternative: /god-deploy (set up deploy pipeline, parallel-safe)
+Both can run; /god-harden is the critical path to Launch.
+```
+
+If more milestones remain in the roadmap, suggest re-running /god-build for
+the next milestone before moving to Tier 3.
+
+
+## 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-cache-clear.md

@@ -0,0 +1,75 @@
+---
+name: god-cache-clear
+description: |
+  Invalidate the agent-output cache. Use after agent prompts change,
+  after a major refactor that should re-run agents, or to recover
+  disk space. Read-only inspection: /god-cost.
+
+  Triggers on: "god cache clear", "/god-cache-clear", "flush cache",
+  "invalidate cache", "reset cache"
+---
+
+# /god-cache-clear
+
+Invalidate agent-output cache entries.
+
+## Usage
+
+### `/god-cache-clear`
+Interactive: shows cache size + entries, asks confirmation, clears all.
+
+### `/god-cache-clear --all`
+Clear every entry. Skip confirmation.
+
+### `/god-cache-clear --expired`
+Clear only entries past their TTL.
+
+### `/god-cache-clear --agent <name>`
+Clear entries for one agent (e.g. after editing
+`agents/god-pm.md`, clear `--agent god-pm`).
+
+### `/god-cache-clear --older-than=<duration>`
+Clear entries older than N (e.g. `--older-than=7d`).
+
+### `/god-cache-clear --stats`
+Show cache stats; clear nothing.
+
+## Output
+
+```
+GODPOWERS CACHE
+
+Location: .godpowers/cache/
+Entries: 47
+Total: 412 KB
+Oldest: 2026-05-08T11:23:47.000Z (2 days ago)
+
+Clearing all 47 entries...
+Cleared 47 entries (412 KB freed).
+```
+
+## When to use
+
+| Scenario | Command |
+|---|---|
+| Edited an agent prompt | `/god-cache-clear --agent god-pm` |
+| Wholesale refactor; everything should re-run | `/god-cache-clear --all` |
+| Disk space, just kill old stuff | `/god-cache-clear --older-than=7d` |
+| Just want to see what's cached | `/god-cache-clear --stats` |
+| Drop expired entries between runs | `/god-cache-clear --expired` (auto-runs in /god-doctor --fix) |
+
+## What it does NOT do
+
+- Does not delete events.jsonl history. Past `cache.hit` records stay
+  in the audit log; only the cached outputs are removed.
+- Does not affect intent.yaml settings. To disable caching entirely,
+  use `/god-budget --cache=off`.
+
+## Implementation
+
+Built-in. Calls `lib/agent-cache.js clear(...)` and `stats(...)`.
+
+## Related
+
+- `/god-cost` - spend + savings report
+- `/god-budget` - cache config (enable, TTL, etc.)

package/skills/god-check-todos.md

@@ -0,0 +1,42 @@
+---
+name: god-check-todos
+description: |
+  List pending todos from .godpowers/todos/TODOS.md. Optionally select one
+  to work on (routes to appropriate workflow).
+
+  Triggers on: "god check todos", "/god-check-todos", "show todos", "what's pending"
+---
+
+# /god-check-todos
+
+List todos and optionally route to a workflow.
+
+## Process
+
+1. Read `.godpowers/todos/TODOS.md`
+2. Display open todos grouped by priority
+3. Ask: "Want to work on one of these?"
+4. If yes: route to the right workflow based on todo nature:
+   - "fix" -> /god-debug or /god-hotfix
+   - "add" -> /god-feature
+   - "refactor" -> /god-refactor
+   - "research" -> /god-spike
+   - default: /god-quick
+
+## Output
+
+```
+Open todos (7):
+
+P0 (1):
+  - 2026-04-15: Fix auth bypass in /api/admin (CRITICAL-001 from harden)
+
+P1 (3):
+  - 2026-04-20: Update Stripe library to v14 (deps audit)
+  - 2026-04-22: Add CSP headers (HARDEN-04)
+  - ...
+
+P2 (3): ...
+
+Want to work on one? (number, or "no")
+```