Assemble agent team

Assemble Agent Team

Turn a complex task into a small, inspectable team of AI workstreams. Select roles from the task, preserve independent outputs, make dependencies explicit, and require the lead to resolve conflicts into one decision.

Follow the user's language for narrative output. Keep machine-readable field names in English so one run can be validated in any language.

1. Decide whether a team adds value

Use a team when at least one condition is true:

• The user explicitly requests multiple agents, an expert team, or parallel work.
• Three or more perspectives could materially change the decision, resources, risks, or priority.
• Independent research must feed a downstream design, review, or decision.
• The final answer must compare conflicting evidence rather than list opinions.
• The task needs an inspectable record of sources, assumptions, handoffs, and unresolved questions.

Stay single-agent when the task is a simple edit, lookup, translation, narrow summary, or fully specified implementation. Do not create roles for ceremony.

Never use this skill to expand authority. File writes, external messages, purchases, deployments, commits, or production actions still require the same permission they would require without a team.

2. Choose the smallest useful mode

Read mode-selection.md before choosing a mode.

Mode	Workstreams	Shape	Default behavior
quick	2 + lead	One parallel stage, then synthesis	Proceed when low-cost and reversible
standard	3–5 + lead	Parallel research, then one handoff or review stage	Default for cross-functional work
full	5–8 + lead	Multi-stage dependency graph with gates	Explain scope and obtain confirmation first

Choose by decision impact, not by the number of departments that could be named. Merge overlapping roles. More than five workstreams needs an explicit reason; more than eight is out of scope for v0.1.

3. Design workstreams from the decision

Read workflow-design.md when roles or dependencies are not obvious.

For each proposed workstream, define:

• id: stable kebab-case identifier.
• display_name: memorable name or codename shown to the user.
• role: clear professional function, not a fabricated credential.
• mission: why this member exists in this run.
• lens: evidence and standards this member brings.
• boundaries: what this member must not decide or claim.
• question: one decision-changing question.
• inputs: allowed sources or upstream outputs.
• output: independently readable deliverable.
• upstream: workstream IDs that must finish first.
• done_when: observable completion condition.

Keep a workstream only if its answer could change the recommendation, a gate, a resource allocation, or a material risk.

Give every member a human-readable identity. Do not expose a team as Agent 1, Agent 2, or only a machine ID. A good identity looks like Atlas | Technical Architect or 筑川｜技术架构师; it is memorable, task-relevant, and clearly an AI role.

Call participants AI team members, AI workstreams, AI subagents, or AI role perspectives. Never imply that a generated role is a verified doctor, lawyer, investor, researcher, or other real professional.

4. Map execution and initialize the run

Classify the workflow:

• parallel: independent questions can run at the same time.
• handoff: a downstream workstream requires upstream evidence.
• hybrid: parallel research feeds one or more downstream reviews or decisions.

Create a JSON array describing the workstreams:

[
  {
    "id": "user-evidence",
    "display_name": "Echo",
    "role": "User evidence analyst",
    "mission": "Identify which user signals should change the decision.",
    "lens": "Interviews, behavior, adoption, and evidence quality.",
    "boundaries": "Does not decide technical architecture.",
    "done_when": "The report separates observed signals, assumptions, and evidence gaps.",
    "inputs": ["User-provided task brief"],
    "output": "Evidence report with decision thresholds and open questions.",
    "question": "What user evidence should change this decision?",
    "upstream": []
  },
  {
    "id": "product-decision",
    "display_name": "Compass",
    "role": "Product decision lead",
    "mission": "Turn upstream evidence into a bounded product choice.",
    "lens": "User value, constraints, tradeoffs, and reversibility.",
    "boundaries": "Must not invent missing evidence.",
    "done_when": "The report makes one bounded choice and names its reversal gates.",
    "inputs": ["User-provided task brief", "user-evidence report"],
    "output": "Product decision memo with a recommendation and reversal gates.",
    "question": "Which option best fits the evidence and constraints?",
    "upstream": ["user-evidence"]
  }
]

Initialize one run directory:

python3 scripts/init_run.py \
  --topic "decision topic" \
  --mode standard \
  --language zh-CN \
  --lead-name "知衡" \
  --lead-role "主控决策整合员" \
  --output-root ./outputs \
  --workstreams ./workstreams.json

Use a user-approved output directory. Do not overwrite an existing run. Keep all formal artifacts under the generated run root.

The run must contain:

00_manifest.md
01_<workstream-id>.md
02_<workstream-id>.md
...
99_lead_synthesis.md

Use the templates in assets/ when constructing or repairing artifacts.

5. Execute without leaking conclusions

When independent subagents are available:

1. Give each subagent only its assigned question, allowed inputs, constraints, and output contract.
2. Avoid giving parallel agents one another's expected conclusions.
3. Run independent workstreams concurrently when useful.
4. Start dependent workstreams only after their declared upstream artifacts exist.
5. Ask downstream workstreams to cite the upstream files they used.
6. Keep status current in 00_manifest.md.

Do not request hidden chain-of-thought. Require concise methods, evidence, findings, decision implications, risks, and handoff notes.

When independent subagents are unavailable, either return the proposed plan or continue with actor_type: single-agent-fallback. Put that value in both the manifest entry and its report, list the affected IDs in the lead's fallback_workstreams, and name them under Execution Disclosure. Never claim that multiple independent agents ran when they did not.

6. Require evidence-aware reports

Read evidence-and-synthesis.md before final synthesis.

Every workstream report must include:

1. Identity card
2. Assigned question
3. Inputs and method
4. Evidence and sources
5. Findings
6. Decision implications
7. Risks and unknowns
8. Recommendation
9. Handoff

Separate:

• sourced facts,
• user-provided facts,
• reasoned inferences,
• assumptions,
• unknowns.

If no external sources were used, state No external sources used rather than leaving the source section empty.

7. Synthesize; do not average

The lead must read every completed required report and produce:

• executive answer,
• workstreams used,
• evidence-strength assessment,
• consensus,
• conflict matrix,
• resolution and rationale,
• unverified assumptions,
• final recommendation or Go/No-Go,
• next steps and stop conditions,
• source index.

The lead must choose or define a conditional gate. Do not end with only “each option has pros and cons.”

8. Validate before delivery

Run:

python3 scripts/validate_run.py <run-directory> --final

Fix structural errors before presenting the result. Treat privacy and suspicious-claim warnings as review prompts, not proof that content is safe.

Read safety-and-privacy.md for sensitive inputs, high-stakes domains, or public artifacts.

9. Deliver compactly

Lead with the decision. Then link or list the manifest, independent reports, and synthesis. State:

• the selected mode,
• which workstreams actually ran,
• whether any fallback occurred,
• important unknowns,
• what still requires human judgment.

Do not describe a plan as completed execution.