[skill-gap]: support hierarchical decomposition for large specifications

[leohxj]

Affected skill

spec-driven-development, with downstream impact on planning-and-task-breakdown and the /plan, /build, /review, and /ship workflow.

Relevant instruction or excerpt

The current workflow is effectively:

one request
→ one SPEC.md
→ one tasks/plan.md
→ one flat tasks/todo.md
→ implementation

The skill can make individual tasks small (for example, limiting their file scope), but it does not define how to decompose one oversized requirement into independently specifiable business capabilities before planning begins.

Project context

This appears when one product requirement contains several independently testable capabilities, such as identity, billing, notifications, and reporting, with explicit dependencies between them.

This is different from running multiple unrelated specs in parallel.

What did not work or did not apply

For a large requirement, task breakdown happens too late. Even if every task is small, all tasks still depend on one monolithic specification and one global plan.

That creates several failure modes:

• the agent must repeatedly load and reason over an oversized contract;
• module boundaries, interfaces, data ownership, and dependency direction remain implicit;
• modules cannot be planned, built, reviewed, or resumed independently;
• a change in one module can invalidate the global plan and task list;
• completion is tracked only at task level, not at capability/module level;
• the final integration and /ship review can become too large to evaluate reliably.

Splitting the work into frontend/backend/database tasks would not solve this. The decomposition unit should be an independently testable business capability or bounded context.

Relationship to existing work

This proposal is intentionally not a duplicate of:

• Proposal : have the specs save in a specific directory structure #50 and Support for multiple/parallel specs #180, which identify artifact overwriting and multiple/parallel spec scoping;
• Feature: Standardize spec directory structure to prevent overwriting #73, which proposes feature-specific directories;
• docs(spec): add spec evolution guidance — V1 scoping and delta specs #383, which proposes V1/delta-spec evolution and plan source-spec tracking.

Those address namespace and temporal evolution. This issue addresses complexity decomposition inside one large requirement.

A useful distinction is:

archive/lifecycle       → separates work across time
workstream namespace    → separates concurrent requirements
module decomposition    → separates complexity within one requirement

A complete workflow may eventually need all three.

Proposed capability

When /spec identifies multiple independently testable business capabilities, it should pause before planning and propose a module decomposition for human approval.

1. Parent initiative spec

The parent spec should contain only cross-cutting concerns:

• overall objective and scope;
• global constraints and invariants;
• module/capability map;
• dependency graph;
• cross-module interfaces;
• integration and end-to-end success criteria;
• deferred or explicitly excluded capabilities.

2. Child module specs

Each module spec should define:

• one independently testable business capability;
• inputs, outputs, and public interfaces;
• data ownership and boundaries;
• dependencies and forbidden dependencies;
• inherited parent constraints plus explicit deltas;
• module-level success criteria.

3. Module-scoped execution artifacts

Each child spec should have its own plan and task list, tied to the exact source spec:

specs/<initiative>/
├── SPEC.md
├── modules.md
└── modules/
    ├── identity/
    │   ├── SPEC.md
    │   ├── plan.md
    │   └── todo.md
    └── billing/
        ├── SPEC.md
        ├── plan.md
        └── todo.md

The exact directory is open for discussion. The important property is stable identity: downstream commands must select an explicit initiative/module path and must never guess which spec or plan is active.

4. Dependency-aware integration

Independent modules may be implemented separately. Dependent modules must follow the approved dependency graph. Before the initiative can ship, the workflow should verify the parent spec's cross-module and end-to-end criteria.

5. Preserve the simple path

Small, cohesive requirements should keep the current single-spec workflow. Hierarchical decomposition should activate only when the requirement contains genuinely independent acceptance boundaries.

Possible workflow

/spec <initiative>
→ detect oversized/multi-capability scope
→ propose module map and dependency graph
→ human approval
→ /spec <initiative>/<module>
→ /plan <initiative>/<module>
→ /build <initiative>/<module>
→ /review <initiative>/<module>
→ integration verification against parent spec
→ /ship <initiative>

Suggested acceptance criteria

• Existing single-spec workflows and evals remain unchanged.
• A large-requirement eval causes the agent to propose capability decomposition before producing a flat plan.
• Parent and child specs have explicit identities and traceable relationships.
• Plans and task lists record their source spec and are never silently reused for another module.
• Dependency ordering is represented and checked before implementation.
• Module completion does not imply initiative completion.
• /ship <initiative> requires the parent integration criteria, not only module-local checks.
• Documentation clearly distinguishes capability decomposition from artifact namespacing and delta specs.

Non-goals

• Do not split work mechanically by repository directories or technical layers.
• Do not require parallel agents or worktrees.
• Do not force hierarchical specs on small features.
• Do not prescribe a full project-management framework.

Open questions

1. Should this live inside spec-driven-development, or be a separate decomposition skill invoked by it?
2. Should module identity be a command argument, a manifest entry, or an explicit artifact path?
3. How should module lifecycle and archive behavior compose with the delta-spec direction in docs(spec): add spec evolution guidance — V1 scoping and delta specs #383?
4. Should branch/worktree metadata be optional module metadata, or remain outside the spec workflow?

[addyosmani]

Well-scoped proposal, and the distinction you draw is the right one. Complexity decomposition inside one requirement is genuinely different from namespacing (#50, #180, #73) and from temporal or delta evolution (#383), and the pack has no home for it today. The "preserve the simple path" constraint and the non-goals (no PM framework, no forced hierarchy on small features) are what keep this from becoming overhead, and they're non-negotiable if it lands.

On your open question 1, my lean is to extend spec-driven-development rather than add a separate decomposition skill. It's the same discipline at a higher altitude, one request that happens to contain several independently testable capabilities, and forking it into its own skill would duplicate most of the spec discipline and add a routing seam for no real gain. The shape I'd want is a bounded front-step inside the skill: detect multi-capability scope, propose a module map plus dependency graph, get human approval, then recurse per module.

Where I'd push back is scope. The load-bearing core here is small and I want to keep it that way: detect oversized scope, propose the capability map and dependency direction before planning, and give each module a stable identity so downstream commands select an explicit path instead of guessing which spec is active. That core is a real gap worth filling. The full specs//modules tree with per-module SPEC, plan, and todo is where I'd be careful, it's a lot of machinery, and it needs to compose with the delta-spec direction in #383 rather than fight it (your open question 3). So: yes to the capability, but let's keep the first version to detection plus module map plus stable identity, and let the artifact layout follow #383 rather than lead it. Good writeup.