diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md index 0e9862b520..ef2ac931c0 100644 --- a/.agents/skills/code-review/SKILL.md +++ b/.agents/skills/code-review/SKILL.md @@ -15,6 +15,13 @@ Review the current changes in the codebase (Go backend + Vite/React SPA monorepo Start from intent and evidence: read the spec/task first when available, then changed tests before production code. Tests reveal the expected behavior and whether the change is actually verified. +### Architecture discussion gate + +For a large architectural change, require a linked issue with maintainer +discussion before the PR opens. If the issue or discussion is missing, report a +blocker. Prefer one logical change and a small diff because this limits risk and +maintainer burden. + ## Available skills - **`/tdd`** — Recommend when flagging untested logic. The author can use this to add tests. diff --git a/.agents/skills/pr/SKILL.md b/.agents/skills/pr/SKILL.md index 9f4598d13b..bce06d2359 100644 --- a/.agents/skills/pr/SKILL.md +++ b/.agents/skills/pr/SKILL.md @@ -71,6 +71,12 @@ explicitly requests task tracking. when the user explicitly requests separate PRs. Use `--draft` if requested, otherwise create as ready-for-review. + **Architecture and scope gate:** Before running any PR creation command, check + large changes for a linked issue with maintainer discussion. If it is missing, + stop and report the blocker. Do not open a PR to start the discussion. Prefer + one logical change and the smallest practical diff; split unrelated cleanup, + refactoring, and feature work into separate PRs. + **PR title** must follow Conventional Commits format (see `/commit` for full rules). CI validates via `pr-title.yml` — the PR title becomes the squash-merge commit used for release notes. **PR body** must be built from `.github/pull_request_template.md`; fail fast if it is missing. Read the whole template before writing the body. Treat HTML comments as authoring instructions for the agent, not as output: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7bad16f75f..667b15a710 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,6 +8,19 @@ SUMMARY (required) Lead with the problem or goal, end with the outcome. Say WHY, not what. No filler phrases ("This PR...", "In order to...", "As part of..."). +LANGUAGE + Write the PR title, body, captions, and review-facing prose in English. + Translate non-English task text before recording it. Do not include the original wording in the PR body. + Keep non-English text only for intentional product localization or exact product data required by the diff. + Keep the surrounding explanation in English. + +ARCHITECTURE AND SCOPE + If the change is large or architectural, require a linked issue with maintainer discussion before opening the PR. + Large changes include new subsystems, public API or protocol changes, persistence changes, new execution boundaries, + authentication or permission-model changes, and cross-cutting changes across subsystems. + If the issue or discussion is missing, stop and report the blocker. Do not open a PR to start the discussion. + Prefer one logical change and the smallest practical diff. Split unrelated cleanup, refactoring, and feature work. + IMPORTANT CHANGES (optional) Include only for significant architectural changes. Skip for small or straightforward changes. Very short bullet list. Each bullet says WHAT changed and why (very short). @@ -52,6 +65,8 @@ RULES ## Checklist +- [ ] If this is a large architectural change, I discussed the direction in a linked issue before opening this PR. +- [ ] This PR contains one logical change; unrelated work is split into separate PRs. - [ ] I have performed a self-review of my code. - [ ] I have manually tested my changes and they work as expected. - [ ] My changes have tests that cover the new functionality and edge cases. diff --git a/AGENTS.md b/AGENTS.md index 4303e26bd3..6c25d51f3b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,12 @@ Architecture notes and per-area conventions live alongside the code they describ - Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types. - Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later. +### Engineering language + +Use English for all engineering text, including specs, plans, PRs, docs, +comments, and docstrings. Translate non-English input before recording it. +Only required product localization and product data can use another language. + ### Commit Conventions (enforced by CI) Commits to `main` **must** follow [Conventional Commits](https://www.conventionalcommits.org/) (`type: description`). PRs are squash-merged - the PR title becomes the commit, validated by CI. Changelog is auto-generated from these via git-cliff (`cliff.toml`). See `.agents/skills/commit/SKILL.md` for allowed types and examples. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9fca9b04e8..5b228ddbc1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,10 +10,32 @@ Join our [Discord](https://discord.gg/gWdCPGcFCD) to ask questions, discuss idea You must understand the code you submit. You're welcome to use AI tools to help write code, but every PR will be reviewed by a human maintainer and the feature you're contributing should be manually tested. If you can't explain what your code does and why, it's not ready to submit. +## Contribution language + +Use English for issues, PRs, documentation, specifications, plans, code +comments, and review discussion. Product localization values can use their +target language. Keep the surrounding explanation in English. + +## Before opening a PR + +Discuss a large architectural change in an issue before implementation or PR +creation. A large change includes a new subsystem, a public API or protocol +change, a persistence or data-model change, a new execution boundary, an +authentication or permission-model change, or a cross-cutting change across +subsystems. + +Describe the problem, proposed direction, affected boundaries, alternatives, +and migration or compatibility risks in the issue. Wait until maintainers have +discussed the direction before opening the PR. Link the issue from the PR. If +an agent is preparing the change, it must stop and report missing discussion +instead of opening the PR. + ## How to Contribute 1. **Fork and branch.** Create a feature branch from `main`. -2. **Keep PRs focused.** One logical change per PR. Small PRs get reviewed faster. +2. **Keep PRs small and focused.** Keep one logical change per PR. Split + unrelated cleanup, refactoring, and feature work. Smaller PRs reduce the + risk surface, make review easier, and reduce maintainer burden. 3. **Update public docs when behavior changes.** User-facing docs live in `docs/public/**`. If your change affects CLI commands, config keys, install/deploy flows, workflows, executors, APIs, screenshots, or user-facing terminology, update the relevant public docs in the same PR. See the [public docs contribution guide](docs/public/README.md) when editing navigation or adding a page. 4. **Test your changes.** Run `make fmt` first, then `make typecheck test lint` before submitting. Manually verify that your feature works end-to-end, and add screenshots or recordings to the PR if it has a UI component. **If your change touches any UI files (anything under `apps/web/`), you must add or update Playwright e2e tests in `apps/web/e2e/` to prevent regressions.** Run them with `make test-e2e`. See [docs/test_e2e_web.md](docs/test_e2e_web.md) for patterns and fixtures. diff --git a/apps/backend/config/prompts/open-pr.md b/apps/backend/config/prompts/open-pr.md index 78e7578d87..a80d986fdf 100644 --- a/apps/backend/config/prompts/open-pr.md +++ b/apps/backend/config/prompts/open-pr.md @@ -32,6 +32,8 @@ Please create and open a Pull Request for the current branch using the GitHub CL - Related Issues section with issue links 5. **Create the PR:** + - Before creating the PR, read and follow the target repository's contribution + guide and agent instructions - Use 'gh pr create' command with appropriate flags - Set the title and body based on the generated description - Set appropriate labels if needed @@ -47,4 +49,4 @@ Please create and open a Pull Request for the current branch using the GitHub CL - Ensure you're on the correct branch before creating the PR - Make sure all commits are pushed to the remote - Verify the base branch is correct (usually 'main' or 'develop') -- Check that CI/CD checks are configured to run \ No newline at end of file +- Check that CI/CD checks are configured to run diff --git a/docs/public/contributing.md b/docs/public/contributing.md index 1239cc78cd..5b30970e4e 100644 --- a/docs/public/contributing.md +++ b/docs/public/contributing.md @@ -12,7 +12,35 @@ Kandev combines a Go server and native launcher, a Vite/React web client, a Type 1. Run `make bootstrap` once in a fresh checkout. 2. Use `make dev` for normal full-stack work. 3. Find the owning backend, web, CLI, desktop, or runtime boundary before editing. -4. Run focused checks, update public docs, and leave a small reviewable diff. +4. Open an issue before a large architectural change and discuss its direction + with maintainers before opening a PR. +5. Keep one logical change in a small PR. Split unrelated work. +6. Run focused checks, update public docs, and leave a small reviewable diff. + +## Contribution language + +Use English for issues, PRs, documentation, specifications, plans, code +comments, and review discussion. Product localization values can use their +target language. Keep the surrounding explanation in English. + +## Discuss large architectural changes first + +Open an issue before you implement or submit a large architectural change. This +includes a new subsystem, a public API or protocol change, a persistence or +data-model change, a new execution boundary, an authentication or +permission-model change, or a cross-cutting change across subsystems. + +Describe the problem, proposed direction, affected boundaries, alternatives, +and migration or compatibility risks in the issue. Wait until maintainers have +discussed the direction before opening the PR. Link the issue from the PR. +An agent must stop and report missing discussion instead of opening the PR. + +## Keep PRs small + +Prefer one logical change and the smallest practical diff. Split unrelated +cleanup, refactoring, documentation, and feature work into separate PRs. +Smaller PRs reduce the risk surface, make review easier, and reduce maintainer +burden. ## Set up the repository @@ -99,6 +127,9 @@ The complete source and Landing build contract is in the [public docs contributi ## Review checklist - The change has one clear user impact and owning subsystem. +- Large architectural changes have a linked issue with maintainer discussion + before the PR opens. +- The PR contains one logical change and the smallest practical diff. - Wire changes update Go DTOs, TypeScript types/clients, compatibility behavior, and protocol docs together. - Persistence changes include fresh-schema and upgrade-path tests. - Credentials, external text, shell arguments, URLs, paths, and logs respect their trust boundary. diff --git a/docs/specs/guide/README.md b/docs/specs/guide/README.md index b4580df5f3..93923bc6eb 100644 --- a/docs/specs/guide/README.md +++ b/docs/specs/guide/README.md @@ -18,3 +18,11 @@ The [system README](../templates/system-readme.md), [system-design](../templates/system-design.md) templates provide the required document shapes. +## Authoring language + +Write all specification, system-design, plan, and work-order files in English. +Use English for filenames, frontmatter, IDs, titles, headings, prose, examples, +comments, and results. Translate non-English task input before recording it. +Do not copy the original wording into an engineering artifact. Keep non-English +text only for intentional product localization or exact product data required +by the contract. Keep the surrounding explanation in English.