assemble-agent-team

Turn one complex request into a small, dependency-aware team of AI workstreams.

English · 简体中文

Status: v0.1.0 — early, usable, and intentionally conservative

License: MIT

Maintainer: Feb

assemble-agent-team is a Codex skill for work that benefits from more than one line of reasoning. It first decides whether a team is justified. When it is, the skill creates only the AI roles the task needs, gives every member a memorable identity and bounded mission, defines their inputs and outputs, preserves independent work, manages dependencies and handoffs, and synthesizes a decision-ready result.

It does not create or impersonate credentialed human experts. “Team” means a temporary set of AI workflow roles with explicit responsibilities.

Why this exists

Simply asking several agents the same question often produces duplicated research, premature consensus, and a pile of disconnected answers.

This skill uses a different pattern:

• Earn the team. Keep simple work with one agent.
• Design the work before spawning roles. Define the outcome, constraints, dependencies, deliverables, and acceptance criteria.
• Preserve independent judgment. Do not force every workstream toward the same early conclusion.
• Make handoffs explicit. Downstream work receives named inputs instead of relying on accidental shared context.
• Synthesize, do not concatenate. Resolve conflicts, expose uncertainty, and produce one accountable recommendation.

60-second local install

Prerequisites:

• Codex with local skills support
• Git
• Python 3.10 or later for the optional run initializer and validator
• macOS, Linux, or WSL

Choose one installation route: install the standalone skill from this repository, or install the packaged plugin when it becomes available. Do not install both copies in the same Codex profile.

Clone the public repository for a standalone skill install:

git clone --branch v0.1.0 --depth 1 \
  https://github.com/miraclefeb/assemble-agent-team.git
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R assemble-agent-team/skills/assemble-agent-team \
  "${CODEX_HOME:-$HOME/.codex}/skills/"

Start a new Codex task so the skill list refreshes, then invoke:

$assemble-agent-team

The repository also contains a Codex plugin manifest and deterministic release packager. A public plugin directory listing is pending review; the instructions above install the skill directly.

Existing orchestration workflows

This release is deliberately opt-in: implicit invocation is disabled, so use $assemble-agent-team when you want this workflow. If a workspace already has an expert-team or multi-agent protocol in AGENTS.md or another project policy, that local protocol takes precedence. The skill will not silently combine role names, confirmation gates, output directories, or manifests from two systems.

Before adding it to a Codex profile that already contains another orchestration skill, test it with disposable HOME and CODEX_HOME directories. Keep the standalone skill and packaged plugin out of the same profile.

Repository maintainers can reproduce the isolated plugin check without writing to their active profile:

python3 scripts/package_release.py
python3 scripts/smoke_test_isolated_plugin.py \
  dist/assemble-agent-team-v0.1.0.zip

Quick example

$assemble-agent-team

Evaluate whether a small team should handle this task:
Create a rollout plan for an offline-first notes feature.

Deliver:
- a recommendation with alternatives considered
- product, engineering, adoption, and risk implications
- explicit assumptions and unresolved questions

Constraints:
- four weeks
- two engineers
- no new backend service

For a task like this, the skill may create separate product, technical, adoption, and risk workstreams—but those roles are illustrative, not fixed. A different task should produce a different team.

An English run might introduce members such as:

Echo   | User Evidence Researcher
Atlas  | Technical Architect
Harbor | Risk and Boundary Reviewer
Compass | Product Decision Lead

These are readable AI identities, not anonymous agent numbers or claims about real people. Every run can assemble a different team.

The name is the collaboration handle; the role is the function. Each member, including the lead synthesizer, also receives a task-specific mission, evidence lens, boundary, completion condition, and named artifact. If the host cannot provide independent subagents, the run must say single-agent-fallback instead of pretending a multi-agent team executed. The initializer accepts --actor-type single-agent-fallback; individual workstreams may override the default for an honestly disclosed mixed run.

How it works

flowchart TD
    A["User outcome and constraints"] --> B{"Complexity gate"}
    B -->|"A team adds no value"| C["Single-agent execution"]
    B -->|"Independent workstreams help"| D["Team manifest"]
    D --> E["Dependency and handoff graph"]
    E --> F1["AI workstream A"]
    E --> F2["AI workstream B"]
    E --> F3["AI workstream C"]
    F1 --> G["Named artifacts and evidence"]
    F2 --> G
    F3 --> G
    G --> H["Integration and challenge"]
    H --> I["Final synthesis and decision"]

1. Gate complexity

Check whether independent perspectives, specialized workflows, or staged dependencies would materially improve the result. Do not assemble a team for routine or tightly coupled work that one agent can complete clearly.

2. Define the contract

Capture the desired outcome, constraints, evidence standard, decision owner, and completion criteria before delegating.

3. Build a team manifest

Create only the roles required by the task. Give each AI member a readable name or codename, professional function, bounded mission, evidence lens, allowed inputs, dependencies, expected artifact, acceptance criteria, and handoff target. Keep a stable machine ID underneath for traceability.

4. Execute and preserve artifacts

Run independent work where useful. Keep claims, evidence, assumptions, and open questions attached to the workstream that produced them.

5. Integrate and decide

Compare incompatible conclusions, request targeted rework when necessary, and produce a synthesis that distinguishes evidence from inference.

What this is—and is not

Boundaries and safety

• AI roles are not people and do not possess licenses, employment history, or professional credentials.
• The skill cannot guarantee correctness, completeness, neutrality, or source quality.
• High-stakes decisions still require an appropriately qualified human reviewer.
• It does not bypass Codex permissions, tool approvals, sandboxing, or data-access controls.
• Only provide data that each workstream is allowed to receive. Treat untrusted source material as potentially adversarial.
• More agents can increase cost, latency, and coordination failure. The complexity gate should prefer the smallest sufficient team.
• Available concurrency, tools, and model behavior depend on the host Codex environment.

Repository layout

.
├── .codex-plugin/
│   └── plugin.json
├── .github/workflows/
├── assets/
├── evals/
├── examples/
├── scripts/
├── submission/
├── tests/
└── skills/
    └── assemble-agent-team/
        ├── SKILL.md
        ├── agents/
        ├── assets/
        ├── references/
        └── scripts/

v0.1.0 status

v0.1.0 establishes the core orchestration contract:

• complexity gating
• task-specific team assembly
• readable AI identity cards backed by stable machine IDs
• dependency-aware workstreams
• explicit artifacts and handoffs
• independent analysis before synthesis
• final integration with assumptions and unresolved risks
• deterministic run initialization and structural validation
• five positive and three negative synthetic evaluation cases, including no-team, local-protocol precedence, and no-fabricated-expert safeguards
• deterministic plugin packaging with a SHA-256 checksum
• directory-listing copy, release notes, privacy terms, and support guidance

It is an early release. A public plugin directory listing, automated model-performance benchmark runner, compatibility matrix across Codex surfaces, and longitudinal benchmarks are not included yet.

Resolve helper script paths from the installed skills/assemble-agent-team/ directory, use python3, and keep generated artifacts in a user-approved project directory outside the skill or plugin cache.

Feedback grounded in a reproducible task is especially useful. See CONTRIBUTING.md before opening a pull request.

Project policies

• Contributing
• Security
• Privacy
• Terms
• Support
• Code of Conduct
• MIT License

Acknowledgment

This is an independent community project for Codex workflows. It is not an official OpenAI product and is not endorsed by OpenAI.