# Team Design

> This skill should be used when /forge:design detects 3+ subsystems with cross-boundary interactions and the user opts in to team-based design. Decomposes into subsystems, assigns parallel Designer agents, and synthesizes into a unified design. Do not use for fewer than 3 subsystems or single-component changes.

- Skill: `flox/team-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add flox/team-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/flox/team-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: flox (https://skillmd.com/u/flox)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/flox/team-design

---


# Team-Based Subsystem Design

Orchestrate parallel Designer agents for complex designs
with multiple subsystems. The interactive session (command)
acts as team lead; decomposition and synthesis run as
spawned sub-agents for context isolation.

**This workflow is strictly opt-in.** The command assesses
complexity and suggests team mode when appropriate. The
user always decides whether to proceed.

## Assessment (Lightweight, In-Command)

Assessment happens inside the `/forge:design` command before
spawning any agents. It is a quick scan, not a heavy
operation.

### Path A: design-approach.md Exists

Read `{slice_path}/design-approach.md` and scan for:
- Component count in "Affected Components" table
- Cross-boundary interactions in "Key Technical Decisions"
- External system integrations mentioned

**If 3+ components with cross-boundary interactions:**
Suggest team mode with AskUserQuestion:

> "The design approach identifies {N} components with
>  cross-boundary interactions ({list}). Team-based
>  design produces deeper edge-case coverage for complex
>  multi-subsystem designs.
>
>  **Note:** Team mode uses significantly more tokens
>  (~Nx for N subsystems plus synthesis overhead).
>
>  1. **Team mode** — Architect decomposition, then
>     parallel designers per subsystem, then synthesis
>  2. **Standard mode** — Single designer handles the
>     entire design"

### Path B: No design-approach.md

Read `{slice_path}/requirements.md` and quickly scan for
signals of multi-subsystem complexity:
- 3+ distinct components or services mentioned
- Multiple external system boundaries
- Complex data flows across component boundaries

**If complexity signals are present:**
Suggest running design-approach first:

> "The requirements mention {N} components with external
>  integrations. Running the design approach first would
>  help identify whether team-based design is appropriate.
>
>  1. **Run design approach first (Recommended)**
>  2. **Proceed with standard full design**
>  3. **Proceed with team mode directly** (higher token
>     cost, less signal)"

**If no complexity signals:** Proceed to standard mode
without mentioning team design.

### Assessment Criteria

Team mode is likely beneficial when:
- Design approach identifies 3+ distinct components
- Components exchange data across boundaries or share state
- Multiple external system integrations exist
- Complex state machines span components
- Shared infrastructure requires upfront coordination

Team mode is NOT appropriate when:
- Fewer than 3 subsystems
- Single-component changes
- Simple changes following well-established patterns

## Structural Parallel with Research Lenses

This follows the same "decompose, parallel explore,
synthesize" pattern as Research Lenses
(Skill: `parallel-research`), but applied differently:

- **Lenses** = different perspectives on the same scope
  (external viewpoints)
- **Team design** = same perspective on different scopes
  (internal decomposition)

They remain separate skills because the decomposition
unit differs: lenses slice by concern, team design slices
by subsystem.

## Three Stages (After User Opts In)

### Stage 1: Architect Decomposition

**Who:** The `Architect Decomposer` agent.
Runs as a sub-agent to isolate code discovery and
decomposition work from the interactive context.

**Spawning the decomposer:**

```
Use Task tool with:
- subagent_type: "Architect Decomposer"
- prompt: |
    ## Inputs
    - slice_path: {slice_path}
    - slice_name: {slice_name}
```

### Stage 2: Parallel Subsystem Design (Team)

**Who:** N Designer agents, one per subsystem, spawned as
teammates or parallel sub-agents.

**Spawning each designer:**

```
Use Task tool with:
- subagent_type: "Designer"
- prompt: |
    ## Inputs
    - mode: "full"
    - slice_path: {slice_path}
    - slice_name: {slice_name}
    - subsystem_name: {subsystem_name}
    - subsystem_number: {N}

    ## Subsystem Scope
    {paste the subsystem's section from
     architect-decomposition.md}

    ## Interface Contracts
    {paste the shared interface contracts section}

    ## Output Location
    Write output to:
    {slice_path}/artifacts/subsystem-{N}-{name}.md
    (NOT to design.md -- synthesizer creates that)
```

**Execution modes:**
- If agent teams available and user selects team mode:
  create a team with one designer per subsystem.
- Otherwise: spawn parallel sub-agents, one per subsystem.

### Stage 3: Synthesis

**Who:** The `Design Synthesizer` agent.
Runs as a sub-agent to isolate synthesis work (reading N
subsystem designs) from the interactive context.

**Spawning the synthesizer:**

```
Use Task tool with:
- subagent_type: "Design Synthesizer"
- prompt: |
    ## Inputs
    - slice_path: {slice_path}
    - slice_name: {slice_name}
    - subsystem_count: {N}
    - subsystem_names: [{name1}, {name2}, ...]
```

## Post-Synthesis Evolution

After synthesis produces `design.md`:
- **Most changes:** Edit `design.md` directly (PR
  discussions, reviewer feedback, refinements)
- **Re-synthesis:** Reserve only for fundamental
  architectural changes where second-order effects are
  hard to trace manually

## Cost and Benefit

| Dimension | Impact |
|-----------|--------|
| Token cost | ~Nx for N subsystems + synthesis |
| Wall clock | Parallel execution offsets overhead |
| Edge cases | Deeper — each designer focuses fully |
| Lifecycles | Complete — no cut corners |
| Interface quality | Pre-agreed contracts prevent drift |
| Conflict detection | Synthesis catches gaps |

## Artifact Summary

| Artifact | Location | Producer |
|----------|----------|----------|
| Architect decomposition | `artifacts/architect-decomposition.md` | Architect Decomposer |
| Subsystem designs | `artifacts/subsystem-{N}-{name}.md` | Designer agents |
| Synthesis notes | `artifacts/synthesis-notes.md` | Design Synthesizer |
| Unified design | `design.md` | Design Synthesizer |