agent-team-designer

Files (12)

• SKILL.md
• agent-result.schema.json · assets/schemas/
• run-report.schema.json · assets/schemas/
• team-spec.schema.json · assets/schemas/
• failure-policy.md · references/
• role-contracts.md · references/
• team-spec-guide.md · references/
• topology-catalog.md · references/
• workload-model.md · references/
• render_agent_configs.py · scripts/
• score_workload.py · scripts/
• validate_team_spec.py · scripts/

SKILL.md (first lines)

# Objective

Produce a validated Agent Team Specification v1 that a Codex parent agent can execute predictably.

# Non-negotiable principles

- Prefer the smallest team that can complete the task.
- Do not parallelize work only to appear faster.
- Parallelize read-heavy exploration and independent review before write-heavy implementation.
- Never assign overlapping write ownership to concurrent tasks.
- Keep `max_depth` at `1` unless the user explicitly requires recursive delegation and the added risk is documented.
- Separate implementation from independent review when risk is 2 or higher.
- Require a human approval gate when risk is 3 or 4.
- Treat text instructions as guidance, not a security boundary; express required sandbox modes explicitly.
- Every task must have objective acceptance criteria and an output contract.

# Procedure

1. Read all applicable `AGENTS.md` and `AGENTS.override.md` instructions before designing the team.
2. Extract the task objective, constraints, acceptance criteria, repository scope, prohibited actions, and available deterministic validators.
3. Apply the workload profiling rubric in `references/workload-model.md`.
4. Decide whether a single agent is sufficient. Stop team expansion if it is.
5. Select a topology from `references/topology-catalog.md`.
6. Define narrow role contracts using `references/role-contracts.md`.
7. Build a dependency DAG. Make file or subsystem ownership explicit for every writer.
8. Define command, schema, independent-review, and human-approval gates as applicable.
9. Define retryable and non-retryable failures, total retry cap, conflict behavior, ambiguity behavior, and workspace preservation.
10. Write the result as `agent-team/team-spec.json`, conforming to `assets/schemas/team-spec.schema.json`.
11. Validate the specification with the bundled `scripts/validate_team_spec.py`. Correct all errors. Explain remaining warnings.
12. Return a concise design summary, the validated file path, selected topology, agent count, concurrency cap, primary risks, and next action.

# Required task packet

Do not send the full conversation to every subagent. Each task packet must contain only:

- task objective
- relevant repository scope
- explicit dependencies
- read and write ownership
- acceptance criteria
- output contract
- timeout and retry limit
- known constraints and prohibited actions

# Output requirements

The specification must contain:

- `spec_version`
- task metadata
- six-dimensional workload profile with rationale
- topology and coordination controls
- agent contracts
- task DAG
- validation gates
- failure policy
- budget class
- deliverables

Use `agent-result-v1` for subagent task outputs unless the user supplies another schema.

# Validation command

Run from the skill directory when possible:

```bash
python3 scripts/validate_team_spec.py /absolute/or/repo/path/agent-team/team-spec.json --strict
```

If this script is unavailable at that path, look for the installed project helper at `.codex/agent-team-workflow/validate_team_spec.py` or the user helper at `~/.codex/agent-team-workflow/validate_team_spec.py`.

# Stop conditions

Stop and report a blocked design when:

- acceptance criteria cannot be made testable and the user has not authorized a human gate;
- required repository instructions are unavailable;
- the task requires permissions unavailable to all configured agents;
- high-risk work lacks an approval authority;
- a safe write-ownership partition cannot be established.

From EmbroiderSnow/Agent-Team-Design, MIT.

More from EmbroiderSnow/Agent-Team-Design