project-decomposition
Installation
SKILL.md
Project Decomposition: Recon, Grouping & Validation
What this skill does
This is the single entry point for measuring a codebase scope and (when needed) decomposing it into topology groups. Two modes:
- Lightweight recon (JSON) —
scripts/decompose.py ... --profile-jsonproduces a structuredProjectProfileJSON with LOC / file counts / module list / dep graph summary / skip patterns. Used by upstream planners to decide pipeline variant and grouping needs. - Full grouping + validation —
scripts/decompose.pydirectly, for L0→L1→L2 grouping protocol and L3 quality validation. Used when the workflow plan declaresgrouping.needed: true.
Both modes are the same decompose.py engine — single source of truth for LOC counting (--lang defines the LOC semantic boundary; --exclude defines the directory boundary), graph extraction, and validation scoring.
Which mode to run
| Caller intent | Use | Why |
|---|---|---|
| Decide whether to fan out at all (sizing, dispatch) | --profile-json |
Returns structured ProjectProfile (LOC, module count, depth, hub-ratio, sizing hints) without grouping output. Cheap, machine-readable. |
| Caller already decided to fan out and needs L1 numbers + L2 grouping + L3 validation | run without --profile-json; then again with --validate for L3 |
Human-readable Graph Statistics + Quality Scores. |
| Caller wants both | run twice: once with --profile-json for the planner, once without for human L1 |
The flags are mutually exclusive in one invocation; do not combine --profile-json with --validate. |