do

Overview

The do skill is the main entry point for the somnio-loop plugin. It accepts a ticket or task description and orchestrates the full agentic loop end-to-end — from triage and planning through implementation, verification, and final artifact delivery.

When to use

User pastes a Jira/Linear/GitHub ticket or a free-form task description
User says /loop:do, “run this end to end”, or “execute the full flow”
Any request that implies a multi-phase deliverable handed off to autonomous execution

Do NOT use for single-step lookups or quick edits — those run without loop overhead.

Inputs

Input	Description
Ticket text	Full ticket body, bullet list, or bare ticket ID (e.g. `TKT-123`)
`.loop/config.yaml`	Autonomy preset and gate configuration
`.loop/state.md`	Prior run context and watch list
`--autonomy=<preset>`	Optional per-run override at the end of the ticket

Outputs

Output	Location
Final deliverable(s)	User’s outputs folder
`run-report.md`	Alongside every artifact
`plan.yml`	`.loop/plans/<ts>-<ticket_hash>.yml`
`trace.json`	`.loop/traces/<ts>-<ticket_hash>.json`
Updated run-log	`.loop/run-log.md`

The final chat message always includes an executive summary and a per-agent consumption table (model, invocations, time, tokens, cost).

Definition of Done

A run is not complete until all of the following are present. The orchestrator verifies this checklist before delivering the final message — missing items trigger a re-dispatch or an explicit partial status, never a silent skip.

Item	Required
Every artifact in `final_artifacts:` exists and is non-empty	Always
`verify-report.md` with a `BLOCKING:` line	Always
`run-report.md` with status, phases, tokens, cost, artifact list	Always
Per-agent consumption table with consistent totals	Always
`run-log.md` entry updated to final status	Always
`trace.json` saved to `.loop/traces/`	Always
`plan.yml` archived to `.loop/plans/`	Always
Ticket status updated / PR created / notification sent	When configured

If the run must be delivered as partial (budget exhausted, max retries hit, unresolvable verifier findings), the orchestrator surfaces exactly what is present and what is missing, and adds the missing items to state.md → High Priority for the next run.

Multi-ticket: one branch and one PR per ticket

When running multiple tickets (do "MH-100 MH-101" or --parallel), each ticket is fully isolated. This is the most common multi-ticket failure mode: workers from two tickets landing on the same branch and producing a merged PR that conflates unrelated changes.

The invariant: one ticket → one branch → one PR. Always. No exceptions.

Scope	Isolated per ticket
Branch	`feature/MH-100-...` and `feature/MH-101-...` — created independently from the same base
Worktrees	Each ticket gets its own `wt-<ticket_id>-<worker_n>` directories
Output dir	`/tmp/loop-runs/<ts>-MH-100/` and `/tmp/loop-runs/<ts>-MH-101/`
run-log entry	One entry per ticket
PR creation	Phase 7 runs independently per ticket — NOT once for the whole batch

How parallel dispatch works

When using --parallel, each ticket is dispatched as an independent sub-agent that runs the full 8-phase do protocol on its own. The parent orchestrator does NOT run phases or create PRs — it only collects results and assembles the summary.

do (parent orchestrator)
  ├─ Agent: ticket MH-100 → runs full loop → branch feature/MH-100-... → PR #444
  ├─ Agent: ticket MH-101 → runs full loop → branch feature/MH-101-... → PR #445
  └─ summary table (assembled by parent after both return)

At the end the orchestrator shows a consolidated table with one PR URL per ticket:

| Ticket | Status      | Branch                    | PR   |
|--------|-------------|---------------------------|------|
| MH-100 | ✅ completed | feature/MH-100-add-cache  | #444 |
| MH-101 | ✅ completed | feature/MH-101-fix-login  | #445 |

Example

/loop:do TKT-421 — Add rate limiting to the public API
 
Acceptance criteria:
- 429 returned after 100 req/min per API key
- X-RateLimit-* headers on every response
- Existing integration tests still pass

Quickstart loop-adr