| name | agent-team-prompt-generation |
| description | Create self-contained execution prompts that define multi-role workflows for Claude sessions without external dependencies |
| version | 1.1.0 |
| source | updated-from-use |
| updated | "2026-04-11T00:00:00.000Z" |
| metadata | {"tags":["workflow","prompt-engineering","planning","role-based-execution","claude-code","github-issues"]} |
Agent-Team Prompt Generation
Use this when handing a GitHub issue or tightly scoped workstream to Claude Code/Codex/Gemini in one self-contained prompt, especially after planning is complete and you want a provider session to operate like an internal agent team in a single run.
Also use it when generating a small set of independent swarm prompts for the same repo ecosystem; see references/parallel-independent-swarm-prompts.md for the five-lane audit decomposition, /goal reverse-prompt shape, and launch/logging pattern.
When to use
- A parent issue or child issue is already planned and needs an execution-ready Claude prompt
- The repo has workflow gates and Claude needs all constraints in one place
- You want one Claude session to simulate multiple roles (Planner, Architect/Implementer, Reviewer, Integrator)
- You need strict write-path ownership and zero scope creep
- You want a reusable handoff artifact committed into
docs/plans/
- You need 3-5+ independent AI swarms to audit different lenses of the same repo ecosystem with comparable outputs
Core pattern
Write one markdown prompt file that gives Claude:
- exact repo path
- exact issue number + title + URL
- parent/child issue relationships
- authoritative docs/artifacts to consume
- allowed write paths
- read-only paths
- forbidden paths
- success condition
- explicit step-by-step execution flow
- exact final return format
The key learning: prompts work best when they are not just “do issue #NNN”, but a constrained operating contract.
Recommended role block
Start the prompt with an internal team definition like:
- Planner
- Architect or Implementer
- Adversarial Reviewer
- Integrator
This reliably pushes Claude to:
- inspect current state first
- draft or revise the main artifact
- critique its own result
- then synthesize and post the final outcome
Required prompt sections
1. Repo and issue identity
State:
- working directory
- primary issue URL
- related/parent/child issues
- whether the issue is planning-only, implementation-ready, or validation-only
2. Workflow constraints
Explicitly state:
- whether the repo is plan-gated
- whether the issue is already
status:plan-approved
- whether this run is architecture-only, planning-only, or implementation-ready
- what must NOT be redefined from the parent issue
This prevents Claude from silently broadening scope.
3. Artifact grounding
List the exact authoritative files Claude must read first.
Example categories:
- parent operating-model docs
- current plan file
- review artifacts
- issue thread state
- likely implementation surfaces
Best practice: say “consume these as authoritative” instead of “consider these if helpful.”
4. Path contract
Always include three blocks:
- Allowed write paths
- Read-only paths
- Forbidden paths
This is the most reusable high-value pattern from the session.
Rules:
- allowed write paths should be exact files or tightly bounded directories
- forbidden paths should include sibling issue territories
- if the worktree is dirty outside allowed paths, instruct Claude not to touch unrelated files
5. Success condition
Give one explicit paragraph describing what must exist by the end of the run.
This should describe outputs, not effort.
Good pattern:
- “By the end of this run, the repo should contain …”
- then list the artifact qualities and required GitHub updates
6. Step-by-step execution plan
Use numbered steps.
A robust pattern is:
- Read and assess current state
- Produce or update the main artifact
- Run internal adversarial review
- Run final integrator pass
- Post GitHub summary / transition issue state if eligible
7. State-transition rule
If the prompt can change GitHub state, include a conditional rule.
Example:
- if final review is APPROVE/MINOR -> move to next state / apply label
- if final review is MAJOR -> do not transition; post blocker summary and stop
This was especially useful in plan-gated issue execution.
8. Final return format
End with a strict required-output list such as:
- What changed
- Final review verdict
- Whether label/state was changed
- Exact files changed
- Exact GitHub comments/labels added
- Residual blockers
This makes later orchestration and artifact roundup much easier.
9. Parallel swarm prompt contract
When producing prompts for multiple independent swarms, assign each worker one lane, one prompt file, one log file, and one expected output artifact. Make the prompts comparable by using a shared output schema, but make the investigation lens distinct per swarm. If the user asks for "reverse prompts" or prompts "we can submit" to /goal, generate copy-paste-ready prompt text or prompt files; do not launch agents, mutate issue state, or push branches unless the user explicitly asks for dispatch/execution. If dispatch is explicitly requested, record PID/provider/log/artifact metadata and verify the process has actually started before reporting dispatch success. See references/parallel-independent-swarm-prompts.md.
Recommended template skeleton
# Claude agent-team prompt: <issue>
We are in `<repo-path>`.
You are Claude Code operating as an internal 4-role agent team in one run:
1. Planner
2. <Architect/Implementer>
3. Adversarial Reviewer
4. Integrator
Do not ask the user any questions.
Repo/workflow constraints:
- ...
Primary issue:
- #NNNN <url>
Parent / related issues:
- ...
Authoritative artifacts to consume:
- ...
Allowed write paths:
- ...
Read-only paths:
- ...
Forbidden paths:
- ...
Success condition:
- ...
Execution steps:
STEP 1 — Read and ground
STEP 2 — Produce/update main artifact
STEP 3 — Internal adversarial review
STEP 4 — Final integrator pass
STEP 5 — GitHub update / state transition
Output requirements:
1. What changed
2. Final review verdict
3. ...
GitHub-specific guidance
When the prompt targets a GitHub issue:
- include the exact issue URL
- include child issue URLs if the work must stay inside one child issue’s scope
- tell Claude whether to post a summary comment
- tell Claude whether label changes are allowed
- explicitly forbid changing labels if that should remain orchestrator-owned
Parent/child issue execution pattern
For issue trees, use this division:
- parent issue prompt: architecture, scope boundaries, dependency order, review synthesis, plan state transitions
- child issue prompt: specialized contract or implementation under the approved parent model
Important lesson:
- tell Claude exactly what the child issue must not redefine from the parent
- otherwise it may re-open already-settled architecture decisions
Dirty-worktree safety pattern
Add this clause whenever the repo may already be dirty:
- first inspect
git status --short
- if unrelated changes exist outside allowed paths, do not touch them
- stop and report if safe isolation is not possible
This is especially important in shared orchestration repos.
Best-fit examples from use
- planning/architecture issue handoff where Claude must finish a normative operating model and only move to
status:plan-review if review clears
- child contract issue handoff where Claude must write one normative spec document under an already-approved parent model
- validation issue handoff where Claude must create conformance-check design without redefining architecture
Pitfalls
- vague allowed paths like “relevant files”
- no forbidden-path block
- not telling Claude whether the issue is planning-only vs execution-ready
- asking Claude to both define parent architecture and implement child details in one run
- missing final return format
- no explicit rule for when GitHub labels/comments should or should not change
- for multi-swarm dispatch, treating process launch as completion instead of separately reporting startup, running/exited state, and artifact existence
- treating a request for reverse prompts as authorization to launch agents; prompt-generation mode and dispatch mode are separate
- giving independent swarms overlapping write permissions or mutually dependent tasks
Minimal checklist before saving a prompt file
- Is the repo path exact?
- Is the issue URL included?
- Are parent/child boundaries explicit?
- Are allowed/read-only/forbidden paths all present?
- Is there a clear success condition?
- Is there a conditional state-transition rule?
- Is the final return format explicit?
If yes, the prompt is usually robust enough for one-go Claude handoff.
