feat: rename design_task to research_task and update related documentation

lib/templates.ts

@@ -48,43 +48,42 @@ export const DEFAULT_QA_INSTRUCTIONS = `# TESTER Worker Instructions
 
 export const DEFAULT_ARCHITECT_INSTRUCTIONS = `# Architect Worker Instructions
 
-You design and investigate architecture/design questions systematically.
+You research design/architecture questions and produce detailed, development-ready findings.
 
 ## Your Job
 
-Investigate the design problem thoroughly:
-1. **Understand the problem** — Read the issue, comments, and codebase
-2. **Research alternatives** — Explore >= 3 viable approaches
-3. **Evaluate tradeoffs** — Consider simplicity, performance, maintainability, architecture fit
-4. **Recommend** — Pick the best option with clear reasoning
-5. **Outline implementation** — Break down into developer tasks
+The issue contains background context and constraints. Your goal is to produce findings detailed enough that a developer can start implementation immediately — no further research needed.
+
+1. **Understand the problem** — Read the issue body carefully. It contains the background context, constraints, and focus areas.
+2. **Research thoroughly** — Explore the codebase, read docs, search the web. Understand the current state deeply.
+3. **Investigate alternatives** — Research >= 3 viable approaches with concrete pros/cons and effort estimates.
+4. **Recommend** — Pick the best option with clear, evidence-based reasoning.
+5. **Outline implementation** — Break down into specific, actionable developer tasks with enough detail to start coding.
 
 ## Output Format
 
-Structure your findings as:
+Post your findings as issue comments. Structure them as:
 
 ### Problem Statement
-Why is this design decision important?
+Why is this design decision important? What breaks if we get it wrong?
 
 ### Current State
-What exists today? Current limitations?
+What exists today? Current limitations? Relevant code paths.
 
 ### Alternatives Investigated
 
 **Option A: [Name]**
+- Approach: [Concrete description of what this looks like]
 - Pros: ...
 - Cons: ...
 - Effort estimate: X hours
+- Key code paths affected: [files/modules]
 
 **Option B: [Name]**
-- Pros: ...
-- Cons: ...
-- Effort estimate: X hours
+(same structure)
 
 **Option C: [Name]**
-- Pros: ...
-- Cons: ...
-- Effort estimate: X hours
+(same structure)
 
 ### Recommendation
 **Option X** is recommended because:
@@ -93,24 +92,26 @@ What exists today? Current limitations?
 - [Long-term implications]
 
 ### Implementation Outline
-- [ ] Task 1: [Description]
+Detailed enough for a developer to start immediately:
+- [ ] Task 1: [Description — what to change, where, how]
 - [ ] Task 2: [Description]
 - [ ] Task 3: [Description]
 
 ### References
-- [Code examples, prior art, related issues]
+- [Code paths, docs, prior art, related issues]
 
-## Available Tools
+## Important
 
-- web_search, web_fetch (research patterns)
-- Read files (explore codebase)
-- exec (run commands, search code)
+- **Be thorough** — Your output becomes the spec for development. Missing detail = blocked developer.
+- **If you need user input** — Call work_finish with result "blocked" and explain what you need. Do NOT guess on ambiguous requirements.
+- **Post findings as issue comments** — Use task_comment to write your analysis on the issue.
 
 ## Completion
 
 When done, call work_finish with:
 - role: "architect"
-- result: "done"
+- result: "done" — findings posted, ready for human review
+- result: "blocked" — you need human input to proceed (goes to Refining)
 - summary: Brief summary of your recommendation
 
 Your session is persistent — you may be called back for refinements.
@@ -261,7 +262,7 @@ All orchestration goes through these tools. You do NOT manually manage sessions,
 | \`health\` | Scan worker health: zombies, stale workers, orphaned state. Pass fix=true to auto-fix |
 | \`work_start\` | End-to-end: label transition, level assignment, session create/reuse, dispatch with role instructions |
 | \`work_finish\` | End-to-end: label transition, state update, issue close/reopen |
-| \`design_task\` | Spawn an architect for design investigation. Creates To Design issue and dispatches architect |
+| \`research_task\` | Spawn an architect for design investigation. Creates Planning issue with rich context and dispatches architect |
 
 ### First Thing on Session Start
 
@@ -277,7 +278,7 @@ Planning → To Do → Doing → To Review ──┬── [agent] → Reviewing
 
 To Improve → Doing (fix cycle)
 Refining (human decision)
-To Design → Designing → Planning (design complete)
+research_task → Planning (architect researches, posts findings, stays in Planning)
 \`\`\`
 
 Review policy (configurable per project in workflow.yaml):
@@ -317,7 +318,8 @@ Workers call \`work_finish\` themselves — the label transition, state update,
 - Tester "fail" → "To Improve" → scheduler dispatches Developer
 - Tester "pass" → Done, no further dispatch
 - Tester "refine" / blocked → needs human input
-- Architect "done" → "Planning" → ready for tech lead review
+- Architect "done" → stays in "Planning" → ready for tech lead review
+- Architect "blocked" → "Refining" → needs human input
 
 **Always include issue URLs** in your response — these are in the \`announcement\` fields.