# Dynamic Methodology Composition

This workflow system doesn't follow a single rigid process. Behaviors activate based on what you're doing. The real workflow is a combination of **core practices** (always active, plugin-enforced) and **advanced rules** (opt-in, for complex projects).

## What's Always Active (Every Project)

These aren't in `.claude/rules/` — they work through the Superpowers plugin, the document hierarchy, and accumulated memory.

| Practice | Source | What it does |
|----------|--------|-------------|
| Document hierarchy | CLAUDE.md / SESSION.md / CONTEXT.md | Session continuity, project state |
| Brainstorming before building | Superpowers plugin | 2-3 approaches, tradeoffs, approval before code |
| TDD | Superpowers plugin | Failing test → implement → verify |
| Systematic debugging | Superpowers plugin | Reproduce → hypothesize → test → fix root cause |
| Verification before completion | Superpowers plugin | Evidence before assertions |
| Backup before edit | Global CLAUDE.md rule | .backup/ directory before modifications |
| Commit & push immediately | Convention | Every meaningful change, conventional commits |
| Pre-push secret scanning | Hook | Block pushes containing known secret values |
| Memory system | Claude Code built-in | Feedback corrections carry between sessions |

## How Core Practices Activate by Task Type

### Starting a New Feature

1. **Superpowers brainstorming** kicks in automatically
   - Clarify requirements → propose approaches → get approval → write spec
2. **Superpowers writing-plans** creates implementation plan
3. **Superpowers TDD** enforces test-first development
4. **Superpowers verification** requires evidence before claiming done
5. Commit with `feat:` message, push immediately

### Debugging a Bug

1. **Superpowers systematic-debugging** kicks in automatically
   - Reproduce → form hypotheses → test systematically → fix root cause
2. Add regression test
3. **Superpowers verification** confirms the fix
4. Commit with `fix:` message, push immediately

### Research / Investigation

1. Memory system provides prior context and feedback
2. Tiered documentation lookup (knowledge → lightweight fetch → heavy docs)
3. Persist findings to SESSION.md or docs/
4. Commit research artifacts with `docs:` message

### Code Review

1. **Superpowers code-review** activates after major steps
2. Reviews against original plan
3. Checks coding standards and security

### Writing a Paper / Design Doc

See `workflows/paper-writing.md` for the full process:
- Start from real problems (friction, not ambition)
- Bounce ideas before converging
- Capture the journey including dead ends

## What Advanced Rules Add (Complex Projects Only)

When `.claude/rules/` files are installed, they add explicit governance on top of the core practices:

| Rule | What it adds beyond core |
|------|------------------------|
| `01-session-discipline` | Formal session start/end protocol, handoff documents, wrap-up questions |
| `02-authority-hierarchy` | Explicit precedence: rules > plugins > instincts > defaults |
| `03-git-workflow` | Branch naming conventions, recovery commands, team collaboration rules |
| `04-proactive-steering` | Phase awareness, scope creep detection, conversation patterns, parallel execution |
| `05-reasoning-patterns` | Five Whys, first principles, Adopt/Extend/Compose/Build matrix, research quality rules |
| `06-context-management` | Thinking modes, token budget awareness, compaction decisions, execution readiness check |
| `07-security-hardening` | File deny lists, prompt injection guards, PR audit checklist, MCP server security |
| `08-code-quality` | Immutability principle, pre-completion checklist, task management conventions |
| `09-context-doc-maintenance` | Living document protocol, what goes where |

### When to Use Advanced Rules

Use them when:
- Multiple people or AI sessions work on the same project
- The project spans multiple domains (ML + infrastructure + web frontend)
- Mistakes are expensive (production systems, data-sensitive)
- You want explicit, enforceable conventions beyond what the plugin provides
- The project is complex enough that implicit conventions cause confusion

Don't use them when:
- It's a small, single-domain project
- You're the only one working on it
- The Superpowers plugin + document hierarchy is sufficient
- Adding governance would slow you down more than it helps

## Composition Example: Core-Only Project (Most Projects)

```
Session start:
  AI reads CLAUDE.md (auto-loaded)
  AI reads MEMORY.md (auto-loaded, feedback corrections)

User: "Add a caching layer for API responses"

  Superpowers brainstorming activates:
    → Clarify: what should be cached? TTL? Invalidation strategy?
    → Propose 2-3 approaches (Redis, in-memory, file-based)
    → Get approval

  Superpowers writing-plans activates:
    → Step-by-step implementation plan

  Superpowers TDD activates:
    → Write failing test for cache hit/miss
    → Implement cache
    → Write failing test for TTL expiry
    → Implement expiry

  Superpowers verification activates:
    → Run tests, show output
    → All green

  Commit: "feat: add Redis caching for API responses"
  Push immediately

  Update CLAUDE.md with new caching component
  Update SESSION.md with design decision
```

## Composition Example: Advanced Project (Mortdecai-tier)

```
Session start:
  01-session-discipline: Read CLAUDE.md, check latest handoff
  02-authority-hierarchy: Know what overrides what
  Memory system: Load feedback corrections

  04-proactive-steering: Assess project state
    → Phase: BUILDING
    → Current task: implement NPC trading system
    → No blockers

User: "Build the NPC trading system"

  05-reasoning-patterns + Superpowers brainstorming:
    → Clarify scope, research existing patterns
    → Brainstorm approaches
    → Apply Adopt/Extend/Compose/Build matrix

  06-context-management:
    → Check context budget before multi-task execution
    → Context at ~45%, proceed

  Superpowers TDD + 08-code-quality:
    → Test-first development
    → Immutability principle applied
    → Pre-completion checklist verified

  07-security-hardening:
    → Pre-commit security check
    → No hardcoded secrets

  03-git-workflow:
    → Feature branch: feature/npc-trading
    → Conventional commit: "feat(npc): add trading system"

  04-proactive-steering:
    → "Next: integration tests for trade transactions"

Session end:
  01-session-discipline: Wrap-up protocol
    → "Should anything be saved to memory?"
    → Write handoff if unfinished
```

## The Key Insight

Most of the workflow is **implicit** — driven by the Superpowers plugin, the document hierarchy, and accumulated feedback memories. The advanced rules are a **formalization** that only matters for complex projects where implicit conventions aren't enough.

If you're adopting this workflow, start with core practices only. Add rules when you feel the need for them — not preemptively.