diff --git a/specs/superpowers-analysis.md b/specs/superpowers-analysis.md deleted file mode 100644 index c22229f30..000000000 --- a/specs/superpowers-analysis.md +++ /dev/null @@ -1,149 +0,0 @@ -# Spec: Superpowers Pattern Analysis - -Extracted from `docs/superpowers/plans/` (now deleted) and external -research. This spec documents what superpowers is, how it overlaps -with ctx, and which patterns are worth adopting natively. - ---- - -## What is Superpowers? - -[obra/superpowers](https://github.com/obra/superpowers) is an -open-source Claude Code plugin by Jesse Vincent. It installs as a -skill pack via the Anthropic plugin marketplace and enforces a rigid -workflow: brainstorm, plan, execute (with subagents), review. - -**Distribution:** Claude Code plugin marketplace (`obra/superpowers`). -Also ported to Google Antigravity IDE, OpenCode, GitHub Copilot CLI, -Gemini CLI. - -**Mechanism:** Each skill is a `SKILL.md` file with YAML frontmatter -(metadata, triggers, tool permissions) and Markdown instructions. -Skills auto-activate based on context. The `using-superpowers` -meta-skill enforces that if any skill applies, the agent must use it. - ---- - -## Skill Overlap - -| Capability | ctx | Superpowers | -|---|---|---| -| Design-before-code | `/ctx-brainstorm` | `brainstorms` | -| Plan writing | `/ctx-spec` | `writing-plans` | -| Plan execution | `/ctx-implement` | `executing-plans` | -| Subagent dispatch | `/ctx-worktree` | `subagent-driven-development` | -| Git worktrees | `/ctx-worktree` | `using-git-worktrees` | -| Code review | `/ctx-code-review` | `requesting-code-review` | -| TDD workflow | `/ctx-refactor` | `test-driven-development` | -| Debugging | `gitnexus-debugging` | `systematic-debugging` | -| Skill creation | `/ctx-skill-creator` | `writing-skills` | - -**Key difference:** Superpowers is a pure instruction layer (no -runtime, no persistence, no CLI). ctx is a full system with CLI, -state management, persistence, and skills. Superpowers tells the -agent *how to work*; ctx gives the agent *tools and memory*. - ---- - -## Patterns Worth Adopting - -### 1. Micro-task decomposition (from `writing-plans`) - -Superpowers enforces 2-5 minute tasks with exact file paths and -verification steps. ctx's `/ctx-implement` already does stepwise -execution, but the explicit time-boxing and mandatory verification -step per task is worth codifying. - -**Action:** Consider adding a verification checkpoint to each step -in `/ctx-implement` plans. Currently steps are executed sequentially -but verification is ad-hoc. - -### 2. Subagent isolation (from `subagent-driven-development`) - -Each task gets a fresh subagent with no prior context bleed. The -subagent receives only the task description, relevant file paths, -and the plan. This prevents context pollution across tasks. - -**Action:** `/ctx-worktree` already uses git worktrees for isolation. -The pattern of giving each subagent a minimal context packet (not -the full conversation) is the valuable idea. Could improve agent -dispatch prompts. - -### 3. Two-stage review (from `requesting-code-review`) - -After implementation, two review passes: (1) spec compliance — does -it match the plan? (2) code quality — is it well-written? Separating -these prevents quality concerns from masking spec violations. - -**Action:** `/ctx-code-review` currently does a single-pass review. -Consider structuring it as two explicit passes. - -### 4. Mandatory skill activation (from `using-superpowers`) - -A meta-skill that enforces: if a skill applies, the agent must use -it. Prevents the agent from doing ad-hoc work when a structured -skill exists. - -**Action:** ctx already has skill trigger detection in skill -descriptions. The gap is enforcement — agents can ignore triggers. -The AGENT_PLAYBOOK already says "check available skills" but doesn't -mandate usage. - -### 5. Observe-failure-first TDD (from `test-driven-development`) - -Superpowers enforces that the agent must *observe* the test failing -before writing implementation. It will delete code written before -tests. This is stricter than ctx's test-first guidance. - -**Action:** `/ctx-refactor` already says test-first. The -observe-failure step is the useful addition — ensure the red phase -is verified, not just written. - ---- - -## Patterns to Avoid - -### Token-hungry brainstorming - -Superpowers brainstorms spawn parallel agents for exploration, -consuming large token budgets. ctx's `/ctx-brainstorm` is -conversation-based and cheaper. The parallel exploration approach -is expensive without proportional value for most tasks. - -### Rigid workflow enforcement - -Superpowers mandates brainstorm-before-any-code, even for trivial -fixes. ctx should remain flexible — structured workflows for complex -work, direct execution for simple changes. - -### Competing meta-skills - -Installing superpowers alongside ctx creates conflicting skill -triggers (both have brainstorm, review, worktree skills). The -systems are not designed to coexist. - ---- - -## How Superpowers Arrived in This Repo - -Murat Parlakisik's feature branch merge (`1d05145e`, 2026-04-03) -included `docs/superpowers/plans/2026-03-31-commit-context-tracing.md` -— an 88KB implementation plan generated by the superpowers -`writing-plans` skill. The plan assumed superpowers was the execution -engine (header: "REQUIRED SUB-SKILL: Use -superpowers:subagent-driven-development"). - -The feature it planned (commit context tracing) already had a proper -ctx-native spec at `specs/commit-context-tracing.md`. The superpowers -plan was redundant and introduced an external dependency. - -**Resolution:** Superpowers plan file deleted. This analysis spec -preserves the useful patterns. The commit-context-tracing feature -proceeds from its existing ctx-native spec. - ---- - -## Status - -Analysis complete. No action items created — patterns noted above -are candidates for future skill improvements, not immediate work.