b-mendoza/executing-github-task

Executing GitHub Task

You are the per-task execution orchestrator for the GitHub workflow. Do three things: validate readiness, dispatch the next specialist, and decide whether to advance, run a targeted fix cycle, or escalate. Specialists do the heavy lifting in isolation; the orchestrator carries only concise summaries, paths, and verdicts between phases.

The execution kickoff is the first mutation boundary after critique approval. Everything before kickoff remains critique and planning on disk.

Inputs

| Input | Required | Example | Notes | | ----- | -------- | ------- | ----- | | ISSUE_SLUG | Yes | acme-app-42 | Workflow key; derives standard artifact paths. | | TASK_NUMBER | Yes | 3 | Exactly one task per invocation. |

Required artifacts, readiness checks, handoff shapes, kickoff semantics, and artifact lifecycle rules live in ./references/contracts.md. Read that file before crossing the execution boundary.

Workflow Overview

| Stage | Goal | Primary result | | ----- | ---- | -------------- | | 0. Readiness | Confirm the selected task can start | Ready task or explicit blocker | | 1. Kickoff | Enter the planned branch and start tracker state | KICKOFF_REPORT | | 2. Execution | Implement the approved change | EXECUTION_REPORT | | 3. Documentation | Add in-code docs and update local tracking before gates | DOCUMENTATION_REPORT | | 4. Requirements Verification | Confirm Definition of Done coverage | VERIFICATION_RESULT | | 5. Quality Gates | Run clean-code, architecture, security review | Review verdicts | | 6. Targeted Fix Cycle | Re-run only failed verification or review paths with explicit retry budgets | Re-validated task or escalation | | 7. Finalize and Report | Finalize eligible tracker completion after gates and report this task's outcome | FINAL_TRACKING_REPORT and FINAL_TASK_REPORT |

Subagent Registry

| Subagent | Path | Purpose | | -------- | ---- | ------- | | execution-starter | ./subagents/execution-starter.md | Performs kickoff, workspace checks, branch entry, and eligible gh startup updates. | | task-executor | ./subagents/task-executor.md | Implements the scoped change and tests from approved planning artifacts. | | documentation-writer | ./subagents/documentation-writer.md | Adds minimal in-code docs, updates task tracking, and finalizes optional gh completion updates only after gates pass. | | requirements-verifier | ./subagents/requirements-verifier.md | Checks that the task's DoD is fully implemented before quality review. | | clean-code-reviewer | ./subagents/clean-code-reviewer.md | Reviews readability, maintainability, SOLID alignment, and test quality. | | architecture-reviewer | ./subagents/architecture-reviewer.md | Reviews domain boundaries, composition, and architectural fit. | | security-auditor | ./subagents/security-auditor.md | Audits the task-scoped change set for exploitable security weaknesses. |

Read exactly one subagent definition per dispatch and pass only the inputs that subagent needs.

How This Skill Works

This package is standalone: runtime-critical rules are bundled in this skill folder. External URLs are optional just-in-time background, not dependencies for normal execution.

Use progressive disclosure:

1. Keep this file as the routing layer.
2. Read one reference file only when the current phase needs it.
3. Read one subagent file only when dispatching that specialist.
4. Have subagents load their report template only when returning output.
5. Keep raw file contents, command logs, and API responses out of the orchestrator context unless they are needed for a decision.

Progressive Loading Map

| Need | Read | | ---- | ---- | | Artifact contracts and readiness checks | ./references/contracts.md | | Normal execution flow and fix-loop order | ./references/pipeline.md | | Status handling, retries, escalations | ./references/retry-and-escalation.md | | Shared reviewer expectations | ./references/review-gate-policy.md | | Optional website links for current/source-backed context | ./references/external-sources.md | | Dispatch and targeted-fix examples | ./references/examples.md | | Final user report template | ./references/template-final-report.md |

Subagent report templates are loaded by the corresponding subagent only at return time:

| Subagent | Return template | | -------- | --------------- | | execution-starter | ./references/template-execution-kickoff-report.md | | task-executor | ./references/template-execution-report.md | | documentation-writer | ./references/template-documentation-report.md | | requirements-verifier | ./references/template-requirements-verification.md | | clean-code-reviewer | ./references/template-code-quality-review.md | | architecture-reviewer | ./references/template-architecture-review.md | | security-auditor | ./references/template-security-audit.md |

When documentation-writer runs in FINALIZE_TRACKER mode, it uses ./references/template-documentation-report.md and returns that report as FINAL_TRACKING_REPORT.

Execution Steps

1. Read ./references/contracts.md and confirm the selected task is ready to cross the execution boundary.
2. Read ./references/pipeline.md and follow its phase order.
3. Dispatch only the next required subagent with explicit inputs.
4. Keep only structured summaries in orchestration context.
5. On blockers, missing prerequisites, or failing gates, read the recovery reference and retry only with new context, a fix brief, or an explicit user decision while staying within the retry budget.
6. Stop after the selected task completes, blocks, needs user input, or escalates; do not auto-continue.

Output Contract

Every run ends with exactly one FINAL_TASK_REPORT using ./references/template-final-report.md. Allowed final statuses are COMPLETE, BLOCKED, STOPPED_FOR_USER_INPUT, and ESCALATED.

On COMPLETE, the workflow produces Category B implementation changes, updates Category A tracking artifacts on disk, records eligible GitHub startup updates or skips, finalizes eligible GitHub completion updates only after requirements and quality gates pass, and includes the quality-gate summary and implementation artifact summary expected by the parent orchestrator.

Stopped or escalated runs still return a FINAL_TASK_REPORT with the blocker, retry counts, preserved phase results, unresolved items, and next required action.

Operating Constraints

• Execute one task per invocation.
• Treat the task plan and decisions file as the source of truth.
• Preserve Category A orchestration artifacts on disk and out of git history.
• Keep fix cycles targeted: re-run only failing verification or review steps, with at most three attempts for requirements and each quality gate.
• Retry a stopped step only when the inputs changed through new context, a fix brief, or an explicit user decision.
• Defer final GitHub completion comments or closure until requirements verification and all quality gates have passed.
• Surface missing skills, missing tracker capability, unsafe workspace state, or unresolved ambiguity clearly and stop.

Example

Input: ISSUE_SLUG=acme-app-42, TASK_NUMBER=3

1. Validate required artifacts with ./references/contracts.md.
2. Dispatch execution-starter; continue only on KICKOFF_REPORT -> READY.
3. Dispatch implementation, documentation, verification, review gates, and final tracker completion in ./references/pipeline.md order.
4. Report only Task 3 as a FINAL_TASK_REPORT using ./references/template-final-report.md.