Project Split Decomposition

Project Split Decomposition

Overview

Real features cross repository boundaries: an API in the backend repo, a screen in the web repo, a screen in the mobile repo. After the human approves the analysis, you split the work along repository lines and open one or more implementation tasks per repository, never one task spanning two, each carrying the slice of the plan that repository needs. A developer working the web task should never have to read the backend repo's plan to do their job.

Core principle: One repository (and, in a monorepo, one component), one self-contained plan slice per task. The split follows the deployable unit, not the feature.

REQUIRED SUB-SKILL: task-decomposition (per-task structure, AC, assignees). This skill decides the BOUNDARIES; task-decomposition fills each task in.

When to Use

Use after the human approves an analiz (see analiz-human-review-gate) whenever the plan touches more than one repository. A single-repository change skips straight to task-decomposition.

How to Split

1. List the repositories the plan touches, by name from list_repositories: backend-api, web, mobile, an automation/test repo, etc. Note which project (initiative, from list_projects) each belongs to, if any.
2. One or more implementation tasks per repository, never one task spanning two. They build, test, and deploy independently.
3. Within a repository, split by layer only if independently deliverable, and by component when it is a monorepo. A backend task may cover the whole vertical slice for that repo; split further only where a reviewer could accept one part and reject another.
4. Write each repository's plan slice into its task. Copy the relevant plan sections, file paths, and the Interfaces blocks that task consumes/produces — verbatim, not "see the main plan." The task is self-contained.
5. Order by cross-repository dependency, in the arguments. The repository that produces an interface goes before the repository that consumes it. On the consuming task set blocked_by: ["<producer key>"] (nobody starts it until the producer is done) and deploy_depends_on: ["<producer key>"] (it may not be released until the producer is live). Both are enforced — a prose "depends on the backend task" is not. See task-decomposition, "Ordering Is an Argument, Not a Sentence".
6. Point every task back at the analysis. derived_from: ["A-N"] on each one. The spec and the plan live as documents on that analiz task, so this is the only route each developer has to them.
7. Size and shared files. A task should land at an estimated ≤ ~400 changed lines including tests, so a reviewer sees all of it inside the 24,000-byte diff cut; over ~1,000 is a split, and refactors are separate from feature work. Two tasks in the same repository that both add a migration (sequence numbers collide), or edit the same router table, locale bundle, DI container, INVENTORY.md or OpenAPI file, are not independent — chain them with blocked_by rather than leaving the collision to be discovered at review time.

The Cross-Repository Contract

The one thing that MUST be identical across the split is the interface between repositories — the API contract. Define it once in the producing task and copy the exact request/response shape into the consuming task's plan slice. A field named taskId in the backend task but task_id in the web task is a guaranteed integration bug.

Schema Tasks

A repository task that adds or changes a migration carries before_deploy (what must be true before this ships — e.g. "migration N applied on stage") and rollback_plan (a code rollback is a git revert; it does not undo the schema, so state what the schema looks like afterward and that the previous release's code must still run against it). A breaking schema change (a drop or rename still read by deployed code) is a separate, later task with deploy_depends_on every consumer update — see migration-and-contract-review.