---
type: runbook
system: atlas-kanban
status: active
owner: Will / Atlas
created: 2026-05-14
related:
  - "[[Atlas Capability Upgrade Program]]"
  - "[[Kanban Task Graph Templates]]"
---

# Atlas Kanban Durable Project Workflow

Use this runbook when a request should become durable, reviewable work instead of staying inside one chat thread.

## When to create or reuse a board

Create or reuse a Kanban board when any of these are true:

- The work spans multiple roles, e.g. research, engineering, ops, review, writing.
- The work should survive an interrupted chat, gateway restart, or laptop sleep.
- A human may need to unblock, review, approve, or redirect a step.
- The output is an artifact, code/config change, runbook, or decision with audit value.
- The work can be parallelized or needs dependency gates.

Use a dedicated board for durable programs and domains. Example:

```bash
hermes kanban init atlas-capability-upgrades
```

Prefer one board per project/domain when unrelated tasks would make status hard to read. Use tenants only as soft namespacing inside a board; use separate boards for hard isolation.

## Default workflow

Default graph:

```text
plan/spec -> task graph -> specialist execution -> reviewer gate -> Atlas synthesis/status report
```

Common stage mapping:

1. Spec/discovery: ops, researcher, or writer creates an implementation-ready spec.
2. Orchestration: orchestrator verifies available profiles, then creates child cards and parent links.
3. Specialist execution: engineer, ops, researcher, writer, or other named specialist does the work in the right workspace.
4. Reviewer gate: reviewer or human reviews code/config/ops changes before they are considered done.
5. Synthesis/status: atlas or writer summarizes outcomes, artifacts, verification, blocked items, and next actions.

## Step 0: inspect current state

Before creating or changing tasks:

```bash
hermes profile list
hermes kanban --board <board> stats --json
hermes kanban --board <board> list
```

Before touching a repository or vault:

```bash
git -C <repo> status --short --branch
```

Do not route work to unknown profile names. The dispatcher will not invent missing assignees.

## Workspace choice

Choose the narrowest workspace that preserves the needed state:

| Workspace kind | Use when | Notes |
|---|---|---|
| `scratch` | Research, specs, status summaries, throwaway artifacts | Fresh per run. Good default for notes that will be copied to durable paths. |
| `dir:<absolute-path>` | Shared persistent notes/config/project directory | Use for Obsidian/vault or other durable shared directories. Inspect status first. |
| `worktree` | Code changes in a git repo | Use for implementation/review to isolate branches. Commit only intentional durable changes. |

For config or repo changes, preserve the stable `default` profile as the production gateway unless Will explicitly asks to migrate it.

## Profile routing policy

Use actual profiles from `hermes profile list`. Current recommended routing:

- `orchestrator`: decompose goals, create/link tasks, status synthesis. Do not implement.
- `researcher`: source discovery, comparisons, requirements investigation.
- `engineer`: code changes, tests, PR-ready diffs in worktree workspaces.
- `ops`: Hermes/profile/gateway/config/runbook operations and host/service diagnostics.
- `reviewer`: code/config/artifact review, approval, or blocking findings.
- `writer`: durable notes, reports, summaries, and polished user-facing artifacts.
- `glm-simple`: cheap/simple low-risk text cleanup or bounded deterministic tasks after an explicit routing decision.
- `atlas`: synthesis/status for Will-facing updates when a durable project needs a named Atlas output.
- `default`: stable production gateway only; do not use as a worker target unless Will explicitly asks.

## Creating dependencies

Use parent links at creation time whenever one task truly needs another task's output.

Example shape:

```bash
SPEC=$(hermes kanban --board <board> create "spec: <feature>" --assignee ops --workspace scratch --priority 10 --json | jq -r .task_id)
IMPL=$(hermes kanban --board <board> create "implement: <feature>" --assignee engineer --parent "$SPEC" --workspace worktree --skill test-driven-development --max-runtime 2h --priority 8 --json | jq -r .task_id)
REVIEW=$(hermes kanban --board <board> create "review: <feature>" --assignee reviewer --parent "$IMPL" --workspace worktree --skill github-code-review --priority 7 --json | jq -r .task_id)
hermes kanban --board <board> create "synthesize: <feature> status" --assignee writer --parent "$REVIEW" --workspace scratch --priority 5
```

Rules:

- Parallel lanes should be siblings with no parent links.
- Dependent stages should use `--parent`/`parents=[...]`; do not rely on prose like "wait for X".
- Create parents first, capture returned ids, then create children with parent ids immediately.
- Avoid linking after creation when a child could be claimed before the dependency exists.

## Worker start and handoff standard

Every worker starts by reading its card and parent handoffs. In a worker, use the Kanban tools; as a human, use:

```bash
hermes kanban --board <board> show <task_id>
hermes kanban --board <board> runs <task_id>
hermes kanban --board <board> log <task_id>
```

Use structured metadata in completions/comments:

```json
{
  "changed_files": ["path/to/file"],
  "artifact_paths": ["path/to/artifact.md"],
  "verification": ["exact command or check performed"],
  "decisions": ["short decision and rationale"],
  "residual_risk": ["known risk or empty list"],
  "retry_notes": "what a retry should avoid or inspect first"
}
```

Never put secrets, raw tokens, raw personal data, long logs, or unrelated transcript text in task bodies, comments, or metadata.

## Reviewer-gate policy

Code, config, and ops changes normally do not complete directly from the implementer.

Implementer workflow:

1. Make narrow, reviewable changes.
2. Verify with targeted commands.
3. Add a Kanban comment containing `review-required handoff` and structured metadata.
4. Block the task with `reason="review-required: <one-line summary>"`.

Example worker-side shape:

```python
kanban_comment(
    body="review-required handoff:\n" + json.dumps({
        "changed_files": ["..."],
        "tests_run": ["..."],
        "verification": ["..."],
        "diff_path": "...",
        "decisions": ["..."],
        "residual_risk": []
    }, indent=2)
)
kanban_block(reason="review-required: implementation finished; needs review before merge")
```

Reviewer workflow:

- Complete the review task if approved, with findings and verification in metadata.
- Block with exact required changes if not approved.
- If changes are needed, create a new follow-up implementation task assigned to the original specialist; do not turn the reviewer card into implementation work.

Docs, research, and spec-only tasks may complete directly when the artifact itself is the deliverable and no risk-bearing change was made.

## Recovery procedure

Do not blindly unblock. Inspect prior state first:

```bash
hermes kanban --board <board> show <task_id>
hermes kanban --board <board> runs <task_id>
hermes kanban --board <board> log <task_id>
```

Blocked task:

1. Read the block reason and comments.
2. If it asks for a human decision, answer in a comment, then unblock.
3. If it is `review-required`, route review or perform review before unblocking.
4. Unblock only after the missing input is present:

```bash
hermes kanban --board <board> unblock <task_id>
```

Spawn failure or gave-up task:

1. Confirm the assignee exists:

```bash
hermes profile list
```

2. Check missing skill, credential, model, or PATH in that profile without printing secrets.
3. Reassign only to an existing profile when needed:

```bash
hermes kanban --board <board> reassign <task_id> <profile> --reclaim --reason "profile recovery: <short reason>"
```

Crashed, timed-out, or stale running task:

1. Read runs/logs/comments first.
2. Prefer chunking scope, reducing memory, or raising max runtime only after understanding the prior failure.
3. Reclaim only when the worker is stale or known dead:

```bash
hermes kanban --board <board> reclaim <task_id> --reason "stale claim: <evidence>"
```

Watch active failures:

```bash
hermes kanban --board <board> watch --kinds completed,blocked,gave_up,crashed,timed_out
```

## Status reporting standard

A daily or phase status report should be produced from board state, not from memory alone.

Inputs:

```bash
hermes kanban --board <board> stats --json
hermes kanban --board <board> list
hermes kanban --board <board> watch --kinds completed,blocked,gave_up,crashed,timed_out
```

Report format:

```markdown
# <Board/project> status - <date>

## Completed since last report
- <task_id/title>: artifact, verification, downstream effect.

## Running/ready by profile
- ops: ...
- engineer: ...
- reviewer: ...
- writer: ...

## Blocked/gave_up items
- <task_id/title>: owner/profile, exact blocker, next action, who owns it.

## Risks / decisions needed
- ...

## Next planned graph expansion
- ...
```

## delegate_task vs Kanban

Use `delegate_task` for short, synchronous, non-durable reasoning inside the current turn when the parent needs the answer immediately.

Use Kanban when work:

- Must survive restarts or interruptions.
- Needs named persistent profiles.
- Requires human review/unblock.
- Spans multiple roles or artifacts.
- Needs dependency tracking or audit history.

A Kanban worker may call `delegate_task` internally for bounded subtasks, but not as a substitute for board handoffs.

## Verification checklist

Before considering a durable project graph healthy:

- `hermes profile list` confirms every assignee exists.
- `hermes kanban --board <board> stats --json` returns successfully.
- Config parse confirms `kanban.dispatch_in_gateway=true` unless intentionally using manual dispatch.
- Task graph has parent links for true dependencies and no links for independent lanes.
- Code/config/ops changes end in reviewer-gated handoffs.
- Status reports include blocked/gave_up items and exact next actions.
