From 8c9c659ef2352705eeff9660b315f50ee1bf143f Mon Sep 17 00:00:00 2001 From: Claudomator Agent Date: Sat, 11 Jul 2026 09:52:47 +0000 Subject: docs: fix workflow diagram — create_story does not auto-spawn a builder task MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The StoryOrchestrator skips stories with no root_task_id (if st.RootTaskID == "") so create_story / POST /api/stories do not trigger Builder spawning on the next tick as the diagram incorrectly claimed. Corrected the flowchart node, the entry-point table rows, and added an explanatory note on the story lifecycle kickoff flow. Co-Authored-By: Claude Sonnet 4.6 --- docs/workflow-and-entry-points.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/workflow-and-entry-points.md b/docs/workflow-and-entry-points.md index 367c5ba..afc7a70 100644 --- a/docs/workflow-and-entry-points.md +++ b/docs/workflow-and-entry-points.md @@ -26,7 +26,7 @@ flowchart TD subgraph CHATBOT["Chatbot MCP (/chatbot/mcp)"] CB_SUBMIT["submit_task tool\n(creates + submits in one step)"] - CB_STORY["create_story tool\n(creates Story row in storage only;\nStoryOrchestrator spawns Builder on next tick)"] + CB_STORY["create_story tool\n(creates Story row with DISCOVERY status;\nno root_task_id set;\norchestrator skips until root_task_id\nis set via PUT /api/stories/{id})"] CB_ACCEPT["accept_story tool\n(REVIEW_READY → DONE;\norchestrator triggers retro next tick)"] end @@ -116,9 +116,9 @@ flowchart TD | `claudomator run ` | `internal/cli/run.go` | Task(s) from YAML | `cli` directly: `CreateTask` → `UpdateTaskState(QUEUED)` → `Pool.Submit` | | `POST /api/tasks` + `POST /api/tasks/{id}/run` | `internal/api/server.go`, `taskops.go` | PENDING task, then QUEUED | `handleRunTask` via `Pool.Submit` | | Chatbot MCP `submit_task` | `internal/api/chatbotmcp.go` | Task (PENDING→QUEUED in one step) | `submitTask()` via `Pool.Submit` | -| Chatbot MCP `create_story` | `internal/api/chatbotmcp.go` | Story row in storage | `StoryOrchestrator` (next tick): creates + submits Builder task | -| Chatbot MCP `accept_story` | `internal/api/chatbotmcp.go` | Story status DONE in storage | `StoryOrchestrator` (next tick): spawns retro task | -| `POST /api/stories` | `internal/api/stories.go` | Story row in storage | `StoryOrchestrator` (next tick) | +| Chatbot MCP `create_story` | `internal/api/chatbotmcp.go` | Story row in storage (`DISCOVERY` status, no `root_task_id`) | **Not auto-submitted** — a builder-role root task must be created separately and linked via `PUT /api/stories/{id}`; orchestrator skips stories with no `root_task_id` | +| Chatbot MCP `accept_story` | `internal/api/chatbotmcp.go` | Story status `DONE` in storage | `StoryOrchestrator` (next tick): spawns retro task | +| `POST /api/stories` | `internal/api/stories.go` | Story row in storage (`DISCOVERY` status, no `root_task_id`) | **Not auto-submitted** — same as `create_story`; `root_task_id` must be set via `PUT /api/stories/{id}` | | `POST /api/stories/{id}/accept` | `internal/api/stories.go` | Story status DONE in storage | `StoryOrchestrator` (next tick): spawns retro task | | `POST /api/webhooks/github` | `internal/api/webhook.go` | Task in **PENDING** state only | Human/chatbot/script must call `POST /api/tasks/{id}/run` | | Agent `spawn_subtask` (no `role=`) | `internal/executor/agentmcp.go`, `internal/agentloop/tools.go` | Child task with `parent_task_id`, `agent.type=claude` | **Not auto-submitted**; parent goes BLOCKED; child is dispatched later | @@ -290,3 +290,12 @@ flowchart LR resume). The `StoryOrchestrator` handles story-specific pipeline orchestration (Builder → Evaluators → Arbitration). They run in the same process but poll independently and write to separate concerns. + +- **Story lifecycle kickoff**: `create_story` (chatbot MCP) and `POST /api/stories` both create a story in + `DISCOVERY` status with no `root_task_id`. The `StoryOrchestrator` skips stories that have no + `root_task_id` (code: `if st.RootTaskID == "" { continue }`). To kick off execution, a human or + chatbot must (1) create a builder-role task (e.g. via `submit_task` with `agent.role="builder"`), + then (2) link it as the story's root via `PUT /api/stories/{id}` with `root_task_id` set. Once + linked, the orchestrator will drive the builder node through Evaluators → Arbitration on each + poll tick. The orchestrator never spawns the initial builder task itself — only the + Evaluator, Arbitration, fix-attempt, and retro tasks are ever auto-spawned by `spawnRoleTask`. -- cgit v1.2.3