@laurentenhoor/devclaw 0.1.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,336 @@
+# DevClaw — Configuration Reference
+
+All DevClaw configuration lives in two places: `openclaw.json` (plugin-level settings) and `projects.json` (per-project state).
+
+## Plugin Configuration (`openclaw.json`)
+
+DevClaw is configured under `plugins.entries.devclaw.config` in `openclaw.json`.
+
+### Model Tiers
+
+Override which LLM model powers each developer level:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "devclaw": {
+        "config": {
+          "models": {
+            "dev": {
+              "junior": "anthropic/claude-haiku-4-5",
+              "medior": "anthropic/claude-sonnet-4-5",
+              "senior": "anthropic/claude-opus-4-5"
+            },
+            "qa": {
+              "reviewer": "anthropic/claude-sonnet-4-5",
+              "tester": "anthropic/claude-haiku-4-5"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Resolution order** (per `lib/tiers.ts:resolveModel`):
+
+1. Plugin config `models.<role>.<level>` — explicit override
+2. `DEFAULT_MODELS[role][level]` — built-in defaults (table below)
+3. Passthrough — treat the level string as a raw model ID
+
+**Default models:**
+
+| Role | Level | Default model |
+|---|---|---|
+| dev | junior | `anthropic/claude-haiku-4-5` |
+| dev | medior | `anthropic/claude-sonnet-4-5` |
+| dev | senior | `anthropic/claude-opus-4-5` |
+| qa | reviewer | `anthropic/claude-sonnet-4-5` |
+| qa | tester | `anthropic/claude-haiku-4-5` |
+
+### Project Execution Mode
+
+Controls cross-project parallelism:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "devclaw": {
+        "config": {
+          "projectExecution": "parallel"
+        }
+      }
+    }
+  }
+}
+```
+
+| Value | Behavior |
+|---|---|
+| `"parallel"` (default) | Multiple projects can have active workers simultaneously |
+| `"sequential"` | Only one project's workers active at a time. Useful for single-agent deployments. |
+
+Enforced in `work_heartbeat` and the heartbeat service before dispatching.
+
+### Heartbeat Service
+
+Token-free interval-based health checks + queue dispatch:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "devclaw": {
+        "config": {
+          "work_heartbeat": {
+            "enabled": true,
+            "intervalSeconds": 60,
+            "maxPickupsPerTick": 4
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Enable the heartbeat service |
+| `intervalSeconds` | number | `60` | Seconds between ticks |
+| `maxPickupsPerTick` | number | `4` | Maximum worker dispatches per tick (budget control) |
+
+**Source:** [`lib/services/heartbeat.ts`](../lib/services/heartbeat.ts)
+
+The heartbeat service runs as a plugin service tied to the gateway lifecycle. Every tick: health pass (auto-fix zombies, stale workers) → tick pass (fill free slots by priority). Zero LLM tokens consumed.
+
+### Notifications
+
+Control which lifecycle events send notifications:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "devclaw": {
+        "config": {
+          "notifications": {
+            "heartbeatDm": true,
+            "workerStart": true,
+            "workerComplete": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+| Setting | Default | Description |
+|---|---|---|
+| `heartbeatDm` | `true` | Send heartbeat summary to orchestrator DM |
+| `workerStart` | `true` | Announce when a worker picks up a task |
+| `workerComplete` | `true` | Announce when a worker finishes a task |
+
+### Agent Tool Permissions
+
+Restrict DevClaw tools to your orchestrator agent:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "my-orchestrator",
+        "tools": {
+          "allow": [
+            "work_start",
+            "work_finish",
+            "task_create",
+            "task_update",
+            "task_comment",
+            "status",
+            "health",
+            "work_heartbeat",
+            "project_register",
+            "setup",
+            "onboard"
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Project State (`projects.json`)
+
+All project state lives in `<workspace>/projects/projects.json`, keyed by group ID.
+
+**Source:** [`lib/projects.ts`](../lib/projects.ts)
+
+### Schema
+
+```json
+{
+  "projects": {
+    "<groupId>": {
+      "name": "my-webapp",
+      "repo": "~/git/my-webapp",
+      "groupName": "Dev - My Webapp",
+      "baseBranch": "development",
+      "deployBranch": "development",
+      "deployUrl": "https://my-webapp.example.com",
+      "channel": "telegram",
+      "roleExecution": "parallel",
+      "dev": {
+        "active": false,
+        "issueId": null,
+        "startTime": null,
+        "level": null,
+        "sessions": {
+          "junior": null,
+          "medior": "agent:orchestrator:subagent:my-webapp-dev-medior",
+          "senior": null
+        }
+      },
+      "qa": {
+        "active": false,
+        "issueId": null,
+        "startTime": null,
+        "level": null,
+        "sessions": {
+          "reviewer": "agent:orchestrator:subagent:my-webapp-qa-reviewer",
+          "tester": null
+        }
+      }
+    }
+  }
+}
+```
+
+### Project fields
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Short project name |
+| `repo` | string | Path to git repo (supports `~/` expansion) |
+| `groupName` | string | Group display name |
+| `baseBranch` | string | Base branch for development |
+| `deployBranch` | string | Branch that triggers deployment |
+| `deployUrl` | string | Deployment URL |
+| `channel` | string | Messaging channel (`"telegram"`, `"whatsapp"`, etc.) |
+| `roleExecution` | `"parallel"` \| `"sequential"` | DEV/QA parallelism for this project |
+
+### Worker state fields
+
+Each project has `dev` and `qa` worker state objects:
+
+| Field | Type | Description |
+|---|---|---|
+| `active` | boolean | Whether this role has an active worker |
+| `issueId` | string \| null | Issue being worked on (as string) |
+| `startTime` | string \| null | ISO timestamp when worker became active |
+| `level` | string \| null | Current level (`junior`, `medior`, `senior`, `reviewer`, `tester`) |
+| `sessions` | Record<string, string \| null> | Per-level session keys |
+
+**DEV session keys:** `junior`, `medior`, `senior`
+**QA session keys:** `reviewer`, `tester`
+
+### Key design decisions
+
+- **Session-per-level** — each level gets its own worker session, accumulating context independently. Level selection maps directly to a session key.
+- **Sessions preserved on completion** — when a worker completes a task, the sessions map is preserved (only `active`, `issueId`, and `startTime` are cleared). This enables session reuse.
+- **Atomic writes** — all writes go through temp-file-then-rename to prevent corruption.
+- **Sessions persist indefinitely** — no auto-cleanup. The `health` tool handles manual cleanup.
+
+---
+
+## Workspace File Layout
+
+```
+<workspace>/
+├── projects/
+│   ├── projects.json          ← Project state (auto-managed)
+│   └── roles/
+│       ├── my-webapp/         ← Per-project role instructions (editable)
+│       │   ├── dev.md
+│       │   └── qa.md
+│       ├── another-project/
+│       │   ├── dev.md
+│       │   └── qa.md
+│       └── default/           ← Fallback role instructions
+│           ├── dev.md
+│           └── qa.md
+├── log/
+│   └── audit.log              ← NDJSON event log (auto-managed)
+├── AGENTS.md                  ← Agent identity documentation
+└── HEARTBEAT.md               ← Heartbeat operation guide
+```
+
+### Role instruction files
+
+`work_start` loads role instructions from `projects/roles/<project>/<role>.md` at dispatch time, falling back to `projects/roles/default/<role>.md`. These files are appended to the task message sent to worker sessions.
+
+Edit to customize: deployment steps, test commands, acceptance criteria, coding standards.
+
+**Source:** [`lib/dispatch.ts:loadRoleInstructions`](../lib/dispatch.ts)
+
+---
+
+## Audit Log
+
+Append-only NDJSON at `<workspace>/log/audit.log`. Auto-truncated to 250 lines.
+
+**Source:** [`lib/audit.ts`](../lib/audit.ts)
+
+### Event types
+
+| Event | Trigger |
+|---|---|
+| `work_start` | Task dispatched to worker |
+| `model_selection` | Level resolved to model ID |
+| `work_finish` | Task completed |
+| `work_heartbeat` | Heartbeat tick completed |
+| `task_create` | Issue created |
+| `task_update` | Issue state changed |
+| `task_comment` | Comment added to issue |
+| `status` | Queue status queried |
+| `health` | Health scan completed |
+| `heartbeat_tick` | Heartbeat service tick (background) |
+| `project_register` | Project registered |
+
+### Querying
+
+```bash
+# All task dispatches
+cat audit.log | jq 'select(.event=="work_start")'
+
+# All completions for a project
+cat audit.log | jq 'select(.event=="work_finish" and .project=="my-webapp")'
+
+# Model selections
+cat audit.log | jq 'select(.event=="model_selection")'
+```
+
+---
+
+## Issue Provider
+
+DevClaw uses an `IssueProvider` interface (`lib/providers/provider.ts`) to abstract issue tracker operations. The provider is auto-detected from the git remote URL.
+
+**Supported providers:**
+
+| Provider | CLI | Detection |
+|---|---|---|
+| GitHub | `gh` | Remote contains `github.com` |
+| GitLab | `glab` | Remote contains `gitlab` |
+
+**Planned:** Jira (via REST API)
+
+**Source:** [`lib/providers/index.ts`](../lib/providers/index.ts)

package/docs/MANAGEMENT.md

@@ -0,0 +1,120 @@
+# The Management Science Behind DevClaw
+
+## Why delegation theory matters for AI orchestration
+
+Every developer who's tried to use AI agents for real work hits the same wall. The agent _can_ write code — but reliably managing a backlog, tracking state, coordinating handoffs, and knowing when to escalate? That's a different problem entirely. It's not a coding problem. It's a management problem.
+
+DevClaw exists because of a gap that management theorists identified decades ago: the difference between someone being _able_ to do work and someone _reliably delivering_ work without constant supervision. The entire plugin is, at its core, an encoded delegation framework. This article traces the management principles behind the design and explores what they teach us about saving time for the person behind the keyboard.
+
+---
+
+## The delegation gap
+
+In 1969, Paul Hersey and Ken Blanchard published what would become Situational Leadership Theory. The central idea is deceptively simple: the way you delegate should match the capability and reliability of the person doing the work. You don't hand an intern the system architecture redesign. You don't ask your principal engineer to rename a CSS class.
+
+DevClaw's level selection does exactly this. When a task comes in, the plugin routes it to the cheapest model that can handle it:
+
+| Complexity                       | Level    | Analogy                     |
+| -------------------------------- | -------- | --------------------------- |
+| Simple (typos, renames, copy)    | Junior   | The intern — just execute   |
+| Standard (features, bug fixes)   | Medior   | Mid-level — think and build |
+| Complex (architecture, security) | Senior   | The architect — design and reason |
+| Review                           | Reviewer | Independent code reviewer   |
+
+This isn't just cost optimization. It mirrors what effective managers do instinctively: match the delegation level to the task, not to a fixed assumption about the delegate.
+
+## Management by exception
+
+Classical management theory — later formalized by Bernard Bass in his work on Transformational Leadership — introduced a concept called Management by Exception (MBE). The principle: a manager should only be pulled back into a workstream when something deviates from the expected path.
+
+DevClaw's task lifecycle is built on this. The orchestrator delegates a task via `work_start`, then steps away. It only re-engages in three scenarios:
+
+1. **DEV completes work** → The label moves to `To Test`. The scheduler dispatches QA on the next tick. No orchestrator involvement needed.
+2. **QA passes** → The issue closes. Pipeline complete.
+3. **QA fails** → The label moves to `To Improve`. The scheduler dispatches DEV on the next tick. The orchestrator may need to adjust the model level.
+4. **QA refines** → The task enters a holding state that _requires human decision_. This is the explicit escalation boundary.
+
+The "refine" state is the most interesting from a delegation perspective. It's a conscious architectural decision that says: some judgments should not be automated. When the QA agent determines that a task needs rethinking rather than just fixing, it escalates to the only actor who has the full business context — the human.
+
+This is textbook MBE. The person behind the keyboard isn't monitoring every task. They're only pulled in when the system encounters something beyond its delegation authority.
+
+## Span of control through standardization
+
+Henry Mintzberg's work on organizational structure identified five coordination mechanisms. The one most relevant to DevClaw is **standardization of work processes** — when coordination happens not through direct supervision but through predetermined procedures that everyone follows.
+
+DevClaw enforces a single, fixed lifecycle for every task across every project:
+
+```
+Planning → To Do → Doing → To Test → Testing → Done
+                                    ↘ To Improve → Doing (fix cycle)
+                                    ↘ Refining → (human decision)
+```
+
+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.
+
+This is what allows a single orchestrator to manage multiple projects simultaneously. Management research has long debated the ideal span of control — typically cited as 5-9 direct reports for knowledge work. DevClaw sidesteps the constraint entirely by making every project follow identical processes. The orchestrator doesn't need to remember how Project A works versus Project B. They all work the same way.
+
+## Trust but verify: structural independence
+
+One of the most common delegation failures is self-review. You don't ask the person who wrote the code to also approve it — not because they're dishonest, but because they're cognitively biased toward their own work.
+
+DevClaw enforces structural separation between development and review by design:
+
+- DEV and QA are separate sub-agent sessions with separate state.
+- QA uses the reviewer level, which can be a different model entirely, introducing genuine independence.
+- The review happens after a clean label transition — QA picks up from `To Test`, not from watching DEV work in real time.
+
+This mirrors a principle from organizational design: effective controls require independence between execution and verification. It's the same reason companies separate their audit function from their operations.
+
+## The economics of context: session reuse
+
+Ronald Coase won a Nobel Prize for explaining why firms exist: transaction costs. Every time you go to the market to hire someone for a task, you pay search costs, negotiation costs, and onboarding costs. Firms exist because keeping people on staff reduces these repeated costs.
+
+DevClaw applies the same logic to AI sessions. Spawning a new sub-agent session costs approximately 50,000 tokens of context loading — the agent needs to read the full codebase before it can do useful work. That's the onboarding cost.
+
+The plugin tracks session keys across task completions. When a DEV finishes task A and task B is ready on the same project, DevClaw detects the existing session and reuses it instead of spawning a new one. No re-onboarding. No context reload.
+
+In management terms: keep your team stable. Reassigning the same person to the next task on their project is almost always cheaper than bringing in someone new — even if the new person is theoretically better qualified.
+
+## The real time savings
+
+Here's what delegation theory reveals about where DevClaw actually saves time. It's not where most people think.
+
+The obvious saving is execution time: AI writes code faster than a human. But that's the smaller gain. The larger saving comes from a concept psychologists call **decision fatigue** — the cumulative cognitive cost of making choices throughout a day.
+
+Without DevClaw, every task requires a human to make a series of small decisions:
+
+- Which model should handle this?
+- Is the DEV session still alive, or do I need a new one?
+- What label should this issue have now?
+- Did I update the state file?
+- Did I log this transition?
+- Is the QA session free, or is it still working on something?
+
+None of these decisions are hard. But they accumulate. Each one consumes a small amount of the same cognitive resource you need for the decisions that actually matter — product direction, architecture choices, business priorities.
+
+DevClaw eliminates entire categories of decisions by making them deterministic. The plugin picks the model. The plugin manages sessions. The plugin transitions labels. The plugin writes audit logs. The person behind the keyboard is left with only the decisions that require human judgment: what to build, what to prioritize, and what to do when QA says "this needs rethinking."
+
+This is the deepest lesson from delegation theory: **good delegation isn't about getting someone else to do your work. It's about protecting your attention for the work only you can do.**
+
+## What the theory suggests next
+
+Management research points to a few directions that could extend DevClaw's delegation model:
+
+**Progressive delegation.** Blanchard's model suggests increasing task complexity for delegates as they prove competent. DevClaw could track QA pass rates per model level and automatically promote — if junior consistently passes QA on borderline tasks, start routing more work to it. This is how good managers develop their people, and it reduces cost over time.
+
+**Delegation authority expansion.** The Vroom-Yetton decision model maps when a leader should decide alone versus consulting the team. Currently, sub-agents have narrow authority — they execute tasks but can't restructure the backlog. Selectively expanding this (e.g., allowing a DEV agent to split a task it judges too large) would reduce orchestrator bottlenecks, mirroring how managers gradually give high-performers more autonomy.
+
+**Outcome-based learning.** Delegation research emphasizes that the _delegator_ learns from outcomes too. Aggregated metrics — QA fail rate by model level, average cycles to Done, time-in-state distributions — would help both the orchestrator agent and the human calibrate their delegation patterns over time.
+
+---
+
+## Further reading
+
+- Hersey, P. & Blanchard, K. (1969). _Management of Organizational Behavior_
+- Bass, B. M. (1985). _Leadership and Performance Beyond Expectations_
+- Mintzberg, H. (1979). _The Structuring of Organizations_
+- Coase, R. H. (1937). _The Nature of the Firm_
+- Appelo, J. (2011). _Management 3.0: Leading Agile Developers, Developing Agile Leaders_
+- Yukl, G. (2013). _Leadership in Organizations_
+- Vroom, V. H. & Yetton, P. W. (1973). _Leadership and Decision-Making_