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 <noreply@anthropic.com>
2026-02-08 16:30:22 +08:00
parent 9195c4be7f
commit e7e61987d4
3 changed files with 87 additions and 60 deletions
--- 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:<parent>:subagent:<uuid>`.
+
+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
--- 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` |