feat: rename design_task to research_task and update related documentation

2026-02-16 18:47:01 +08:00
parent d87b9f68a2
commit b57ede0863
15 changed files with 249 additions and 173 deletions
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -583,7 +583,7 @@ Every piece of data and where it lives:
 │  status         → read labels + read state                      │
 │  health         → check sessions + fix zombies                  │
 │  project_register → labels + prompts + state init (one-time)    │
-│  design_task    → architect dispatch                            │
+│  research_task  → architect dispatch                            │
 │                                                                 │
 │  Bootstrap hook → injects role instructions into worker sessions│
 │  Review pass    → polls PR status, auto-merges approved PRs     │
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -164,24 +164,10 @@ workflow:
      type: terminal
      label: Done
      color: "#5cb85c"
-    toDesign:
-      type: queue
-      role: architect
-      label: To Design
-      color: "#0075ca"
-      priority: 1
-      on:
-        PICKUP: designing
-    designing:
-      type: active
-      role: architect
-      label: Designing
-      color: "#d4c5f9"
-      on:
-        COMPLETE: planning
-        BLOCKED: refining
 ```

+Note: The architect role has no dedicated workflow states. Design tasks are triggered via `research_task` tool only — issues go directly to Planning.
+
 **State types:**

 | Type | Description |
@@ -340,7 +326,7 @@ Restrict DevClaw tools to your orchestrator agent:
            "project_register",
            "setup",
            "onboard",
-            "design_task"
+            "research_task"
          ]
        }
      }
--- a/docs/MANAGEMENT.md
+++ b/docs/MANAGEMENT.md
@@ -53,7 +53,7 @@ Planning → To Do → Doing → To Test → Testing → Done
                                    ↘ Refining → (human decision)
 ```

-The ARCHITECT role adds a parallel track: `To Design → Designing → Planning`.
+The ARCHITECT role is tool-triggered only via `research_task` — no queue states. Issues go directly to Planning, the architect researches and posts findings, then the issue stays in Planning for human review.

 Every label transition, state update, and audit log entry happens atomically inside the plugin. The orchestrator agent cannot skip a step, forget a label, or corrupt session state — because those operations are deterministic code, not instructions an LLM follows imperfectly.

--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -17,7 +17,7 @@ Planning → To Do → Doing → To Test → Testing → Done
                         ↘ In Review → (PR approved → auto-merge) → To Test
                                    ↘ To Improve → Doing (merge conflict / fix cycle)
                                    ↘ Refining → (human decision)
-To Design → Designing → Planning
+research_task → Planning (architect researches, stays in Planning)
 ```

 States have types (`queue`, `active`, `hold`, `review`, `terminal`), transitions with actions (`gitPull`, `detectPr`, `mergePr`, `closeIssue`, `reopenIssue`), and review checks (`prMerged`, `prApproved`).
@@ -46,7 +46,7 @@ DEVELOPER can submit a PR for human review (`result: "review"`), which transitio

 ### Architect Role

-The architect role enables design investigations. `design_task` creates a `To Design` issue and dispatches an architect worker. The architect completes with `done` (→ Planning) or `blocked` (→ Refining).
+The architect role enables design investigations. `research_task` creates a Planning issue with rich context and dispatches an architect worker directly (no queue states). The architect posts findings as comments, then completes with `done` (stays in Planning for human review) or `blocked` (→ Refining).

 ### Workspace Layout Migration

--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -28,7 +28,7 @@ npm run build
 | [lib/projects.test.ts](../lib/projects.test.ts) | Project state: read/write, worker state, atomic file operations |
 | [lib/bootstrap-hook.test.ts](../lib/bootstrap-hook.test.ts) | Bootstrap hook: role instruction loading, source tracking, overloads |
 | [lib/tools/task-update.test.ts](../lib/tools/task-update.test.ts) | Task update tool: label transitions, validation |
-| [lib/tools/design-task.test.ts](../lib/tools/design-task.test.ts) | Design task tool: architect dispatch |
+| [lib/tools/research-task.test.ts](../lib/tools/research-task.test.ts) | Research task tool: architect dispatch |
 | [lib/tools/queue-status.test.ts](../lib/tools/queue-status.test.ts) | Queue status formatting |
 | [lib/setup/migrate-layout.test.ts](../lib/setup/migrate-layout.test.ts) | Workspace layout migration: `projects/` → `devclaw/` |

--- a/docs/TOOLS.md
+++ b/docs/TOOLS.md
@@ -79,8 +79,8 @@ Complete a task with a result. Called by workers (DEVELOPER/TESTER/ARCHITECT sub
 | tester | `"fail"` | Testing → To Improve | Issue reopened |
 | tester | `"refine"` | Testing → Refining | Awaits human decision |
 | tester | `"blocked"` | Testing → Refining | Awaits human decision |
-| architect | `"done"` | Designing → Planning | Design complete |
-| architect | `"blocked"` | Designing → Refining | Awaits human decision |
+| architect | `"done"` | stays in Planning | Design complete, ready for human review |
+| architect | `"blocked"` | Planning → Refining | Awaits human decision |

 **What it does atomically:**

@@ -140,7 +140,7 @@ Change an issue's state label manually without going through the full pickup/com
 | `state` | StateLabel | Yes | New state label |
 | `reason` | string | No | Audit log reason for the change |

-**Valid states:** `Planning`, `To Do`, `Doing`, `To Test`, `Testing`, `Done`, `To Improve`, `Refining`, `In Review`, `To Design`, `Designing`
+**Valid states:** `Planning`, `To Do`, `Doing`, `To Test`, `Testing`, `Done`, `To Improve`, `Refining`, `In Review`

 **Use cases:**

@@ -331,11 +331,11 @@ Conversational onboarding guide. Returns step-by-step instructions for the agent

 ---

-### `design_task`
+### `research_task`

-Spawn an architect for a design investigation. Creates a "To Design" issue and dispatches an architect worker.
+Spawn an architect for a design investigation. Creates a Planning issue with rich context and dispatches an architect worker. No queue states — tool-triggered only.

-**Source:** [`lib/tools/design-task.ts`](../lib/tools/design-task.ts)
+**Source:** [`lib/tools/research-task.ts`](../lib/tools/research-task.ts)

 **Parameters:**

@@ -343,8 +343,9 @@ Spawn an architect for a design investigation. Creates a "To Design" issue and d
 |---|---|---|---|
 | `projectGroupId` | string | Yes | Project group ID |
 | `title` | string | Yes | Design task title |
-| `description` | string | No | Design problem description |
-| `level` | `"junior"` \| `"senior"` | No | Architect level. Default: `"junior"`. |
+| `description` | string | Yes | Detailed background context for the architect |
+| `focusAreas` | string[] | No | Specific areas to investigate |
+| `complexity` | `"simple"` \| `"medium"` \| `"complex"` | No | Guides level selection. Default: `"medium"`. |

 ---

@@ -360,8 +361,8 @@ tester:pass       → Testing   → Done         (close issue)
 tester:fail       → Testing   → To Improve   (reopen issue)
 tester:refine     → Testing   → Refining     (awaits human decision)
 tester:blocked    → Testing   → Refining     (awaits human decision)
-architect:done    → Designing → Planning     (design complete)
-architect:blocked → Designing → Refining     (awaits human decision)
+architect:done    → stays in Planning          (design complete, ready for human review)
+architect:blocked → Planning → Refining       (awaits human decision)
 ```

 ## Issue Priority Order