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

Parent Type	Child Type	Child's Children
Project	Epics	Features → Tasks
Epic	Features	Tasks
Feature	Tasks	(none)

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:

  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

Log Branch Status

Use

append_issue_log

to record:

• Branch created: "Created feature branch feature/{ISSUE_ID}"
• Existing branch: "Continuing on existing branch {BRANCH_NAME}"

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 issues yourself - implementation does not include planning

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:

   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:

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.

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: You MUST address ALL findings before proceeding:
  1. Review each finding - Evaluate whether it's valid
  2. Fix valid findings - Make the necessary changes, including minor ones (documentation, style, small improvements)
  3. Challenge incorrect findings - If you believe a finding is wrong, explain your reasoning in the issue log. You are not required to blindly follow incorrect recommendations, but you must justify skipping any finding.
  4. Re-run review after making fixes to verify they were addressed
  5. Proceed to commit only when all valid findings are resolved
• Questions requiring answers:
  • STOP orchestration
  • Use

    AskUserQuestion

    to get answers from the user
  • Re-run review with the answers provided

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

   • Append any final log entries via

     append_issue_log

2. Commit the changes using the

   /git:commit

   skill (if available) or manually:

   Using the skill (preferred):

   /git:commit [TASK_ID] Summary of changes
   

   Manual fallback (if skill unavailable):

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

   Example:

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

3. Verify commit succeeded and no

   .trellis/

   changes remain uncommitted

4. Log the commit using

   append_issue_log

   on the parent issue

7. Handle Errors

<rules> <critical>If you encounter a permission error, STOP IMMEDIATELY and report to the user. Do NOT attempt workarounds.</critical> <critical>If a hook returns any unexpected errors or fails, STOP IMMEDIATELY and report to the user. Hook errors indicate important validation failures.</critical> <critical>NEVER work around errors by skipping steps, using alternative approaches, or ignoring validation failures.</critical> <critical>When blocked by any unexpected error - even if you think it doesn't apply to you - your only options are: (1) ask the user for help, or (2) stop completely.</critical> <critical>Do NOT assume an error is irrelevant or a false positive. Report any unexpected errors to the user and let them decide.</critical> </rules>

If a child fails or the subagent reports an error:

1. Stop execution - Do not proceed to other children
2. Log the failure - Use

   append_issue_log

   on the parent to record what happened
3. Ask the user - Use AskUserQuestion to report the failure and ask how to proceed:
   • Retry the failed child
   • Skip the failed child and continue
   • Stop orchestration entirely
4. Follow user direction - Do what the user decides

Common error scenarios that require stopping:

• Permission denied when running commands
• Unexpected hook failures (pre-commit, post-edit, quality checks)
• Subagent returning errors or incomplete results
• Git commit failures

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:

CRITICAL - Update Trellis BEFORE committing:

1. Update Trellis first:

   • Log the documentation update using

     append_issue_log

   • Make any other Trellis updates needed

2. Commit the changes 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]"
   

3. Verify no

   .trellis/

   changes remain uncommitted

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. Log completion using

   append_issue_log

4. If any uncommitted changes exist (including

   .trellis/

   ), commit them using the

   /git:commit

   skill (if available) or manually:

   Using the skill (preferred):

   /git:commit chore: complete [ISSUE_ID]
   

   Manual fallback (if skill unavailable):

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

5. Verify no uncommitted changes remain - especially in

   .trellis/

6. Report summary to user:

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

Progress Tracking

Throughout orchestration:

• Use

  append_issue_log

  on the parent to record progress
• Report status to user after each child completes
• Keep user informed of which child is currently running

Important Constraints

• No parallel execution: Run only one child at a time
• No creating work: Do not create new issues; only execute planned work
• Respect dependencies: Never start a child before its prerequisites are done
• Stop on failure: Always stop and ask user when something goes wrong
• 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

<rules> <critical>STOP on ANY error - permission errors, hook failures, or unexpected results</critical> <critical>NEVER work around errors or assume they don't apply</critical> <critical>Do NOT proceed to next child if current child encountered errors</critical> <critical>Report ALL errors to the user, even if you think they're false positives</critical> <critical>Update Trellis issues BEFORE git commits so .trellis/ changes are included</critical> <critical>Never leave .trellis/ changes uncommitted when finishing work</critical> <critical>Address ALL review findings - do not ignore feedback because it seems minor</critical> <critical>If you skip a review finding, you MUST explain why you believe it is incorrect</critical> </rules>