Buff Plan

buff-plan v2

Pattern-informed adaptive planning with versioning. Reads from counterfeit memory before generating plans, uses a question elimination ladder to skip what's already known, and writes architectural decisions back to counterfeit. Plans are versioned through git — no separate version files.

Activation

Triggers on: /buff:plan, /buff:plan <goal>, or any user message requesting project planning or architecture design.

/buff:plan [goal]              # create new plan
/buff:plan --refine            # refine current plan based on what's changed
/buff:plan --diff              # show what changed since last version
/buff:plan --version           # show plan version history

Question elimination ladder

A 5-level cascade that progressively eliminates questions. Check each level in order — every level that resolves removes one question from the user interaction:

1. Goal provided as argument? → skip goal question
2. Stack detectable from project files? → skip stack question
3. patterns.json has architecture preference? → skip architecture question (use preferred patterns)
4. decisions.json has prior decisions? → skip constraints question (inherit existing constraints)
5. Existing plan with progress? → skip scope question (refine, don't restart)

Results:

• Mature project with memory: zero questions, instant plan generation.
• New project, no memory: 2-3 questions (existing behavior).
• Somewhere in between: only the questions that cannot be answered from context.

Always state which questions were eliminated and why in the inline summary.

Workflow

Step 1 — Silent project scan (always first)

Before asking anything, gather context by reading:

1. package.json / pyproject.toml / Cargo.toml / bun.lockb → detect stack, dependencies, scripts
2. CLAUDE.md → existing project instructions or constraints
3. Project source tree (top 2 levels) → understand structure, file count, patterns
4. git log --oneline -20 → understand recent work and direction
5. .buff/plan.md → check if a prior plan exists (extend vs. rewrite)
6. README.md → project description and goals if present

Record what was found. Never ask for information that the scan answered.

Step 2 — Counterfeit pre-read

Read from counterfeit memory to inform planning decisions:

1. Read ~/.buff/memory/patterns.json — extract architecture preferences, tech decisions, anti-patterns
2. Read .buff/memory/decisions.json — extract prior architectural decisions for this project
3. Read ~/.buff/memory/corrections.json — extract plan-related corrections (filter for skill: "plan")
4. Read .buff/memory/graph.json — if it exists, understand current project structure and dependencies

Record what was found. Apply patterns and avoid anti-patterns in the plan.

Step 3 — Targeted questions with elimination ladder

Run the 5-level elimination ladder. For each level, check if the information is available from Step 1 or Step 2. Only ask questions that remain unanswered.

Common necessary questions (only if not eliminated):

• "Is this a greenfield build or extending existing functionality?" (if codebase is ambiguous)
• "What is the primary deliverable?" (if goal not specified as argument)
• "Any hard constraints — deadline, specific libs to avoid, target platform?" (if none found in codebase or decisions.json)

Do not ask about the stack, framework, or tools — the scan and counterfeit answer those.

Step 4 — Write .buff/plan.md

Create or overwrite .buff/plan.md with this structure:

# Project Plan
_Generated by buff · [date] · v[N]_
_Previous: v[N-1] ([date]) · v[N-2] ([date])_

## Summary
[2-3 sentence project overview]

## Architecture
_Based on: [provenance — N prior projects, patterns applied]_
_Applying: [list of patterns being used and why]_

[Prose description of system architecture]

### System Diagram

\`\`\`mermaid
graph TD
  [high-level system components and their relationships]
\`\`\`

### Component Diagram

\`\`\`mermaid
graph LR
  [detailed component-level breakdown]
\`\`\`

## Stack

| Layer | Technology | Rationale |
|---|---|---|
| Runtime | ... | ... |
| Framework | ... | ... |
| Database | ... | ... |
| Testing | ... | ... |

## Components

### [Component Name]
- **Purpose**: ...
- **Interface**: ...
- **Dependencies**: ...

[Repeat for each component]

## Phases

### Phase 1 — [Name] [effort: S/M/L]
- [ ] Task 1 [S]
- [ ] Task 2 [M] ⚠ high-risk: N files depend on this
**Test**: [what should be tested after this phase]

### Phase 2 — [Name] [effort: S/M/L]
- [ ] Task 1 [S]
- [ ] Task 2 [L]
**Test**: [what should be tested after this phase]

## Constraints
- [Technical constraints]
- [Scope limits]
- [Known risks]

## Open Questions
- [Anything unresolved that needs decision]

Generate Mermaid diagrams at two levels:

• System diagram: Top-level components (client, server, database, external services)
• Component diagram: Internal module breakdown

Both diagrams must be text-only Mermaid in fenced code blocks — no ASCII art.

Step 5 — Write to counterfeit

After writing the plan, persist decisions back to counterfeit memory:

1. Architectural decisions → append to .buff/memory/decisions.json:

   {
     "decision": "[what was decided]",
     "rationale": "[why]",
     "date": "[today]",
     "skill": "plan",
     "affects": ["[paths or areas affected]"]
   }
   

2. Stack/pattern choices → update ~/.buff/memory/patterns.json:

   • If pattern already exists: increment frequency, update last_used
   • If new pattern with 2+ occurrences across projects: add entry
   • Single instance: do not add to global patterns yet (stays in project decisions.json)

Step 6 — Inline summary

After writing the file, print exactly this format (3-5 lines, no more):

Plan written to .buff/plan.md (v[N])
Sections: Architecture · Components (N) · Phases (N) · Constraints
Stack: [detected stack]
Questions eliminated: [N]/5 (via [sources])
Next: run /buff:execute to begin implementation

Plan output upgrades

Dependency-aware phasing

When graph.json exists, use it to order phases bottom-up — foundations before features. Files with no dependents can be built in any order. Files that many others depend on must be built first.

Order: shared types → utilities → data layer → business logic → API/routes → UI

Risk-flagged tasks

Mark tasks that touch files with high complexity or many dependents:

• 4+ files depend on this file: ⚠ high-risk: N files depend on this
• File has 200+ lines: ⚠ complex: N lines
• File has untested functions: ⚠ untested: [function names]

Effort estimation

Tag each task with effort based on file count and complexity:

Testability

Every phase includes a **Test** line specifying what should be tested after that phase completes. This gives /buff:execute and /buff:test clear targets.

--refine workflow

When the user runs /buff:plan --refine:

1. Read current .buff/plan.md — the existing plan
2. Read .buff/session.log — what's been implemented since the plan was written
3. Read .buff/backlog.md — discoveries and additions from forge/execute
4. Read .buff/memory/graph.json — current project state vs plan assumptions
5. Compare: what was planned vs what exists now
6. Update the plan:
   • Mark completed tasks with [x]
   • Adjust remaining tasks based on what was learned
   • Add new phases if discoveries warrant them
   • Remove tasks that are no longer relevant
   • Update effort estimates based on actual progress
7. Bump version in plan header (e.g., v1 → v2)
8. Write updated .buff/plan.md
9. Write any new decisions to .buff/memory/decisions.json
10. Print inline summary showing what changed

--diff command

Show what changed since the last plan version. Zero overhead — git-native:

git diff HEAD~1 .buff/plan.md

If .buff/plan.md has no git history, print: "No previous versions — plan has not been committed yet."

--version command

Show plan version history. Zero overhead — git-native:

git log --oneline .buff/plan.md

If .buff/plan.md has no git history, print: "No version history — plan has not been committed yet."

Versioning

The plan header includes the current version and previous version dates:

# Project Plan
_Generated by buff · 2026-03-21 · v3_
_Previous: v2 (2026-03-20) · v1 (2026-03-19)_

No separate version files. Git IS the version history. Each time the plan is written or refined, the version number increments. The --diff and --version commands use git to show history.

Writes to counterfeit

After planning completes (both new plans and refinements):

1. Architectural decisions → .buff/memory/decisions.json

   • Each significant decision gets an entry with decision, rationale, date, skill, and affects fields
   • Do not duplicate — if a decision already exists with the same content, skip it

2. Stack/pattern choices → ~/.buff/memory/patterns.json

   • Increment frequency and update last_used if the pattern already exists
   • Add new entries only when frequency reaches 2+ across projects
   • Tech decisions (e.g., "Elysia over Express") follow the same frequency rule

Correction detection

Watch for the user correcting plan output (rejection, replacement, redirect). Follow the correction capture mechanism defined in counterfeit SKILL.md — detect signals, record to learnings.json + corrections.json, promote to patterns.json at 2+ occurrences. Use skill: "plan" when writing correction entries. Apply the correction immediately without arguing.

Plan file rules

• Single file: Always write to .buff/plan.md. Never split unless user explicitly runs /buff:plan --split.
• --split flag: Writes to .buff/plan/architecture.md, .buff/plan/components.md, .buff/plan/phases.md.
• Idempotent: If .buff/plan.md exists and user runs /buff:plan again, ask "Extend existing plan or rewrite?" before overwriting.
• Git-trackable: The .buff/plan.md file is intentionally committed — do not add it to .gitignore.

Stack detection

First check .buff/memory/context.json — if project.stack is already populated, use it and skip detection. Otherwise detect from project files in this order:

If Counterfeit has no stored preference and no project files exist, default to: Bun + TypeScript + Elysia for backend, React + Vite for frontend.

Quality standards

A good plan written by this skill:

• Can be read in under 60 seconds
• Contains enough detail that /buff:execute needs zero clarification
• Has Mermaid diagrams that accurately reflect the architecture
• Lists concrete, actionable tasks (not vague goals)
• Captures all constraints that will affect implementation
• Shows provenance — the user can see what informed each decision
• Tags every task with effort estimation (S/M/L)
• Flags high-risk tasks that touch critical or heavily-depended-on files

Additional Resources

• references/plan-templates.md — Extended plan templates for specific project types (API, CLI, fullstack app, library)