docs: add PR template, title conventions, and prepare-pr workflow

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+<!-- PR title format: type(scope): description — e.g., feat(auth): add SSO login -->
+<!-- Keep the title under 72 characters, use imperative mood, no trailing period. -->
+
+## Summary
+
+<!-- What changed and why? Keep this brief and outcome-focused. -->
+<!-- Include any architectural changes and enough context for a reviewer unfamiliar with this code area. -->
+
+## Verification
+
+<!-- List the checks you ran and what passed. Add command output notes when useful. -->
+
+- [ ]
+
+## Visual Changes
+
+<!-- If UI/visual behavior changed, add before/after screenshots in the table below. -->
+<!-- If there are no visual changes, replace the table with: N/A -->
+
+| Before | After |
+| ------ | ----- |
+|        |       |
+
+## Reviewer Notes
+
+<!-- Optional: reviewer focus areas, edge cases, or context that helps review quickly. -->

.kilocode/workflows/prepare-pr.md

@@ -0,0 +1,54 @@
+# Prepare PR
+
+Prepare a pull request description using this repository's PR template and then create or update the PR.
+
+## Required source of truth
+
+- Read and use `/.github/pull_request_template.md` from this repository.
+- Preserve section headings and order exactly as they appear in the template.
+- Do not add sections that are not present in the template.
+
+## PR title
+
+- Use the format `type(scope): <description>` (e.g., `feat(auth): add SSO login`).
+- Common types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `style`, `perf`.
+- Keep the title under 72 characters, use imperative mood, and do not end with a period.
+
+## Build the PR description
+
+1. Collect branch context.
+   - Run git commands to understand all changes that will be included in the PR.
+   - Include all commits since branch divergence, not just the latest commit.
+
+2. Prefill `## Summary`.
+   - Describe what changed and why.
+   - Explicitly call out any architectural changes.
+   - Include enough context for a reviewer unfamiliar with this code area.
+   - Keep it concise and reviewer-friendly.
+
+3. Prefill `## Verification` from this session.
+   - Capture verification already performed in this session (tests, typecheck, lint, builds, manual checks).
+   - Include command names and short pass/fail outcomes when available.
+   - Add a final placeholder bullet for extra user-provided verification details.
+
+4. Prepare `## Visual Changes`.
+   - Detect likely visual/UI changes from changed files (for example: `*.tsx`, `*.jsx`, CSS, Tailwind config, component/page/view files).
+   - If visual/UI changes are likely, keep the before/after screenshot table and add meaningful row labels/placeholders.
+   - If no visual/UI changes are likely, replace the section content with `N/A`.
+
+5. Prefill `## Reviewer Notes`.
+   - Add concise context that helps reviewer efficiency (risk areas, tricky logic, rollout notes).
+   - Keep this section brief.
+
+## Confirm with the user
+
+- Print the full generated PR description in markdown.
+- Ask for confirmation and any edits.
+- Apply edits and show the final version before writing it to GitHub.
+
+## Create or update PR
+
+1. Check whether a PR already exists for the current branch.
+2. If a PR exists, update the PR body using `gh pr edit --body`.
+3. If a PR does not exist, create it as a **draft** using `gh pr create --draft` with the generated title and body.
+4. Return the PR URL.

AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md
+
+## Pull Request Titles
+
+- Use the format: `type(scope): <description>`
+  - Common types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `style`, `perf`
+  - Scope is optional but encouraged (e.g., `feat(auth): add SSO login`)
+- Use imperative mood (e.g., "Add feature", not "Added feature").
+- Keep titles under 72 characters.
+- Do not end the title with a period.
+
+## Draft PRs
+
+When creating a pull request, **always create it as a draft** (`gh pr create --draft`). Let the author mark it ready for review.
+
+## Pull Request Descriptions
+
+When creating or updating a pull request, you **must** follow the PR template in `.github/pull_request_template.md`. Every PR description must include these four sections in order:
+
+### `## Summary`
+
+- Describe what changed and why. Be outcome-focused.
+- Call out architectural changes explicitly.
+- Include enough context for a reviewer unfamiliar with this code area.
+- Keep it concise. Do not pad with generic filler.
+
+### `## Verification`
+
+- List the checks you actually ran during development (tests, typecheck, lint, build, manual checks).
+- Include command names and pass/fail outcomes where available.
+- **Do not fabricate verification steps.** Only list testing you actually performed. Reviewers rely on this section to assess risk — dishonest verification is worse than none.
+
+### `## Visual Changes`
+
+- If UI or visual behavior changed, include a before/after screenshot table.
+- If there are no visual changes, replace the section content with `N/A`.
+
+### `## Reviewer Notes`
+
+- Add concise context that helps reviewer efficiency: risk areas, tricky logic, rollout notes, or edge cases.
+- If there is nothing noteworthy, keep this section brief or write `N/A`.
+
+### General rules
+
+- Preserve section headings and order exactly as they appear in the template.
+- Do not add sections that are not in the template.
+- Do not leave HTML comments from the template in the final description — replace them with actual content.
+- PR descriptions must be accurate and valuable to reviewers. Generic or boilerplate descriptions waste reviewer time.
+- Review all commits on the branch (not just the latest) when writing the summary.