[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M71C6ZY1EGM4SGVYT4B2HHD7":3,"skill-same:01M71C6ZY1EGM4SGVYT4B2HHD7":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":23,"linkOnly":24,"markdownContent":25,"markdownBody":26,"frontMatter":27,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":14,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":6,"ownerDescription":33,"updatedAt":34,"install":35,"resources":48},"01M71C6ZY1EGM4SGVYT4B2HHD7","implementation-planning",null,"Generates detailed implementation plans from finalized designs","yqecea\u002Fgem-swarm","yqecea","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F196189405?v=4","01M71C12KWH5QPTE12J69335KF","Yusuf","01M71C12MFS3BRGNE5SSHB4DY9",1,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fimplementation-planning\u002FSKILL.md",[],[19,20,21,22],"planning","implementation","implementation planning","plans","2026-11-10 10:12:30",false,"---\nname: implementation-planning\ndescription: Generates detailed implementation plans from finalized designs\n---\n\n# Implementation Planning Skill\n\n**Standard workflow only.** If `task_complexity` is `simple` and workflow mode is Express, do not activate this skill. Simple tasks use the Express workflow, which does not activate implementation-planning. Return to the Express Workflow section.\n\nActivate this skill during Phase 2 of Maestro orchestration, after the design document has been approved. This skill provides the methodology for generating detailed, actionable implementation plans that map directly to subagent assignments.\n\n## Codebase Grounding\n\nDo not generate an implementation plan from guesses about the repository.\n\nUse the built-in `codebase_investigator` before phase decomposition when:\n- The task modifies an existing codebase\n- File ownership, integration points, or validation commands are still unclear after reading the approved design\n- Parallelization decisions depend on understanding current module boundaries or likely file overlap\n\nAsk the investigator for:\n- The modules and files most likely to change\n- Existing architectural boundaries and conventions the plan must preserve\n- Integration seams, dependencies, and shared ownership hotspots\n- Validation commands and test entry points already used by the project\n- Parallelization or conflict risks that should prevent batching\n\nSkip the investigator only for greenfield tasks, documentation-only work, or plans where the current turn already established the relevant repo structure from direct reads.\n\nReuse investigator findings directly in the implementation plan:\n- File inventories should reflect real candidate paths, not placeholders\n- Validation criteria should prefer repo-native commands the investigator surfaced\n- Parallel batches should account for actual ownership overlap and conflict risk\n\n## Plan Generation Methodology\n\n### Input Analysis\nBefore generating the plan, thoroughly analyze the approved design document for:\n- Read `task_complexity` from the approved design document's frontmatter. Apply phase count guidance and domain analysis scaling accordingly. Record `task_complexity` in implementation plan frontmatter.\n- Components and their responsibilities\n- Interfaces and contracts between components\n- Data models and their relationships\n- External dependencies and integrations\n- Technology stack decisions\n- Quality requirements that influence implementation order\n\n### Phase Decomposition\n\nBreak the implementation into phases following these principles:\n\n1. **Foundation First**: Infrastructure, configuration, and shared types\u002Finterfaces come first\n2. **Dependencies Flow Downward**: A phase can only depend on phases with lower IDs\n3. **Single Responsibility**: Each phase delivers a cohesive unit of functionality\n4. **Agent Alignment**: Each phase maps to an agent specialization. The SAME agent MAY appear in multiple parallel phases when the task decomposes into independent sub-deliverables within one domain (see Same-Agent Decomposition below)\n5. **Agent Capability Match**: Verify the assigned agent's tool tier supports the phase deliverables (see compatibility check below)\n6. **Testability**: Each phase should be independently validatable\n\n### Phase Ordering Strategy\n\n```\nLayer 1: Foundation (types, interfaces, configuration)\n    |\nLayer 2: Core Domain (business logic, data models)\n    |\nLayer 3: Infrastructure (database, external services, API layer)\n    |\nLayer 4: Integration (connecting components, middleware)\n    |\nLayer 5: Quality (testing, security review, performance)\n    |\nLayer 6: Documentation & Polish\n```\n\n### Agent-Deliverable Compatibility Check\n\nBefore finalizing agent assignments, verify each phase's agent can deliver its requirements:\n\n| Phase Deliverable | Required Tier | Compatible Agents |\n|-------------------|--------------|-------------------|\n| Creates\u002Fmodifies files | Full Access or Read+Write | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, technical-writer, product-manager, ux-designer, copywriter |\n| Runs shell commands | Full Access or Read+Shell | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist |\n| Analysis\u002Freview only | Any tier | All agents |\n\n\u003CHARD-GATE>\nRead-Only agents (architect, api-designer, code-reviewer, content-strategist, compliance-reviewer)\nCANNOT be assigned to phases that create or modify files. If a phase requires file creation\nand domain expertise from a Read-Only agent, split it: the Read-Only agent produces a spec\nor analysis, then a write-capable agent (typically coder) implements the files based on that output.\n\u003C\u002FHARD-GATE>\n\n### Phase Count Guidance\n\nScale decomposition granularity to `task_complexity` (read from design document frontmatter):\n- **simple**: 1-3 phases. Prefer single-phase execution when feasible. Combine foundation + implementation. Skip separate documentation\u002Fpolish phases.\n- **medium**: 3-5 phases. Use the layer model but combine Quality and Documentation into the final implementation phase where practical.\n- **complex**: No phase count cap. Full layer decomposition strategy applies.\n\n### Parallelization Identification\n\nPhases can run in parallel when:\n- They have no shared file dependencies (no overlapping files_created or files_modified)\n- They are at the same dependency depth (same layer)\n- They do not share data model ownership\n- Their validation can run independently\n\nMark parallel-eligible phases with `parallel: true` and group them into execution batches.\n\n### Same-Agent Parallel Decomposition\n\nWhen 70%+ of the work maps to a single agent specialization, decompose by **deliverable** — not by agent type. The orchestrator MUST auto-detect this condition and apply it without user configuration.\n\n**Ultrawork Override**: When `ultrawork: true` is set in session state, the 70% threshold drops to **40%**. Decompose by deliverable whenever 2+ independent file sets exist within a single agent's scope, regardless of what percentage of total work that agent handles. Allow up to **8 parallel instances** of the same agent (standard mode caps at 4).\n\n#### Trigger Conditions (auto-detected by planner)\n- The task is primarily one domain (e.g., \"build a landing page\" = all frontend)\n- The deliverables split into 2-4 independent units with non-overlapping files (Ultrawork: 2-8 units)\n- Each unit is self-contained enough for the agent to complete without the other units\n\n#### Decomposition Strategies\n\n| Strategy | Example | When to Use |\n|----------|---------|-------------|\n| **By section** | Header+Nav, Hero+CTA, Features, Footer+Contact | Landing pages, multi-section layouts |\n| **By feature** | Auth UI, Dashboard, Settings page | Feature-rich apps |\n| **By concern** | Layout+Structure, Styling+Animations, Responsive+A11y | When sections share too many files |\n\n#### File Ownership Contract\nEach parallel instance of the same agent MUST own non-overlapping files:\n- Instance A: `components\u002FHeader.tsx`, `components\u002FNav.tsx`\n- Instance B: `components\u002FHero.tsx`, `components\u002FFeatures.tsx`\n- Instance C: `components\u002FFooter.tsx`, `components\u002FContact.tsx`\n\nShared files (e.g., `globals.css`, `layout.tsx`, `page.tsx`) go to a **post-batch integration phase** — a single agent that stitches the parallel outputs together.\n\n#### Post-Batch Integration Phase\nAfter parallel same-agent phases complete, always add a lightweight integration phase:\n- **Agent**: same specialist (e.g., `frontend_specialist`)\n- **Task**: import all parallel outputs, wire into shared layout, resolve conflicts\n- **Depends on**: ALL parallel phases\n- **Files**: only shared\u002Fbarrel files (layout, page, globals)\n\n### Automatic Quality Review Pipeline\n\nFor any task that produces user-facing output (UI, landing page, app), the planner MUST append a review layer AFTER the build phases complete. This is automatic — the user does not request it.\n\n#### When to Append (auto-detected)\n- The task involves `frontend_specialist`, `mobile_developer`, or `game_developer`\n- The build phase(s) create or modify 3+ files\n- The task complexity is `medium` or `complex`\n\n#### Review Pipeline Structure\n\n```\nBuild Phase(s) → Integration (if parallel) → Review Batch (parallel) → Fix Phase\n```\n\n**Review Batch**: 2-3 parallel instances of the SAME implementing agent, each reviewing ONE quality dimension:\n\n| Review Instance | Focus | What to Check |\n|----------------|-------|---------------|\n| Responsive Review | Layout at 375px, 768px, 1024px, 1440px | Breakpoints, overflow, touch targets, safe areas |\n| Design Compliance | Style adherence | Does output match the chosen taste style? Anti-slop check, animation quality |\n| Accessibility + Performance | A11y + Core Web Vitals | ARIA, keyboard nav, contrast, image optimization, bundle size |\n\nEach review instance produces a structured findings report (Critical\u002FMajor\u002FMinor). The findings feed into a single **Fix Phase** where the implementing agent addresses Critical and Major issues.\n\n#### Review Phase Template\n```\nAgent: [same as build agent]\nPhase: [N]\u002F[total]\nTask: REVIEW ONLY — do NOT modify files\nFocus: [Responsive \u002F Design Compliance \u002F Accessibility + Performance]\n\nReview the following files created in previous phases:\n[file list from build phases]\n\nProduce a findings report with:\n- Severity: Critical \u002F Major \u002F Minor\n- File + line number\n- What's wrong\n- Suggested fix\n\nDo NOT write code. Report findings only.\n```\n\n#### Fix Phase Template\n```\nAgent: [same as build agent]\nPhase: [N]\u002F[total]\nTask: Fix Critical and Major findings from review batch\n\n[Aggregated findings from all review instances]\n\nFix each finding. Skip Minor unless trivial.\n```\n\n## Implementation Detail Requirements\n\n### Per-Phase Specification\n\nEach phase in the plan must include:\n\n#### Objective\nA clear, measurable statement of what this phase delivers.\n\n#### Agent Assignment\nWhich agent(s) execute this phase, with rationale for selection.\n\n#### Files to Create\nFor each new file:\n- Full relative path from project root\n- Purpose and responsibility\n- Key interfaces, classes, or functions to define\n- Complete type signatures for public APIs\n\n#### Files to Modify\nFor each existing file:\n- Full relative path from project root\n- Specific changes required and why\n- Expected before\u002Fafter for critical sections\n\n#### Implementation Details\n\nProvide sufficient detail for the assigned agent to execute without ambiguity:\n- Interface definitions with complete type signatures\n- Base class contracts with abstract method signatures\n- Dependency injection patterns and registration points\n- Error handling strategy (error types, propagation, recovery)\n- Configuration requirements (environment variables, config files)\n\n#### Validation Criteria\nSpecific commands to run and expected outcomes:\n- Build\u002Fcompile commands\n- Lint\u002Fformat checks\n- Unit test commands\n- Integration test commands (if applicable)\n- Manual verification steps (if applicable)\n\n#### Dependencies\n- `blocked_by`: Phase IDs that must complete before this phase starts\n- `blocks`: Phase IDs that cannot start until this phase completes\n\n### Dependency Minimization\n\nList only **direct** blockers in `blocked_by`. Do not include transitive dependencies — they inflate dependency depth and prevent parallelism.\n\nAnti-pattern (over-specified):\n- Phase 2: blocked_by: [1]\n- Phase 3: blocked_by: [1, 2] — Phase 1 is redundant, already reachable via Phase 2\n- Phase 4: blocked_by: [1, 2, 3] — Phases 1, 2 are redundant\n\nResult: depths 0, 1, 2, 3 — zero parallel phases.\n\nCorrect (minimized):\n- Phase 2: blocked_by: [1]\n- Phase 3: blocked_by: [1] — Only needs Phase 1 output, not Phase 2\n- Phase 4: blocked_by: [2, 3] — Needs both done\n\nResult: depths 0, 1, 2 — Phases 2 and 3 run in parallel at depth 1.\n\nAsk for each dependency: \"Does this phase truly need the output of that specific phase, or is it transitively covered?\"\n\nIf `validate_plan` is available, review its `parallelization_profile` and `redundant_dependency` warnings before presenting the plan. Revise `blocked_by` to eliminate redundancies when possible.\n\n## Agent Assignment Criteria\n\n### Matching Tasks to Agents\n\n| Task Domain | Primary Agent | Secondary Agent | Rationale |\n|-------------|--------------|-----------------|-----------|\n| System design, architecture | `architect` | - | Read-only analysis, design expertise |\n| API contracts, endpoints | `api-designer` | `coder` | Design then implement |\n| Feature implementation | `coder` | - | Full implementation access |\n| Code quality review | `code-reviewer` | - | Read-only verification |\n| Database schema, queries | `data-engineer` | - | Schema + implementation |\n| Bug investigation | `debugger` | - | Read + shell for investigation |\n| CI\u002FCD, infrastructure | `devops-engineer` | - | Full DevOps access |\n| Performance analysis | `performance-engineer` | - | Read + shell for profiling |\n| Code restructuring | `refactor` | - | Write + shell access (for validation) |\n| Security assessment | `security-engineer` | - | Read + shell for scanning |\n| Test creation | `tester` | - | Full test implementation |\n| Documentation | `technical-writer` | - | Write access for docs |\n| Technical SEO audit | `seo-specialist` | - | Read + shell + web search |\n| Marketing copy, content | `copywriter` | - | Read\u002Fwrite |\n| Content planning | `content-strategist` | - | Read + web search\u002Ffetch |\n| UX design, user flows | `ux-designer` | - | Read\u002Fwrite + web search |\n| WCAG compliance audit | `accessibility-specialist` | - | Read + shell + web search |\n| Requirements, product | `product-manager` | - | Read\u002Fwrite + web search |\n| Tracking, analytics | `analytics-engineer` | `coder` | Implement then instrument |\n| Internationalization | `i18n-specialist` | `coder` | Implement then localize |\n| Design tokens, theming | `design-system-engineer` | `coder` | Tokens then consume |\n| Legal, regulatory | `compliance-reviewer` | - | Read + web search\u002Ffetch |\n\n### Assignment Rules\n1. Match the primary task domain to the agent specialization\n2. Consider tool requirements — does the task need shell access? Write access?\n3. For parallel phases, assign non-overlapping file ownership to each agent\n4. Prefer focused single-deliverable phases. The same agent MAY run in multiple parallel phases with distinct file ownership (see Same-Agent Decomposition)\n5. Never assign more files to an agent than it can handle within its `max_turns` limit\n6. For UI\u002Ffrontend tasks, always append the Automatic Quality Review Pipeline after build phases\n\n### Token Budget Estimation\nEstimate token consumption per phase based on:\n- Number of files to read (input tokens)\n- Complexity of output expected (output tokens)\n- Agent's max_turns limit as upper bound\n- Historical averages: ~500 input tokens per file read, ~200 output tokens per file written\n\n### Cost Estimation\n\n#### Per-Phase Cost Factors\n- **Model tier**: Pro agents (~$0.01\u002F1K input, ~$0.04\u002F1K output) vs Flash agents (~$0.001\u002F1K input, ~$0.004\u002F1K output)\n- **Input complexity**: Number of files read, average file size, context from previous phases\n- **Output complexity**: Lines of code generated, number of files created\u002Fmodified\n- **Retry budget**: Add 50% buffer per phase for potential retries (max 2 retries)\n\n#### Estimation Formula\n```\nPhase Cost = (input_tokens × input_rate + output_tokens × output_rate) × retry_multiplier\n```\n\nWhere:\n- `input_tokens` = files_to_read × 500 + context_tokens\n- `output_tokens` = files_to_write × 200 + validation_output\n- `retry_multiplier` = 1.5 (accounts for up to 2 retries)\n\n#### Plan-Level Cost Summary\nInclude this table in every implementation plan:\n\n| Phase | Agent | Model | Est. Input | Est. Output | Est. Cost |\n|-------|-------|-------|-----------|------------|----------|\n| 1 | [agent] | [model] | [tokens] | [tokens] | [$X.XX] |\n| ... | ... | ... | ... | ... | ... |\n| **Total** | | | **[sum]** | **[sum]** | **[$X.XX]** |\n\n## Plan Document Generation\n\n### Output Location\n\nThe write path depends on whether your runtime provides a Plan Mode surface (check `get_runtime_context`, loaded at session start, step 0).\n\n- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the plan there first, then copy to the permanent location after approval. Call `exit_plan_mode` with the plan path to present the plan for user approval.\n- **Plan Mode not active or not available**: Write the implementation plan directly to the project's plans directory.\n\nPermanent location: `\u003Cstate_dir>\u002Fplans\u002FYYYY-MM-DD-\u003Ctopic-slug>-impl-plan.md` (where `\u003Cstate_dir>` resolves from `GEM_SWARM_STATE_DIR`, default `docs\u002Fmaestro`).\n\nIf your runtime does not provide a Plan Mode transition, track planning progress using the plan-update mechanism from your runtime context, write directly to the final location, and use the user-prompt tool from runtime context for the approval gate.\n\n### Document Structure\nUse the `implementation-plan` template loaded via `get_skill_content`.\n\n### Required Sections\n\n1. **Plan Overview**: Summary of total phases, agents involved, estimated effort\n2. **Dependency Graph**: Visual representation showing phase dependencies and parallel opportunities\n3. **Execution Strategy Table**: Stage-by-stage breakdown with agent assignments and execution mode\n4. **Phase Details**: Full specification for each phase (objective, agent, files, details, validation, dependencies)\n5. **File Inventory**: Complete table mapping every file to its phase and purpose\n6. **Risk Classification**: Per-phase risk assessment (LOW\u002FMEDIUM\u002FHIGH) with rationale\n7. **Execution Profile**: Summary of parallel vs sequential characteristics to inform mode selection:\n   ```\n   Execution Profile:\n   - Total phases: [N]\n   - Parallelizable phases: [M] (in [B] batches)\n   - Sequential-only phases: [S]\n   - Estimated parallel wall time: [time estimate based on batch execution]\n   - Estimated sequential wall time: [time estimate based on serial execution]\n\n   Note: Native parallel execution currently runs agents in autonomous mode.\n   All tool calls are auto-approved without user confirmation.\n   ```\n\n### Completion Criteria\nThe implementation plan is complete when:\n- Every component from the design document maps to at least one phase\n- All phase dependencies are acyclic (no circular dependencies)\n- Parallel opportunities are identified and marked\n- Each phase has clear validation criteria\n- File ownership is non-overlapping for parallel phases\n- The user has given explicit approval of the complete plan\n\nBefore presenting the plan for approval, check whether `validate_plan` appears in your available tools. If it does, call it with the plan structure and `task_complexity` to verify phase count constraints, file ownership, acyclic dependencies, and agent validity. If it does not, self-check against the phase count limits above.\n\n### Post-Generation\nAfter writing the implementation plan:\n1. Confirm the file path to the user\n2. Present the dependency graph and execution strategy\n3. Highlight parallel execution opportunities\n4. Provide token budget estimates\n5. If your runtime provides Plan Mode, call `exit_plan_mode` with the plan path to present the plan for user approval. If Plan Mode is not available, present the completed plan for user approval using the user-prompt tool from runtime context.\n6. Ensure the approved plan is at `\u003Cstate_dir>\u002Fplans\u002FYYYY-MM-DD-\u003Cslug>-impl-plan.md` as the permanent project reference (copy from the staging directory if Plan Mode was used)\n7. Ask if the user is ready to proceed to execution (Phase 3)\n8. Upon approval, create the session state file via the session-management skill\n","# Implementation Planning Skill\n\n**Standard workflow only.** If `task_complexity` is `simple` and workflow mode is Express, do not activate this skill. Simple tasks use the Express workflow, which does not activate implementation-planning. Return to the Express Workflow section.\n\nActivate this skill during Phase 2 of Maestro orchestration, after the design document has been approved. This skill provides the methodology for generating detailed, actionable implementation plans that map directly to subagent assignments.\n\n## Codebase Grounding\n\nDo not generate an implementation plan from guesses about the repository.\n\nUse the built-in `codebase_investigator` before phase decomposition when:\n- The task modifies an existing codebase\n- File ownership, integration points, or validation commands are still unclear after reading the approved design\n- Parallelization decisions depend on understanding current module boundaries or likely file overlap\n\nAsk the investigator for:\n- The modules and files most likely to change\n- Existing architectural boundaries and conventions the plan must preserve\n- Integration seams, dependencies, and shared ownership hotspots\n- Validation commands and test entry points already used by the project\n- Parallelization or conflict risks that should prevent batching\n\nSkip the investigator only for greenfield tasks, documentation-only work, or plans where the current turn already established the relevant repo structure from direct reads.\n\nReuse investigator findings directly in the implementation plan:\n- File inventories should reflect real candidate paths, not placeholders\n- Validation criteria should prefer repo-native commands the investigator surfaced\n- Parallel batches should account for actual ownership overlap and conflict risk\n\n## Plan Generation Methodology\n\n### Input Analysis\nBefore generating the plan, thoroughly analyze the approved design document for:\n- Read `task_complexity` from the approved design document's frontmatter. Apply phase count guidance and domain analysis scaling accordingly. Record `task_complexity` in implementation plan frontmatter.\n- Components and their responsibilities\n- Interfaces and contracts between components\n- Data models and their relationships\n- External dependencies and integrations\n- Technology stack decisions\n- Quality requirements that influence implementation order\n\n### Phase Decomposition\n\nBreak the implementation into phases following these principles:\n\n1. **Foundation First**: Infrastructure, configuration, and shared types\u002Finterfaces come first\n2. **Dependencies Flow Downward**: A phase can only depend on phases with lower IDs\n3. **Single Responsibility**: Each phase delivers a cohesive unit of functionality\n4. **Agent Alignment**: Each phase maps to an agent specialization. The SAME agent MAY appear in multiple parallel phases when the task decomposes into independent sub-deliverables within one domain (see Same-Agent Decomposition below)\n5. **Agent Capability Match**: Verify the assigned agent's tool tier supports the phase deliverables (see compatibility check below)\n6. **Testability**: Each phase should be independently validatable\n\n### Phase Ordering Strategy\n\n```\nLayer 1: Foundation (types, interfaces, configuration)\n    |\nLayer 2: Core Domain (business logic, data models)\n    |\nLayer 3: Infrastructure (database, external services, API layer)\n    |\nLayer 4: Integration (connecting components, middleware)\n    |\nLayer 5: Quality (testing, security review, performance)\n    |\nLayer 6: Documentation & Polish\n```\n\n### Agent-Deliverable Compatibility Check\n\nBefore finalizing agent assignments, verify each phase's agent can deliver its requirements:\n\n| Phase Deliverable | Required Tier | Compatible Agents |\n|-------------------|--------------|-------------------|\n| Creates\u002Fmodifies files | Full Access or Read+Write | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, technical-writer, product-manager, ux-designer, copywriter |\n| Runs shell commands | Full Access or Read+Shell | coder, data-engineer, devops-engineer, tester, refactor, design-system-engineer, i18n-specialist, analytics-engineer, debugger, performance-engineer, security-engineer, seo-specialist, accessibility-specialist |\n| Analysis\u002Freview only | Any tier | All agents |\n\n\u003CHARD-GATE>\nRead-Only agents (architect, api-designer, code-reviewer, content-strategist, compliance-reviewer)\nCANNOT be assigned to phases that create or modify files. If a phase requires file creation\nand domain expertise from a Read-Only agent, split it: the Read-Only agent produces a spec\nor analysis, then a write-capable agent (typically coder) implements the files based on that output.\n\u003C\u002FHARD-GATE>\n\n### Phase Count Guidance\n\nScale decomposition granularity to `task_complexity` (read from design document frontmatter):\n- **simple**: 1-3 phases. Prefer single-phase execution when feasible. Combine foundation + implementation. Skip separate documentation\u002Fpolish phases.\n- **medium**: 3-5 phases. Use the layer model but combine Quality and Documentation into the final implementation phase where practical.\n- **complex**: No phase count cap. Full layer decomposition strategy applies.\n\n### Parallelization Identification\n\nPhases can run in parallel when:\n- They have no shared file dependencies (no overlapping files_created or files_modified)\n- They are at the same dependency depth (same layer)\n- They do not share data model ownership\n- Their validation can run independently\n\nMark parallel-eligible phases with `parallel: true` and group them into execution batches.\n\n### Same-Agent Parallel Decomposition\n\nWhen 70%+ of the work maps to a single agent specialization, decompose by **deliverable** — not by agent type. The orchestrator MUST auto-detect this condition and apply it without user configuration.\n\n**Ultrawork Override**: When `ultrawork: true` is set in session state, the 70% threshold drops to **40%**. Decompose by deliverable whenever 2+ independent file sets exist within a single agent's scope, regardless of what percentage of total work that agent handles. Allow up to **8 parallel instances** of the same agent (standard mode caps at 4).\n\n#### Trigger Conditions (auto-detected by planner)\n- The task is primarily one domain (e.g., \"build a landing page\" = all frontend)\n- The deliverables split into 2-4 independent units with non-overlapping files (Ultrawork: 2-8 units)\n- Each unit is self-contained enough for the agent to complete without the other units\n\n#### Decomposition Strategies\n\n| Strategy | Example | When to Use |\n|----------|---------|-------------|\n| **By section** | Header+Nav, Hero+CTA, Features, Footer+Contact | Landing pages, multi-section layouts |\n| **By feature** | Auth UI, Dashboard, Settings page | Feature-rich apps |\n| **By concern** | Layout+Structure, Styling+Animations, Responsive+A11y | When sections share too many files |\n\n#### File Ownership Contract\nEach parallel instance of the same agent MUST own non-overlapping files:\n- Instance A: `components\u002FHeader.tsx`, `components\u002FNav.tsx`\n- Instance B: `components\u002FHero.tsx`, `components\u002FFeatures.tsx`\n- Instance C: `components\u002FFooter.tsx`, `components\u002FContact.tsx`\n\nShared files (e.g., `globals.css`, `layout.tsx`, `page.tsx`) go to a **post-batch integration phase** — a single agent that stitches the parallel outputs together.\n\n#### Post-Batch Integration Phase\nAfter parallel same-agent phases complete, always add a lightweight integration phase:\n- **Agent**: same specialist (e.g., `frontend_specialist`)\n- **Task**: import all parallel outputs, wire into shared layout, resolve conflicts\n- **Depends on**: ALL parallel phases\n- **Files**: only shared\u002Fbarrel files (layout, page, globals)\n\n### Automatic Quality Review Pipeline\n\nFor any task that produces user-facing output (UI, landing page, app), the planner MUST append a review layer AFTER the build phases complete. This is automatic — the user does not request it.\n\n#### When to Append (auto-detected)\n- The task involves `frontend_specialist`, `mobile_developer`, or `game_developer`\n- The build phase(s) create or modify 3+ files\n- The task complexity is `medium` or `complex`\n\n#### Review Pipeline Structure\n\n```\nBuild Phase(s) → Integration (if parallel) → Review Batch (parallel) → Fix Phase\n```\n\n**Review Batch**: 2-3 parallel instances of the SAME implementing agent, each reviewing ONE quality dimension:\n\n| Review Instance | Focus | What to Check |\n|----------------|-------|---------------|\n| Responsive Review | Layout at 375px, 768px, 1024px, 1440px | Breakpoints, overflow, touch targets, safe areas |\n| Design Compliance | Style adherence | Does output match the chosen taste style? Anti-slop check, animation quality |\n| Accessibility + Performance | A11y + Core Web Vitals | ARIA, keyboard nav, contrast, image optimization, bundle size |\n\nEach review instance produces a structured findings report (Critical\u002FMajor\u002FMinor). The findings feed into a single **Fix Phase** where the implementing agent addresses Critical and Major issues.\n\n#### Review Phase Template\n```\nAgent: [same as build agent]\nPhase: [N]\u002F[total]\nTask: REVIEW ONLY — do NOT modify files\nFocus: [Responsive \u002F Design Compliance \u002F Accessibility + Performance]\n\nReview the following files created in previous phases:\n[file list from build phases]\n\nProduce a findings report with:\n- Severity: Critical \u002F Major \u002F Minor\n- File + line number\n- What's wrong\n- Suggested fix\n\nDo NOT write code. Report findings only.\n```\n\n#### Fix Phase Template\n```\nAgent: [same as build agent]\nPhase: [N]\u002F[total]\nTask: Fix Critical and Major findings from review batch\n\n[Aggregated findings from all review instances]\n\nFix each finding. Skip Minor unless trivial.\n```\n\n## Implementation Detail Requirements\n\n### Per-Phase Specification\n\nEach phase in the plan must include:\n\n#### Objective\nA clear, measurable statement of what this phase delivers.\n\n#### Agent Assignment\nWhich agent(s) execute this phase, with rationale for selection.\n\n#### Files to Create\nFor each new file:\n- Full relative path from project root\n- Purpose and responsibility\n- Key interfaces, classes, or functions to define\n- Complete type signatures for public APIs\n\n#### Files to Modify\nFor each existing file:\n- Full relative path from project root\n- Specific changes required and why\n- Expected before\u002Fafter for critical sections\n\n#### Implementation Details\n\nProvide sufficient detail for the assigned agent to execute without ambiguity:\n- Interface definitions with complete type signatures\n- Base class contracts with abstract method signatures\n- Dependency injection patterns and registration points\n- Error handling strategy (error types, propagation, recovery)\n- Configuration requirements (environment variables, config files)\n\n#### Validation Criteria\nSpecific commands to run and expected outcomes:\n- Build\u002Fcompile commands\n- Lint\u002Fformat checks\n- Unit test commands\n- Integration test commands (if applicable)\n- Manual verification steps (if applicable)\n\n#### Dependencies\n- `blocked_by`: Phase IDs that must complete before this phase starts\n- `blocks`: Phase IDs that cannot start until this phase completes\n\n### Dependency Minimization\n\nList only **direct** blockers in `blocked_by`. Do not include transitive dependencies — they inflate dependency depth and prevent parallelism.\n\nAnti-pattern (over-specified):\n- Phase 2: blocked_by: [1]\n- Phase 3: blocked_by: [1, 2] — Phase 1 is redundant, already reachable via Phase 2\n- Phase 4: blocked_by: [1, 2, 3] — Phases 1, 2 are redundant\n\nResult: depths 0, 1, 2, 3 — zero parallel phases.\n\nCorrect (minimized):\n- Phase 2: blocked_by: [1]\n- Phase 3: blocked_by: [1] — Only needs Phase 1 output, not Phase 2\n- Phase 4: blocked_by: [2, 3] — Needs both done\n\nResult: depths 0, 1, 2 — Phases 2 and 3 run in parallel at depth 1.\n\nAsk for each dependency: \"Does this phase truly need the output of that specific phase, or is it transitively covered?\"\n\nIf `validate_plan` is available, review its `parallelization_profile` and `redundant_dependency` warnings before presenting the plan. Revise `blocked_by` to eliminate redundancies when possible.\n\n## Agent Assignment Criteria\n\n### Matching Tasks to Agents\n\n| Task Domain | Primary Agent | Secondary Agent | Rationale |\n|-------------|--------------|-----------------|-----------|\n| System design, architecture | `architect` | - | Read-only analysis, design expertise |\n| API contracts, endpoints | `api-designer` | `coder` | Design then implement |\n| Feature implementation | `coder` | - | Full implementation access |\n| Code quality review | `code-reviewer` | - | Read-only verification |\n| Database schema, queries | `data-engineer` | - | Schema + implementation |\n| Bug investigation | `debugger` | - | Read + shell for investigation |\n| CI\u002FCD, infrastructure | `devops-engineer` | - | Full DevOps access |\n| Performance analysis | `performance-engineer` | - | Read + shell for profiling |\n| Code restructuring | `refactor` | - | Write + shell access (for validation) |\n| Security assessment | `security-engineer` | - | Read + shell for scanning |\n| Test creation | `tester` | - | Full test implementation |\n| Documentation | `technical-writer` | - | Write access for docs |\n| Technical SEO audit | `seo-specialist` | - | Read + shell + web search |\n| Marketing copy, content | `copywriter` | - | Read\u002Fwrite |\n| Content planning | `content-strategist` | - | Read + web search\u002Ffetch |\n| UX design, user flows | `ux-designer` | - | Read\u002Fwrite + web search |\n| WCAG compliance audit | `accessibility-specialist` | - | Read + shell + web search |\n| Requirements, product | `product-manager` | - | Read\u002Fwrite + web search |\n| Tracking, analytics | `analytics-engineer` | `coder` | Implement then instrument |\n| Internationalization | `i18n-specialist` | `coder` | Implement then localize |\n| Design tokens, theming | `design-system-engineer` | `coder` | Tokens then consume |\n| Legal, regulatory | `compliance-reviewer` | - | Read + web search\u002Ffetch |\n\n### Assignment Rules\n1. Match the primary task domain to the agent specialization\n2. Consider tool requirements — does the task need shell access? Write access?\n3. For parallel phases, assign non-overlapping file ownership to each agent\n4. Prefer focused single-deliverable phases. The same agent MAY run in multiple parallel phases with distinct file ownership (see Same-Agent Decomposition)\n5. Never assign more files to an agent than it can handle within its `max_turns` limit\n6. For UI\u002Ffrontend tasks, always append the Automatic Quality Review Pipeline after build phases\n\n### Token Budget Estimation\nEstimate token consumption per phase based on:\n- Number of files to read (input tokens)\n- Complexity of output expected (output tokens)\n- Agent's max_turns limit as upper bound\n- Historical averages: ~500 input tokens per file read, ~200 output tokens per file written\n\n### Cost Estimation\n\n#### Per-Phase Cost Factors\n- **Model tier**: Pro agents (~$0.01\u002F1K input, ~$0.04\u002F1K output) vs Flash agents (~$0.001\u002F1K input, ~$0.004\u002F1K output)\n- **Input complexity**: Number of files read, average file size, context from previous phases\n- **Output complexity**: Lines of code generated, number of files created\u002Fmodified\n- **Retry budget**: Add 50% buffer per phase for potential retries (max 2 retries)\n\n#### Estimation Formula\n```\nPhase Cost = (input_tokens × input_rate + output_tokens × output_rate) × retry_multiplier\n```\n\nWhere:\n- `input_tokens` = files_to_read × 500 + context_tokens\n- `output_tokens` = files_to_write × 200 + validation_output\n- `retry_multiplier` = 1.5 (accounts for up to 2 retries)\n\n#### Plan-Level Cost Summary\nInclude this table in every implementation plan:\n\n| Phase | Agent | Model | Est. Input | Est. Output | Est. Cost |\n|-------|-------|-------|-----------|------------|----------|\n| 1 | [agent] | [model] | [tokens] | [tokens] | [$X.XX] |\n| ... | ... | ... | ... | ... | ... |\n| **Total** | | | **[sum]** | **[sum]** | **[$X.XX]** |\n\n## Plan Document Generation\n\n### Output Location\n\nThe write path depends on whether your runtime provides a Plan Mode surface (check `get_runtime_context`, loaded at session start, step 0).\n\n- **Plan Mode active**: Some runtimes restrict writes to a temporary staging directory during Plan Mode. Write the plan there first, then copy to the permanent location after approval. Call `exit_plan_mode` with the plan path to present the plan for user approval.\n- **Plan Mode not active or not available**: Write the implementation plan directly to the project's plans directory.\n\nPermanent location: `\u003Cstate_dir>\u002Fplans\u002FYYYY-MM-DD-\u003Ctopic-slug>-impl-plan.md` (where `\u003Cstate_dir>` resolves from `GEM_SWARM_STATE_DIR`, default `docs\u002Fmaestro`).\n\nIf your runtime does not provide a Plan Mode transition, track planning progress using the plan-update mechanism from your runtime context, write directly to the final location, and use the user-prompt tool from runtime context for the approval gate.\n\n### Document Structure\nUse the `implementation-plan` template loaded via `get_skill_content`.\n\n### Required Sections\n\n1. **Plan Overview**: Summary of total phases, agents involved, estimated effort\n2. **Dependency Graph**: Visual representation showing phase dependencies and parallel opportunities\n3. **Execution Strategy Table**: Stage-by-stage breakdown with agent assignments and execution mode\n4. **Phase Details**: Full specification for each phase (objective, agent, files, details, validation, dependencies)\n5. **File Inventory**: Complete table mapping every file to its phase and purpose\n6. **Risk Classification**: Per-phase risk assessment (LOW\u002FMEDIUM\u002FHIGH) with rationale\n7. **Execution Profile**: Summary of parallel vs sequential characteristics to inform mode selection:\n   ```\n   Execution Profile:\n   - Total phases: [N]\n   - Parallelizable phases: [M] (in [B] batches)\n   - Sequential-only phases: [S]\n   - Estimated parallel wall time: [time estimate based on batch execution]\n   - Estimated sequential wall time: [time estimate based on serial execution]\n\n   Note: Native parallel execution currently runs agents in autonomous mode.\n   All tool calls are auto-approved without user confirmation.\n   ```\n\n### Completion Criteria\nThe implementation plan is complete when:\n- Every component from the design document maps to at least one phase\n- All phase dependencies are acyclic (no circular dependencies)\n- Parallel opportunities are identified and marked\n- Each phase has clear validation criteria\n- File ownership is non-overlapping for parallel phases\n- The user has given explicit approval of the complete plan\n\nBefore presenting the plan for approval, check whether `validate_plan` appears in your available tools. If it does, call it with the plan structure and `task_complexity` to verify phase count constraints, file ownership, acyclic dependencies, and agent validity. If it does not, self-check against the phase count limits above.\n\n### Post-Generation\nAfter writing the implementation plan:\n1. Confirm the file path to the user\n2. Present the dependency graph and execution strategy\n3. Highlight parallel execution opportunities\n4. Provide token budget estimates\n5. If your runtime provides Plan Mode, call `exit_plan_mode` with the plan path to present the plan for user approval. If Plan Mode is not available, present the completed plan for user approval using the user-prompt tool from runtime context.\n6. Ensure the approved plan is at `\u003Cstate_dir>\u002Fplans\u002FYYYY-MM-DD-\u003Cslug>-impl-plan.md` as the permanent project reference (copy from the staging directory if Plan Mode was used)\n7. Ask if the user is ready to proceed to execution (Phase 3)\n8. Upon approval, create the session state file via the session-management skill\n",{"name":5,"description":7},"main","923c514d4d5e15bbfd65ec7eaf949a997679aa3e","src\u002Fskills\u002Fshared\u002Fimplementation-planning","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm","https:\u002F\u002Fgithub.com\u002Fyqecea","15 y.o Data Science,Student","2026-04-26 20:00:27",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add yqecea\u002Fgem-swarm --skill implementation-planning",{"tool":41,"command":42},"bunx","bunx skills add yqecea\u002Fgem-swarm --skill implementation-planning",{"tool":44,"command":45},"pnpm","pnpm dlx skills add yqecea\u002Fgem-swarm --skill implementation-planning","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fimplementation-planning\u002FSKILL.md",true,[],[50,64,78,90,115,132],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":23},"01M71C74XVPP23ST10E8MYJZA0","validation","Cross-cutting validation methodology for verifying phase outputs and project integrity","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fvalidation\u002FSKILL.md",[],[52,57,58,59,60,61,62,63],"validation methodology","for","project","outputs","phase","methodology","integrity",{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":23},"01M71C72PTKRV481M975R3QDDE","session-management","Manages orchestration session state, tracking, and resumption","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fsession-management\u002FSKILL.md",[],[71,72,73,74,75,76,77],"management","session","session management","tracking","orchestration","state","session state",{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":23},"01M71C6XQVGMDFJ50BP5SBDS76","execution","Phase execution methodology for orchestration workflows with error handling and completion protocols","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fexecution\u002FSKILL.md",[],[80,58,85,86,62,61,87,88,89,75],"error handling","with","protocols","error","workflows",{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":106,"publishedAt":23},"01M71C6VY8APWMNK1XEJ3WP7A2","design-dialogue","Guides structured design conversations for complex engineering tasks","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fdesign-dialogue\u002FSKILL.md",[96,101],{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":102,"categoryName":103,"taxonomyType":104,"taxonomyTypeDesc":105},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[107,108,109,110,58,111,112,113,114],"design dialogue","design","dialogue","conversations","tasks","guides","engineering","structured",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":127,"publishedAt":23},"01M71C6R4RJWG3S2R26778TPD8","delegation","Agent delegation best practices for constructing effective subagent prompts with proper scoping","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fdelegation\u002FSKILL.md",[121,124],{"categoryNo":122,"categoryName":123,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000010","后端与接口",{"categoryNo":125,"categoryName":126,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000023","Skill与智能体开发",[117,128,129,58,130,86,131],"subagent","scoping","best practices","prompts",{"skillNo":133,"name":134,"nameZh":6,"description":135,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":136,"categories":137,"keywords":144,"publishedAt":23},"01M71C6PFKHSVBPCES0VKGSD0Y","code-review","Standalone code review methodology for structured, severity-classified code assessment","https:\u002F\u002Fgithub.com\u002Fyqecea\u002Fgem-swarm\u002Fblob\u002Fmain\u002Fsrc\u002Fskills\u002Fshared\u002Fcode-review\u002FSKILL.md",[138,141],{"categoryNo":139,"categoryName":140,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000007","代码审查",{"categoryNo":142,"categoryName":143,"taxonomyType":104,"taxonomyTypeDesc":105},"01JBSEEDCAT000000000000030","开发工程师",[145,146,147,148,149,114,62,150,58],"code","code review","review","severity","standalone","assessment"]