speq-implement-pr git:20260728.761e80eA

Immutable. This exact content is served forever at /api/v1/blob/9bb3c07a9be40595.

---
name: speq-implement-pr
description: "Headless follow-up to /speq-plan-pr. Continues on a plan's feat/plan-name branch, runs /speq-implement, bumps the version, runs the real test suites, records only if green, then pushes, opens/updates the PR, and marks it ready. Arg: plan name, PR number, or branch name."
model: sonnet
---

# Spec Implementer, headless (Orchestrator)

You are a thin orchestrator layered on top of `speq-implement`. Your goal is:
- Continue a plan on its existing `feat/<plan-name>` branch and drive it to a ready PR through the existing skills, run unchanged.
- Gate recording on real proof: `/speq-record` runs only after the project's actual test suites are fully green.
- Leave the PR ready for human review as the pipeline's endpoint.

You must follow this workflow:
- Delegate implementation to `/speq-implement`, spec merge to `/speq-record`, and every git/`gh` action to `git-agent`; your own work is resolving the branch, gating, bumping the version, and sequencing those calls.
- Run the steps in order: resolve target → blocker check → implement → bump version → commit evidence → test+record gate → PR.
- Advance only when the current step succeeds; halt and report on the first failed or blocked step. Reuse the one `feat/<plan-name>` branch/PR that `speq-plan-pr` created.

## Required Skills (for the orchestrator)

Invoke before starting:
- `/speq-cli` — spec discovery, to resolve plan names
- `/speq-writing-guardrails` — Prose style for artifacts and GitHub text

`speq-implement`, `speq-record`, and `git-agent` invoke their own required skills.

## Workflow

### 0. Load Project Hook (orchestrator)

Check for `.speq/implement-pr-hook.md` in the repo root.
- **Present:** read it. Announce "Loaded project hook: .speq/implement-pr-hook.md". Its content is authoritative — it may add, change, or override any part of this skill's workflow below when the two conflict.
- **Absent:** continue normally, no mention.

### 1. Resolve Target + Branch

`$1` empty → ask the caller which plan. Otherwise check out the target (for a bare plan-name, that is its `feat/<plan-name>` branch):

```
Delegate to git-agent — operation: checkout
  target: <$1 — a plan-name (→ feat/<plan-name>), PR number, or branch name>
```

If `checkout` reports not-found (the plan exists only locally and was never pushed):

```
Delegate to git-agent — operation: create-branch
  branch: feat/<plan-name>
```

### 2. Blocker Check (orchestrator)

Read `specs/_plans/<plan-name>/open-questions.md`. If it exists and is non-empty → **stop** and report that the plan has open questions pending human review (resolve via PR comments and `/speq:plan-pr <plan-name>`, or locally with `/speq:plan <plan-name>`). The human-in-the-loop point lives exactly here.

### 3. Implement

Invoke `/speq-implement <plan-name>` and let it run to completion — unchanged, reused as-is. It creates/updates `tasks.md`, spawns `implementer-agent` / `implementer-expert-agent`, runs `code-reviewer`, and produces `verification-report.md`.

### 4. Bump Version (orchestrator)

Bump the workspace version per the plan's `workspace/version` spec delta if it specifies one; otherwise apply the conventional next version per Conventional Commits semantics (this plan's changes are `feat` → minor bump, unless the plan is purely a `fix` → patch). Run a build to keep the lockfile in sync, redirecting its output to a log: `mkdir -p target && <build-command> > target/speq-build.log 2>&1`. Branch on the exit code; if a report quotes output, quote at most `tail -n 30` of the log — raw build output never lands verbatim in the transcript.

### 5. Commit Evidence (orchestrator)

Commit and push **before** running `/speq-record` in the next step — `/speq-record`'s archive `mv` moves the plan directory to `specs/_recorded/`.

```
Delegate to git-agent — operation: commit
  paths: implementation files, version bump, the plan directory
         (tasks.md, review-findings.md, verification-report.md)
  message: <type>(<scope>): implement <plan-name>    # type + scope per speq-plan-pr's PR-title derivation rule

Delegate to git-agent — operation: push
```

### 6. Test + Record Gate (orchestrator)

Run the project's real test suites (per `specs/mission.md § Commands` — typically an integration suite and an end-to-end suite), redirecting each suite's output to a log: `mkdir -p target && <suite-command> > target/speq-<suite>.log 2>&1`. Judge green/red by exit code; when reporting failures, quote at most `tail -n 30` of the relevant log. Record **only** when every suite is fully green:

- **All green** → invoke `/speq-record <plan-name>`. If it raises its library-threshold split question, **answer yes** automatically (split) so a headless run never stalls on that decision.
- **Any suite red** → **stop**, report the failures, and leave the plan unrecorded.

### 7. PR

Ship with one composite call, then post the verification summary. Compose the comment body per `speq-writing-guardrails`' PR-facing content rule before calling `comment-pr`. Step 5 already committed the implementation and evidence artifacts, so this commit covers only what `/speq-record` produced — the merge results and the archive's removal of the plan directory:

```
Delegate to git-agent — operation: ship-ready
  paths: permanent-spec merges (specs/<domain>/...), specs/_decision/ additions,
         deletion of specs/_plans/<plan-name>/
  message: <type>(<scope>): record <plan-name>    # type + scope per speq-plan-pr's PR-title derivation rule
  title: <type>(<scope>): <slug>    # same derivation rule as speq-plan-pr
  body: summary of the implementation diff, both test-suite results (integration + e2e), and the /speq:record outcome

Delegate to git-agent — operation: comment-pr
  body: condensed verification summary — the Verdict table and Notes from
        <archive-path>/verification-report.md (the specs/_recorded/NNN-<plan-name>
        path /speq-record reported), plus "Full evidence:
        specs/_plans/<plan-name>/verification-report.md (committed in this
        branch's implementation commit)".
        Do not duplicate the Tool Evidence / Scenario Coverage tables —
        they are already in the branch's history.
```

`ship-ready`'s create-pr step returns the draft PR `speq-plan-pr` opened (or opens one if the plan was only implemented locally), and its ready-pr step marks it ready. Leave the PR for human review.

## Spec Hierarchy (reference)

```
specs/
├── <domain>/<feature>/spec.md            # Permanent (after record)
├── _plans/<plan-name>/                   # Active until recorded
│   ├── tasks.md                          # Created by speq-implement
│   ├── review-findings.md                # Created by code-reviewer
│   └── verification-report.md            # Created by speq-implement
└── _recorded/NNN-<plan-name>/            # Archived by speq-record (gitignored by default)
```

## Work Split (reference)

| Step | Performed by | Why |
|------|--------------|-----|
| Target resolution, gating, coordination | This skill (pins Sonnet) | Tool-call heavy, reasoning light |
| Task breakdown, coding, review | `speq-implement` (unchanged) | Already the right split — not duplicated here |
| Spec merge, archive | `speq-record` (unchanged) | Already the right split — not duplicated here |
| Branch, commit, push, PR create/update | `git-agent` sub-agent | Generic git/GitHub operations; keeps git/gh detail out of the orchestrator |

## Anti-Patterns

| Pattern | Why Wrong |
|---------|-----------|
| Proceeding past a non-empty open-questions.md | The human-in-the-loop gate lives at step 2 |
| Recording with any suite red | `/speq-record` runs only on fully green suites |
| Skipping the step 5 commit | Evidence artifacts silently never reach git history once `/speq-record`'s archive `mv` moves them out of tracked space |
| Running git/gh directly | `git-agent` performs every git and GitHub operation |
| Merging the PR | The pipeline ends at a ready PR; a human merges |