Agent Workflow

AI Agent Workflow

Agent-workflow requests are usually about choosing the smallest repeatable loop that keeps the agent effective: start the session cleanly, keep repo work grounded, use the right execution surface, and recover quickly when context or tooling drifts. Keep the entrypoint focused on workflow triage and load the references only when the user needs exact command recipes or deeper patterns.

When to use this skill

• Set up a clean daily workflow for Claude Code, Codex, Gemini CLI, or a

mixed-agent toolchain

• Recover from context overload, bad session hygiene, or tool sprawl
• Decide how to split work across chat, shell, MCP, worktrees, and multiple

agents

• Choose a practical repo-delivery loop for edit, test, review, and PR work
• Improve runtime verification habits, especially when a live browser or app

matters

Prefer a narrower sibling skill when the main job is more specific:

• git-workflow for branch, commit, rebase, push, and PR coordination
• agent-configuration for hooks, permissions, skills, plugins, and project

instruction files

• playwriter when browser or runtime verification should use the live browser

session

• clawteam, omg, omx, or ohmg when the user explicitly wants an

orchestrated team workflow rather than a general operating loop

Instructions

Step 1: Classify the workflow request before prescribing commands

Sort the request into one or two primary lanes:

• session-control: startup, context reset, prompt hygiene, resume, handoff
• repo-delivery: inspect, edit, test, verify, commit, PR
• tools-and-runtime: shell vs MCP vs browser vs extension surface
• multi-agent: delegation, worktrees, role split, synthesis

Ground the workflow with the active agent surface, current repo state, and the pain point that is slowing the user down. Do not dump a universal command list before the workflow lane is clear.

Step 2: Choose the smallest operating loop that fits

Use these defaults unless the environment proves otherwise:

• start with the lightest loop that can finish the job safely
• keep read-only inspection cheap before switching to edits or broad tool use
• prefer one bounded branch or worktree per meaningful change lane
• keep browser verification explicit when runtime behavior matters
• recover from context drift by resetting or handing off, not by piling more

instructions into the same polluted session

Step 3: Pull the matching reference, not the whole package

Load only the reference that matches the user's job:

• references/session-and-context-management.md for startup, reset, resume,

handoff, and context hygiene

• references/repo-delivery-and-runtime-loops.md for shell, test, PR,

worktree, and live-verification workflow patterns

• references/mcp-and-multi-agent-patterns.md for MCP usage, delegation,

specialist routing, and cross-agent orchestration

Step 4: Keep workflow advice grounded in the actual surface

Before recommending a loop, confirm the relevant runtime facts:

• which agent or CLI is active
• whether the job is read-only, implementation, review, or verification
• whether a repo, remote, branch, or running app is already in play
• whether the browser or runtime check should use playwriter instead of a

fresh headless browser

Do not prescribe worktree, PR, MCP, or multi-agent flows as generic defaults when the task is small enough to finish directly.

Step 5: Verify the workflow result

After choosing or applying the workflow, verify with the smallest relevant checks:

• repo state or branch state if the workflow touched code
• test or build status if the workflow included implementation
• browser or runtime checks when the workflow claims behavior changed
• explicit next owner or handoff state when the loop is not fully local

Do not claim the workflow is improved until the post-action state matches the intended operating lane.

Examples

Example 1: Recover a polluted session

Input:

My agent session is getting slow and confused. What workflow should I use to
reset without losing useful context?

Expected shape:

• classifies this as a session-control problem first
• recommends reset, resume, or handoff tactics instead of piling on prompts
• preserves only the context needed for the next bounded task

Example 2: Pick a repo-delivery loop

Input:

What is a good daily workflow for using Claude or Codex to inspect code, make a
change, run tests, and open a PR without the session getting messy?

Expected shape:

• picks a compact inspect-edit-verify-commit loop
• uses worktrees or branches only when the scope justifies them
• includes verification before PR creation

Example 3: Decide between shell, MCP, and browser surfaces

Input:

I can use shell tools, MCP servers, or browser automation. How should I decide
which workflow to use for a task?

Expected shape:

• distinguishes read-only shell work from external-service or runtime needs
• keeps MCP or browser usage scoped to tasks that actually benefit from them
• routes live browser verification to playwriter when the active session

matters

Example 4: Split a multi-agent task

Input:

I want one agent researching, another implementing, and another validating.
What workflow keeps that from turning into chaos?

Expected shape:

• classifies this as a multi-agent workflow problem
• recommends bounded ownership, artifact handoff, and synthesis checkpoints
• avoids parallelizing work that is still on the critical path

Best practices

1. Start from the actual bottleneck, not a memorized command catalog 2. Keep the primary loop small: inspect, act, verify, summarize 3. Use worktrees and multi-agent splits only when they reduce contention or waiting 4. Prefer live-browser verification via playwriter when runtime behavior matters 5. Reset or hand off polluted context instead of dragging stale assumptions forward 6. Keep detailed command recipes and platform-specific examples in references so the entrypoint stays compact and triggerable

References

• references/session-and-context-management.md
• references/repo-delivery-and-runtime-loops.md
• references/mcp-and-multi-agent-patterns.md
• Claude Code docs
• OpenAI Codex docs
• Gemini CLI docs

MCP and Multi-Agent Patterns

Use this reference when the workflow problem is mainly about choosing between shell, MCP, browser, or multiple agents and keeping the coordination legible.

MCP decision rule

Reach for MCP when the task needs:

• structured access to an external system
• a client-specific integration surface
• richer interaction than plain shell or file tools provide
• repeated use of the same external capability in one bounded lane

Stay direct when shell or local file inspection can already finish the task.

Do not turn MCP into the default answer for simple repo-local work.

Tool-surface selection

Use the lightest surface that preserves quality:

• direct repo tools for local file and shell work
• MCP for connected services or specialized integrations
• browser automation for rendered or interactive behavior
• live browser reuse with playwriter when session continuity matters

When the user only asks for one narrow outcome, do not prescribe a heavy multi-surface workflow around it.

Multi-agent split rules

Split work across agents only when:

• independent lanes can run in parallel
• ownership can be kept clear
• the synthesis cost is lower than the time saved

Avoid splitting when:

• the next action depends on unresolved work on the critical path
• every lane would edit the same files
• the coordination overhead exceeds the actual task size

Good multi-agent ownership packets include:

• exact goal
• scope boundary
• expected artifact
• reporting checkpoint
• final synthesis owner

Practical patterns

Research -> implement -> verify

Use when the request mixes external discovery, code changes, and validation.

• researcher or web-capable lane gathers the non-local facts
• implementation lane applies the bounded change
• verification lane proves the claim with tests or runtime checks
• lead lane synthesizes outcome and next action

Worktree-based parallel delivery

Use when two independent implementation or review lanes must run at once.

• one branch or worktree per lane
• no overlapping write ownership
• merge or close each lane independently

Runtime-verification lane

Use when code is changed locally but the real proof lives in the app.

• implementation lane changes code
• verification lane checks runtime behavior
• use playwriter when existing browser state matters

Coordination anti-patterns

• parallelizing before the task is decomposed
• assigning multiple agents to the same write set
• opening too many MCP or browser surfaces for one small job
• skipping the synthesis step after parallel work finishes

Repo Delivery and Runtime Loops

Use this reference when the workflow problem is mainly about moving from repo inspection to edits, verification, and PR preparation without thrashing.

Default repo-delivery loop

The smallest durable loop is:

1. inspect the relevant state 2. make one bounded change 3. verify with the smallest convincing check 4. review the diff 5. commit or prepare the PR

Keep the loop narrow. If the change or verification expands beyond one coherent lane, split it before continuing.

Shell vs edit vs browser verification

Use shell-first when:

• the task is file inspection, search, lint, test, build, or other deterministic

local work

• the output needed is textual and repo-local

Use browser or runtime verification when:

• the claim is about rendered behavior or a running app
• stateful browser context matters
• user-visible interactions need confirmation

For live browser or runtime checks, prefer playwriter over fresh headless automation when the active browser session matters.

Worktrees and parallel lanes

Use worktrees when:

• two meaningful branches need to move in parallel
• you need clean separation between feature, hotfix, or review lanes
• one agent or session would otherwise keep stomping on another branch state

Do not use worktrees for a tiny one-file fix that can finish in one branch with one agent.

Good worktree rules:

• one worktree per branch
• one clear owner per worktree at a time
• merge or close stale worktrees once their lane ends
• keep branch names meaningful enough to trace the lane later

PR preparation loop

Before opening a PR:

1. re-check branch and working-tree state 2. run the target validation for the touched lane 3. inspect the diff for accidental scope creep 4. write a commit message that captures why the change exists 5. open the PR only after the bounded scope is clean

If the repo uses recurring maintenance lanes, record the current stage as one of:

• survey
• improvement
• pr-open
• pr-review
• merge

Runtime verification checklist

Before claiming success for a workflow that changed behavior:

• verify the relevant tests or builds if code changed
• verify the live runtime or browser behavior if UX changed
• verify the post-action repo state matches the intended lane
• record the next owner when the current run stops before merge

Session and Context Management

Use this reference when the workflow problem is mainly about keeping the active agent session clean, resumable, and cheap to recover.

Session startup loop

Start each meaningful task with the smallest grounding packet:

1. confirm the active repo or workspace 2. inspect current state before proposing action 3. load only the files or context needed for the next bounded step 4. decide whether this session should stay local or become a handoff

Good startup habits:

• check usage or context pressure early when the client exposes it
• keep a short explicit task statement for the current lane
• separate unrelated tasks instead of stacking them into one long thread
• preserve only reusable conclusions, not every transient detail

When to reset instead of continue

Reset or hand off when:

• the session contains stale assumptions from an older task
• context pressure is causing shallow or repetitive answers
• the next task has a different scope, repo area, or execution surface
• the active thread is spending more effort remembering than solving

Do not keep adding corrective prompts to a polluted session if a clean restart would be cheaper.

Resume and handoff patterns

Use resume when:

• the next step depends on detailed work already done in the same lane
• the session history still matches the current task
• the cost of re-grounding is higher than the cost of continuing

Use a handoff when:

• another agent or later run will own the next bounded step
• the current work produced a stable artifact, status, or queue state
• the next lane needs a narrower specialist or different runtime surface

Good handoff contents:

• current goal
• verified state
• blocker, if any
• next owner
• exact artifact or branch to continue from

Context hygiene rules

• prefer summary plus file references over replaying long transcripts
• keep repo facts separate from temporary hypotheses
• restate the active task after a major pivot
• avoid loading every tool or MCP server "just in case"
• treat browser/runtime validation as its own explicit lane when needed

Recovery checklist

When the session is dragging:

1. stop broad exploration 2. summarize what is verified 3. drop irrelevant branches of work 4. restart or hand off with the minimum surviving context 5. re-ground the next task from current repo or runtime state