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