@complexthings/superpowers-agent 9.2.0 → 10.0.0

package/skills/collaboration/executing-plans/SKILL.md

@@ -1,130 +0,0 @@
----
-name: executing-plans
-description: Use when you have a written implementation plan to execute in a separate session with review checkpoints. Use this skill whenever a user opens a session with a plan file, says "execute this plan", "implement this plan", or hands you a plan document to work through. This is the parallel-session counterpart to subagent-driven-development — use it when the human wants to work in a separate context window with batch checkpoints rather than staying in the planning session.
-metadata:
-  when_to_use: when partner provides a complete implementation plan to execute in controlled batches with review checkpoints, in a separate session from where the plan was written
-  version: 2.3.0
----
-
-# Executing Plans
-
-## Overview
-
-Load plan, review critically, execute tasks in batches, report for review between batches.
-
-**Core principle:** Batch execution with checkpoints for architect review — you implement, then pause for human eyes before continuing.
-
-**Announce at start:** "I'm using the executing-plans skill to implement this plan."
-
-**Note:** This skill is designed for parallel sessions (no subagents). If you're in a session *with* subagents available, `subagent-driven-development` will give better results — fresh context per task and automated review gates. But if you're here, you're in the right place.
-
-```mermaid
-flowchart TD
-    LOAD[Load and review plan] --> CONCERN{Concerns?}
-    CONCERN -->|yes| ASK[Raise with partner]
-    ASK --> CONCERN
-    CONCERN -->|no| TODO[Create TodoWrite list]
-    TODO --> BATCH[Execute next batch of tasks]
-    BATCH --> VERIFY[Run verifications]
-    VERIFY --> REPORT[Report to partner]
-    REPORT --> FEEDBACK{Feedback?}
-    FEEDBACK -->|changes needed| APPLY[Apply changes]
-    APPLY --> BATCH
-    FEEDBACK -->|continue| MORE{More tasks?}
-    MORE -->|yes| BATCH
-    MORE -->|no| FINISH[Use finishing-a-development-branch]
-```
-
-## The Process
-
-### Step 1: Load and Review Plan
-
-1. Read plan file
-2. Review critically — identify any questions or concerns about the plan
-3. If concerns: Raise them with your human partner before starting
-4. If no concerns: Create TodoWrite with all tasks and proceed
-
-### Step 2: Execute Batch
-
-**Default: First 3 tasks** (adjust based on complexity — 1 for risky/complex tasks, up to 5 for simple/mechanical ones)
-
-If the plan already has chunk markers (`## Chunk N: ...`), use those as your batches.
-
-For each task in the batch:
-1. Mark as `in_progress`
-2. Follow each step exactly — the plan has bite-sized steps for a reason
-3. Run verifications as specified in the plan
-4. Mark as `completed`
-
-### Step 3: Report and Wait
-
-When the batch is complete, report clearly:
-
-```
-Batch complete:
-- Task N: [what was done, verification output]
-- Task N+1: [what was done, verification output]
-
-Ready for feedback.
-```
-
-Wait. Don't start the next batch until the partner responds.
-
-Apply any changes from feedback, then execute the next batch.
-
-### Step 4: Complete Development
-
-After all tasks complete and verified:
-- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
-- **REQUIRED SUB-SKILL:** Use `superpowers:finishing-a-development-branch`
-- Follow that skill to verify tests, present options, execute choice
-
-## When to Stop and Ask for Help
-
-**STOP executing immediately when:**
-- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
-- Plan has critical gaps preventing starting
-- You don't understand an instruction
-- Verification fails repeatedly (don't retry the same failing approach)
-
-**Ask for clarification rather than guessing.** The human wrote the plan — they know the intent.
-
-## When to Revisit Earlier Steps
-
-**Return to Review (Step 1) when:**
-- Partner updates the plan based on your feedback
-- Fundamental approach needs rethinking
-
-**Don't force through blockers** — stop and ask.
-
-## Batch Size Guidance
-
-The default of 3 tasks is a reasonable starting point, but adapt:
-
-| Situation | Batch size |
-|-----------|-----------|
-| Risky changes (migrations, deletes, auth) | 1 |
-| Complex multi-file tasks | 1–2 |
-| Standard implementation tasks | 3 (default) |
-| Simple mechanical tasks (config, docs) | 4–5 |
-| Plan has explicit chunk markers | Use chunks |
-
-## Remember
-
-- Review the plan critically before starting — questions are cheaper before code is written
-- Follow plan steps exactly — the plan was designed to be followed, not interpreted
-- Don't skip verifications — they exist to catch problems early
-- Reference skills when the plan says to
-- Between batches: report clearly, then wait for partner
-- Stop when blocked, don't guess or power through
-- Never start implementation on main/master branch without explicit user consent
-
-## Integration
-
-**Required workflow skills:**
-- **superpowers:using-git-worktrees** — REQUIRED: Set up isolated workspace before starting
-- **superpowers:writing-plans** — Creates the plan this skill executes
-- **superpowers:finishing-a-development-branch** — Complete development after all tasks
-
-**Alternative (same-session with subagents):**
-- **superpowers:subagent-driven-development** — Preferred when subagents are available; fresh context per task + automated two-stage review

package/skills/collaboration/executing-plans/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "2.3.0",
-    "name": "superpowers:collaboration/executing-plans",
-    "title": "Executing Plans",
-    "aliases": [
-        "executing-plans",
-        "collaboration/executing-plans"
-    ]
-}

package/skills/collaboration/finishing-a-development-branch/SKILL.md

@@ -1,261 +0,0 @@
----
-name: finishing-a-development-branch
-description: Use when implementation is complete and you need to decide how to integrate the work — guides completion of development work by running pre-merge checks, presenting structured options for merge, PR, or cleanup, and handling the chosen workflow including branch and worktree cleanup. Invoke this skill whenever a user says "I'm done", "implementation complete", "wrap up", "finish this branch", "create a PR", "merge to main", or "what do I do now that I'm done coding".
----
-
-# Finishing a Development Branch
-
-## Overview
-
-Guide completion of development work by running pre-merge checks, presenting clear options, and handling the chosen workflow.
-
-**Core principle:** Verify → Present options → Execute choice → Clean up.
-
-**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
-
-## The Process
-
-### Step 1: Pre-Flight Checks
-
-Before presenting options, run these checks in order. Stop and report on any failure.
-
-#### 1a. Clean working tree
-
-```bash
-git status --short
-```
-
-If there are uncommitted changes, ask: "There are uncommitted changes. Should I commit them, stash them, or discard them before proceeding?"
-
-Wait for answer before continuing.
-
-#### 1b. Run tests
-
-Discover the test command by checking `package.json`, `Makefile`, `pyproject.toml`, `.github/workflows/`, or the project's README. Common commands:
-
-```bash
-npm test          # Node.js
-cargo test        # Rust
-pytest            # Python
-go test ./...     # Go
-./gradlew test    # Gradle
-bundle exec rspec # Ruby
-```
-
-**If tests fail:**
-```
-Tests failing (<N> failures). Must fix before completing:
-
-[Show failures]
-
-Cannot proceed with merge/PR until tests pass.
-```
-
-Stop. Don't proceed to Step 2.
-
-**If tests pass:** Continue to Step 2.
-
-#### 1c. Check if branch is up-to-date
-
-```bash
-git fetch origin
-git rev-list --count HEAD..origin/<base-branch> 2>/dev/null
-```
-
-If the count is greater than 0, inform the user:
-```
-The base branch has <N> new commit(s) that aren't in this branch.
-Rebasing before merging will avoid hidden conflicts and keep history clean.
-```
-
-This is advisory, not blocking — proceed to Step 2 regardless.
-
-### Step 2: Determine Base Branch
-
-```bash
-# Check what branch this was created from
-git log --oneline HEAD ^main ^master 2>/dev/null | tail -1
-# Or check the most recent common ancestor
-git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
-```
-
-If ambiguous, ask: "What branch should I merge/PR into? (main, master, develop, etc.)"
-
-### Step 3: Present Options
-
-Present exactly these 4 options:
-
-```
-Implementation complete. What would you like to do?
-
-1. Merge back to <base-branch> locally
-2. Push and create a Pull Request
-3. Keep the branch as-is (I'll handle it later)
-4. Discard this work
-
-Which option?
-```
-
-Keep options concise — don't add explanation unless asked.
-
-### Step 4: Execute Choice
-
-#### Option 1: Merge Locally
-
-```bash
-# Switch to base branch and update
-git switch <base-branch>
-git pull --ff-only
-
-# Merge feature branch (use --no-ff to preserve branch history, or --squash for clean log)
-git merge <feature-branch>
-
-# Verify tests still pass on merged result
-<test command>
-
-# If tests pass: delete feature branch and prune stale refs
-git branch -d <feature-branch>
-git fetch --prune
-```
-
-Then: Cleanup worktree (Step 5)
-
-#### Option 2: Push and Create PR
-
-```bash
-# Push branch to remote
-git push -u origin <feature-branch>
-```
-
-Create PR with a meaningful description — fill in every section based on what was actually implemented:
-
-```bash
-gh pr create --title "<concise title describing the change>" --body "$(cat <<'EOF'
-## Summary
-- <what changed, bullet 1>
-- <why it exists, bullet 2>
-
-## Motivation
-<Why does this exist? Link related issues if applicable.>
-Closes #NNN
-
-## Testing
-<How was this verified? What edge cases were exercised?>
-
-## Reviewer Notes
-<What feedback do you want? Any design decisions to discuss?>
-EOF
-)"
-```
-
-Good PR titles are imperative and specific: `"Add retry logic to payment processor"` not `"fix stuff"`.
-After creating the PR, share the URL with the user.
-
-Then: Cleanup worktree (Step 5)
-
-#### Option 3: Keep As-Is
-
-Report: "Keeping branch `<name>`. Worktree preserved at `<path>`."
-
-**Don't cleanup worktree.**
-
-#### Option 4: Discard
-
-**Confirm first:**
-```
-This will permanently delete:
-- Branch <name>
-- All commits: <commit-list>
-- Worktree at <path> (if applicable)
-
-Type 'discard' to confirm.
-```
-
-Wait for exact typed confirmation.
-
-If confirmed:
-
-```bash
-git switch <base-branch>
-git branch -D <feature-branch>
-```
-
-Then: Cleanup worktree (Step 5)
-
-### Step 5: Cleanup Worktree
-
-First check whether this work is in a worktree or the main working directory:
-
-```bash
-git worktree list | grep "$(git branch --show-current)"
-```
-
-**If in a worktree (Options 1, 2, 4):**
-
-```bash
-git worktree remove <worktree-path>
-```
-
-**If not in a worktree:** No worktree cleanup needed — the work is in the main repo directory.
-
-**For Option 3:** Keep worktree regardless.
-
-## Quick Reference
-
-| Option | Merge | Push | Keep Worktree | Cleanup Branch |
-|--------|-------|------|---------------|----------------|
-| 1. Merge locally | ✓ | - | - | ✓ (+ prune) |
-| 2. Create PR | - | ✓ | - | - |
-| 3. Keep as-is | - | - | ✓ | - |
-| 4. Discard | - | - | - | ✓ (force) |
-
-## Common Mistakes
-
-**Skipping test verification**
-- Problem: Merge broken code, create a failing PR
-- Fix: Always verify tests before offering options
-
-**Skipping the clean working tree check**
-- Problem: Uncommitted work gets lost or included unexpectedly
-- Fix: `git status --short` first; resolve before proceeding
-
-**Not updating before merge**
-- Problem: Stale conflicts hide bugs introduced at merge time
-- Fix: Advisory check in Step 1c; encourage rebasing when base has moved
-
-**Open-ended questions**
-- Problem: "What should I do next?" leads to ambiguous answers
-- Fix: Present exactly 4 structured options
-
-**Not pruning remote-tracking refs**
-- Problem: Stale refs in `git branch -r` cause confusion about what exists
-- Fix: `git fetch --prune` after Option 1 merge
-
-**No confirmation for discard**
-- Problem: Accidentally deletes work
-- Fix: Require typed "discard" confirmation
-
-## Red Flags
-
-**Never:**
-- Proceed with uncommitted changes without user direction
-- Proceed with failing tests
-- Merge without verifying tests on the merged result
-- Delete work without confirmation
-- Force-push without explicit user request
-
-**Always:**
-- Check for uncommitted changes before anything else
-- Verify tests before offering options
-- Present exactly 4 options
-- Get typed confirmation for Option 4
-- Check for worktree vs. main working directory before cleanup
-
-## Integration
-
-**Called by:**
-- **subagent-driven-development** (Step 7) — After all tasks complete
-- **executing-plans** (Step 5) — After all batches complete
-
-**Pairs with:**
-- **using-git-worktrees** — Cleans up worktrees created by that skill

package/skills/collaboration/finishing-a-development-branch/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.1.0",
-    "name": "superpowers:collaboration/finishing-a-development-branch",
-    "title": "Finishing a Development Branch",
-    "aliases": [
-        "finishing-a-development-branch",
-        "collaboration/finishing-a-development-branch"
-    ]
-}

package/skills/collaboration/leveraging-cli-tools/scripts/slim.py

@@ -1,167 +0,0 @@
-#!/usr/bin/env python3
-"""slim - reduce noisy command output to signal before it reaches your context.
-
-A stdin->stdout filter for output you CAN'T shape with a tool's own flags:
-logs, scan results, status dumps, stack traces, repeated lines. For tools that
-already project output (jq/yq/dasel/miller/htmlq), use their selectors instead;
-piping them through slim is redundant.
-
-Pipe a verbose command through it and ask only for the reductions you need:
-
-    cargo test 2>&1 | slim --errors --dedup
-    rg -n TODO --no-ignore | slim --group-dir
-    gh run view --log | slim --uniq --max-line 200 --middle 40
-    kubectl get events | slim --dedup --stats
-
-Reductions (compose freely):
-  --comments        drop comment-only lines (# // ; -- *) and blank lines
-  --errors          keep only lines matching error|warn|fail|fatal|panic|exception (-i)
-  --grep RE         keep only lines matching regex RE (use --invert to drop them)
-  --invert          invert --grep / --errors (drop matches instead of keeping)
-  --dedup           collapse ALL repeated lines, first-seen order, annotate "  (xN)"
-  --uniq            collapse only CONSECUTIVE repeats, annotate "  (xN)" (log-friendly)
-  --group-dir       turn a list of file paths into per-directory counts
-  --max-line N      truncate each line to N chars, append a horizontal ellipsis
-  --head N          keep first N lines
-  --tail N          keep last N lines
-  --middle N        keep first N and last N lines, replace the gap with a marker
-  --stats           print "lines A->B, bytes A->B (-P%)" to stderr (output unaffected)
-
-Always-on, lossless: trailing whitespace is stripped and runs of blank lines
-collapse to one. Everything lossy is opt-in. Order: filter -> transform ->
-dedup -> group -> blank-collapse -> truncate. Reductions are LOSSY by design;
-ask for what the task needs and know what you're discarding.
-"""
-import argparse
-import re
-import sys
-
-COMMENT_RE = re.compile(r"^\s*(#|//|;|--|\*|/\*|\*/)")
-ERROR_RE = re.compile(r"error|warn|fail|fatal|panic|exception|traceback", re.IGNORECASE)
-ELLIPSIS = "…"
-
-
-def annotate(line: str, n: int) -> str:
-    return line if n == 1 else f"{line}  (x{n})"
-
-
-def dedup_all(lines):
-    counts, order = {}, []
-    for ln in lines:
-        if ln not in counts:
-            counts[ln] = 0
-            order.append(ln)
-        counts[ln] += 1
-    return [annotate(ln, counts[ln]) for ln in order]
-
-
-def dedup_adjacent(lines):
-    out, prev, n = [], None, 0
-    for ln in lines:
-        if ln == prev:
-            n += 1
-        else:
-            if prev is not None:
-                out.append(annotate(prev, n))
-            prev, n = ln, 1
-    if prev is not None:
-        out.append(annotate(prev, n))
-    return out
-
-
-def group_dir(lines):
-    counts, order = {}, []
-    for ln in lines:
-        token = ln.split(":", 1)[0].strip()  # tolerate rg's path:line: prefix
-        d = token.rsplit("/", 1)[0] + "/" if "/" in token else "./"
-        if d not in counts:
-            counts[d] = 0
-            order.append(d)
-        counts[d] += 1
-    width = max((len(d) for d in order), default=0)
-    return [f"{d.ljust(width)}  ({counts[d]} file{'s' if counts[d] != 1 else ''})" for d in order]
-
-
-def collapse_blanks(lines):
-    out, blank = [], False
-    for ln in lines:
-        if ln.strip() == "":
-            if not blank:
-                out.append("")
-            blank = True
-        else:
-            out.append(ln)
-            blank = False
-    while out and out[-1] == "":
-        out.pop()
-    return out
-
-
-def main() -> int:
-    p = argparse.ArgumentParser(add_help=True, description="Reduce noisy stdout to signal.")
-    p.add_argument("--comments", action="store_true")
-    p.add_argument("--errors", action="store_true")
-    p.add_argument("--grep", metavar="RE")
-    p.add_argument("--invert", action="store_true")
-    p.add_argument("--dedup", action="store_true")
-    p.add_argument("--uniq", action="store_true")
-    p.add_argument("--group-dir", action="store_true")
-    p.add_argument("--max-line", type=int, metavar="N")
-    p.add_argument("--head", type=int, metavar="N")
-    p.add_argument("--tail", type=int, metavar="N")
-    p.add_argument("--middle", type=int, metavar="N")
-    p.add_argument("--stats", action="store_true")
-    args = p.parse_args()
-
-    raw = sys.stdin.read()
-    in_lines = raw.splitlines()
-    in_bytes = len(raw.encode("utf-8", "replace"))
-
-    lines = [ln.rstrip() for ln in in_lines]
-
-    if args.comments:
-        lines = [ln for ln in lines if ln.strip() and not COMMENT_RE.match(ln)]
-
-    if args.errors or args.grep:
-        pat = re.compile(args.grep) if args.grep else ERROR_RE
-        keep = (lambda ln: not pat.search(ln)) if args.invert else (lambda ln: bool(pat.search(ln)))
-        lines = [ln for ln in lines if keep(ln)]
-
-    if args.max_line and args.max_line > 0:
-        lines = [ln if len(ln) <= args.max_line else ln[: args.max_line] + ELLIPSIS for ln in lines]
-
-    if args.dedup:
-        lines = dedup_all(lines)
-    elif args.uniq:
-        lines = dedup_adjacent(lines)
-
-    if args.group_dir:
-        lines = group_dir(lines)
-
-    lines = collapse_blanks(lines)
-
-    if args.middle and args.middle > 0 and len(lines) > 2 * args.middle:
-        omitted = len(lines) - 2 * args.middle
-        lines = lines[: args.middle] + [f"{ELLIPSIS} {omitted} lines omitted {ELLIPSIS}"] + lines[-args.middle :]
-    if args.head and args.head > 0:
-        lines = lines[: args.head]
-    if args.tail and args.tail > 0:
-        lines = lines[-args.tail :]
-
-    out = "\n".join(lines)
-    if out:
-        out += "\n"
-    sys.stdout.write(out)
-
-    if args.stats:
-        out_bytes = len(out.encode("utf-8", "replace"))
-        pct = 0 if in_bytes == 0 else round(100 * (1 - out_bytes / in_bytes))
-        change = f"-{pct}%" if pct >= 0 else f"+{-pct}% larger"
-        sys.stderr.write(
-            f"slim: lines {len(in_lines)}->{len(lines)}, bytes {in_bytes}->{out_bytes} ({change})\n"
-        )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())