---
name: plan
description: This skill should be used when the user asks to "/gobby plan", "create plan", "plan feature", "write specification". Guide users through structured specification planning. Does NOT create tasks - use /g expand for that.
version: "1.0.0"
category: core
---

# /g plan - Implementation Planning Skill

Guide users through structured requirements gathering and specification writing.
**This skill creates the plan document only.** Use `/g expand <plan-file>` to create tasks.

## Workflow Overview

1. **Requirements Gathering** - Ask questions to understand the feature
2. **Draft Plan** - Write structured plan document
3. **Plan Verification** - Check for TDD anti-patterns and dependency issues
4. **User Approval** - Present plan for review
5. **Hand off to /g expand** - User runs `/g expand` on the plan file

## Step 0: **REQUIRED** ENTER PLAN MODE

Before creating any plan, you must enter Claude Code's plan mode to explore the codebase
and design the implementation approach.

**How to enter**: Use the `EnterPlanMode` tool or respond with a planning-focused message
that triggers plan mode. Plan mode allows you to read files and design without making edits.

**Why required**: Plan creation requires understanding existing code patterns, architecture
constraints, and dependencies before proposing new work.

## Step 1: Requirements Gathering

Ask the user:
1. "What is the name/title for this feature or project?"
2. "What is the high-level goal? (1-2 sentences)"
3. "Are there any constraints or requirements I should know about?"
4. "What are the unknowns or risks?"

## Step 2: Draft Plan Structure

Create a plan with:
- **Epic title**: The overall feature name
- **Phases**: Logical groupings of work (e.g., "Foundation", "Core Implementation", "Polish")
- **Tasks**: Atomic units of work under each phase
- **Dependencies**: Which tasks block which (use notation: `depends: #N` or `depends: Phase N`)

## Step 3: Write Plan Document

Write to `.gobby/plans/{kebab-name}.md`:

```markdown
# {Epic Title}

## Overview
{Goal and context from Step 1}

## Constraints
{Constraints from Step 1}

## Phase 1: {Phase Name}

**Goal**: {One sentence outcome}

**Tasks:**
- [ ] Task 1 title
- [ ] Task 2 title (depends: Task 1)
- [ ] Task 3 title (parallel)

## Phase 2: {Phase Name}

**Goal**: {One sentence outcome}

**Tasks:**
- [ ] Task 4 (depends: Phase 1)
- [ ] Task 5 (parallel with Task 4)

## Task Mapping

<!-- Updated after task creation -->
| Plan Item | Task Ref | Status |
|-----------|----------|--------|
```

**Dependency Notation:**
- Use `(depends: Task 1)` or `(depends: Phase N)` in markdown
- Dependencies are resolved when tasks are created via `create_task` with `parent_task_id`

## Step 4: Plan Verification (REQUIRED)

Before presenting to the user, verify the plan does NOT contain TDD anti-patterns:

### Check 1: No Explicit Test Tasks

Scan for tasks that should NOT exist (TDD sandwich creates these automatically):

**FORBIDDEN patterns - remove these if found:**
- `"Write tests for..."` or `"Add tests for..."`
- `"Test..."` as task title prefix
- `"[TDD]..."` or `"[IMPL]..."` or `"[REF]..."`
- `"Ensure tests pass"` or `"Run tests"`
- `"Add unit tests"` or `"Add integration tests"`
- Any task with `test` as the primary verb

**ALLOWED (these are fine):**
- `"Add TestClient fixture"` (not a test task, but test infrastructure)
- `"Configure pytest settings"` (configuration, not test writing)

### Check 2: Dependency Tree Validation

Verify the dependency structure is valid:

1. **No circular dependencies**: Task A → B → A is invalid
2. **No missing dependencies**: If Task B depends on Task A, Task A must exist
3. **Phase dependencies are valid**: `depends: Phase N` must reference an existing phase
4. **Leaf tasks are implementation work**: Bottom-level tasks should be concrete work, not meta-tasks

### Check 3: Task Categorization

Ensure each task has a valid category:
- `code` - Implementation tasks (gets TDD triplets)
- `config` - Configuration changes (gets TDD triplets)
- `docs` - Documentation tasks (no TDD)
- `refactor` - Refactoring tasks, including updating existing tests (no TDD)
- `test` - Test infrastructure (no TDD)
- `research` - Investigation tasks (no TDD)
- `planning` - Architecture/design (no TDD)
- `manual` - Manual verification (no TDD)

### Verification Output

After verification, report:
```
Plan Verification:
✓ No explicit test tasks found
✓ Dependency tree is valid (no cycles, all refs exist)
✓ Categories assigned correctly

Ready for user approval.
```

Or if issues found:
```
Plan Verification:
✗ Found 2 explicit test tasks (removed):
  - "Add tests for user authentication" → REMOVED
  - "Ensure all tests pass" → REMOVED
✓ Dependency tree is valid
✓ Categories assigned correctly

Plan updated. Ready for user approval.
```

## Step 5: User Approval & Handoff

Present the plan to the user:
- Show the full plan document
- Show verification results
- Ask: "Does this plan look correct? Would you like any changes?"
- Make changes if requested

Once approved, tell the user:
```
Plan approved! To create tasks from this plan, run:

/g expand <plan-file-path>

This will:
1. Create a root epic from the plan
2. Analyze the codebase for context
3. Generate subtasks with TDD instructions and validation criteria
4. Wire up dependencies
```

**This skill ends here.** Task creation is handled by `/g expand`.

---

## Plan Format Reference (for /g expand)

The following sections describe what `/g expand` expects and how it will process your plan.

## Task Granularity Guidelines

Each task should be:
- **Atomic**: Completable in one AI session 
- **Testable**: Has clear pass/fail criteria
- **Verb-led**: Starts with action verb (Add, Create, Implement, Update, Remove)
- **Scoped**: References specific files/functions when possible

Good: "Add TaskEnricher class to src/gobby/tasks/enrich.py"
Bad: "Implement enrichment" (too vague)

## TDD Compatibility (IMPORTANT)

When `/g expand` processes your plan, it applies TDD to each code/config task automatically.

### TDD Triplet Pattern

Each feature task (category: code) gets expanded into three children:
- **[TDD]** - Write failing tests first
- **[IMPL]** - Make tests pass
- **[REF]** - Refactor while keeping tests green

```
Feature Task
├── [TDD] Write failing tests for feature
├── [IMPL] Implement feature
└── [REF] Clean up, verify tests pass
```

### Task Categories

Valid categories (from `src/gobby/storage/tasks.py`):
- `code` - Implementation tasks (gets TDD triplets)
- `config` - Configuration changes (gets TDD triplets)
- `docs` - Documentation tasks (no TDD)
- `refactor` - Refactoring tasks, including updating existing tests (no TDD)
- `test` - Test infrastructure tasks (fixtures, helpers) (no TDD)
- `research` - Investigation tasks (no TDD)
- `planning` - Architecture/design tasks (no TDD)
- `manual` - Manual functional testing (observe output) (no TDD)

### What /g plan Creates vs What /g expand Creates

**Your plan document should contain:**
- Feature tasks with implied `category: code` or `category: config`
- Documentation tasks with implied `category: docs`
- Clear phase structure and dependencies

**Your plan should NOT contain:**
- `[TDD]`, `[IMPL]`, `[REF]` prefixed tasks
- "Write tests for: ..." tasks
- "Ensure tests pass" tasks
- Separate test tasks alongside implementation

**When you run `/g expand <plan-file>`:**

```
Input: .gobby/plans/memory-v3.md

Output task tree:
#100 [epic] Memory V3 Backend                      L1 (from plan title)
├── #101 [task] Create protocol.py                 L2 (from plan content)
│   └─ validation: Protocol class exists with required methods
│   └─ description: TDD: 1) Write tests... 2) Run tests...
├── #102 [task] Create backends/__init__.py        L2
│   └─ validation: Factory function works
│   └─ description: TDD: 1) Write tests... 2) Run tests...
└── #103 [task] Add config schema                  L2
    └─ validation: Config loads and validates
    └─ description: TDD: 1) Write tests... 2) Run tests...
```

**NOTE**: `/g expand` adds TDD instructions and validation criteria automatically.
You just need to write a clear plan with well-defined tasks.

## Example Usage

```
User: /g plan
Agent: "What feature would you like to plan?"
User: "Add dark mode support to the app"
Agent: [Asks clarifying questions]
Agent: [Writes plan to .gobby/plans/dark-mode.md]
Agent: [Runs verification - checks for TDD anti-patterns]
Agent: "Here's the plan. Does this look correct?"
User: "Yes, looks good"
Agent: "Plan approved! To create tasks, run:
        /g expand .gobby/plans/dark-mode.md"

User: /g expand .gobby/plans/dark-mode.md
Agent: [Creates epic, analyzes codebase, generates subtasks with TDD]
Agent: "Created 12 tasks under epic #47 with validation criteria."
```

## Optional: Workflow-Enforced Planning

For stricter enforcement of the planning process with step gates and tool restrictions,
you can activate the `plan-expansion` workflow instead of following this skill manually.

### When to Use the Workflow

Use the workflow when you want:
- **Hard step gates** - Can't proceed to task creation without approval
- **Tool restrictions** - Edit/Write blocked during discovery and gather phases
- **Loop enforcement** - Expansion loop can't be skipped or abandoned
- **State persistence** - Workflow state survives context compaction

### How to Activate

After gathering requirements (Step 1), activate the workflow:

```python
call_tool("gobby-workflows", "activate_workflow", {
    "name": "plan-expansion",
    "variables": {
        "context_analyzed": false,  # Start from discovery
        "apc_choice": null
    }
})
```

Or skip discovery if you've already analyzed the codebase:

```python
call_tool("gobby-workflows", "activate_workflow", {
    "name": "plan-expansion",
    "step": "gather",  # Start from requirements elicitation
    "variables": {
        "context_analyzed": true
    }
})
```

### Workflow Steps

1. **discover** - Analyze existing context (blocks Edit/Write)
2. **gather** - A/P/C elicitation menu (blocks Edit/Write)
3. **draft_plan** - Write plan document (only .gobby/plans/ allowed)
4. **verify_plan** - Check structure and dependencies
5. **create_hierarchy** - Create epic → phase → task structure
6. **expand_loop** - Auto-expand feature tasks with TDD
7. **cleanup** - Evaluate tree, fix deps, identify duplicates, offer cleanup
8. **verify_tasks** - Confirm task tree and update plan
9. **complete** - Workflow finished

### Hybrid Approach

The skills and workflow are complementary:
- **`/g plan`**: Interactive flexibility for requirements and drafting
- **`/g expand`**: Creates tasks with TDD and validation
- **Workflow**: Deterministic expansion with enforced gates

Recommended pattern:
1. Use `/g plan` for Steps 1-5 (requirements through approval)
2. Use `/g expand <plan-file>` to create tasks
3. Or activate `plan-expansion` workflow for stricter enforcement
