project-split-decomposition
Use when an approved analiz spans more than one repository - split the work per repository and open one or more tasks per repository, each carrying its own plan slice
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- project-split-decomposition
- category
- architecture
- description
- Use when an approved analiz spans more than one repository - split the work per repository and open one or more tasks per repository, each carrying its own plan slice
03 SKILL.md 正文
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
- List the repositories the plan touches, by name from
list_repositories: backend-api, web, mobile, an automation/test repo, etc. Note whichproject(initiative, fromlist_projects) each belongs to, if any. - One or more implementation tasks per repository, never one task spanning two. They build, test, and deploy independently.
- Within a repository, split by layer only if independently deliverable, and by
componentwhen 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. - 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.
- 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) anddeploy_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". - 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. - Size and shared files. Default to one task per repository and layer for the whole feature — every extra task is another agent run, review, QA pass and release. ~400 changed lines including tests is where a reviewer still sees all of it inside the 24,000-byte diff cut; that is a comfortable size, not a reason to split. 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.mdor OpenAPI file, are not independent — chain them withblocked_byrather 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.
Worked Example
Approved analiz: "Users can export a project's tasks to CSV from web and mobile."
Split into three tasks:
| Task | Repository | Assignee | Ordering arguments | Scope slice |
|---|---|---|---|---|
| Add task export endpoint (T-1) | backend-api | backend-developer | derived_from: ["A-12"] |
GET /api/v1/projects/:id/tasks/export → CSV; plan slice with handler, service, test |
| Add export button to web board | web | frontend-developer | derived_from: ["A-12"], blocked_by: ["T-1"], deploy_depends_on: ["T-1"] |
Calls the endpoint, downloads the file; plan slice with component + api client |
| Add export action to mobile board | mobile | mobile-developer | derived_from: ["A-12"], blocked_by: ["T-1"], deploy_depends_on: ["T-1"] |
Same endpoint, native share sheet; plan slice with screen + api client |
A data or game slice follows the same rule: a churn model's training pipeline (data-scientist, in the analytics repository) and the endpoint that serves its score (backend-developer, in the API) are two tasks, the second blocked_by the first and consuming the model artifact's name and version from it.
The exact endpoint path and CSV column order are defined in the backend task and copied into both consumer tasks' plan slices. All three go to todo together with repository set on each (backend-api, web, mobile): the two consumers park themselves behind T-1 and are picked up automatically when it lands, and neither can be released ahead of it.
Common Mistakes
- One task titled "add export to web and mobile" — two repositories, must be two tasks.
- A consumer task that says "see the backend plan for the contract" — copy the contract in; the developer only sees their own task.
- Splitting a single-repo change across three tasks that can't be reviewed independently — over-decomposition.
- Mismatched field names between the producing and consuming task's plan slices.
- Leaving
repositoryunset and trusting the fallback — it lands in the active repository context or the default one, which is often wrong for a consumer task.
Red Flags
- A consumer task with no
blocked_by/deploy_depends_onon its producer → the order exists only in your head, and the frontend can start (and ship) before the API it calls. - A task with no
derived_from→ the developer cannot reach the plan slice you wrote for them. - A created task whose
repositorydiffers from its row in thesplittable. - A task's plan slice references files in a repository the task doesn't own.
- Two tasks would edit the same repository's same files → they are really one task, or
blocked_byif they must stay separate. - The interface shape differs between the producer and consumer tasks.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns