Decomposition Planning and Roadmap workflow skill. Use this skill when the user needs Creates step-by-step decomposition plans and migration roadmaps for breaking apart monolithic applications. Use when asking "what order should I extract services?", "plan my migration", "create a decomposition roadmap", "prioritize what to split", "monolith to microservices strategy", or tracking decomposition progress. Do NOT use for domain analysis (use domain-analysis) or component sizing (use component-identification-sizing) and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
Decomposition Planning and Roadmap workflow skill. Use this skill when the user needs Creates step-by-step decomposition plans and migration roadmaps for breaking apart monolithic applications. Use when asking "what order should I extract services?", "plan my migration", "create a decomposition roadmap", "prioritize what to split", "monolith to microservices strategy", or tracking decomposition progress. Do NOT use for domain analysis (use domain-analysis) or component sizing (use component-identification-sizing) and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off.
This public intake copy packages packages/skills-catalog/skills/(architecture)/decomposition-planning-roadmap from https://github.com/tech-leads-club/agent-skills into the native Omni Skills editorial shape without hiding its origin.
Use it when the operator needs the upstream workflow, support files, and repository context to stay intact while the public validator and private enhancer continue their normal downstream flow.
This intake keeps the copied upstream files intact and uses the external_source block in metadata.json plus ORIGIN.md as the provenance anchor for review.
Decomposition Planning and Roadmap This skill creates structured decomposition plans and roadmaps to guide the migration from monolithic to distributed architectures, prioritizing work and tracking progress through decomposition patterns.
Imported source sections that did not map cleanly to the public headings are still preserved below or in the support files. Notable imported sections: How to Use, Core Concepts, Output Format, Current State Assessment, Phased Roadmap, Prioritized Work Plan.
When to Use This Skill
Use this section as the trigger filter. It should make the activation boundary explicit before the operator loads files, runs commands, or opens a pull request.
Starting a decomposition effort
Planning migration from monolith to distributed architecture
Prioritizing decomposition work
Creating architecture stories for decomposition
Tracking progress through decomposition patterns
Need structured approach to decomposition
Operating Table
Situation
Start here
Why it matters
First-time use
metadata.json
Confirms repository, branch, commit, and imported path through the external_source block before touching the copied workflow
Provenance review
ORIGIN.md
Gives reviewers a plain-language audit trail for the imported source
Workflow execution
QUICK-REFERENCE.md
Starts with the smallest copied file that materially changes execution
Supporting context
README.md
Adds the next most relevant copied source file without loading the entire package
Handoff decision
## Related Skills
Helps the operator switch to a stronger native skill when the task drifts
Workflow
This workflow is intentionally editorial and operational at the same time. It keeps the imported source useful to the operator while still satisfying the public intake standards that feed the downstream enhancer flow.
Check Component Inventory
Have components been identified and sized?
Is there a component inventory document?
Are oversized components identified?
Check Common Component Analysis
Have common domain components been identified?
Are consolidation opportunities documented?
Imported Workflow Notes
Imported: Analysis Process
Phase 1: Assess Current State
Analyze what's already been done:
Check Component Inventory
Have components been identified and sized?
Is there a component inventory document?
Are oversized components identified?
Check Common Component Analysis
Have common domain components been identified?
Are consolidation opportunities documented?
Has coupling impact been analyzed?
Check Component Structure
Have components been flattened?
Are there orphaned classes?
Is component structure clean?
Check Dependency Analysis
Have component dependencies been mapped?
Is coupling analysis complete?
Is feasibility assessed?
Check Domain Identification
Have domains been identified?
Are components grouped into domains?
Are namespaces aligned with domains?
Check Service Extraction
Have any services been extracted?
Are domain services created?
Is service-based architecture in place?
Output: Current state assessment showing what's done and what's remaining
Phase 2: Identify Patterns to Apply
Determine which decomposition patterns need to be applied:
Output: Prioritized list of patterns and work items
Phase 4: Create Phased Roadmap
Build a phased roadmap with milestones:
Define Phases
Phase 1: Analysis & Preparation
Phase 2: Domain Organization
Phase 3: Service Extraction
Phase 4: Optimization & Refinement
Assign Patterns to Phases
Which patterns belong in which phase?
What's the sequence within each phase?
What are the phase dependencies?
Set Milestones
What marks completion of each phase?
What are the success criteria?
What deliverables are expected?
Estimate Timeline
How long will each phase take?
What are the dependencies?
What's the critical path?
Output: Phased roadmap with timeline and milestones
Phase 5: Generate Architecture Stories
Create architecture stories for tracking work:
Create Story Template
As an architect, I need to [apply pattern/refactor component]
to support [architectural characteristic/business need]
so that [benefit/outcome]
Break Down Work
One story per pattern application
One story per major refactoring
One story per domain grouping
Add Acceptance Criteria
What defines "done"?
What metrics validate success?
What tests verify completion?
Estimate Effort
Story points or time estimates
Complexity assessment
Risk factors
Output: List of architecture stories with estimates
Phase 6: Track Progress
Monitor progress through decomposition:
Track Pattern Completion
Which patterns are complete?
Which are in progress?
Which are blocked?
Track Story Completion
Stories completed
Stories in progress
Stories not started
Track Metrics
Components identified
Components refactored
Domains created
Services extracted
Identify Blockers
What's blocking progress?
What dependencies are missing?
What risks have emerged?
Output: Progress dashboard and status report
Imported: Next Steps
After creating the roadmap:
Review with Stakeholders - Get buy-in on plan
Start Phase 1 - Begin with analysis patterns
Track Progress - Monitor completion and blockers
Adjust as Needed - Update roadmap based on learnings
Celebrate Milestones - Recognize progress
Imported: How to Use
Quick Start
Request creation of a decomposition plan:
"Create a decomposition roadmap for this codebase"
"Plan the decomposition migration strategy"
"Prioritize decomposition work based on component analysis"
"Create a step-by-step decomposition plan"
Usage Examples
Example 1: Complete Roadmap
User: "Create a decomposition roadmap for this codebase"
The skill will:
1. Analyze current codebase state
2. Identify decomposition patterns to apply
3. Prioritize work based on risk and value
4. Create phased roadmap
5. Generate architecture stories
6. Estimate effort and dependencies
Example 2: Prioritized Plan
User: "Prioritize decomposition work based on component analysis"
The skill will:
1. Review component inventory and dependencies
2. Assess risk and value for each pattern
3. Prioritize patterns by impact
4. Create prioritized work plan
Example 3: Phase Planning
User: "Create a phased decomposition plan"
The skill will:
1. Group decomposition patterns into phases
2. Identify dependencies between phases
3. Create phase timeline
4. Define phase success criteria
Step-by-Step Process
Assess Current State: Analyze codebase and identify what's been done
Identify Patterns: Determine which decomposition patterns to apply
Prioritize Work: Rank patterns by risk, value, and dependencies
Create Roadmap: Build phased plan with milestones
Generate Stories: Create architecture stories for tracking
Track Progress: Monitor progress through decomposition phases
Examples
Example 1: Ask for the upstream workflow directly
Use @decomposition-planning-roadmap to handle <task>. Start from the copied upstream workflow, load only the files that change the outcome, and keep provenance visible in the answer.
Explanation: This is the safest starting point when the operator needs the imported workflow, but not the entire repository.
Example 2: Ask for a provenance-grounded review
Review @decomposition-planning-roadmap against metadata.json and ORIGIN.md, then explain which copied upstream files you would load first and why.
Explanation: Use this before review or troubleshooting when you need a precise, auditable explanation of origin and file selection.
Example 3: Narrow the copied support files before execution
Use @decomposition-planning-roadmap for <task>. Load only the copied references, examples, or scripts that change the outcome, and name the files explicitly before proceeding.
Explanation: This keeps the skill aligned with progressive disclosure instead of loading the whole copied package by default.
Example 4: Build a reviewer packet
Review @decomposition-planning-roadmap using the copied upstream files plus provenance, then summarize any gaps before merge.
Explanation: This is useful when the PR is waiting for human review and you want a repeatable audit packet.
Best Practices
Treat the generated public skill as a reviewable packaging layer around the upstream repository. The goal is to keep provenance explicit and load only the copied source material that materially improves execution.
Start with analysis patterns (Patterns 1-4)
Prioritize low-risk, high-value work
Create architecture stories for tracking
Set clear milestones and success criteria
Track progress regularly
Adjust roadmap based on learnings
Collaborate with stakeholders on priorities
Imported Operating Notes
Imported: Best Practices
Do's ✅
Start with analysis patterns (Patterns 1-4)
Prioritize low-risk, high-value work
Create architecture stories for tracking
Set clear milestones and success criteria
Track progress regularly
Adjust roadmap based on learnings
Collaborate with stakeholders on priorities
Don'ts ❌
Don't skip analysis patterns
Don't start service extraction too early
Don't ignore dependencies between patterns
Don't create unrealistic timelines
Don't skip progress tracking
Don't forget to validate with stakeholders
Don't proceed without feasibility assessment
Troubleshooting
Problem: The operator skipped the imported context and answered too generically
Symptoms: The result ignores the upstream workflow in packages/skills-catalog/skills/(architecture)/decomposition-planning-roadmap, fails to mention provenance, or does not use any copied source files at all.
Solution: Re-open metadata.json, ORIGIN.md, and the most relevant copied upstream files. Check the external_source block first, then restate the provenance before continuing.
Problem: The imported workflow feels incomplete during review
Symptoms: Reviewers can see the generated SKILL.md, but they cannot quickly tell which references, examples, or scripts matter for the current task.
Solution: Point at the exact copied references, examples, scripts, or assets that justify the path you took. If the gap is still real, record it in the PR instead of hiding it.
Problem: The task drifted into a different specialization
Symptoms: The imported skill starts in the right place, but the work turns into debugging, architecture, design, security, or release orchestration that a native skill handles better.
Solution: Use the related skills section to hand off deliberately. Keep the imported provenance visible so the next skill inherits the right context instead of starting blind.
Related Skills
@accessibility - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-cold-outreach - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-pricing - Use when the work is better handled by that native specialization after this imported skill establishes context.
@ai-sdr - Use when the work is better handled by that native specialization after this imported skill establishes context.
Additional Resources
Use this support matrix and the linked files below as the operator packet for this imported skill. They should reflect real copied source material, not generic scaffolding.
Resource family
What it gives the reviewer
Example path
references
copied reference notes, guides, or background material from upstream
references/n/a
examples
worked examples or reusable prompts copied from upstream
examples/n/a
scripts
upstream helper scripts that change execution or validation
scripts/n/a
agents
routing or delegation notes that are genuinely part of the imported package
agents/n/a
assets
supporting assets or schemas copied from the source package
#### Imported: Prioritized Work Plan### High Priority (Do First)1.**Complete Component Flattening** (Priority: 9/10)
- Risk: Low
- Value: High (enables domain grouping)
- Dependencies: None
- Effort: 2 weeks
2.**Dependency Analysis** (Priority: 8/10)
- Risk: Low
- Value: High (validates feasibility)
- Dependencies: Component flattening
- Effort: 1 week
### Medium Priority (Do Next)3.**Domain Identification** (Priority: 7/10)
- Risk: Medium
- Value: High (enables service extraction)
- Dependencies: Dependency analysis
- Effort: 2 weeks
### Low Priority (Do Later)4.**Service Extraction** (Priority: 5/10)
- Risk: High
- Value: High (final goal)
- Dependencies: Domain identification
- Effort: 8 weeks
Architecture Stories
#### Imported: Architecture Stories### Story 1: Flatten Ticket Components**As an architect**, I need to flatten the Ticket component hierarchy
to support better component organization
so that components exist only as leaf nodes.
**Acceptance Criteria**:
- [ ] No orphaned classes in root namespaces
- [ ] All components are leaf nodes
- [ ] Component structure validated
**Estimate**: 5 story points
**Priority**: High
**Dependencies**: None
### Story 2: Identify Component Domains**As an architect**, I need to group components into logical domains
to support service-based architecture
so that components can be extracted to domain services.
**Acceptance Criteria**:
- [ ] All components assigned to domains
- [ ] Domain boundaries validated with stakeholders
- [ ] Domain map created
**Estimate**: 8 story points
**Priority**: High
**Dependencies**: Component flattening complete
High Value, Low Risk | High Value, High Risk
(Do First) | (Do Carefully)
────────────────────────┼──────────────────────
Low Value, Low Risk | Low Value, High Risk
(Do Later) | (Avoid/Defer)
Story Estimation
Use story points or time estimates:
Story Points (Fibonacci):
1: Trivial (few hours)
2: Simple (1 day)
3: Small (2-3 days)
5: Medium (1 week)
8: Large (2 weeks)
13: Very Large (3+ weeks)
Time Estimates:
Small: 1-3 days
Medium: 1-2 weeks
Large: 2-4 weeks
Very Large: 1+ month
Imported: Integration with Other Skills
This skill coordinates the use of other decomposition skills:
Component Identification & Sizing → Foundation for planning
Common Domain Component Detection → Identifies consolidation work
Component Flattening → Prepares for domain grouping
