@groupby/ai-dev 0.5.13 → 0.5.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "Interactive installer for Rezolve Ai development content",
   "type": "module",
   "bin": {

package/teams/brain-studio/skills/arch-context/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: arch-context
+description: Provides standardized procedures for loading the minimum required architecture documentation for any agent workflow in this repository — if `.github/copilot-instructions.md` exists, reading it and applying its Doc Routing Table to the detected change types; otherwise consulting `docs/architecture/` directly if present — then loading each required doc and noting any gaps. Outputs a `<loaded-docs>` list and `<arch-constraints>` summary consumed by downstream review and planning workflow steps (whether skills or prompts). Auto-apply before any prompt that must evaluate code or plan changes against project architecture standards.
+---
+
+# Architecture Context Guide
+
+## Relationship to other repository skills
+
+- the git-context skill — must be read first; `<change-types>` produced there is the
+  primary input to this skill's routing step.
+
+This skill governs *which* architecture docs to load and *how* to apply them. The docs
+themselves (under `docs/architecture/`, if present) are the source-of-truth for architecture
+decisions and override this skill when they conflict.
+
+## Mandatory application (agents)
+
+Whenever a prompt must evaluate or plan changes against project architecture standards:
+
+1. **Confirm `<change-types>` is available** from the git-context skill.
+2. **Read this skill file** before opening any architecture doc.
+3. Follow the **Working method** steps in order.
+4. Do not load docs outside those mapped by the routing table unless the task explicitly
+   requires it — always document why in a `## Documentation Gaps` note.
+
+This skill is optional for purely mechanical tasks (e.g. renaming a file) where no
+architecture evaluation is needed.
+
+## When to use
+
+- Before a code review — to know which docs govern the changed files.
+- Before writing an implementation plan — to understand architectural constraints.
+- Before writing a PR description that references architectural patterns.
+- Any time a prompt says "load the architecture docs" or "apply the routing table".
+
+## When not to use
+
+- The task is exclusively about workflow (git commands, Jira, CI) with no code changes.
+- The caller has already identified and loaded the required docs in the current session.
+
+## Truthfulness and claims
+
+- Do not claim a doc was loaded if it was not — unavailable docs must be noted.
+- Do not invent architecture rules not found in the loaded docs.
+- If the codebase contradicts a loaded doc, the doc represents the target state — flag
+  the discrepancy; do not normalise the legacy pattern.
+- Do not load `docs/architecture/README.md` or `docs/architecture/00-developer-quick-start.md`
+  — those are human-facing indexes, not agent context.
+
+## Self-contained operating mode
+
+The routing table (embedded below, or in `.github/copilot-instructions.md` if present)
+is the canonical map for this project. Always apply it from the `<change-types>` list.
+Do not apply generic online advice about architecture documentation loading — use this
+table only.
+
+---
+
+## Embedded implementation standard
+
+### 1) Always-load doc
+
+Regardless of change type, always load (if present):
+
+```
+docs/architecture/12-code-conventions/README.md
+```
+
+This is the baseline for all code-generation and review tasks.
+
+### 2) Doc Routing Table
+
+If `.github/copilot-instructions.md` exists and contains the Doc Routing Table, apply
+each row whose **Change type** appears in `<change-types>` and load the additional docs
+listed in the **Load these extra docs** column. Otherwise, if `docs/architecture/` is
+present, load the applicable docs from the routing table below for each change type.
+
+| Change type | Load these extra docs |
+|-------------|-----------------------|
+| Styling / styled-components | `docs/architecture/12-code-conventions/04-styled-components.md`, `docs/architecture/12-code-conventions/12-css-antipatterns.md` |
+| New component or hook | `docs/architecture/01-system-overview-tech-stack.md`, `docs/architecture/02-module-structure/README.md`, `docs/architecture/03-state-management.md` |
+| API / data fetching | `docs/architecture/03-state-management.md`, `docs/architecture/04-data-flow-api.md` |
+| Auth / permissions | `docs/architecture/05-authentication.md` |
+| Tenant / area / collection scoping | `docs/architecture/06-tenant-and-data-context.md` |
+| Feature flags | `docs/architecture/07-feature-flags.md` |
+| Utilities / shared services | `docs/architecture/08-services-utilities.md` |
+| External integrations | `docs/architecture/09-external-integrations.md` |
+| Config / build | `docs/architecture/10-build-deployment.md` |
+| Test changes | `docs/architecture/11-testing-strategy/README.md` |
+
+> `docs/architecture/13-git-workflow.md` (if present) is **developer-facing only**. Load
+> it only when drafting a commit message or PR title.
+
+### 3) Load procedure
+
+For each doc identified in steps 1 and 2:
+
+1. Open the file and read its full content.
+2. Follow any cross-links it contains to additional referenced docs.
+3. If a doc cannot be loaded (file missing, permission error), record it in
+   `<missing-docs>` and note it in the `## Documentation Gaps` section of the output.
+
+### 4) Record loaded docs
+
+After loading, store:
+
+- `<loaded-docs>` — list of every doc path successfully loaded.
+- `<missing-docs>` — list of every doc that could not be loaded (empty if none).
+- `<arch-constraints>` — a one-sentence summary of the key constraint each doc imposes,
+  for quick reference during review or planning.
+
+---
+
+## Working method (apply in this order)
+
+1. **Baseline** — Always load `docs/architecture/12-code-conventions/README.md` first
+   (if present).
+2. **Route** — For each entry in `<change-types>`, apply the routing table in §2 and
+   collect the additional docs to load.
+3. **Load** — Open and read each identified doc; follow any intra-doc cross-links.
+4. **Record** — Populate `<loaded-docs>`, `<missing-docs>`, and `<arch-constraints>`.
+5. **Report** — Return `<loaded-docs>` to the caller; include `<missing-docs>` in a
+   `## Documentation Gaps` note if non-empty.
+
+## Quality bar before final answer
+
+- `<loaded-docs>` lists every doc that was actually read — not intended to be read.
+- The always-load baseline doc appears first in `<loaded-docs>`.
+- No doc from outside the routing table was loaded without an explicit justification.
+- `<missing-docs>` is present and either empty or lists actual failures.
+- `docs/architecture/README.md` and `docs/architecture/00-developer-quick-start.md` do
+  not appear in `<loaded-docs>`.
+- Architecture rules cited in subsequent output come from `<loaded-docs>` — not invented.
+

package/teams/brain-studio/skills/draft-plan/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: draft-plan
+description: Use when the user invokes `/draft-plan` (or asks to "draft a plan", "plan this spec"). Only runs when explicitly invoked — do NOT auto-trigger on the word "plan".
+---
+
+# draft-plan
+
+Turn a spec into a discussed, approved, high-level implementation plan.
+This is **Step 3** of the AI-assisted development workflow.
+
+## Inputs
+
+- **Spec file path** — typically `.ai/tasks/{KEY}/spec.md`. The user may pass
+  it explicitly (`/draft-plan S4R-10559`) or by ticket key.
+- **If no argument is given:** list all `spec.md` files in `.ai/tasks/*/`
+  with their last-modified dates and ask which one to plan.
+- **If no spec.md exists** (no argument given and none found under
+  `.ai/tasks/*/`, or an explicit key/path was given but the file is missing):
+  do **not** guess or fabricate a spec, and do **not** silently proceed with
+  nothing. Ask the user for a ticket key or a spec-file path. Mentioning
+  `/jira-spec` as one possible next step is fine, but the skill must stop and
+  wait for the user's answer rather than assuming that path.
+- **Do not invent a spec.** If no matching spec file exists, stop and tell the
+  user to run `/jira-spec` first.
+
+## Workflow
+
+### 1. Read the spec verbatim
+
+- Read the entire spec file.
+- Pay attention to: Original Description, Acceptance Criteria, AI-gathered
+  Implementation Notes, Open Questions. The first two are authoritative; the
+  third is a starting hypothesis, not a constraint.
+- Note the slug from the spec metadata (for branch naming consistency).
+
+### 2. Load architecture docs, if available
+
+Using the change types identified in the spec (or inferred from its content):
+
+1. **If `docs/architecture/12-code-conventions/README.md` exists,** always
+   load it first.
+2. **If `.github/copilot-instructions.md` exists,** apply the Doc Routing
+   Table it defines:
+   - Component/hook → `01-system-overview`, `02-module-structure`, `03-state-management`
+   - Styling → `docs/architecture/12-code-conventions/04-styled-components.md`, `docs/architecture/12-code-conventions/12-css-antipatterns.md`
+   - API/data → `03-state-management`, `04-data-flow-api`
+   - Tests → `11-testing-strategy/README.md`
+   - etc.
+3. **Load `.ai/patterns.md`** if it exists — check for relevant past solutions.
+4. Follow cross-links within loaded docs.
+
+If neither `docs/architecture/` nor `.github/copilot-instructions.md` exists
+in this repo, skip this step and rely on direct codebase investigation
+instead.
+
+### 3. Investigate the codebase (deeper than `/jira-spec`)
+
+The spec used **medium-depth** scanning. This skill uses **deep** scanning.
+For each likely touch point:
+
+- Read the relevant files **end-to-end**, not just excerpts.
+- Trace data flow across layers (e.g. component → hook → Redux slice →
+  API client) for any feature that crosses them.
+- Identify shared abstractions the change must conform to (factories,
+  interfaces, base classes, validators, mappers).
+- Find related tests in `test/unit/` and `test/integration/` — understand
+  the existing test shape before proposing new tests.
+- If `docs/architecture/` exists, check its cross-links for constraints the
+  plan must respect.
+- Run `git log --oneline -- <path>` on key files to see recent changes that
+  suggest active areas / patterns.
+
+Time-box this: deep does not mean exhaustive. Stop when you can describe the
+shape of the change confidently.
+
+### 4. Draft the plan structure (in chat, not yet written)
+
+Present the plan to the user in chat first, using this shape:
+
+```markdown
+# Plan — {KEY}: {short summary}
+
+## Goal
+<1–2 sentences in plain English. Tied to the spec's Acceptance Criteria.>
+
+## Approach
+<3–6 sentences describing the chosen direction. Why this shape rather than
+alternatives. Reference architecture docs where they constrain the choice.>
+
+## Affected areas
+
+### <Module or layer 1, e.g. "src/search-for-retail/filters/">
+- `path/to/file` — what role this file plays in the change
+- `path/to/other` — likewise
+
+### <Module or layer 2>
+- ...
+
+### Tests
+- `test/unit/...` — existing tests to extend
+- `test/integration/...` — integration tests to add/update
+- Use custom `render()` from `test-utils.tsx` for component tests
+
+(Group by module/layer, not by file. Include test paths explicitly.)
+
+## Sequencing
+1. <First phase — what gets done, in what order, why this order>
+2. <Second phase>
+3. <Third phase>
+
+(Each phase should be independently committable / verifiable where possible.)
+
+## Test strategy
+TDD applies by default: failing tests are written before each implementation
+phase (Red → Green → Refactor). Note any phase that is exempt and why
+(e.g. pure config change with no testable behaviour).
+- <Which existing test files will be extended; which new tests are needed>
+- <Unit tests in test/unit/, integration tests in test/integration/>
+- <Follow conventions from `docs/architecture/11-testing-strategy/`, if present>
+
+## Risks & open questions
+- <Anything that could derail the plan.>
+- <Anything the spec leaves ambiguous that the user should decide.>
+
+## Out of scope
+- <Explicit non-goals — things that look related but won't be addressed.>
+```
+
+### 5. Discuss with the user
+
+After presenting the plan, ask the user:
+
+> *"Does this plan capture the right approach? Reply `approve` to write
+> the plan to a file, or tell me what to change."*
+
+Iterate:
+- If the user asks "why X over Y?" — explain, update plan if needed.
+- If the user asks for more detail on an area — investigate further and add.
+- If the user disagrees — revise. Do not write a plan the user hasn't endorsed.
+- Track decisions made during discussion in a "Decisions during planning"
+  section.
+
+### 6. Write the plan on approval, then stop
+
+Trigger: user replies `approve` (or equivalent).
+
+- **Output path:** `.ai/tasks/{KEY}/plan.md`
+- **If the plan file already exists,** ask before overwriting.
+- Write the plan using the same structure as the in-chat preview, plus:
+  - A header block with the spec file, ticket key, slug, and the date.
+  - A "Decisions during planning" section capturing anything clarified.
+- After writing, report the path and remind of next steps:
+
+> *"Plan saved at `.ai/tasks/{KEY}/plan.md` (local-only — `.ai/` is gitignored).
+> Next: run `/tdd-implement` when ready."*
+
+**Then stop.**
+
+### What "stop" means after approval
+
+Approval authorizes **writing the plan file — nothing else.** Do **not**:
+
+- Start implementation, even partially.
+- Edit any source file, test, config, or build file.
+- Create a branch, stage changes, or run a build / test / lint.
+- Suggest next actions beyond the single closing line.
+
+## Plan Revision
+
+If during implementation the plan proves wrong, a `## Revision` section is
+**appended** (not overwritten). Format:
+
+```markdown
+## Revision (added during implementation)
+
+- **Trigger:** AI review found that X approach doesn't work because Y
+- **Change:** Switched from A to B
+- **Impact:** Phase 3 replaced, Phase 4 added
+- **Approved by:** user (date)
+```
+
+Old content stays for audit trail. This section is added by `/tdd-implement`,
+not by this skill.
+
+## Content rules
+
+- **High-level by default.** No line numbers. No code snippets. No method bodies.
+- **Affected files are allowed.** Pointing at `path/to/Service` is fine;
+  saying "change line 142 to call `foo()`" is not.
+- **Verify every file path cited in "Affected areas".** Confirm each listed
+  path exists. Mark new files as `(new)`. Remove hallucinated paths.
+- **Acceptance Criteria must be addressable.** Each AC should map to something
+  in "Affected areas" or "Test strategy".
+- **No implementation, ever.** Approval means "save the plan", not "start coding".
+
+## Hard rules
+
+- **Do not write the plan file until the user approves.**
+- **Do not modify the spec file.** Specs are audit records.
+- **One plan file per spec.**
+- **Do not start implementation after writing the plan.**
+- **Local-only artifact.** `.ai/` is gitignored — the plan is never committed.
+  It reaches the team only when `/draft-pr` embeds it in the PR body.
+
+## Common Mistakes
+
+- Writing the plan without reading the spec end-to-end. The Original Description
+  and Acceptance Criteria are authoritative — guessing from the ticket title
+  produces a plan that misses scope.
+- Starting implementation after approval. Approval means "save the plan", not
+  "start coding". Stop after the file is written.
+- Citing file paths that do not exist in the repo. Verify every path in
+  "Affected areas" before presenting the plan. Mark genuinely new files `(new)`.
+- Including code snippets, line numbers, or method-level prescriptions. The plan
+  is high-level — what changes and why, not how line by line.
+- Overwriting an existing plan file without asking the user first.
+- Not tracking decisions made during discussion. Anything resolved in chat goes
+  into the "Decisions during planning" section of the written plan.
+- Modifying the spec file. Specs are append-only audit records — only
+  `/tdd-implement` appends a `## Revision`, and only on explicit user approval.
+- Guessing which spec to plan, or fabricating one, when none can be found.
+  Ask the user for a ticket key or spec-file path instead.

package/teams/brain-studio/skills/draft-pr/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: draft-pr
+description: Use when the user invokes `/draft-pr` (or asks to "draft a PR", "open a draft PR", "create a draft pull request"). Pushes the current branch and opens a DRAFT pull request on GitHub, filling the body from the plan/spec/review files and mapping to the repo's PR template. Always opens as draft, never marks it ready, never assigns reviewers. Only runs when explicitly invoked — do NOT auto-trigger on the word "PR".
+---
+
+# draft-pr
+
+Push the current branch and open a **draft** pull request on GitHub.
+This is **Step 7** of the AI-assisted development workflow.
+
+## Prerequisite
+
+- `gh` CLI installed and authenticated (`gh auth status` succeeds).
+- The repo's remote points at GitHub (`git remote -v` shows github.com).
+- The current branch is **not** the default branch and has commits ahead.
+
+If any fails, stop with a specific actionable message.
+
+## Workflow
+
+### 1. Pre-flight
+
+1. Detect the default branch (same logic as `/tdd-implement`):
+   - `git symbolic-ref --short refs/remotes/origin/HEAD` → strip `origin/`.
+   - Fallback: `git config init.defaultBranch`.
+   - Fallback: ask the user.
+2. Confirm current branch is not the default. If it is, stop.
+3. `git status` — working tree must be clean. If not, ask (commit / stash / abort).
+4. Branch has commits ahead: `git rev-list --count {default}..HEAD > 0`. If zero, stop.
+5. Check existing PR for this branch:
+   ```bash
+   gh pr view --json url,state,isDraft,title --jq '.'
+   ```
+   - If PR exists, show URL and ask: update description or skip?
+   - On `update`: use `gh pr edit --body-file` instead of `gh pr create`.
+   - On `skip`: stop.
+
+### 2. Derive ticket key and PR title
+
+- **Ticket key:** parse from branch name `<type>/{KEY}-{slug}` first;
+  fallback to commit messages `... ({KEY})`. If not found in either,
+  ask the user before continuing — store as `<ticket-key>`.
+- **PR title:** use the squashed commit's first line. It should already be:
+  ```
+  <type>(<scope>): <description> ({KEY})
+  ```
+  This format is validated by CI (`amannn/action-semantic-pull-request`).
+  If the title doesn't match, warn the user.
+
+### 3. Validate commit format
+
+Verify the commit(s) follow Conventional Commits with ticket key:
+
+```
+<type>(<scope>): <description> (<ticket-key>)
+```
+
+Run: `git log {default}..HEAD --pretty=%s`
+
+- If `<ticket-key>` was found: each message must match
+  `^(feat|fix|chore|refactor|test|docs|style|perf|ci|build)(\(.+\))?: .+ \([A-Z]+-\d+\)$`
+- If `<ticket-key>` is unknown (user confirmed): validate only the
+  Conventional Commits prefix — `^(feat|fix|chore|refactor|test|docs|style|perf|ci|build)(\(.+\))?: .+$`
+  — and warn that the `({KEY})` suffix is missing.
+- If any commit doesn't match, show the offending message and ask the user
+  to amend before pushing.
+- **Do not amend automatically.**
+
+### 4. Gather content sources
+
+In priority order:
+
+1. **Plan file** — `.ai/tasks/{KEY}/plan.md`: Goal, Approach, Test strategy,
+   Out of scope, plus the `## Deviations` / `## Post-Mortem` appended by
+   `/tdd-implement`. Its **full contents** are embedded in the PR (see Step 5).
+2. **Review file** — `.ai/tasks/{KEY}/review.md`: Verdict, findings summary.
+3. **Spec file** — `.ai/tasks/{KEY}/spec.md`: Acceptance Criteria. Its **full
+   contents** are embedded in the PR (see Step 5).
+4. **Commit body** — `git log -1 --pretty=%B` (the squashed commit message).
+5. **Commit history** — `git log {default}..HEAD --oneline` (fallback).
+
+The `.ai/` folder is gitignored, so spec/plan/review are **not in the repo** —
+this PR is the only channel through which the team can read them, when they
+exist. Note which sources were used.
+
+**Graceful degradation:** none of `plan.md`, `review.md`, or `spec.md` need to
+exist — this skill never fails or blocks because an `.ai/` artifact is
+missing. If some or all are absent, fall back to the commit body / commit
+history sources above; the PR still opens either way. State plainly in the
+chat preview (Step 6) and in the final "content sources used" list which
+artifacts were found and which were not (e.g. "Plan and review not found —
+composed from commit history only").
+
+### 5. Compose the PR body
+
+#### 5a. Read the PR template, with fallback
+
+Read `.github/pull_request_template.md` if it exists, and use it to shape the
+body:
+
+- **Template present with recognizable sections** (headings matching, loosely,
+  "Summary", "Testing Notes" / "How was this tested", "Related Ticket" /
+  "Ticket" / "Jira", "PR Quality Checklist" / "Checklist"): map content into
+  those sections **using the template's own heading text and order** — do not
+  rename or reorder them. The mapping guidance below (5b–5e) describes what
+  content goes where.
+- **Template present but shaped differently** (different headings, extra or
+  missing sections, different grouping): map content best-effort onto
+  whichever sections exist. If a piece of content has no obvious home (e.g.
+  the AI Evidence block), append it as its own section near the end of the
+  body rather than forcing it into an unrelated section, and call this out in
+  the chat preview (Step 6) so the user can move or drop it.
+- **Template absent:** compose the body using the default shape in 5b–5e
+  (`# Summary`, `## Testing Notes`, `## Related Ticket`, `## PR Quality
+  Checklist`) and say so explicitly in the chat preview, so the user knows no
+  template was found and can confirm the shape is acceptable.
+- **Never fail or block** on a missing or differently-structured template —
+  always produce a best-effort body. Ambiguities get surfaced in the Step 6
+  preview, where the user can reply `edit` to adjust before anything is
+  pushed.
+
+The subsections below describe content mapping using the default section
+names; apply the same content to whatever the template actually calls them.
+
+#### 5b. Summary
+
+- 2–4 sentences from Plan's Goal + Approach.
+- If the review had a PASS WITH NOTES verdict, mention it briefly.
+- Keep it skimmable — a reviewer grasps the change in 30 seconds.
+- End the Summary with a one-line pointer to the embedded artifacts, if any
+  were found in Step 4:
+
+  ```markdown
+  > Note: AI artifacts (spec & plan) are embedded at the bottom of this PR.
+  ```
+
+  Omit this pointer line if neither spec.md nor plan.md was found.
+
+#### 5c. Testing Notes
+
+- From Plan's Test Strategy: what test surfaces were added/extended.
+- From Review: verification result (`yarn lint && yarn typecheck && yarn test` — PASS).
+- Mention if e2e tests were added (Playwright).
+- List edge cases considered (from spec AC).
+- If plan/review/spec are unavailable, derive this section from the commit
+  body/history instead and say so — never invent test results.
+
+#### 5d. Related Ticket
+
+- Format: `[{KEY}](https://rezolvetech.atlassian.net/browse/{KEY})`
+
+#### 5e. PR Quality Checklist
+
+Read the checklist section verbatim from `.github/pull_request_template.md`
+at PR time — whatever it is titled there (`## PR Quality Checklist`,
+`## Checklist`, etc.). **Leave all boxes unchecked.** Do not invent, reorder,
+or modify checklist items — use exactly what is in the file. If the template
+has no checklist-like section (or no template exists at all), omit this
+section from the PR body rather than fabricating checklist items.
+
+#### 5f. AI Evidence (appended after checklist)
+
+The `.ai/` folder is gitignored, so the spec and plan — when they exist — are
+**not in the repo**; this PR is the only place teammates can read them. Embed
+their **full contents** in collapsible blocks at the very end of the body.
+The top-of-Summary pointer (added in 5b, if present) tells reviewers the
+blocks are there.
+
+```markdown
+---
+
+## AI Development Evidence
+
+- [ ] Spec — embedded below
+- [ ] Plan reviewed and approved — embedded below
+- [ ] TDD: tests written before implementation
+- [ ] AI code review passed — Verdict: {verdict}
+- Verification: `yarn lint && yarn typecheck && yarn test` — PASS
+
+<details>
+<summary>Spec (.ai/tasks/{KEY}/spec.md)</summary>
+
+{full verbatim contents of spec.md}
+
+</details>
+
+<details>
+<summary>Plan (.ai/tasks/{KEY}/plan.md — includes Deviations & Post-Mortem)</summary>
+
+{full verbatim contents of plan.md}
+
+</details>
+```
+
+- Read `spec.md` and `plan.md` from disk and paste their **full contents** into
+  the matching `<details>` block. Do not summarize or trim them here — the
+  Summary above is the skimmable version; these blocks are the complete record.
+- **If a file is missing, omit its entire `<details>` block and its checklist
+  bullet above** — do not embed an empty or placeholder block. Instead, add a
+  single plain-text line stating what's missing (e.g. "Spec not found —
+  ticket worked without `/jira-spec`."). If neither spec.md nor plan.md
+  exists, drop the AI Development Evidence section entirely and rely on the
+  "content sources used" note from Step 4.
+- Leave every `- [ ]` evidence box unchecked — reviewers tick them.
+
+### 6. Show the proposed PR for review
+
+Before any push, present in chat:
+
+```markdown
+# Draft PR preview
+
+**Repo:** <owner>/<repo>
+**Base:** <default-branch>
+**Head:** <current-branch>
+**Title:** <title>
+**Draft:** yes
+
+---
+<full body, exactly as it will appear>
+---
+
+Content sources used: <list>
+```
+
+Ask:
+> *"Looks good? Reply `confirm` to push and open the draft PR, `edit`
+> to revise, or `cancel` to stop."*
+
+### 7. Push, then create the PR (only on `confirm`)
+
+1. **Push:**
+   - `git push -u origin <current-branch>` (fast-forward only).
+   - If rejected as non-fast-forward, **stop**. Do not force-push:
+     > *"Push rejected — remote has commits not in local history.
+     > Resolve manually (`git push --force-with-lease` if sure), then
+     > re-run `/draft-pr`."*
+   - Show push output on success.
+
+2. **Create:**
+   - `gh pr create --draft --title "<title>" --body-file <tmpfile> --base <default>`
+   - Capture the URL.
+
+If `update` path: `gh pr edit <number> --body-file <tmpfile>`.
+
+### 8. Stop
+
+Print:
+> *"Draft PR ready at `<url>`. I have not marked it ready, assigned
+> reviewers, or opened follow-up issues."*
+
+Do **not**:
+- `gh pr ready`
+- Add labels, assignees, reviewers, milestones
+- Comment on the PR
+- Run CI manually
+- Create related issues
+- Start the next ticket
+
+## Hard rules
+
+- **Always `--draft`.** Never `gh pr ready`.
+- **Never push or create without explicit `confirm`.**
+- **Never assign reviewers, labels, or milestones.**
+- **Never check a `- [ ]` box.** Reviewers tick boxes.
+- **Never overwrite existing PR description without asking.**
+- **Never force-push.** Stop and surface if non-fast-forward.
+- **Never invent acceptance criteria or test results.**
+- **PR title must match Conventional Commits format** for CI validation.
+- **Commit messages must include `({KEY})` suffix.**
+
+## Common mistakes
+
+- Pushing before showing PR preview.
+- Checking template boxes because "tests pass".
+- Creating duplicate PR when one already exists.
+- Marking PR ready even after user says "looks great".
+- Putting the full spec/plan in the visible Summary instead of the collapsed
+  `<details>` blocks at the end (the Summary stays skimmable; the full
+  artifacts go in the details).
+- PR title missing scope or ticket key → CI rejects.
+- Forgetting the AI Evidence section when spec/plan exist.
+- Embedding an empty or placeholder `<details>` block instead of omitting it
+  when an `.ai/` artifact is missing.
+- Assuming `.github/pull_request_template.md` exists or has the exact
+  `# Summary` / `## Testing Notes` / `## Related Ticket` / `## PR Quality
+  Checklist` shape — a missing or differently-structured template must be
+  handled best-effort, never treated as a failure.
+- Force-pushing to resolve conflicts.
+- Retrying a rejected push with `--force-with-lease` because "it's
+  probably fine". Force-push is the user's call, not the skill's.