From e7e61987d4da884d1ad629006d70329b79b899f7 Mon Sep 17 00:00:00 2001 From: Lauren ten Hoor Date: Sun, 8 Feb 2026 16:30:22 +0800 Subject: [PATCH] Replace PM terminology with orchestrator/session model across docs - Add "Agents vs Sessions" explainer section to ARCHITECTURE.md - Replace all "PM Agent" references with "Orchestrator" in sequence diagrams - Fix ticket creation: agents create issues via glab, not humans - Update scope boundaries to show sub-agent session responsibilities - Clarify plugin returns instructions, agent executes session operations - Update ONBOARDING.md issue creation to show agent-first workflow Co-Authored-By: Claude Opus 4.6 --- README.md | 54 ++++++++++++++++---------------- docs/ARCHITECTURE.md | 73 +++++++++++++++++++++++++++++--------------- docs/ONBOARDING.md | 20 ++++++------ 3 files changed, 87 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 4260845..c62a26c 100644 --- a/README.md +++ b/README.md @@ -2,21 +2,21 @@ **Every group chat becomes an autonomous development team.** -Add the agent to a Telegram group, point it at a GitLab repo — that group now has a **PM** managing the backlog, a **DEV** writing code, and a **QA** reviewing it. All autonomous. Add another group, get another team. Each project runs in complete isolation with its own task queue, workers, and session state. +Add the agent to a Telegram group, point it at a GitLab repo — that group now has an **orchestrator** managing the backlog, a **DEV** sub-agent session writing code, and a **QA** sub-agent session reviewing it. All autonomous. Add another group, get another team. Each project runs in complete isolation with its own task queue, workers, and session state. DevClaw is the [OpenClaw](https://openclaw.ai) plugin that makes this work. ## Why -[OpenClaw](https://openclaw.ai) is great at giving AI agents the ability to develop software — spawn sub-agents, manage sessions, work with code. But running a real multi-project development pipeline exposes a gap: the orchestration layer between "agent can write code" and "agent reliably manages multiple projects" is brittle. Every task involves 10+ coordinated steps across GitLab labels, session state, model selection, and audit logging. Agents forget steps, corrupt state, null out session IDs they should preserve, or pick the wrong model for the job. +[OpenClaw](https://openclaw.ai) is great at giving AI agents the ability to develop software — spawn sub-agent sessions, manage sessions, work with code. But running a real multi-project development pipeline exposes a gap: the orchestration layer between "agent can write code" and "agent reliably manages multiple projects" is brittle. Every task involves 10+ coordinated steps across GitLab labels, session state, model selection, and audit logging. Agents forget steps, corrupt state, null out session IDs they should preserve, or pick the wrong model for the job. DevClaw fills that gap with guardrails. It gives the orchestrator atomic tools that make it impossible to forget a label transition, lose a session reference, or skip an audit log entry. The complexity of multi-project orchestration moves from agent instructions (that LLMs follow imperfectly) into deterministic code (that runs the same way every time). ## The idea -One head agent acts as the **PM** across all your projects. It reads task backlogs, decides priorities, and delegates work. For each task, it spawns (or reuses) a **DEV** sub-agent to write code or a **QA** sub-agent to review it. Every Telegram group is a separate project — the PM keeps them completely isolated while managing them all from a single process. +One orchestrator agent manages all your projects. It reads task backlogs, creates issues, decides priorities, and delegates work. For each task, it spawns (or reuses) a **DEV** sub-agent session to write code or a **QA** sub-agent session to review it. Every Telegram group is a separate project — the orchestrator keeps them completely isolated while managing them all from a single process. -DevClaw gives the PM four tools that replace hundreds of lines of manual orchestration logic. Instead of following a 10-step checklist per task (fetch issue, check labels, pick model, check for existing session, transition label, update state, log audit event...), it calls `task_pickup` and the plugin handles everything atomically. +DevClaw gives the orchestrator four tools that replace hundreds of lines of manual orchestration logic. Instead of following a 10-step checklist per task (fetch issue, check labels, pick model, check for existing session, transition label, update state, log audit event...), it calls `task_pickup` and the plugin handles everything atomically. ## How it works @@ -24,48 +24,48 @@ DevClaw gives the PM four tools that replace hundreds of lines of manual orchest graph TB subgraph "Group Chat A" direction TB - A_PM["🎯 PM (head agent)"] + A_O["🎯 Orchestrator"] A_GL[GitLab Issues] - A_DEV["🔧 DEV (sub-agent)"] - A_QA["🔍 QA (sub-agent)"] - A_PM -->|task_pickup| A_GL - A_PM -->|spawns / sends| A_DEV - A_PM -->|spawns / sends| A_QA + A_DEV["🔧 DEV (sub-agent session)"] + A_QA["🔍 QA (sub-agent session)"] + A_O -->|task_pickup| A_GL + A_O -->|spawns / sends| A_DEV + A_O -->|spawns / sends| A_QA end subgraph "Group Chat B" direction TB - B_PM["🎯 PM (head agent)"] + B_O["🎯 Orchestrator"] B_GL[GitLab Issues] - B_DEV["🔧 DEV (sub-agent)"] - B_QA["🔍 QA (sub-agent)"] - B_PM -->|task_pickup| B_GL - B_PM -->|spawns / sends| B_DEV - B_PM -->|spawns / sends| B_QA + B_DEV["🔧 DEV (sub-agent session)"] + B_QA["🔍 QA (sub-agent session)"] + B_O -->|task_pickup| B_GL + B_O -->|spawns / sends| B_DEV + B_O -->|spawns / sends| B_QA end subgraph "Group Chat C" direction TB - C_PM["🎯 PM (head agent)"] + C_O["🎯 Orchestrator"] C_GL[GitLab Issues] - C_DEV["🔧 DEV (sub-agent)"] - C_QA["🔍 QA (sub-agent)"] - C_PM -->|task_pickup| C_GL - C_PM -->|spawns / sends| C_DEV - C_PM -->|spawns / sends| C_QA + C_DEV["🔧 DEV (sub-agent session)"] + C_QA["🔍 QA (sub-agent session)"] + C_O -->|task_pickup| C_GL + C_O -->|spawns / sends| C_DEV + C_O -->|spawns / sends| C_QA end AGENT["Single OpenClaw Agent"] - AGENT --- A_PM - AGENT --- B_PM - AGENT --- C_PM + AGENT --- A_O + AGENT --- B_O + AGENT --- C_O ``` -It's the same agent process — but each group chat gives it a different project context. The PM role, the workers, the task queue, and all state are fully isolated per group. +It's the same agent process — but each group chat gives it a different project context. The orchestrator role, the workers, the task queue, and all state are fully isolated per group. ## Task lifecycle -Every task (GitLab issue) moves through a fixed pipeline of label states. DevClaw tools handle every transition atomically — label change, state update, audit log, and session management in a single call. +Every task (GitLab issue) moves through a fixed pipeline of label states. Issues are created by the orchestrator agent or by sub-agent sessions — not manually. DevClaw tools handle every transition atomically — label change, state update, audit log, and session management in a single call. ```mermaid stateDiagram-v2 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index d8d0577..dc0266a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,17 +1,35 @@ # DevClaw — Architecture & Component Interaction +## Agents vs Sessions + +Understanding the OpenClaw model is key to understanding how DevClaw works: + +- **Agent** — A configured entity in `openclaw.json`. Has a workspace, model, identity files (SOUL.md, IDENTITY.md), and tool permissions. Persists across restarts. +- **Session** — A runtime conversation instance. Created when the agent starts or when `sessions_spawn` is called. Each session has its own context window and conversation history. +- **Sub-agent session** — A session spawned by the orchestrator agent via `sessions_spawn`. Despite the name, it is NOT a separate agent — it's a child session running under the same agent, with its own isolated context. Format: `agent::subagent:`. + +DevClaw operates at the **orchestrator agent** level. The orchestrator runs a single long-lived session that manages all projects. For each task, it spawns (or reuses) DEV and QA sub-agent sessions. The plugin handles the orchestration logic — label transitions, state management, model selection, audit logging — and returns structured instructions. The orchestrator agent then executes the actual session operations (`sessions_spawn` or `sessions_send`). + +``` +Orchestrator Agent (configured in openclaw.json) + └─ Main session (long-lived, handles all projects) + ├─ DEV sub-agent session (project A) ← sessions_spawn / sessions_send + ├─ QA sub-agent session (project A) ← sessions_spawn / sessions_send + ├─ DEV sub-agent session (project B) + └─ QA sub-agent session (project B) +``` + ## System overview ```mermaid graph TB subgraph "External" - USER[Human / User] GL[GitLab] TG[Telegram] end subgraph "OpenClaw Runtime" - AGENT[Orchestrator Agent / PM] + AGENT[Orchestrator Agent] DEV[DEV sub-agent session] QA[QA sub-agent session] end @@ -30,9 +48,10 @@ graph TB REPO[Project Repository] end - USER -->|creates issues| GL - USER -->|sends messages| TG TG -->|delivers messages| AGENT + AGENT -->|announces to group| TG + + AGENT -->|creates/updates issues| GL AGENT -->|calls| TP AGENT -->|calls| TC @@ -64,9 +83,8 @@ graph TB AGENT -->|sessions_send| QA DEV -->|writes code, creates MRs| REPO + DEV -->|creates/updates issues| GL QA -->|reviews code, tests| REPO - - AGENT -->|announces to group| TG ``` ## Complete ticket lifecycle @@ -75,8 +93,10 @@ This traces a single issue from creation to completion, showing every component ### Phase 1: Issue created +Issues are created by the orchestrator agent or by sub-agent sessions via `glab`. The orchestrator can create issues based on user requests in Telegram, backlog planning, or QA feedback. Sub-agents can also create issues when they discover bugs or related work during development. + ``` -Human → GitLab: creates issue #42 with label "To Do" +Orchestrator Agent → GitLab: creates issue #42 with label "To Do" ``` **State:** GitLab has issue #42 labeled "To Do". Nothing in DevClaw yet. @@ -84,12 +104,12 @@ Human → GitLab: creates issue #42 with label "To Do" ### Phase 2: Heartbeat detects work ``` -Heartbeat triggers → Agent calls queue_status() +Heartbeat triggers → Orchestrator calls queue_status() ``` ```mermaid sequenceDiagram - participant A as PM Agent + participant A as Orchestrator participant QS as queue_status participant GL as GitLab participant PJ as projects.json @@ -108,13 +128,13 @@ sequenceDiagram QS-->>A: { dev: idle, queue: { toDo: [#42] } } ``` -**Agent decides:** DEV is idle, issue #42 is in To Do → pick it up. +**Orchestrator decides:** DEV is idle, issue #42 is in To Do → pick it up. ### Phase 3: DEV pickup ```mermaid sequenceDiagram - participant A as PM Agent + participant A as Orchestrator participant TP as task_pickup participant GL as GitLab participant MS as Model Selector @@ -135,7 +155,7 @@ sequenceDiagram TP->>PJ: activateWorker(-123, dev, { issueId: "42", model: "sonnet" }) TP->>AL: append { event: "task_pickup", ... } TP->>AL: append { event: "model_selection", ... } - TP-->>A: { sessionAction: "send", sessionId: "existing-session", announcement: "🔧 Sending DEV (sonnet) for #42: Add login page" } + TP-->>A: { sessionAction: "send", sessionId: "existing-session", announcement: "..." } A->>TG: "🔧 Sending DEV (sonnet) for #42: Add login page" A->>A: sessions_send(sessionId, task description) ``` @@ -149,17 +169,17 @@ sequenceDiagram ### Phase 4: DEV works ``` -DEV sub-agent → reads codebase, writes code, creates MR -DEV sub-agent → reports back to PM: "done, MR merged" +DEV sub-agent session → reads codebase, writes code, creates MR +DEV sub-agent session → reports back to orchestrator: "done, MR merged" ``` -This happens inside the OpenClaw session. DevClaw is not involved — the DEV sub-agent works autonomously with the codebase. +This happens inside the OpenClaw session. DevClaw is not involved — the DEV sub-agent session works autonomously with the codebase. ### Phase 5: DEV complete ```mermaid sequenceDiagram - participant A as PM Agent + participant A as Orchestrator participant TC as task_complete participant GL as GitLab participant PJ as projects.json @@ -196,7 +216,7 @@ Same as Phase 3, but with `role: "qa"`. Label transitions "To Test" → "Testing ```mermaid sequenceDiagram - participant A as PM Agent + participant A as Orchestrator participant TC as task_complete participant GL as GitLab participant PJ as projects.json @@ -218,7 +238,7 @@ sequenceDiagram ```mermaid sequenceDiagram - participant A as PM Agent + participant A as Orchestrator participant TC as task_complete participant GL as GitLab participant MS as Model Selector @@ -254,7 +274,7 @@ The heartbeat runs periodically (triggered by the agent or a scheduled message). ```mermaid sequenceDiagram - participant A as PM Agent + participant A as Orchestrator participant SH as session_health participant QS as queue_status participant TP as task_pickup @@ -290,6 +310,7 @@ Every piece of data and where it lives: │ Labels: [To Do | Doing | To Test | Testing | Done | ...] │ │ State: open / closed │ │ MRs: linked merge requests │ +│ Created by: orchestrator agent, DEV/QA sub-agents, or humans │ └─────────────────────────────────────────────────────────────────┘ ↕ glab CLI (read/write) ┌─────────────────────────────────────────────────────────────────┐ @@ -335,8 +356,8 @@ Every piece of data and where it lives: ┌─────────────────────────────────────────────────────────────────┐ │ Git Repository (codebase) │ │ │ -│ DEV sub-agent: reads code, writes code, creates MRs │ -│ QA sub-agent: reads code, runs tests, reviews MRs │ +│ DEV sub-agent session: reads code, writes code, creates MRs │ +│ QA sub-agent session: reads code, runs tests, reviews MRs │ │ task_complete (DEV done): git pull to sync latest │ └─────────────────────────────────────────────────────────────────┘ ``` @@ -355,16 +376,20 @@ graph LR Z[Zombie cleanup] end - subgraph "Agent handles (with DevClaw instructions)" + subgraph "Orchestrator handles (with DevClaw instructions)" SP[Session spawn/send] MSG[Telegram announcements] HB[Heartbeat scheduling] + IC[Issue creation via glab] end - subgraph "External (not DevClaw)" - IC[Issue creation] + subgraph "Sub-agent sessions handle" CR[Code writing] MR[MR creation/review] + BUG[Bug issue creation] + end + + subgraph "External" DEPLOY[Deployment] HR[Human decisions] end diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index 8cd336d..2071885 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -9,7 +9,7 @@ | [`glab`](https://gitlab.com/gitlab-org/cli) CLI | GitLab issue/label management | `glab --version` | | glab authenticated | Plugin calls glab for every label transition | `glab auth status` | | A GitLab repo with issues | The task backlog lives in GitLab | `glab issue list` from your repo | -| An OpenClaw agent with Telegram | The PM agent that will orchestrate | Agent defined in `openclaw.json` | +| An OpenClaw agent with Telegram | The orchestrator agent that will manage projects | Agent defined in `openclaw.json` | ## Setup steps @@ -35,7 +35,7 @@ In `openclaw.json`, your orchestrator agent needs access to the DevClaw tools: "agents": { "list": [{ "id": "my-orchestrator", - "name": "Dev PM", + "name": "Dev Orchestrator", "model": "anthropic/claude-sonnet-4-5", "tools": { "allow": [ @@ -53,7 +53,7 @@ In `openclaw.json`, your orchestrator agent needs access to the DevClaw tools: } ``` -The agent also needs the OpenClaw session tools (`sessions_spawn`, `sessions_send`, `sessions_list`) — DevClaw handles the orchestration logic, but the agent executes the actual session operations. +The agent also needs the OpenClaw session tools (`sessions_spawn`, `sessions_send`, `sessions_list`) — DevClaw handles the orchestration logic (labels, state, model selection, audit), but the agent executes the actual session operations to spawn or communicate with DEV/QA sub-agent sessions. ### 3. Create GitLab labels @@ -112,10 +112,12 @@ Add your orchestrator bot to the Telegram group for the project. The agent will ### 6. Create your first issue -```bash -cd ~/git/my-project -glab issue create --title "My first task" --label "To Do" -``` +Issues can be created in multiple ways: +- **Via the agent** — Ask the orchestrator in the Telegram group: "Create an issue for adding a login page" +- **Via glab CLI** — `cd ~/git/my-project && glab issue create --title "My first task" --label "To Do"` +- **Via GitLab UI** — Create an issue and add the "To Do" label + +The orchestrator agent and sub-agent sessions can all create and update issues via `glab` tool usage. ### 7. Test the pipeline @@ -127,7 +129,7 @@ The agent should call `queue_status` and report the "To Do" issue. Then: > "Pick up issue #1 for DEV" -The agent calls `task_pickup`, which selects a model, transitions the label to "Doing", and returns instructions to spawn or reuse a DEV session. +The agent calls `task_pickup`, which selects a model, transitions the label to "Doing", and returns instructions to spawn or reuse a DEV sub-agent session. ## Adding more projects @@ -146,7 +148,7 @@ Each project is fully isolated — separate queue, separate workers, separate st | Project registration | You (once per project) | Entry in `projects.json` | | Agent definition | You (once) | Agent in `openclaw.json` with tool permissions | | Telegram group setup | You (once per project) | Add bot to group | -| Task creation | You or external | Create GitLab issues with labels | +| Issue creation | Agent or sub-agents | Created via `glab` tool usage (or manually via GitLab UI) | | Label transitions | Plugin | Atomic `--unlabel` + `--label` via glab | | Model selection | Plugin | Keyword-based heuristic per task | | State management | Plugin | Atomic read/write to `projects.json` |