ship-from-plan

Files (2)

• SKILL.md
• model-map.md · references/

SKILL.md (first lines)

# Ship From Plan

## Overview

Execute one completed implementation plan through isolation, implementation, ready PR creation, CI convergence, and differential-review convergence. Delegate each stage to its owning workflow while this skill owns authorization, transitions, stop conditions, private artifacts, and final readiness.

Invocation grants standing authorization for all AI-resolvable edits, commits, and pushes. Do not pause at nested routine approval gates. Human authority is still required for product, protocol, security-boundary, irreversible-data, and external-compatibility decisions.

Never auto-merge.

## Inputs

Required:

- `PLAN_PATH`: repository-relative path to a completed implementation plan.
- `IMPLEMENTOR_MODEL`: friendly name from `references/model-map.md`.
- `REVIEWER_MODEL`: friendly name from `references/model-map.md`.

Optional:

- `BRANCH_NAME`: derived from the plan filename stem when omitted.
- `WORKTREE_DIR`: passed to `superpowers:using-git-worktrees`.
- `BASE_BRANCH`: passed to `/create-pr --base`; otherwise `/create-pr` resolves the repository default.

If a required input is missing, ask for it before starting Stage 1. Model selection is a required user input, not an environment default.

## Preflight

1. Read `PLAN_PATH` once. Require a writing-plans header and checkbox tasks. Stop if the file is missing or is not an implementation plan.
2. Read `references/model-map.md`.
3. Detect the active environment from runtime agent capabilities.
4. Resolve both friendly model names and confirm they are dispatchable. If either is unavailable, list available identifiers and ask the user to choose; never substitute.
5. Require a Git repository with an `origin` remote.
6. Derive `BRANCH_NAME` from the plan stem when omitted.
7. Detect an existing branch, worktree, or PR using the intended branch name. V1 does not resume across sessions. If ownership cannot be proven for this invocation, stop and report the existing worktree, branch, PR URL, and observable head commit. Do not adopt or duplicate them.

Announce every stage and continue automatically unless a stop condition applies.

## Stage 1: Isolate

Read and follow `superpowers:using-git-worktrees`.

The invocation explicitly requests isolation, so it supplies worktree consent. Detect existing isolation first. Use `BRANCH_NAME` and `WORKTREE_DIR` when supplied.

Run project setup and baseline tests in the isolated worktree.

Overrides:

- If native and Git worktree creation both fail, stop. Never accept an in-place fallback.
- If baseline tests fail, stop with the exact command and failures. Do not implement on an unclean baseline.
- Never implement on `main`, `master`, or the primary checkout.

## Stage 2: Implement

Read and follow the active environment's native `superpowers:subagent-driven-development` workflow against `PLAN_PATH`.

Enforce these portable outcomes:

- Use a fresh implementer for every plan task.
- Every implementer dispatch uses `IMPLEMENTOR_MODEL`.
- Every task receives explicit spec-compliance and code-quality judgment. One combined reviewer or two sequential reviewers are both valid.
- Every task reviewer uses `REVIEWER_MODEL`.
- Resolve review findings through the native review loop.
- Run a final whole-branch review with `REVIEWER_MODEL`.
- Return control to this skill after the final review and before `superpowers:finishing-a-development-branch`.

Never downgrade, upgrade, or substitute the selected role models.

Handle implementer status:

- `DONE`: enter the native review loop.
- `DONE_WITH_CONCERNS`: resolve correctness and scope concerns before review; record non-blocking observations.
- `NEEDS_CONTEXT`: supply focused context and redispatch with the same model.
- `BLOCKED`: supply context, decompose the task, and redispatch with the same model. Stop only when resolution requires a different model or a human-owned change to the plan contract.

Do not impose a fixed retry count on context enrichment or task decomposition. Do not invoke `finishing-a-development-branch`.

## Stage 3: Create a Ready PR

Require a named feature branch. Push it before PR creation:

```bash
set -euo pipefail
BRANCH="$(git branch --show-current)"
test -n "$BRANCH"
git push --set-upstream origin "$BRANCH"
```

Record `HEAD` before invoking create-PR.

Invoke `/create-pr`. Add `--base "$BASE_BRANCH"` only when the user supplied `BASE_BRANCH`; otherwise allow `/create-pr` to resolve the configured repository default. Standing authorization covers its routine preview and any AI-resolvable `/doc-update` changes. Preserve create-PR sensitive-content scrubbing.

Require a PR number and URL. The PR is ready for review by default. If it is draft, mark it ready:

```bash
set -euo pipefail
if [ "$(gh pr view "$PR_NUMBER" --json isDraft --jq .isDraft)" = "true" ]; then
  gh pr ready "$PR_NUMBER"
fi
```

Stop if creation fails or the PR cannot be marked ready. Do not run `gh pr ready --undo`.

If `/create-pr` changed `HEAD`, run another whole-branch review with `REVIEWER_MODEL`, resolve every AI-owned finding, and push the reviewed head before Stage 4.

## Stage 4: Converge CI

Wait for every check on the current PR head to reach a terminal state. Polling while checks run does not count as a fix round.

If all checks pass, continue to Stage 5.

If no checks exist, stop because readiness cannot be established.

For a terminal failing head:

1. Invoke `/fix-ci` for the PR.
2. Analyze all failures before editing.
3. Treat this invocation as standing authorization for every AI-resolvable fix and the resulting commit.
4. Skip nested per-fix and commit approval prompts.

From kyzooghost/skills, MIT.

More from kyzooghost/skills