Phase 0: dev-task wrapper + LXC bootstrap recipe + arch README

README.md

@@ -1,3 +1,58 @@
-# orchestrator
+# agent-coding-empire orchestrator
 
-Glue between Gitea and the dev/auditor LXCs. PM tools, webhook handler, dev-task wrapper, auditor workflow.
+Glue between Gitea and the dev/auditor LXCs that run `claude-code` headless.
+
+## Architecture (v0)
+
+```
+                              ┌──────────────────────────────┐
+                              │ Gitea (CT 101)               │
+                              │  - Issues with labels        │
+                              │  - PRs                       │
+                              │  - Actions runner (CT 112)   │
+                              └────────┬─────────────────────┘
+                                       │ webhook
+                                       ▼
+              ┌──────────────────────────────────────┐
+              │ orchestrator (CT 103, this repo)     │
+              │  - webhook handler (Phase 2)         │
+              │  - PM helper scripts                 │
+              │  - SSH-triggers dev-task on dev LXCs │
+              └────────┬─────────────────────────────┘
+                       │ SSH
+                       ▼
+              ┌──────────────────┐
+              │ dev-01 (CT 120)  │  one slot active at a time
+              │  - claude-code   │
+              │  - tea CLI       │
+              │  - dev-task.sh   │
+              └──────────────────┘
+```
+
+## Constraints
+
+- **Max-plan auth shared.** Each dev LXC has a copy of `~/.claude/.credentials.json`.
+  They all draw from the same rate-limit pool as Danny's interactive sessions.
+- **One dev agent active at a time** in v0 (no parallel) to avoid starving the pool.
+- **Default model = sonnet.** Opus only when issue body explicitly says `Model: opus`.
+- **Hard wallclock cap** = 30 minutes per task (configurable via `MAX_WALLCLOCK`).
+
+## Repo layout
+
+```
+agents/
+  dev-task.sh          # runs inside dev LXC; takes <repo> <issue-id>, opens PR
+pm/
+  (todo)               # PM scripts that create structured issues
+auditor/
+  (todo)               # Gitea Actions workflow for PR review
+provisioning/
+  (todo)               # scripts to bootstrap a fresh dev LXC
+```
+
+## Phase status
+
+- [x] Phase 0: Gitea repos, dev-01 LXC, claude-code + tea installed, auth verified
+- [ ] Phase 1: manual closed loop (PM writes issue → dev-task → PR)
+- [ ] Phase 2: webhook-driven automation
+- [ ] Phase 3: multi-dev (still one active at a time)