agent-team-prompt-generation

# Agent-Team Prompt Generation

Use this when handing a GitHub issue or tightly scoped workstream to Codex in one self-contained prompt, especially after planning is complete and you want Codex to operate like an internal agent team in a single run.

## When to use
- A parent issue or child issue is already planned and needs an execution-ready Codex prompt
- The repo has workflow gates and Codex needs all constraints in one place
- You want one Codex 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/`

## Core pattern

Write one markdown prompt file that gives Codex:
1. exact repo path
2. exact issue number + title + URL
3. parent/child issue relationships
4. authoritative docs/artifacts to consume
5. allowed write paths
6. read-only paths
7. forbidden paths
8. success condition
9. explicit step-by-step execution flow
10. 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 Codex 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 Codex from silently broadening scope.

### 3. Artifact grounding
List the exact authoritative files Codex 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 Codex 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:
1. Read and assess current state
2. Produce or update the main artifact
3. Run internal adversarial review
4. Run final integrator pass
5. 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:
1. What changed
2. Final review verdict
3. Whether label/state was changed
4. Exact files changed
5. Exact GitHub comments/labels added
6. Residual blockers

This makes later orchestration and artifact roundup much easier.

## Recommended template skeleton

```md
# Codex agent-team prompt: <issue>

We are in `<repo-path>`.

You are Codex 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 Codex whether to post a summary comment
- tell Codex 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 Codex 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 Codex must finish a normative operating model and only move to `status:plan-review` if review clears
- child contract issue handoff where Codex must write one normative spec document under an already-approved parent model
- validation issue handoff where Codex must create conformance-check design without redefining architecture

## Pitfalls
- vague allowed paths like “relevant files”
- no forbidden-path block
- not telling Codex whether the issue is planning-only vs execution-ready
- asking Codex 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

## 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 Codex handoff.