Project Decomposition

A framework for assessing whether a project plan is too large for a single team and, if so, decomposing it into sequenced subprojects (runs) with formal entry/exit criteria, artifact dependencies, and orchestration choreography.

This is a documentation-only activity — it produces plans and validation scripts but does not execute anything.

When to Decompose

Evaluate the plan against these complexity thresholds:

Factor	Single-Team Threshold	Split Recommended
Total tasks	1-15	16+
Distinct phases with sequential dependencies	1-2	3+
Distinct persona types needed	1-4	5+
Estimated working directories	1	2+ (worktrees)
Cross-cutting concerns (handoffs, gates)	0-1	2+
Tasks with external validation (builds, tests)	1-5	6+

Also consider these qualitative factors:

Context window pressure: Will a single team lead exhaust its context window tracking all tasks, agent messages, and intermediate results?
Error blast radius: If one phase fails, does it invalidate all subsequent work? Isolation into runs limits blast radius.
Natural phase boundaries: Does the plan have clear “checkpoint” moments where all prior work is committed and validated before proceeding?

If the plan falls below all thresholds and none of the qualitative factors apply, document the assessment and proceed with a single team. Do not split for the sake of splitting — coordination overhead is real cost.

Invocation

/project-decomposition <plan-file-path>

Where <plan-file-path> is the path to the plan file to decompose. The file can be any structured plan: task-plan.md, exploration-plan.md, implementation-plan.md, or similar.

Examples:

/project-decomposition workspace/projects/ad-hoc/front-end/playwright-exploration/exploration-plan.md
/project-decomposition workspace/projects/mvp2/11-fe-test-coverage/implementation-plan.md

Workflow

Step 1: Read the Plan and Context

Read the plan file.
Identify the project directory (the parent directory of the plan file).
Review available persona definitions to understand capabilities.
Read any files referenced in the plan (analysis documents, parent plans, specifications) for additional context.

Step 2: Assess Plan Size

Apply the complexity thresholds table above. Document each factor’s value, whether it exceeds the threshold, and your overall recommendation.

Step 3: Design the Split

If splitting is recommended, identify runs based on:

Natural phase boundaries — Points where work is committed, validated, and a clean handoff can occur.
Artifact boundaries — Groups of tasks that produce a coherent set of outputs consumed by later tasks.
Persona boundaries — Groups of tasks assigned to the same set of personas.
Risk boundaries — Isolate high-risk work (upgrades, migrations) from lower-risk work (documentation, tests).

Name runs with a sequential prefix and descriptive suffix: run-N-<description>/ (e.g., run-1-context/, run-2-instrumentation/, run-3-validation/).

Step 4: Produce Deliverables

Create the following in the project directory:

Deliverable: `team-split-assessment.md`

Placed in the project directory root. Documents the complexity analysis, recommendation, and proposed run structure.

Template: Team Split Assessment

Populate the Open Questions and Decisions table with any unresolved split boundaries, grouping trade-offs, risk tolerance decisions, or persona assignment ambiguities.

Deliverable: Subproject Directories

One directory per run — run-N-<description>/ — each containing a project-plan.md and a validate-exit.sh script.

`project-plan.md` structure

Template: Project Plan (Run)

`validate-exit.sh`

An executable bash script that programmatically checks all exit criteria:

#!/usr/bin/env bash
set -euo pipefail

# Run N: <Description> — Exit Criteria Validation

PASS=0
FAIL=0
TOTAL=<number of criteria>

check() {
  local desc="$1" cmd="$2" expected="$3"
  local result
  if result=$(eval "$cmd" 2>&1); then
    if [[ "$result" == *"$expected"* ]]; then
      echo "PASS: $desc"
      ((PASS++))
    else
      echo "FAIL: $desc (expected '$expected', got '$result')"
      ((FAIL++))
    fi
  else
    echo "FAIL: $desc (command failed: $result)"
    ((FAIL++))
  fi
}

echo "=== Entry Criteria ==="
# check "description" "command" "expected"

echo ""
echo "=== Exit Criteria ==="
# check "description" "command" "expected"

echo ""
echo "=== Summary ==="
echo "Passed: $PASS / $TOTAL"
echo "Failed: $FAIL / $TOTAL"

[[ $FAIL -eq 0 ]] && echo "ALL CHECKS PASSED" || { echo "SOME CHECKS FAILED"; exit 1; }

Deliverable: `choreography.md`

Top-level orchestration plan in the project directory root. Describes the execution sequence, artifact dependencies, and hand-off protocol between runs.

Template: Choreography

Naming Conventions

Artifact	Convention
Run directories	`run-N-<kebab-case-description>/`
Plan files	`project-plan.md` (inside each run directory)
Validation scripts	`validate-exit.sh` (inside each run directory)
Assessment	`team-split-assessment.md` (project directory root)
Choreography	`choreography.md` (project directory root)
Worktrees	`${projectName}-worktrees/${taskName}` at workspace root
Branches	`${githubUsername}/${projectName}/${taskName}`

Worktree grouping

All worktrees for a project are grouped under a parent directory at the workspace root: ${projectName}-worktrees/${taskName} (e.g., fe-coverage-worktrees/run-2). Branches follow the same hierarchy. Include worktree creation commands in each run’s entry criteria and worktree removal commands in each run’s exit criteria.

Multi-Repository Release Ordering

When the plan spans multiple repositories, the choreography must include a release phase. Run exit criteria should verify that PRs are merged in dependency order and composite build overrides are reverted before the release run begins.

See Release Lifecycle conventions for the full per-repository release sequence.

When NOT to Split

If the assessment determines the plan is small enough for a single team:

Document the assessment in team-split-assessment.md with the rationale.
Do not create run directories or choreography.
Launch a single team directly against the existing plan.

Complex Project Definition and Planning — produces the plans that this skill decomposes
Project Planning Workflow — for well-defined single-phase projects