--- name: ac-workflow-product-manager description: "Decomposes large features into concrete development phases with DAG dependencies. Each phase produces fully functional code. Outputs YAML manifest. Triggers on keywords: decompose feature, phase planning, roadmap breakdown, feature phases, PM decomposition, split feature" project-agnostic: true allowed-tools: - Read - Write - Glob - Grep - Bash --- # Product Manager - Phase Decomposition Decomposes large features/bugs/chores into concrete, self-contained development phases. ## Core Principles 1. **Self-Contained Phases**: Each phase produces fully functional code (even if partial to overall goal) 2. **Incremental Value**: Every phase delivers testable, deployable value 3. **Clear Boundaries**: Phases have explicit inputs, outputs, and acceptance criteria 4. **DAG Dependencies**: Phases form a directed acyclic graph - parallel where possible ## Input Analysis When given a feature/prompt/spec: 1. **Read input thoroughly** - Understand full scope 2. **Identify atomic units** - Find smallest deployable pieces 3. **Map dependencies** - What must exist before what 4. **Group logically** - Combine related atoms into phases 5. **Validate DAG** - Ensure no circular dependencies ## Phase Decomposition Rules ### Phase Sizing - **Too small**: Single file change, trivial addition - **Just right**: 1-3 related components, clear acceptance criteria, testable - **Too large**: Multiple unrelated concerns, can't be tested independently ### Feature Complexity Assessment Assess overall feature complexity to guide phase count and downstream execution-modifier selection: | Feature Complexity | Typical Phases | Default Phase Modifier | |-------------------|----------------|------------------------| | Simple | 1-2 | lean or leanest | | Medium | 2-4 | lean or normal | | Complex | 4-8 | normal or full | | Very Complex | 8+ | full (critical phases) | ### Phase Independence Each phase MUST: - Have clear entry point (what exists before) - Produce working code (no broken intermediate states) - Be testable in isolation - Have explicit acceptance criteria ### Dependency Types - `hard`: Phase cannot start until dependency completes - `soft`: Phase benefits from dependency but can proceed with stubs ## Output Format ### Complexity to downstream execution mapping When generating `o_spec_config` for each phase, use this mapping as downstream execution metadata: | estimated_complexity | o_spec_config.modifier | o_spec_config.skip | |---------------------|------------------------|-------------------| | trivial | leanest | ["TEST", "DOCUMENT"] | | low | leanest | [] | | medium | lean | [] | | high | normal | [] | | critical | full | [] | The `o_spec_config.model` field is optional; leave null unless specific model override is needed for the phase. ### Phase Bundling Rules Bundling reduces orchestration overhead by combining related phases into single downstream spec-execution cycles. #### Complexity Scores (for bundle size limits) | estimated_complexity | score | bundleable | |---------------------|-------|------------| | trivial | 1 | yes | | low | 2 | yes | | medium | 3 | yes | | high | N/A | no (standalone) | | critical | N/A | no (standalone) | #### Bundling Criteria Phases CAN be bundled when ALL conditions are met: 1. **Complexity ceiling**: Only trivial, low, medium phases (high/critical stay standalone) 2. **DAG alignment**: Same `execution_order` batch (no cross-dependency bundling) 3. **Size limits**: Max 5 phases AND cumulative score <= 10 per bundle 4. **Semantic cohesion**: Related functionality (shared concern/component) #### Semantic Similarity Heuristics Cluster bundleable phases by: - **Title prefix**: Common prefix indicates shared concern (e.g., "Auth: models", "Auth: endpoints") - **Scope overlap**: Shared file paths or component names - **Description keywords**: API, database, UI, models as group markers #### Bundle Configuration Aggregation For bundled phases, compute aggregate `bundle_config`: - `modifier`: MAX(phase modifiers) - leanest < lean < normal < full - `skip`: INTERSECTION(phase skips) - if any phase needs a stage, bundle runs it - `model`: First non-null model, or null #### Bundling Algorithm ``` FOR each batch in execution_order: 1. Separate high/critical phases as standalone 2. FOR remaining trivial/low/medium phases: a. Cluster by semantic similarity (title prefix, scope overlap) b. FOR each cluster: - While cumulative_score <= 10 AND phase_count <= 5: add phase - Assign bundle_id to grouped phases 3. Generate bundle entries with aggregated config ``` Generate manifest at: `outputs/phases/{timestamp}-{feature-slug}/manifest.yml` ```yaml # Phase Manifest # Generated by product-manager skill meta: feature: "Feature title" description: "Brief description of overall goal" created_at: "ISO timestamp" total_phases: N estimated_complexity: "low|medium|high|very_high" phases: - id: "phase-1" title: "Short descriptive title" description: | What this phase accomplishes. Why it's a logical unit. scope: - "Specific deliverable 1" - "Specific deliverable 2" acceptance_criteria: - "Testable criterion 1" - "Testable criterion 2" dependencies: [] # or ["phase-id"] dependency_type: null # or "hard"|"soft" spec_prompt: | Inline prompt for downstream spec execution. Include specific technical requirements. o_spec_config: modifier: "lean" # full | normal | lean | leanest (derived from estimated_complexity) model: null # opus | sonnet | haiku (optional override) skip: [] # list of stages to skip, e.g., ["TEST", "DOCUMENT"] estimated_complexity: "trivial|low|medium|high|critical" bundle_id: null # Set by bundling algorithm; null = standalone execution - id: "phase-2" title: "..." dependencies: ["phase-1"] dependency_type: "hard" # ... rest of fields execution_order: # Computed from DAG - phases that can run in parallel grouped together - parallel: ["phase-1", "phase-3"] # No dependencies, run together - sequential: ["phase-2"] # Depends on phase-1 - parallel: ["phase-4", "phase-5"] # Both depend on phase-2 validation: dag_valid: true no_circular_deps: true all_phases_reachable: true bundles: # Generated by bundling algorithm - groups trivial/low/medium phases - bundle_id: "bundle-batch1-group1" phases: ["phase-1", "phase-2"] bundle_config: modifier: "lean" # MAX of bundled phase modifiers model: null skip: [] # INTERSECTION of bundled phase skips spec_title: "Auth models and basic utilities" spec_path: "specs/2025/12/feat/oauth/bundle-001-auth-models.md" cumulative_score: 4 # Sum of phase complexity scores - bundle_id: "bundle-batch2-group1" phases: ["phase-4", "phase-5"] bundle_config: modifier: "lean" model: null skip: [] spec_title: "Session and RBAC utilities" spec_path: "specs/2025/12/feat/oauth/bundle-002-session-rbac.md" cumulative_score: 5 ``` ## Decomposition Process ### Step 1: Scope Analysis ``` Read input -> Extract requirements -> Identify components -> List concerns ``` ### Step 2: Atomic Breakdown For each concern: - What's the minimum viable piece? - What can be tested independently? - What has clear boundaries? ### Step 3: Dependency Mapping ``` For each atomic unit: - What must exist before this works? - What does this enable? - Can this run in parallel with anything? ``` ### Step 4: Phase Grouping Combine atoms into phases when: - They share the same concern - They must change together (coupling) - Separate execution would be wasteful ### Step 5: DAG Validation ```python # Pseudocode for validation def validate_dag(phases): visited = set() in_progress = set() def has_cycle(phase_id): if phase_id in in_progress: return True # Cycle detected if phase_id in visited: return False in_progress.add(phase_id) for dep in phases[phase_id].dependencies: if has_cycle(dep): return True in_progress.remove(phase_id) visited.add(phase_id) return False for phase_id in phases: if has_cycle(phase_id): raise ValueError(f"Circular dependency detected: {phase_id}") ``` ### Step 6: Bundle Computation After DAG validation, compute phase bundles: ```python # Pseudocode for bundle computation COMPLEXITY_SCORES = {"trivial": 1, "low": 2, "medium": 3} MAX_BUNDLE_SCORE = 10 MAX_BUNDLE_SIZE = 5 def compute_bundles(phases, execution_order): bundles = [] for batch in execution_order: batch_phases = [p for p in phases if p.id in batch.phases] # Separate standalone (high/critical) from bundleable standalone = [p for p in batch_phases if p.estimated_complexity in ("high", "critical")] bundleable = [p for p in batch_phases if p.estimated_complexity not in ("high", "critical")] # Cluster bundleable by semantic similarity (title prefix, scope overlap) clusters = cluster_by_similarity(bundleable) for cluster in clusters: # Create bundles respecting size limits bundle = create_bundle_from_cluster(cluster, MAX_BUNDLE_SCORE, MAX_BUNDLE_SIZE) bundles.append(bundle) return bundles ``` ### Step 7: Execution Order Compute topological sort with parallelization: 1. Find all phases with no unmet dependencies 2. Group them as parallel batch 3. Mark as "scheduled" 4. Repeat until all scheduled ## Example Decomposition **Input**: "Add user authentication with OAuth2, session management, and role-based access control" **Output Phases**: 1. **phase-auth-models** (no deps) - User model, session model, role model - Database migrations - Acceptance: Models exist, migrations run 2. **phase-oauth-provider** (no deps, parallel with 1) - OAuth2 provider configuration - Token handling utilities - Acceptance: Can obtain tokens from provider 3. **phase-auth-flow** (deps: phase-auth-models, phase-oauth-provider) - Login/logout endpoints - Session creation/validation - Acceptance: User can authenticate 4. **phase-rbac** (deps: phase-auth-models) - Role assignment logic - Permission checking middleware - Acceptance: Roles restrict access 5. **phase-integration** (deps: phase-auth-flow, phase-rbac) - Wire authentication into existing routes - Add role requirements to protected endpoints - Acceptance: Full auth flow works E2E ## Usage Invoke when: - Feature requires multiple structured spec-execution cycles - Scope is unclear and needs breakdown - Dependencies between parts are complex - Parallel development is desired Output is consumed by downstream spec execution workflows.