Seth/Seth-Workflow-April-2026
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: add core/ tier reflecting actual universal workflow

Browse Source 
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:
Mortdecai
2026-04-01 16:55:04 -04:00
parent 9ff8e915b8
commit ea3cf45953
12 changed files with 949 additions and 326 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/customization.md
+107 -102
View File
@@ -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
+30 -35
View File
@@ -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.