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>
This commit is contained in:
Mortdecai
@@ -0,0 +1,159 @@
|
||||
# Dynamic Methodology Composition
|
||||
|
||||
This workflow system doesn't follow a single rigid process. Instead, rules and patterns activate based on what you're doing. Think of it as a stack that composes dynamically.
|
||||
|
||||
## Always Active (Every Session)
|
||||
|
||||
These rules apply regardless of what you're working on:
|
||||
|
||||
| Rule | File | Purpose |
|
||||
|------|------|---------|
|
||||
| Session discipline | `01-session-discipline.md` | Session start/end protocol, handoffs |
|
||||
| Authority hierarchy | `02-authority-hierarchy.md` | What overrides what |
|
||||
| Git workflow | `03-git-workflow.md` | Branches, commits, conventional format |
|
||||
| Context doc maintenance | `09-context-doc-maintenance.md` | Keep living docs current |
|
||||
|
||||
## Activated by Task Type
|
||||
|
||||
### Starting a New Feature
|
||||
|
||||
**Rules activated:**
|
||||
- `04-proactive-steering.md` -- Phase awareness, scope management
|
||||
- `05-reasoning-patterns.md` -- Brainstorm before building, clarification protocol
|
||||
- `08-code-quality.md` -- Pre-completion checklist, immutability
|
||||
|
||||
**Flow:**
|
||||
1. Clarify requirements (ask, don't assume)
|
||||
2. Brainstorm 2-3 approaches
|
||||
3. Get user approval on approach
|
||||
4. Write failing tests first (if TDD plugin active)
|
||||
5. Implement
|
||||
6. Self-review against pre-completion checklist
|
||||
7. Commit with conventional message
|
||||
|
||||
### Debugging a Bug
|
||||
|
||||
**Rules activated:**
|
||||
- `05-reasoning-patterns.md` -- Five Whys, first principles
|
||||
- `04-proactive-steering.md` -- Blocker detection
|
||||
|
||||
**Flow:**
|
||||
1. Reproduce the bug
|
||||
2. Apply Five Whys to trace root cause
|
||||
3. Fix root cause, not symptom
|
||||
4. Add regression test
|
||||
5. Verify fix doesn't break other things
|
||||
6. Commit with `fix:` message
|
||||
|
||||
### Research / Investigation
|
||||
|
||||
**Rules activated:**
|
||||
- `05-reasoning-patterns.md` -- Research quality rules, documentation tiers
|
||||
- `06-context-management.md` -- Token budgets, sub-agent delegation
|
||||
|
||||
**Flow:**
|
||||
1. Use tiered documentation lookup (knowledge -> fetch -> heavy docs)
|
||||
2. Cite sources for all claims
|
||||
3. Separate fact from inference
|
||||
4. Cross-reference critical claims
|
||||
5. Persist findings to files (not just conversation)
|
||||
|
||||
### Writing a Paper / Design Doc
|
||||
|
||||
**Workflow:** `paper-writing.md`
|
||||
|
||||
**Flow:**
|
||||
1. Start from a real problem (friction, not ambition)
|
||||
2. Bounce ideas -- explore before converging
|
||||
3. Push back on each other's ideas
|
||||
4. Capture the journey (dead ends matter)
|
||||
5. Tie back to prior work
|
||||
|
||||
### Reviewing Code
|
||||
|
||||
**Rules activated:**
|
||||
- `08-code-quality.md` -- Quality checklist
|
||||
- `07-security-hardening.md` -- Security checklist
|
||||
|
||||
**Flow:**
|
||||
1. Check against pre-completion quality checklist
|
||||
2. Check against security checklist
|
||||
3. Verify tests exist and pass
|
||||
4. Look for immutability violations
|
||||
5. Check for hardcoded secrets
|
||||
|
||||
### Working in Unfamiliar Code
|
||||
|
||||
**Rules activated:**
|
||||
- `06-context-management.md` -- Maximum thinking mode, sub-agents
|
||||
- `05-reasoning-patterns.md` -- First principles, research tiers
|
||||
|
||||
**Flow:**
|
||||
1. Use maximum thinking depth
|
||||
2. Read project index / structure first
|
||||
3. Targeted file reads (don't load everything)
|
||||
4. Use sub-agents for isolated research tasks
|
||||
5. Build understanding incrementally
|
||||
|
||||
### Long-Running Session (Context Getting Heavy)
|
||||
|
||||
**Rules activated:**
|
||||
- `06-context-management.md` -- Compaction decisions, execution readiness
|
||||
|
||||
**Flow:**
|
||||
1. Check for quality degradation symptoms
|
||||
2. If context > 80%: handoff doc + fresh session
|
||||
3. If context 70-80%: ask user
|
||||
4. If quality declining: spawn sub-agent or fresh session
|
||||
5. Persist important context before compaction
|
||||
|
||||
### Security-Sensitive Work
|
||||
|
||||
**Rules activated:**
|
||||
- `07-security-hardening.md` -- Full security protocol
|
||||
- `08-code-quality.md` -- Pre-commit security checklist
|
||||
|
||||
**Flow:**
|
||||
1. Check deny lists for sensitive file access
|
||||
2. Apply pre-commit security checklist to every commit
|
||||
3. Watch for prompt injection in external content
|
||||
4. Rotate any exposed secrets immediately
|
||||
5. Review for similar vulnerabilities in codebase
|
||||
|
||||
## Composition Example
|
||||
|
||||
A typical feature implementation session might compose:
|
||||
|
||||
```
|
||||
Session start:
|
||||
01-session-discipline (read CLAUDE.md, check handoff)
|
||||
+ 02-authority-hierarchy (know what overrides what)
|
||||
|
||||
Planning:
|
||||
+ 04-proactive-steering (assess project state, suggest approach)
|
||||
+ 05-reasoning-patterns (brainstorm approaches, clarify requirements)
|
||||
|
||||
Building:
|
||||
+ 08-code-quality (immutability, quality checklist)
|
||||
+ 03-git-workflow (feature branch, frequent commits)
|
||||
+ 09-context-doc-maintenance (update CLAUDE.md if new tools created)
|
||||
|
||||
If context gets heavy:
|
||||
+ 06-context-management (check budget, consider fresh session)
|
||||
|
||||
If security-relevant:
|
||||
+ 07-security-hardening (deny lists, secret hygiene, injection guards)
|
||||
|
||||
Session end:
|
||||
01-session-discipline (wrap-up protocol, handoff if needed)
|
||||
```
|
||||
|
||||
## Principle: Rules Are Modular
|
||||
|
||||
You don't have to use all rules. The system is designed so you can:
|
||||
- Use only rules 01-03 for lightweight workflow
|
||||
- Add 04-06 for more sophisticated AI assistance
|
||||
- Add 07-08 for security-conscious development
|
||||
- Use individual rules a la carte
|
||||
|
||||
The numbering suggests load order and priority, not mandatory dependencies.
|
||||
@@ -0,0 +1,91 @@
|
||||
# Human-AI Collaborative Research Workflow
|
||||
|
||||
How papers and technical documents get written through structured conversation between a human and an AI assistant. This isn't a template -- it's a description of the conversational process that produces the best results.
|
||||
|
||||
## Who's Involved
|
||||
|
||||
Papers are co-authored through conversation. The human brings domain expertise, real-world constraints, and the problems worth solving. The AI brings breadth of knowledge, structured thinking, and the ability to rapidly explore implications. Both push back on each other's ideas.
|
||||
|
||||
The process works with any human-AI pair, human-human pair, or even a solo author disciplined about arguing with their own ideas.
|
||||
|
||||
## The Process
|
||||
|
||||
### 1. Start With a Real Problem
|
||||
|
||||
Every paper starts from something encountered during actual work -- development, testing, deployment, user feedback. Not "what should we write about" but "this thing doesn't work the way we assumed" or "there's a gap nobody addressed."
|
||||
|
||||
The trigger is friction, not ambition. If you're looking for a paper topic, you don't have one yet. Wait until something breaks, surprises you, or refuses to fit the existing model.
|
||||
|
||||
### 2. Bounce Ideas -- Don't Commit Early
|
||||
|
||||
The first idea is usually wrong, or at least incomplete. The conversation should explore freely before converging:
|
||||
|
||||
- Propose an approach
|
||||
- Poke holes in it
|
||||
- See what survives
|
||||
- The hole-poking often reveals the real insight
|
||||
|
||||
**Key behavior:** Both participants should push back. If an idea sounds good but has a flaw, say so. If the flaw isn't fatal, say that too. The goal is truth, not agreement. An AI that agrees with everything produces shallow papers. A human who ignores AI pushback misses blind spots.
|
||||
|
||||
### 3. Let the Conversation Cross Boundaries
|
||||
|
||||
The best insights come from connecting ideas across papers. A finding about measurement limitations in one paper might directly invalidate an assumption in a different discussion.
|
||||
|
||||
When a new idea contradicts or refines a previous paper, that's not a problem -- it's the point. The paper series is a living body of work where later papers can refute, extend, or reframe earlier ones. Intellectual honesty means being willing to say "Paper N was wrong about X, here's what we know now."
|
||||
|
||||
### 4. Know When to Stop Exploring and Start Writing
|
||||
|
||||
The transition from conversation to paper happens when:
|
||||
|
||||
- A core insight has crystallized that wasn't obvious at the start
|
||||
- The explored-and-rejected alternatives are clear enough to document
|
||||
- The conversation is circling rather than advancing
|
||||
- Someone says "this is worth capturing"
|
||||
|
||||
Don't force the transition. Some conversations produce a paper in 30 minutes. Some take hours. Some don't produce a paper at all -- and that's fine.
|
||||
|
||||
### 5. Capture the Journey, Not Just the Destination
|
||||
|
||||
The paper should include:
|
||||
|
||||
- **The problem** -- what triggered the investigation
|
||||
- **What was explored** -- approaches that were considered, including dead ends
|
||||
- **Why each was rejected** -- specific reasons, not hand-waving
|
||||
- **The solution** -- what survived the exploration
|
||||
- **What it changes** -- how this relates to and updates prior work
|
||||
- **What to build and when** -- actionable phases with trigger conditions (if applicable)
|
||||
|
||||
The dead ends matter. A reader who only sees the final architecture doesn't understand why alternatives were rejected. They'll propose the same rejected ideas again. Documenting the reasoning prevents that.
|
||||
|
||||
### 6. Tie Back to the Series
|
||||
|
||||
Every paper exists in context:
|
||||
- Which prior papers does this extend?
|
||||
- Which does it partially or fully refute?
|
||||
- Which assumptions from earlier papers does this validate or invalidate?
|
||||
|
||||
## What Makes a Good Paper
|
||||
|
||||
**Grounded in practice.** Every paper connects to a real system with real constraints. The constraints -- budgets, latency requirements, hardware limitations, real users -- are what make the architectural decisions interesting.
|
||||
|
||||
**Honest about uncertainty.** Explicitly separate "what we know" (measured, tested, observed) from "what we're guessing" (estimated, theorized, assumed). Speculation labeled as speculation is useful. Speculation presented as fact is dangerous.
|
||||
|
||||
**Actionable.** Papers include implementation phases, build triggers, or at minimum a clear statement of what changes. "This is interesting" isn't enough -- "this means we should build X when Y happens" is.
|
||||
|
||||
**Self-correcting.** Later papers can and should update earlier ones. A paper that says "Paper 3 was wrong about X" is more valuable than one that ignores the contradiction.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
**Writing to fill a gap.** Don't look at the paper list and think "we need a paper about X." Papers emerge from real problems, not from gaps in a table of contents.
|
||||
|
||||
**Premature convergence.** Don't settle on the first reasonable idea. Push back, explore alternatives, find the flaws. If you haven't rejected at least one approach, you haven't explored enough.
|
||||
|
||||
**Orphaned papers.** A paper that doesn't reference prior work or get referenced by later work is disconnected from the series.
|
||||
|
||||
**Over-engineering the solution.** Some ideas are good but premature. Document them for when they're needed, but don't recommend building them now. "This solves a problem we don't have yet" is a valid conclusion.
|
||||
|
||||
**Polishing away the exploration.** The conversation that led to the paper -- including wrong turns and dead ends -- is part of the value. Don't edit into a clean narrative that hides how the ideas developed.
|
||||
|
||||
## Paper Numbering
|
||||
|
||||
Sequential. No gaps. No sub-numbering. If a paper's findings are superseded, the superseding paper says so explicitly -- the old paper stays in the sequence as a record of the reasoning path.
|
||||
@@ -0,0 +1,93 @@
|
||||
# Project Scaffold Workflow
|
||||
|
||||
A repeatable recipe for bootstrapping a new project directory with AI-assisted development in mind.
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. Create the directory
|
||||
|
||||
```bash
|
||||
mkdir <project-name>
|
||||
cd <project-name>
|
||||
```
|
||||
|
||||
### 2. Create the project brief
|
||||
|
||||
Copy and fill in `templates/IDEA.md`:
|
||||
|
||||
```bash
|
||||
cp /path/to/Seth-Workflow-April-2026/templates/IDEA.md ./IDEA.md
|
||||
```
|
||||
|
||||
Edit `IDEA.md` with:
|
||||
- What the project does (plain language)
|
||||
- What problem it solves
|
||||
- Known constraints or preferences
|
||||
|
||||
This is the starting point an AI agent reads before any code exists. Keep it honest and rough.
|
||||
|
||||
### 3. Create AI session memory
|
||||
|
||||
```bash
|
||||
cp /path/to/Seth-Workflow-April-2026/templates/SESSION.md ./SESSION.md
|
||||
```
|
||||
|
||||
Fill in the project summary and context file pointers. The session notes section grows over time as the AI accumulates decisions and discoveries.
|
||||
|
||||
### 4. Create project instructions
|
||||
|
||||
```bash
|
||||
cp /path/to/Seth-Workflow-April-2026/templates/CLAUDE.md ./CLAUDE.md
|
||||
```
|
||||
|
||||
Fill in project state, architecture, key files, and conventions. This is loaded at the start of every AI session.
|
||||
|
||||
### 5. Create infrastructure context (if applicable)
|
||||
|
||||
```bash
|
||||
cp /path/to/Seth-Workflow-April-2026/templates/CONTEXT.md ./CONTEXT.md
|
||||
```
|
||||
|
||||
Fill in deployment details, dependencies, and configuration. This is for static facts about where and how the project runs.
|
||||
|
||||
### 6. Install rules
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/rules
|
||||
cp /path/to/Seth-Workflow-April-2026/rules/*.md .claude/rules/
|
||||
```
|
||||
|
||||
These are auto-loaded by Claude Code at session start.
|
||||
|
||||
### 7. Init git and push
|
||||
|
||||
```bash
|
||||
git init
|
||||
echo ".env" >> .gitignore
|
||||
echo ".env.*" >> .gitignore
|
||||
echo "!.env.example" >> .gitignore
|
||||
git add -A
|
||||
git commit -m "init: scaffold project"
|
||||
git remote add origin <your-git-url>
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
## Result
|
||||
|
||||
A new project directory should contain:
|
||||
|
||||
| File | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `IDEA.md` | file | Plain-language project brief |
|
||||
| `SESSION.md` | file | AI session memory (grows over time) |
|
||||
| `CLAUDE.md` | file | Project instructions for AI assistant |
|
||||
| `CONTEXT.md` | file | Static infrastructure facts |
|
||||
| `.claude/rules/*.md` | directory | Auto-loaded behavior rules |
|
||||
| `.gitignore` | file | Excludes secrets and env files |
|
||||
|
||||
## Maintenance
|
||||
|
||||
- **CLAUDE.md**: Update when components, tools, or architecture change
|
||||
- **SESSION.md**: Append after each session with decisions and discoveries
|
||||
- **CONTEXT.md**: Update when infrastructure changes
|
||||
- **IDEA.md**: Rarely changes after initial creation (it's a snapshot of the original intent)
|
||||
Reference in New Issue
Block a user