AI Prompts for Sub-agent Orchestration

Write the role definition for a maker agent in [YOUR_PROJECT]. The maker agent's only job is to implement tasks from the task queue. Write the role as a .claude/agents/ YAML definition that specifies: the agent's name and description, the exact instructions for reading a task from .agent/tasks.md, the constraints on what files it may edit, the test it must run before marking a task done, and the format it uses to update the state file when finished.

Write the role definition for a checker agent in [YOUR_PROJECT]. The checker agent may never write or modify code. Its job is to review the maker's output against: the original task spec, the test results, the style conventions in AGENTS.md, and any performance or security requirements. Write the full .claude/agents/ YAML definition and the structured output format the checker must produce: PASS with summary, or FAIL with a numbered list of specific issues.

Write a sub-agent definition for a read-only research agent for [YOUR_PROJECT]. This agent reads code, documentation, and logs. It may not write to any source files or tests. Its output is always a structured markdown report written to .agent/research-[timestamp].md. Define: the agent's allowed tools (file reads, shell for grep and find only), the output format, and the prompt template it uses to scope its research.

I am building a multi-agent team for [YOUR_PROJECT] using [TECH STACK, e.g. Next.js, Supabase, Tailwind]. Design three specialized agents matched to this stack: one frontend agent (focuses on React components and CSS), one backend agent (focuses on API routes and database queries), and one ops agent (focuses on deployment config and environment variables). Write the YAML definition for each, including which files each agent is allowed to edit.

Write a sub-agent definition for [YOUR_PROJECT] that maintains documentation automatically. The agent runs after every successful implementation pass and: reads the git diff to understand what changed, updates the affected sections of README.md and any inline JSDoc comments, writes a changelog entry, and updates AGENTS.md if any loop conventions changed. The agent must never modify source code or tests. Write the full agent definition.

Design the handoff format that the maker agent writes for the checker agent in [YOUR_PROJECT]. The handoff must include: the task ID and original spec, the files changed with a summary of each change, the test command run and its output, the commands used to verify the change works, and a confidence score from the maker (1-3) with the reason. Write the full format specification and a sample handoff for a fictional bug fix.

Write the orchestrator prompt for [YOUR_PROJECT] that starts the agent team, monitors progress, and makes routing decisions. The orchestrator should: read .agent/tasks.md each cycle, assign the highest-priority task to the maker agent, wait for the maker to write its handoff file, pass the handoff to the checker, read the checker verdict, and either mark the task done or send it back to the maker with the checker's failure notes. Write the full orchestrator prompt.

My sub-agent handoff in [YOUR_PROJECT] sometimes fails when the checker cannot evaluate the maker's output because the handoff file is incomplete. Write the failure recovery protocol: what the orchestrator should check if the handoff file is missing or malformed, the retry prompt it sends to the maker agent, the maximum number of retries before escalating, and the escalation format that alerts me without stopping the loop.

I have three independent tasks in [YOUR_PROJECT] that can be worked on in parallel: [TASK 1], [TASK 2], [TASK 3]. Design a parallel agent workflow using git worktrees: one worktree per task, one maker agent per worktree, one shared checker agent that reviews all three when done. Write the launch sequence, the worktree naming convention, the checker scheduling logic, and the merge protocol once all three pass verification.

Write the final step in the [YOUR_PROJECT] agent loop: the merge and close protocol. After all tasks in a batch pass verification, the loop should: merge each worktree branch to main in priority order, run the full test suite after each merge, roll back any merge that introduces a failing test, delete the merged worktrees, update .agent/done.md, and write the batch summary. Write the merge protocol as a loop prompt and as a Claude Code hook.