Agentic Orchestration Part 1: Taming Local Claude Agents
Welcome to the first part of our series on building a resilient, autonomous agentic workflow. Over the next five posts, we will explore how to transition from running one-off scripts to building a fully-fledged command system that leverages local Claude agents to automate tedious repository maintenance.
In this first part, we focus on the foundation: defining agents in ~/.claude/agents, structuring complex workflows in ~/.claude/commands, and passing context via strict handoff documents.
What are Local Claude Agents?
When we talk about “local agents,” we are referring to configurations living directly on your machine. Instead of interacting with a generic AI over a web interface, a local agent is deeply contextualized.
In our architecture, an agent is defined as a simple Markdown file with YAML frontmatter in ~/.claude/agents/. For example, here is a snippet of ~/.claude/agents/major-upgrader.md:
---
name: major-upgrader
description: Major version upgrade specialist. Detects outdated major versions, groups related packages by ecosystem (e.g. @nestjs/*), reads migration docs, creates a plan, then processes each group.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---
# Major Version Upgrader
You are an expert at upgrading packages across major version boundaries...
By defining the agent this way, we give it a clear identity, a specific LLM model, and access to necessary tools (like Bash or File Editing). The markdown body contains its strict operating instructions.
The Orchestrator Command Pattern
To automate tasks, you need to chain multiple agents together. We define these pipelines in ~/.claude/commands/. The primary entry point is the /orchestrate command.
If you run /orchestrate feature "Add user authentication", the Orchestrator doesn’t just prompt Claude once. It executes a predefined workflow chain:
planner -> tdd-guide -> code-reviewer -> security-reviewer
The first agent in this chain, the Planner (powered by the larger opus model), acts as the architectural brain. It is instructed to never write application code directly. Instead, it breaks the complex feature down into a highly structured Implementation Plan containing:
- Architecture Changes (e.g., new database tables or API routes).
- Implementation Steps broken into phased milestones with specific file paths.
- Risks & Mitigations.
By forcing the planner to think strictly about architecture first, we prevent the “blank canvas hallucination” where an LLM just starts furiously writing spaghetti code.
The Handoff Document
LLMs suffer from context bloat. If the code-reviewer agent sees all the scratchpad thoughts of the planner agent, it gets confused. To solve this, the Orchestrator enforces a strict Handoff Document between agents in the chain.
When an agent finishes its job, it must produce a document exactly like this:
## HANDOFF: planner -> tdd-guide
### Context
[Summary of what was planned]
### Findings
[Key architectural decisions]
### Files Modified
[List of files touched]
### Open Questions
[Unresolved items for the next agent]
The Orchestrator takes this Markdown block and feeds it to the next agent in the pipeline as its starting prompt. This keeps the context clean, isolated, and focused.
What’s Next?
Now that we have defined our agents and the Orchestrator pipeline, we can start putting them to work. In Part 2, we will explore our first concrete workflow: /orchestrate dependency-updates repo. We will see how the planner -> security-upgrader -> pr-creator pipeline automatically manages our minor and patch bumps.
Keep pushing forward and savor every step of your coding journey.