Agent Swarm Orchestrator

Multi-project coding automation: Obsidian task intake → Claude Code → Codex review → GitLab MR → merge + sync.

Architecture

CODEBLOCK0

Core Paths

Path	Purpose
INLINECODE0	Control plane (scripts, registry, tasks)
INLINECODE1

Project configs (repo, paths, branch) | | ~/agent-swarm/tasks.json | Task state machine | | ~/GitLab/repos/ | Local repos | | ~/GitLab/worktrees/ | Per-task worktrees | | ~/Documents/Obsidian Vault/agent-swarm/ | Task intake notes |

Scripts

Script	Purpose
INLINECODE6	Create worktree + prompt + tmux → run-agent
INLINECODE7

claude -p → check commits → trigger review | | review-and-push.sh | Codex review → graded fix → push → MR | | check-agents.sh | Cron + post-merge: detect done/stuck, mark done, send notification | | scan-obsidian.sh | Parse Obsidian notes, spawn status: ready tasks | | send-notifications.sh | Send .notification files via OpenClaw CLI | | merge-and-sync.sh | Merge MR + sync local main | | sync-project-main.sh | Fast-forward local repo to origin/main | | new-project.sh | Initialize project (GitLab + registry + context + Obsidian) | | cleanup.sh | Daily archive old tasks, clean worktrees/logs |

Usage

Spawn task

CODEBLOCK1

Monitor

CODEBLOCK2

Merge and sync

CODEBLOCK3

New project

CODEBLOCK4

Task Lifecycle

CODEBLOCK5

Prerequisites

Claude Code CLI

• - Authenticated via OAuth (~/.claude.json oauthAccount)
• INLINECODE20: INLINECODE21
• INLINECODE22 projects: trust ~/GitLab/worktrees and ~/GitLab/repos (hasTrustDialogAccepted: true)
• No ANTHROPIC_* env vars leaking into tmux (causes proxy conflicts)

Tools

• - claude CLI (Claude Code)
• INLINECODE28 CLI (OpenAI Codex, for review)
• INLINECODE29 CLI (GitLab)
• INLINECODE30, python3, INLINECODE32

Cron

CODEBLOCK6

Notifications

Configure in ~/agent-swarm/registry.json:
CODEBLOCK7

INLINECODE34 in config.sh reads these values and calls:
CODEBLOCK8

⚠️ Do NOT use >/dev/null 2>&1 in swarm_notify — errors must be visible so failed sends are not silently marked as sent.

Prompt Template

Each task gets a prompt file with:

1. 1. Project name, task description, priority
2. Working directory and branch
3. Project context (from context.md)
4. Standard instructions (commit, push, MR, update context.md if architectural changes)

Obsidian Integration

• - Frontmatter status: active | stop controls project scanning
• Task block: ### Task Name + status: ready + INLINECODE42
• INLINECODE43 + status: ready triggers INLINECODE45
• Dedup: sha1(project+name+desc)[:12], flagged in logs
• Debounce: skip files modified within last 1 minute

Review Policy

• - Coding: Claude Code (-p mode, auto-exit)
• Review: Codex (codex exec review)
• CRITICAL/HIGH: auto-fix retry (max 2), then INLINECODE48
• MEDIUM: auto-fix (non-blocking), skip for docs-only
• LOW: notes in MR description only
• Docs-only: downgrade CRITICAL/HIGH to MEDIUM

Portable Install

CODEBLOCK9

Then: register projects in registry.json, set cron, configure notifications.

Intent → Action Mapping

When a user message matches one of these intents, take the corresponding action immediately without asking for confirmation:

User says	Context	Action
"合并" / "merge" / "merge it"	Replied to a PR_READY notification	Extract <project> and <mr-iid> from the notification, run INLINECODE52
"起任务" / "spawn" / "新任务"

With a task description | Run spawn-agent.sh <project> "<desc>" |
| "查状态" / "check status" | Any | Run check-agents.sh and summarize output |
| "新项目" / "new project" | With a project name | Run new-project.sh <project-name> |

Extracting MR info from PR_READY notifications

PR_READY notifications follow this format:
CODEBLOCK10

Extract Project → <project>, and the number at the end of the MR URL → <mr-iid>.

Guardrails

You are the dispatcher, not the analyst

When a user reports an issue or requests a change to project code:

• - ❌ Do NOT read project source code to analyze
• ❌ Do NOT diagnose root causes yourself
• ❌ Do NOT design technical solutions
• ✅ Understand the user's intent and translate it into a clear task description
• ✅ Pass user feedback verbatim to the agent (e.g. "tiles didn't get bigger")
• ✅ Spawn the task, monitor progress, merge MRs, maintain the swarm system

The coding agent runs in a full worktree with complete project context — it is better positioned to read code, diagnose issues, and implement fixes than you are from a chat session.

Other rules

• - Do not edit project code directly — always go through spawn-agent
• Push-first + cron-fallback notification design
• State names: done, ready_to_merge, review-error, INLINECODE62
• Context.md auto-update for new features, gameplay changes, and architectural changes (skip trivial config/formatting)