gh-bradleygolden-claude-marketplace-elixir-plugins-meta/skills/workflow-generator/templates/plan-template.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Create detailed implementation plan for Elixir feature or task	brief-description	Read, Grep, Glob, Task, Bash, TodoWrite, Write, AskUserQuestion

Plan

Generate a detailed, phased implementation plan for Elixir projects.

Purpose

Create executable implementation plans with clear phases, success criteria, and verification steps for Elixir development.

Steps to Execute:

Step 1: Context Gathering

Read referenced files completely:

• If user references files, code, or tickets, read them FULLY first
• Use Read tool WITHOUT limit/offset parameters
• Gather complete context before any planning

Spawn parallel research agents:

Use Task tool to spawn agents that will inform your plan:

1. codebase-locator (subagent_type="general-purpose"):

   • Find relevant Elixir modules, contexts, schemas
   • Locate similar implementations for reference
   • Identify files that will need modification

2. codebase-analyzer (subagent_type="general-purpose"):

   • Analyze existing patterns and conventions
   • Understand current architecture and design
   • Trace how similar features are implemented

3. Skill (core:hex-docs-search):

   • Research relevant Hex packages if needed
   • Understand framework patterns (Phoenix, Ecto, etc.)
   • Find official documentation for libraries

Wait for all agents before proceeding.

Present your informed understanding:

• Summarize what you learned with file:line references
• Show the current implementation state
• Identify what needs to change

Ask ONLY questions that code cannot answer:

• Design decisions and trade-offs
• User preferences between valid approaches
• Clarifications on requirements

Step 2: Research & Discovery

If user provides corrections or additional context:

• Verify through additional research
• Spawn new sub-agents if needed
• Update your understanding

Present design options:

• Show 2-3 valid approaches with pros/cons
• Include code examples for each approach
• Reference similar patterns in the codebase
• Explain trade-offs specific to Elixir/Phoenix

Get user approval on approach before writing detailed plan.

Step 3: Plan Structure Proposal

Propose phased implementation outline based on {{PLANNING_STYLE}}:

{{#if PLANNING_STYLE equals "Detailed phases"}} Phased Structure:

1. Phase 1: [Name] - [Brief description]
2. Phase 2: [Name] - [Brief description]
3. Phase 3: [Name] - [Brief description]

Each phase will include:

• Specific module/file changes
• Code examples showing changes
• Verification steps {{/if}}

{{#if PLANNING_STYLE equals "Task checklist"}} Task Checklist Structure:

• Task 1: [Description]
• Task 2: [Description]
• Task 3: [Description]

Each task will include:

• Files to modify
• Expected outcome
• How to verify {{/if}}

{{#if PLANNING_STYLE equals "Milestone-based"}} Milestone Structure:

• Milestone 1: [Deliverable]
• Milestone 2: [Deliverable]
• Milestone 3: [Deliverable]

Each milestone will include:

• Tasks required
• Acceptance criteria
• Verification approach {{/if}}

Get user approval before writing detailed plan.

Step 4: Write Detailed Plan

Gather metadata:

date +"%Y-%m-%d" && git log -1 --format="%H" && git branch --show-current && git config user.name

Create plan file:

• Location: {{DOCS_LOCATION}}/plans/YYYY-MM-DD-description.md
• Format: {{DOCS_LOCATION}}/plans/YYYY-MM-DD-brief-kebab-case-description.md
• Example: {{DOCS_LOCATION}}/plans/2025-01-23-add-user-authentication.md

Plan Template:

---
date: [ISO timestamp]
author: [Git user name]
commit: [Current commit hash]
branch: [Current branch name]
repository: [Repository name]
title: "[Feature/Task Description]"
status: planned
tags: [plan, elixir, {{PROJECT_TYPE_TAGS}}]
---

# Plan: [Feature/Task Description]

**Date**: [Current date]
**Author**: [Git user name]
**Branch**: [Current branch]
**Project Type**: {{PROJECT_TYPE}}

## Overview

[2-3 sentences describing what this plan accomplishes and why]

## Current State

[Describe the current implementation with file:line references]

**Existing Modules:**
- `lib/my_app/context.ex` - [What it currently does]
- `lib/my_app_web/controllers/controller.ex` - [What it currently does]

**Current Behavior:**
[Describe how the system currently works in this area]

## Desired End State

[Describe the target implementation]

**New/Modified Modules:**
- `lib/my_app/new_context.ex` - [What it will do]
- `lib/my_app/schemas/new_schema.ex` - [What it will contain]

**Target Behavior:**
[Describe how the system should work after implementation]

{{#if PLANNING_STYLE equals "Detailed phases"}}
## Implementation Phases

### Phase 1: [Phase Name]

**Goal**: [What this phase accomplishes]

**Changes Required:**

1. **Create/Modify** `lib/my_app/schema.ex`
   ```elixir
   defmodule MyApp.Schema do
     use Ecto.Schema
     import Ecto.Changeset

     schema "table" do
       field :name, :string
       # Add fields
       timestamps()
     end

     def changeset(struct, params) do
       struct
       |> cast(params, [:name])
       |> validate_required([:name])
     end
   end

2. Create/Modify lib/my_app/context.ex

   defmodule MyApp.Context do
     alias MyApp.{Repo, Schema}
   
     def create_thing(attrs) do
       %Schema{}
       |> Schema.changeset(attrs)
       |> Repo.insert()
     end
   end
   

Verification:

• mix compile --warnings-as-errors succeeds
• {{TEST_COMMAND}} passes
• Schema migration runs cleanly {{/if}}

{{#if PLANNING_STYLE equals "Task checklist"}}

Implementation Tasks

• Task 1: Create Ecto schema for [entity]

  • File: lib/my_app/schemas/entity.ex
  • Include fields: [list]
  • Add validations: [list]
  • Verify: Schema tests pass

• Task 2: Add context functions

  • File: lib/my_app/contexts/context.ex
  • Functions: create/1, update/2, delete/1, list/0
  • Verify: Context tests pass

• Task 3: Create controller/LiveView

  • File: lib/my_app_web/controllers/entity_controller.ex
  • Actions: index, show, new, create, edit, update, delete
  • Verify: Controller tests pass {{/if}}

{{#if PLANNING_STYLE equals "Milestone-based"}}

Implementation Milestones

Milestone 1: Database Layer Complete

Deliverables:

• Ecto schema with validations
• Migration file
• Basic CRUD context functions

Tasks:

• Create schema module
• Write migration
• Implement context
• Add tests

Acceptance Criteria:

• All database operations work
• Tests cover happy and error paths
• Migration runs without errors

Milestone 2: Web Layer Complete

Deliverables:

• Controller or LiveView
• Templates/HEEx
• Routes configured

Tasks:

• Create controller/LiveView
• Add templates
• Update router
• Add integration tests

Acceptance Criteria:

• All CRUD operations accessible via web
• UI renders correctly
• Integration tests pass {{/if}}

Success Criteria

Automated Verification

Run these commands to verify implementation:

• Compilation: mix compile --warnings-as-errors succeeds
• Tests: {{TEST_COMMAND}} passes {{QUALITY_TOOLS_CHECKS}}

Manual Verification

Human verification required:

• Feature works as expected in browser/IEx
• Edge cases handled appropriately
• Error messages are clear and helpful
• Documentation updated (@moduledoc, @doc)
• No console errors or warnings
• Performance is acceptable

Dependencies

[List any Hex packages that need to be added to mix.exs]

Configuration Changes

[List any config changes needed in config/]

Migration Strategy

[If database changes, describe migration approach]

Rollback Plan

[How to undo these changes if needed]

Notes

[Any additional context, decisions, or considerations]

### Step 5: Present Plan

**Show user the created plan:**
- Location of plan file
- Brief summary of phases/tasks
- Success criteria overview

**Confirm readiness:**
- Ask if plan looks good or needs adjustments
- Offer to clarify any phase/task
- Ready to proceed to implementation

## Important Guidelines

### Complete Alignment Required

**No open questions in final plan:**
- All technical decisions resolved
- All design choices made
- All ambiguities clarified
- Ready for immediate execution

### Success Criteria Format

**Separate automated from manual:**

**Automated** = Can run via command:
- `{{TEST_COMMAND}}`
- `mix compile --warnings-as-errors`
- `mix format --check-formatted`
{{QUALITY_TOOLS_EXAMPLES}}

**Manual** = Requires human verification:
- UI functionality
- UX quality
- Edge case handling
- Documentation quality

### Code Examples Required

Every phase/task with code changes MUST include:
- Specific file paths
- Actual Elixir code examples
- Not pseudo-code or placeholders
- Show imports, use statements, module attributes

### Elixir-Specific Considerations

**For Phoenix projects:**
- Context boundaries and public APIs
- Controller vs LiveView choice
- Route placement and naming
- Template organization

**For Ecto changes:**
- Schema design and relationships
- Changeset validations
- Migration strategy (reversible)
- Repo operations (transaction needs)

**For Process-based features:**
- Supervision tree placement
- GenServer/Agent design
- Message passing patterns
- Process naming and registration

## Non-Negotiable Standards

1. **Research first**: Always gather context before planning
2. **No placeholders**: Every code example must be real Elixir code
3. **File references**: Always include specific file paths
4. **Success criteria**: Always separate automated vs manual
5. **User approval**: Get approval on approach before detailed plan
6. **Complete plan**: No open questions when finished

## Example Scenario

**User**: "Add user authentication to the Phoenix app"

**Process**:
1. Research existing auth patterns in codebase
2. Present options: Guardian vs Pow vs custom
3. User chooses Guardian
4. Propose 5 phases: Schema, Context, Plugs, Controllers, Tests
5. User approves
6. Write detailed plan with Guardian-specific code examples
7. Include Guardian dependency in plan
8. Define success criteria (auth tests pass, login works)