Initial commit
This commit is contained in:
Zhongwei Li
408
skills/workflow-generator/templates/plan-template.md
Normal file
408
skills/workflow-generator/templates/plan-template.md
Normal file
@@ -0,0 +1,408 @@
|
||||
---
|
||||
description: Create detailed implementation plan for Elixir feature or task
|
||||
argument-hint: [brief-description]
|
||||
allowed-tools: 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:**
|
||||
```bash
|
||||
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:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
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`
|
||||
```elixir
|
||||
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)
|
||||
Reference in New Issue
Block a user