# Execute

> Executes, implements, or works through a GitHub issue, milestone, or inline task list end to end with TDD, then opens a PR and merges it once CI is green.

- Skill: `martinopolo/execute` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add martinopolo/execute`
- Raw SKILL.md: https://api.skillmd.com/api/skills/martinopolo/execute/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: MartinoPolo (https://skillmd.com/u/martinopolo)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/martinopolo/execute

---


# Execute Work

Unified execution skill with TDD methodology. Accepts GitHub issues, milestones, or inline tasks.

**The main agent is a pure orchestrator.** It parses input, sets up context, spawns sub-agents, routes their bounded JSON results, and gates on user decisions. Review findings, test failures, and CI logs are handled inside sub-agents — main only ever sees the return contracts. Never ask a sub-agent for its raw findings or logs.

## Communication Style

Use compressed output throughout execution: drop articles, filler, pleasantries, hedging. Fragments OK. Use abbreviations (DB/auth/config) and arrows (X → Y). Pattern: `[thing] [action] [reason]. [next step].` Keep technical terms exact, code blocks intact, error messages verbatim.

**Exception:** Step 10 final report uses normal professional prose (it's posted as a PR comment and read by humans).

## Behavior Contract

- Default: run automatically end-to-end
- Ask user only when scope is unclear, conflicting, risky, or blocked
- TDD is the default execution method for all work

## Step 1: Resolve Input

Detect input type from `$ARGUMENTS`:

- **GitHub issue** `#42` → `gh issue view <n> --json title,body,labels,comments,state,milestone,url`. Extract goal, constraints, acceptance criteria, blocking relationships.
- **Milestone** `milestone:"Version 2"` → `gh issue list --milestone "Version 2" --state open --json number,title,labels,body`. Select exactly one open, unblocked issue in milestone order; execute only that issue this run. None unblocked → report blockers, stop.
- **Inline tasks** `"add dark mode toggle, fix header spacing"` → parse comma-separated tasks or markdown checklist items. No GitHub issue — just execute with TDD.
- No `$ARGUMENTS` → ask user what to execute.

## Step 2: Analyze (GitHub issues only)

Spawn `mp-issue-analyzer` sub-agent to explore + analyze + plan:

> Issue: [title, body, acceptance criteria]
> Codebase: [project root]
>
> 1. Explore the codebase to understand relevant areas (breadth: medium)
> 2. Classify issue type (bug/task/feature) with rationale
> 3. Create execution plan: files to modify/create, behaviors to test (TDD), acceptance criteria mapped to test cases, risk areas and open questions
> 4. If external library behavior is uncertain, note it for Context7 lookup
> 5. If issue body/comments reference design files (e.g. `designs/<slug>/*.html`, `SUMMARY.md`, design brief), read them and extract layout + intent. Map to the existing design system per **Design Mapping** below; record mapping decisions in the plan as implementation constraints.

If analyzer identifies open questions → ask user (clarification gate).

If analyzer identifies external library uncertainty → spawn `mp-context7-docs-fetcher` sub-agent.

### Design Mapping (when issue references mockups)

Mockups are **inspiration, not source of truth.** When the issue links design files:

- Read the linked files before planning.
- **Layout** — match the mockup.
- **Colors** — match intent using existing semantic/theme tokens, even when the mockup uses a raw hex/OKLCH value a token already covers.
- **Components** — reuse existing custom components and variants (e.g. `Button`) instead of inlining raw elements. A significantly different look becomes a new variant of the custom component.
- Pass these mapping decisions to the TDD executor (Step 4) and verify-fix orchestrator (Step 5) as implementation constraints.

## Step 3: Detect Available Checks

Run `node ${CLAUDE_PLUGIN_ROOT}/../mp/scripts/detect-check-scripts.mjs` and parse the key=value output. Store static check commands (`CHECK_ALL`, `TYPECHECK`, `LINT`, `FORMAT`, `BUILD`) and test commands (`TEST`, `TEST_UNIT`, `TEST_E2E`) — passed verbatim to sub-agents in Steps 5, 8d, 9.

**Test commands are first-class checks** — the CI parity gate: if CI runs them, they must pass locally before push.

## Step 4: TDD Execution Loop

Execute the selected issue/task using **red-green-refactor**:

### 4a. Confirm Behaviors to Test

From the analyzer output (or inline task description), list behaviors that need tests. Each acceptance criterion becomes one or more test cases. Ask user to confirm if the list seems incomplete.

### 4b. Execute TDD

Spawn `mp-tdd-executor` sub-agent with:

- The confirmed behaviors list from 4a
- Project context (test framework, file structure, relevant source files)
- Acceptance criteria from the issue/task
- Design Mapping constraints from Step 2 when the issue references mockups
- The test/check commands from Step 3, verbatim

The executor handles the full red-green-refactor cycle for each behavior.

## Step 5: Verify-Fix Loop (delegated)

All checking, reviewing, finding analysis, and fixing happens inside ONE nested orchestrator. Spawn an `mp-check-fixer` sub-agent (omit `model`; it declares its own):

> Inputs:
>
> - check_commands: [static check commands from Step 3]
> - test_commands: [test commands from Step 3]
> - reviewers: [list per flags — see below]
> - context: [issue/task summary, acceptance criteria, Design Mapping constraints from Step 2]
> - changed_scope: [branch + files changed in Step 4]
> - browser_verification: [true only for UI-heavy changes where e2e doesn't cover the interaction]
>
> Return ONLY your JSON contract.

Reviewer list by flags:

- Default: `mp-reviewer-code-quality`, `mp-reviewer-best-practices`, `mp-reviewer-spec-alignment`, `mp-reviewer-test-quality`
- `--full-review`: add `mp-reviewer-security`, `mp-reviewer-performance`, `mp-reviewer-error-handling`
- `--no-review`: empty list (static checks + tests still run — CI parity)

**Route the returned JSON:**

- `"clean"` → continue to Step 6
- `"issues_remaining"` → carry `unresolved_findings` (verbatim) into Step 6 triage; continue
- `"blocked"` → **do not push.** Report `blockers` + `summary` to user and stop. Hard blocker, not an unresolved item.

## Step 6: Unresolved Triage (GitHub issues only)

Collect items that remain unresolved: `unresolved_findings` from Step 5, open questions from Step 2 that couldn't be clarified, edge cases discovered during implementation but out of current issue's scope.

**If no unresolved items → skip to Step 7.**

Spawn `mp-unresolved-issue-tracker` sub-agent:

> Source issue: #<current_issue>
> Unresolved items:
>
> - **<summary>**: <reasoning why unresolved> — <description>
> - ...

The agent finds the parent epic, scans sibling issues for scope match (appends to sibling body if fits), and creates/updates an `Unresolved: [epic title]` tracking issue (labeled `HITL`) for remaining items. See `agents/mp-unresolved-issue-tracker.md` for full logic.

## Step 7: Commit and Push

Spawn `mp-git-committer` sub-agent to stage, commit, and push:

> push: true (for GitHub issues) / false (for inline tasks)
> issue_ref: "refs #N" or "fixes #N" (for GitHub issues)
> commit_hint: summary of implemented behaviors from Step 4

**Handle result:**

- **OK** → continue to Step 8 (GitHub issues) or Step 10 (inline tasks)
- **SKIP** → report "Nothing to commit" — check if push needed
- **FAIL** → diagnose error from agent output. If pre-commit hook failed, spawn `mp-executor` with the concrete fix and re-spawn committer. Up to 2 retries before escalating to user.

## Step 8: Create PR (GitHub issues only)

For inline tasks (no GitHub issue): skip to Step 10.

Spawn `mp-pr-manager` sub-agent to create or update the PR:

> issue_number: N (from Step 1)
> description_hint: summary of changes and behaviors implemented

**Handle result:**

- **OK** → continue to Step 8d
- **FAIL** → diagnose error, fix (spawn `mp-executor` with concrete instructions), re-spawn (up to 2 retries). If still failing → escalate to user.

### 8d. Mergeability, CI, and close-out

After PR creation succeeds, read and follow [CLOSE_OUT.md](CLOSE_OUT.md) for conflict resolution, the mandatory CI gate, final reporting, merging, and worktree sync.

## Rules

> Code quality and git conventions enforced by hooks.

- **TDD is not optional** — every behavior gets a test before implementation
- **Never weaken a correct test to make it pass.** A test may be fixed only when its assertion/selector/setup is demonstrably wrong relative to the acceptance criteria (e.g. invalid CSS selector, stale API contract, wrong role). Document the reason in the commit message.
- **Fix underlying issues** rather than suppressing (`@ts-ignore`, `eslint-disable`)
- **One behavior, one test** — keep tests focused
- **Red before green** — verify the test fails before implementing
- **Minimal green** — write only enough code to pass the test
- **Commit after each issue** — one commit per issue
- **CI is the completion gate** — a run ends when `gh pr checks` shows green, not when local checks pass
- **Main stays out of findings** — raw reviewer output, test failures, and CI logs live in sub-agents; main routes bounded JSON only

## Flags

Auto-merge is the **default** behavior: after CI is green and the final-report comment is posted, the PR is squash-merged and the branch deleted. Use `--no-auto-merge` to opt out.

| Flag              | Effect                                                                             |
| ----------------- | ---------------------------------------------------------------------------------- |
| `--full-review`   | Add security, performance, and error-handling reviewers to Step 5 (7 total)        |
| `--no-review`     | Skip reviewer sub-agents in Step 5 (static checks + tests still run for CI parity) |
| `--no-tdd`        | Skip TDD loop, implement directly (for trivial changes like config updates)        |
| `--no-auto-merge` | Stop after CI green + final-report comment; leave PR open instead of merging it    |