agy-superpowers 5.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# antigravity-superpowers
+
+> **Superpowers for [Google Antigravity](https://antigravity.google)** — a complete development workflow powered by composable skills, workflows, and rules.
+
+
+This repo ports the [Superpowers](https://github.com/obra/superpowers) skills library to work natively with **Google Antigravity agent**, with Antigravity-compatible path conventions, an auto-update workflow, and curated workflow files translated from the upstream skills.
+
+---
+
+## Quick Start
+
+### Option 1 — npx (recommended, no install needed)
+
+Inside any project directory:
+
+```bash
+npx agy-superpowers@latest init
+```
+
+This scaffolds `.agent/` with all Superpowers skills, workflows, and rules.
+Open the project with **Google Antigravity** — Superpowers activates automatically.
+
+To overwrite an existing `.agent/`:
+
+```bash
+npx agy-superpowers@latest init --force
+```
+
+### Option 2 — Global install
+
+```bash
+npm install -g agy-superpowers
+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
+```
+
+---
+
+## How It Works
+
+**Antigravity automatically reads skills before every response.** You don't need to invoke them manually — the `superpowers.md` rule (set to `alwaysApply: true`) instructs the agent to check for a relevant skill before acting.
+
+### The Core Development Loop
+
+```
+💡 Idea → /brainstorm → /write-plan → /execute-plan → /code-review → merge
+```
+
+| Step | Workflow        | What happens                                                   |
+| ---- | --------------- | -------------------------------------------------------------- |
+| 1    | `/brainstorm`   | Agent asks clarifying questions, refines your idea into a spec |
+| 2    | `/write-plan`   | Spec → bite-sized tasks (2–5 min each) with exact file paths   |
+| 3    | `/execute-plan` | Tasks run in batches with human checkpoints                    |
+| 4    | `/code-review`  | Pre-review checklist, severity-based issue reporting           |
+| 5    | _(auto)_        | `finishing-a-development-branch` — merge / PR / discard        |
+
+---
+
+## 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                                                 |
+
+---
+
+## Keeping Up to Date
+
+Upstream Superpowers releases are tracked automatically. To update:
+
+```
+/update-superpowers
+```
+
+This workflow will:
+
+1. Pull the latest Superpowers release from GitHub
+2. Re-sync all skill symlinks
+3. AI-rewrite any changed workflows and rules to stay Antigravity-compatible
+4. Commit all changes with a versioned commit message
+
+---
+
+## Installation
+
+### 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
+
+```bash
+git clone https://github.com/<your-username>/antigravity-superpowers
+cd antigravity-superpowers
+# Open with Antigravity — the agent will detect .agent/ automatically
+```
+
+---
+
+## Philosophy
+
+This setup enforces four core principles across every task:
+
+- **Test-Driven Development** — Write the failing test first, always
+- **YAGNI** — Don't build what isn't needed yet
+- **Systematic over ad-hoc** — Follow the skill process, don't guess
+- **Evidence over claims** — Verify before declaring success
+
+---
+
+## Credits
+
+- **[Superpowers](https://github.com/obra/superpowers)** by [Jesse Vincent](https://blog.fsck.com) & [Prime Radiant](https://primeradiant.com) — the upstream skills library this repo is built on.
+- Antigravity integration & workflow adaptation by [@bonnguyenitc](https://github.com/bonnguyenitc).
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

package/bin/init.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// bin/init.js
+// Usage: npx antigravity-superpowers init
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.resolve(__dirname, '..', 'template', 'agent');
+const TARGET_DIR = path.join(process.cwd(), '.agent');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command !== 'init') {
+  console.error(`❌ Unknown command: ${command || '(none)'}`);
+  console.error('');
+  console.error('Usage: npx antigravity-superpowers init');
+  console.error('       npx antigravity-superpowers init --force   # overwrite existing .agent/');
+  process.exit(1);
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Guard: don't overwrite existing .agent/ without --force
+if (fs.existsSync(TARGET_DIR)) {
+  console.warn('⚠️  .agent/ already exists in this directory.');
+  console.warn('   Delete it first or re-run with --force to overwrite:');
+  console.warn('');
+  console.warn('   npx antigravity-superpowers init --force');
+  console.warn('');
+  if (!args.includes('--force')) {
+    process.exit(1);
+  }
+  fs.rmSync(TARGET_DIR, { recursive: true });
+  console.log('🗑  Removed existing .agent/');
+}
+
+console.log('🚀 Initialising antigravity-superpowers…');
+copyDir(TEMPLATE_DIR, TARGET_DIR);
+console.log('✅ .agent/ created successfully!\n');
+console.log('📖 Next steps:');
+console.log('   1. Open your project with Google Antigravity');
+console.log('   2. The agent will automatically detect .agent/ and activate Superpowers');
+console.log('   3. Use /brainstorm, /write-plan, /execute-plan, /code-review, /debug');
+console.log('');
+console.log('📦 Keep skills up to date: /update-superpowers');

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "agy-superpowers",
+  "version": "5.0.5",
+  "description": "Superpowers skills library for Google Antigravity agent — scaffold .agent/ with one command",
+  "type": "module",
+  "bin": {
+    "agy-superpowers": "bin/init.js"
+  },
+  "files": [
+    "bin/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build-template.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "antigravity",
+    "superpowers",
+    "agent",
+    "skills",
+    "workflow",
+    "ai"
+  ],
+  "author": "bonnguyenitc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bonnguyenitc/antigravity-superpowers.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/agent/.shared/update-superpowers.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO="https://github.com/obra/superpowers"
+VERSION_FILE=".agent/superpowers-version.json"
+SKILLS_DIR=".agent/skills"
+
+# ── Phase 0: Version Check ────────────────────────────────────────────────────
+
+echo "🔍 Checking superpowers version..."
+
+# Read current installed tag
+CURRENT_TAG=$(jq -r '.tag // "none"' "$VERSION_FILE" 2>/dev/null || echo "none")
+
+# Fetch latest release tag from GitHub API
+LATEST_TAG=$(curl -Lfs --retry 3 \
+  "https://api.github.com/repos/obra/superpowers/releases/latest" \
+  | grep '"tag_name"' | cut -d'"' -f4)
+
+if [[ -z "$LATEST_TAG" ]]; then
+  echo "❌ Failed to fetch latest release from GitHub. Check your network." >&2
+  exit 1
+fi
+
+echo "  Current: ${CURRENT_TAG}"
+echo "  Latest:  ${LATEST_TAG}"
+
+if [[ "$CURRENT_TAG" == "$LATEST_TAG" ]]; then
+  echo "✅ Already up to date (${LATEST_TAG}). Nothing to do."
+  exit 0
+fi
+
+# ── Show release notes excerpt ────────────────────────────────────────────────
+
+echo ""
+echo "🆕 New release available: ${CURRENT_TAG} → ${LATEST_TAG}"
+echo ""
+
+RELEASE_BODY=$(curl -Lfs --retry 3 \
+  "https://api.github.com/repos/obra/superpowers/releases/latest" \
+  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('body','')[:800])" 2>/dev/null \
+  || echo "(no notes)")
+
+echo "Release notes (excerpt):"
+echo "────────────────────────"
+echo "$RELEASE_BODY"
+echo "────────────────────────"
+echo ""
+
+# ── Phase 1: Clone + Symlinks ─────────────────────────────────────────────────
+
+echo "📥 Cloning superpowers @ ${LATEST_TAG}..."
+
+TMP_DIR=$(mktemp -d)
+CLONE_TARGET="${TMP_DIR}/superpowers"
+
+# Clone at exact release tag, shallow for speed
+if ! git clone --branch "$LATEST_TAG" --depth 1 "$REPO" "$CLONE_TARGET" 2>&1; then
+  echo "❌ Clone failed. Aborting — superpowers/ is unchanged." >&2
+  rm -rf "$TMP_DIR"
+  exit 1
+fi
+
+echo "✅ Clone successful."
+
+# Backup existing superpowers/ before replacing
+if [[ -d "superpowers" ]]; then
+  BACKUP_DIR="superpowers.bak.$(date +%s)"
+  mv superpowers "$BACKUP_DIR"
+  echo "📦 Old superpowers/ backed up to ${BACKUP_DIR}"
+fi
+
+# Move new clone into place
+mv "$CLONE_TARGET" superpowers/
+rm -rf "$TMP_DIR"
+echo "✅ superpowers/ replaced."
+
+# Remove nested .git (we don't want a nested git repo)
+rm -rf superpowers/.git
+
+# ── Recreate all skill symlinks ───────────────────────────────────────────────
+
+echo "🔗 Rebuilding ${SKILLS_DIR}/ symlinks..."
+
+mkdir -p "$SKILLS_DIR"
+
+# Remove old symlinks only (not regular files)
+find "$SKILLS_DIR" -maxdepth 1 -type l -delete
+
+# Detect and link ALL skills in new superpowers
+NEW_SKILLS=()
+for skill_dir in superpowers/skills/*/; do
+  skill_name=$(basename "$skill_dir")
+  ln -sf "../../${skill_dir}" "${SKILLS_DIR}/${skill_name}"
+  NEW_SKILLS+=("$skill_name")
+done
+
+echo "✅ Linked ${#NEW_SKILLS[@]} skills: ${NEW_SKILLS[*]}"
+
+# ── Sync agents: copy + fix path references ───────────────────────────────────
+
+echo "📋 Syncing .agent/agents/ from superpowers/agents/..."
+
+AGENTS_DIR=".agent/agents"
+mkdir -p "$AGENTS_DIR"
+
+SYNCED_AGENTS=()
+for agent_src in superpowers/agents/*.md; do
+  [[ -f "$agent_src" ]] || continue
+  agent_name=$(basename "$agent_src")
+  dest="${AGENTS_DIR}/${agent_name}"
+
+  # Copy verbatim, then fix known Antigravity path differences in-place:
+  #   .agents/  →  .agent/   (superpowers uses .agents/, Antigravity uses .agent/)
+  cp "$agent_src" "$dest"
+  sed -i '' 's|\.agents/|.agent/|g' "$dest"
+
+  SYNCED_AGENTS+=("$agent_name")
+  echo "  ✅ ${agent_name}"
+done
+
+echo "✅ Synced ${#SYNCED_AGENTS[@]} agent(s): ${SYNCED_AGENTS[*]}"
+
+# ── Sync commands → workflows: copy + fix path references ─────────────────────
+
+echo "🔄 Syncing .agent/workflows/ from superpowers/commands/..."
+
+WORKFLOWS_DIR=".agent/workflows"
+mkdir -p "$WORKFLOWS_DIR"
+
+SYNCED_WORKFLOWS=()
+for cmd_src in superpowers/commands/*.md; do
+  [[ -f "$cmd_src" ]] || continue
+  cmd_name=$(basename "$cmd_src")
+  dest="${WORKFLOWS_DIR}/${cmd_name}"
+
+  # Copy verbatim, then fix path references:
+  #   .agents/  →  .agent/
+  cp "$cmd_src" "$dest"
+  sed -i '' 's|\.agents/|.agent/|g' "$dest"
+
+  SYNCED_WORKFLOWS+=("$cmd_name")
+  echo "  ✅ ${cmd_name}"
+done
+
+if [[ ${#SYNCED_WORKFLOWS[@]} -eq 0 ]]; then
+  echo "  (no commands found in superpowers/commands/)"
+else
+  echo "✅ Synced ${#SYNCED_WORKFLOWS[@]} workflow(s): ${SYNCED_WORKFLOWS[*]}"
+fi
+
+# ── Save version state ────────────────────────────────────────────────────────
+
+echo "💾 Saving version state to ${VERSION_FILE}..."
+
+mkdir -p "$(dirname "$VERSION_FILE")"
+cat > "$VERSION_FILE" << EOF
+{
+  "tag": "${LATEST_TAG}",
+  "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "source": "${REPO}"
+}
+EOF
+
+echo "✅ Version saved: ${LATEST_TAG}"
+echo ""
+echo "────────────────────────────────────────────────────────"
+echo "SCRIPT_DONE:${LATEST_TAG}"
+echo "────────────────────────────────────────────────────────"
+echo ""
+echo "⏭  Script complete. Antigravity will now handle the AI rewrite phase."

package/template/agent/agents/code-reviewer.md

@@ -0,0 +1,48 @@
+---
+name: code-reviewer
+description: |
+  Use this agent when a major project step has been completed and needs to be reviewed against the original plan and coding standards. Examples: <example>Context: The user is creating a code-review agent that should be called after a logical chunk of code is written. user: "I've finished implementing the user authentication system as outlined in step 3 of our plan" assistant: "Great work! Now let me use the code-reviewer agent to review the implementation against our plan and coding standards" <commentary>Since a major project step has been completed, use the code-reviewer agent to validate the work against the plan and identify any issues.</commentary></example> <example>Context: User has completed a significant feature implementation. user: "The API endpoints for the task management system are now complete - that covers step 2 from our architecture document" assistant: "Excellent! Let me have the code-reviewer agent examine this implementation to ensure it aligns with our plan and follows best practices" <commentary>A numbered step from the planning document has been completed, so the code-reviewer agent should review the work.</commentary></example>
+model: inherit
+---
+
+You are a Senior Code Reviewer with expertise in software architecture, design patterns, and best practices. Your role is to review completed project steps against original plans and ensure code quality standards are met.
+
+When reviewing completed work, you will:
+
+1. **Plan Alignment Analysis**:
+   - Compare the implementation against the original planning document or step description
+   - Identify any deviations from the planned approach, architecture, or requirements
+   - Assess whether deviations are justified improvements or problematic departures
+   - Verify that all planned functionality has been implemented
+
+2. **Code Quality Assessment**:
+   - Review code for adherence to established patterns and conventions
+   - Check for proper error handling, type safety, and defensive programming
+   - Evaluate code organization, naming conventions, and maintainability
+   - Assess test coverage and quality of test implementations
+   - Look for potential security vulnerabilities or performance issues
+
+3. **Architecture and Design Review**:
+   - Ensure the implementation follows SOLID principles and established architectural patterns
+   - Check for proper separation of concerns and loose coupling
+   - Verify that the code integrates well with existing systems
+   - Assess scalability and extensibility considerations
+
+4. **Documentation and Standards**:
+   - Verify that code includes appropriate comments and documentation
+   - Check that file headers, function documentation, and inline comments are present and accurate
+   - Ensure adherence to project-specific coding standards and conventions
+
+5. **Issue Identification and Recommendations**:
+   - Clearly categorize issues as: Critical (must fix), Important (should fix), or Suggestions (nice to have)
+   - For each issue, provide specific examples and actionable recommendations
+   - When you identify plan deviations, explain whether they're problematic or beneficial
+   - Suggest specific improvements with code examples when helpful
+
+6. **Communication Protocol**:
+   - If you find significant deviations from the plan, ask the coding agent to review and confirm the changes
+   - If you identify issues with the original plan itself, recommend plan updates
+   - For implementation problems, provide clear guidance on fixes needed
+   - Always acknowledge what was done well before highlighting issues
+
+Your output should be structured, actionable, and focused on helping maintain high code quality while ensuring project goals are met. Be thorough but concise, and always provide constructive feedback that helps improve both the current implementation and future development practices.

package/template/agent/rules/superpowers.md

@@ -0,0 +1,52 @@
+---
+description: Superpowers workflow rules - apply when building features, debugging, or planning any development task
+alwaysApply: true
+---
+
+# Superpowers Skills Integration
+
+This workspace uses the **Superpowers** skills library located in `superpowers/skills/`.
+All skills are symlinked into `.agent/skills/` and are automatically available.
+
+## Core Rule: Check Skills Before Acting
+
+**Before any response or action**, check if a relevant skill applies. If there's even a 1% chance a skill applies, read it via `view_file` on its `SKILL.md` and follow it exactly.
+
+## Available Skills
+
+| Skill | When to Use |
+|---|---|
+| `brainstorming` | Before ANY creative work — adding features, building components, modifying behavior |
+| `writing-plans` | After design is approved — break work into 2-5 min tasks |
+| `executing-plans` | When running a plan in batches with human checkpoints |
+| `subagent-driven-development` | When dispatching subagents per task with two-stage review |
+| `test-driven-development` | During ALL implementation — RED → GREEN → REFACTOR |
+| `systematic-debugging` | When debugging any issue |
+| `verification-before-completion` | Before declaring any fix or task is done |
+| `requesting-code-review` | Before submitting code for review |
+| `receiving-code-review` | When responding to review feedback |
+| `using-git-worktrees` | When starting work on a new isolated branch |
+| `finishing-a-development-branch` | When tasks complete — merge / PR / discard |
+| `dispatching-parallel-agents` | When running concurrent subagent workflows |
+| `writing-skills` | When creating new skills |
+
+## How to Read a Skill (Antigravity)
+
+Use `view_file` on the skill's `SKILL.md`:
+```
+.agent/skills/<skill-name>/SKILL.md
+```
+Example: `.agent/skills/brainstorming/SKILL.md`
+
+## Instruction Priority
+
+1. **User's explicit instructions** — highest priority
+2. **Superpowers skills** — override default behavior
+3. **Default system behavior** — lowest priority
+
+## Key Principles
+
+- **YAGNI**: Don't build what isn't needed yet
+- **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