# Seth-Workflow-April-2026

A battle-tested AI-assisted development workflow distilled from 26+ projects across infrastructure, game servers, ML training, web apps, hardware control, and research papers.

This isn't a theoretical framework. Every rule here exists because something broke without it.

## Two Tiers: Core + Advanced

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

### 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 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 |
|-----------|---------|
| `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 |

## Methodology Guides

- `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 (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 pipelines
- Hardware control systems (3D printers, IoT devices)
- Human-AI collaborative research papers
- Web applications and API servers

Every practice earned its place by preventing a real problem.

## License

MIT. Use it, adapt it, share it.