agy-superpowers 5.0.6 → 5.0.8

package/README.md

@@ -130,6 +130,29 @@ This workflow will:
 
 ---
 
+## Configuration
+
+Per-project settings live in `.agent/config.yml`. Create or edit this file in your project's `.agent/` folder:
+
+```yaml
+# .agent/config.yml
+
+# auto_commit: true | false
+# When true (default), Superpowers skills automatically commit after completing
+# tasks and writing design docs.
+# When false, all git commits and staging are skipped — files are left as
+# modified for you to commit manually.
+auto_commit: true
+```
+
+| Setting | Default | Description |
+|---|---|---|
+| `auto_commit` | `true` | AI auto-commits after tasks and design docs. Set to `false` to skip all commits. |
+
+This file is preserved across `/update-superpowers` runs.
+
+---
+
 ## Installation
 
 ### Using This Repo in Your Project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-superpowers",
-  "version": "5.0.6",
+  "version": "5.0.8",
   "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
   "type": "module",
   "bin": {

package/template/agent/config.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/patches/skills-patches.md

@@ -0,0 +1,74 @@
+# Skill Patches
+
+Patches applied by AI during the `update-superpowers` workflow (Phase 2, Step 7).
+Each patch describes the *intent* of the change — AI finds the relevant section and rewrites it.
+Do not match text literally. Understand intent and adapt to current upstream wording.
+
+---
+
+## Patch: Platform Adaptation — using-superpowers
+
+**File:** `using-superpowers/SKILL.md`
+**Intent:** Remove all references to Claude Code, Gemini CLI, and Codex. Replace with a single
+Antigravity block: skills are read using `view_file` on `.agent/skills/<name>/SKILL.md`.
+Reference `references/antigravity-tools.md` for tool name mappings.
+The Platform Adaptation section should say this package is configured for Google Antigravity,
+with tool name equivalents in `references/antigravity-tools.md`.
+
+---
+
+## Patch: Platform mentions — executing-plans
+
+**File:** `executing-plans/SKILL.md`
+**Intent:** Replace any mentions of "Claude Code", "Codex", or other non-Antigravity platforms
+with "Antigravity". Example: "(such as Claude Code or Codex)" → "(such as Antigravity)".
+
+---
+
+## Patch: Skills path — writing-skills
+
+**File:** `writing-skills/SKILL.md`
+**Intent:** Replace platform-specific personal skill paths (`~/.claude/skills` for Claude Code,
+`~/.agents/skills/` for Codex) with the Antigravity path: `~/.agent/skills`.
+
+---
+
+## Patch: Visual companion platform blocks — brainstorming
+
+**File:** `brainstorming/visual-companion.md`
+**Intent:** Remove the Codex-specific server block. Replace Claude Code and Gemini CLI
+server startup blocks with a single Antigravity block:
+```bash
+# Launch the server normally
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+---
+
+## Patch: Platform comment — dispatching-parallel-agents
+
+**File:** `dispatching-parallel-agents/SKILL.md`
+**Intent:** Remove the comment `// In Claude Code / AI environment` (or similar platform-specific
+inline comments). The code should work without platform-specific annotations.
+
+---
+
+## Patch: auto_commit flag — brainstorming
+
+**File:** `brainstorming/SKILL.md`
+**Intent:** Make the step that commits the design document to git conditional on `.agent/config.yml`:
+- Read `.agent/config.yml` before committing
+- If `auto_commit: true` (default): commit normally with `git add <path> && git commit -m "docs: add <topic> design spec"`
+- If `auto_commit: false`: skip commit and staging entirely. Print: "Skipping commit (auto_commit: false in .agent/config.yml). File is ready for manual commit."
+
+---
+
+## Patch: auto_commit flag — subagent-driven-development
+
+**File:** `subagent-driven-development/SKILL.md`
+**Intent:** Make the implementer subagent commit step conditional on `.agent/config.yml`:
+- Read `.agent/config.yml` before committing
+- 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."
+Update any diagram labels that mention "commits" to reflect this conditionality
+(e.g. "commits (if auto_commit: true)").

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

@@ -0,0 +1,193 @@
+---
+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)

package/template/agent/skills/app-store-optimizer/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: app-store-optimizer
+description: Use when working on App Store / Google Play listing optimization, keyword strategy, screenshots, ratings, or app store A/B testing
+---
+
+# App Store Optimizer Lens
+
+> **Philosophy:** ASO is SEO for app stores. Discoverability + conversion = downloads.
+> Most apps lose 60%+ of potential downloads to a weak listing, not a weak product.
+
+---
+
+## Core Instincts
+
+- **Title keyword is the highest-ranking signal** — include your primary keyword in the title
+- **First 3 screenshots convert or kill** — most users never scroll past them
+- **Ratings velocity > average rating** — a burst of fresh 5-stars beats a stale 4.8
+- **Keyword field is invisible to users but critical to ranking** — use every character
+- **Localize for top markets** — EN + your top 3 markets = 80% of opportunity
+
+---
+
+## Platform Limits (Know These Cold)
+
+### iOS App Store
+| Field | Limit | Notes |
+|-------|-------|-------|
+| Title | **30 chars** | Primary keyword weight = 2× |
+| Subtitle | **30 chars** | Secondary keyword, benefit-focused |
+| Keywords | **100 chars** | Comma-separated, no spaces, no repeats from title |
+| Description | **4000 chars** | First **255 chars** shown before "more" |
+| Promo text | **170 chars** | Updates without review; use for time-limited offers |
+| Screenshots | Up to **10** | Sizes vary by device; first 3 drive 80% of conversion |
+| Preview video | **15–30 seconds** | First 3 seconds must hook without sound |
+
+### Google Play
+| Field | Limit | Notes |
+|-------|-------|-------|
+| Title | **30 chars** | Keyword-rich |
+| Short description | **80 chars** | Shown in search; make it scannable |
+| Long description | **4000 chars** | First 167 chars auto-expanded; repeat keyword 3–5× |
+| Screenshots | Up to **8** | 16:9 or 9:16 preferred |
+| Feature graphic | **1024 × 500px** | Shown in featured slots |
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| Title = just the brand name | Zero keyword signal | Brand + primary keyword (e.g., "Todoist: To-Do List & Tasks") |
+| Leave keywords field blank (iOS) | 100 chars of free ranking wasted | Fill every character with non-title keywords |
+| First screenshot = app logo splash | Users bounce, no context | First screenshot = core value prop as hero text |
+| Ask for review on first open | Users hate it, Apple rejects manipulative prompts | Ask after a success action (task completed, streak hit) |
+| Ignore 1-star reviews | Review responses shown publicly; silence = neglect | Respond within 48h; apologize + explain fix |
+| Use keywords that appear in title (iOS) | Apple ignores duplicates | Every keyword field word must be unique |
+| Generic description | No differentiation, no keywords | Keyword-rich first paragraph, benefit bullets |
+
+---
+
+## Keyword Research Process
+
+1. **Seed keywords** — brainstorm 20–30 relevant terms
+2. **Competitor analysis** — check top 5 competitor titles/subtitles
+3. **Volume + difficulty** — use Sensor Tower / AppTweak / AppFollow to score
+4. **Priority matrix** — High volume + Low difficulty = target first
+5. **Long-tail focus** — easier to rank for "meditation app for anxiety" than "meditation"
+6. **Update every 60–90 days** — track rank changes, iterate
+
+---
+
+## Ratings Strategy
+
+**When to prompt:** After user completes a meaningful success action, NOT on launch.
+- Good triggers: completed task, reached streak, finished session, saved something
+- Bad triggers: app open, screen view, after onboarding
+
+**Target benchmarks:**
+| Metric | Floor | Target |
+|--------|-------|--------|
+| Average rating | > 4.0 | > 4.5 |
+| Review count (for featuring) | > 100 | > 500 |
+| Response rate to 1-star | — | > 80% within 48h |
+
+**Recovering from bad ratings:** Respond to every 1-star, release fix quickly, request updated review from resolved users.
+
+---
+
+## Questions You Always Ask
+
+**When auditing a listing:**
+- Is the primary keyword in the title?
+- Do the first 3 screenshots tell a complete story without reading any text?
+- Is the keyword field 100% utilized (iOS)?
+- What's the current conversion rate from impression to download? (Benchmark: 3–7%)
+
+**When planning ASO strategy:**
+- Which markets are we localizing for?
+- What keywords are competitors ranking for that we're missing?
+- When was the last time we A/B tested screenshots?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] Title is brand name only (no keyword)
+- [ ] iOS keyword field < 90 characters used
+- [ ] First screenshot is a splash screen or abstract illustration
+- [ ] No response to 1-star reviews
+
+**Should fix:**
+- [ ] Description first 255 chars (iOS) / 167 chars (Play) not benefit-focused
+- [ ] No preview video
+- [ ] Listing not localized for top 3 markets
+
+---
+
+## Who to Pair With
+- `copywriter` — for listing copy strategy
+- `growth-hacker` — for launch burst strategy (ratings velocity)
+- `conversion-optimizer` — for screenshot A/B testing
+
+---
+
+## Tools
+AppFollow · Sensor Tower · AppTweak · AppFigures · MobileAction · Apple Search Ads Intelligence

package/template/agent/skills/auth-and-identity/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: auth-and-identity
+description: Use when implementing authentication, authorization, SSO/SAML/OIDC, multi-tenant identity, session management, or role-based access control for a SaaS product
+---
+
+# Auth & Identity Lens
+
+> **Philosophy:** Authentication proves who you are. Authorization proves what you can do.
+> Mixing them up is the most common source of privilege escalation bugs.
+
+---
+
+## Core Instincts
+
+- **AuthN ≠ AuthZ** — always handle them as separate concerns
+- **Every request must be authenticated AND authorized** — auth middleware is not authorization
+- **Tenant context must be established on every request** — after AuthN, before any DB query
+- **Fail closed** — when in doubt, deny; never default to permissive
+- **Never roll your own crypto** — use proven libraries and protocols
+
+---
+
+## Multi-Tenant Auth Flow
+
+```
+Request arrives →
+1. Verify token/session (AuthN) → get user_id
+2. Load user + tenant membership → get tenant_id, role
+3. Set tenant context (RLS / app context)
+4. Check permission for this route/resource (AuthZ)
+5. Execute request
+```
+
+**Order matters:** If you skip step 3, RLS doesn't know which tenant. If you skip step 4, any authenticated user can do anything.
+
+---
+
+## Auth Strategy Selection
+
+| Method | Best for | Not for |
+|--------|----------|---------|
+| **JWT (stateless)** | Stateless APIs, microservices | When you need instant revocation |
+| **Session cookie** | Web apps, SSR | Mobile-first or API-only |
+| **API key** | Machine-to-machine, developer APIs | User-facing login |
+| **SAML 2.0** | Enterprise SSO (Okta, Azure AD) | Consumer apps |
+| **OIDC / OAuth 2.0** | Social login, federated identity | Internal-only systems |
+
+**Indie hacker default:** Session cookies for web (HttpOnly, Secure, SameSite=Strict) + JWT for API endpoints.
+
+---
+
+## JWT Rules
+
+```
+Access token:
+- Expiry: 15 minutes (short-lived; compromised → limited damage window)
+- Payload: user_id, tenant_id, role, exp — NO sensitive data
+- Store: Memory (never localStorage) or HttpOnly cookie
+
+Refresh token:
+- Expiry: 7–30 days
+- Store: HttpOnly cookie ONLY
+- Rotate on every use (refresh token rotation)
+- Invalidate all refresh tokens on password change/logout all
+
+Signing:
+- Algorithm: RS256 (asymmetric, allows public verification) or HS256 (simpler, shared secret)
+- Secret: ≥ 32 random bytes; rotate if compromised (support multiple valid secrets during rotation)
+```
+
+---
+
+## RBAC Pattern (Role-Based Access Control)
+
+```typescript
+// Roles per tenant membership (not global)
+type TenantRole = 'owner' | 'admin' | 'member' | 'viewer';
+
+// Permissions defined as capability strings
+const PERMISSIONS = {
+  owner:  ['billing:manage', 'members:manage', 'data:delete', 'data:write', 'data:read'],
+  admin:  ['members:manage', 'data:write', 'data:read'],
+  member: ['data:write', 'data:read'],
+  viewer: ['data:read'],
+} satisfies Record<TenantRole, string[]>;
+
+// Check at every protected route/action
+function can(user: User, permission: string): boolean {
+  return PERMISSIONS[user.tenantRole]?.includes(permission) ?? false;
+}
+```
+
+---
+
+## SSO / SAML Integration (Enterprise)
+
+```
+When to build SAML:
+- Enterprise customers require it (Okta, Azure AD, Google Workspace)
+- Single "SAML" request in a deal is worth building immediately
+
+Implementation options for indie hackers:
+1. WorkOS — $0 to start, pay per enterprise connection; fastest path
+2. Auth0 / Clerk — SAML add-on; higher cost at scale
+3. Roll your own — samlify / passport-saml; significant complexity
+
+SAML Flow:
+  User → Your SP (Service Provider) → IdP (Okta/AzureAD) → SAML assertion → SP → Session
+```
+
+---
+
+## ❌ Anti-Patterns to Avoid
+
+| ❌ NEVER DO | Why | ✅ DO INSTEAD |
+|------------|-----|--------------|
+| JWT in `localStorage` | XSS attack steals token, unlimited access | `HttpOnly` cookie |
+| Long-lived access tokens (> 1 hour) | Compromised token = long exposure window | 15 min expiry + refresh token rotation |
+| Storing passwords as anything but bcrypt/argon2id | Rainbow table crack in seconds | bcrypt cost ≥12 or argon2id |
+| Checking auth at route level only | Bypassed by internal calls | Check permissions at the service/data layer |
+| Global admin role without per-tenant scope | One compromised admin = all tenants affected | Admin role always scoped to a tenant |
+| No rate limiting on auth endpoints | Brute force, credential stuffing | Max 5 attempts / 15 min per IP |
+| Email as unique identifier across tenants | Same email in multiple tenants = collision | `(email, tenant_id)` composite unique |
+
+---
+
+## Questions You Always Ask
+
+**When designing auth:**
+- Is tenant context established before any DB query happens?
+- Does AuthZ happen at the service layer, not just route middleware?
+- Are refresh tokens rotated on every use?
+- What's the logout flow? Does it invalidate server-side session/refresh token?
+
+**When adding a new role or permission:**
+- Is this the least privilege needed for this action?
+- Have we tested that a lower-privileged role cannot access this?
+
+---
+
+## Red Flags
+
+**Must fix:**
+- [ ] JWT stored in `localStorage`
+- [ ] No tenant_id in auth context (tenant isolation can't work)
+- [ ] Authorization only checked at route level (not service/data layer)
+- [ ] No rate limiting on `/login`, `/forgot-password`, `/reset-password`
+
+**Should fix:**
+- [ ] Refresh tokens not rotated on use
+- [ ] No MFA option for admin/owner roles
+- [ ] Email uniqueness checked globally (not per-tenant)
+
+---
+
+## Who to Pair With
+- `saas-architect` — for tenant context in data model
+- `security-engineer` — for token storage and auth security audit
+- `backend-developer` — for middleware and session management
+
+---
+
+## Tools
+**Hosted auth:** Clerk · Auth0 · Supabase Auth · Firebase Auth  
+**Self-hosted:** NextAuth.js / Auth.js · Lucia · Better Auth  
+**Enterprise SSO:** WorkOS · Boxyhq (open source)  
+**Libraries:** `jose` (JWT) · `bcrypt` / `argon2` (passwords) · `samlify` (SAML)