plugins/projman/agents/planner.md

@@ -310,14 +310,55 @@ Think through the technical approach:
 - `[Sprint 17] fix: Resolve login timeout issue`
 - `[Sprint 18] refactor: Extract authentication module`
 
-**Task Granularity Guidelines:**
-| Size | Scope | Example |
-|------|-------|---------|
-| **Small** | 1-2 hours, single file/component | Add validation to one field |
-| **Medium** | Half day, multiple files, one feature | Implement new API endpoint |
-| **Large** | Should be broken down | Full authentication system |
+**Task Sizing Rules (MANDATORY):**
 
-**If a task is too large, break it down into smaller tasks.**
+| Effort | Files | Checklist Items | Max Tool Calls | Agent Scope |
+|--------|-------|-----------------|----------------|-------------|
+| **XS** | 1 file | 0-2 items | ~30 | Single function/fix |
+| **S** | 1 file | 2-4 items | ~50 | Single file feature |
+| **M** | 2-3 files | 4-6 items | ~80 | Multi-file feature |
+| **L** | MUST BREAK DOWN | - | - | Too large for one agent |
+| **XL** | MUST BREAK DOWN | - | - | Way too large |
+
+**CRITICAL: L and XL tasks MUST be broken into subtasks.**
+
+**Why:** Sprint 3 showed agents running 400+ tool calls on single "implement hook" tasks. This causes:
+- Long wait times (1+ hour per task)
+- No progress visibility
+- Resource exhaustion
+- Difficult debugging
+
+**Task Scoping Checklist:**
+1. Can this be completed in one file? → XS or S
+2. Does it touch 2-3 files? → M (max)
+3. Does it touch 4+ files? → MUST break down
+4. Does it require complex decision-making? → MUST break down
+5. Would you estimate 50+ tool calls? → MUST break down
+
+**Breaking Down Large Tasks:**
+
+**BAD (L/XL - too broad):**
+```
+[Sprint 3] feat: Implement git-flow branch validation hook
+Labels: Efforts/L, ...
+```
+
+**GOOD (broken into S/M tasks):**
+```
+[Sprint 3] feat: Create branch validation hook skeleton
+Labels: Efforts/S, ...
+
+[Sprint 3] feat: Add prefix pattern validation (feat/, fix/, etc.)
+Labels: Efforts/S, ...
+
+[Sprint 3] feat: Add issue number extraction and validation
+Labels: Efforts/S, ...
+
+[Sprint 3] test: Add branch validation unit tests
+Labels: Efforts/S, ...
+```
+
+**If a task is estimated L or XL, STOP and break it down before creating.**
 
 **IMPORTANT: Include wiki implementation reference in issue body:**
 
@@ -479,5 +520,7 @@ Sprint 17 - User Authentication (Due: 2025-02-01)
 11. **Always use suggest_labels** - Don't guess labels
 12. **Always think through architecture** - Consider edge cases
 13. **Always cleanup local files** - Delete after migrating to wiki
+14. **NEVER create L/XL tasks without breakdown** - Large tasks MUST be split into S/M subtasks
+15. **Enforce task scoping** - If task touches 4+ files or needs 50+ tool calls, break it down
 
 You are the thoughtful planner who ensures sprints are well-prepared, architecturally sound, and learn from past experiences. Take your time, ask questions, and create comprehensive plans that set the team up for success.

plugins/projman/commands/sprint-plan.md

@@ -155,15 +155,70 @@ The planner agent will:
 - `[Sprint 17] fix: Resolve login timeout issue`
 - `[Sprint 18] refactor: Extract authentication module`
 
-## Task Granularity Guidelines
+## Task Sizing Rules (MANDATORY)
 
-| Size | Scope | Example |
-|------|-------|---------|
-| **Small** | 1-2 hours, single file/component | Add validation to one field |
-| **Medium** | Half day, multiple files, one feature | Implement new API endpoint |
-| **Large** | Should be broken down | Full authentication system |
+**CRITICAL: Tasks sized L or XL MUST be broken down into smaller tasks.**
 
-**If a task is too large, break it down into smaller tasks.**
+| Effort | Files | Checklist Items | Max Tool Calls | Agent Scope |
+|--------|-------|-----------------|----------------|-------------|
+| **XS** | 1 file | 0-2 items | ~30 | Single function/fix |
+| **S** | 1 file | 2-4 items | ~50 | Single file feature |
+| **M** | 2-3 files | 4-6 items | ~80 | Multi-file feature |
+| **L** | MUST BREAK DOWN | - | - | Too large for one agent |
+| **XL** | MUST BREAK DOWN | - | - | Way too large |
+
+**Why This Matters:**
+- Agents running 400+ tool calls take 1+ hour, with no visibility
+- Large tasks lack clear completion criteria
+- Debugging failures is extremely difficult
+- Small tasks enable parallel execution
+
+**Scoping Checklist:**
+1. Can this be completed in one file? → XS or S
+2. Does it touch 2-3 files? → M (maximum for single task)
+3. Does it touch 4+ files? → MUST break down
+4. Would you estimate 50+ tool calls? → MUST break down
+5. Does it require complex decision-making mid-task? → MUST break down
+
+**Example Breakdown:**
+
+**BAD (L - too broad):**
+```
+[Sprint 3] feat: Implement schema diff detection hook
+Labels: Efforts/L
+- Hook skeleton
+- Pattern detection for DROP/ALTER/RENAME
+- Warning output formatting
+- Integration with hooks.json
+```
+
+**GOOD (broken into S tasks):**
+```
+[Sprint 3] feat: Create schema-diff-check.sh hook skeleton
+Labels: Efforts/S
+- [ ] Create hook file with standard header
+- [ ] Add file type detection for SQL/migrations
+- [ ] Exit 0 (non-blocking)
+
+[Sprint 3] feat: Add DROP/ALTER pattern detection
+Labels: Efforts/S
+- [ ] Detect DROP COLUMN/TABLE/INDEX
+- [ ] Detect ALTER TYPE changes
+- [ ] Detect RENAME operations
+
+[Sprint 3] feat: Add warning output formatting
+Labels: Efforts/S
+- [ ] Format breaking change warnings
+- [ ] Add hook prefix to output
+- [ ] Test output visibility
+
+[Sprint 3] chore: Register hook in hooks.json
+Labels: Efforts/XS
+- [ ] Add PostToolUse:Edit hook entry
+- [ ] Test hook triggers on SQL edits
+```
+
+**The planner MUST refuse to create L/XL tasks without breakdown.**
 
 ## MCP Tools Available