# Buff Plan

> This skill should be used when the user asks to "plan a project", "create a plan", "start planning", "design the architecture", "run /buff:plan", "what should I build", "help me structure this project", "refine the plan", "show plan diff", "plan version history", or begins a new project or feature. Pattern-informed adaptive planning that reads from counterfeit memory, eliminates redundant questions, and writes versioned plans to .buff/plan.md. Supports --refine, --diff, and --version commands.

- Skill: `majiayu000/buff-plan` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/buff-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/buff-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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:

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

| Tag | Meaning |
|---|---|
| `[S]` | 1-2 files, straightforward logic |
| `[M]` | 3-5 files, moderate complexity or cross-cutting |
| `[L]` | 6+ files, complex logic, or high-risk dependencies |

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

```bash
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:

```bash
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:

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

| File found | Inferred stack |
|---|---|
| `bun.lockb` | Bun + TypeScript |
| `package.json` + `next.config.*` | Next.js |
| `package.json` + `vite.config.*` | Vite + TS/JS |
| `requirements.txt` / `pyproject.toml` | Python |
| `Cargo.toml` | Rust |
| `go.mod` | Go |
| Nothing | Fall back to Counterfeit global preferences |

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)