agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/subagent-driven-development/SKILL.md

@@ -32,6 +32,7 @@ digraph when_to_use {
 ```
 
 **vs. Executing Plans (parallel session):**
+
 - Same session (no context switch)
 - Fresh subagent per task (no context pollution)
 - Two-stage review after each task: spec compliance first, then code quality
@@ -95,6 +96,7 @@ Use the least powerful model that can handle each role to conserve cost and incr
 **Architecture, design, and review tasks**: use the most capable available model.
 
 **Task complexity signals:**
+
 - Touches 1-2 files with a complete spec → cheap model
 - Touches multiple files with integration concerns → standard model
 - Requires design judgment or broad codebase understanding → most capable model
@@ -110,6 +112,7 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 **NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
 
 **BLOCKED:** The implementer cannot complete the task. Assess the blocker:
+
 1. If it's a context problem, provide more context and re-dispatch with the same model
 2. If the task requires more reasoning, re-dispatch with a more capable model
 3. If the task is too large, break it into smaller pieces
@@ -202,23 +205,27 @@ Done!
 ## Advantages
 
 **vs. Manual execution:**
+
 - Subagents follow TDD naturally
 - Fresh context per task (no confusion)
 - Parallel-safe (subagents don't interfere)
 - Subagent can ask questions (before AND during work)
 
 **vs. Executing Plans:**
+
 - Same session (no handoff)
 - Continuous progress (no waiting)
 - Review checkpoints automatic
 
 **Efficiency gains:**
+
 - No file reading overhead (controller provides full text)
 - Controller curates exactly what context is needed
 - Subagent gets complete information upfront
 - Questions surfaced before work begins (not after)
 
 **Quality gates:**
+
 - Self-review catches issues before handoff
 - Two-stage review: spec compliance, then code quality
 - Review loops ensure fixes actually work
@@ -226,6 +233,7 @@ Done!
 - Code quality ensures implementation is well-built
 
 **Cost:**
+
 - More subagent invocations (implementer + 2 reviewers per task)
 - Controller does more prep work (extracting all tasks upfront)
 - Review loops add iterations
@@ -234,6 +242,7 @@ Done!
 ## Red Flags
 
 **Never:**
+
 - Start implementation on main/master branch without explicit user consent
 - Skip reviews (spec compliance OR code quality)
 - Proceed with unfixed issues
@@ -248,35 +257,42 @@ Done!
 - Move to next task while either review has open issues
 
 **Before implementer commits:** Check `.agent/config.yml` for `auto_commit` setting.
+
 - If `auto_commit: true` (default): commit normally with `git add` + `git commit`
 - If `auto_commit: false`: skip commit and staging entirely. Print: "Skipping commit (auto_commit: false in .agent/config.yml). Files left as modified for manual commit."
 
 **If subagent asks questions:**
+
 - Answer clearly and completely
 - Provide additional context if needed
 - Don't rush them into implementation
 
 **If reviewer finds issues:**
+
 - Implementer (same subagent) fixes them
 - Reviewer reviews again
 - Repeat until approved
 - Don't skip the re-review
 
 **If subagent fails task:**
+
 - Dispatch fix subagent with specific instructions
 - Don't try to fix manually (context pollution)
 
 ## Integration
 
 **Required workflow skills:**
+
 - **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:requesting-code-review** - Code review template for reviewer subagents
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks
 
 **Subagents should use:**
+
 - **superpowers:test-driven-development** - Subagents follow TDD for each task
 - **Domain skills matching the task context** - e.g. `mobile-developer` for React Native work, `backend-developer` for API work, `frontend-developer` for web UI. Include only the relevant SKILL.md in the implementer prompt context; load specific references on demand as the task requires them.
 
 **Alternative workflow:**
+
 - **superpowers:executing-plans** - Use for parallel session instead of same-session execution

package/template/agent/skills/subagent-driven-development/implementer-prompt.md

@@ -28,13 +28,14 @@ Task tool (general-purpose):
 
     ## Your Job
 
+    Once you're clear on requirements:
     1. Implement exactly what the task specifies
     2. Write tests (following TDD if task says to)
     3. Verify implementation works
     4. Commit your work (if auto_commit is enabled)
-       - Read `.agent/config.yml` to check the `auto_commit` setting
-       - If `auto_commit: true` (or not set): `git add` changed files + `git commit`
-       - If `auto_commit: false`: skip commit and staging entirely. Print: "Skipping commit (auto_commit: false in .agent/config.yml). Files left as modified for manual commit."
+       - Read `.agent/config.yml` — check `auto_commit` setting
+       - If `auto_commit: true` (or not set): `git add` + `git commit`
+       - If `auto_commit: false`: skip commit and staging entirely, print "Skipping commit (auto_commit: false)."
     5. Self-review (see below)
     6. Report back
 

package/template/agent/skills/using-git-worktrees/SKILL.md

@@ -63,9 +63,10 @@ git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/d
 
 Per Jesse's rule "Fix broken things immediately":
 1. Add appropriate line to .gitignore
-2. Commit the change (if auto_commit enabled)
-   - Read `.agent/config.yml` — if `auto_commit: false`: skip commit, print "Skipping git operation (auto_commit: false)."
+2. Commit the change (if `auto_commit` is enabled):
+   - Read `.agent/config.yml` — check `auto_commit` setting
    - If `auto_commit: true` (or absent): `git add .gitignore && git commit -m "chore: ignore worktree directory"`
+   - If `auto_commit: false`: skip commit, print "Skipping git operation (auto_commit: false)."
 3. Proceed with worktree creation
 
 **Why critical:** Prevents accidentally committing worktree contents to repository.

package/template/agent/skills/using-superpowers/SKILL.md

@@ -19,21 +19,23 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou
 
 Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
 
-1. **User's explicit instructions** (GEMINI.md, AGENTS.md, direct requests) — highest priority
+1. **User's explicit instructions** (direct requests, project config) — highest priority
 2. **Superpowers skills** — override default system behavior where they conflict
 3. **Default system prompt** — lowest priority
 
-If GEMINI.md or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+If the user says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
 
 ## How to Access Skills
 
-**In Antigravity:** Use `view_file` on `.agent/skills/<skill-name>/SKILL.md` to read a skill. Skills are detected automatically from their `description` field.
+Use `view_file` on the skill's `SKILL.md`:
+```
+.agent/skills/<skill-name>/SKILL.md
+```
+Example: `.agent/skills/brainstorming/SKILL.md`
 
 ## Platform Adaptation
 
-This package is configured for **Google Antigravity**. Tool name mappings are handled automatically via `GEMINI.md` in your workspace.
-
-For tool name equivalents, see `references/antigravity-tools.md`.
+This package is configured for **Google Antigravity**. Tool name equivalents are documented in `references/antigravity-tools.md`.
 
 # Using Skills
 

package/template/agent/skills/using-superpowers/references/copilot-tools.md

@@ -0,0 +1,52 @@
+# Copilot CLI Tool Mapping
+
+Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
+
+| Skill references | Copilot CLI equivalent |
+|-----------------|----------------------|
+| `Read` (file reading) | `view` |
+| `Write` (file creation) | `create` |
+| `Edit` (file editing) | `edit` |
+| `Bash` (run commands) | `bash` |
+| `Grep` (search file content) | `grep` |
+| `Glob` (search files by name) | `glob` |
+| `Skill` tool (invoke a skill) | `skill` |
+| `WebFetch` | `web_fetch` |
+| `Task` tool (dispatch subagent) | `task` (see [Agent types](#agent-types)) |
+| Multiple `Task` calls (parallel) | Multiple `task` calls |
+| Task status/output | `read_agent`, `list_agents` |
+| `TodoWrite` (task tracking) | `sql` with built-in `todos` table |
+| `WebSearch` | No equivalent — use `web_fetch` with a search engine URL |
+| `EnterPlanMode` / `ExitPlanMode` | No equivalent — stay in the main session |
+
+## Agent types
+
+Copilot CLI's `task` tool accepts an `agent_type` parameter:
+
+| Claude Code agent | Copilot CLI equivalent |
+|-------------------|----------------------|
+| `general-purpose` | `"general-purpose"` |
+| `Explore` | `"explore"` |
+| Named plugin agents (e.g. `superpowers:code-reviewer`) | Discovered automatically from installed plugins |
+
+## Async shell sessions
+
+Copilot CLI supports persistent async shell sessions, which have no direct Claude Code equivalent:
+
+| Tool | Purpose |
+|------|---------|
+| `bash` with `async: true` | Start a long-running command in the background |
+| `write_bash` | Send input to a running async session |
+| `read_bash` | Read output from an async session |
+| `stop_bash` | Terminate an async session |
+| `list_bash` | List all active shell sessions |
+
+## Additional Copilot CLI tools
+
+| Tool | Purpose |
+|------|---------|
+| `store_memory` | Persist facts about the codebase for future sessions |
+| `report_intent` | Update the UI status line with current intent |
+| `sql` | Query the session's SQLite database (todos, metadata) |
+| `fetch_copilot_cli_documentation` | Look up Copilot CLI documentation |
+| GitHub MCP tools (`github-mcp-server-*`) | Native GitHub API access (issues, PRs, code search) |

package/template/agent/skills/writing-plans/SKILL.md

@@ -97,13 +97,15 @@ Expected: PASS
 
 - [ ] **Step 5: Commit (if auto_commit enabled)**
 
-Check `.agent/config.yml` for `auto_commit` setting:
-- If `auto_commit: true` (default):
+Check `.agent/config.yml` for `auto_commit` setting.
+
+If `auto_commit: true` (default when absent):
 ```bash
 git add tests/path/test.py src/path/file.py
 git commit -m "feat: add specific feature"
 ```
-- If `auto_commit: false`: skip commit and staging. Print: "Skipping commit (auto_commit: false)."
+
+If `auto_commit: false`: skip commit and staging. Print: "Skipping commit (auto_commit: false)."
 ````
 
 ## No Placeholders

package/template/agent/skills/writing-skills/SKILL.md

@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
 
-**Personal skills live in agent-specific directories (`~/.agent/skills` for Antigravity)** 
+**Personal skills live in `~/.agent/skills`** 
 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
 

package/template/agent/superpowers-version.json

@@ -1,5 +1,5 @@
 {
-  "tag": "v5.0.6",
-  "updated_at": "2026-03-28T11:32:19Z",
+  "tag": "v5.0.7",
+  "updated_at": "2026-04-02T12:29:10Z",
   "source": "https://github.com/obra/superpowers"
 }

package/template/agent/tmp/agent-config-backup.yml

@@ -0,0 +1,9 @@
+# Antigravity Superpowers — Project Config
+#
+# Configure per-project behavior by editing this file.
+# Skills read this file to determine how to behave in this project.
+
+# auto_commit: true | false
+# When true (default), AI automatically commits after completing tasks and writing design docs.
+# When false, all git commits and staging are skipped; files are left as modified for manual commit.
+auto_commit: false

package/template/agent/skills/ai-integrated-product/SKILL.md

@@ -1,57 +0,0 @@
----
-name: ai-integrated-product
-description: Use when integrating AI/LLM capabilities into a product, building AI-powered features, or evaluating APIs
----
-
-# AI Integrated Product Lens
-
-## Identity
-You are pragmatic about AI. You view LLMs as unreliable but powerful probabilistic engines, not magic. You focus on cost control, useful constraints, and graceful degradation when the AI inevitably hallucinates or the API goes down.
-
-## Core Instincts
-- **AI is a feature, not a product** — the underlying workflow must provide value; AI just accelerates it
-- **Cost control from day 1** — LLM API costs scale with usage; if you don't limit tokens, you will lose money
-- **UX > Model capabilities** — a great UI wrapped around a fast, cheap model (GPT-4o-mini) beats a clunky UI block-awaiting an expensive model (GPT-4o)
-- **Trust but verify** — users need to be able to edit, undo, or reject AI outputs
-
-## Core Knowledge
-
-**AI API Landscape for Indie (2025-2026):**
-- **OpenAI (GPT-4o, GPT-4o-mini):** Best general-purpose, predictable JSON modes.
-- **Anthropic (Claude 3.5 Sonnet):** Exceptional for coding, long context, and nuanced writing.
-- **Google (Gemini 2.0 Flash):** Incredible pricing and multimodal speed.
-- **Open-source (Llama/Mistral via Together/Groq):** Cheapest at scale, fastest inference.
-
-**Cost Benchmarks (Approx input/output per 1M tokens):**
-- GPT-4o-mini: $0.15 / $0.60
-- GPT-4o: $2.50 / $10.00
-- Claude 3.5 Sonnet: $3.00 / $15.00
-- Gemini 2.0 Flash: $0.10 / $0.40
-
-**Cost Management Strategies:**
-- Estimate tokens per request before calling the API.
-- Set hard usage caps per user tier.
-- Cache common responses (exact or semantic caching).
-- Use cheaper models (Flash/Mini) for routing/classification, save expensive models for complex generation.
-
-**Feature Patterns:**
-- Text generation/summarization (Drafting assistants)
-- Conversational UI (Support bots)
-- Classification/tagging (Sorting incoming data)
-- Data extraction (Converting messy HTML/text into clean JSON)
-
-**Prompt Engineering Basics:**
-- Deeply specific system prompts.
-- Few-shot examples (give it 3 good inputs + outputs).
-- Always use structured output (JSON schema) when parsing programmatically.
-
-## Questions You Always Ask
-- Can we use a cheaper model (like Gemini Flash or GPT-4o-mini) for this specific task?
-- What is the UI/UX when the API takes 5 seconds to respond?
-- How are we capping usage so a single enthusiastic user doesn't cost us $50 today?
-
-## Red Flags / Anti-Patterns
-- [ ] Passing user input directly to an expensive model without a rate limit
-- [ ] Relying on the AI to perform complex math or exact character counts
-- [ ] No fallback state for when the API times out
-- [ ] "Building a ChatGPT wrapper" with no distinct workflow advantage

package/template/agent/skills/analytics-setup/SKILL.md

@@ -1,51 +0,0 @@
----
-name: analytics-setup
-description: Use when setting up analytics, choosing tracking tools, or designing a metrics dashboard for an indie product
----
-
-# Analytics Setup Lens
-
-## Identity
-You focus on actionable metrics over vanity numbers. You prefer privacy-first, lightweight tracking over heavy, enterprise-grade suites. You want to understand the user journey without invading their privacy or blowing the indie budget.
-
-## Core Instincts
-- **Track what matters, ignore the rest** — event bloat kills data utility
-- **Privacy first** — if you don't need user-level tracking, use aggregate tools
-- **Different questions need different tools** — product analytics ≠ web analytics ≠ error tracking
-- **Cohorts over totals** — "Total Users" is a vanity metric; "D7 Retention by Week" is actionable
-
-## Core Knowledge
-
-**Analytics Stack for Indie (Budget-Friendly):**
-- **Web Analytics (Marketing):** Plausible ($9/mo, privacy-first) or Umami (free self-hosted). Avoid Google Analytics unless required by an ad platform.
-- **Product Analytics (In-App):** PostHog (generous free tier, all-in-one) or Mixpanel (free up to 20M events).
-- **Error Tracking:** Sentry (free tier: 5K events/mo) or BugSnag.
-- **Uptime:** BetterUptime free tier or UptimeRobot.
-
-**Essential Events to Track (Day 1):**
-- **Web/SaaS:** `signup`, `activation` (the "Aha!" moment), `feature_used` (top 3 core features), `upgrade_started`, `payment_completed`, `churned`.
-- **Mobile:** `app_opened`, `session_duration`, `notification_opened`, `iap_initiated`.
-- **Extension:** `installed`, `extension_opened`, `upgraded`.
-
-**Implementation Patterns:**
-- **Naming convention:** `noun_verb` (e.g., `subscription_started`). Be strictly consistent.
-- **User properties:** plan type, signup_date, platform. Attach these to the user profile, not every event.
-- **Group analytics by cohort:** Weekly signup cohorts are the best way to measure improvements over time.
-
-**Dashboard Template (The 5 Metrics That Matter):**
-1. Daily/Weekly Active Users (DAU/WAU)
-2. Activation Rate (% reaching the aha moment)
-3. Retention (D1, D7, D30)
-4. Revenue (MRR, trial-to-paid conversion rate)
-5. Acquisition source breakdown
-
-## Questions You Always Ask
-- What is the ONE primary metric for this product?
-- How are we defining an "Active" user? (Hint: it shouldn't just be "logging in")
-- Have we set a strict naming convention for our events before we start writing `track()` calls?
-
-## Red Flags / Anti-Patterns
-- [ ] Tracking every single button click ("event bloat")
-- [ ] No tracking at all on V1 ("I'll add analytics later")
-- [ ] Using vanity metrics (page views, total registered accounts without filtering for activation)
-- [ ] No consistent event naming convention

package/template/agent/skills/api-design/SKILL.md

@@ -1,193 +0,0 @@
----
-name: api-design
-description: Use when designing REST or GraphQL APIs, defining versioning strategy, implementing rate limiting, pagination, or writing API documentation
----
-
-# API Design Lens
-
-> **Philosophy:** An API is a contract. Breaking it breaks your users' production systems.
-> Design APIs for the client's needs, not the server's convenience.
-
----
-
-## Core Instincts
-
-- **API contracts are forever** — breaking changes in v1 are unforgivable; version aggressively
-- **Design for the consumer** — the client's workflow, not the server's data model, drives resource design
-- **Idempotency is non-negotiable** — safe to retry = safe to build reliable systems on top of
-- **Errors must be informative** — vague errors waste developer hours
-- **Consistency over cleverness** — a boring, predictable API is a beloved API
-
----
-
-## REST Resource Design Rules
-
-```
-Resource naming:
-  ✅ /users/{id}/projects          (noun, plural, hierarchical)
-  ❌ /getProjectsForUser/{id}      (verb, confusing)
-  ❌ /user-projects/{userId}       (mixed conventions)
-
-HTTP verbs:
-  GET    /resources        → list (paginated)
-  GET    /resources/{id}   → get one
-  POST   /resources        → create
-  PUT    /resources/{id}   → full replace (idempotent)
-  PATCH  /resources/{id}   → partial update
-  DELETE /resources/{id}   → delete (idempotent)
-
-Idempotency:
-  GET, PUT, DELETE = always idempotent
-  POST = not idempotent by default → use Idempotency-Key header
-```
-
----
-
-## HTTP Status Codes (Precise Usage)
-
-| Status | Use when | Body |
-|--------|----------|------|
-| 200 | Success, returns data | Resource |
-| 201 | Created | Resource + `Location` header |
-| 204 | Success, no body | Empty |
-| 400 | Malformed request / validation failure | Error with field details |
-| 401 | Missing or invalid auth | Error |
-| 403 | Auth valid, no permission | Error (don't reveal resource existence) |
-| 404 | Resource not found | Error |
-| 409 | Conflict (duplicate, state clash) | Error with conflict detail |
-| 422 | Valid format, business rule violation | Error with reason |
-| 429 | Rate limited | Error + `Retry-After` header |
-| 500 | Unexpected server error | Generic error (log full details server-side) |
-
----
-
-## Error Response Standard (RFC 7807 / Problem Details)
-
-```json
-{
-  "type": "https://docs.myapp.com/errors/validation-failed",
-  "title": "Validation Failed",
-  "status": 422,
-  "detail": "One or more fields are invalid",
-  "errors": [
-    { "field": "email", "message": "Must be a valid email address" },
-    { "field": "name",  "message": "Required" }
-  ],
-  "requestId": "01HX7Y3Z..."
-}
-```
-
-**Always include `requestId`** — allows support to find logs immediately.
-
----
-
-## Pagination
-
-```
-Offset-based (simple, less scalable):
-  GET /users?page=2&limit=20
-  ✅ Good for: admin UIs, small datasets
-  ❌ Bad for: large datasets (OFFSET N scans N rows)
-
-Cursor-based (scalable, real-time safe):
-  GET /users?cursor=eyJpZCI6MTIzfQ&limit=20
-  Response: { data: [...], nextCursor: "eyJpZCI6MTQzfQ", hasMore: true }
-  ✅ Good for: feeds, large datasets, infinite scroll
-  ❌ Bad for: jump-to-page UI
-
-Default recommendation: Cursor-based with opaque base64 cursors.
-Expose total count only when necessary (expensive for large tables).
-```
-
----
-
-## Rate Limiting
-
-```
-Strategy: Token bucket or sliding window
-
-Headers to include:
-  X-RateLimit-Limit:     1000    (max requests per window)
-  X-RateLimit-Remaining: 847     (requests left)
-  X-RateLimit-Reset:     1711234567  (Unix timestamp when window resets)
-  Retry-After:           60      (seconds to wait, on 429 only)
-
-Recommended limits for SaaS APIs:
-  Authenticated:   1000 req/min per user
-  Unauthenticated: 60 req/min per IP
-  Sensitive (auth endpoints): 5 req/15min per IP
-```
-
----
-
-## API Versioning
-
-```
-Strategy options:
-  URL versioning:    /v1/users   ← RECOMMENDED (explicit, cacheable)
-  Header versioning: Accept: application/vnd.myapp.v1+json  (less visible)
-  Query param:       /users?version=1  (ugly, cache issues)
-
-Breaking vs non-breaking changes:
-  Non-breaking (safe without versioning):
-    ✅ Adding new optional fields to response
-    ✅ Adding new optional request parameters
-    ✅ Adding new endpoints
-  
-  Breaking (requires new version):
-    ❌ Removing fields from response
-    ❌ Changing field types
-    ❌ Changing endpoint behavior
-    ❌ Renaming fields
-```
-
----
-
-## ❌ Anti-Patterns to Avoid
-
-| ❌ NEVER DO | Why | ✅ DO INSTEAD |
-|------------|-----|--------------|
-| Return 200 for errors | Clients parse status codes; 200 failure = broken integrations | Use correct status codes |
-| Expose internal IDs (auto-increment integers) | Enumerable, leaks count of records | UUIDs always |
-| Breaking changes without versioning | Clients' production breaks silently | `/v2/` or deprecation period |
-| Unbounded list endpoints | OOM at scale | Always paginate; default limit 20, max 100 |
-| Verbose errors in production | Leaks internals to attackers | Generic message to client; details in server logs only |
-| Synchronous long-running operations | Timeout at 30s+, bad UX | Accept → 202 Accepted → polling or webhook |
-
----
-
-## Questions You Always Ask
-
-**When designing a new endpoint:**
-- Is this resource name a noun (not a verb)?
-- What's the idempotency story? Can the client safely retry?
-- What's the pagination strategy? What's the max page size?
-- Is this a breaking change to existing consumers?
-
----
-
-## Red Flags
-
-**Must fix:**
-- [ ] `200 OK` returned for error responses
-- [ ] No pagination on list endpoints
-- [ ] Auto-increment integer IDs exposed
-- [ ] Breaking API change without version bump
-
-**Should fix:**
-- [ ] No rate limiting on public endpoints
-- [ ] Error responses without field-level details
-- [ ] No `requestId` in error responses (prevents support lookup)
-- [ ] No OpenAPI/Swagger spec
-
----
-
-## Who to Pair With
-- `backend-developer` — for implementation of API patterns
-- `auth-and-identity` — for auth design on API endpoints
-- `saas-architect` — for multi-tenant API context
-
----
-
-## Tools
-OpenAPI / Swagger (spec) · Scalar / Stoplight (docs) · Hono / Fastify / Express (Node.js) · Zod / Joi (validation) · `express-rate-limit` / Upstash Rate Limit · Postman / Insomnia (testing)