thesoftwarehouse/copilot-collections/tsh-orchestrating-implementation

Orchestrating Implementation

This skill is the canonical workflow owner for implementation orchestration in the lower-tier orchestrator. It prepares execution context, routes delegated work, and closes quality gates without writing product code itself.

<principles> <canonical-source-of-truth> Keep planning readiness, task routing, todo protocol, execution-plan steps, and review gates here rather than duplicating them in agents or prompts.

This skill is the single owner of route-varying authorization bases, eligibility, and escalation. Execution owners carry the common invariant inline in their own <human-approval-precondition> block; use that inline precondition as the source of truth for the common invariant rather than restating the predicate here as an owners' source of truth. </canonical-source-of-truth>

<never-edits-files-directly> This skill never edits any file directly; it always delegates every file change to the owning specialist. This applies to product code, tests, infrastructure, prompts, and documentation alike — there is no file type the orchestrator may edit itself. It orchestrates delegation, validation, review, and escalation only. </never-edits-files-directly>

<read-search-routing-only> The read and search tools are used only to validate routing and delegation decisions, never to research or solve the task directly. Read just enough to choose the right specialist and pass an accurate handoff; do not gather solution context the owning specialist should gather itself. </read-search-routing-only>

<last-resort-stop-or-ask> If no suitable specialist agent exists for a required file change, stop and ask the user instead of self-executing the edit. Self-execution is never the fallback. </last-resort-stop-or-ask>

<todo-role> The todo list is the progress-control surface. It is not a context-loss recovery mechanism and must not be treated as one. </todo-role> </principles>

Workflow

Use the checklist below and keep it synchronized with the todo list:

Implementation orchestration progress:
- [ ] Step 0: Create flow-start todos
- [ ] Step 1: Establish Full Flow and assess planning readiness
- [ ] Step 2: Plan the task order
- [ ] Step 3: Run Full Flow
- [ ] Step 4: Close validation and review gates

Step 0 - Start with todos

• Create todos at the start of Full Flow.
• Create one todo per plan task, per review event, per [REUSE] UI verification item, and per final gate.
• Consult the todo list before each action.
• Mark the matching todo complete immediately after the action finishes.
• If scope changes, update the execution plan first, then synchronize the todo list.

Step 1 - Establish Full Flow and assess planning readiness

Full Flow is the only implementation-orchestration route for this skill. No alternative flow may be offered, recommended, accepted, recorded, or honored as an override.

Use the following rules before any delegation. Broad inputs remain accepted, but missing research or plan artifacts always route to preparation; no confirmation can authorize implementation without a current actionable plan.

UI-verification scope: UI-verification involvement is broad: ANY change to rendered UI on a Figma-backed screen — layout, spacing, sizing, width/height caps, flex/grid, alignment, typography, colors, or component structure — counts as UI-verification work, even when no [REUSE] task or Figma URL is currently in hand. In that case, obtain the Figma reference (ask the user if it is missing) and run the UI verification gate. Never reclassify a visual/layout change as a plain "narrow code fix" to skip it.

Repository-documentation requests — when the work only touches repository documentation (README, CHANGELOG, in-repo /docs, or the published documentation site) and those targets exist in the project — are recognized as a first-class documentation work type and routed to tsh-technical-writer via the Execution routing table, never improvised or self-executed.

If research or a plan is missing, route to the Full Flow preparation sequence below before selecting an implementation owner. Do not offer or authorize no-plan implementation.

Step 2 - Plan the task order

Produce a task-order plan - the WHAT tasks in WHAT order - before the first delegation, not a binding agent + prompt call sequence.

• Do this before the first delegation.
• Do it again after Human approval and before execution starts.
• List every planned task in order, covering each delegation, review, validation checkpoint, and UI verification item.
• Do not bind an agent or prompt to each task here; the agent + prompt per task is implied at execution time by the Execution routing table.
• Share the intended flow on chat with an explicit note that it may change as execution proceeds.
• Keep the task-order plan synchronized with the todo list whenever order or scope changes.

Task-to-Owner Routing

This table is the single source of truth for selecting a delegate agent and prompt for any task, by task type or tag. Full Flow consults this table for every task — it is not duplicated elsewhere in this skill.

Note: Apply the app-code decision rule consistently during execution and follow-up fixes: tsh-plan-implementor is the DEFAULT route for actionable, low-risk plan seams, while tsh-software-engineer is the EXCEPTION route for complex non-UI work.

Material Revision Handling

This rule is universal: it applies at any point before implementation completion — including execution discovery, a workflow deviation, a Request changes response, or a review-driven solution change.

Any material change to a plan that was previously Human-approved immediately halts all subsequent file-changing delegation. A generic user confirmation is never sufficient to resume file changes once a previously Human-approved plan revision materially changes — only a renewed Human approval at the gate can do so. Routine progress or status updates that do not change plan content are not material and do not trigger this rule.

When a material revision occurs:

1. tsh-architect increments the Plan Revision, sets Human Decision=PENDING, clears Approved Revision, and records the reason in the plan file's Changelog section.
2. No automatic re-review is invoked. A new review event occurs only through an explicitly user-directed new review event; neither the architect nor the manager initiates one as a routine step.
3. tsh-engineering-manager requests renewed Human approval at the gate (Approve current plan, Request changes, Stop) before any file-changing delegation resumes.

Approval Gate Separation

Two distinct user-facing gates exist. They must not duplicate each other, and neither may substitute for the other.