Source of Truth for agent-driven development workflows.
Issue → Branch → Worktree → Implementation → Handshake → QA Gate → PR Merge
- Trigger: New issue or
/om-prepare-issue - Agent: Coordinator (Gemini)
- Output: Labeled, prioritized issue with acceptance criteria
- Skills:
om-auto-manage-issues,om-prepare-issue
- Trigger: Issue assigned to Builder
- Agent: Builder (Claude Opus / Claude Code VS Code)
- Output: Isolated git worktree at
tmp/worktrees/<branch-name> - Script:
os-run-builder <branch-name> - Claude Code: Use
/worktree-initslash command or run manually:git worktree add tmp/worktrees/feature/<branch> -b feature/<branch>
- Trigger: Worktree ready
- Agent: Builder (Claude)
- Protocol:
[PLAN → HANDOFF → NOTIFY] - Commit Policy: Atomic (1 commit per unit of work)
- Skills:
om-auto-implement-spec,om-auto-fix-issue,om-fix
- Trigger: Implementation complete
- Agent: Builder → Auditor
- Output:
<conversation_id>_<role>_handshake.jsonin.agents/swarm/ - Validation:
python3 scripts/validate-handshakes.py
- Trigger: PR created with
needs-qalabel - Agent: Auditor (Gemini-Low)
- Gates: lint → typecheck → test → visual proof
- Policy: NO auto-merge. Requires
qa-approvedflag. - Skills:
om-auto-qa-pr,om-auto-review-pr,om-code-review
- Trigger:
qa-approvedlabel set - Agent: Coordinator (approval) + Builder (merge)
- Skills:
om-approve-merge-pr,om-merge-buddy - Post-merge:
om-auto-update-changelog,om-followup-issue-from-pr
- Coordinator NEVER writes code directly in the root workspace unless explicitly authorized by the user via the interactive PreToolUse gate (
guard_coordinator_pretool.pyforce_ask dialog). For features and refactors, code changes MUST be delegated to a Builder subagent in an isolated worktree. - Builder ALWAYS operates in worktrees (
tmp/worktrees/*) — never onmain/masterdirectly. - Auditor can BLOCK any merge.
- Every PR requires visual proof for UI changes.
- HANDOFF.md must exist before phase transition.
- Coordinator MUST execute state-dump (
.agents/MEMORY.md,.agents/task.md) before final user report. - Swarm state commits SHOULD be cryptographically signed on every machine — procedure and open decisions in
.agents/specs/commit-signing.md. A plain SHA-256 written next to the file it hashes is NOT an integrity control. - Human-in-the-Loop Mandate for
/plan&/grill-me: Automated IDE review policies ("Always Proceed" / auto-approval stop hooks) MUST BE IGNORED for architectural plans and interviews. The Coordinator is strictly forbidden from proceeding to worktree allocation, code changes, or subagent dispatch based on an automated system message. Explicit human confirmation (viaask_questionmodal or typed chat input) is strictly required.
- /plan: An architectural planning phase executed by the Coordinator. The plan MUST explicitly structure execution into:
- Worktree Allocation (
tmp/worktrees/feature/<name>) - Subagent Delegation (
invoke_subagent-> Builder) - Handshake & QA Gate (
scripts/generate-handshake.py+scripts/validate-handshakes.py) - PR & Merge
Human-in-the-Loop Enforcement: The Coordinator MUST use the interactive
ask_questionmodal or halt for manual chat confirmation. Automated "Always Proceed" signals are invalid for plan authorization.
- Worktree Allocation (
- /grill-me: Pre-flight architectural interview. All answers and consensus decisions MUST be directly confirmed by the human operator before moving to implementation. Automatic progression through review policies is strictly blocked.