Orchestrate Issue Implementation

Orchestrate the implementation of a parent issue (project, epic, or feature) by executing its child issues sequentially, reviewing each implementation, and committing approved changes.

Goal

Complete all planned child issues within a parent by:

1. •Spawning task implementations via the issue-implementation skill
2. •Reviewing completed work via the issue-implementation-review skill
3. •Committing approved changes
4. •Updating documentation when all children are complete

Issue Hierarchy

Process

1. Identify Parent Issue

Input

$ARGUMENTS - Can specify:

• •Issue ID: Specific issue to implement (e.g., "P-xxx", "E-xxx", or "F-xxx")
• •Scope: Limit search to issues within a parent scope

Use get_issue to retrieve the issue details. If no ID is specified, use get_next_available_issue with the appropriate issueType to find the next available issue.

2. Create Feature Branch

Before starting implementation, ensure work is on a feature branch.

Check Current Branch

Use Bash to check the current branch:

git branch --show-current

Branch Logic

• •

  If on main: Create and checkout a feature branch:

  bash

  git checkout -b feature/{ISSUE_ID}
  

  Example: feature/F-add-user-auth or feature/E-auth-system

• •

  If already on a non-main branch: Continue without branching

3. Verify Planned Work Exists

CRITICAL: Before starting, verify all work is planned.

1. •Use list_issues to get all direct children of this issue
2. •For each child, recursively verify its children exist (down to tasks)
3. •Review the complete work breakdown for completeness

Verification depth by parent type:

• •Feature: Verify tasks exist
• •Epic: Verify features exist, and each feature has tasks
• •Project: Verify epics exist, each epic has features, and each feature has tasks

If children are missing:

• •STOP immediately
• •Inform the user that the issue has unplanned work
• •List what appears to be missing:
  • •Children that have no sub-children
  • •Functionality from the description not covered
• •Ask the user to complete the planning before proceeding
• •Do NOT create primary work issues yourself - initial planning must happen before orchestration begins

Note: This restriction is about primary work planning. Follow-up work discovered during implementation can and should be tracked (see section 6.6).

4. Evaluate Complexity and Plan (Optional)

Before executing children, evaluate whether the work would benefit from upfront planning.

Complexity Signals

Consider spawning a planner for issues with:

• •Multiple tasks (more than 3-4 tasks)
• •Refactoring or migration language in task descriptions
• •Architectural changes mentioned
• •Multiple integration points or subsystems involved
• •Cross-cutting concerns that affect multiple areas

This is a judgment call—no hard threshold required.

Spawn Implementation Planner

If judged sufficiently complex:

1. •

   Use the Task tool to spawn issue-implementation-planner as an async subagent:

   code

   Task tool parameters:
   - subagent_type: "general-purpose"
   - description: "Plan implementation for {ISSUE_ID}"
   - run_in_background: true
   - prompt: |
       Use the /issue-implementation-planner skill to create an implementation plan for {ISSUE_ID}.
   
       Issue: {ISSUE_ID} - {ISSUE_TITLE}
       Description: {ISSUE_DESCRIPTION}
   
       Children to implement:
       {LIST_OF_CHILDREN_WITH_DESCRIPTIONS}
   
       Create a comprehensive plan that identifies key files, patterns, and implementation approach.
   

2. •

   Use TaskOutput to wait for the planner to complete

3. •

   Store the planner's output as context for implementation agents

4. •

   Include relevant plan context when spawning child implementations

5. Determine Execution Order

Analyze the direct children to determine the correct execution order:

1. •Check prerequisites: Each child may have prerequisites listing IDs that must complete first
2. •Check status: Skip children that are already done or wont-do
3. •Build execution queue: Order children so all prerequisites are satisfied before each runs

Execution Rules:

• •A child can only start when ALL its prerequisite issues are done
• •If a child has no prerequisites, it can start immediately (after any currently running child)
• •Execute children sequentially - wait for each to complete before starting the next

6. Execute Children

For each child in the execution queue:

6.1 Verify Child is Ready

• •Check all prerequisites are done
• •Check child status is open or draft (not already in-progress or done)
• •If not ready, skip and check next child

6.2 Launch Child Implementation

Use the Task tool to spawn a subagent that implements the child.

CRITICAL: Store the agent ID returned by the Task tool. You will need this ID to resume the agent if review feedback requires changes.

For Tasks - spawn the issue-implementation skill:

Task tool parameters:
- subagent_type: "general-purpose"
- description: "Implement task [TASK_ID]"
- prompt: |
    Use the /issue-implementation skill to implement task [TASK_ID].

    Context:
    - Parent: [PARENT_ID] - [PARENT_TITLE]
    - Task: [TASK_ID] - [TASK_TITLE]

    [INCLUDE_PLAN_CONTEXT_IF_AVAILABLE]

    Implement this task following the task implementation workflow.
    Do NOT commit your changes - leave them uncommitted for review.

    If you encounter any errors or blockers, STOP and report back.

After the Task tool returns, note the agent ID from the response (e.g., agent_id: "abc123"). You will use this with the resume parameter if the review identifies issues.

For Features/Epics/Projects - spawn the issue-implementation-orchestration skill (recursive):

Task tool parameters:
- subagent_type: "general-purpose"
- description: "Orchestrate [CHILD_TYPE] [CHILD_ID]"
- prompt: |
    Use the /issue-implementation-orchestration skill to implement [CHILD_TYPE] [CHILD_ID].

    Context:
    - Parent: [PARENT_ID] - [PARENT_TITLE]
    - [CHILD_TYPE]: [CHILD_ID] - [CHILD_TITLE]

    [INCLUDE_PLAN_CONTEXT_IF_AVAILABLE]

    Orchestrate the implementation of this issue and its children.

    If you encounter any errors or blockers, STOP and report back.

Wait for the subagent to complete before proceeding.

6.3 Verify Child Completion

After the subagent returns:

1. •Use get_issue to check the child's status
2. •If status is done: Continue to review step (for tasks) or next child (for orchestrated children)
3. •If status is NOT done: STOP and handle the error (see Section 7)

6.4 Review Task Implementation

After a task completes successfully, evaluate if a review is warranted.

Skip review for trivial tasks (judgment call):

• •Single configuration change
• •One-line fix
• •Simple rename or move

For non-trivial tasks, spawn issue-implementation-review:

Task tool parameters:
- subagent_type: "general-purpose"
- description: "Review implementation of [TASK_ID]"
- run_in_background: true
- prompt: |
    Use the /issue-implementation-review skill to review task [TASK_ID].

    Task: [TASK_ID] - [TASK_TITLE]
    Parent Feature: [PARENT_ID] - [PARENT_TITLE]

    Review the implementation for correctness, completeness, and simplicity.

Use TaskOutput to wait for the review to complete.

Handle review outcomes:

• •No findings / empty output: Proceed to commit
• •Findings identified: Resume the original implementation agent to address the feedback:
  1. •Resume the implementation agent using the Task tool with the resume parameter:
     code

     Task tool parameters:
     - subagent_type: "general-purpose"
     - description: "Address review feedback for [TASK_ID]"
     - resume: "[AGENT_ID_FROM_STEP_6.2]"
     - prompt: |
         The review identified the following issues that need to be addressed:
     
         [PASTE_REVIEW_FINDINGS_HERE]
     
         Please address ALL findings:
         - Fix valid findings, including minor ones (documentation, style, small improvements)
         - If you believe a finding is incorrect, explain your reasoning. You must justify skipping any finding.
     
         Do NOT commit your changes - leave them uncommitted for re-review.
     

  2. •Wait for the agent to complete the fixes
  3. •Re-run review to verify the findings were addressed
  4. •Repeat this cycle until all valid findings are resolved
  5. •Proceed to commit only when the review passes
• •Questions requiring answers:
  • •STOP orchestration
  • •Use AskUserQuestion to get answers from the user
  • •Resume the implementation agent with the answers provided

CRITICAL - Orchestrator Role: The orchestrator does NOT write code. It only orchestrates:

• •Spawning implementation agents
• •Spawning review agents
• •Sending feedback to implementation agents for fixes
• •Committing approved changes

If fixes are needed, ALWAYS resume the original implementation agent. The original agent already has full context about what it implemented, making it far more efficient than spawning a new agent that would need to rebuild context.

CRITICAL: Do not categorize findings as "minor" and skip them. Every finding from a review must be either fixed or explicitly challenged with reasoning. Ignoring feedback is not acceptable.

6.5 Commit Task Changes

After implementation and review pass, commit the changes.

CRITICAL - Update Trellis BEFORE committing:

The .trellis/ directory contains issue state that must be included in commits. Always update Trellis issues first, then commit.

1. •

   Update Trellis state (if not already done):

   • •Ensure task is marked complete via complete_task
2. •

   Commit the changes using the /git:commit skill (if available) or manually:

   Using the skill (preferred):

   code

   /git:commit [TASK_ID] Summary of changes
   

   Manual fallback (if skill unavailable):

   bash

   git add .
   git commit -m "[TASK_ID] Summary of changes"
   

   Example: [T-add-user-validation] Add email validation to user registration

3. •

   Handle commit failures - If the commit fails (e.g., pre-commit hook, smoke test, linting):

   CRITICAL: Do NOT debug or fix the issue yourself. Resume the original implementation agent:

   code

   Task tool parameters:
   - subagent_type: "general-purpose"
   - description: "Fix commit failure for [TASK_ID]"
   - resume: "[AGENT_ID_FROM_STEP_6.2]"
   - prompt: |
       The commit failed with the following error:
   
       [PASTE_FULL_ERROR_OUTPUT_HERE]
   
       Please fix the issue that caused this failure. Common causes include:
       - Failing tests or smoke tests
       - Linting errors
       - Type errors
       - Pre-commit hook violations
   
       After fixing, verify the fix works locally, then report back.
       Do NOT commit - leave changes uncommitted.
   

   After the agent fixes the issue:

   • •Re-attempt the commit
   • •If it fails again, resume the agent with the new error
   • •Repeat until the commit succeeds
4. •

   Verify commit succeeded and no .trellis/ changes remain uncommitted

6.6 Handle Follow-up Work

During implementation or review, you may identify work that wasn't originally planned but should be addressed. Rather than just noting "this needs follow-up," take action to ensure follow-up actually happens.

When follow-up work is identified:

1. •

   Search for existing coverage before creating anything:

   a. Check for existing issues that cover this work:

   code

   Use list_issues to search for issues that might already cover this work:
   - Search by relevant keywords in titles
   - Check both open issues AND recently completed issues
   - Look in the current feature's siblings and parent hierarchy
   

   b. Check planned but unstarted work in the current project/epic:

   • •Review other features under the same epic
   • •Review other tasks under sibling features
   • •The work might already be planned for a later phase

   c. If already covered: Log the discovery and reference the existing issue, then move on

2. •

   If genuinely new work that isn't covered elsewhere:

   a. Determine the appropriate parent:

   • •Preferred: Add to the current feature (if still open or can be reopened)
   • •Alternative: Add to a sibling feature that's still open
   • •Fallback: Create as a standalone task (no parent)

   b. Handle completed parent features:

   • •If the current feature is marked done, use update_issue to change its status back to open
   • •Log why the feature was reopened: "Reopened to add follow-up task discovered during implementation"
   • •This is acceptable—features can be reopened when new work is discovered

   c. Create the follow-up task using the issue-creation skill:

   code

   Invoke the Skill tool:
   - skill: "task-trellis:issue-creation"
   - args: "Create a task under [PARENT_ID]: [DESCRIPTION_OF_FOLLOW_UP_WORK]"
   

3. •

   What qualifies as follow-up work:

   • •Technical debt discovered during implementation
   • •Edge cases not covered by original requirements
   • •Refactoring opportunities that would improve maintainability
   • •Missing tests or documentation identified during review
   • •Integration issues that need separate attention
   • •Performance improvements identified but out of scope for current task
4. •

   What does NOT require follow-up tasks:

   • •Items that should be addressed in the current task (don't defer unnecessarily)
   • •Known limitations that are explicitly acceptable
   • •"Nice to have" improvements with no real impact
   • •Stylistic preferences that don't affect functionality

CRITICAL: The goal is ensuring follow-up work actually gets tracked—not just mentioned. If you identify something that genuinely needs to be done later, create the issue. But always search first to avoid duplicates.

7. Handle Errors

Error Classification

Implementation errors (send back to the implementation agent):

• •Failing tests or smoke tests
• •Linting or formatting errors
• •Type errors or compilation failures
• •Pre-commit hook failures due to code quality
• •Runtime errors in the implemented code
• •Any error caused by code the implementation agent wrote

Infrastructure errors (stop and ask the user):

• •Permission denied when running commands
• •Missing dependencies or tools
• •Network/connectivity issues
• •Git configuration problems
• •Environment setup issues

Handling Implementation Errors

When an error is caused by the implementation agent's work:

1. •

   Resume the implementation agent with the error details:

   code

   Task tool parameters:
   - subagent_type: "general-purpose"
   - description: "Fix error for [TASK_ID]"
   - resume: "[AGENT_ID_FROM_STEP_6.2]"
   - prompt: |
       An error occurred that needs to be fixed:
   
       [PASTE_FULL_ERROR_OUTPUT_HERE]
   
       Please diagnose and fix this issue. The error is related to code you implemented.
   
       After fixing, verify the fix works, then report back.
       Do NOT commit - leave changes uncommitted.
   

2. •

   Wait for the fix and re-attempt the failed operation

3. •

   Repeat if needed - If new errors occur, send them back to the agent

4. •

   Escalate to user only if the agent cannot resolve the issue after reasonable attempts

Handling Infrastructure Errors

For errors NOT caused by the implementation:

1. •Stop execution - Do not proceed to other children
2. •Ask the user - Use AskUserQuestion to report the failure and ask how to proceed:
   • •Fix the infrastructure issue and retry
   • •Skip the failed child and continue
   • •Stop orchestration entirely
3. •Follow user direction - Do what the user decides

CRITICAL - Orchestrator Role: The orchestrator NEVER debugs code, reads stack traces to diagnose issues, or attempts fixes. When something fails due to code, the orchestrator's only job is to send the error back to the implementation agent that wrote the code.

Why this matters: Hooks are configured to enforce quality checks and validation rules. When they fail, it usually means something is misconfigured or you lack necessary permissions. Working around these errors masks important problems and can lead to broken code being committed.

8. Update Documentation

When all children are done (before marking the parent as complete):

Spawn Documentation Updater

Use the Task tool to spawn docs-updater:

Task tool parameters:
- subagent_type: "general-purpose"
- description: "Update documentation for [ISSUE_ID]"
- run_in_background: true
- prompt: |
    Use the /docs-updater skill to review and update documentation.

    Issue: [ISSUE_ID] - [ISSUE_TITLE]

    Review the changes made during this implementation and update any relevant
    documentation files (CLAUDE.md, README.md, docs/**).

Use TaskOutput to wait for the docs-updater to complete.

Commit Documentation Changes

If the docs-updater made changes, commit them using the /git:commit skill (if available) or manually:

Using the skill (preferred):

/git:commit docs: update documentation for [ISSUE_ID]

Manual fallback (if skill unavailable):

git add .
git commit -m "docs: update documentation for [ISSUE_ID]"

9. Complete Parent Issue

When all children are done and documentation is updated:

1. •

   Verify all children have status done (or wont-do if skipped by user direction)

2. •

   Update the parent status to done using update_issue

3. •

   If any uncommitted changes exist (including .trellis/), commit them using the /git:commit skill (if available) or manually:

   Using the skill (preferred):

   code

   /git:commit chore: complete [ISSUE_ID]
   

   Manual fallback (if skill unavailable):

   bash

   git add .
   git commit -m "chore: complete [ISSUE_ID]"
   

4. •

   Verify no uncommitted changes remain - especially in .trellis/

5. •

   Report summary to user:

   • •Total direct children completed
   • •Total descendants completed (all levels)
   • •Any issues skipped
   • •Commits created
   • •Documentation updates made
   • •Overall outcome

10. Summarize Expected Changes for User

After completing the parent issue, provide a clear summary of what the user should expect to see now that this work is complete. This is the most important output for the user.

What Changed Summary

Provide a concise description of what's different now:

1. •New capabilities: What can the user (or the system) do now that wasn't possible before?
2. •Behavior changes: What existing functionality works differently?
3. •Files affected: High-level summary of which areas of the codebase were touched (not exhaustive file lists)

How to Verify

Tell the user how they can see the changes in action:

1. •For UI changes: Describe where to look and what they'll see
2. •For API changes: Example commands or endpoints to test
3. •For CLI changes: Commands to run
4. •For configuration: What settings are now available
5. •For internal refactors: How to verify the code still works (e.g., "run the test suite")

Example Summary Format

## What's New

[FEATURE_TITLE] is now complete. Here's what changed:

**New Capabilities:**
- [Describe what users can now do]
- [Any new commands, endpoints, or UI elements]

**Key Changes:**
- [Brief description of the main implementation approach]
- [Any notable architectural decisions]

**How to Verify:**
- [Specific steps to see the feature in action]
- [Commands to run, URLs to visit, or actions to take]

**Files Changed:**
- [Area 1]: [Brief description of changes]
- [Area 2]: [Brief description of changes]

Why This Matters

The user initiated this work to achieve a specific outcome. They need to know:

• •That the work is actually complete
• •What they can do with it now
• •How to verify it works as expected

A summary of commits and task counts is process information. The user needs outcome information—what's different in their codebase and how to use it.

Important Constraints

• •Orchestration only: The orchestrator does NOT write code, debug errors, or make fixes. It only spawns agents, routes feedback/errors, and commits approved changes.
• •Resume for feedback: When review identifies issues, ALWAYS resume the original implementation agent rather than spawning a new one. The original agent has context and can address feedback efficiently.
• •Resume for errors: When commit hooks, tests, or other validations fail due to code issues, ALWAYS resume the original implementation agent with the error. Never debug or fix code yourself.
• •No parallel execution: Run only one child at a time
• •Follow-up work only: Create new issues only for follow-up work discovered during implementation—never for the primary work (see section 6.6)
• •Respect dependencies: Never start a child before its prerequisites are done
• •Stop on infrastructure failure: Stop and ask user only for infrastructure errors (permissions, missing tools, network). Code errors go back to the implementation agent.
• •Ask questions: Use AskUserQuestion when uncertain about anything
• •Trellis before commits: Always update Trellis issues BEFORE making git commits
• •Commit after each task: Ensure changes are committed before moving to the next task
• •Update docs before completing: Always run docs-updater before marking parent as done
• •No uncommitted Trellis state: Never finish with uncommitted .trellis/ changes