/team-shape

name: team-shape
description: "Assess team structure against Skelton's Team Topologies. Evaluate cognitive load, interaction modes, and Conway's Law alignment."
metadata:
  instruction_budget: "26"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."

Team Shape Assessment

Evaluate organizational design for fast flow. Source: Skelton & Pais, *Team Topologies*, **2nd edition (IT Revolution, 23 Sept 2025, ISBN 9781966280002)**.

**Model re-verified against primary sources 2026-09-01** — teamtopologies.com/key-concepts, the 2nd-edition publisher page, and the 2026 AI material (QCon London keynote 17 Mar 2026; "AI ROI" executive report 12 Aug 2026). It is still **four** fundamental team types and **three** interaction modes. The authors have added no AI-specific team type, and their stated position is that none is needed. Third parties do propose new ones (SAFe, various blogs) and InfoQ's QCon report names an "Innovation and Practices Enabling Team" — read the name: that is a *named specialization of the existing enabling team*, not a fifth fundamental type. Do not add either to the enum in `schemas/canvas/team-shape.schema.json`.

Two caveats worth carrying: the 2nd edition adds **platform grouping** (a platform team may itself be one or more teams), and the live site renders the third interaction mode "Facilitation" while the book says "facilitating" — which is why that enum is deliberately unpinned.

Preflight: Read target canvas file(s) before any Write/Edit

**Hard rule.** Before issuing `Write` or `Edit` against any `.claude/canvas/*.yml`, use the **Read tool** on that file in this session. Claude Code's Read-before-Write check requires the `Read` tool specifically — `cat`/`head`/`grep` via Bash do NOT satisfy it.

**Edit vs Write — different cost profiles** (verified 2026-05-14):

• **`Edit`** (exact-string replacement): `Read` with `limit: 1` satisfies the check at ~50 tokens. State-tracking is per-file, not per-byte — subsequent `Edit` calls work anywhere in the file. Use this for partial updates against large canvas files (e.g., `purpose.yml` at 800+ lines).
• **`Write`** (full replacement): do a **full Read** first. Write obliterates the file; you should see what you're about to replace. The `limit:1` shortcut is *not* appropriate here.

**ID-bearing entries — scan the ID space before assigning** (added 2026-05-15, v0.23.19): When adding a new component, opportunity, solution, or any other ID-bearing entry to a canvas file, run a Bash grep first to confirm the next ID in your prefix sequence is actually free:

grep -o "<prefix>-[0-9][0-9]*" .claude/canvas/<file>.yml | sort -u -t- -k2 -n | tail -3

Replace `<prefix>` with the canvas's ID prefix (`comp` for landscape, `opp` for opportunities, `sol` for solutions, `ht` for human-tasks, etc.). Then pick the next free integer, **matching the zero-padding already used in that file**. The sort is NUMERIC (`-t- -k2 -n`) rather than lexical, and that is not pedantry: a plain `sort -u` orders `ht-1` after `ht-080`, so on a canvas with inconsistent padding it reports the wrong maximum and the next ID collides. Verified on the dogfood repo 2026-08-13, where lexical sort returned `ht-1` as the highest human-task ID against an actual `ht-080`. `grep -o` is also deliberate: it matches IDs wherever they appear, including cross-references and prose, so an ID that was promised somewhere but not yet defined is not handed out twice. `validate_canvas.py` has a per-file duplicate-ID check (it reports `duplicate id '<id>'`) that catches the failure on CI, but a duplicate can persist in the working tree for days if CI isn't run between edit and discovery; that happened on 2026-05-15, when a duplicate ID was created in `landscape.yml`.

Original failure mode: anti-pattern #7 instance #5, 2026-05-09 — agent conflated Bash `head` with the Read tool, lost ~14k tokens to a Write-fail → remedial-full-Read → re-Write loop. The `limit:1` discipline (graduated 2026-05-14, v0.23.18) prevents the second-order cost where the agent *correctly* follows the rule but full-Reads every time. The ID-scan discipline (graduated 2026-05-15, v0.23.19) prevents the related class where the agent reads enough of the file to satisfy the Edit check but not enough to see existing ID assignments — kin to anti-pattern #8 (Stale State Read).

If this skill writes to multiple canvas files, register each one first (limit:1 for Edit-only paths; full Read for Write paths) AND ID-scan any prefix you intend to assign.

See `${CLAUDE_PLUGIN_ROOT}/engine/agent-operating-contract.md` *Canvas writes — Read before Write* for the canonical rule.

Assessment Workflow

1. Map Current Teams

For each team, classify:

• **Stream-aligned**: Owns a user journey or business domain (most teams should be this)
• **Enabling**: Helps other teams acquire capabilities (temporary engagement)
• **Complicated subsystem**: Deep specialist knowledge (only when cognitive load justifies)
• **Platform**: Internal product that reduces cognitive load for stream-aligned teams

2. Evaluate Cognitive Load

For each team, assess:

• **Intrinsic load**: Problem complexity (can't reduce, only manage)
• **Extraneous load**: Bad tools/processes (SHOULD reduce -- platform teams help here)
• **Germane load**: Learning new relevant things (encourage)
• If team is overloaded: shrink domain, move complexity to platform, or split

3. Audit Interaction Modes

Between each pair of collaborating teams:

• **Collaboration**: Working closely together (time-box this -- it's expensive)
• **X-as-a-Service**: Consuming/providing via API (ideal steady state)
• **Facilitating**: Helping another team learn (enabling teams do this)

4. Conway's Law Check

Conwa