agy-superpowers 5.0.8 → 5.1.0

package/README.md

@@ -1,5 +1,8 @@
 # antigravity-superpowers
 
+[![npm version](https://img.shields.io/npm/v/agy-superpowers.svg)](https://www.npmjs.com/package/agy-superpowers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
 > **Superpowers for [Google Antigravity](https://antigravity.google)** — a complete development workflow powered by composable skills, workflows, and rules.
 
 
@@ -39,36 +42,31 @@ agy-superpowers init
 ## What's Inside
 
 ```
-antigravity-superpowers/
-├── .agent/
-│   ├── rules/
-│   │   └── superpowers.md        # Always-on rule: agent checks skills before acting
-│   ├── skills/                   # Symlinks → superpowers/skills/*
-│   │   ├── brainstorming/
-│   │   ├── writing-plans/
-│   │   ├── executing-plans/
-│   │   ├── subagent-driven-development/
-│   │   ├── test-driven-development/
-│   │   ├── systematic-debugging/
-│   │   ├── verification-before-completion/
-│   │   ├── requesting-code-review/
-│   │   ├── receiving-code-review/
-│   │   ├── using-git-worktrees/
-│   │   ├── finishing-a-development-branch/
-│   │   ├── dispatching-parallel-agents/
-│   │   ├── writing-skills/
-│   │   └── using-superpowers/
-│   ├── workflows/
-│   │   ├── brainstorm.md         # /brainstorm
-│   │   ├── write-plan.md         # /write-plan
-│   │   ├── execute-plan.md       # /execute-plan
-│   │   ├── code-review.md        # /code-review
-│   │   ├── debug.md              # /debug
-│   │   └── update-superpowers.md # /update-superpowers
-│   └── .shared/
-│       └── update-superpowers.sh # Shell script for version management
-└── superpowers/                  # Upstream source (git-managed)
-    └── skills/                   # All skill SKILL.md files live here
+.agent/
+├── rules/
+│   └── superpowers.md          # Always-on rule: agent checks skills before acting
+├── skills/                     # 44 skills (patched from upstream)
+│   ├── brainstorming/
+│   ├── writing-plans/
+│   ├── executing-plans/
+│   ├── backend-developer/
+│   ├── frontend-developer/
+│   ├── mobile-developer/
+│   ├── growth-hacker/
+│   ├── monetization-strategist/
+│   └── ...                     # + 36 more skills
+├── workflows/
+│   ├── brainstorm.md           # /brainstorm
+│   ├── write-plan.md           # /write-plan
+│   ├── execute-plan.md         # /execute-plan
+│   ├── code-review.md          # /code-review
+│   ├── debug.md                # /debug
+│   ├── publish.md              # /publish
+│   └── update-superpowers.md   # /update-superpowers
+├── patches/
+│   └── skills-patches.md       # AI-driven skill patches (see below)
+└── .shared/
+    └── update-superpowers.sh   # Shell script for version management
 ```
 
 ---
@@ -91,25 +89,75 @@ antigravity-superpowers/
 | 4    | `/code-review`  | Pre-review checklist, severity-based issue reporting           |
 | 5    | _(auto)_        | `finishing-a-development-branch` — merge / PR / discard        |
 
+### Additional Workflows
+
+| Workflow              | What happens                                                 |
+| --------------------- | ------------------------------------------------------------ |
+| `/debug`              | Systematic 4-phase debugging process                         |
+| `/publish`            | Publish to npm with version bump, git tag, and push          |
+| `/update-superpowers` | Pull latest upstream release, re-sync skills, AI-rewrite rules |
+
+---
+
+## AI-Driven Skill Patching
+
+Skills are sourced from upstream Superpowers but automatically patched to be Antigravity-native. The patching system uses a human-readable spec at `.agent/patches/skills-patches.md` which the AI interprets semantically — making patches resilient to upstream changes.
+
+When you run `/update-superpowers`, skills are:
+1. Copied fresh from `superpowers/skills/`
+2. Patched via AI to remove non-Antigravity references
+3. Ready to use immediately
+
 ---
 
 ## Skills Reference
 
-| Skill                            | Triggers automatically when...                                       |
-| -------------------------------- | -------------------------------------------------------------------- |
-| `brainstorming`                  | You're adding a feature, building a component, or modifying behavior |
-| `writing-plans`                  | Design is approved — breaking work into tasks                        |
-| `executing-plans`                | Running a plan step-by-step with checkpoints                         |
-| `subagent-driven-development`    | Dispatching subagents per task with two-stage review                 |
-| `test-driven-development`        | During ALL implementation (RED → GREEN → REFACTOR)                   |
-| `systematic-debugging`           | Debugging any issue                                                  |
-| `verification-before-completion` | Before declaring a fix or task done                                  |
-| `requesting-code-review`         | Before submitting code for review                                    |
-| `receiving-code-review`          | Responding to review feedback                                        |
-| `using-git-worktrees`            | Starting work on a new isolated branch                               |
-| `finishing-a-development-branch` | When tasks are complete                                              |
-| `dispatching-parallel-agents`    | Running concurrent subagent workflows                                |
-| `writing-skills`                 | Creating a new skill                                                 |
+| Skill | Triggers automatically when... |
+| ----- | ------------------------------ |
+| `api-design` | Designing REST or GraphQL APIs, versioning, rate limiting, pagination, or API docs |
+| `app-store-optimizer` | Working on App Store / Google Play listing optimization, keyword strategy, or A/B testing |
+| `auth-and-identity` | Implementing authentication, authorization, SSO/SAML/OIDC, session management, or RBAC |
+| `backend-developer` | Designing APIs, server-side logic, database schemas, or reviewing backend code |
+| `brainstorming` | Adding a feature, building a component, or modifying behavior |
+| `community-manager` | Building and managing communities on Discord, Reddit, Slack, or social platforms |
+| `content-marketer` | Planning content strategy, SEO content, social media, or email newsletters |
+| `conversion-optimizer` | Optimizing landing pages, trial-to-paid funnels, paywall design, or onboarding flows |
+| `copywriter` | Writing landing page copy, app store descriptions, email sequences, or user-facing text |
+| `cto-architect` | Making system design decisions, managing tech debt, planning for scale |
+| `customer-success-manager` | Managing user support, feedback loops, NPS/CSAT tracking, or handling churn |
+| `data-analyst` | Setting up metrics, analyzing funnels, cohort analysis, dashboards, or A/B test results |
+| `devops-engineer` | Working on CI/CD pipelines, infrastructure, deployment, monitoring, or reliability |
+| `dispatching-parallel-agents` | Facing 2+ independent tasks that can run without shared state |
+| `email-infrastructure` | Setting up transactional email, deliverability, SPF/DKIM/DMARC, or email templates |
+| `executing-plans` | Running a plan step-by-step with checkpoints |
+| `finishing-a-development-branch` | Implementation is complete and you need to merge / PR / discard |
+| `frontend-developer` | Building web UI, component architecture, or reviewing frontend code |
+| `game-design` | Designing game mechanics, core loops, progression, monetization, or difficulty curves |
+| `game-developer` | Working on game app features, reviewing game code, or game architecture decisions |
+| `growth-hacker` | Planning user acquisition, viral loops, activation funnels, or growth experiments |
+| `i18n-localization` | Planning i18n architecture, localizing for new markets, or managing translations |
+| `influencer-marketer` | Planning UGC campaigns, creator partnerships, TikTok/YouTube/Instagram marketing |
+| `mobile-developer` | Working on mobile app features, reviewing mobile code, or mobile architecture |
+| `monetization-strategist` | Designing pricing models, freemium strategy, IAP, or modeling unit economics |
+| `paid-acquisition-specialist` | Running Meta Ads, Google Ads, Apple Search Ads, or any paid acquisition channel |
+| `product-manager` | Defining requirements, prioritizing features, planning roadmaps, or validating problems |
+| `real-time-features` | Implementing WebSockets, SSE, live collaboration, or real-time notifications |
+| `receiving-code-review` | Receiving code review feedback, before implementing suggestions |
+| `requesting-code-review` | Completing tasks or before merging to verify work meets requirements |
+| `retention-specialist` | Improving user retention, reducing churn, analyzing engagement, or re-engagement |
+| `saas-architect` | Designing multi-tenant SaaS architecture, tenant isolation, or data models |
+| `security-engineer` | Reviewing app security, handling user data, ensuring GDPR/App Store compliance |
+| `seo-specialist` | Working on technical SEO, keyword research, on-page optimization, or backlink strategy |
+| `subagent-driven-development` | Executing implementation plans with independent tasks in the current session |
+| `subscription-billing` | Integrating subscription billing, Stripe webhooks, trial logic, or dunning flows |
+| `systematic-debugging` | Debugging any issue |
+| `test-driven-development` | Implementing any feature or bugfix |
+| `using-git-worktrees` | Starting work on an isolated branch |
+| `using-superpowers` | Starting any conversation — checks for relevant skills |
+| `ux-designer` | Designing UI, wireframes, user research, or information architecture |
+| `verification-before-completion` | Before declaring a fix or task done |
+| `writing-plans` | Design is approved — breaking work into tasks |
+| `writing-skills` | Creating or editing a skill |
 
 ---
 
@@ -124,9 +172,10 @@ Upstream Superpowers releases are tracked automatically. To update:
 This workflow will:
 
 1. Pull the latest Superpowers release from GitHub
-2. Re-sync all skill symlinks
+2. Copy fresh skills from upstream
 3. AI-rewrite any changed workflows and rules to stay Antigravity-compatible
-4. Commit all changes with a versioned commit message
+4. Apply skill patches via `.agent/patches/skills-patches.md`
+5. Commit all changes with a versioned commit message
 
 ---
 
@@ -157,25 +206,11 @@ This file is preserved across `/update-superpowers` runs.
 
 ### Using This Repo in Your Project
 
-Copy the `.agent/` folder into your project root:
-
-```bash
-cp -r /path/to/antigravity-superpowers/.agent /your/project/
-```
-
-Or clone this repo as a submodule and symlink `.agent/`:
-
-```bash
-git submodule add https://github.com/<your-username>/antigravity-superpowers .antigravity-superpowers
-ln -s .antigravity-superpowers/.agent .agent
-```
-
-### Starting Fresh
+The recommended way is `npx` (see Quick Start above). Alternatively, clone and copy:
 
 ```bash
-git clone https://github.com/<your-username>/antigravity-superpowers
-cd antigravity-superpowers
-# Open with Antigravity — the agent will detect .agent/ automatically
+git clone https://github.com/bonnguyenitc/antigravity-superpowers
+cp -r antigravity-superpowers/.agent /your/project/
 ```
 
 ---

package/package.json

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

package/template/agent/rules/superpowers.md

@@ -14,6 +14,8 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 
 ## Available Skills
 
+### Development Workflow
+
 | Skill | When to Use |
 |---|---|
 | `brainstorming` | Before ANY creative work — adding features, building components, modifying behavior |
@@ -29,6 +31,57 @@ All skills are symlinked into `.agent/skills/` and are automatically available.
 | `finishing-a-development-branch` | When tasks complete — merge / PR / discard |
 | `dispatching-parallel-agents` | When running concurrent subagent workflows |
 | `writing-skills` | When creating new skills |
+| `using-superpowers` | When starting any conversation — find and use skills |
+
+### Technical Roles
+
+| Skill | When to Use |
+|---|---|
+| `frontend-developer` | Web UI, component architecture, React/Vue/Svelte/Vanilla. Has `react-rules/` (66 Vercel rules) and `vue-rules/` (44 antfu rules) |
+| `backend-developer` | APIs, server-side logic, database schemas |
+| `mobile-developer` | Mobile apps — React Native, Flutter, iOS, Android. Has `react-native-rules/` (38), `flutter-rules/` (8), `android-rules/` (17), `ios-rules/` (19) |
+| `game-developer` | Mobile game features, architecture decisions |
+| `game-design` | Game mechanics, core loops, progression, monetization |
+| `cto-architect` | System design, tech debt, scaling, architecture |
+| `saas-architect` | Multi-tenant SaaS architecture, tenant isolation |
+| `devops-engineer` | CI/CD, infrastructure, deployment, monitoring |
+| `security-engineer` | App security, auth, GDPR, security audits |
+
+### Business & Growth
+
+| Skill | When to Use |
+|---|---|
+| `product-manager` | Product requirements, feature prioritization, roadmap |
+| `data-analyst` | Metrics, funnels, cohort analysis, A/B tests |
+| `growth-hacker` | User acquisition, viral loops, activation funnels |
+| `monetization-strategist` | Pricing, freemium, IAP, unit economics |
+| `conversion-optimizer` | Landing pages, trial-to-paid, onboarding, CRO |
+| `retention-specialist` | Onboarding flows, churn reduction, re-engagement |
+| `customer-success-manager` | User support, feedback loops, NPS/CSAT |
+| `app-store-optimizer` | ASO, keyword strategy, screenshots, ratings |
+| `ux-designer` | UI design, wireframes, user research, IA |
+| `copywriter` | Landing copy, app descriptions, email sequences |
+
+### Marketing & Content
+
+| Skill | When to Use |
+|---|---|
+| `content-marketer` | Content strategy, SEO content, social media |
+| `seo-specialist` | Technical SEO, keywords, backlinks, organic search |
+| `community-manager` | Discord, Reddit, Slack community management |
+| `influencer-marketer` | UGC, creator partnerships, affiliate programs |
+| `paid-acquisition-specialist` | Meta Ads, Google Ads, Apple Search Ads, ROAS |
+
+### Infrastructure & Integration
+
+| Skill | When to Use |
+|---|---|
+| `api-design` | REST/GraphQL APIs, versioning, rate limiting |
+| `auth-and-identity` | Auth, SSO/SAML/OIDC, RBAC, session management |
+| `subscription-billing` | Stripe, IAP, trials, dunning flows |
+| `email-infrastructure` | Transactional email, SPF/DKIM/DMARC, deliverability |
+| `real-time-features` | WebSockets, SSE, live collaboration, presence |
+| `i18n-localization` | Internationalization, translations, localized ASO |
 
 ## How to Read a Skill (Antigravity)
 
@@ -50,3 +103,4 @@ Example: `.agent/skills/brainstorming/SKILL.md`
 - **TDD always**: Write failing tests first, then code
 - **Systematic over ad-hoc**: Follow the skill process, don't guess
 - **Evidence over claims**: Verify before declaring success
+

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

@@ -25,9 +25,10 @@ Load plan, review critically, execute all tasks, report when complete.
 
 For each task:
 1. Mark as in_progress
-2. Follow each step exactly (plan has bite-sized steps)
-3. Run verifications as specified
-4. Mark as completed
+2. **Check for domain skills** — before writing any code, identify which domain skill applies to this task's context (e.g. `mobile-developer` for React Native work, `backend-developer` for API work, `frontend-developer` for web UI). Read only the relevant SKILL.md (not all references); load specific references on demand as the task requires them.
+3. Follow each step exactly (plan has bite-sized steps)
+4. Run verifications as specified
+5. Mark as completed
 
 ### Step 3: Complete Development
 

package/template/agent/skills/frontend-developer/SKILL.md

@@ -131,3 +131,42 @@ Too many re-renders → React DevTools Profiler → memo, useMemo, useCallback
 Slow data fetch    → Parallel with Promise.all(), SWR/React Query for cache
 Large images       → WebP format, srcset for responsive, lazy loading
 ```
+
+---
+
+## Platform References
+
+When this skill is invoked, detect the project's framework and read
+the matching reference file(s) from `references/` before proceeding:
+
+| Stack indicator                         | Reference file                  |
+|-----------------------------------------|---------------------------------|
+| `next.config.js/ts` or `react` in deps  | `references/react-nextjs.md`    |
+| `nuxt.config.ts` or `vue` in deps       | `references/vue-nuxt.md`        |
+| `svelte.config.js` or `svelte` in deps  | `references/svelte-sveltekit.md`|
+| No framework deps / plain HTML          | `references/vanilla.md`         |
+
+If the stack is unclear, ask the user which framework they're using.
+
+### Granular Rules (React)
+
+For React/Next.js projects, `references/react-rules/` contains 66
+individual rule files from [Vercel's agent-skills](https://github.com/vercel-labs/agent-skills).
+Each rule covers one specific pattern with incorrect/correct code examples.
+
+Read `references/react-rules/_sections.md` for the full index
+organized by priority (CRITICAL → LOW). Reference individual rules
+when working on specific areas (waterfalls, bundle size, re-renders, SSR, etc.).
+
+### Granular Rules (Vue)
+
+For Vue/Nuxt projects, `references/vue-rules/` contains 44 individual
+rule files from [antfu/skills](https://github.com/antfu/skills)
+(sourced from [vuejs-ai/skills](https://github.com/vuejs-ai/skills)),
+organized into three sub-directories:
+
+- `best-practices/` — Components, reactivity, composables, performance (22 files)
+- `router/` — Vue Router guards, navigation, lifecycle gotchas (8 files)
+- `testing/` — Vitest, composable testing, Pinia setup, async patterns (11 files)
+
+Read the `_index.md` in each sub-directory for an overview.