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>

CLAUDE.md

@@ -4,13 +4,28 @@ This repository contains a shareable AI-assisted development workflow. It is a r
 
 ## What This Is
 
-A collection of rules, templates, hooks, and methodology guides for working with AI coding assistants (Claude Code, etc.). The rules in `rules/` are designed to be copied into `.claude/rules/` in any project.
+A two-tier workflow system for AI coding assistants (Claude Code, etc.), reflecting how the workflow is actually used across 26+ projects.
+
+## Two Tiers
+
+### Core (every project)
+The `core/` directory describes the practices that run universally:
+- **Document hierarchy** — CLAUDE.md / SESSION.md / CONTEXT.md / IDEA.md
+- **Superpowers plugin** — The workflow engine (brainstorming, TDD, debugging, verification)
+- **Memory system** — Persistent feedback and project memories across sessions
+- **Backup before edit** — .backup/ directory before any modification
+- **Commit & push** — Every change, immediately, conventional commits
+- **Feedback behaviors** — Learned corrections and confirmed approaches
+
+### Advanced (complex projects only)
+The `rules/` directory contains `.claude/rules/` files for projects that need explicit governance beyond what the core provides.
 
 ## Structure
 
 | Directory | Purpose |
 |-----------|---------|
-| `rules/` | Core behavior rules (copy to `.claude/rules/`) |
+| `core/` | Universal practices (every project) |
+| `rules/` | Advanced governance rules (copy to `.claude/rules/`) |
 | `templates/` | File templates for bootstrapping new projects |
 | `hooks/` | Claude Code hooks (pre-push secret scanning) |
 | `settings/` | Example Claude Code configuration |
@@ -20,6 +35,6 @@ A collection of rules, templates, hooks, and methodology guides for working with
 ## Conventions
 
 - Conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
-- All rules are self-contained markdown files with no external dependencies
+- All files are self-contained markdown with no external dependencies
 - Templates use `<placeholder>` syntax for values the user fills in
 - No credentials, IPs, or personal information anywhere in this repo

README.md

@@ -4,76 +4,100 @@ A battle-tested AI-assisted development workflow distilled from 26+ projects acr
 
 This isn't a theoretical framework. Every rule here exists because something broke without it.
 
-## Philosophy
+## Two Tiers: Core + Advanced
 
-1. **Dynamic composition** — Rules activate based on what you're doing, not a rigid pipeline. Debugging pulls in Five Whys. New features pull in brainstorming + TDD. Research pulls in the paper-writing workflow.
-2. **Session discipline** — AI assistants forget between sessions. Files are the memory. If it's not written down, it doesn't exist next session.
-3. **Proactive steering** — The AI should be a co-pilot, not a passive tool. It should know where the project is, suggest next steps, and detect when you're stuck.
-4. **Security by default** — Secrets scanning, deny lists, and injection guards are not optional add-ons.
-5. **Context is finite** — Token budgets are real. Tiered documentation lookup, sub-agent delegation, and session management all exist to work within that constraint.
+This workflow has two tiers that reflect how it's actually used:
+
+### Core (used in every project)
+
+The **core/** directory contains what actually runs across all 26+ projects. No `.claude/rules/` files needed — these behaviors come from the document hierarchy, the Superpowers plugin, the memory system, and accumulated feedback.
+
+| Practice | File | What it does |
+|----------|------|-------------|
+| Document hierarchy | `core/document-hierarchy.md` | CLAUDE.md + SESSION.md + CONTEXT.md + IDEA.md |
+| Superpowers plugin | `core/superpowers-workflow.md` | Brainstorming, TDD, debugging, verification, code review |
+| Memory system | `core/memory-system.md` | Persistent feedback and project memories across sessions |
+| Backup before edit | `core/backup-before-edit.md` | .backup/ directory before any file modification |
+| Commit & push | `core/commit-and-push.md` | Commit every change, push immediately, conventional commits |
+| Feedback behaviors | `core/feedback-driven-behaviors.md` | Learned corrections and confirmed approaches |
+
+### Advanced (for complex, multi-domain projects)
+
+The **rules/** directory contains formalized governance rules from the most mature project implementation. These are `.claude/rules/` files that auto-load at session start and provide explicit, enforceable conventions.
+
+Most projects don't need these. Use them when a project is complex enough that implicit conventions aren't sufficient — when multiple people work on it, when it spans multiple domains, or when mistakes are expensive.
 
 ## Quick Start
 
-### 1. Copy rules to your project
+### Minimum viable workflow (Core only)
+
+1. **Install the Superpowers plugin:**
+   ```bash
+   claude plugin install superpowers
+   ```
+
+2. **Set up your project documents:**
+   ```bash
+   cp templates/CLAUDE.md ./CLAUDE.md    # Project instructions (fill in)
+   cp templates/SESSION.md ./SESSION.md  # AI memory (grows over time)
+   ```
+
+3. **Add backup-before-edit to your global instructions:**
+   Add to `~/.claude/CLAUDE.md`:
+   ```
+   Before editing any file, back up the original to a .backup/ directory in the same parent folder.
+   ```
+
+4. **Install the pre-push hook:**
+   ```bash
+   cp hooks/check-secrets-before-push.sh ~/.config/git/check-secrets-before-push.sh
+   chmod +x ~/.config/git/check-secrets-before-push.sh
+   ```
+   Then add it to your Claude Code settings (see `settings/settings.example.json`).
+
+That's it. The Superpowers plugin handles workflow enforcement (brainstorming, TDD, debugging, verification). The document hierarchy provides session continuity. The memory system learns your preferences over time.
+
+### Full workflow (Core + Advanced rules)
+
+Add the rules for projects that need explicit governance:
 
 ```bash
 mkdir -p .claude/rules
 cp rules/*.md .claude/rules/
 ```
 
-These are auto-loaded by Claude Code from `.claude/rules/` at session start.
-
-### 2. Set up templates for a new project
-
-```bash
-cp templates/IDEA.md ./IDEA.md        # Fill in your project brief
-cp templates/SESSION.md ./SESSION.md  # AI session memory (grows over time)
-cp templates/CONTEXT.md ./CONTEXT.md  # Static infrastructure facts
-cp templates/CLAUDE.md ./CLAUDE.md    # Project instructions for Claude
-```
-
-### 3. Install the pre-push hook (optional but recommended)
-
-```bash
-cp hooks/check-secrets-before-push.sh ~/.config/git/check-secrets-before-push.sh
-chmod +x ~/.config/git/check-secrets-before-push.sh
-```
-
-Then add it to your Claude Code settings (see `settings/settings.example.json`).
-
-### 4. Review the methodology guides
-
-- `workflows/dynamic-methodology.md` — How rules compose based on task type
-- `workflows/project-scaffold.md` — New project bootstrap recipe
-- `workflows/paper-writing.md` — Human-AI collaborative research
+These auto-load at session start and provide: session discipline, authority hierarchy, git workflow, proactive steering, reasoning patterns, context management, security hardening, code quality standards, and documentation maintenance rules.
 
 ## What's Inside
 
 | Directory | Purpose |
 |-----------|---------|
-| `rules/` | Core behavior rules — drop into `.claude/rules/` |
-| `templates/` | File templates for new projects |
+| `core/` | **Universal practices** — what actually runs in every project |
+| `rules/` | **Advanced governance** — `.claude/rules/` files for complex projects |
+| `templates/` | File templates for bootstrapping new projects |
 | `hooks/` | Claude Code hooks (pre-push secret scanning) |
 | `settings/` | Example Claude Code configuration |
 | `workflows/` | Human-readable methodology guides |
 | `docs/` | Philosophy and customization guides |
 
-## Adapting This Workflow
+## Methodology Guides
 
-See `docs/customization.md` for how to adapt these rules to your own projects. The rules are designed to be modular — use what fits, ignore what doesn't.
+- `workflows/dynamic-methodology.md` — How core practices and advanced rules compose based on task type
+- `workflows/project-scaffold.md` — New project bootstrap recipe
+- `workflows/paper-writing.md` — Human-AI collaborative research
 
 ## Origin
 
 Distilled from real-world usage across:
-- Multi-agent AI systems
-- Homelab infrastructure (70+ services, 4-node cluster)
+- Multi-agent AI systems (50+ tools, multi-provider routing)
+- Homelab infrastructure (70+ services, 4-node cluster, 500TB+ storage)
 - Game server operations and plugin development
-- ML model training and evaluation
-- Hardware control systems (3D printers, IoT)
+- ML model training and evaluation pipelines
+- Hardware control systems (3D printers, IoT devices)
 - Human-AI collaborative research papers
 - Web applications and API servers
 
-Every rule earned its place by preventing a real problem.
+Every practice earned its place by preventing a real problem.
 
 ## License
 

core/backup-before-edit.md

@@ -0,0 +1,41 @@
+# Backup Before Edit
+
+Before editing any file, back up the original to a `.backup/` directory in the same parent folder.
+
+## Why
+
+Disk space is cheap. Lost work is expensive. AI assistants sometimes make destructive edits — overwriting files, truncating content, or introducing bugs that are hard to reverse. A `.backup/` directory provides instant recovery without relying on git history (which may not exist yet, or may have uncommitted changes).
+
+## How
+
+Before modifying `src/config.py`:
+
+```bash
+mkdir -p src/.backup
+cp src/config.py src/.backup/config.py
+```
+
+For files that get edited multiple times, timestamp the backup:
+
+```bash
+cp src/config.py src/.backup/config.py.$(date +%Y%m%d-%H%M%S)
+```
+
+## Gitignore
+
+Add `.backup/` to your `.gitignore` so backups are never committed:
+
+```
+.backup/
+```
+
+## When to Apply
+
+- **Always** before editing existing files, especially configuration or infrastructure files
+- **Always** when an AI assistant is making changes to files you haven't read yet
+- **Skip** for files you just created in this session (nothing to back up)
+- **Skip** for test files during rapid iteration (git handles recovery)
+
+## Where This Rule Lives
+
+This belongs in your global `~/.claude/CLAUDE.md` so it applies to every project without per-project configuration. It's the one rule that should be universal and unconditional.

core/commit-and-push.md

@@ -0,0 +1,73 @@
+# Commit & Push Discipline
+
+The actual commit workflow: commit every meaningful change immediately, push on the same command. No squashing, no batching unrelated changes.
+
+## The Rule
+
+**Commit and push after every meaningful change.** Not at the end of the day. Not in batches. Every completed function, bug fix, test addition, or documentation update gets its own commit and push.
+
+## Why This Is Non-Negotiable
+
+1. **You never lose more than 15-30 minutes of work.** If the machine dies, the power goes out, or the AI assistant corrupts a file, your latest work is already on the remote.
+2. **Fine-grained history.** Each commit is one logical change. `git bisect` actually works. Reverts are surgical, not radioactive.
+3. **No merge conflicts from batching.** Small, frequent pushes rarely conflict. Large, infrequent pushes always do.
+4. **Accountability.** The commit message explains *what* and *why* for each change individually.
+
+## Commit Message Format
+
+Conventional commits, always:
+
+```
+<type>: <short description>
+```
+
+| Type | When |
+|------|------|
+| `feat:` | New feature or functionality |
+| `fix:` | Bug fix |
+| `docs:` | Documentation changes |
+| `refactor:` | Code restructuring (no behavior change) |
+| `test:` | Adding or updating tests |
+| `chore:` | Maintenance, dependencies |
+
+Examples:
+```bash
+git commit -m "feat: add user authentication endpoint"
+git commit -m "fix: resolve null pointer in data parser"
+git commit -m "test: add unit tests for payment module"
+```
+
+## Push Immediately
+
+After committing, push in the same command or immediately after:
+
+```bash
+git add <files> && git commit -m "feat: ..." && git push
+```
+
+If using a git hosting CLI wrapper (like `gitea push`), use that — it handles authentication automatically.
+
+## What Counts as "Meaningful"
+
+- A function completed and working
+- A bug fixed and tested
+- Tests added or modified
+- Documentation updated
+- Configuration changed
+- Before switching to a different task
+- Before risky experiments
+- Every 15-30 minutes of active coding (at natural breakpoints)
+
+## What Does NOT Get Committed
+
+- Code that doesn't compile or run
+- Half-finished features with no clean boundary
+- Files containing secrets (.env, credentials, tokens)
+- Temporary debugging artifacts (console.log spam, print statements)
+
+## Security Before Committing
+
+Before every push:
+- Ensure `.env` and credential files are in `.gitignore`
+- The pre-push hook (if installed) scans tracked files against known secret values
+- Never commit secrets — if one slips through, rotate immediately (git rm doesn't erase history)

core/document-hierarchy.md

@@ -0,0 +1,100 @@
+# Document Hierarchy
+
+The foundation of the entire workflow. Four file types, each with a distinct purpose, used consistently across every project.
+
+## The Four Documents
+
+| File | Purpose | When Updated | Loaded |
+|------|---------|-------------|--------|
+| **CLAUDE.md** | Project instructions for the AI | When components, tools, or architecture change | Every session (auto) |
+| **SESSION.md** | Accumulated AI memory — decisions, discoveries, patterns | During/after each session | On demand |
+| **CONTEXT.md** | Static infrastructure facts — hosts, ports, services | When infrastructure changes | On demand |
+| **IDEA.md** | Plain-language project brief | Rarely (initial creation) | On demand |
+
+## CLAUDE.md — The Starting Point
+
+The AI reads this first, every session. It should contain:
+
+- **Project state** — current phase, branch, test status, deployment
+- **Architecture** — how components connect, key files and their roles
+- **Conventions** — commit style, naming, project-specific rules
+- **Credentials** — where they live (never the values themselves)
+- **Development commands** — setup, run, test
+
+**Keep it lean.** Everything in CLAUDE.md loads every session. Don't dump session notes or temporary debugging context here. Stable, long-term facts only.
+
+**Keep it current.** If you create a new tool and don't document it here, the next session won't know it exists. Update CLAUDE.md immediately when components change — don't leave it for later.
+
+## SESSION.md — The Living Memory
+
+Accumulates decisions, discoveries, and context across AI sessions. Grouped by topic, not by date.
+
+```markdown
+## Session Notes
+
+### Infrastructure decisions
+- Chose LXC over Docker-in-LXC because the service doesn't need container isolation
+- Enabled nesting=1 on the container to allow Docker inside
+
+### Bug fixes & discoveries
+- Service wasn't starting: had autoStart=false in config
+  (fixed: set autoStart=true, verified with restart)
+
+### Open threads
+- [ ] Add Redis backend for session persistence
+- [ ] Web dashboard for monitoring
+```
+
+**Key principle:** Update the relevant section rather than appending raw timestamped blocks. A reader should be able to scan by topic, not wade through chronological entries.
+
+## CONTEXT.md — The Infrastructure Facts
+
+Static facts about where and how the project runs. Ports, hosts, services, dependencies. Updated when infrastructure changes, not during routine development.
+
+This is separate from CLAUDE.md because infrastructure facts are reference material — loaded on demand, not every session.
+
+## IDEA.md — The Original Intent
+
+Written once at project creation. Captures what the project is, what problem it solves, and any known constraints. Rarely modified after creation.
+
+Useful for: new contributors understanding why the project exists, AI assistants that need to understand the original motivation, and the project creator looking back at initial intent vs current reality.
+
+## How They Relate
+
+```
+Session start:
+  → AI reads CLAUDE.md (auto-loaded, always)
+  → AI checks MEMORY.md (auto-loaded, always)
+  → AI checks .claude/sessions/ for recent handoffs
+
+During work:
+  → AI reads CONTEXT.md when infrastructure details needed
+  → AI reads SESSION.md when historical decisions needed
+  → AI reads IDEA.md when original intent/scope is questioned
+
+Session end:
+  → AI updates SESSION.md with new decisions/discoveries
+  → AI updates CLAUDE.md if components changed
+  → AI writes handoff if work is unfinished
+```
+
+## The Global CLAUDE.md
+
+In addition to per-project CLAUDE.md files, a global `~/.claude/CLAUDE.md` applies to all projects. Use it for:
+
+- Universal rules (like "backup before edit")
+- Tool documentation (CLI wrappers, custom scripts)
+- Infrastructure overview (what machines exist, how to reach them)
+- Cross-project conventions
+
+Per-project CLAUDE.md files inherit from and can override the global one.
+
+## Anti-Patterns
+
+**CLAUDE.md as a dumping ground.** If it grows beyond ~200 lines, it's too heavy. Move reference material to CONTEXT.md, move decisions to SESSION.md, move architecture to `docs/`.
+
+**SESSION.md as a chat transcript.** It's not a log of what was said. It's a curated record of what was *decided* and *discovered*. Group by topic, not by date.
+
+**CONTEXT.md for opinions.** It stores facts (this service runs on port 8080), not opinions (we should probably migrate to a different port). Opinions go in SESSION.md or design docs.
+
+**Forgetting to update CLAUDE.md.** The single most common failure mode. You create a new tool, the session ends, the next session doesn't know it exists. Update immediately, not "later."

core/feedback-driven-behaviors.md

@@ -0,0 +1,82 @@
+# Feedback-Driven Behaviors
+
+Over time, corrections and confirmed approaches accumulate into persistent behavioral patterns. These are the real workflow rules — not written in a rules file, but learned from experience and stored in memory.
+
+## How It Works
+
+When the user corrects the AI ("don't do X") or confirms a non-obvious approach ("yes, exactly like that"), the correction or confirmation is saved as a feedback memory. Future sessions load these memories and adjust behavior accordingly.
+
+This means the workflow evolves organically. The rules files define the framework, but feedback memories define the actual behavior within that framework.
+
+## Common Feedback Patterns
+
+These are examples of the kinds of behavioral rules that emerge from real usage:
+
+### Execution Style
+- **Prefer immediate execution over confirmation dialogs.** When the task is obvious, communicate what you're doing and go. Don't ask "should I proceed?" for routine operations.
+- **Queue awareness.** Users often queue follow-up instructions while work runs in the background. Always check for and address ALL queued messages before moving on.
+
+### Subagent Safety
+- **Use subagent-driven execution by default** for independent tasks — it's faster and keeps context clean.
+- **NEVER use subagents for destructive operations.** Git history changes, bare repo operations, database modifications, file deletions on remote servers — do these manually in the main conversation, one at a time. A subagent can't be stopped mid-operation if something goes wrong.
+
+### Research Depth
+- **Read memory files before creating tasks or starting work.** Feedback memories contain corrections that prevent repeating past mistakes. Skipping them means re-learning the same lessons.
+- **Verify infrastructure before acting on documentation.** Ping IPs before SSH, check services before connecting. Docs go stale faster than code.
+
+### Communication
+- **Voice opinions.** Push back when the user's direction seems wrong. "I think there's a better approach because..." is more valuable than silent compliance.
+- **Use the question tool for design choices.** Don't make assumptions about architecture or design — ask explicitly when multiple valid approaches exist.
+
+## Recording New Feedback
+
+When a correction happens:
+
+```markdown
+---
+name: feedback_no_mock_database
+description: Integration tests must use real database, not mocks
+type: feedback
+---
+
+Integration tests must hit a real database, not mocks.
+
+**Why:** Prior incident where mocked tests passed but the production migration failed.
+Mock/prod divergence masked a broken migration.
+
+**How to apply:** When writing tests that touch database operations, always use a
+test database instance. Never mock the database layer in integration tests.
+```
+
+Key elements:
+- **The rule itself** (lead with this)
+- **Why** — the reason, often a past incident or strong preference
+- **How to apply** — when/where this guidance kicks in
+
+## Recording Confirmed Approaches
+
+Corrections are obvious. Confirmations are quieter — watch for them:
+
+- "Yes, exactly" or "perfect, keep doing that"
+- Accepting an unusual choice without pushback
+- "The single bundled PR was the right call here"
+
+Save these too. If you only save corrections, you drift away from approaches the user has already validated.
+
+## Feedback vs Rules
+
+| Aspect | Rules (`.claude/rules/`) | Feedback (memory) |
+|--------|--------------------------|-------------------|
+| Scope | Project-wide | Often personal/contextual |
+| Authority | Highest (cannot override) | Advisory (can override freely) |
+| Creation | Deliberate, authored | Organic, from corrections |
+| Maintenance | Manual | Decays if unused |
+| Loading | Auto-loaded every session | Auto-loaded via MEMORY.md |
+
+In most projects, feedback memories ARE the rules — there are no `.claude/rules/` files. The governance comes entirely from accumulated corrections and confirmed approaches.
+
+## When Feedback Contradicts Rules
+
+If a feedback memory says "skip tests for quick fixes" but a rule says "always write tests," follow the rule. Feedback memories are subordinate to explicit rules (see the authority hierarchy).
+
+But in projects without explicit rules, feedback memories are the highest available authority after user instructions.

core/memory-system.md

@@ -0,0 +1,121 @@
+# Memory System
+
+AI assistants forget everything between sessions. The memory system provides persistent, file-based memory that carries context forward.
+
+## How It Works
+
+Claude Code maintains a memory directory at `~/.claude/projects/<project-path>/memory/`. Each memory is a markdown file with frontmatter metadata, indexed by a `MEMORY.md` file.
+
+## Memory Types
+
+### User Memories
+Information about who you are — role, expertise, preferences. Helps the AI tailor its approach.
+
+```markdown
+---
+name: user_role
+description: User is a senior infrastructure engineer with deep Linux/networking expertise
+type: user
+---
+
+Senior infrastructure engineer. Deep expertise in Linux, ZFS, Proxmox, networking.
+New to React frontend work — frame frontend explanations in terms of backend analogues.
+```
+
+### Feedback Memories
+Corrections and confirmed approaches — what to do and what NOT to do. **The most important type.** These prevent the AI from making the same mistake twice.
+
+```markdown
+---
+name: feedback_subagent_safety
+description: Never use subagents for destructive server operations
+type: feedback
+---
+
+Never use subagents for destructive server operations (git history changes,
+bare repo operations, database modifications). Do these manually, one at a time.
+
+**Why:** A subagent running destructive ops in parallel caused data loss.
+The main conversation can't intervene if a subagent goes wrong.
+
+**How to apply:** Before dispatching any agent, check if the task involves
+destructive operations. If yes, do it in the main conversation sequentially.
+```
+
+### Project Memories
+Ongoing work, decisions, and context that isn't derivable from code or git history.
+
+```markdown
+---
+name: project_auth_rewrite
+description: Auth middleware rewrite driven by legal compliance, not tech debt
+type: project
+---
+
+Auth middleware rewrite is driven by legal/compliance requirements around
+session token storage, not tech-debt cleanup.
+
+**Why:** Legal flagged the current implementation for non-compliant token storage.
+**How to apply:** Scope decisions should favor compliance over ergonomics.
+```
+
+### Reference Memories
+Pointers to where information lives in external systems.
+
+```markdown
+---
+name: reference_bug_tracker
+description: Pipeline bugs tracked in Linear project INGEST
+type: reference
+---
+
+Pipeline bugs are tracked in Linear project "INGEST".
+API monitoring alerts go to #oncall-api Slack channel.
+```
+
+## MEMORY.md Index
+
+`MEMORY.md` is a one-line-per-entry index of all memory files. It's loaded into every conversation.
+
+```markdown
+# Memory Index
+
+- [user_role.md](user_role.md) — Senior infra engineer, new to React
+- [feedback_subagent_safety.md](feedback_subagent_safety.md) — No subagents for destructive ops
+- [project_auth_rewrite.md](project_auth_rewrite.md) — Auth rewrite is compliance-driven
+- [reference_bug_tracker.md](reference_bug_tracker.md) — Bugs in Linear INGEST project
+```
+
+Keep entries under 150 characters. MEMORY.md is truncated after 200 lines.
+
+## What NOT to Save
+
+- Code patterns or architecture (derivable from reading current code)
+- Git history (use `git log` / `git blame`)
+- Debugging solutions (the fix is in the code, context in the commit message)
+- Anything already in CLAUDE.md
+- Ephemeral task details (use task tools instead)
+
+## When to Save
+
+- **Immediately** when the user explicitly asks to remember something
+- **Proactively** when you learn about the user's role, preferences, or expertise
+- **After corrections** — if the user says "don't do X", save it as feedback
+- **After confirmed approaches** — if something non-obvious worked, save that too
+- **When project context emerges** that won't be in code (deadlines, stakeholder decisions, compliance requirements)
+
+## When to Read
+
+- At conversation start (MEMORY.md index is auto-loaded)
+- When the user references prior-conversation work
+- Before making decisions that prior feedback might inform
+- When the user says "check", "recall", or "remember"
+
+## Stale Memory
+
+Memories can become outdated. Before acting on a memory:
+- If it names a file path: check the file exists
+- If it names a function or flag: grep for it
+- If the user asks about *current* state: prefer `git log` or reading code over recalling a snapshot
+
+"The memory says X exists" is not the same as "X exists now."

core/superpowers-workflow.md

@@ -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

docs/customization.md

@@ -2,144 +2,149 @@
 
 How to adapt this workflow for your own projects.
 
-## Start Small
+## Start With Core (This Is All Most Projects Need)
 
-You don't need to adopt everything at once. Here's a recommended progression:
+The core practices run without any `.claude/rules/` files. They're the actual daily workflow:
 
-### Level 1: Essentials (Start Here)
-```
-.claude/rules/
-  01-session-discipline.md    # Session start/end protocol
-  03-git-workflow.md           # Conventional commits, branches
-  09-context-doc-maintenance.md # Keep docs current
+### 1. Install the Superpowers plugin
+```bash
+claude plugin install superpowers
 ```
 
-Plus the templates:
-- `CLAUDE.md` -- project instructions
-- `SESSION.md` -- AI memory across sessions
+This gives you: brainstorming before building, TDD enforcement, systematic debugging, verification before completion, code review, and implementation planning. It's the workflow engine.
 
-This gives you: session continuity, clean git history, and documentation that stays current.
-
-### Level 2: Quality
-Add:
-```
-.claude/rules/
-  05-reasoning-patterns.md    # Brainstorm before building, Five Whys
-  08-code-quality.md           # Quality checklist, immutability
+### 2. Set up the document hierarchy
+```bash
+cp templates/CLAUDE.md ./CLAUDE.md    # Fill in project state and architecture
+cp templates/SESSION.md ./SESSION.md  # AI memory, grows over time
 ```
 
-This gives you: better architectural decisions, fewer bugs, and consistent code quality.
+Add `CONTEXT.md` if you have infrastructure details. Add `IDEA.md` for new projects.
 
-### Level 3: Sophisticated AI Assistance
-Add:
+### 3. Add backup-before-edit to your global instructions
+In `~/.claude/CLAUDE.md`:
 ```
-.claude/rules/
-  02-authority-hierarchy.md    # What overrides what
-  04-proactive-steering.md     # AI as co-pilot, not passive tool
-  06-context-management.md     # Token budgets, session management
+Before editing any file, back up the original to a .backup/ directory.
 ```
 
-This gives you: an AI assistant that actively steers the project, manages its own context, and follows a clear authority hierarchy.
-
-### Level 4: Security Hardening
-Add:
-```
-.claude/rules/
-  07-security-hardening.md     # Deny lists, injection guards
-```
-
-Plus the pre-push hook:
+### 4. Install the pre-push hook
 ```bash
 cp hooks/check-secrets-before-push.sh ~/.config/git/check-secrets-before-push.sh
+chmod +x ~/.config/git/check-secrets-before-push.sh
 ```
 
-This gives you: secret scanning, file access restrictions, and prompt injection awareness.
+Add to Claude Code settings (see `settings/settings.example.json`).
 
-## Customizing Individual Rules
+### 5. Let the memory system do its job
 
-### Session Discipline (01)
+As you work, correct the AI when it does something wrong. Confirm when it does something right in a non-obvious way. These corrections and confirmations persist as feedback memories that improve behavior over time.
 
-**Adapt:** The session wrap-up questions. Your team might have different things to check at session end. The handoff document format might need project-specific sections.
+**That's it.** This is the actual workflow for 25 out of 26 projects. The Superpowers plugin enforces the process, the documents provide continuity, the memory system learns, the hook catches secrets.
 
-**Don't remove:** The principle of persisting decisions to files. This is the foundation of session continuity.
+## When to Add Advanced Rules
 
-### Git Workflow (03)
+Add `.claude/rules/` files when you notice:
 
-**Adapt:** Branch naming conventions to match your team's standard. Commit types if you use a different convention than conventional commits.
+- **Convention drift** — Different sessions make inconsistent decisions because there's no explicit standard
+- **Onboarding friction** — New contributors (or new AI sessions) take too long to understand how this project works
+- **Expensive mistakes** — The project touches production systems where errors have real consequences
+- **Multi-domain complexity** — The project spans ML + infrastructure + frontend + deployment and context switching causes errors
+- **Session handoff problems** — Multi-session work loses important context despite SESSION.md
 
-**Don't remove:** Frequent commits and conventional format. These create searchable, revertible history.
+### Adding Rules Incrementally
 
-### Proactive Steering (04)
+Don't install all 9 rules at once. Add what you need:
 
-**Adapt:** The phase names (IDEATION, PLANNING, etc.) to match your team's vocabulary. The auto-invoke tool signals to match your toolchain.
+**First:** Session discipline + git workflow
+```bash
+mkdir -p .claude/rules
+cp rules/01-session-discipline.md .claude/rules/
+cp rules/03-git-workflow.md .claude/rules/
+```
 
-**Don't remove:** The principle of ending every response with direction. This prevents "what now?" dead ends.
+These formalize the session start/end protocol and git conventions that the core practices handle implicitly.
 
-### Reasoning Patterns (05)
+**Then:** Reasoning patterns + code quality (if decisions need more rigor)
+```bash
+cp rules/05-reasoning-patterns.md .claude/rules/
+cp rules/08-code-quality.md .claude/rules/
+```
 
-**Adapt:** The documentation lookup tiers to match your documentation tools. The Adopt/Extend/Compose/Build thresholds based on your project's tolerance for dependencies.
+**Then:** Proactive steering + context management (if the AI needs to be more autonomous)
+```bash
+cp rules/04-proactive-steering.md .claude/rules/
+cp rules/06-context-management.md .claude/rules/
+```
 
-**Don't remove:** Clarification before assumption and brainstorm before building. These prevent wasted work.
+**Then:** Security hardening + authority hierarchy (if the project is security-sensitive or has conflicting guidance)
+```bash
+cp rules/07-security-hardening.md .claude/rules/
+cp rules/02-authority-hierarchy.md .claude/rules/
+```
 
-### Context Management (06)
+## Customizing Core Practices
 
-**Adapt:** The token budget numbers based on your AI assistant's context window. The thinking mode names to match your tool's syntax.
+### Document hierarchy
+- Adjust the CLAUDE.md template to match your project's shape
+- Some projects don't need CONTEXT.md (no infrastructure)
+- Some projects don't need IDEA.md (existing codebase, no "original intent" to capture)
 
-**Don't remove:** The execution readiness check. Starting 3+ tasks at high context usage compounds errors.
+### Superpowers plugin
+- TDD enforcement can be overridden per-request ("skip tests this time" — requires explicit acknowledgment)
+- Brainstorming depth scales with task complexity (simple tasks get lighter treatment)
+- The plugin is configurable — check its documentation for options
+
+### Memory system
+- Review feedback memories periodically — some become outdated
+- User memories help the AI tailor explanations to your expertise level
+- Project memories capture context that isn't in code or git history
+
+### Commit conventions
+- Conventional commits (`feat:`, `fix:`, etc.) are the default but not mandatory
+- The core principle is: one logical change per commit, push immediately
+- Adapt the types to your team's vocabulary if needed
+
+## Customizing Advanced Rules
+
+### Session discipline (01)
+Adapt: The wrap-up questions. Your team might check different things at session end.
+Keep: Persisting decisions to files. This is foundational.
+
+### Git workflow (03)
+Adapt: Branch naming conventions to match your team.
+Keep: Frequent commits and conventional format.
+
+### Proactive steering (04)
+Adapt: Phase names to match your team's vocabulary.
+Keep: Ending every response with direction.
+
+### Reasoning patterns (05)
+Adapt: Documentation lookup tiers to match your tools.
+Keep: Clarification before assumption, brainstorm before building.
+
+### Context management (06)
+Adapt: Token budget numbers for your AI assistant's context window.
+Keep: The execution readiness check.
 
 ### Security (07)
+Adapt: Deny list patterns for your infrastructure.
+Keep: Prompt injection guardrails.
 
-**Adapt:** The deny list patterns to match your infrastructure. Add paths specific to your cloud provider, secrets manager, etc.
+## Removing Things
 
-**Don't remove:** The prompt injection guardrails. External content is always untrusted input.
+If a core practice doesn't fit:
+- Don't install the Superpowers plugin → brainstorming/TDD become suggestions, not enforced
+- Don't use SESSION.md → lose session continuity (not recommended)
+- Don't install the pre-push hook → rely on `.gitignore` alone for secret prevention
 
-## Adding Project-Specific Rules
-
-Create additional rules in `.claude/rules/` with higher numbers:
-
-```
-.claude/rules/
-  10-api-conventions.md        # Your API design standards
-  11-testing-requirements.md   # Your testing requirements
-  12-deployment-process.md     # Your deployment workflow
-```
-
-Higher numbers load after lower numbers. Project-specific rules can reference the base rules:
-
-```markdown
-# API Conventions
-
-In addition to the quality standards in `08-code-quality.md`:
-
-- All endpoints must return JSON
-- All errors must use RFC 7807 format
-- All endpoints must have OpenAPI documentation
-```
-
-## Removing Rules
-
-If a rule doesn't fit your workflow, simply don't copy it to `.claude/rules/`. The remaining rules continue to work independently.
-
-**Caveat:** If you remove `02-authority-hierarchy.md`, be aware that conflicts between rules, plugins, and defaults won't have a clear resolution order. Consider keeping it even if simplified.
+If an advanced rule doesn't fit:
+- Simply don't copy it to `.claude/rules/`. The remaining rules work independently.
+- Exception: if you remove `02-authority-hierarchy.md`, conflicts between rules and plugins won't have a clear resolution. Consider keeping it even if simplified.
 
 ## Team Adoption
 
-For teams adopting this workflow:
-
-1. **Start with Level 1** across all projects
-2. **Standardize CLAUDE.md format** so any team member's AI assistant can pick up any project
-3. **Share SESSION.md conventions** so session memories are consistently structured
-4. **Discuss which rules to add** based on the team's pain points
-5. **Customize rule content** to match team conventions, but keep the rule structure
-
-The templates in `templates/` are starting points. Evolve them as your team discovers what works.
-
-## Measuring Success
-
-You'll know the workflow is working when:
-- New sessions start productive immediately (no "where was I?")
-- Decisions made last week are documented and discoverable
-- The AI suggests next steps you agree with (proactive steering is calibrated)
-- No secrets are committed (security rules are working)
-- Git history tells a clear story (conventional commits + frequent commits)
-- Context doesn't degrade in long sessions (context management is working)
+1. Start with core practices only across all projects
+2. Standardize the CLAUDE.md format so anyone's AI can pick up any project
+3. Let the memory system accumulate team-specific feedback organically
+4. Add advanced rules only to projects that demonstrably need them
+5. Review rules quarterly — remove any that aren't preventing real problems

docs/philosophy.md

@@ -8,72 +8,67 @@ AI coding assistants are powerful but amnesiac. They forget everything between s
 
 This workflow exists because these problems are solvable with structure.
 
+## The Two-Tier Reality
+
+This workflow has two tiers because that's what actually works in practice:
+
+**Core practices** (used everywhere): The document hierarchy, the Superpowers plugin, the memory system, backup-before-edit, commit-and-push discipline, and the pre-push hook. These run in every project without any `.claude/rules/` files. The plugin enforces the workflow; the documents provide continuity; the memory system learns corrections.
+
+**Advanced rules** (used in complex projects): Formal `.claude/rules/` files that provide explicit governance — session discipline protocols, authority hierarchy, proactive steering patterns, reasoning frameworks. These only make sense when a project is complex enough that implicit conventions break down.
+
+Most projects never need the advanced tier. The core practices handle everything from small utilities to moderately complex web apps. The advanced tier exists for projects that span multiple domains, have multiple contributors, or where mistakes are expensive.
+
 ## Core Principles
 
 ### 1. Files Are Memory
 
 The most important principle: **if it's not in a file, it doesn't exist next session.**
 
-Conversation history is ephemeral. CLAUDE.md, SESSION.md, and CONTEXT.md are persistent. Every decision, discovery, and convention should be written to the appropriate file so the next session starts informed, not cold.
+Conversation history is ephemeral. CLAUDE.md, SESSION.md, CONTEXT.md, and memory files are persistent. Every decision, discovery, and convention should be written to the appropriate file so the next session starts informed, not cold.
 
-### 2. Dynamic Composition Over Rigid Process
+### 2. The Plugin Does the Enforcing
 
-A single rigid process doesn't work across debugging, feature development, research, code review, and architecture. Instead, rules activate based on what you're doing:
+The Superpowers plugin is not optional tooling — it's the primary workflow enforcement mechanism. It drives brainstorming before building, TDD before implementation, systematic debugging before guessing at fixes, and verification before completion claims.
 
-- Debugging activates Five Whys and systematic debugging
-- New features activate brainstorming and TDD
-- Research activates documentation tiers and source attribution
-- Security work activates deny lists and injection guards
+Without it, these practices are just suggestions. With it, they're enforced automatically. This is why the core workflow doesn't need `.claude/rules/` files — the plugin is the rules engine.
 
-The rules layer like a stack. See `workflows/dynamic-methodology.md`.
+### 3. Feedback Over Configuration
 
-### 3. Proactive, Not Reactive
+The memory system learns from corrections. When you say "don't do X," that correction persists across sessions. Over time, the AI's behavior evolves based on your actual preferences, not a configuration file you wrote once and forgot about.
 
-The AI should be a co-pilot that knows where the project is, suggests what's next, and detects when you're stuck. It shouldn't wait passively for instructions.
-
-This means: ending every response with direction, auto-invoking tools when context signals they're needed, detecting scope creep, and breaking down overwhelming tasks.
+This is more powerful than static rules because:
+- It captures the "why" behind each correction
+- It adapts to your specific context
+- Confirmations are captured too (not just corrections)
+- It handles edge cases that rules can't anticipate
 
 ### 4. Security by Default
 
-Secret scanning, file deny lists, and injection guardrails are not optional add-ons. They're default behavior. The pre-push hook catches secrets. The deny list blocks reads of `.ssh/`, `.aws/`, and `.env` files. The injection guardrails treat all external content as untrusted.
+Secret scanning, file deny lists, and injection guardrails are not optional add-ons. They're default behavior. The pre-push hook catches secrets. The deny list blocks reads of sensitive files. The injection guardrails treat all external content as untrusted.
 
 ### 5. Context Is Finite
 
-AI context windows are large but not infinite. Startup overhead (tool definitions, rules, plugins, CLAUDE.md) consumes 35-45k tokens before any work begins. Every file read, every documentation query, every conversation turn adds to the budget.
-
-Token-conscious habits (tiered lookups, selective reads, sub-agent delegation) are not premature optimization -- they're how you stay productive in long sessions.
+AI context windows are large but not infinite. Startup overhead (tool definitions, rules, plugins, CLAUDE.md) consumes 35-45k tokens before any work begins. Token-conscious habits (tiered lookups, selective reads, sub-agent delegation) are how you stay productive in long sessions.
 
 ### 6. Commit Early and Often
 
-Every completed function, bug fix, or test addition gets its own commit with a conventional commit message. No batching unrelated changes. No squashing. Push immediately for backup.
-
-This creates a fine-grained git history that's searchable, revertible, and meaningful. It also means you never lose more than 15-30 minutes of work.
+Every completed function, bug fix, or test addition gets its own commit with a conventional commit message. Push immediately. No batching. No squashing.
 
 ### 7. Honest About Uncertainty
 
-Separate fact from inference. Cite sources. Flag single-source claims. Mark speculation as speculation. Cross-reference critical claims.
-
-An AI that confidently states wrong information is worse than one that says "I'm not sure, let me check."
+Separate fact from inference. Cite sources. Flag single-source claims. Mark speculation as speculation. An AI that confidently states wrong information is worse than one that says "I'm not sure, let me check."
 
 ## What This Workflow Is NOT
 
-- **Not a project management system.** It doesn't track sprints, estimate velocity, or assign work to people.
-- **Not a CI/CD pipeline.** It doesn't build, test, or deploy your code. It guides the AI assistant working alongside you.
+- **Not a project management system.** It doesn't track sprints or estimate velocity.
+- **Not a CI/CD pipeline.** It doesn't build, test, or deploy your code.
 - **Not prescriptive about stack.** It works with any language, framework, or deployment target.
-- **Not AI-specific in philosophy.** Most of these principles (commit often, document decisions, security by default) apply to human-only teams too. The AI-specific parts are context management, session discipline, and the authority hierarchy.
+- **Not all-or-nothing.** The core practices work alone. The advanced rules are optional layers.
 
 ## Origin
 
-This workflow wasn't designed top-down. It accumulated bottom-up across 26+ real projects:
+This workflow wasn't designed top-down. It accumulated bottom-up across 26+ real projects. The core practices emerged because they worked everywhere — every project uses the document hierarchy, every session benefits from the Superpowers plugin, every correction saved to memory prevents future mistakes.
 
-- Multi-agent AI systems with 50+ tools
-- Infrastructure management (70+ services on a 4-node cluster)
-- Game server operations and plugin development
-- ML model training and evaluation pipelines
-- Hardware control systems (3D printers, IoT devices)
-- Human-AI collaborative research papers
-- Web applications and API servers
-
-Every rule exists because something broke without it. The session discipline rules exist because AI assistants kept losing context. The security rules exist because secrets were almost committed. The reasoning patterns exist because first-idea-wins produced inferior architectures.
+The advanced rules emerged from one project that was complex enough to need them. They're a formalization of patterns that the core practices handle implicitly in simpler contexts.
 
 Nothing here is theoretical. It all earned its place.

settings/settings.example.json

@@ -1,17 +1,26 @@
 {
   "_comment": "Example Claude Code settings.json — copy relevant sections to ~/.claude/settings.json",
+  "_note": "This reflects the actual configuration used across 26+ projects",
 
   "enabledPlugins": {
-    "_comment": "Recommended plugins from the official marketplace",
+    "_comment_core": "CORE — Superpowers is the workflow engine, not optional",
     "superpowers@claude-plugins-official": true,
+
+    "_comment_recommended": "RECOMMENDED — quality and maintenance tools",
     "code-review@claude-plugins-official": true,
     "code-simplifier@claude-plugins-official": true,
-    "claude-md-management@claude-plugins-official": true
+    "claude-md-management@claude-plugins-official": true,
+
+    "_comment_optional": "OPTIONAL — enable based on your work",
+    "frontend-design@claude-plugins-official": false,
+    "skill-creator@claude-plugins-official": false,
+    "plugin-dev@claude-plugins-official": false
   },
 
   "hooks": {
     "PreToolUse": [
       {
+        "_comment": "Block git pushes if tracked files contain secrets",
         "matcher": "Bash",
         "hooks": [
           {
@@ -26,7 +35,8 @@
   },
 
   "_permissions_example": {
-    "_comment": "Add to permissions.deny to block access to sensitive files",
+    "_comment": "Add to your settings.json top level to block access to sensitive files",
+    "permissions": {
       "deny": [
         "Read(~/.ssh/*)",
         "Read(~/.aws/*)",
@@ -39,16 +49,13 @@
         "Write(~/.aws/*)",
         "Write(**/.env*)"
       ]
+    }
   },
 
-  "_mcp_example": {
-    "_comment": "Example MCP server configuration — add servers relevant to your workflow",
-    "mcpServers": {
-      "example-server": {
-        "command": "/path/to/server",
-        "args": [],
-        "env": {}
-      }
-    }
+  "_global_claude_md": {
+    "_comment": "Add these lines to your ~/.claude/CLAUDE.md (global instructions)",
+    "rules": [
+      "Before editing any file, back up the original to a .backup/ directory in the same parent folder."
+    ]
   }
 }

workflows/dynamic-methodology.md

@@ -1,159 +1,175 @@
 # Dynamic Methodology Composition
 
-This workflow system doesn't follow a single rigid process. Instead, rules and patterns activate based on what you're doing. Think of it as a stack that composes dynamically.
+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).
 
-## Always Active (Every Session)
+## What's Always Active (Every Project)
 
-These rules apply regardless of what you're working on:
+These aren't in `.claude/rules/` — they work through the Superpowers plugin, the document hierarchy, and accumulated memory.
 
-| Rule | File | Purpose |
-|------|------|---------|
-| Session discipline | `01-session-discipline.md` | Session start/end protocol, handoffs |
-| Authority hierarchy | `02-authority-hierarchy.md` | What overrides what |
-| Git workflow | `03-git-workflow.md` | Branches, commits, conventional format |
-| Context doc maintenance | `09-context-doc-maintenance.md` | Keep living docs current |
+| 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 |
 
-## Activated by Task Type
+## How Core Practices Activate by Task Type
 
 ### Starting a New Feature
 
-**Rules activated:**
-- `04-proactive-steering.md` -- Phase awareness, scope management
-- `05-reasoning-patterns.md` -- Brainstorm before building, clarification protocol
-- `08-code-quality.md` -- Pre-completion checklist, immutability
-
-**Flow:**
-1. Clarify requirements (ask, don't assume)
-2. Brainstorm 2-3 approaches
-3. Get user approval on approach
-4. Write failing tests first (if TDD plugin active)
-5. Implement
-6. Self-review against pre-completion checklist
-7. Commit with conventional message
+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
 
-**Rules activated:**
-- `05-reasoning-patterns.md` -- Five Whys, first principles
-- `04-proactive-steering.md` -- Blocker detection
-
-**Flow:**
-1. Reproduce the bug
-2. Apply Five Whys to trace root cause
-3. Fix root cause, not symptom
-4. Add regression test
-5. Verify fix doesn't break other things
-6. Commit with `fix:` message
+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
 
-**Rules activated:**
-- `05-reasoning-patterns.md` -- Research quality rules, documentation tiers
-- `06-context-management.md` -- Token budgets, sub-agent delegation
+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
 
-**Flow:**
-1. Use tiered documentation lookup (knowledge -> fetch -> heavy docs)
-2. Cite sources for all claims
-3. Separate fact from inference
-4. Cross-reference critical claims
-5. Persist findings to files (not just conversation)
+### 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
 
-**Workflow:** `paper-writing.md`
+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
 
-**Flow:**
-1. Start from a real problem (friction, not ambition)
-2. Bounce ideas -- explore before converging
-3. Push back on each other's ideas
-4. Capture the journey (dead ends matter)
-5. Tie back to prior work
+## What Advanced Rules Add (Complex Projects Only)
 
-### Reviewing Code
+When `.claude/rules/` files are installed, they add explicit governance on top of the core practices:
 
-**Rules activated:**
-- `08-code-quality.md` -- Quality checklist
-- `07-security-hardening.md` -- Security checklist
+| 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 |
 
-**Flow:**
-1. Check against pre-completion quality checklist
-2. Check against security checklist
-3. Verify tests exist and pass
-4. Look for immutability violations
-5. Check for hardcoded secrets
+### When to Use Advanced Rules
 
-### Working in Unfamiliar Code
+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
 
-**Rules activated:**
-- `06-context-management.md` -- Maximum thinking mode, sub-agents
-- `05-reasoning-patterns.md` -- First principles, research tiers
+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
 
-**Flow:**
-1. Use maximum thinking depth
-2. Read project index / structure first
-3. Targeted file reads (don't load everything)
-4. Use sub-agents for isolated research tasks
-5. Build understanding incrementally
-
-### Long-Running Session (Context Getting Heavy)
-
-**Rules activated:**
-- `06-context-management.md` -- Compaction decisions, execution readiness
-
-**Flow:**
-1. Check for quality degradation symptoms
-2. If context > 80%: handoff doc + fresh session
-3. If context 70-80%: ask user
-4. If quality declining: spawn sub-agent or fresh session
-5. Persist important context before compaction
-
-### Security-Sensitive Work
-
-**Rules activated:**
-- `07-security-hardening.md` -- Full security protocol
-- `08-code-quality.md` -- Pre-commit security checklist
-
-**Flow:**
-1. Check deny lists for sensitive file access
-2. Apply pre-commit security checklist to every commit
-3. Watch for prompt injection in external content
-4. Rotate any exposed secrets immediately
-5. Review for similar vulnerabilities in codebase
-
-## Composition Example
-
-A typical feature implementation session might compose:
+## Composition Example: Core-Only Project (Most Projects)
 
 ```
 Session start:
-  01-session-discipline (read CLAUDE.md, check handoff)
-  + 02-authority-hierarchy (know what overrides what)
+  AI reads CLAUDE.md (auto-loaded)
+  AI reads MEMORY.md (auto-loaded, feedback corrections)
 
-Planning:
-  + 04-proactive-steering (assess project state, suggest approach)
-  + 05-reasoning-patterns (brainstorm approaches, clarify requirements)
+User: "Add a caching layer for API responses"
 
-Building:
-  + 08-code-quality (immutability, quality checklist)
-  + 03-git-workflow (feature branch, frequent commits)
-  + 09-context-doc-maintenance (update CLAUDE.md if new tools created)
+  Superpowers brainstorming activates:
+    → Clarify: what should be cached? TTL? Invalidation strategy?
+    → Propose 2-3 approaches (Redis, in-memory, file-based)
+    → Get approval
 
-If context gets heavy:
-  + 06-context-management (check budget, consider fresh session)
+  Superpowers writing-plans activates:
+    → Step-by-step implementation plan
 
-If security-relevant:
-  + 07-security-hardening (deny lists, secret hygiene, injection guards)
+  Superpowers TDD activates:
+    → Write failing test for cache hit/miss
+    → Implement cache
+    → Write failing test for TTL expiry
+    → Implement expiry
 
-Session end:
-  01-session-discipline (wrap-up protocol, handoff if needed)
+  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
 ```
 
-## Principle: Rules Are Modular
+## Composition Example: Advanced Project (Mortdecai-tier)
 
-You don't have to use all rules. The system is designed so you can:
-- Use only rules 01-03 for lightweight workflow
-- Add 04-06 for more sophisticated AI assistance
-- Add 07-08 for security-conscious development
-- Use individual rules a la carte
+```
+Session start:
+  01-session-discipline: Read CLAUDE.md, check latest handoff
+  02-authority-hierarchy: Know what overrides what
+  Memory system: Load feedback corrections
 
-The numbering suggests load order and priority, not mandatory dependencies.
+  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.