/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

•Requirements Gathering - Ask questions to understand the feature
•Draft Plan - Write structured plan document
•Plan Verification - Check for TDD anti-patterns and dependency issues
•User Approval - Present plan for review
•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:

•"What is the name/title for this feature or project?"
•"What is the high-level goal? (1-2 sentences)"
•"Are there any constraints or requirements I should know about?"
•"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:

•No circular dependencies: Task A → B → A is invalid
•No missing dependencies: If Task B depends on Task A, Task A must exist
•Phase dependencies are valid: depends: Phase N must reference an existing phase
•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:

code

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:

code

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:

code

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

code

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

code

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

code

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

•discover - Analyze existing context (blocks Edit/Write)
•gather - A/P/C elicitation menu (blocks Edit/Write)
•draft_plan - Write plan document (only .gobby/plans/ allowed)
•verify_plan - Check structure and dependencies
•create_hierarchy - Create epic → phase → task structure
•expand_loop - Auto-expand feature tasks with TDD
•cleanup - Evaluate tree, fix deps, identify duplicates, offer cleanup
•verify_tasks - Confirm task tree and update plan
•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:

•Use /g plan for Steps 1-5 (requirements through approval)
•Use /g expand <plan-file> to create tasks
•Or activate plan-expansion workflow for stricter enforcement