@nst173/superpowers-ccg 1.3.0

package/skills/EVALUATION.md

@@ -0,0 +1,201 @@
+# Skills Evaluation Scenarios
+
+Use evaluation scenarios (per Anthropic best practices) to validate skill effectiveness.
+
+## Evaluation Format
+
+```json
+{
+  "skill": "skill-name",
+  "query": "User request",
+  "context": "Optional context file",
+  "expected_behavior": [
+    "Expected behavior 1",
+    "Expected behavior 2"
+  ]
+}
+```
+
+## 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
+
+```json
+{
+  "skill": "debugging-systematically",
+  "query": "Tests are failing, please take a look",
+  "context": "npm test output shows 3 test failures",
+  "expected_behavior": [
+    "Phase 1: Carefully read the error messages before proposing fixes",
+    "Try to reproduce the issue",
+    "Check recent code changes",
+    "Phase 2: Compare with similar working code",
+    "Phase 3: Form a single hypothesis and minimize the test",
+    "Phase 4: Write a failing test before fixing"
+  ]
+}
+```
+
+```json
+{
+  "skill": "debugging-systematically",
+  "query": "Build failed and I can't understand the error",
+  "expected_behavior": [
+    "Do not guess a fix immediately",
+    "Carefully read the full error message and stack trace",
+    "If multiple components are involved, add diagnostic logs to isolate the layer",
+    "Form a hypothesis before proposing a fix"
+  ]
+}
+```
+
+### verifying-before-completion
+
+```json
+{
+  "skill": "verifying-before-completion",
+  "query": "Fix this bug and then commit",
+  "expected_behavior": [
+    "Run tests after the fix",
+    "Show test output proving success",
+    "Only claim 'fixed' after seeing passing evidence",
+    "Avoid vague wording like 'should work' or 'should pass'"
+  ]
+}
+```
+
+### brainstorming
+
+```json
+{
+  "skill": "brainstorming",
+  "query": "I want to add user authentication",
+  "expected_behavior": [
+    "Understand the current project state first (files, docs, recent commits)",
+    "Ask one question at a time",
+    "Prefer multiple-choice questions",
+    "Propose 2-3 different approaches with trade-offs",
+    "Present the design in sections and confirm after each"
+  ]
+}
+```
+
+### executing-plans
+
+```json
+{
+  "skill": "executing-plans",
+  "query": "Execute the plan in docs/plans/feature.md",
+  "expected_behavior": [
+    "Read the plan first and review it critically",
+    "Ask questions before starting if anything is unclear",
+    "Use a checklist to track progress",
+    "Report after each batch and wait for feedback",
+    "Do not skip verification steps in the plan"
+  ]
+}
+```
+
+### developing-with-subagents
+
+```json
+{
+  "skill": "developing-with-subagents",
+  "query": "Execute this plan using subagents",
+  "context": "docs/plans/feature.md",
+  "expected_behavior": [
+    "Read the plan once and extract all tasks",
+    "Dispatch a separate subagent for each task",
+    "Answer subagent questions before proceeding",
+    "Run spec review before code quality review",
+    "Iterate on fixes until the reviewer passes"
+  ]
+}
+```
+
+## 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
+
+1. Run the query without the skill and record behavior
+2. Enable the skill and run the same query
+3. Compare behavior against expected_behavior
+4. Record differences and iterate on the skill

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: brainstorming
+description: "Explores user intent, requirements and design through collaborative dialogue before implementation. Use when: creating features, building components, adding functionality, modifying behavior, or starting any creative work. Keywords: design, requirements, spec, ideation, planning"
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## Protocol Threshold (Required)
+
+Follow `skills/shared/protocol-threshold.md`. The hook injects CP reminders automatically.
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Model tip for exploration:** When dispatching subagents to explore the codebase, use `model: haiku` for fast, cost-effective searches. Haiku excels at file pattern matching and quick lookups.
+
+**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.
+- See `skills/shared/supplementary-tools.md` for full reference.
+
+**► CP1 (Task Analysis):** After understanding the idea, apply `coordinating-multi-model-work/checkpoints.md`.
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- 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`.
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation (must not be skipped):**
+
+Once the user confirms the design looks right, do ALL of the following:
+
+1. Ensure the output directory exists (create `docs/plans/` if missing)
+2. Write the final design content to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+3. Then tell the user the file path you wrote
+
+Only commit if the user explicitly asks you to commit.
+
+**Native Task Integration (must not be skipped):**
+
+After each design section is confirmed by the user, create a native task using Claude Code's TaskCreate tool. Follow the format in `skills/shared/task-format-reference.md`.
+
+~~~yaml
+TaskCreate:
+  subject: "Implement [Component Name]"
+  description: |
+    **Goal:** [What this component produces — one sentence]
+
+    **Files:**
+    - Create/Modify: [paths identified during design]
+
+    **Acceptance Criteria:**
+    - [ ] [Criterion from design validation]
+    - [ ] [Criterion from design validation]
+
+    **Verify:** [How to test this component works]
+
+    ```json:metadata
+    {"files": ["path/from/design"], "verifyCommand": "command to verify", "acceptanceCriteria": ["criterion 1", "criterion 2"]}
+    ```
+  activeForm: "Implementing [Component Name]"
+~~~
+
+Track all returned task IDs.
+
+After **all** components are validated, wire dependency relationships:
+
+~~~yaml
+TaskUpdate:
+  taskId: [dependent-task-id]
+  addBlockedBy: [prerequisite-task-ids]
+~~~
+
+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
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Multi-Model Design Validation
+
+See `skills/shared/multi-model-integration-section.md` for routing, invocation, and fallback rules.

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

@@ -0,0 +1,36 @@
+# Multi-Model Gate (Fail-Closed)
+
+Use this gate whenever a skill decides **Routing != CLAUDE** (`CODEX`, `GEMINI`, or `CROSS_VALIDATION`).
+
+## 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`.
+- If you cannot obtain required external output, stop in `BLOCKED`.
+
+## Evidence Requirement
+
+```text
+[Multi-Model Gate]
+Routing: CODEX | GEMINI | CROSS_VALIDATION
+Why: <one sentence>
+
+Evidence (Implementation):
+- Tool: mcp__codex__codex | mcp__gemini__gemini
+- Params: <key MCP parameters used>
+- Result: <3-6 bullets>
+
+Evidence (Opus Review):
+- Reviewer: Opus
+- Artifact: <commit SHA>
+- Result: <3-6 bullets>
+```
+
+## Failure Handling
+
+```text
+[Multi-Model Gate]
+Routing: CODEX | GEMINI | CROSS_VALIDATION
+Status: BLOCKED
+Reason: timeout | tool-unavailable | permission-blocked | other
+```

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

@@ -0,0 +1,51 @@
+# Multi-Model Integration Guide
+
+Claude is orchestrator-only. All implementation code goes through external models.
+
+## 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.
+
+## 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 send multiple workers the same bounded implementation task.
+
+## Prompt Structure
+
+Every implementation prompt should contain:
+
+```text
+## Task
+[single bounded task]
+
+## Files
+[explicit file set]
+
+## Acceptance
+[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
+```
+
+## 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

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

@@ -0,0 +1,51 @@
+---
+name: coordinating-multi-model-work
+description: "Routes bounded implementation tasks to Codex (backend and systems) or Gemini (frontend) via MCP tools. Claude is orchestrator-only and should stay out of the implementation hot path. Use when: implementation, debugging, refactoring, UI work, APIs, databases, scripts, CI/CD, or cross-model arbitration."
+---
+
+# Coordinating Multi-Model Work
+
+## Overview
+
+Claude is the orchestrator. It routes tasks, coordinates workers, and integrates results, but never writes implementation code.
+
+Use this module to route one bounded task at a time:
+- **Codex** — backend and systems
+- **Gemini** — frontend
+
+## Core Rules
+
+1. Reduce the current work to one bounded task with a clear file set and verification command.
+2. Route that bounded task to exactly one worker unless there is real architectural uncertainty.
+3. Reuse the same worker `SESSION_ID` for follow-up fixes on that task.
+4. Ask for `diff-or-questions`, not prototypes, essays, or full rewrites.
+5. After the worker completes, review the artifact with Opus.
+
+## Cross-Validation
+
+`CROSS_VALIDATION` is rare. Use it only when:
+- the task genuinely spans frontend and backend at the same time, or
+- two viable designs remain after scope reduction, or
+- the failure mode is still ambiguous after one worker pass.
+
+Do not use cross-validation as the default for ordinary implementation work.
+
+## Checkpoint Workflow
+
+At CP1, CP2, and CP3:
+1. Decide routing
+2. Apply `GATE.md`
+3. Continue only with evidence
+
+## Response Protocol
+
+All external model prompts must reference Serena memory `global/response_protocol`.
+
+## Reference Files
+
+- `coordinating-multi-model-work/checkpoints.md`
+- `coordinating-multi-model-work/routing-decision.md`
+- `coordinating-multi-model-work/GATE.md`
+- `coordinating-multi-model-work/INTEGRATION.md`
+- `coordinating-multi-model-work/review-chain.md`
+- `coordinating-multi-model-work/cross-validation.md`

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

@@ -0,0 +1,31 @@
+# Collaboration Checkpoints
+
+## Overview
+
+Checkpoints exist to control routing and keep the orchestrator thread small.
+
+## CP1: Task Analysis
+
+- Reduce the work to one bounded task.
+- Prefer one worker.
+- Record routing in one short block.
+
+## CP2: Mid-Review
+
+Trigger only when:
+- 2 or more attempts have failed on the same bounded task
+- the worker returns blocking questions
+- the task still has unresolved cross-domain ambiguity
+
+Before escalating to `CROSS_VALIDATION`, first narrow the task further or split it.
+
+## CP3: Quality Gate
+
+- Review the artifact, not the whole session narrative.
+- If code changed, run the Opus review chain.
+- If no code changed, skip quality review.
+
+## User Override
+
+- "Use Codex" / "Use Gemini" / "Cross-validate" force corresponding routing.
+- "Do not use external models" forces `CLAUDE` for docs and coordination only.

package/skills/coordinating-multi-model-work/cross-validation.md

@@ -0,0 +1,37 @@
+# Cross-Validation Mechanism
+
+Cross-validation is for arbitration, not for routine implementation.
+
+## Use It Only When
+
+- the task has unavoidable frontend and backend coupling
+- two competing designs remain after scope reduction
+- one worker pass did not remove the ambiguity
+
+## Do Not Use It When
+
+- one worker can own the task cleanly
+- you only want a prototype or a second opinion
+- the implementation can be split into smaller bounded tasks
+
+## Pattern
+
+1. Ask Codex and Gemini the same narrow question.
+2. Collect concise answers.
+3. Compare only the disagreements.
+4. Choose a direction.
+5. Route implementation to one worker.
+
+## Output
+
+```markdown
+## Cross-Validation Summary
+
+**Agreement:** [shared conclusions]
+
+**Divergences:**
+| Aspect | Codex | Gemini | Resolution |
+|--------|-------|--------|------------|
+
+**Next worker:** [CODEX or GEMINI]
+```

package/skills/coordinating-multi-model-work/prompts/codex-base.md

@@ -0,0 +1,40 @@
+# Codex Base Prompt Templates
+
+> Invoke via `mcp__codex__codex`.
+> All prompts in English.
+
+## Bounded Implementation Template
+
+```text
+## Task
+{task_description}
+
+## Files
+{file_list}
+
+## Acceptance
+{acceptance_criteria}
+
+## Verify
+{verify_command}
+
+## Response Protocol
+FIRST: Read Serena memory 'global/response_protocol' for full format rules.
+FALLBACK: Return exactly one of:
+1. ## DIFF → ## VERIFY → ## ISSUES
+2. ## QUESTIONS
+```
+
+## Narrow Analysis Template
+
+```text
+## Question
+{narrow_question}
+
+## Files
+{file_list}
+
+## Response Protocol
+FIRST: Read Serena memory 'global/response_protocol' for full format rules.
+FALLBACK: Output ## ANALYSIS (<=120 words) → ## ISSUES (<=3) → ## VERDICT (one line).
+```

package/skills/coordinating-multi-model-work/prompts/gemini-base.md

@@ -0,0 +1,41 @@
+# Gemini Base Prompt Templates
+
+> Invoke via `mcp__gemini__gemini`.
+> All prompts in English.
+> Keep prompts narrow.
+
+## Bounded Implementation Template
+
+```text
+## Task
+{task_description}
+
+## Files
+{file_list}
+
+## Acceptance
+{acceptance_criteria}
+
+## Verify
+{verify_command}
+
+## Response Protocol
+FIRST: Read Serena memory 'global/response_protocol' for full format rules.
+FALLBACK: Return exactly one of:
+1. ## DIFF → ## VERIFY → ## ISSUES
+2. ## QUESTIONS
+```
+
+## Narrow Analysis Template
+
+```text
+## Question
+{narrow_question}
+
+## Files
+{file_list}
+
+## Response Protocol
+FIRST: Read Serena memory 'global/response_protocol' for full format rules.
+FALLBACK: Output ## ANALYSIS (<=120 words) → ## ISSUES (<=3) → ## VERDICT (one line).
+```

package/skills/coordinating-multi-model-work/review-chain.md

@@ -0,0 +1,25 @@
+# Review Chain (Canonical Reference)
+
+This is the single source of truth for the review chain rule.
+
+## The Rule
+
+```text
+FinalArbiter = Opus
+```
+
+## What This Means
+
+| Implementer | Reviewer |
+|-------------|----------|
+| Codex | Opus |
+| Gemini | Opus |
+| Docs-only | Skip |
+
+## Key Rules
+
+- Opus has final say on every code-changing path.
+- All implementers are reviewed directly by Opus.
+- If Opus is unavailable for a code-changing path: `BLOCKED`.
+- Max 3 fix-review loops before escalating to the user.
+- Docs-only changes are exempt from quality review.

package/skills/coordinating-multi-model-work/routing-decision.md

@@ -0,0 +1,50 @@
+# Routing Decision Framework
+
+## Overview
+
+This framework guides Claude in making semantic routing decisions for multi-model task distribution.
+
+## When to Use
+
+Invoke this framework when a skill needs to call external models (Codex/Gemini) via the MCP tools (`mcp__codex__codex`, `mcp__gemini__gemini`).
+
+## Decision Output
+
+```text
+**Routing Decision:** [CODEX | GEMINI | CROSS_VALIDATION | CLAUDE]
+**Rationale:** [One sentence]
+```
+
+## Routing Targets
+
+- **CODEX** - Backend and systems expert for APIs, databases, algorithms, server-side logic, CI/CD, scripts, Dockerfiles, infrastructure, and repo tooling
+- **GEMINI** - Frontend expert for UI, components, styles, interactions
+- **CROSS_VALIDATION** - Multiple models for full-stack tasks, architectural decisions, or high uncertainty (Codex + Gemini)
+- **CLAUDE** - Orchestrator only: routing decisions, coordination, documentation edits
+
+## Decision Guidelines
+
+- Strong backend or systems signals and weak/no frontend signals → **CODEX**
+- Strong frontend signals and weak/no backend signals → **GEMINI**
+- Strong signals in both domains or high uncertainty → **CROSS_VALIDATION**
+- Documentation-only or pure coordination → **CLAUDE**
+
+## File Extension Heuristics
+
+| File Pattern | Default Routing |
+|-------------|----------------|
+| `**/*.go`, `**/*.py`, `**/*.sql` | CODEX |
+| `**/*.sh`, `**/*.yml`, `Dockerfile`, `Makefile`, `**/*.tf` | CODEX |
+| `**/*.tsx`, `**/*.css`, `**/*.html` | GEMINI |
+| Mixed frontend + backend | CROSS_VALIDATION |
+| `**/*.md` (docs only, no code) | CLAUDE |
+
+## Example
+
+**Input:** "Fix the flaky test in CI pipeline"
+
+**Output:**
+```text
+**Routing Decision:** CODEX
+**Rationale:** CI/CD pipeline task with clear systems and automation signals
+```