Initial commit

2025-11-29 18:02:18 +08:00
commit 9dede11447
13 changed files with 4585 additions and 0 deletions
--- a/skills/workflow-generator/templates/implement-template.md
+++ b/skills/workflow-generator/templates/implement-template.md
@@ -0,0 +1,394 @@
+---
+description: Execute Elixir implementation plan with verification checkpoints
+argument-hint: [plan-name or path]
+allowed-tools: Read, Write, Edit, Grep, Glob, Task, Bash, TodoWrite, AskUserQuestion
+---
+
+# Implement
+
+Execute an approved Elixir implementation plan with built-in verification and progress tracking.
+
+## Purpose
+
+Follow implementation plans phase-by-phase while maintaining quality through automated verification at each checkpoint.
+
+## Steps to Execute:
+
+### Step 1: Locate and Read Plan
+
+**If user provides plan name:**
+```bash
+# Search for plan file
+find {{DOCS_LOCATION}}/plans -name "*[plan-name]*.md" -type f
+```
+
+**If user provides path:**
+- Read the file directly
+
+**If no argument provided:**
+- List available plans:
+```bash
+ls -t {{DOCS_LOCATION}}/plans/*.md | head -5
+```
+- Ask user which plan to implement
+
+**Read plan completely:**
+- Use Read tool WITHOUT limit/offset
+- Parse the full plan structure
+- Identify all phases/tasks/milestones
+- Note the success criteria
+
+### Step 2: Check Existing Progress
+
+**Look for checkmarks in the plan:**
+- Identify which phases/tasks are already completed (checked)
+- Identify current phase/task (first unchecked item)
+- Verify completed items are actually done (spot check)
+
+**If resuming work:**
+- Trust completed checkmarks unless evidence suggests otherwise
+- Start from first unchecked phase/task
+- Confirm with user if multiple checkmarks exist but work seems incomplete
+
+**If starting fresh:**
+- All items should be unchecked
+- Begin with Phase 1 / Task 1 / Milestone 1
+
+### Step 3: Review Original Context
+
+**Before implementing, review:**
+- Original research that informed the plan
+- Related tickets or documentation
+- Files that will be modified
+
+**Read referenced files:**
+- Read any files mentioned in the current phase/task
+- Understand current implementation
+- Identify exact changes needed
+
+### Step 4: Execute Phase-by-Phase
+
+**For each phase/task/milestone:**
+
+1. **Mark as in-progress** in TodoWrite
+   ```
+   1. [in_progress] Implementing Phase 1: Database Layer
+   2. [pending] Implementing Phase 2: Context Functions
+   3. [pending] Implementing Phase 3: Web Layer
+   ```
+
+2. **Follow the plan's core intent** while remaining flexible:
+   - Stick to the planned approach
+   - Use the code examples as guides
+   - Adapt if you discover better patterns in the codebase
+   - If reality diverges from plan, surface the discrepancy (see Mismatches section)
+
+3. **Make the changes:**
+   - Create new modules as specified
+   - Modify existing modules as specified
+   - Add tests as specified
+   - Update configuration if needed
+
+4. **Run verification** after completing the phase:
+   {{VERIFICATION_COMMANDS}}
+
+5. **Update the plan file** with checkmarks:
+   - Use Edit tool to add `[x]` to completed items in the plan
+   - Example: Change `- [ ] Create schema` to `- [x] Create schema`
+
+6. **Pause for confirmation:**
+   - Present verification results
+   - Show what was completed
+   - Show test output if relevant
+   - Ask: "Phase N complete. Proceed to Phase N+1?"
+   - Wait for user approval before continuing
+
+### Step 5: Handle Plan vs Reality Mismatches
+
+**When reality diverges from the plan:**
+
+**State the discrepancy explicitly:**
+- "The plan expects X to exist at path/to/file.ex:10"
+- "But I found Y instead"
+- "This matters because Z"
+
+**Explain why it matters:**
+- How does this affect the current phase?
+- Can we proceed or must we adjust?
+
+**Request clarity:**
+- "Should I:"
+  - "A) Adapt the plan to match reality"
+  - "B) Update reality to match the plan"
+  - "C) Something else"
+
+**Do not guess** - always surface mismatches and get user input.
+
+### Step 6: Complete Implementation
+
+**After all phases/tasks complete:**
+
+1. **Run full verification suite:**
+   {{FULL_VERIFICATION_SUITE}}
+
+2. **Mark plan as complete:**
+   - Edit plan file frontmatter: `status: completed`
+   - Add completion date to frontmatter
+
+3. **Present final summary:**
+   ```markdown
+   ✅ Implementation Complete: [Plan Name]
+
+   **Phases Completed**: [N]
+   **Files Modified**: [list key files]
+   **Tests Added**: [N]
+
+   **Final Verification**:
+   - ✅ Compilation: Success
+   - ✅ Tests: [N] passed
+   {{QUALITY_TOOLS_SUMMARY}}
+
+   **Next Steps**:
+   - Run QA validation: `/qa "[plan-name]"`
+   - Manual testing recommended
+   - Ready for code review
+   ```
+
+## Verification Commands
+
+### Per-Phase Verification
+
+After each phase, run:
+
+```bash
+# Compile with warnings as errors
+mix compile --warnings-as-errors
+
+# Run tests
+{{TEST_COMMAND}}
+
+# Format check
+mix format --check-formatted
+```
+
+{{OPTIONAL_QUALITY_CHECKS}}
+
+### Full Verification Suite
+
+After completing all phases:
+
+```bash
+# Clean compile
+mix clean && mix compile --warnings-as-errors
+
+# Full test suite
+{{TEST_COMMAND}}
+
+# Format check
+mix format --check-formatted
+
+{{FULL_QUALITY_SUITE}}
+```
+
+## Handling Failures
+
+### If Compilation Fails
+
+1. **Show the error**
+2. **Identify the issue** (missing import, typo, etc.)
+3. **Fix the issue**
+4. **Re-run compilation**
+5. **Do not proceed** until compilation succeeds
+
+### If Tests Fail
+
+1. **Show the test output**
+2. **Analyze the failure**:
+   - Is it expected based on incomplete implementation?
+   - Is it a real bug in the new code?
+   - Is it a pre-existing test that needs updating?
+3. **Fix or update as needed**
+4. **Re-run tests**
+5. **Do not proceed** until tests pass
+
+### If Pre-Commit Hook Triggers
+
+Some projects have pre-commit hooks (format, Credo, etc.):
+
+1. **Read the hook output**
+2. **Apply automatic fixes** if available:
+   ```bash
+   mix format
+   ```
+3. **Address issues** manually if needed
+4. **Re-run verification**
+
+## Progress Tracking
+
+### TodoWrite Usage
+
+Maintain a todo list throughout implementation:
+
+```
+1. [completed] Read and parse plan
+2. [completed] Phase 1: Database Layer
+3. [in_progress] Phase 2: Context Functions
+4. [pending] Phase 3: Web Layer
+5. [pending] Phase 4: Tests
+6. [pending] Final verification
+```
+
+**Update frequently:**
+- Mark completed when phase finishes
+- Mark in-progress when starting new phase
+- Keep user informed of progress
+
+### Plan File Updates
+
+The plan file is the source of truth:
+
+- **Add checkmarks** as phases complete
+- **Update status** in frontmatter
+- **Add notes** if implementation deviates
+- **Preserve history** (don't delete content)
+
+## Flexibility vs Adherence
+
+### Stick to the Plan When:
+- Code examples are clear and correct
+- Planned approach matches codebase patterns
+- No new information contradicts the plan
+
+### Adapt When:
+- You discover better existing patterns
+- File structure has changed
+- Dependencies have been updated
+- Tests reveal issues with planned approach
+
+### Always Surface When:
+- Plan expects something that doesn't exist
+- Existing code contradicts planned changes
+- Uncertainty about how to proceed
+
+## Elixir-Specific Guidelines
+
+### Module Creation
+
+When creating new modules:
+
+```elixir
+defmodule MyApp.Context.Feature do
+  @moduledoc """
+  [Description of module purpose]
+  """
+
+  # Clear module structure
+  # Use statements at top
+  # Group related functions
+  # Add @doc for public functions
+end
+```
+
+### Test Organization
+
+```elixir
+defmodule MyApp.FeatureTest do
+  use MyApp.DataCase  # or ConnCase for controllers
+
+  describe "function_name/1" do
+    test "success case" do
+      # Arrange
+      # Act
+      # Assert
+    end
+
+    test "error case" do
+      # Test error handling
+    end
+  end
+end
+```
+
+### Migration Files
+
+When creating migrations:
+
+```elixir
+defmodule MyApp.Repo.Migrations.CreateFeature do
+  use Ecto.Migration
+
+  def change do
+    create table(:features) do
+      add :name, :string, null: false
+      # ...
+
+      timestamps()
+    end
+
+    # Indexes
+    create index(:features, [:name])
+  end
+end
+```
+
+**Run migration after creation:**
+```bash
+mix ecto.migrate
+```
+
+## Resume Capability
+
+### If Implementation is Interrupted
+
+The plan file preserves state:
+
+1. **Read the plan** - checkmarks show progress
+2. **Verify checkmarks** - spot check completed work
+3. **Continue** from first unchecked item
+4. **No need to restart** - trust the checkmarks
+
+### If Tests Break Later
+
+Sometimes completed phases have tests that break:
+
+1. **Identify which phase's tests broke**
+2. **Analyze the root cause**
+3. **Fix the issue**
+4. **Re-verify that phase**
+5. **Continue with current phase**
+
+## Example Session
+
+**User**: `/implement user-authentication`
+
+**Process**:
+1. Find plan: `{{DOCS_LOCATION}}/plans/2025-01-23-user-authentication.md`
+2. Read plan: 4 phases, all unchecked
+3. Phase 1: Create User schema
+   - Create `lib/my_app/accounts/user.ex`
+   - Create migration
+   - Run `mix ecto.migrate`
+   - Verify: `mix compile && {{TEST_COMMAND}}`
+   - Update plan: `[x] Phase 1: Database Layer`
+   - Pause: "Phase 1 complete. Proceed to Phase 2?"
+4. User: "yes"
+5. Phase 2: Add context functions
+   - Implement in `lib/my_app/accounts.ex`
+   - Add tests
+   - Verify: `mix compile && {{TEST_COMMAND}}`
+   - Update plan: `[x] Phase 2: Context Functions`
+   - Pause: "Phase 2 complete. Proceed to Phase 3?"
+6. Continue until all phases complete
+7. Final verification suite
+8. Mark plan status: completed
+9. Present summary
+
+## Important Reminders
+
+- **One phase at a time**: Complete and verify before moving on
+- **Checkpoints matter**: Don't skip verification
+- **Update the plan**: Keep checkmarks current
+- **Pause for confirmation**: Let user track progress
+- **Surface mismatches**: Don't guess when plan diverges from reality
+- **Trust completions**: Checkmarks indicate done work (unless evidence suggests otherwise)
+- **Maintain quality**: All verifications must pass