init: scaffold Seth-Workflow-April-2026

User-agnostic, shareable AI-assisted development workflow distilled from 26+ real projects. Includes 9 composable rules, 4 project templates, pre-push secret scanning hook, 3 methodology guides, and customization docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 15:55:58 -04:00
commit 9ff8e915b8
22 changed files with 1917 additions and 0 deletions
@@ -0,0 +1,145 @@
+# Customization Guide
+
+How to adapt this workflow for your own projects.
+
+## Start Small
+
+You don't need to adopt everything at once. Here's a recommended progression:
+
+### 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
+```
+
+Plus the templates:
+- `CLAUDE.md` -- project instructions
+- `SESSION.md` -- AI memory across sessions
+
+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
+```
+
+This gives you: better architectural decisions, fewer bugs, and consistent code quality.
+
+### Level 3: Sophisticated AI Assistance
+Add:
+```
+.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
+```
+
+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:
+```bash
+cp hooks/check-secrets-before-push.sh ~/.config/git/check-secrets-before-push.sh
+```
+
+This gives you: secret scanning, file access restrictions, and prompt injection awareness.
+
+## Customizing Individual Rules
+
+### Session Discipline (01)
+
+**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.
+
+**Don't remove:** The principle of persisting decisions to files. This is the foundation of session continuity.
+
+### Git Workflow (03)
+
+**Adapt:** Branch naming conventions to match your team's standard. Commit types if you use a different convention than conventional commits.
+
+**Don't remove:** Frequent commits and conventional format. These create searchable, revertible history.
+
+### Proactive Steering (04)
+
+**Adapt:** The phase names (IDEATION, PLANNING, etc.) to match your team's vocabulary. The auto-invoke tool signals to match your toolchain.
+
+**Don't remove:** The principle of ending every response with direction. This prevents "what now?" dead ends.
+
+### Reasoning Patterns (05)
+
+**Adapt:** The documentation lookup tiers to match your documentation tools. The Adopt/Extend/Compose/Build thresholds based on your project's tolerance for dependencies.
+
+**Don't remove:** Clarification before assumption and brainstorm before building. These prevent wasted work.
+
+### Context Management (06)
+
+**Adapt:** The token budget numbers based on your AI assistant's context window. The thinking mode names to match your tool's syntax.
+
+**Don't remove:** The execution readiness check. Starting 3+ tasks at high context usage compounds errors.
+
+### Security (07)
+
+**Adapt:** The deny list patterns to match your infrastructure. Add paths specific to your cloud provider, secrets manager, etc.
+
+**Don't remove:** The prompt injection guardrails. External content is always untrusted input.
+
+## 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.
+
+## 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)
@@ -0,0 +1,79 @@
+# Philosophy
+
+Why this workflow exists and the principles behind it.
+
+## The Problem
+
+AI coding assistants are powerful but amnesiac. They forget everything between sessions. They can't tell when they're running low on context. They don't know your project's conventions unless told. They'll happily commit secrets, skip tests, or propose architectures that contradict last week's decisions.
+
+This workflow exists because these problems are solvable with structure.
+
+## 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.
+
+### 2. Dynamic Composition Over Rigid Process
+
+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:
+
+- 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
+
+The rules layer like a stack. See `workflows/dynamic-methodology.md`.
+
+### 3. Proactive, Not Reactive
+
+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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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."
+
+## 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 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.
+
+## Origin
+
+This workflow wasn't designed top-down. It accumulated bottom-up across 26+ real projects:
+
+- 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.
+
+Nothing here is theoretical. It all earned its place.