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: ```text 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. | Task type or tag | Delegate to | Prompt to use | Notes | | ----------------------------- | ----------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | app code (plan task) | `tsh-plan-implementor` | `tsh-implement-common-task.prompt.md` | DEFAULT route for a Human-approved plan revision's actionable, low-risk plan seams that must be executed exactly as written | | app code (complex) | `tsh-software-engineer` | `tsh-implement-common-task.prompt.md` | EXCEPTION route for complex non-UI work; choose `Kimi K2.7 Code` or `GPT-5.3-Codex` for medium-reasoning precision on complex work, or `Gemini 3.6 Flash` for fast, low-cost, large-context analysis | | UI with Figma | `tsh-ui-engineer` | `tsh-implement-ui-common-task.prompt.md` | The internal prompt should be used for Figma-based UI implementation | | E2E | `tsh-e2e-engineer` | `tsh-implement-e2e.prompt.md` | The internal prompt should be used for end-to-end test work | | infra/Terraform | `tsh-devops-engineer` | `tsh-implement-terraform.prompt.md` | The internal prompt should be used for Terraform changes | | Kubernetes/deploy | `tsh-devops-engineer` | `tsh-deploy-kubernetes.prompt.md` | The internal prompt should be used for deployment or Kubernetes work | | CI/CD | `tsh-devops-engineer` | `tsh-implement-pipeline.prompt.md` | The internal prompt should be used for pipeline work | | observability | `tsh-devops-engineer` | `tsh-implement-observability.prompt.md` | The internal prompt should be used for logging, metrics, or tracing work | | LLM prompts | `tsh-prompt-engineer` | `tsh-engineer-prompt.prompt.md` | The internal prompt should be used for prompt-engineering tasks | | documentation | `tsh-technical-writer` | `tsh-write-documentation.prompt.md` | The internal prompt should be used for repository documentation work across all targets — README, CHANGELOG, `/docs`, and the published documentation site when those targets exist in the project | | `[REUSE]` UI verification | `tsh-ui-reviewer` | `tsh-review-ui.prompt.md` | Review each UI item individually; do not batch | | `[REUSE]` other | per the task definition | — | Execute as defined in the task definition; delegate to the matching implementer only when new product code is required | 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. | Gate | Owner | Exact labels | When it fires | Who writes the record | | --- | --- | --- | --- | --- | | Plan-authoring approval | `tsh-architect` | `Approve plan`, `I have comments` | Immediately after a settled review event: a revision-bound verdict accepted for the revision read plus a written disposition for every eligible blocker. It does not fire on the low-risk-exemption path, where no reviewer verdict exists. | `tsh-architect` writes the literal decision into the plan's `## Human Approval` table. | | Execution authorization (recovery-only) | `tsh-engineering-manager` | `Approve current plan`, `Request changes`, `Stop` | Before the first file-changing delegation, and again after any material revision — but only when no valid approval already exists for the current unchanged `Plan Revision`. | `tsh-engineering-manager` delegates the write to `tsh-architect`; it never writes the record itself because it has no `edit` tool. | The Manager's gate is fail-closed recovery only, never a second normal authorization when a valid current-revision record already exists, including one recorded by `tsh-architect`. The manager MUST read the exact plan path and evaluate each canonical approval field before reuse. This skill is the sole detailed owner of that validation and receipt procedure. The manager MUST perform the validation read-only against the exact plan path, then evaluate the existing three canonical fields: `Human Decision`, `Approved Revision`, and a valid UTC-Z `Decision Timestamp`. A valid unchanged persisted record produces an ephemeral bounded `reused` receipt containing the exact plan path, current revision, persisted timestamp, review path when available, and the result of each predicate field. It authorizes reuse without a duplicate manager gate. If the record is unreadable or missing, stale, mismatched, non-literal, or in `PENDING` state, the manager MUST fail closed and produce an ephemeral `invalid-or-missing` receipt naming the exact failed field or path. Manager-turn-only consent is explicitly rejected as a validity criterion. The exact plan path and persisted fields win if handoff routing metadata conflicts; the manager fails closed rather than using conflicting pointers. Handoff pointers, architect prose, delegated turns, reviewer output, and receipts never replace on-disk validation. Do not persist a receipt or add metadata, provenance, a ledger, a cryptographic claim, a schema change, or a fourth predicate term. Reuse never manufactures consent: it requires the exact canonical predicate over a literal recorded decision, and any missing, unreadable, stale, mismatched, or `PENDING` record forces the gate. Neither gate may weaken the canonical `## Human Approval` schema, values, validity predicate, or reset behavior owned by `tsh-creating-implementation-plans`. After any material revision, **Material Revision Handling** above applies in full and no prior approval is reusable. ## Implementation Discussion Boundary The **authoring discussion** is the discussion in which the plan was authored, reviewed, and approved at the Architect's plan-authoring gate. The **implementation discussion** is a new discussion the user starts to deliver that plan. Recording plan-authoring Human approval completes the authoring discussion; implementation begins only in a new discussion. In the authoring discussion, after a current-revision recorded `APPROVED`, the manager reports the exact plan path, current `Plan Revision`, persisted `Decision Timestamp`, and review path when present, names implementation as the next step, and MUST NOT perform any file-changing delegation there. This includes the Full Flow where `/tsh-implement` routed planning to the Architect in this same discussion and the Architect recorded approval there. New implementation discussions enter through `/tsh-implement` or a direct `tsh-engineering-manager` invocation. The manager re-reads and reuses the existing on-disk record under the unchanged predicate `Human Decision=APPROVED`, `Approved Revision=current Plan Revision`, and a `Decision Timestamp` that is valid ISO 8601 UTC ending in `Z`, without presenting a duplicate approval gate. The discussion boundary is a lifecycle stop, never an approval-validity criterion. Invalid or missing states remain fail-closed, and **Material Revision Handling** remains unchanged; the boundary grants no exception. The low-risk-exemption path is excluded: no Architect plan-authoring gate ran there, and the manager's execution-authorization gate remains the only user-facing gate. This boundary is instruction-level and auditable; it does not detect or enforce a VS Code conversation identifier. It introduces no fields, values, provenance, receipts, ledgers, or additional predicate terms. ## Full Flow ### Planning readiness Check the current state before creating or executing any plan. | Artifact or signal | Treat as ready when | If not ready | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `*.research.md` | It exists for the current task and contains enough context to explain scope, constraints, requirements, and referenced inputs or links | Route to `tsh-context-engineer` with `tsh-research.prompt.md` | | `*.plan.md` | It exists for the current task and contains ordered, actionable tasks that can be delegated | Route to `tsh-architect` with `tsh-plan.prompt.md` | | Open questions gate | It exists and contains no `❓ Open` rows in `## Open Questions`, so unresolved questions are not blocking execution readiness | Route to `tsh-architect` with `tsh-plan.prompt.md` | | Technical Context | The plan has a populated `Technical Context` section with conventions, patterns, stack, and testing guidance relevant to implementation | Route to `tsh-architect` with `tsh-review-codebase.prompt.md` | | Reviewer readiness | Satisfied by a settled review event recorded in `.plan-review.md` — a revision-bound verdict accepted at return plus a written disposition for every eligible blocker — or, before any Human approval has ever been recorded, by the unchanged explicitly recorded valid low-risk automated-review exemption for initial plan preparation; this is never Human approval | Route to `tsh-architect` with `tsh-plan.prompt.md` to return a finished reviewed plan or an explicitly stated valid exemption | | Human approval state | The plan's persisted Human Approval record satisfies `Human Decision=APPROVED`, `Approved Revision=current Plan Revision`, and a `Decision Timestamp` that is valid ISO 8601 UTC ending in `Z`. A record `tsh-architect` already wrote at its plan-authoring gate satisfies this row for the unchanged revision; apply the **Implementation Discussion Boundary**. | Present the mandatory Human approval gate before the first file-changing delegation | ### Planning sequence 1. **Check for existing research and plan files** - Inspect current `*.research.md` and `*.plan.md` state first. 2. **Fill missing context when needed** - If research is missing or incomplete, delegate to `tsh-context-engineer` with `tsh-research.prompt.md`. 3. **Create or refresh the reviewed plan when needed** - If the plan is missing, stale, not actionable, or not reviewer-ready, delegate to `tsh-architect` with `tsh-plan.prompt.md`. The architect owns producing a finished reviewed plan with one invocation per plan lifecycle; the sole exception is an explicitly user-directed new review event, never a routine architect or manager option. If a return is non-revision-bound or a blocker remains unresolved, the architect uses `vscode/askQuestions` with exactly `stop here` and `custom guidance`, neither of which authorizes another review. Preserve append-only review history and never approve with unhandled blockers. The plan MUST be authored following the `tsh-creating-implementation-plans` skill — it owns the plan template and structure rules. Missing research always routes to `tsh-context-engineer` first; missing plans always route to `tsh-architect`. After the review event is settled, the architect runs its own plan-authoring approval gate (`Approve plan`, `I have comments`) and records the literal decision in the plan's `## Human Approval` table; see **Approval Gate Separation**. 4. **Create execution todos from the plan** - Create todos per plan task, not just per phase. 5. **Capture UI inventory early** - Find every `[REUSE]` UI task and every Figma URL in the plan and research files. If a Figma-backed UI task does not have a Figma reference, stop and get it from the user before execution starts. 6. **Ask for the dev server URL when UI tasks exist** - If the UI inventory is non-empty, use `vscode/askQuestions` to get the exact user-confirmed full dev server URL before execution starts. Treat it as a pinned session input and forward it unchanged through every reviewer and capture delegation. 7. **Apply the Technical Context rule** - If the plan already contains populated Technical Context, use it and skip rediscovery; otherwise delegate to `tsh-architect` with `tsh-review-codebase.prompt.md`. 8. **Separate reviewer readiness from Human approval readiness** - Reviewer readiness is satisfied by a settled review event recorded in `.plan-review.md` — a revision-bound verdict accepted at return plus a written disposition for every eligible blocker — or, before any Human approval has ever been recorded for this plan, by the unchanged explicitly stated valid low-risk automated-review exemption for initial plan preparation. This is Reviewer readiness only and never execution permission; neither basis substitutes for Human approval. A material revision after Human approval still halts delegation and requires renewed Human approval, but no automatic reviewer invocation; a new review event occurs only through the explicitly user-directed new review event exception. 9. **Pass the Human approval gate before execution** - Before the first file-changing delegation, present the exact current plan path, the plan's current contents, the current Plan Revision, and the review path when present. When reviewer readiness rests on the initial-plan low-risk exemption instead of a review report, state plainly that no reviewer report exists because the initial-preparation exemption is the documented readiness basis; never let the exemption substitute for Human approval itself. Offer exactly: `Approve current plan`, `Request changes`, `Stop`. `Approve current plan` authorizes every unchanged task in that revision, in plan order; `Request changes` returns to `tsh-architect`; `Stop` ends without implementation. If the plan's persisted `## Human Approval` record already satisfies the canonical predicate for the current unchanged `Plan Revision` — for example because `tsh-architect` recorded it at its plan-authoring gate — reuse that approval per **Approval Gate Separation** instead of presenting this gate again, subject to the **Implementation Discussion Boundary**.