product-apps-decomposition
Skill9 starsChanged 27 days agoMITView on GitHub
Use when planning how to structure a product — deciding whether to build one large app or several focused apps. Gives generic decomposition guidance always (reliability + token economy), and steers to the specific app breakdown when docs/<app>/product.md defines one. Do NOT use for single-file edits or for app-internal component structure.
In this repository119 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/fusebase-flow-always.mdcCursor rule
- .cursor/rules/fusebase-flow-implementation.mdcCursor rule
- .cursor/rules/fusebase-flow-security.mdcCursor rule
- .cursor/rules/fusebase-flow-specs.mdcCursor rule
- .cursor/rules/fusebase-flow-validation.mdcCursor rule
- api-explorationSkill
- app-api-contract-testingSkill
- app-backendSkill
- app-business-docsSkill
- app-dev-practicesSkill
- app-e2e-testsSkill
- app-quality-patternsSkill
- app-routingSkill
- app-secretsSkill
- app-sidecarSkill
- app-ui-designSkill
- business-logic-guardianSkill
- client-vs-internalSkill
- code-reviewSkill
- comment-policySkill
- communicationSkill
- design-discovery-ideationSkill
- dev-debug-logsSkill
- documentation-budgetSkill
- file-uploadSkill
- find-wasted-codeSkill
- find-wasted-effortSkill
- fusebase-cliSkill
- fusebase-dashboardsSkill
- fusebase-flow-health-checkSkill
- fusebase-gateSkill
- fusebase-portal-specific-appsSkill
- git-history-diagnosticSkill
- git-workflowSkill
- handling-authentication-errorsSkill
- handoffSkill
- implementation-planningSkill
- invite-with-passwordSkill
- lightweight-laneSkill
- liveness-disciplineSkill
- managed-integrationsSkill
- mcp-gate-debugSkill
- module-size-disciplineSkill
- north-starSkill
- phase-auditSkill
- product-docs-firstSkill
- product-ownerSkill
- project-onboardingSkill
- release-deploy-reportingSkill
- remote-logsSkill
- repo-onboarding-context-mapSkill
- requirements-specificationSkill
- role-disciplineSkill
- security-permissions-reviewSkill
- skill-authoringSkill
- smoke-testingSkill
- task-delegationSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 106
Do not invent a specific app breakdown when product.md has none — give generic guidance.
- Distinctive: line 107
Do not over-split into unmaintainable micro-apps.
- Distinctive: line 108
Do not apply this to app-internal component structure.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Product → Apps Decomposition
Style: Mode-B-lite. Generic guidance always; steers to the product breakdown when
docs/<app>/product.mddefines one (generic-with-enhancement, not pure no-op — E3).
Purpose
Encode the "a product is composed of focused apps" model: breaking a product into smaller, focused apps (vs one monolith) improves reliability (one app's failure can't sink the rest) and token economy (the LLM loads only the relevant app's context). Apps talk via internal API; complexity per app stays low.
When to invoke
- Planning a new product/app and deciding scope/structure.
- Operator says "should this be one app or several", "how do I split this product".
docs/<app>/product.mdexists with an apps breakdown (steer to it).
Do not invoke when
- Single-file edits / bug fixes.
- App-internal component/folder structure (that's implementation detail, not product decomposition).
Required inputs
| Input | Where it lives | If missing |
| Product breakdown (optional) | docs/<app>/product.md | give generic guidance; do not invent a breakdown |
| Reliability/scale needs | operator / North Star | ask if scope-critical (FR-19) |
Procedure
- If
docs/<app>/product.mddefines an apps breakdown → read and steer to it. Otherwise give generic guidance (do not fabricate a specific breakdown). - Score the boundary with § Split decision below — signals vs costs, both columns honestly; the worked CRM example shows the shape of a defensible verdict.
- Keep apps focused: each app = one coherent job; apps integrate via internal API / webhooks. Every planned cross-app call edge is a
callAppApicontract to author and keep green (CLI skillapp-api-contract-testing). - Recommend boundaries with rationale (reliability, token economy, independent deploy) — and the explicit call-edge list.
- Record the breakdown. A decided decomposition goes into
docs/<app>/product.md§ apps breakdown (authored viaproduct-docs-first,templates/product.md): per app — one-line job, owned data, planned call edges. Later sessions steer to it (step 1) instead of re-deciding. Do not leave a locked breakdown chat-only. - Hand to planning (
implementation-planning) per app. - Ambiguity → ask operator (FR-19).
Split decision (signals vs costs)
| Split signals (favor separate apps) | Concretely |
| Distinct data ownership | Each app owns its dashboards/stores; peers read via API, never write the other's data directly |
| Independent deploy cadence | One area ships weekly, the other is stable — separate apps deploy without re-verifying the other |
| Failure blast radius | A crash or bad deploy in one area must not take down the other (client-facing portal vs internal admin is the classic cut) |
| Per-app context size | Combined codebase would bloat the LLM window; per-app context stays small enough for reliable edits (token economy) |
| Split costs (favor one app) | Concretely |
| Cross-app API + contract maintenance | Every runtime call between apps is AppApisApi.callAppApi(...) and needs a consumer contract kept green (CLI skill app-api-contract-testing); each call edge is permanent maintenance |
| Per-app auth/permission/embed overhead | Each app separately configures permissions, portal embedding, public access |
| Per-app deploy/ops overhead | Separate builds, deploys, smoke runs, and remote-log surfaces per app |
| Chatty boundary | If the areas constantly need each other's data inside one interaction, the network seam adds latency + failure modes a single app doesn't have |
Rules of thumb: ≥2 signals and ≤2–3 planned call edges → split. 0–1 signals, or a chatty seam → one app. Undecidable → ask the operator (FR-19).
Worked example — client CRM product
Candidate areas: pipeline board (internal sales), client portal (clients see their own deals/documents), reporting.
| Boundary | Signals | Costs | Verdict |
| Portal vs pipeline | Data ownership (portal reads deals, never writes); blast radius (client surface must survive internal-tool breakage); independent cadence | 1 call edge (client-portal → crm-pipeline: getClientDeals) + 1 contract | Split — crm-pipeline + client-portal |
| Reporting vs pipeline | Same data, same cadence, no blast-radius concern | Would add 3+ chatty aggregate-query edges | Keep inside crm-pipeline as a view |
Result: 2 apps, 1 contract, recorded in docs/crm/product.md § apps breakdown (step 5).
Output artifacts
| Artifact | Location | Mode |
| Decomposition recommendation | chat / product doc | Mode A / Mode-B-lite |
| Recorded apps breakdown (job + owned data + call edges per app) | docs/<app>/product.md via product-docs-first | Mode B |
Failure cases
| Failure | Detection | Response |
| Over-splitting (too many tiny apps) | step 2 | consolidate; split has a cost too |
| Monolith pressure | step 2 | flag reliability/token risk; recommend split |
Escalation path
- Cross-app architecture concern →
workflows/architect-escalation.md. - Product intent unclear →
product-docs-first/ ask operator. - New cross-app call edge decided → author the consumer contract via the
app-api-contract-testingCLI skill before the edge ships.
Anti-patterns
- Do not invent a specific app breakdown when
product.mdhas none — give generic guidance. - Do not over-split into unmaintainable micro-apps.
- Do not apply this to app-internal component structure.
Clean-room note
Original Fusebase Flow content. See docs/source-map.md. No third-party code, prompts, or skill files copied.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.