bigpowers 2.87.4 → 2.87.5

package/.gemini/extensions/bigpowers/commands/prompts/define-success.md

@@ -0,0 +1,11 @@
+---
+name: define-success
+description: "TOMBSTONE — renamed/merged to plan-work. This stub resolves for one release then is removed."
+---
+
+# define-success (tombstoned)
+
+This skill has been renamed or merged into `plan-work`. Use `plan-work` instead.
+
+This stub exists for one release as a transition aid, then is removed once
+`scripts/validate-tombstones.sh` flags it as expired.

package/.gemini/extensions/bigpowers/commands/prompts/delegate-task.md

@@ -0,0 +1,90 @@
+---
+name: delegate-task
+description: "Delegate one complex task to a single subagent, review its work in two stages before merging back. Sequential — one agent at a time, with oversight. Use when a task is complex and requires careful review before the result is accepted. Distinct from dispatch-agents (no parallelism here; reviewer sees full diff before proceeding)."
+---
+
+# story: e45s30
+
+# Delegate Task
+> **HARD GATE** — **HARD GATE** — Delegated work must have clear success criteria and verification commands. The delegate must be able to verify completion independently.
+
+
+Delegate a single complex task to a subagent with a two-stage review gate before accepting the result. Use when oversight of a single task matters more than speed.
+
+**Distinct from `dispatch-agents`:** This skill runs one subagent sequentially with a mandatory review. `dispatch-agents` runs multiple subagents in parallel without inter-task review gates.
+
+## Subagent depth tiers (e45s30)
+
+Select brief depth from task `risk:` and skill `effort:` before spawning:
+
+| Tier | When | Brief includes |
+|------|------|----------------|
+| `full_maturity` | P0 stories, multi-file refactors, security work | Full template + CONVENTIONS excerpts + threat model if present |
+| `standard` | Default implementation tasks | Goal, scope, out-of-bounds, constraints, verify, prior decisions |
+| `minimal_decisive` | Light probes, read-only audits | Goal, verify, explicit file list (≤15 lines total) |
+
+State `depth: <tier>` in the Agent tool description field.
+
+## Process
+
+### 1. Define the task
+
+Before spawning the agent, read `specs/state.yaml` if it exists. Then write a minimal self-contained brief using this template (brief size directly controls token cost and hallucination risk — do not pad):
+
+```
+Goal: [one sentence — specific, measurable outcome]
+In scope: [explicit file or module list]
+Out of bounds: [what NOT to do]
+Constraints: [relevant CONVENTIONS.md rules, existing patterns, test requirements]
+Verify: [runnable command]
+Prior decisions: [relevant entries from specs/state.yaml — omit section if none apply]
+```
+
+Do not include full file contents, full conversation history, or decisions unrelated to this task.
+
+### 2. Spawn the subagent (iterative retrieval, max 3 cycles)
+
+Use the Agent tool with a **fresh context** per spawn. Pass prior decisions only via `specs/state.yaml`.
+
+**Cycle:** dispatch → evaluate output vs goal → refine brief → re-spawn if needed (max 3 cycles).
+
+Include in each brief:
+- All context the agent needs (it starts cold — no shared state)
+- Reference to CONVENTIONS.md constraints
+- The verify command it must run before reporting done
+
+### 3. Stage 1 review — output inspection
+
+When the subagent returns, review its report before looking at the diff:
+- Did it run the verify command? Did it pass?
+- Does it explain what it changed and why?
+- Are there any concerns raised by the agent?
+
+If the report raises red flags, ask the subagent for clarification or re-run with adjusted instructions.
+
+### 4. Stage 2 review — diff inspection
+
+Inspect the actual diff:
+```bash
+git diff main...HEAD
+```
+
+Check:
+- [ ] Changes are scoped to what was asked — nothing extra
+- [ ] No `any`, no `@ts-ignore`, no disabled lint rules
+- [ ] Tests added for new behavior
+- [ ] CONVENTIONS.md compliance (naming, structure, no gh issue creation)
+- [ ] Boy Scout Rule: touched areas are cleaner than before
+
+### 5. Decision
+
+- **Accept**: merge the result into the main working branch
+- **Revise**: send back to the subagent with specific feedback
+- **Reject**: discard and re-approach differently
+
+**After accepting**, append to `specs/state.yaml` under `## Active Decisions`:
+```
+**[task short name]**: [what approach the agent chose and why — one sentence]
+```
+
+Report the decision and rationale to the user.

package/.gemini/extensions/bigpowers/commands/prompts/deploy.md

@@ -0,0 +1,197 @@
+---
+name: deploy
+description: "Build → verify artifact → deploy → wait → smoke deployment pipeline. Platform-agnostic (MCP or CLI), with configurable timeout, retry with exponential backoff, and integrated health-check. The deploy half of CI/CD: run after build to push to production."
+---
+
+# Deploy
+
+> **HARD GATE** — Do not deploy without running tests first. Run `test` or your CI suite before this skill.
+>
+> **HARD GATE** — Use this skill from a CI/CD pipeline or post-merge on `main`/`master`. Never deploy from a feature branch.
+>
+> **HARD GATE** — The deploy skill orchestrates deployment; the `smoke-test` skill validates post-deploy health. Chain them: `deploy → smoke-test`.
+
+Orchestrate a full build-to-deployment pipeline: build the artifact, verify it exists and is non-empty, invoke a platform deploy tool (MCP or CLI), poll until the deploy completes or times out, then run a baseline smoke test against the live URL.
+
+## Pipeline Stages
+
+```
+build → verify artifact → deploy → wait/retry → smoke
+```
+
+| Stage | Description | Failure mode |
+|-------|-------------|-------------|
+| Build | Execute the project's build command | Non-zero exit: report build error |
+| Verify | Check artifact exists and is non-empty | Missing/empty: report artifact path |
+| Deploy | Invoke platform deploy tool (MCP, Vercel CLI, rsync, etc.) | Non-zero exit: report deploy error |
+| Wait | Poll deploy status every 30s up to `DEPLOY_TIMEOUT` (default 5 min) | Timeout: report exceeded |
+| Smoke | `curl -sSf $DEPLOY_URL` as baseline health check | Non-200: report failure |
+
+## Process
+
+### 1. Detect build command
+
+Read project manifest files in order to determine the build command:
+
+| Manifest | Build command |
+|----------|--------------|
+| `package.json` | `npm run build` (or `scripts.build` value) |
+| `Cargo.toml` | `cargo build --release` |
+| `pyproject.toml` / `setup.py` | Depends on build backend (`poetry build`, `pip install -e .`, etc.) |
+| `Makefile` | `make build` or first target named `build` |
+| `AGENTS.md` / `CLAUDE.md` | Look for `build:` in project commands section |
+
+If no manifest is found, prompt the user with: "No detected build command. Pass `--build 'npm run build'` or specify the command."
+
+### 2. Build the artifact
+
+```bash
+npm run build
+```
+
+Or the detected command from step 1. If the build fails, exit non-zero and report the build output.
+
+### 3. Verify the artifact
+
+```bash
+ARTIFACT_DIR="${ARTIFACT_DIR:-dist}"
+if [ ! -d "$ARTIFACT_DIR" ] || [ -z "$(ls -A "$ARTIFACT_DIR" 2>/dev/null)" ]; then
+  echo "FAIL: build artifact not found at $ARTIFACT_DIR"
+  exit 1
+fi
+```
+
+Configurable via `$ARTIFACT_DIR` environment variable (default: `dist/`).
+
+### 4. Deploy to platform
+
+Platform-agnostic — supports multiple deployment targets via environment variables:
+
+| Platform | Env var | Example |
+|----------|---------|---------|
+| Vercel | `VERCEL_TOKEN`, `VERCEL_PROJECT_ID` | `vercel deploy --prod --token $VERCEL_TOKEN` |
+| Netlify | `NETLIFY_AUTH_TOKEN`, `NETLIFY_SITE_ID` | `netlify deploy --prod --auth $NETLIFY_AUTH_TOKEN --dir $ARTIFACT_DIR` |
+| Platform MCP | MCP tool call | `mcp deploy` via your platform MCP server |
+| rsync/SSH | `DEPLOY_SSH_USER`, `DEPLOY_SSH_HOST`, `DEPLOY_SSH_PATH` | `rsync -avz $ARTIFACT_DIR/ $DEPLOY_SSH_USER@$DEPLOY_SSH_HOST:$DEPLOY_SSH_PATH` |
+| Custom | `DEPLOY_COMMAND` | Run any deploy command string |
+
+The deploy tool is selected by which environment variables are set. If none are configured:
+
+```bash
+echo "No deploy target configured. Set one of: VERCEL_TOKEN, NETLIFY_AUTH_TOKEN, DEPLOY_SSH_USER+DEPLOY_SSH_HOST, DEPLOY_COMMAND, or MCP deploy tool."
+exit 1
+```
+
+### 5. Wait and poll status
+
+After invoking the deploy command, poll for completion:
+
+See [REFERENCE.md](REFERENCE.md)
+
+Use exponential backoff for retries on transient failures:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 6. Baseline smoke test
+
+See [REFERENCE.md](REFERENCE.md)
+
+For comprehensive health-checking, chain to the `smoke-test` skill:
+
+```bash
+# After deploy success
+bash scripts/run-smoke.sh "$DEPLOY_URL"
+```
+
+### 7. Three-independent-facts verification (e45s15)
+
+Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts).
+
+## Verify
+
+→ verify: `command -v curl >/dev/null 2>&1 && test -f skills/smoke-test/SKILL.md`
+
+---
+
+# Deploy — Reference
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ARTIFACT_DIR` | `dist` | Build output directory |
+| `DEPLOY_URL` | *(required)* | Live URL for smoke test |
+| `DEPLOY_TIMEOUT` | `300` | Max wait for deploy completion (seconds) |
+| `DEPLOY_POLL_INTERVAL` | `30` | Polling interval (seconds) |
+| `RETRY_MAX` | `3` | Max deploy retry attempts |
+| `BUILD_COMMAND` | *(auto-detect)* | Override build command |
+
+
+---
+
+## Verification
+
+→ verify: `test -f deploy/SKILL.md && grep -q 'name: deploy' deploy/SKILL.md && echo OK`
+→ verify: `grep -qi 'build\|artifact\|deploy\|smoke' deploy/SKILL.md && echo OK`
+→ verify: `grep -ci 'package.json\|Cargo.toml\|Makefile\|manifest' deploy/SKILL.md | awk '{if($1>=1) print "OK"; else print "FAIL"}'`
+→ verify: `grep -ci 'timeout\|poll\|status\|retry\|backoff' deploy/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'curl.*DEPLOY_URL\|smoke\|health' deploy/SKILL.md && echo OK`
+
+---
+
+## Reference block 1
+
+```bash
+DEPLOY_TIMEOUT="${DEPLOY_TIMEOUT:-300}"   # seconds (default 5 minutes)
+DEPLOY_POLL_INTERVAL="${DEPLOY_POLL_INTERVAL:-30}"  # seconds
+
+start_time=$(date +%s)
+while true; do
+  elapsed=$(( $(date +%s) - start_time ))
+  if [ "$elapsed" -ge "$DEPLOY_TIMEOUT" ]; then
+    echo "FAIL: deploy status polling timed out after ${DEPLOY_TIMEOUT}s"
+    exit 1
+  fi
+  
+  status=$(get_deploy_status)  # platform-specific status check
+  if [ "$status" = "ready" ] || [ "$status" = "done" ]; then
+    echo "Deploy completed in ${elapsed}s"
+    break
+  fi
+  
+  sleep "$DEPLOY_POLL_INTERVAL"
+done
+```
+
+---
+
+## Reference block 2
+
+```bash
+RETRY_MAX="${RETRY_MAX:-3}"
+base_delay=2
+for attempt in $(seq 1 "$RETRY_MAX"); do
+  if deploy_command; then
+    break
+  fi
+  if [ "$attempt" -eq "$RETRY_MAX" ]; then
+    echo "FAIL: deploy failed after ${RETRY_MAX} attempts"
+    exit 1
+  fi
+  sleep $(( base_delay * 2 ** (attempt - 1) ))
+done
+```
+
+---
+
+## Reference block 3
+
+```bash
+DEPLOY_URL="${DEPLOY_URL:?DEPLOY_URL must be set}"
+if curl -sSf "$DEPLOY_URL" > /dev/null 2>&1; then
+  echo "OK: $DEPLOY_URL responds with HTTP 200"
+else
+  echo "FAIL: $DEPLOY_URL is not responding with HTTP 200"
+  exit 1
+fi
+```

package/.gemini/extensions/bigpowers/commands/prompts/design-interface.md

@@ -0,0 +1,96 @@
+---
+name: design-interface
+description: "Generate multiple radically different interface designs for a module using parallel sub-agents, then compare trade-offs. Based on \"Design It Twice\" from A Philosophy of Software Design. Use when user wants to design an API, explore interface options, compare module shapes, or mentions \"design it twice\"."
+---
+
+# Design Interface
+
+Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare.
+
+> **HARD GATE** — Multiple design options must be explored. Do NOT settle on first idea. Compare trade-offs (UX, complexity, extensibility, performance) before committing.
+
+## Workflow
+
+### 1. Gather Requirements
+
+Before designing, understand:
+
+- [ ] What problem does this module solve?
+- [ ] Who are the callers? (other modules, external users, tests)
+- [ ] What are the key operations?
+- [ ] Any constraints? (performance, compatibility, existing patterns)
+- [ ] What should be hidden inside vs exposed?
+
+Ask: "What does this module need to do? Who will use it?"
+
+### 2. Generate Designs (Parallel Sub-Agents)
+
+Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach.
+
+```
+Prompt template for each sub-agent:
+
+Design an interface for: [module description]
+
+Requirements: [gathered requirements]
+
+Constraints for this design: [assign a different constraint to each agent]
+- Agent 1: "Minimize method count - aim for 1-3 methods max"
+- Agent 2: "Maximize flexibility - support many use cases"
+- Agent 3: "Optimize for the most common case"
+- Agent 4: "Take inspiration from [specific paradigm/library]"
+
+Output format:
+1. Interface signature (types/methods)
+2. Usage example (how caller uses it)
+3. What this design hides internally
+4. Trade-offs of this approach
+```
+
+### 3. Present Designs
+
+Show each design with:
+
+1. **Interface signature** — types, methods, params
+2. **Usage examples** — how callers actually use it in practice
+3. **What it hides** — complexity kept internal
+
+Present designs sequentially so user can absorb each approach before comparison.
+
+### 4. Compare Designs
+
+After showing all designs, compare them on:
+
+- **Interface simplicity**: fewer methods, simpler params
+- **General-purpose vs specialized**: flexibility vs focus
+- **Implementation efficiency**: does shape allow efficient internals?
+- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad)
+- **Ease of correct use** vs **ease of misuse**
+
+Discuss trade-offs in prose, not tables. Highlight where designs diverge most.
+
+### 5. Synthesize
+
+Often the best design combines insights from multiple options. Ask:
+
+- "Which design best fits your primary use case?"
+- "Any elements from other designs worth incorporating?"
+
+## Evaluation Criteria
+
+From "A Philosophy of Software Design":
+
+**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly.
+
+**General-purpose**: Can handle future use cases without changes. But beware over-generalization.
+
+**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals?
+
+**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid).
+
+## Anti-Patterns
+
+- Don't let sub-agents produce similar designs — enforce radical difference
+- Don't skip comparison — the value is in contrast
+- Don't implement — this is purely about interface shape
+- Don't evaluate based on implementation effort