@nst173/superpowers-ccg 1.3.0

package/README.md

@@ -0,0 +1,171 @@
+# Superpowers-CCG
+
+Superpowers-CCG is a fork/enhanced variant of [obra/superpowers](https://github.com/obra/superpowers). It keeps the same skills-driven workflow and adds **CCG multi-model orchestration**: Claude is the **pure orchestrator** (never writes code), routing implementation to **Codex MCP** (backend and systems) and **Gemini MCP** (frontend), with **Opus as the reviewer** for every code-changing path.
+
+> **CCG** = **C**laude + **C**odex + **G**emini
+
+## npm CLI
+
+This repo now also ships a project-level installer CLI for supported agents:
+
+- Claude Code
+- Cursor
+- Antigravity
+
+Run it with:
+
+```bash
+npx @nst173/superpowers-ccg setup
+```
+
+Install only specific agents:
+
+```bash
+npx @nst173/superpowers-ccg setup --agent claude-code --agent cursor
+```
+
+Install into another project directory:
+
+```bash
+npx @nst173/superpowers-ccg setup ../my-project --all
+```
+
+Preview changes without writing files:
+
+```bash
+npx @nst173/superpowers-ccg setup --dry-run
+```
+
+List supported agents:
+
+```bash
+npx @nst173/superpowers-ccg list
+```
+
+## What You Get
+
+- **Claude as pure orchestrator**: Claude routes, coordinates, and integrates. It never writes implementation code.
+- **Multi-model routing (CCG)**: route tasks to Codex (backend and systems) or Gemini (frontend). Use **CROSS_VALIDATION** for full-stack or critical tasks.
+- **Opus reviewer**: Opus reviews all code-changing paths directly.
+- **MCP tool integration**: external calls go through `mcp__codex__codex` and `mcp__gemini__gemini`.
+- **Collaboration checkpoints**: CP1/CP2/CP3 checkpoints are embedded in the main skills.
+- **Fail-closed gate**: if a required external model call cannot complete, the workflow stops with `BLOCKED`.
+
+## Quick Start (Claude Code)
+
+### Prerequisites
+
+- [Claude Code](https://docs.claude.com/docs/claude-code) installed (`claude --version`)
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and authenticated (`gemini --version`)
+- [Codex CLI](https://developers.openai.com/codex/quickstart) installed and authenticated (`codex --version`)
+- `uv` / `uvx` available
+
+### Install
+
+```bash
+claude plugin marketplace add https://github.com/sitien173/superpowers-ccg
+claude plugin install superpowers-ccg
+```
+
+### MCP Setup
+
+```bash
+# Backend and systems specialist
+claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp
+
+# Frontend specialist
+claude mcp add gemini -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/geminimcp.git geminimcp
+```
+
+## Using External Models
+
+You normally do **not** call MCP tools manually. Tell Claude what you want, and the workflow decides when to invoke external models.
+
+- Backend or systems: "Use Codex MCP for the API/database/CI parts, return a patch only."
+- Frontend: "Use Gemini MCP for UI/components/styles, return a patch only."
+- Cross-validation: "Do CROSS_VALIDATION for this design and reconcile conflicts."
+- Code review runs automatically after implementation.
+
+## Model Selection
+
+| Task type | Routing | MCP Tool |
+|---|---|---|
+| Backend, systems, scripts, CI/CD, Docker, infrastructure | CODEX | `mcp__codex__codex` |
+| Frontend (UI/components/styles) | GEMINI | `mcp__gemini__gemini` |
+| Full-stack / unclear / high impact | CROSS_VALIDATION | multiple |
+| Orchestration only (docs, coordination) | CLAUDE | none |
+
+The routing and checkpoint rules live in `skills/coordinating-multi-model-work/`.
+
+## Cursor Plugin
+
+This repo now also ships a Cursor Marketplace plugin scaffold based on `cursor/plugin-template`.
+
+- Marketplace manifest: [`.cursor-plugin/marketplace.json`](.cursor-plugin/marketplace.json)
+- Plugin package: [`plugins/superpowers-ccg`](plugins/superpowers-ccg)
+- Setup notes: [`docs/cursor-plugin.md`](docs/cursor-plugin.md)
+
+Validate the Cursor packaging with:
+
+```bash
+node scripts/validate-cursor-plugin.mjs
+```
+
+## Antigravity Port
+
+This repo now also includes an Antigravity-oriented port built around:
+
+- [`AGENTS.md`](AGENTS.md)
+- [`GEMINI.md`](GEMINI.md)
+- [`.agent/skills`](.agent/skills)
+- [`config/antigravity/mcp_config.example.json`](config/antigravity/mcp_config.example.json)
+- [`docs/antigravity.md`](docs/antigravity.md)
+
+Sync the project skills with:
+
+```bash
+node scripts/sync-antigravity-workspace.mjs
+```
+
+## Checkpoint Protocol
+
+| Checkpoint | When | Purpose |
+|---|---|---|
+| CP1 | Before first Task call | Assess routing, invoke external model early |
+| CP2 | Mid-execution | Triggered by uncertainty, stalled debugging, or repeated failures |
+| CP3 | Before claiming completion | Final domain review and verification |
+
+## Differences vs Superpowers (obra/superpowers)
+
+- **Claude as orchestrator-only**: Claude never writes implementation code.
+- **Built-in multi-model routing** via MCP tools (Codex, Gemini).
+- **Codex covers systems work**: scripts, CI/CD, Dockerfiles, and infrastructure route to Codex.
+- **Opus reviews all code** directly.
+- **CP checkpoints** enforce evidence-driven collaboration.
+- **Skill set changes** align the plugin with the CCG workflow.
+
+## Update
+
+```bash
+claude plugin update superpowers-ccg
+```
+
+## Testing
+
+See `tests/claude-code/README.md` for the Claude Code skills test suite.
+
+```bash
+./tests/claude-code/run-skill-tests.sh
+```
+
+## Support
+
+- Issues: https://github.com/sitien173/superpowers-ccg/issues
+
+## Acknowledgments
+
+- [obra/superpowers](https://github.com/obra/superpowers) - Original Superpowers project
+- [BryanHoo/superpowers-ccg](https://github.com/BryanHoo/superpowers-ccg) - CCG collaboration fork
+- [fengshao1227/ccg-workflow](https://github.com/fengshao1227/ccg-workflow) - CCG workflow
+- [GuDaStudio/geminimcp](https://github.com/GuDaStudio/geminimcp) - Gemini MCP
+- [GuDaStudio/codexmcp](https://github.com/GuDaStudio/codexmcp) - Codex MCP

package/agents/code-reviewer.md

@@ -0,0 +1,54 @@
+---
+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: opus
+---
+
+You are the final code review arbiter with expertise in software architecture, design patterns, and best practices. Your role is to review completed project steps against original plans, evaluate any assistant-review feedback, and make the final judgment on whether the implementation is ready.
+
+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. **Prior Feedback Arbitration**:
+   - If prior review feedback is provided, treat it as advisory input, not a binding verdict
+   - Re-evaluate each reported issue against the actual diff and project context
+   - Explicitly decide whether to accept, dismiss, or refine prior findings
+   - Add missed issues when prior feedback is incomplete
+
+7. **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/cli/superpowers-ccg.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.mjs";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(`superpowers-ccg: ${error.message}`);
+  process.exit(1);
+});

package/commands/brainstorm.md

@@ -0,0 +1,6 @@
+---
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores requirements and design before implementation."
+disable-model-invocation: true
+---
+
+Invoke the superpowers-ccg:brainstorming skill and follow it exactly as presented to you

package/commands/execute-plan.md

@@ -0,0 +1,6 @@
+---
+description: Execute plan in batches with review checkpoints
+disable-model-invocation: true
+---
+
+Invoke the superpowers-ccg:executing-plans skill and follow it exactly as presented to you

package/commands/write-plan.md

@@ -0,0 +1,6 @@
+---
+description: Create detailed implementation plan with bite-sized tasks
+disable-model-invocation: true
+---
+
+Invoke the superpowers-ccg:writing-plans skill and follow it exactly as presented to you

package/config/antigravity/mcp_config.example.json

@@ -0,0 +1,26 @@
+{
+  "mcpServers": {
+    "codex": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/GuDaStudio/codexmcp.git",
+        "codexmcp"
+      ],
+      "env": {
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
+      }
+    },
+    "gemini": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/GuDaStudio/geminimcp.git",
+        "geminimcp"
+      ],
+      "env": {
+        "GEMINI_API_KEY": "${GEMINI_API_KEY}"
+      }
+    }
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" user-prompt-submit.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" pre-tool-use-task.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/pre-tool-use-task.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# PreToolUse hook for Task tool - enforce model selection reminder
+
+echo "⚠️ Task model enforcement check: implementation/docs -> model:sonnet, search/exploration -> model:haiku" >&2

package/hooks/run-hook.cmd

@@ -0,0 +1,19 @@
+: << 'CMDBLOCK'
+@echo off
+REM Polyglot wrapper: runs .sh scripts cross-platform
+REM Usage: run-hook.cmd <script-name> [args...]
+REM The script should be in the same directory as this wrapper
+
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+"C:\Program Files\Git\bin\bash.exe" -l "%~dp0%~1" %2 %3 %4 %5 %6 %7 %8 %9
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/hooks/session-start.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# SessionStart hook for superpowers-ccg plugin
+
+set -euo pipefail
+
+# Check if legacy skills directory exists and build warning
+warning_message=""
+legacy_skills_dir="${HOME}/.config/superpowers/skills"
+if [ -d "$legacy_skills_dir" ]; then
+    warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
+fi
+
+# Compact session context (~300 tokens); load full skills on demand via Skill tool
+COMPACT_CONTEXT="$(cat <<'ENDOFCOMPACT'
+You have superpowers.
+
+**Core Rules:**
+1. **1% Rule:** If there is even a 1% chance a skill applies, use the Skill tool to load it before responding.
+2. **Claude is orchestrator-only:** All implementation code goes through external models (Codex/Gemini MCP).
+3. **Checkpoint Protocol:** CP1 before first Task call, CP3 before claiming completion.
+4. **Fail-Closed:** If Routing != CLAUDE and MCP call fails, output BLOCKED (see GATE.md for tiered policy).
+
+**Multi-Model Routing:**
+- Backend (API, DB, auth) → CODEX (`mcp__codex__codex`)
+- Frontend (UI, styles) → GEMINI (`mcp__gemini__gemini`)
+- Backend and systems (API, DB, auth, CI/CD, scripts, infrastructure) → CODEX (`mcp__codex__codex`)
+- Full-stack/uncertain → CROSS_VALIDATION (multiple)
+- Docs/coordination only → CLAUDE
+
+**Shared Serena (HTTP 9121):** All agents share one Serena instance. `global/response_protocol` controls token-efficient agent output format.
+
+**Supplementary Tools (optional):** Grok Search/Tavily (research), Sequential-Thinking (complex reasoning), Serena (shared context bus), Magic (UI components), Morphllm (bulk edits).
+
+**Skill Namespace:** `superpowers-ccg:` — use Skill tool to load any skill by name.
+
+**To learn more:** Load `superpowers-ccg:using-superpowers` or `superpowers-ccg:coordinating-multi-model-work` for full instructions.
+ENDOFCOMPACT
+)"
+
+# Escape outputs for JSON using pure bash
+escape_for_json() {
+    local input="$1"
+    local output=""
+    local i char
+    for (( i=0; i<${#input}; i++ )); do
+        char="${input:$i:1}"
+        case "$char" in
+            $'\\') output+='\\' ;;
+            '"') output+='\"' ;;
+            $'\n') output+='\n' ;;
+            $'\r') output+='\r' ;;
+            $'\t') output+='\t' ;;
+            *) output+="$char" ;;
+        esac
+    done
+    printf '%s' "$output"
+}
+
+compact_escaped=$(escape_for_json "$COMPACT_CONTEXT")
+warning_escaped=$(escape_for_json "$warning_message")
+
+# Output context injection as JSON
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "<EXTREMELY_IMPORTANT>\n${compact_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
+  }
+}
+EOF
+
+exit 0

package/hooks/user-prompt-submit.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook for superpowers-ccg plugin
+
+set -euo pipefail
+
+REMINDER_TEXT="[CP Protocol Threshold]
+
+Before the first Task call, output a short standalone [CP1 Assessment] block.
+Before claiming completion, output a short standalone [CP3 Assessment] block.
+
+Use the minimal format below. Do not add extra narration to the checkpoint itself.
+
+[CP1 Assessment]
+- Task type: [Frontend/Backend/Full-stack/Other]
+- Complexity: [Trivial/Standard/Critical]
+- Routing decision: [CLAUDE/CODEX/GEMINI/CROSS_VALIDATION]
+- Rationale: [one sentence]
+
+Compact trivial form:
+[CP1] Routing: CLAUDE | Trivial: <reason>
+
+[CP3 Assessment]
+- Task type: [Frontend/Backend/Full-stack/Other]
+- Routing decision: [CLAUDE/CODEX/GEMINI/CROSS_VALIDATION]
+- Rationale: [one sentence]
+
+Compact trivial form:
+[CP3] Verified: <evidence>
+"
+
+printf '%s\n' "$REMINDER_TEXT"

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nst173/superpowers-ccg",
+  "version": "1.3.0",
+  "description": "CLI to install Superpowers CCG workflows at project level for Claude Code, Cursor, and Antigravity.",
+  "type": "module",
+  "bin": {
+    "superpowers-ccg": "./cli/superpowers-ccg.mjs",
+    "spccg": "./cli/superpowers-ccg.mjs"
+  },
+  "files": [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    "LICENSE",
+    "README.md",
+    "agents",
+    "commands",
+    "hooks",
+    "skills",
+    ".cursor",
+    ".agent",
+    "config/antigravity",
+    "cli",
+    "src"
+  ],
+  "scripts": {
+    "test:smoke": "node scripts/smoke-test-cli.mjs",
+    "prepublishOnly": "npm run test:smoke"
+  },
+  "keywords": [
+    "claude-code",
+    "cursor",
+    "antigravity",
+    "workflow",
+    "skills",
+    "orchestrator",
+    "mcp",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "nst173",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sitien173/superpowers-ccg.git"
+  },
+  "homepage": "https://github.com/sitien173/superpowers-ccg#readme",
+  "bugs": {
+    "url": "https://github.com/sitien173/superpowers-ccg/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}