feat: add core/ tier reflecting actual universal workflow
The original repo presented everything as equal rules. In reality, the workflow has two tiers: core practices (used in every project) and advanced rules (only in complex projects like Mortdecai). Core tier adds: - backup-before-edit (global CLAUDE.md rule) - superpowers-workflow (the actual workflow engine) - memory-system (persistent feedback and project memories) - document-hierarchy (CLAUDE.md/SESSION.md/CONTEXT.md/IDEA.md) - commit-and-push discipline - feedback-driven behaviors Updated README, docs, and dynamic-methodology to reflect the two-tier reality instead of presenting advanced rules as universal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mortdecai
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user