executing-github-task

What this skill does

# 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`.