Create Feature PR

Contract

Prereqs:

• Run inside the target git repo with a clean working tree (or stash unrelated changes).
• git and gh available on PATH, and gh auth status succeeds.
• $AGENT_HOME points at the repo root (or tools are otherwise available).

Inputs:

• Required: feature summary + acceptance criteria.
• Optional: kickoff artifacts already prepared (for example plan/progress/scaffold/docs files) to commit before opening the PR.
• Optional (only when this feature PR is created from a progress PR): planning PR number and progress file reference.

Outputs:

• A new branch feat/<slug>, one or more commits, and a GitHub draft PR created via gh.
• PR title/body describe the target feature outcome (not a kickoff commit subject).
• When kickoff artifacts already exist, they can be committed first and used to open the draft PR before implementation code lands.
• PR body populated from references/PR_TEMPLATE.md (include a full GitHub URL to the progress file when provided).

Exit codes:

• N/A (multi-command workflow; failures surfaced from underlying git/gh commands)

Failure modes:

• Dirty working tree or wrong base branch.
• Missing gh auth or insufficient permissions to push/create PR.
• Missing feature summary/acceptance criteria (cannot produce an outcome-oriented PR).
• PR title/body follows a housekeeping commit subject (for example Add plan file) instead of the feature outcome.
• PR body missing required sections; if using a progress file, missing/invalid progress link.

Preflight (mandatory)

1. Confirm runtime intent:
   • kickoff-only: open draft implementation PR now, implementation continues later.
   • kickoff+implementation: open draft PR now and continue implementation in the same turn.
2. Collect required feature context:
   • feature summary + acceptance criteria (required before PR creation).
   • optional progress file URL and/or planning PR number.
3. If summary/criteria are missing:
   • ask for a 1-2 sentence feature outcome and expected behavior.
   • do not derive PR title/body from git log -1 --pretty=%B.
4. Confirm kickoff artifacts in scope (if present) and commit them before opening the PR.

Inputs

• Prefer explicit user feature description and acceptance criteria.
• If still unclear, ask for a 1-2 sentence feature summary and expected behavior.
• Do not use a latest commit subject as PR narrative input; commits like Add plan file are not valid PR title/body sources.
• Existing plan/progress/scaffold files can be committed first, then used to open the draft PR.

Branch naming

• Prefix: feat/.
• Build the slug from the feature summary.
• Slug rules: lowercase; replace non-alphanumeric with hyphens; collapse hyphens; trim to 3-6 words.
• If a ticket ID like ABC-123 appears, prefix it: feat/abc-123-<slug>.

Workflow

1. Run preflight (above) and stop if feature summary/acceptance criteria remain missing.
2. Confirm the working tree is clean; stash or commit unrelated changes if needed.
3. Determine the base branch (default origin/HEAD); ask if unclear.
4. Create the branch: git checkout -b feat/<slug>.
5. If kickoff artifacts already exist (plan/progress/scaffold/docs), commit them first:
   • use $semantic-commit-autostage skill by default.
   • implement it via the autostage flow defined by that skill (git add + semantic-commit ...).
   • use semantic-commit only when the user has explicitly staged a reviewed subset.
6. Generate PR body from references/PR_TEMPLATE.md.
7. Push the branch and open a draft PR immediately:
   • gh pr create --draft ...
8. Continue implementation on the same PR (code + tests), updating PR body/testing notes as progress changes.

PR rules

• Title: capitalize the first word; reflect the feature outcome; never mirror a housekeeping commit subject.
• Replace the first H1 line in references/PR_TEMPLATE.md with the PR title.
• Body narrative (Summary, Changes, Risk / Notes) must describe the intended feature outcome even when the first commit is kickoff-only.
• Progress (optional):
  • Use this section only when the feature PR is derived from a progress PR.
  • Generate by passing --from-progress-pr plus either:
    • --progress-url <full-github-url>, or
    • --progress-file docs/progress/<file>.md (script auto-resolves full URL from origin remote + current branch).
  • If no progress file, omit the ## Progress section entirely (do not write None).
• Planning PR (optional):
  • Use this section only when the feature PR is derived from a progress PR.
  • If this feature work follows a planning PR, add ## Planning PR and reference it as - #<number> (no extra text/URL).
  • If no planning PR, omit the ## Planning PR section entirely (do not write None).
• Always include Summary, Changes, Testing, and Risk/Notes sections.
• If tests are not run, state "not run (reason)".
• Use $AGENT_HOME/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh --pr to generate the PR body quickly.
  • Non-progress flow: run with --pr only (no Progress/Planning PR sections).
  • Progress-derived flow: add --from-progress-pr --planning-pr <number> and either --progress-url <full-github-url> or --progress-file docs/progress/<file>.md.
• Open draft PRs by default; only open non-draft when the user explicitly requests it.

Output

• Use references/ASSISTANT_RESPONSE_TEMPLATE.md as the response format.
• Use $AGENT_HOME/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh --output to generate the output template quickly.