--- name: pstack-pr preamble-tier: 3 version: 0.2.0 description: | End-of-implementation review and PR creation. Enforces conventional commits, orchestrates the full review gauntlet (gstack /review, /codex review + challenge, optional /qa and /design-review for UI changes, /health for the quality score), prompts for anti-patterns, opens the PR with the standard pstack body template. Stays on `gh` + local git (developer-side; PMs and non-tech users don't open PRs). Use when asked to "open PR", "/pstack-pr", "ship this branch". triggers: - /pstack-pr - open PR - ship this branch - ready for review allowed-tools: - Bash - Read - Write - Skill --- # pstack-pr End-of-implementation review and PR creation. ## Skills orchestrated | Skill | When | |---|---| | gstack `/review` | Step 3 — pre-landing diff review for structural issues (SQL safety, LLM trust boundaries, conditional side effects) | | gstack `/codex review` | Step 3 — independent diff review with a pass/fail gate; cross-model coverage of what Claude's review might miss | | gstack `/codex challenge` | Step 3 (optional) — adversarial pass, tries to break the diff | | gstack `/qa` | Step 3 (conditional) — when frontend files changed, walk through the actual app and find bugs | | gstack `/design-review` | Step 3 (conditional) — when frontend files changed, audit visual polish against the project's design system | | gstack `/health` | Step 3 — quality dashboard score on the diff; tracks trend over time | | `pstack-anti-pattern` | Step 5 — log failed approaches surfaced during work | ## Steps ### 1. Verify branch state - Branch is pushable (no uncommitted changes) - Branch tracks remote (`gh repo set-default` if needed) - Linked issue number is known (from branch name or asked) ### 1.5. Enforce conventional commits Validate every commit on the branch against the [Conventional Commits](https://www.conventionalcommits.org/) format. Catches non-compliant messages early — before review pipeline cost — and keeps `release-please`, gstack `/retro`, and downstream changelog tooling working. ```bash BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' || echo main) # Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert # Optional scope in (parens), optional ! for breaking change PATTERN='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?: .+' BAD=$(git log "origin/$BASE..HEAD" --format='%h %s' | grep -vE "$PATTERN" || true) if [ -n "$BAD" ]; then echo "✗ Non-conventional commits found:" echo "$BAD" echo echo "Fix with one of:" echo " - git commit --amend (most recent commit)" echo " - git rebase -i origin/$BASE (older commits, use 'reword')" echo " - Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert" echo " - Format: (): " exit 1 fi ``` If any commit fails, **stop**. Show the user the offending commits and the fix options. Do not proceed to the review pipeline. Skip merge commits if the project uses merge-commit workflow (per repo's `CLAUDE.md` branching policy) by adding `--no-merges` to the `git log` call. ### 2. Local build pipeline Run the project's local checks. Each must pass before proceeding: ```bash pnpm typecheck # or: npx tsc --noEmit pnpm test pnpm lint ``` If any fails, surface the failure. Do not proceed to the review skills in Step 3 — they spend tokens/time and shouldn't run against a broken branch. ### 3. Review gauntlet Run review skills in order. Each one's output should be surfaced; serious findings stop the workflow until resolved. **3a. gstack `/review`** — pre-landing structural review against the base branch. Catches SQL safety issues, LLM trust boundary violations, conditional side effects. Required. **3b. gstack `/codex review`** — independent diff review by Codex. Cross-model coverage catches what Claude misses. Has a pass/fail gate — if it returns FAIL, stop and address findings before continuing. **3c. gstack `/codex challenge`** (optional but recommended for risky changes) — adversarial pass. Tries to break the diff. Run when: - Auth / payment / data-destruction code changed - Cross-cutting refactor with >200 lines diff - The dev has uncertainty about edge cases **3d. Detect scope** — check which categories of files changed: ```bash BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main) CHANGED=$(git diff --name-only "origin/$BASE...HEAD") # Frontend signal echo "$CHANGED" | grep -qE '\.(tsx|jsx|css|scss|svelte|vue)$|^(apps/web|packages/ui)/' && FRONTEND=true || FRONTEND=false # Backend signal echo "$CHANGED" | grep -qE '\.(rs|go|py|rb)$|^(apps/api|services/)/' && BACKEND=true || BACKEND=false ``` **3e. gstack `/qa` (conditional)** — if `$FRONTEND` is true and the project has a dev server, invoke `/qa` to actually walk through the changed flows in a browser and find bugs. Iteratively fixes what it finds (use `/qa-only` if you want report-only). Skip if no dev server. **3f. gstack `/design-review` (conditional)** — if `$FRONTEND` is true, audit visual polish against the project's design system (audit-only — does NOT impose new patterns). Skip for backend-only diffs. **3g. gstack `/health`** — code quality dashboard score on the diff. Track the trend over time. Doesn't block, but note the score in the PR body. **3h. Plan-alignment check** — if a spec exists (frozen at `docs/specs/.md` from `/pstack-execute`), confirm the diff matches the spec's acceptance criteria. Use `superpowers:requesting-code-review` to dispatch a fresh-context reviewer subagent that checks acceptance-criteria-by-acceptance-criteria. Flag any scope drift. If any review surfaces blockers, stop the workflow. The dev addresses them and re-runs `/pstack-pr` from Step 1. ### 4. Generate PR description Render `${CLAUDE_SKILL_DIR}/../../templates/pr-description.md` filling in: - Closes: link to issue - Spec: link to Epic body (drafty) and `docs/specs/.md` (frozen, if first story) - What changed: bullet list with file:line citations - What didn't change: any preserved invariants - How tested: test paths + manual verification + gstack `/qa` results if run - Review summary: outcomes of `/review`, `/codex review`, `/qa`, `/design-review` (one line each) - Health score: from `/health` - Alternatives considered: required (link anti-patterns entries if any) - Risk: low/medium/high + one-sentence rationale - Reviewer focus: 1–3 bullet areas ### 5. Anti-pattern prompt Ask: > "Any failed approaches during this work that should be logged in > `docs/anti-patterns.md`? (y/N)" If yes, invoke `pstack-anti-pattern` skill. ### 6. Open PR ```bash gh pr create \ --title "" \ --body-file \ --base \ --head ``` If repo conventions require a project link (e.g., periant), add: - `--project ` ### 7. Report URL Print the PR URL. ## GitNexus integration In Step 4 (Generate PR description), add an "Affected dependencies" section to the body when GitNexus is running: ```bash if GITNEXUS=$(${CLAUDE_SKILL_DIR}/../../scripts/gitnexus-check.sh); then BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || echo main) CHANGED_FILES=$(git diff --name-only "$(git merge-base HEAD "$BASE")" HEAD) for file in $CHANGED_FILES; do ${CLAUDE_SKILL_DIR}/../../scripts/gitnexus-query.sh affected "$file" 2>/dev/null || true done | sort -u fi ``` Include the deduplicated list of affected packages/modules in the PR body so reviewers see blast radius up-front. If GitNexus is unreachable, omit the section. Do not block PR creation on GitNexus availability. ## Do not - Do not skip the review gauntlet in Step 3. - Do not skip conditional gstack skills when their signals are positive (frontend changed → run `/qa` + `/design-review`). - Do not call gstack's design-generation skills (`/design-shotgun`, `/design-consultation`, `/design-html`). Only the audit-side ones (`/design-review`). - Do not auto-merge. - Do not push --force. - Do not pass a Codex `[P1]` finding silently — surface it to the user with options.