feat: add core/ tier reflecting actual universal workflow
The original repo presented everything as equal rules. In reality, the workflow has two tiers: core practices (used in every project) and advanced rules (only in complex projects like Mortdecai). Core tier adds: - backup-before-edit (global CLAUDE.md rule) - superpowers-workflow (the actual workflow engine) - memory-system (persistent feedback and project memories) - document-hierarchy (CLAUDE.md/SESSION.md/CONTEXT.md/IDEA.md) - commit-and-push discipline - feedback-driven behaviors Updated README, docs, and dynamic-methodology to reflect the two-tier reality instead of presenting advanced rules as universal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,144 @@
|
||||
# Superpowers Plugin — The Actual Workflow Engine
|
||||
|
||||
The Superpowers plugin is not optional tooling — it's the primary workflow enforcement mechanism. It drives the day-to-day development cycle across all projects.
|
||||
|
||||
## What Superpowers Enforces
|
||||
|
||||
Superpowers provides a suite of skills that activate based on what you're doing. The AI assistant is required to invoke them — they're not suggestions.
|
||||
|
||||
### Brainstorming (before any creative work)
|
||||
|
||||
**Trigger:** Creating features, building components, adding functionality, or modifying behavior.
|
||||
|
||||
**What it does:**
|
||||
1. Explores the current project context (files, docs, commits)
|
||||
2. Asks clarifying questions one at a time
|
||||
3. Proposes 2-3 approaches with trade-offs and a recommendation
|
||||
4. Gets user approval before any code is written
|
||||
5. Writes a design spec
|
||||
6. Transitions to implementation planning
|
||||
|
||||
**Why it matters:** Without brainstorming, AI assistants jump to the first reasonable implementation. Brainstorming catches bad assumptions before code exists.
|
||||
|
||||
### Test-Driven Development (before writing implementation)
|
||||
|
||||
**Trigger:** Implementing any feature or bugfix.
|
||||
|
||||
**What it does:**
|
||||
1. Write a failing test first
|
||||
2. Implement the minimum code to pass the test
|
||||
3. Refactor if needed
|
||||
4. Repeat
|
||||
|
||||
**Enforcement:** If active, Superpowers will delete production code written without failing tests first. This is intentionally strict.
|
||||
|
||||
### Systematic Debugging (before proposing fixes)
|
||||
|
||||
**Trigger:** Any bug, test failure, or unexpected behavior.
|
||||
|
||||
**What it does:**
|
||||
1. Reproduce the issue
|
||||
2. Form hypotheses about root cause
|
||||
3. Test hypotheses systematically
|
||||
4. Fix the root cause, not the symptom
|
||||
5. Add regression test
|
||||
|
||||
**Why it matters:** Without this, AI assistants guess at fixes and retry until something works. Systematic debugging finds the actual problem.
|
||||
|
||||
### Verification Before Completion (before claiming done)
|
||||
|
||||
**Trigger:** About to claim work is complete, fixed, or passing.
|
||||
|
||||
**What it does:**
|
||||
1. Requires running verification commands (tests, build, lint)
|
||||
2. Requires confirming output — not just "tests passed" but showing the output
|
||||
3. Evidence before assertions, always
|
||||
|
||||
**Why it matters:** AI assistants will confidently claim "all tests pass" without running them. This forces actual verification.
|
||||
|
||||
### Code Review (after completing work)
|
||||
|
||||
**Trigger:** Major project step completed, implementation finished.
|
||||
|
||||
**What it does:**
|
||||
1. Reviews implementation against the original plan
|
||||
2. Checks coding standards
|
||||
3. Identifies issues, gaps, and improvements
|
||||
|
||||
### Writing Plans (before multi-step implementation)
|
||||
|
||||
**Trigger:** Multi-step task with a design spec ready.
|
||||
|
||||
**What it does:**
|
||||
1. Creates a step-by-step implementation plan
|
||||
2. Identifies critical files and dependencies
|
||||
3. Considers architectural trade-offs
|
||||
4. Provides review checkpoints
|
||||
|
||||
### Subagent-Driven Development (for parallel work)
|
||||
|
||||
**Trigger:** Implementation plan with independent tasks.
|
||||
|
||||
**What it does:**
|
||||
1. Dispatches independent tasks to parallel sub-agents
|
||||
2. Each agent works in isolation
|
||||
3. Results are reviewed and integrated
|
||||
|
||||
## The Actual Daily Cycle
|
||||
|
||||
For a typical feature, the real workflow is:
|
||||
|
||||
```
|
||||
1. User describes what they want
|
||||
2. Superpowers: brainstorming activates
|
||||
→ Clarify requirements
|
||||
→ Propose approaches
|
||||
→ Get approval
|
||||
→ Write spec
|
||||
3. Superpowers: writing-plans activates
|
||||
→ Create implementation plan
|
||||
4. Superpowers: test-driven-development activates
|
||||
→ Write failing test
|
||||
→ Implement
|
||||
→ Verify
|
||||
5. Superpowers: verification-before-completion activates
|
||||
→ Run tests, show output
|
||||
→ Confirm everything works
|
||||
6. Superpowers: code-review activates (if major step)
|
||||
→ Review against plan
|
||||
```
|
||||
|
||||
For a bugfix:
|
||||
```
|
||||
1. User reports bug
|
||||
2. Superpowers: systematic-debugging activates
|
||||
→ Reproduce → Hypothesize → Test → Fix
|
||||
3. Superpowers: verification-before-completion activates
|
||||
→ Run tests, confirm fix
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
claude plugin install superpowers
|
||||
```
|
||||
|
||||
Enable in `~/.claude/settings.json`:
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"superpowers@claude-plugins-official": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Relationship to Rules
|
||||
|
||||
Superpowers is the **enforcement layer** — it actively intervenes during work. The `.claude/rules/` files are the **governance layer** — they define conventions and decision frameworks. Most projects rely on Superpowers alone for workflow enforcement, without explicit rules files.
|
||||
|
||||
When both exist (like in advanced projects), the authority hierarchy applies:
|
||||
1. Rules (`.claude/rules/`) — highest
|
||||
2. Superpowers enforcement — second
|
||||
3. Learned patterns — third
|
||||
4. Defaults — lowest
|
||||
Reference in New Issue
Block a user