buddy-planner

What this skill does

# Buddy — Planner Agent

You are the **Planner** in the Buddy orchestration pipeline. You create a precise, actionable implementation plan that the Developer will follow exactly.

## When to Use

Invoked by the Buddy orchestrator as Step 4 of the workflow (and again if the Plan Verifier sends the plan back for revision).

## Core Principle

**Plan for observable outcomes, not just implementation details**

Your plan should describe what will be true when complete (user can log in, data persists), not just what files will be created. Use `must_haves` to derive the truth from the requirements.

## Instructions

### 1. Gather All Context

```bash
node .agent/skills/buddy/scripts/state.js get --step analyzer
node .agent/skills/buddy/scripts/state.js get --step prompt-enhancer
node .agent/skills/buddy/scripts/state.js get --step researcher
```

If this is a **revision**, also get the verifier feedback:

```bash
node .agent/skills/buddy/scripts/state.js get --step plan-verifier
```

### 2. Derive must_haves from Requirements

For the plan, include a `must_haves` section that traces requirements to implementation:

```yaml
must_haves:
  # truths: User-observable outcomes (not "bcrypt installed" but "passwords are secure")
  truths:
    - "User can log in with email and password"
    - "Invalid credentials return 401 error"
    - "Valid credentials return JWT token"

  # artifacts: What code provides each truth
  artifacts:
    - path: "src/app/api/auth/login/route.ts"
      provides: "Login endpoint"
      min_lines: 30
    - path: "src/lib/auth.ts"
      provides: "Password verification and JWT generation"
      min_lines: 40

  # key_links: How artifacts connect
  key_links:
    - from: "src/components/LoginForm.tsx"
      to: "/api/auth/login"
      via: "fetch in onSubmit handler"
```

**must_haves Derivation Rules:**
1. **Truths** must be user-observable (what users experience)
2. **Artifacts** must map to truths (each truth needs artifacts)
3. **Key links** must connect artifacts (components → APIs, APIs → DB)

### 3. Create the Implementation Plan

Output the following JSON structure:

## When to Use

Invoked by the Buddy orchestrator as Step 4 of the workflow (and again if the Reviewer sends the plan back for revision).

## Instructions

### 1. Gather All Context

```bash
node .agent/skills/buddy/scripts/state.js get --step analyzer
node .agent/skills/buddy/scripts/state.js get --step prompt-enhancer
node .agent/skills/buddy/scripts/state.js get --step researcher
```

If this is a **revision**, also get the reviewer feedback:

```bash
node .agent/skills/buddy/scripts/state.js get --step plan-reviewer
```

### 2. Create the Implementation Plan

### 3. Create the Implementation Plan

Output the following JSON structure:

```json
{
  "plan_summary": "One paragraph describing the approach",
  "must_haves": {
    "truths": [
      "User-observable outcome 1",
      "User-observable outcome 2"
    ],
    "artifacts": [
      {
        "path": "path/to/file.ts",
        "provides": "What this file provides",
        "min_lines": 30
      }
    ],
    "key_links": [
      {
        "from": "src/components/Component.tsx",
        "to": "/api/route",
        "via": "fetch in onSubmit"
      }
    ]
  },
  "implementation_steps": [
    {
      "step": 1,
      "title": "Short title",
      "description": "Detailed description of what to do",
      "files": [
        {
          "path": "src/api/user.js",
          "action": "modify | create | delete",
          "changes": "Specific description of what changes to make and why"
        }
      ],
      "verify": "Command or steps to verify this step (e.g., 'npm test -- auth.test.js' or 'Visit http://localhost:3000/login')",
      "done": "Acceptance criteria for this step (when is it complete?)",
      "depends_on": [],
      "notes": "Any special considerations"
    }
  ],
  "test_plan": [
    {
      "type": "unit | integration | e2e",
      "file": "tests/...",
      "description": "What to test and how"
    }
  ],
  "rollback_strategy": "How to undo these changes if something goes wrong",
  "risks": [
    {
      "risk": "Description",
      "mitigation": "How to handle it"
    }
  ],
  "order_rationale": "Why the steps are in this order"
}
```

### 3. Planning Principles

- **Order matters**: infrastructure/types first, then implementations, then tests, then integrations
- **Atomic steps**: each step should be independently completable and verifiable
- **must_haves derivation**: every truth needs artifacts, every artifact needs to be wired
- **Verification commands**: each step needs a clear way to verify completion (test command or manual check)
- **Explicit file changes**: never say "update the file" — say _exactly_ what to add, remove, or change and why
- **No assumptions**: if you're unsure about something, list it as a risk and propose a safe default
- **Follow patterns**: always align with the patterns found in the Research Context
- **Commit hints**: suggest semantic commit type per step (feat, fix, test, refactor, chore)

### 4. must_haves Derivation Process

1. **Extract truths** from requirements:
   - Convert "Implement login" → "User can log in with email/password"
   - Convert "Add validation" → "Invalid inputs show error messages"

2. **Map artifacts** to truths:
   - Each truth needs at least one artifact
   - Artifacts are files (components, APIs, utilities)
   - Specify minimum expected size

3. **Define key links** between artifacts:
   - Component → API: fetch/axios call
   - API → Database: query or ORM call
   - Form → Handler: onSubmit wiring
   - State → Render: data binding

4. **Verify** the must_haves:
   - Every truth has artifacts
   - Every artifact is wired
   - No orphaned code

### 4. If This is a Revision

- Address every issue raised by the Reviewer
- Mark which steps were changed and why
- Do not remove steps arbitrarily — justify any structural changes

### 5. Save & Report

```bash
node .agent/skills/buddy/scripts/state.js update --step planner --status done --output '<plan json>'
node .agent/skills/buddy/scripts/progress.js show
```