---
title: Swarm Operating Manual
area: reference
tags: [reference, assistant, atlas, swarm]
created: 2026-05-14
updated: 2026-05-14
status: active
related: [[Ops Home]], [[Project Context Index]], [[Context Pack]], [[Promote Session Output to Notes]], [[Atlas Capability Upgrade Program]]
---

# Swarm Operating Manual

This is the front door for Will's Atlas/Hermes/Obsidian/Kanban swarm. Start here when an agent or human needs to understand where durable state lives, how work moves through the system, and what must stay out of notes.

## Entry points

- Daily navigation: [[Ops Home]].
- Active project state: [[Project Context Index]] and the relevant note in `Projects/`.
- Reusable procedures: [[Runbooks Home]].
- Stable references and summaries: [[Resources Home]].
- Specialist handoffs: use [[Context Pack]].
- Session promotion procedure: [[Promote Session Output to Notes]].

## Roles

- Will: sets goals, approves policy decisions, reviews risky or irreversible work.
- Atlas / coordinator: maintains high-level context, routes work to Kanban or specialist profiles, synthesizes handoffs, and keeps indexes current.
- Writer: drafts docs, project context packs, status reports, runbooks, and note updates.
- Researcher: gathers sources and summarizes facts with citations or source paths.
- Implementer / coding specialist: makes narrow code or config changes in the correct repo or workspace.
- Reviewer: checks usability, safety, diffs, tests, and whether acceptance criteria were met before changes are treated as complete.

## Where durable state lives

- `Projects/`: active implementation programs, project specs, project status, and project-specific context.
- [[Project Context Index]]: one-row orientation for active projects, including board, repo/workspace path, status, commands, runbooks, and owner/reviewer.
- `Runbooks/`: repeatable operational procedures.
- `Decisions/`: important product, architecture, or workflow choices.
- `Resources/`: stable summaries, manuals, research notes, and references.
- `Templates/`: reusable note and handoff formats.
- `Inbox/`: loose captures that still need triage.
- Hermes Kanban: active task graph, blockers, worker handoffs, and review gates.

## Starting work

1. Open [[Ops Home]] and follow links to the active project or runbook.
2. Check [[Project Context Index]] for the project row: board, status, repo/workspace path, owner, reviewer, and verification commands.
3. Read the project note and any linked specs, runbooks, decisions, or context packs.
4. If the work is multi-step or should survive one chat, create or use a Hermes Kanban board/task instead of keeping it in chat.
5. Give specialists a short [[Context Pack]] rather than a long transcript.
6. At handoff, write durable facts to the right note and put transient execution details in Kanban comments or the final worker summary.

## Request patterns

- Plan: ask Atlas to create a plan/spec in `Projects/` or `.hermes/plans/`, then route work through Kanban.
- Execute: provide a context pack, target files/repos, acceptance criteria, and verification commands.
- Review: point reviewer at the diff, artifact path, task id, tests run, and risk areas.
- Schedule: use Hermes cron for recurring checks or summaries; document the job purpose and owner in the relevant project/runbook.
- Promote: use [[Promote Session Output to Notes]] when chat output becomes durable knowledge.

## Safety boundaries

Never write these to notes, task bodies, commits, or durable handoffs:

- API keys, passwords, OAuth tokens, private keys, session cookies, recovery codes, or credentials.
- Raw PII or contact details beyond what is already intentionally kept in the vault.
- Full chat dumps copied for convenience; summarize current state, decisions, paths, and verification instead.
- Runtime churn such as cache files, offsets, local auth state, `.obsidian/workspace.json`, or generated database WAL/SHM files.
- Unsupported claims, guessed paths, or stale status presented as current truth.

Use `TBD (owner: name)` for unknown fields rather than inventing values.

## Maintenance cadence

- Update [[Project Context Index]] after major Kanban completion, repo/workspace change, new runbook, or accepted decision.
- Review active project rows weekly for stale status, missing reviewer, or obsolete commands.
- When a specialist creates a durable artifact, link it from the project note and relevant home/index note.
- Keep [[Ops Home]] mostly as navigation; keep vault-wide rules in [[Vault Conventions]]; keep swarm workflow guidance here.
