@nst173/superpowers-ccg 1.3.0 → 1.3.1

package/lib/prompts.js

@@ -0,0 +1,92 @@
+import prompts from 'prompts';
+
+const AGENT_CHOICES = [
+  {
+    title: 'Claude Code',
+    value: 'claude-code'
+  },
+  {
+    title: 'Cursor',
+    value: 'cursor'
+  },
+  {
+    title: 'Antigravity',
+    value: 'antigravity'
+  }
+];
+
+export async function collectInteractiveConfig() {
+  const answers = await prompts(
+    [
+      {
+        type: 'multiselect',
+        name: 'agents',
+        message: 'Which agents do you want to install?',
+        choices: AGENT_CHOICES,
+        min: 1,
+        instructions: false
+      },
+      {
+        type: 'text',
+        name: 'grokApiUrl',
+        message: 'GROK_API_URL',
+        validate: requiredValue
+      },
+      {
+        type: 'password',
+        name: 'grokApiKey',
+        message: 'GROK_API_KEY',
+        validate: requiredValue
+      },
+      {
+        type: 'text',
+        name: 'tavilyApiUrl',
+        message: 'TAVILY_API_URL (optional)'
+      },
+      {
+        type: 'password',
+        name: 'tavilyApiKey',
+        message: 'TAVILY_API_KEY (optional)'
+      },
+      {
+        type: 'password',
+        name: 'firecrawlApiKey',
+        message: 'FIRECRAWL_API_KEY (optional)'
+      },
+      {
+        type: 'text',
+        name: 'firecrawlApiUrl',
+        message: 'FIRECRAWL_API_URL (optional)'
+      }
+    ],
+    {
+      onCancel() {
+        throw new Error('Installation cancelled.');
+      }
+    }
+  );
+
+  return {
+    agents: answers.agents,
+    mcpEnv: buildMcpEnv({
+      GROK_API_URL: answers.grokApiUrl,
+      GROK_API_KEY: answers.grokApiKey,
+      TAVILY_API_URL: answers.tavilyApiUrl,
+      TAVILY_API_KEY: answers.tavilyApiKey,
+      FIRECRAWL_API_KEY: answers.firecrawlApiKey,
+      FIRECRAWL_API_URL: answers.firecrawlApiUrl
+    })
+  };
+}
+
+function requiredValue(value) {
+  return value && value.trim() ? true : 'This value is required.';
+}
+
+function buildMcpEnv(values) {
+  return Object.fromEntries(
+    Object.entries(values)
+      .map(([key, value]) => [key, typeof value === 'string' ? value.trim() : ''])
+      .filter(([, value]) => value)
+  );
+}

package/lib/skills-core.js

@@ -0,0 +1,208 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Extract YAML frontmatter from a skill file.
+ * Current format:
+ * ---
+ * name: skill-name
+ * description: Use when [condition] - [what it does]
+ * ---
+ *
+ * @param {string} filePath - Path to SKILL.md file
+ * @returns {{name: string, description: string}}
+ */
+function extractFrontmatter(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const lines = content.split('\n');
+
+        let inFrontmatter = false;
+        let name = '';
+        let description = '';
+
+        for (const line of lines) {
+            if (line.trim() === '---') {
+                if (inFrontmatter) break;
+                inFrontmatter = true;
+                continue;
+            }
+
+            if (inFrontmatter) {
+                const match = line.match(/^(\w+):\s*(.*)$/);
+                if (match) {
+                    const [, key, value] = match;
+                    switch (key) {
+                        case 'name':
+                            name = value.trim();
+                            break;
+                        case 'description':
+                            description = value.trim();
+                            break;
+                    }
+                }
+            }
+        }
+
+        return { name, description };
+    } catch (error) {
+        return { name: '', description: '' };
+    }
+}
+
+/**
+ * Find all SKILL.md files in a directory recursively.
+ *
+ * @param {string} dir - Directory to search
+ * @param {string} sourceType - 'personal' or 'superpowers' for namespacing
+ * @param {number} maxDepth - Maximum recursion depth (default: 3)
+ * @returns {Array<{path: string, name: string, description: string, sourceType: string}>}
+ */
+function findSkillsInDir(dir, sourceType, maxDepth = 3) {
+    const skills = [];
+
+    if (!fs.existsSync(dir)) return skills;
+
+    function recurse(currentDir, depth) {
+        if (depth > maxDepth) return;
+
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+
+            if (entry.isDirectory()) {
+                // Check for SKILL.md in this directory
+                const skillFile = path.join(fullPath, 'SKILL.md');
+                if (fs.existsSync(skillFile)) {
+                    const { name, description } = extractFrontmatter(skillFile);
+                    skills.push({
+                        path: fullPath,
+                        skillFile: skillFile,
+                        name: name || entry.name,
+                        description: description || '',
+                        sourceType: sourceType
+                    });
+                }
+
+                // Recurse into subdirectories
+                recurse(fullPath, depth + 1);
+            }
+        }
+    }
+
+    recurse(dir, 0);
+    return skills;
+}
+
+/**
+ * Resolve a skill name to its file path, handling shadowing
+ * (personal skills override superpowers skills).
+ *
+ * @param {string} skillName - Name like "superpowers:brainstorming" or "my-skill"
+ * @param {string} superpowersDir - Path to superpowers skills directory
+ * @param {string} personalDir - Path to personal skills directory
+ * @returns {{skillFile: string, sourceType: string, skillPath: string} | null}
+ */
+function resolveSkillPath(skillName, superpowersDir, personalDir) {
+    // Strip superpowers: prefix if present
+    const forceSuperpowers = skillName.startsWith('superpowers:');
+    const actualSkillName = forceSuperpowers ? skillName.replace(/^superpowers:/, '') : skillName;
+
+    // Try personal skills first (unless explicitly superpowers:)
+    if (!forceSuperpowers && personalDir) {
+        const personalPath = path.join(personalDir, actualSkillName);
+        const personalSkillFile = path.join(personalPath, 'SKILL.md');
+        if (fs.existsSync(personalSkillFile)) {
+            return {
+                skillFile: personalSkillFile,
+                sourceType: 'personal',
+                skillPath: actualSkillName
+            };
+        }
+    }
+
+    // Try superpowers skills
+    if (superpowersDir) {
+        const superpowersPath = path.join(superpowersDir, actualSkillName);
+        const superpowersSkillFile = path.join(superpowersPath, 'SKILL.md');
+        if (fs.existsSync(superpowersSkillFile)) {
+            return {
+                skillFile: superpowersSkillFile,
+                sourceType: 'superpowers',
+                skillPath: actualSkillName
+            };
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Check if a git repository has updates available.
+ *
+ * @param {string} repoDir - Path to git repository
+ * @returns {boolean} - True if updates are available
+ */
+function checkForUpdates(repoDir) {
+    try {
+        // Quick check with 3 second timeout to avoid delays if network is down
+        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
+            cwd: repoDir,
+            timeout: 3000,
+            encoding: 'utf8',
+            stdio: 'pipe'
+        });
+
+        // Parse git status output to see if we're behind
+        const statusLines = output.split('\n');
+        for (const line of statusLines) {
+            if (line.startsWith('## ') && line.includes('[behind ')) {
+                return true; // We're behind remote
+            }
+        }
+        return false; // Up to date
+    } catch (error) {
+        // Network down, git error, timeout, etc. - don't block bootstrap
+        return false;
+    }
+}
+
+/**
+ * Strip YAML frontmatter from skill content, returning just the content.
+ *
+ * @param {string} content - Full content including frontmatter
+ * @returns {string} - Content without frontmatter
+ */
+function stripFrontmatter(content) {
+    const lines = content.split('\n');
+    let inFrontmatter = false;
+    let frontmatterEnded = false;
+    const contentLines = [];
+
+    for (const line of lines) {
+        if (line.trim() === '---') {
+            if (inFrontmatter) {
+                frontmatterEnded = true;
+                continue;
+            }
+            inFrontmatter = true;
+            continue;
+        }
+
+        if (frontmatterEnded || !inFrontmatter) {
+            contentLines.push(line);
+        }
+    }
+
+    return contentLines.join('\n').trim();
+}
+
+export {
+    extractFrontmatter,
+    findSkillsInDir,
+    resolveSkillPath,
+    checkForUpdates,
+    stripFrontmatter
+};

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@nst173/superpowers-ccg",
-  "version": "1.3.0",
-  "description": "CLI to install Superpowers CCG workflows at project level for Claude Code, Cursor, and Antigravity.",
+  "version": "1.3.1",
+  "description": "Superpowers CCG workflows for Claude Code, Cursor, and Antigravity.",
   "type": "module",
   "bin": {
-    "superpowers-ccg": "./cli/superpowers-ccg.mjs",
-    "spccg": "./cli/superpowers-ccg.mjs"
+    "superpowers-ccg": "./bin/cli.js"
   },
   "files": [
     "AGENTS.md",
@@ -17,16 +16,10 @@
     "commands",
     "hooks",
     "skills",
-    ".cursor",
-    ".agent",
-    "config/antigravity",
-    "cli",
-    "src"
+    "bin",
+    "lib",
+    "templates"
   ],
-  "scripts": {
-    "test:smoke": "node scripts/smoke-test-cli.mjs",
-    "prepublishOnly": "npm run test:smoke"
-  },
   "keywords": [
     "claude-code",
     "cursor",
@@ -34,8 +27,7 @@
     "workflow",
     "skills",
     "orchestrator",
-    "mcp",
-    "cli"
+    "mcp"
   ],
   "license": "MIT",
   "author": "nst173",
@@ -50,6 +42,9 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "prompts": "2.4.2"
+  },
   "publishConfig": {
     "access": "public"
   }

package/skills/EVALUATION.md

@@ -18,37 +18,7 @@ Use evaluation scenarios (per Anthropic best practices) to validate skill effect
 
 ## Core Workflow Skills
 
-### test-driven-development
-
-```json
-{
-  "skill": "test-driven-development",
-  "query": "Add a function to validate email format",
-  "expected_behavior": [
-    "Write a failing test before implementation",
-    "Run tests to confirm failure and show the reason",
-    "Write minimal code to make the test pass",
-    "Run tests to confirm passing",
-    "Do not add functionality beyond the test scope"
-  ]
-}
-```
-
-```json
-{
-  "skill": "test-driven-development",
-  "query": "This function has a bug, please fix it",
-  "context": "src/utils/parser.ts",
-  "expected_behavior": [
-    "Write a failing test that reproduces the bug",
-    "Confirm the test fails for the correct reason",
-    "Fix the code",
-    "Confirm the test passes"
-  ]
-}
-```
-
-### debugging-systematically
+### debugging-systematically
 
 ```json
 {
@@ -143,57 +113,7 @@ Use evaluation scenarios (per Anthropic best practices) to validate skill effect
 }
 ```
 
-## Supporting Skills
-
-### using-git-worktrees
-
-```json
-{
-  "skill": "using-git-worktrees",
-  "query": "Create an isolated workspace to develop a new feature",
-  "expected_behavior": [
-    "Check existing .worktrees or worktrees directories",
-    "Verify the directory is gitignored",
-    "If not ignored, add it to .gitignore and commit",
-    "Run project setup after creating the worktree",
-    "Run tests to verify a clean baseline"
-  ]
-}
-```
-
-### finishing-development-branches
-
-```json
-{
-  "skill": "finishing-development-branches",
-  "query": "Development is complete, help me handle the branch",
-  "expected_behavior": [
-    "Run tests and verify they pass",
-    "Do not offer completion options if tests fail",
-    "Provide exactly 4 options",
-    "Require confirmation when discarding",
-    "Clean up the worktree correctly"
-  ]
-}
-```
-
-### dispatching-parallel-agents
-
-```json
-{
-  "skill": "dispatching-parallel-agents",
-  "query": "Five test files are failing, help me fix them",
-  "expected_behavior": [
-    "Identify whether failures are independent",
-    "If independent, group them by problem domain",
-    "Dispatch multiple agents in parallel",
-    "Give each agent a clear scope and constraints",
-    "Summarize results and verify no conflicts"
-  ]
-}
-```
-
-## Run the Evaluation
+## Run the Evaluation
 
 1. Run the query without the skill and record behavior
 2. Enable the skill and run the same query

package/skills/brainstorming/SKILL.md

@@ -29,10 +29,10 @@ Follow `skills/shared/protocol-threshold.md`. The hook injects CP reminders auto
 
 **Supplementary tools (optional, enhance research):**
 - **Grok Search (Tavily):** If the idea involves unfamiliar tech, current trends, or competitive analysis — use `mcp__grok-search__web_search` to gather real-time information before proposing approaches. Especially useful when the user references a library, service, or pattern you're uncertain about.
-- **Serena:** If the project is large (>10 files involved) — use Serena for semantic codebase exploration to understand existing architecture and symbol relationships.
+- **Auggie:** If the project is large (>10 files involved) — use Auggie for full-context semantic codebase retrieval to understand the existing architecture and likely implementation anchors.
 - See `skills/shared/supplementary-tools.md` for full reference.
 
-**► CP1 (Task Analysis):** After understanding the idea, apply `coordinating-multi-model-work/checkpoints.md`.
+**► CP1 (Task Assessment & Routing):** After understanding the idea, apply `coordinating-multi-model-work/checkpoints.md`.
 
 **Exploring approaches:**
 
@@ -41,7 +41,7 @@ Follow `skills/shared/protocol-threshold.md`. The hook injects CP reminders auto
 - Lead with your recommended option and explain why
 - **Sequential-Thinking (optional):** For complex designs with 3+ interacting components, use Sequential-Thinking MCP to systematically decompose trade-offs and validate reasoning chains before presenting options.
 
-**► CP2 (Mid-Review):** When multiple approaches have significant trade-offs, apply `coordinating-multi-model-work/checkpoints.md`.
+**CP2 note:** CP2 is the external execution phase and starts only after the design is routed into implementation.
 
 **Presenting the design:**
 
@@ -100,11 +100,10 @@ TaskUpdate:
 
 Before handing off to writing-plans, run `TaskList` to display the complete task tree with dependency status so the user can confirm it looks right.
 
-**Implementation (if continuing):**
-
-- Ask: "Ready to set up for implementation?"
-- Use superpowers:using-git-worktrees to create isolated workspace
-- Use superpowers:writing-plans to create detailed implementation plan
+**Implementation (if continuing):**
+
+- Ask: "Ready to turn this into an implementation plan?"
+- Use superpowers:writing-plans to create detailed implementation plan
 
 ## Key Principles
 

package/skills/coordinating-multi-model-work/GATE.md

@@ -5,7 +5,7 @@ Use this gate whenever a skill decides **Routing != CLAUDE** (`CODEX`, `GEMINI`,
 ## Core Rule
 
 - If `Routing != CLAUDE`, you must obtain external model output via MCP tools (`mcp__codex__codex`, `mcp__gemini__gemini`).
-- If code changed, you must run the review chain per `coordinating-multi-model-work/review-chain.md`.
+- You must finish with CP4 Final Spec Review per `coordinating-multi-model-work/review-chain.md`.
 - If you cannot obtain required external output, stop in `BLOCKED`.
 
 ## Evidence Requirement
@@ -20,9 +20,10 @@ Evidence (Implementation):
 - Params: <key MCP parameters used>
 - Result: <3-6 bullets>
 
-Evidence (Opus Review):
-- Reviewer: Opus
-- Artifact: <commit SHA>
+Evidence (CP4 Spec Review):
+- Reviewer: Claude
+- Status: PASS | PARTIAL | FAIL
+- Artifact: <files reviewed>
 - Result: <3-6 bullets>
 ```
 

package/skills/coordinating-multi-model-work/INTEGRATION.md

@@ -5,47 +5,111 @@ Claude is orchestrator-only. All implementation code goes through external model
 ## Standard Pattern
 
 1. Define one bounded task.
-2. Include only the minimum context needed to complete that task.
-3. Ask the worker for one of two outcomes:
-   - changed hunks / patch-ready diff
-   - blocking questions
-4. Reuse `SESSION_ID` only for follow-up fixes on the same task.
-5. Run Opus review on the resulting artifact.
+2. Turn CP0 findings into small reusable `CONTEXT_ARTIFACTS`.
+3. Build one `TASK_CONTEXT_BUNDLE` for the bounded task.
+4. If routing is not `CLAUDE`, execute CP2 with:
+   - a compressed original user request
+   - `CONTEXT_REFS` from the task-scoped bundle
+   - `HYDRATED_CONTEXT` snippets for that task only
+   - the CP1 task summary
+   - the explicit file set
+   - the success criteria and verify command for the bounded task
+5. Ask the worker to return complete final file content whenever practical, with unified diff patch as fallback, using External Response Protocol v1.1.
+6. Reuse `SESSION_ID` only for follow-up fixes on the same task, and send deltas only:
+   - changed refs
+   - new hydrated snippets
+   - updated verification failures or spec gaps
+7. If CP1 chose `Cross-Validation`, or CP2 returned conflicts, overlap, gaps, clarifications, or continuation requests, run CP3 Reconciliation as Claude's decision layer.
+8. Always run CP4 Final Spec Review after CP3, or directly after CP2/Claude-only work when no reconciliation is needed.
+9. Only `PASS` completes the task. `PARTIAL` and `FAIL` require a retry, follow-up, or user clarification.
 
 ## Hard Rules
 
 - Do not ask for draft code that the orchestrator will later re-implement.
 - Do not ask for design prose on an implementation task.
 - Do not restate the whole PRD, plan, or prior conversation in every prompt.
+- Do not repaste the full CP0 discovery output into every worker prompt.
 - Do not send multiple workers the same bounded implementation task.
+- Do not ask for changed hunks only when the worker can return the final file content directly.
+- Do not turn CP4 into a code-quality or best-practice review pass.
 
 ## Prompt Structure
 
 Every implementation prompt should contain:
 
 ```text
-## Task
+## Original User Request
+[original user request]
+
+## Task Context Bundle
+TASK_ID: [stable bounded-task id]
+
+## Context Refs
+- [artifact id]
+- [artifact id]
+
+## Hydrated Context
+[only the small context snippets needed to complete this bounded task]
+
+## CP1 Task Summary
 [single bounded task]
 
 ## Files
 [explicit file set]
 
-## Acceptance
+## Success Criteria
 [2-5 concrete checks]
 
 ## Verify
 [exact command]
 
 ## Response Protocol
-FIRST: Read Serena memory 'global/response_protocol' for full format rules.
-FALLBACK: Output only one of:
-1. ## DIFF → ## VERIFY → ## ISSUES
-2. ## QUESTIONS
+Use exactly this structure:
+
+# EXTERNAL RESPONSE PROTOCOL v1.1
+
+## SUMMARY
+[one sentence]
+
+## FILES MODIFIED
+| Action  | File Path          | Description of Change |
+|---------|--------------------|-----------------------|
+| Created | src/...            | ...                   |
+| Edited  | src/...            | ...                   |
+
+## FILE CONTENTS
+[complete final file content for each modified file, preferred; unified diff patch only when full content is impractical]
+
+## CONTEXT ARTIFACTS
+[optional reusable artifacts discovered or updated during execution]
+
+## SPEC COMPLIANCE
+- Meets Spec? YES / PARTIAL / NO
+- Explanation: ...
+
+## CLARIFICATIONS NEEDED
+None (or list questions)
+
+## NEXT STEPS / CONTINUATION
+TASK_COMPLETE / CONTINUE_SESSION / HANDOVER_TO_CLAUDE
 ```
 
 ## When To Cross-Validate
 
 Use `CROSS_VALIDATION` only for design arbitration or unresolved multi-domain ambiguity. When you do:
-- ask both models the same narrow question
-- compare only divergences
-- do not ask both to generate full implementations
+- keep the file set and success criteria narrow
+- compare only the meaningful divergences
+- return one reconciled artifact in External Response Protocol v1.1, not two unrelated implementations
+
+## CP4 Final Spec Review
+
+Claude performs CP4 in the main thread using:
+- the original user request
+- the CP1 task summary
+- the CP1 success criteria
+- the files modified by the workflow
+
+CP4 returns:
+- `PASS` when the implementation fully satisfies the spec
+- `PARTIAL` when some required behavior is missing or incomplete
+- `FAIL` when a core requirement is not satisfied