implementation-kickoff

---
name: implementation-kickoff
description: Carry implementation through an isolated worktree and local handoff. Use only when this skill is explicitly invoked.
---

# Implementation Kickoff

Use this skill as the explicit transition from an agreed implementation scope to isolated execution. Keep the user's original checkout and existing branches unchanged, and finish with a clean local branch that is ready for the user to push.

## Non-negotiable boundaries

- Treat explicit invocation of this skill as authorization to fetch, create one dedicated worktree, rebase or replay task-owned changes, create the final local branch, stage task-owned files, and create one local commit. It never authorizes push, pull-request creation, or any GitHub mutation.
- Do not start during an investigation-only phase or before a required user approval. Finish planning and any required implementation scope contract first.
- Use read-only GitHub access when remote PR evidence is required.
- Preserve unrelated and user-owned changes. Do not remove an existing worktree or rewrite an existing branch to make room for this workflow.

## 1. Establish the task boundary

Record the original requirement, success criteria, intended target (`origin/main` unless the user states otherwise), task-owned paths, compatibility boundary, intentionally unsupported cases, and required repository skills. For a multi-step task, create and maintain the repository's required ExecPlan. An ExecPlan, review packet, ledger, trace, or temporary report is operational-only by default even when repository policy requires creating it; do not add it to the shipped-path manifest unless the original requirement or repository policy explicitly makes that exact path a committed deliverable.

If the current directory is a worktree previously created for this same task in the current conversation, resume it. Otherwise, continue from the user's current checkout only long enough to create a new worktree.

## 2. Create a detached worktree from current main

1. Verify the source checkout's raw status without modifying it.
2. Fetch `origin main`. If the fetch fails, stop rather than claiming a stale ref is current.
3. Record the fetched `origin/main` commit.
4. Choose a unique task-oriented path under the configured Codex worktree root. Check both the filesystem and `git worktree list`; never reuse or delete a collision.
5. Run `git worktree add --detach <worktree> origin/main` and perform all subsequent implementation work there.
6. Confirm the new worktree is detached at the recorded commit and initially clean.

Do not create the final branch yet. A detached worktree makes the eventual `$pr-draft-summary` branch suggestion authoritative and prevents temporary naming from becoming accidental output.

## 3. Implement without task commits

Keep the task diff uncommitted through implementation, focused tests, formatting, and review fixes. Track new files explicitly because ordinary diff statistics omit untracked files. Maintain one canonical shipped-path manifest separately from operational artifacts and require a concrete deliverable reason for every path in it. Use the applicable repository skills and references, including `$implementation-strategy` before user-facing or runtime changes.

When the task can be decomposed without temporarily breaking a supported contract, implement one narrow end-to-end behavior slice at a time and run its focused test before adding the next slice. Do not force cross-cutting migrations or atomic compatibility changes into artificial slices that cannot remain valid independently.

Do not create checkpoint commits. If an external interruption requires extra protection, leave the dedicated worktree intact or use a clearly named temporary stash; restore the changes before continuing and do not treat the stash as a deliverable.

### Taking over an existing pull request

When the user asks to complete another author's pull request:

1. Refresh the PR metadata, head, discussion, and complete three-dot diff through read-only access.
2. Confirm that the PR is still an appropriate takeover source. Do not treat an already merged PR as an active takeover.
3. Apply the original PR's complete task diff onto the worktree based on current `origin/main`; do not derive the final branch from the contributor branch and do not preserve its intermediate commit topology.
4. Record the original PR number, PR author login, verified commit identity, existing valid `Co-authored-by` trailers, linked issues, and the original intent that the replacement must preserve.
5. If a valid author identity cannot be obtained from the PR's commits, stop before committing and ask the user. Never invent an email address.

## 4. Replay the complete task onto the latest main

After implementation, focused tests, and formatting are stable, fetch `origin main` again. If it advanced:

1. Confirm that every local change is task-owned.
2. Save tracked and untracked task changes in a uniquely named temporary stash.
3. Rebase the detached HEAD onto `origin/main`. With no task commits, this updates the empty local commit range to the new base.
4. Reapply the stash and confirm it was removed only after a clean application.
5. Resolve conflicts only when the requirement and surrounding source make the correct result unambiguous. Otherwise preserve the stash and conflict evidence, then stop for user direction.
6. Rerun formatting and every focused check affected by the new base.

Record this observed `origin/main` commit as the final-base candidate. Do not call an older base "latest" merely because its changes appear unrelated.

## 5. Complete final review and verification

Run applicable completion gates against the complete task-owned diff on the final-base candidate. Apply formatting and safe hook-equivalent normalization before review, including generated-file provenance checks where relevant. Use `$implementation-final-review` to select lightweight, ordinary, or high-risk review; supply all task-owned untracked file contents as well as tracked changes. Only high-risk review requires `review_state.py --complete-diff-output <complete.diff>` and the strict packet/ledger protocol. Follow the selected procedure's evidence and invalidation rules.

After clean review, run `$changeset-validation` when packages or changesets changed and `$code-change-verification` whenever its SDK eligibility rules apply. Lightweight review does not waive an otherwise required SDK stack. Repo-meta work uses its applicable skill and focused checks. Do not create the branch or commit while required review, verification, or evidence remains incomplete.

## 6. Generate the complete PR handoff

Invoke `$pr-draft-summary` only after review and every applicable final repository gate apply to the final content. Give it a self-contained packet containing the original requirement, implementation scope contract, important decisions and intent, complete changed-path inventory including untracked files, final diff and statistics, compatibility notes, issue references, and takeover provenance.

The worktree is intentionally detached. Tell `$pr-draft-summary` to treat the current branch value `HEAD` as "no branch yet" and require a concrete unused branch-name suggestion; never accept `HEAD` as the suggestion. The description must explain the complete final change and its motivation, not only the last review fix.

For a takeover, begin the description with prose such as `This pull request supersedes #<number> and ...`. Preserve any separate issue-closing line only when the final implementation actually resolves that issue.

If the diff, scope, base, behavior claim, issue relationship, or provenance changes after generation, regenerate the entire PR handoff.

## 7. Recheck main and create one commit

Fetch `origin main` once more immediately before creating the branch. If it differs from the final-base candidate, return to section 4 and replay onto the new base. Apply the selected review tier's base-change rules in `$implementation-final-review`; only high-risk work uses the verified base-advance closure in [high-risk-review.md](../implementation-final-review/references/high-risk-review.md) step 20. Recheck relevant upstream dependencies and tooling before retaining review evidence. Rerun applicable final verification on the new base and regenerate the PR handoff; obtain affected independent re-review whenever the selected tier requires it. Once stable:

1. Check whether the suggested branch exists locally, remotely, or in another worktree. Ask `$pr-draft-summary` for the next available numeric suffix and regenerate the handoff before creating a colliding branch.
2. Create the exact suggested branch in the task worktree.
3. Stage only the task-owned shipped-path manifest, including intended new files. Compare the staged changed-path set byte-for-byte with the canonical shipped manifest before committing; any missing or unexpected path is a hard stop. In particular, do not stage an ignored ExecPlan or review artifact merely because it was required during implementation.
4. Use the PR draft title as the commit subject.
5. For a takeover, add the verified original PR author as `Co-authored-by: Name <email>`, retain distinct valid co-author trailers from the imported commits, and deduplicate identities.
6. Create exactly one commit. Let repository hooks run normally.

Branch creation and committing identical content are repository bookkeeping and do not invalidate clean content review. If a hook or manual fix changes task content, stop, classify the change under `$implementation-final-review`, and rerun every invalidated gate and `$pr-draft-summary` before replacing or amending the commit.

## 8. Validate and hand off

Run `python3 .agents/skills/implementation-kickoff/scripts/validate_handoff.py --repo <worktree> --base <final-base> --expected-branch <branch> --shipped-path-manifest <manifest>`. For a takeover, also pass `--required-trailer-email <verified-email>` for each identity that must be credited. The shipped-path manifest must be a finite regular file whose type and content are read from one opened descriptor. It contains one exact repository-relative shipped path per line and excludes operational artifacts.

Independently confirm that the committed diff has the reviewed content fingerprint when final review supplied one. The validator checks Git topology and repository cleanliness; it does not replace semantic review or fingerprint verification.

Leave the worktree in place. Report the worktree path, final observed base commit, branch, commit SHA and subject, verification results, review status, PR title and description, and whether takeover provenance was included. Treat the worktree path and validator output as local diagnostics: never include them in the PR title, PR description, or other copy-ready external text. State explicitly that nothing was pushed and no pull request was created.

## Failure behavior

- Fetch failure: stop without creating or updating the final branch.
- Worktree or branch collision: preserve the existing target and choose a new unused path or regenerated branch suggestion.
- Replay conflict: retain recoverable task changes and ask for direction when the correct resolution is ambiguous.
- Review or verification failure: leave the detached task worktree for continuation; do not package a commit as ready.
- Commit-hook mutation: invalidate affected evidence, fix the missing hook-parity preflight or generated-file normalization, and repeat the required gates.
- Non-clean or multi-commit final state: do not hand off as complete until corrected without discarding user-owned work.

From openai/openai-agents-js at 05241c7, shown as plain text under its license: MIT (permissive). The license text is in LICENSE.

• SKILL.md12 KB · c2e9b89d5077
• agents/
• openai.yaml300 B · f1c44f4e076c
• scripts/
• test_validate_handoff.py11 KB · 8741b7ab0a0b
• validate_handoff.py11 KB · 19d0ee797552

4 files, 34 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.