trk ProcessWire Writing Plans
Write comprehensive implementation plans assuming the engineer has zero context for our codebase. Document everything they need to know: exact files, proper ProcessWire API logic, and step-by-step verification commands.
Core Concepts
Announce at start: "I'm using the pw-writing-plans skill to create the implementation plan."
Save plans to: docs/specs/plans/YYYY-MM-DD-<feature-name>.md
File Structure & Scope
- If a spec describes multiple independent subsystems, break it down. Write the plan for the first subsystem only.
- Splitting by responsibility: Identify which Hooks go into
site/ready.php, which schema changes go intosite/migrations/, etc.
Bite-Sized Task Granularity (The TDD Proxy)
Each task must be a single action (2-5 minutes). Rather than pytest, ProcessWire tasks verify implementation via CLI checks (wire field:info, pw_query MCP) or functional scratch scripts.
Plan Document Header (Mandatory)
Every plan MUST start with this header:
# [Feature Name] Implementation Plan
> **For agentic workers:** Execute this plan task-by-task. Steps use checkbox (`- [ ]`) syntax. Do not skip verification steps.
**Goal:** [One sentence describing what this builds]
**Architecture:** [2-3 sentences about the ProcessWire implementation approach]
---
Task Structure Template
Use this format for every ProcessWire task. Ensure you never output placeholders.
### Task 1: Create Summary Field
**Files:**
- Create: `site/migrations/2026_04_13_000000_create_summary_field.php`
- [ ] **Step 1: Write Migration Command**
```bash
wire make:migration create_summary_field --type=create-field --field=summary
```
- [ ] **Step 2: Implement Code (e.g., configuring field in migration file)**
```php
<?php
// ... inside migration up() method ...
$field = $this->wire()->fields->get('summary');
$field->type = $this->wire()->modules->get('FieldtypeTextarea');
$field->label = 'Article Summary';
$field->save();
```
- [ ] **Step 3: Run & Verify Implementation**
Run: `wire migrate`
Run Verification: `wire field:info summary --json`
Expected: Output showing the field is created with label "Article Summary".
- [ ] **Step 4: Commit**
```bash
git add site/migrations/
git commit -m "migration: add summary field"
```
No Placeholders (Hard Rule)
Every step must contain the ACTUAL content an engineer needs. NEVER write these plan failures:
- ❌ "TBD", "TODO", "implement later"
- ❌ "Add appropriate ProcessWire error handling" (Write the actual
$sanitizerlogic instead) - ❌ "Update the hook logic here" (Without providing the exact
addHookAftercode block) - ❌ "Run ProcessWire verification commands" (Without explicitly providing
wire config:getor similar)
Self-Review Checklist
After writing the complete plan, look at it with fresh eyes. Fix issues inline before confirming.
1. Spec coverage: Can you point to a task that implements every aspect of the brainstormed specification?
2. Placeholder scan: Search your plan for "TODO" or "TBD". Fix them.
3. ProcessWire Type Consistency: Did you accidentally use $this->pages in a template context? Fix it to $pages or $this->wire()->pages depending on the file type.
Anti-Patterns & Loophole Closing
- ❌ Skipping Migrations: Recommending manual UI configuration instead of migration files. All schema must be code-driven.
- ❌ Telling instead of coding: Step instructions without actual code blocks or bash scripts.
- ❌ Massive Monolith Tasks: Bundling field creation, template generation, and Hook assignments into a single 20-minute step. Break it down!
Execution Handoff
After saving the plan, say:
"Plan complete and saved to <filename>.md. Ready to execute task by task?"