Design

team-forge:design — machinery design (opt-in)

Entry condition: the contract earned it. This phase runs only when docs/team-forge/<team>/contract.yaml says route: machinery (a needed check with no backing capability, cross-session/unattended work, or genuine fan-out/standing roster — see the contract skill's Step 7). Direct execution — the default — never comes here; a contract whose route outgrows the fast path comes back and runs this phase then.

This phase produces .claude/team-forge/<team>/design.yaml — what the forge consumes. The design is generated by multiple forge-design-agents running in parallel, each focused on a different lens; their reciprocal review catches gaps before the human approval gate.

Follow-on for an already-forged team/workflow reusing its roster + gate vocabulary skips this phase too: the contract's task sketch carries everything TASKS.yaml needs — append the tasks to the existing TASKS.yaml, sync status.json.goal_directive from the revised contract, and resume the runtime loop.

Step 0 — machinery interrogation (absorbed from the old Phase 1)

The contract deliberately doesn't ask these; they are machinery concerns. Ask now:

1. Archetype (work-shape) triage:

   "As the work proceeds, do the agents each hold distinct, evolving context they defend across rounds (research debate, competing approaches) — or is it a stream of tasks/items done, gated, and handed off, each unit starting fresh?" Fresh-per-unit / gate-driven → workflow (pick shape: sequential-gated | parallel-drain, + recurring if scheduled/unattended; elicit the integration branch). Persistent peer-context → team (refine the contract's task sketch into 2–5 milestones, each with a verifiable output + human go/no-go, hard dependencies, interface-to-next, expected team size, iteration shape; cyclic dependencies → push back).

2. Roster needs beyond work/verify/advise? Domain experts, external-tool wrappers, anything project-specific.
3. Tracking expectations? State fields + dashboard panels the user wants — the contract's done_when status is always panel one.
4. Token budget? Hard ceiling or soft target; per-cohort if iterative.

Inputs

• The contract (docs/team-forge/<team>/contract.yaml) — problem, checkable done_when, decision split, task sketch. Legacy brainstorm/plan docs, if the KB has them, are background only.
• The user (for approval gates)

What you produce

.claude/team-forge/<team>/design.yaml — fully populated per the template at <team-forge-extension>/templates/design.yaml.j2.

Procedure

Archetype branch. If Step 0's triage chose archetype: workflow, run "Workflow archetype — Phase 3 branch" below instead of the roster lenses. It produces a design.yaml with archetype: workflow blocks (shape / recurring? / tasks-or-queue / gates / worker / advisor / ledger), not roster / rehydrate / tracking.

The lead invokes this skill, then orchestrates 3 design-agents in parallel. Each agent gets the contract (and any legacy brainstorm/plan docs), but a different lens.

---

Workflow archetype — Phase 3 branch

W-Step 1 — asset discovery + gate-vocabulary discovery

Run the same asset discovery (skills + agents across the 4 sources, domain-filtered). Additionally — the workflow centerpiece — discover the GATE VOCABULARY from the codebase's verification surface (W5): read the repo's test suites, CI config, build targets (Makefile), and invariants; for each, name a gate (command + criterion). A gate that needs a backing capability the repo lacks (e.g. a pre/post-refactor parity harness) is a skill gap. Skills are the product (WORKFLOW-SCOPING.md): the gap-filling skills are the highest-value output, not the agents.

Record each gap as a skill_gaps: entry in design.yaml (schema + quality bar in templates/design.yaml.j2) — Phase 4 emits one DRAFT scaffold per entry. Hold each entry to the skill quality bar below.

W-Step 2 — dispatch 3 design-agents (workflow lenses)

• Lens 1 — task/gate correctness: from the contract's task sketch, propose the tasks block (id, output, depends_on, blast_radius, gate_set ⊆ gates, dispatch inline|worker); verify the DAG is acyclic and each gate_set matches its blast_radius. (Parallel-drain: propose the queue block — eligibility, triage predicate, wave_size, routes — instead.)
• Lens 2 — gate vocabulary + skill gaps: finalize gates from the codebase surface; list the skill gaps to produce; confirm every blast-radius tier has a covering gate.
• Lens 3 — profile + fan-out + ledger fit: propose the worker + advisor profiles (default procedure + project skill overlay), the ledger (state_shape — incl. the current_plan/plan_history runtime fields — events, dashboard_panels), the fan_out points (where the lead bursts via the Workflow tool), and (parallel-drain) the recurring block. Dashboard sizing: a one-shot workflow (no recurring) gets NO dashboard by default — status.json + TASKS.yaml is the whole observability surface; only add ledger.dashboard: true when the run is long/recurring enough that a rendered page earns its keep. If a dashboard IS declared, dashboard_panels entries must be renderer ids from the shell's registry (see templates/design.yaml.j2 — forge.py aborts on anything else); panel intent goes in a YAML comment, never as a prose list entry. Declare a fan_out point ONLY where there is genuine N-way parallelism or a multi-item fan-out→synthesize→verify — single/sequential tasks stay inline (the lead codes them, or one Agent dispatch for an isolated piece), never a Workflow. Over-declaring fan_out makes the runtime burst where an inline step would do; the parallel-drain wave is the one always-Workflow point.

W-Step 3 — synthesize + compose the workflow design.yaml

Point contract: at the problem contract first (both archetypes): the forge lints it and DERIVES the goal: block — the lead's standing orders — from it (statement, checkable done_when, decision split). Never hand-compose goal: when a contract exists; a hand-written block is only for contract-less legacy designs, and drift between the two is a defect.

Reconcile the lenses and compose design.yaml with archetype: workflow + the workflow blocks. Worked schema references: tests/fixtures/workflow-tidy/design.yaml (sequential-gated) and tests/fixtures/workflow-drain/design.yaml (parallel-drain + recurring). Invariant: ledger.state_shape declares shape only — current_plan/plan_history are runtime fields the forge seeds null/[], never contract literals.

W-Step 4 — present + skill-gap plan

Show the user the task DAG, the gate vocabulary, and the skills to be produced (the skill_gaps entries, each with its trigger + acceptance). On approval, go to Phase 4 — the forge renderer (python3 <team-forge-extension>/tools/forge.py <design.yaml>) auto-detects archetype: workflow and emits one DRAFT scaffold per gap at .claude/team-forge/<team>/skill-drafts/<name>/SKILL.md. The human (optionally with skill-creator to flesh out the body) reviews each draft against its promotion checklist, runs the acceptance check green, then promotes it to .claude/skills/<name>/. Until promoted, gates that call the skill fail-closed — intentional.

---

Skill quality bar — "a proper skill per project purpose" (both archetypes)

A skill_gaps entry earns forging only if it passes all five:

1. One capability, not a task note — reusable beyond the task that spawned it. "Check pre/post parity for module X" fails; "pre/post-refactor parity harness" passes.
2. Trigger-first description — the trigger field states when to invoke ("Use when …"), because that description is what future sessions match against. A summary of what the skill is does not trigger.
3. Runnable acceptance — a command that proves the skill works, executable before promotion. No acceptance → no forge.
4. Purpose-anchored — traceable to project.domain + brief + the contract's verification posture. The verification posture is the richest gap source: every "what does 'good' look like" answer with no backing capability is a kind: verification gap.
5. Discovery-first — a gap exists only after reuse and adapt buckets came up empty; if prior art was adapted, cite it in adapted_from.

Team archetype — Phase 3 (the roster lenses)

Step 1 — Pre-design: asset discovery (skills + agents), purpose-filtered

Before dispatching design-agents, the lead searches for reusable assets — both skills AND agents — across four sources, then filters by the project's domain/purpose (from the contract) so the design agents see only relevant prior art, not the whole world.

Sources:

1. <target_repo>/.claude/skills/ + <target_repo>/.claude/agents/ — project-local

2. ~/.claude/skills/ + ~/.claude/agents/ — user-global

3. Installed Claude Code plugins — read each plugin's skills/ and agents/

4. Reference libraries named in design.yaml.reference_libraries (e.g. ecc). Each name resolves to a pinned manifest team-forge ships at reference-libraries/<name>.yaml (repo URL + pinned commit). Materialize the pinned commit on demand into a local cache and read its agents/ + skills/:

   CACHE=$(python3 <team-forge-ext>/tools/fetch_reference.py <team-forge-ext>/reference-libraries/<name>.yaml)
   # then read $CACHE/agents and $CACHE/skills
   

   Reference libraries are never vendored into team-forge and never installed as active skills (that would overflow context + pollute the namespace). They are prior art to adapt, fetched at a pinned commit so discovery is reproducible. ECC at its pin has ~60 agents + ~250 skills — the domain filter below is what keeps that from swamping the design.

Domain filter (MANDATORY): keep only assets whose domain matches the project. A frontend project keeps frontend-patterns, a11y-architect, the React reviewer; it drops the golang / swift / healthcare entries. Without this filter a large reference library (ECC has ~180 assets) swamps the design. Filter BEFORE passing the catalog to the design agents.

Produce four buckets:

• reuse — installed agents/skills usable as-is: domain-agnostic AND already in the target's .claude/agents/ (or user-global / a plugin) → reference, don't re-emit. Reuse policy is strict — only propose reuse when the asset is domain-agnostic AND domain-matches. A combiner-specific librarian is NOT offered to a frontend team. Never reuse another forged team's <team>-* agent: it is theirs and retires with them, so depending on it breaks you at their teardown. If you want that capability, forge your own copy under your team's prefix.
• adapt — reference-library assets (e.g. ECC agents/skills) whose pattern is worth borrowing. Default consumption mode is reference-and-adapt: the forge writes our own project-owned version citing what it adapted — NOT a verbatim vendor-copy (avoids licensing entanglement + staleness).
• collision-list — every existing agent/skill name in the target, so the forge never emits a clashing filename.
• pattern-reference — agents/teams (ours or ECC's) whose role structure informs the roster design.

Pass the filtered catalog + buckets to all 3 design-agents.

Step 2 — Dispatch 3 design-agents in parallel

The lead spawns 3 forge-design-agents via Agent() dispatch. Each runs a Phase 3 design pass independently. They DO NOT see each other's output until Step 4.

Lens 1: roster-correctness

"Read the contract (+ any legacy brainstorm/plan docs). Propose a roster with at least one teammate per required role (work / verify / advise). Add tracker/monitor teammates ONLY if the tracking load justifies standing agents (high event volume, long-running cohorts) — the default is a lead-written ledger + a deterministic dashboard render step. For each teammate: name, role, purpose (one paragraph), skills (from this catalog: <skill catalog>). Special focus: are there gaps where a role can't be filled because no skill exists for it? Flag aggressively."

Returns: roster proposal + gaps list. Before inventing any teammate, check the reuse + adapt + pattern-reference buckets — prefer reusing an existing shared agent, or adapting a reference-library agent (e.g. an ECC reviewer/architect), over a blank-page invention. Flag each roster entry as reuse / adapt / new.

Lens 2: comms + coverage

"Read the contract + this draft roster. Validate:

• Role coverage (work/verify/advise + orchestrator; tracker/monitor only if justified)
• Comms closure (every reference resolvable)
• Hard dependencies (do milestones actually have prerequisites the roster can fulfill?) Propose a tracking.state_shape (fields + their source agents) and tracking.events_to_log. Flag anywhere the proposed roster lacks an agent that the milestones' interfaces would require."

Returns: validation issues + tracking spec proposal.

Lens 3: domain fit + risks

"Read the contract + this draft roster + this skill catalog. Where does the roster feel 'forced'? Are there project-domain constraints from the contract that no roster entry addresses? Propose constraints[] entries for domain-specific facts. Propose dashboard_panels[] entries that would be useful for the user — choosing ONLY from the shell's renderer-id registry (see templates/design.yaml.j2); panel intent goes in a comment, never a prose entry."

Returns: domain-fit issues + constraints proposal + dashboard_panels proposal.

Step 3 — Wait for all 3 agents

All 3 return structured outputs. Lead collects them.

Step 4 — Reciprocal review

Lead synthesizes the 3 lens outputs:

1. Roster: take Lens 1's roster as starting point; apply Lens 2's coverage corrections; flag any issues Lens 3 raises about specific entries
2. tracking.state_shape: take Lens 2's proposal; cross-reference with Lens 3's dashboard_panels (every panel should be backed by a state field)
3. tracking.events_to_log: combine Lens 2's enum proposal
4. tracking.dashboard_panels: take Lens 3's proposal; verify each panel has supporting state in state_shape AND is a registry renderer id (forge.py aborts on prose entries)
5. constraints: take Lens 3's proposal; the contract's context + domain facts should map here
6. skill_discovery_results.proposed_loadouts_per_teammate: derive from Lens 1's roster (each teammate's skills field)
7. skill_gaps: from Lens 1's gaps list ("no skill exists for this role/need") + any verification-posture item with no backing capability — filtered through the Skill quality bar above. Each surviving gap becomes a full skill_gaps: entry (name, kind, backing, trigger, spec, acceptance, consumers); Phase 4 emits its DRAFT scaffold.

If the 3 lens outputs conflict on the role coverage (e.g., Lens 1 says 5 teammates is right, Lens 2 says we need 7) → invoke a 4th agent to resolve, or surface the conflict to the user.

Step 5 — Compose the design.yaml

Render the template at <team-forge-extension>/templates/design.yaml.j2 with:

• project block from the contract + user-confirmed
• milestones block from Step 0's refinement of the contract's task sketch
• roster from synthesis above
• rehydrate block:
  • durable_state derived from the universal team-forge layout (see SCOPING.md)
  • respawn_order: [tracker first IF present; advise + shared verifiers next; work next; monitor last IF present]
• tracking block from synthesis
• constraints from synthesis
• skill_discovery_results from Step 1 + Step 4 synthesis

Write the rendered YAML to .claude/team-forge/<team>/design.yaml.

Step 6 — Present to the user

Show the user:

• The full design.yaml (or a summary of it)
• Specifically highlight:
  • Which existing assets you propose to reuse rather than forge (and why each is domain-agnostic + already installed)
  • Which teammates have NO skill loadout (pure prompt-driven)
  • Any gaps flagged by Lens 1
  • Any domain-fit issues flagged by Lens 3
• Ask: approve to move to Phase 4 (Forge)?

Step 7 — On approval, persist + log

After user approval:

1. The design.yaml is already written (Step 5)

2. Log a phase_3_complete event to the tracker (if tracker is already spawned; if this is a fresh run, tracker doesn't exist yet — that comes in Phase 4)

3. Emit (the old Phase 4 — now just the renderer): run the tooling preflight below, then python3 <team-forge-extension>/tools/forge.py <path-to-design.yaml> and review its output (it validates the design + contract, aborts on a hook-protected default branch, and prints every file it emits). Skill-gap DRAFTs land in skill-drafts/ for human promotion.

   Tooling preflight (warn, don't abort — record accepted risks in constraints): grep the target's .claude/settings*.json + .claude/hooks/ for (a) an auto-formatter PostToolUse hook that re-churns unrelated lines — have the user scope it to changed lines or bless a binary-write path first; (b) a review-receipt hook that inspects staged files from the harness CWD — under worktrees it never sees the staged files and gets blanket-bypassed, silently defeating the gate; make it worktree-aware first; (c) model pins with no fallback tier — confirm critical stages aren't pinned to a single provider tier (the runtime retries one tier down on outage).

Re-design loop

If the user rejects:

1. Capture WHY (specific issues)
2. Re-dispatch the 3 design-agents with the rejection context added to their prompts
3. Loop until user approves or aborts

Failure modes

• All 3 lens outputs disagree on role coverage → surface to user, don't auto-resolve
• Skill discovery returns empty → the project's .claude/skills/ and ~/.claude/skills/ are bare; tell the user that loadouts will be sparse and ask if they want to install a skill library (or configure a reference library) before continuing
• No agent in the catalog matches a critical role need → tell the user; the project will need either custom skill development OR a different roster strategy

What this skill is NOT

• Not Phase 4. We don't emit any .md files here — only the design.yaml.
• Not autonomous. The user gates Step 6.
• Not the contract phase in disguise. The problem + done_when are settled there; we design machinery for them.

Output review

The review checklist for this phase lives at references/review.md — extracted from this skill so a separately-dispatched review subagent can load just the criteria without the full procedural skill body (context isolation).

Two equivalent ways to run the review:

1. Inline (lighter, lead does it) — read references/review.md yourself, run the checklist against the file(s) you just produced, surface ✓/✗ results to the user before the approval ask.

2. Subagent (more isolated, fresh context) — dispatch a subagent with the prompt:

   "Review the output at <path-to-output-file> against the criteria in references/review.md of the team-forge <this-skill-name> skill. Report the checklist as a ✓/✗ list, then name any specific gaps for each ✗." The subagent reads only the criteria file + the output — no other team-forge context required.

Either path produces the same checklist output. The subagent path is preferable when the lead's context window is large enough that adding the review work would crowd it, or when a colder/independent verdict is wanted.

After the review (regardless of path), surface results to the user and ask: approve, revise, or abort. Do not auto-pass on a hard-abort trigger (those are documented in references/review.md per phase).