docs: enhance PR guidelines and template (#28)

* docs: enhance PR guidelines and template

* docs: refine contribution guidelines and issue templates

Clarify when to open an issue first, what can go straight to a PR,
and align CONTRIBUTING with the PR template without duplicating checklists.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: update doc

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

.github/ISSUE_TEMPLATE/1-bug-report.yml

@@ -13,6 +13,8 @@ body:
 
         Please try to include as much information as possible.
 
+        If you plan to submit a fix: link this issue in your PR. Small, reproducible bugs can go straight to a PR; for broader or uncertain fixes, wait for maintainer feedback first.
+
   - type: input
     id: version
     attributes:

.github/ISSUE_TEMPLATE/2-feature-request.yml

@@ -11,6 +11,7 @@ body:
         Before you submit a feature:
         1. Search existing issues for similar features. If you find one, 👍 it rather than opening a new one.
         2. The Kimi Code team will try to balance the varying needs of the community when prioritizing or rejecting new features. Please understand that not all features will be accepted.
+        3. Do not open a feature PR until maintainers have had a chance to respond here. PRs without prior discussion may be closed without review.
 
   - type: textarea
     id: feature

.github/pull_request_template.md

@@ -1,25 +1,28 @@
 <!--
 Thank you for your contribution to Kimi Code!
-Please make sure you already discussed the feature or bugfix you are proposing in an issue with the maintainers.
-Please understand that if you have not gotten confirmation from the maintainers, your pull request may be closed or ignored without further review due to limited bandwidth.
+Please open an issue before sending a feature PR — PRs without prior discussion may be closed without review.
 
 See https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md for more.
 -->
 
 ## Related Issue
 
-<!-- Please link to the issue here. -->
+<!-- Link the issue this feature came from. If there is no issue, explain the problem in the next section instead. -->
 
 Resolve #(issue_number)
 
-## Description
+## Problem
 
-<!-- Please describe your changes in detail. -->
+<!-- What user need or limitation does this address? If the linked issue already covers this, write "See linked issue". -->
+
+## What changed
+
+<!-- What did you implement, and why does this approach fit Kimi Code? -->
 
 ## Checklist
 
 - [ ] I have read the [CONTRIBUTING](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md) document.
-- [ ] I have linked the related issue, if any.
-- [ ] I have added tests that prove my fix is effective or that my feature works.
+- [ ] I have linked a related issue, or explained the problem above.
+- [ ] I have added tests that prove my feature works.
 - [ ] Ran `gen-changesets` skill, or this PR needs no changeset.
 - [ ] Ran `gen-docs` skill, or this PR needs no doc update.

AGENTS.md

@@ -55,6 +55,8 @@ This is a TypeScript monorepo built for agent-assisted development. Keep the roo
 - Prefer `rg` / `rg --files` when reading code.
 - When designing changes, follow existing boundaries and local patterns first.
 - When creating a PR, the PR title must follow Conventional Commit style, e.g. `chore: remove legacy format commands`.
+- When an AI agent opens or updates a PR, fill in `.github/pull_request_template.md` — link the related issue or explain the problem, then describe what changed. Do not leave placeholder text or submit a generic summary of the diff.
+- Do not submit vague AI-generated PR text. The human author must understand the change well enough to explain the code, edge cases, and why the approach fits this repository.
 - After finishing a task and before submitting a PR, you must run the `gen-changesets` skill (see `.agents/skills/gen-changesets/SKILL.md`) and generate a changeset under `.changeset/` according to its rules.
 - When generating a changeset, **never** decide on a `major` bump on your own. When you judge a change to meet the major criteria (breaking changes, incompatible user configuration, renamed or removed commands/arguments, changed behavior semantics, etc.), you must stop and explain it to the user and ask for confirmation. **Only write `major` after the user has explicitly agreed.** Otherwise default to `minor` (and fall back to `patch` if `minor` is unclear). See the "Hard rule: confirm with the user before writing `major`" section in `.agents/skills/gen-changesets/SKILL.md` for details.
 - Prefer importing via `import ... from '#/...'`, which serves the same purpose as `import ... from '@/...'`.

CONTRIBUTING.md

@@ -4,9 +4,24 @@ Thanks for taking the time to contribute! This project moves quickly, and though
 
 ## Before You Start
 
-- Open an issue or discussion before making changes larger than ~100 lines so we can align on direction early.
-- We only merge PRs that are aligned with the roadmap — drive-by refactors without context are unlikely to land.
-- Code quality bar: as good as code written by a strong human engineer or a competent coding agent. We hold AI-assisted contributions to the same standard as hand-written ones.
+Kimi Code already has opinions on CLI/TUI behavior, agent workflows, and public APIs. If your change shifts that direction, open an issue first so we can align before you invest time in a PR.
+
+We hold AI-assisted contributions to the same standard as hand-written ones. **You should understand what you submit** — what changed, how it behaves at the edges, and why it fits this codebase. If you cannot explain that, the PR is not ready for review.
+
+We only merge PRs aligned with the roadmap. Drive-by refactors without context are unlikely to land.
+
+**Discuss first** — open an issue before coding. PRs without prior discussion may be closed without review:
+
+- New features or user-visible behavior changes (regardless of size)
+- Refactors or other changes larger than ~100 lines
+- Public API or compatibility changes
+- Bug fixes where the cause or fix approach is still unclear
+
+**Can open a PR directly** — link an existing issue when there is one:
+
+- Clear, reproducible bug fixes with a focused diff
+- Typos, documentation-only changes, and small CI/build fixes
+- Small changes that clearly match an existing issue or maintainer request
 
 ## Project Layout
 
@@ -65,20 +80,13 @@ This repo uses [changesets](https://github.com/changesets/changesets) to manage
 - Every PR that affects release artifacts (code, behavior, public API) **must** include a changeset.
 - Docs-only, test-only, or CI-only PRs may skip changesets.
 - Generate one with `pnpm changeset` and follow the prompts (which packages are touched, which bump level).
-- For repo-specific conventions, see `.changeset/README.md`.
+- For repo-specific conventions on package selection and bump levels, see `.changeset/README.md`. When working in this repo with coding agents, use the `gen-changesets` skill.
 
-## Pull Request Checklist
+## Pull Requests
 
-Before requesting review, make sure your PR ticks the following:
+Use the [PR template](.github/pull_request_template.md) when opening a feature pull request.
 
-- [ ] Linked an issue (for non-trivial changes)
-- [ ] PR title follows Conventional Commits
-- [ ] Added or updated tests
-- [ ] Added a changeset if the PR affects release artifacts
-- [ ] Ran `pnpm lint && pnpm typecheck && pnpm test` locally
-- [ ] Updated user-facing docs in `docs/` if behavior changed
-
-The `.github/pull_request_template.md` checklist is a shorter subset of this — both must pass.
+PR titles must follow [Conventional Commits](#commit-convention); CI runs `pnpm lint`, `pnpm typecheck`, and `pnpm test` on every PR. Update user-facing docs in `docs/` when behavior changes — use the `gen-docs` skill when working with coding agents.
 
 ## Code Style