kanbot 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/README.md +8 -8
  2. package/package.json +1 -1
  3. package/schema/config.schema.json +38 -8
  4. package/src/agents/load.ts +11 -0
  5. package/src/agents/sync.ts +8 -8
  6. package/src/capabilities.ts +157 -0
  7. package/src/color.ts +16 -0
  8. package/src/commands/board.ts +14 -7
  9. package/src/commands/doctor.ts +206 -19
  10. package/src/commands/init.ts +15 -3
  11. package/src/commands/sync.ts +1 -1
  12. package/src/commands/upgrade.ts +20 -1
  13. package/src/config.ts +38 -8
  14. package/src/daemon/derive.ts +41 -0
  15. package/src/daemon/loop.ts +2 -0
  16. package/src/jobs/prompts.ts +25 -5
  17. package/src/jobs/run.ts +61 -22
  18. package/src/known-hashes.json +42 -57
  19. package/src/providers/claude.ts +40 -30
  20. package/src/providers/codex.ts +60 -30
  21. package/src/providers/mcp.ts +71 -0
  22. package/src/schemas/results.ts +2 -5
  23. package/templates/.agents/skills/approach-designer/SKILL.md +1 -1
  24. package/templates/.agents/skills/kanbot-admin/SKILL.md +21 -4
  25. package/templates/.agents/skills/kanbot-guide/SKILL.md +26 -7
  26. package/templates/.agents/skills/kanbot-idea/SKILL.md +1 -1
  27. package/templates/.agents/skills/plan-template/SKILL.md +14 -6
  28. package/templates/.agents/skills/pr-description/SKILL.md +7 -3
  29. package/templates/.agents/skills/project-conventions/SKILL.md +23 -35
  30. package/templates/.agents/skills/review-findings/SKILL.md +47 -0
  31. package/templates/.agents/skills/spec-review/SKILL.md +10 -27
  32. package/templates/.agents/skills/user-stories/SKILL.md +1 -1
  33. package/templates/.github/pull_request_template.md +6 -0
  34. package/templates/.kanbot/agents/acceptance-reviewer.md +43 -0
  35. package/templates/.kanbot/agents/fixer.md +7 -5
  36. package/templates/.kanbot/agents/implementer.md +49 -0
  37. package/templates/.kanbot/agents/plan-critic.md +3 -3
  38. package/templates/.kanbot/agents/planner.md +10 -9
  39. package/templates/.kanbot/agents/reviewer.md +42 -0
  40. package/templates/AGENTS.md +2 -3
  41. package/templates/.agents/skills/accessibility/SKILL.md +0 -76
  42. package/templates/.agents/skills/code-review/SKILL.md +0 -83
  43. package/templates/.agents/skills/frontend-design/LICENSE.txt +0 -177
  44. package/templates/.agents/skills/frontend-design/SKILL.md +0 -76
  45. package/templates/.agents/skills/tdd/SKILL.md +0 -51
  46. package/templates/.agents/skills/verify-ui/SKILL.md +0 -104
  47. package/templates/.kanbot/agents/implementer-backend.md +0 -57
  48. package/templates/.kanbot/agents/implementer-docs.md +0 -55
  49. package/templates/.kanbot/agents/implementer-frontend.md +0 -54
  50. package/templates/.kanbot/agents/implementer-technical.md +0 -53
  51. package/templates/.kanbot/agents/reviewer-code.md +0 -46
  52. package/templates/.kanbot/agents/reviewer-spec.md +0 -49
  53. package/templates/.kanbot/agents/test-writer.md +0 -35
  54. package/templates/.kanbot/agents/ui-verifier.md +0 -35
@@ -6,8 +6,8 @@ description: Addresses review findings, human PR review comments, failing CI and
6
6
  models: { claude: sonnet, codex: default }
7
7
  effort: high
8
8
  tools: [read, edit, bash]
9
- skills: [project-conventions, project-memory, tdd, code-review, verify-ui, pr-description]
10
- subagents: [explorer, test-writer]
9
+ skills: [project-conventions, project-memory, review-findings, pr-description]
10
+ subagents: [explorer]
11
11
  output: fix-result
12
12
  ---
13
13
 
@@ -19,15 +19,17 @@ You are the fixer. You take a list of things to address on an existing PR branch
19
19
  - One or more of: reviewer findings (ids like `F1`), human PR review comments (with comment or thread ids, file and line), failing CI check names with log excerpts.
20
20
  - Or merge conflicts: a merge of the base branch is in progress and the prompt lists the conflicted files. Resolve them so both the PR's change and the base branch's changes survive. Stage the result; don't abort the merge.
21
21
 
22
+ - The repo's capabilities table, when it has one.
23
+
22
24
  ## Process
23
25
 
24
26
  1. Read `project-conventions` and `project-memory`. List every input item with its `ref`. Human comments take precedence over agent findings when they conflict.
25
27
  2. For each item, reproduce or confirm the problem before changing code: read the code at the referenced location; for CI failures, run the same command locally and get the same failure.
26
- 3. Fix the cause, not the symptom. When the item is a bug, first add or adjust a test that fails because of it (`tdd`), then fix.
28
+ 3. Fix the cause, not the symptom. When the item is a bug, first add or adjust a test that fails because of it, then fix. Use the repo's skills and agents for the how, and a capability from the table when its "when" fits.
27
29
  4. Keep each fix minimal and inside the plan. Commit per item or per tight group with a conventional message that names the ref, e.g. `fix(api): reject empty names (F2)`.
28
30
  5. After all items: run the full test suite, lint and typecheck. A fix that breaks something else is not a fix.
29
- 6. If your changes affect the UI, re-take the affected screenshots with `verify-ui`, overwriting the same files under `.kanbot/screenshots/<branch>/` so the PR shows the latest version. Commit them.
30
- 7. If the PR description is now wrong (behaviour, copy, screenshot list), return a corrected `prBody` per `pr-description`.
31
+ 6. If your changes affect what users see, re-run the `verify` or `preview` capability when it applies, so the PR's evidence is current. Commit what it produces for review.
32
+ 7. If the PR description is now wrong (behaviour, copy, Validation), return a corrected `prBody` per `pr-description`.
31
33
  8. If human feedback taught a lesson that applies beyond this PR, record it per `project-memory`.
32
34
  9. Do not silently skip anything. If you disagree with a finding, or it asks for out-of-scope work, or you cannot reproduce it, leave the code as is and explain.
33
35
 
@@ -0,0 +1,49 @@
1
+ ---
2
+
3
+ name: implementer
4
+ tier: column
5
+ description: Implements an approved plan on the current branch. Hands the how to the repo's own skills and agents, and owns the result.
6
+ models: { claude: sonnet, codex: default }
7
+ effort: high
8
+ tools: [read, edit, bash]
9
+ skills: [project-conventions, project-memory, pr-description]
10
+ subagents: [explorer]
11
+ output: implement-result
12
+ ---
13
+
14
+ You turn an approved plan into a committed change on the current branch and hand back a PR title and body. The repo decides how to build; you make sure the plan is met.
15
+
16
+ ## Inputs you get
17
+
18
+ - The issue, the approved plan, the branch, and the worktree you are in.
19
+ - For exploratory variants: the approach k to build. Build only `### Approach k`.
20
+ - The repo's capabilities table, when it has one.
21
+
22
+ ## Process
23
+
24
+ 1. Read `AGENTS.md`, `project-conventions` and `project-memory`. Delegate to `explorer` to map the code the plan touches. Reuse what exists.
25
+ 2. Build the plan step by step. Use the repo's skills and agents for the how. Use a capability from the table when its "when" fits; required ones are a must when they apply.
26
+ 3. Prove each acceptance criterion with a test or the `verify` capability. Use `preview` when it fits.
27
+ 4. Commit after each coherent step with a conventional commit message.
28
+ 5. Run the full tests, lint and typecheck. Self-review the diff against the plan and remove anything outside it.
29
+
30
+ ## Hard rules
31
+
32
+ - Never call `gh`, `git push`, or anything that talks to GitHub. kanbot pushes and opens the PR.
33
+ - Stay inside the plan. Needed work outside it goes in `risks`.
34
+ - Never weaken, skip or delete a test to make it pass.
35
+ - Leave the worktree clean: everything to review is committed.
36
+
37
+ ## Definition of done
38
+
39
+ Every acceptance criterion is implemented and proven, checks pass, and all work is committed.
40
+
41
+ ## Output
42
+
43
+ Return the structured result; it is your only channel to GitHub.
44
+ - `status`: `done`, or `blocked` when you can't go on without a human. Commit useful work first.
45
+ - `prTitle`: conventional commit, under 72 characters.
46
+ - `prBody`: per `pr-description`. Under Validation, list the capabilities, skills or checks you used and what they showed. No `Closes` line.
47
+ - `testsRun`: each command you ran with its outcome.
48
+ - `risks`: real risks and skipped follow-ups.
49
+ - `blockedReason`: one sentence on what a human must do when blocked; otherwise null.
@@ -13,15 +13,15 @@ You critique a draft plan as a demanding product lead and tech lead would. Your
13
13
 
14
14
  ## Check
15
15
 
16
- 1. **User need.** Is there a real user and a real problem, or a feature list? Does the story contain the solution instead of the need? For `technical` plans, is the benefit to someone named?
16
+ 1. **User need and value.** Is there a real user and a real problem, or a feature list? Is it worth doing now? Does the story contain the solution instead of the need? For `technical` plans, is the benefit to someone named?
17
17
  2. **Size.** Could one implementer ship this in a single small PR (rule of thumb: under ~400 changed lines, one reviewable concern)? If not, name the split using a pattern from `issue-splitting` and say which slice ships first.
18
18
  3. **Acceptance criteria.** Is every criterion Given/When/Then, observable from outside, and checkable from the PR? Flag vague words: "fast", "intuitive", "properly", "support", "handle". Are unhappy paths covered (empty, error, invalid input, no permission)?
19
- 4. **Design notes.** For UI work: are loading, empty, error and success states described? Mobile? Keyboard and screen-reader use?
19
+ 4. **Design notes.** Are the states users can hit (empty, error, in progress, no access) covered by criteria or notes?
20
20
  5. **Implementation steps.** Small, ordered, each leaving the code working? Do they name files? Is there a step that hides a large unknown (spike needed)?
21
21
  6. **Length.** Is anything repeated, padded or not needed to build and verify this? Under ~30 lines?
22
22
  7. **Scope.** Anything that belongs in `## Out of scope`? Anything out of scope that a criterion silently requires?
23
23
  8. **Approaches** (only with `explore:N`). Exactly N? Genuinely different on a real axis, or cosmetic variants? Each with honest tradeoffs?
24
- 9. **Assumptions.** Unstated assumptions that should be questions for the human.
24
+ 9. **Assumptions.** Unstated assumptions about user need or value? Does each say how to confirm it? Which risky ones should be open questions for the human?
25
25
 
26
26
  ## Rules
27
27
 
@@ -22,19 +22,20 @@ You are the planner. You turn one issue into a plan a single implementer can shi
22
22
  ## Process
23
23
 
24
24
  1. Read the `project-conventions` and `project-memory` skills and `AGENTS.md`. Then delegate to `explorer` to map the code this issue touches: relevant files, existing patterns and utilities to reuse, how tests are run. Do not plan against code you have not looked at.
25
- 2. Find the user need. Who is the user, what are they trying to get done, what hurts today? Load `user-stories`. If the issue has the `technical` label, write a technical goal instead, but still name who benefits.
26
- 3. Judge size with `issue-splitting`. If the work is more than one independently shippable slice, plan only the first slice here and propose the rest as `newIssues`. Prefer the thinnest slice that delivers something a user can notice or that unblocks the next slice.
27
- 4. Write the plan with the exact structure in `plan-template`. Acceptance criteria are Given/When/Then checkboxes that a reviewer can verify from the PR alone. Implementation steps name the files likely touched.
28
- 5. If the issue has an `explore:N` label (N = 2..4), delegate to the `approach-designer` subagent with the need, criteria, explorer map and N, and add `## Approaches` with exactly N approaches numbered `### Approach 1: <name>` … `### Approach N: <name>`. Each approach must differ in architecture, interaction model, data model, or build-vs-buy. Two approaches that differ only in styling or naming count as one. Acceptance criteria stay shared across approaches; implementation steps may differ per approach and belong inside each approach section.
29
- 6. Delegate the draft to `plan-critic`. Fix everything it flags as too big, untestable, or not user-centred, or note in `summary` why you disagree.
30
- 7. On later rounds, answer every new human comment. Change the plan when a comment asks for it. If a comment asks to split, emit the split as `newIssues` and shrink this plan.
25
+ 2. Find the user need and the business value first. Who is the user, what are they trying to get done, what hurts today, and why is it worth doing now? Load `user-stories`. If the issue has the `technical` label, write a technical goal instead, but still name who benefits.
26
+ 3. List the assumptions the plan rests on about user need and business value, each with how to confirm it (ask, data, user test). Risky, unconfirmed ones go in `questions`; kanbot adds them to the plan, and the issue can't start until they are answered. Technical unknowns are not assumptions here: use `explore:N` or a spike.
27
+ 4. Judge size with `issue-splitting`. If the work is more than one independently shippable slice, plan only the first slice here and propose the rest as `newIssues`. Prefer the thinnest slice that delivers something a user can notice or that unblocks the next slice.
28
+ 5. Write the plan with the exact structure in `plan-template`. Acceptance criteria are Given/When/Then checkboxes that a reviewer can verify from the PR alone. Implementation steps name the files likely touched.
29
+ 6. If the issue has an `explore:N` label (N = 2..4), delegate to the `approach-designer` subagent with the need, criteria, explorer map and N, and add `## Approaches` with exactly N approaches numbered `### Approach 1: <name>` … `### Approach N: <name>`. Each approach must differ in architecture, interaction model, data model, or build-vs-buy. Two approaches that differ only in styling or naming count as one. Acceptance criteria stay shared across approaches; implementation steps may differ per approach and belong inside each approach section.
30
+ 7. Delegate the draft to `plan-critic`. Fix everything it flags as too big, untestable, or not user-centred, or note in `summary` why you disagree.
31
+ 8. On later rounds, answer every new human comment. Change the plan when a comment asks for it. If a comment asks to split, emit the split as `newIssues` and shrink this plan.
31
32
 
32
33
  ## Hard rules
33
34
 
34
35
  - Never call `gh`, `git push`, or anything that talks to GitHub. The daemon writes the plan, replies, labels and new issues from your output.
35
36
  - Do not edit files or commit. You plan; you do not implement.
36
37
  - Never claim or imply approval. Never move the card or say "ready to implement" as if it were decided.
37
- - Do not invent product facts. When a choice depends on information only the human has, make a reasonable default, mark it as an assumption in the plan, and ask in `questions`.
38
+ - Do not invent product facts. When a choice depends on information only the human has, pick a reasonable default and list it under Assumptions. Ask in `questions` only when a wrong guess would waste the work, since questions block Ready.
38
39
  - Keep scope tight. Anything nice-to-have goes into `## Out of scope` or a new issue in `ideas`.
39
40
 
40
41
  ## Definition of done
@@ -48,5 +49,5 @@ Return the structured result; it is your only channel to GitHub.
48
49
  - `summary`: one sentence to the human on what changed this round.
49
50
  - `replies`: exactly one entry per input human comment, keyed by its `commentId`. Answer the question or say what you changed in the plan. One or two sentences; disagreeing is fine if you give the reason.
50
51
  - `newIssues`: slices split from this issue (`subIssue: true`, `column: planning` when ready to plan next, `ideas` otherwise) and unrelated ideas you noticed (`subIssue: false`, `column: ideas`). Each body is a user story, a one-line need and draft acceptance criteria. Empty when there is nothing to split.
51
- - `labels`: the full set this issue should carry from what you control: exactly one `type:frontend|backend|docs|infra`, plus `technical` when it is not a user-facing story. Keep any `explore:N` label that is present.
52
- - `questions`: questions only the human can answer, each answerable in one line. Empty if none.
52
+ - `labels`: `technical` when it is not a user-facing story; otherwise empty. Keep any `explore:N` label that is present.
53
+ - `questions`: questions only the human can answer, each answerable in one line. kanbot writes them into the plan's Open questions; don't write that section yourself. Empty if none.
@@ -0,0 +1,42 @@
1
+ ---
2
+
3
+ name: reviewer
4
+ tier: column
5
+ description: First review pass on a PR branch. Hands the technical review to the repo's `review` capability and reports findings in kanbot's format. Read-only.
6
+ models: { claude: opus, codex: default }
7
+ effort: high
8
+ tools: [read, bash]
9
+ skills: [project-conventions, project-memory, review-findings]
10
+ subagents: [explorer]
11
+ output: review-result
12
+ ---
13
+
14
+ You run the technical review of one PR branch. The repo owns how to review; you own the result. A second pass checks acceptance criteria, so leave that to it.
15
+
16
+ ## Inputs you get
17
+
18
+ - The issue, the approved plan, the PR title and body, the base branch, and the worktree at the PR head.
19
+ - The repo's capabilities table, when it has one.
20
+ - On later rounds: your earlier findings and the fixer's reply to each.
21
+
22
+ ## Process
23
+
24
+ 1. Read `AGENTS.md`, `project-conventions` and `project-memory`. Load `review-findings`.
25
+ 2. If the capabilities table maps `review`, hand the review to it: load the skill or delegate to the agent, with the diff range (`git diff <base>...HEAD`) and the plan. Extra gates the repo wants (security, performance…) live there.
26
+ 3. If `review` is not mapped, review the diff yourself against `AGENTS.md`, `project-conventions` and the code around each hunk. Run the project's tests, lint and typecheck. A failure caused by the branch is a blocker.
27
+ 4. Use other capabilities from the table when their "when" fits.
28
+ 5. Turn what you found into findings per `review-findings`. Check each one yourself before you report it.
29
+ 6. On later rounds, follow the re-review rules in `review-findings`.
30
+
31
+ ## Hard rules
32
+
33
+ - Never call `gh`, `git push`, or anything that talks to GitHub. kanbot posts your review.
34
+ - Read-only. Don't edit files, commit or change git state. Bash is for reading, diffing and running checks.
35
+ - Don't review the plan or ask for scope beyond it.
36
+
37
+ ## Output
38
+
39
+ Return the structured result; it is your only channel to GitHub.
40
+ - `verdict`: per `review-findings`.
41
+ - `summary`: one or two sentences. Name what reviewed it (the `review` capability or a plain review).
42
+ - `findings`: ids `F1`, `F2`, … highest severity first, in the `review-findings` format.
@@ -11,8 +11,8 @@ Board flow:
11
11
  1. **Ideas**: raw issues; nothing runs.
12
12
  2. **Planning**: `planner` writes a plan into the issue body and answers human comments each round.
13
13
  3. **Ready**: a human approves the plan by moving the card here.
14
- 4. **In Progress**: an `implementer-*` agent builds the plan on a branch and commits.
15
- 5. **Review**: `reviewer-code`, then `reviewer-spec`, then `fixer` for findings, human review comments, failing CI and merge conflicts.
14
+ 4. **In Progress**: `implementer` builds the plan on a branch and commits, using the repo's skills and agents (see `capabilities` in `.kanbot/config.yml`).
15
+ 5. **Review**: `reviewer` (technical, via the `review` capability), then `acceptance-reviewer`, then `fixer` for findings, human review comments, failing CI and merge conflicts.
16
16
  6. **Done**: a human merges, or approves and the daemon merges.
17
17
 
18
18
  ## Golden rules
@@ -32,7 +32,6 @@ Board flow:
32
32
  - `.kanbot/agents/*.md`: agent definitions (frontmatter + instructions). This is the source of truth.
33
33
  - `.agents/skills/<name>/SKILL.md`: skills shared by all agents. `.claude/skills` is a symlink to it.
34
34
  - `.claude/agents/`, `.claude/settings.json` and `.codex/agents/` are **generated** from `.kanbot/agents` by `kanbot sync`. Do not edit them by hand; edit the source and run `kanbot sync`.
35
- - `.kanbot/screenshots/<branch>/`: UI screenshots committed for review.
36
35
 
37
36
  ## When working interactively
38
37
 
@@ -1,76 +0,0 @@
1
- ---
2
-
3
- name: accessibility
4
- description: "Practical WCAG 2.2 AA checklist for building and reviewing web UI: semantics, keyboard, focus, labels, contrast, motion, forms, dynamic content. Use when building or changing any user interface, reviewing a UI PR, or when a11y, a screen reader, keyboard navigation or contrast comes up."
5
- ---
6
-
7
- # Accessibility (WCAG 2.2 AA)
8
-
9
- Build it in while writing the markup; retrofitting costs more. Native HTML elements get most of this right for free.
10
-
11
- ## Structure and semantics
12
-
13
- - [ ] One `<h1>` per page; headings in order without skipped levels; headings describe the section.
14
- - [ ] Landmarks: `<header>`, `<nav>`, `<main>`, `<footer>`; one `<main>`.
15
- - [ ] Buttons are `<button>` (actions), links are `<a href>` (navigation). No clickable `<div>`/`<span>`.
16
- - [ ] Lists are `<ul>/<ol>`, tabular data is `<table>` with `<th scope>`.
17
- - [ ] `lang` set on `<html>`. Page `<title>` describes the page.
18
- - [ ] ARIA only when no native element fits; a wrong role is worse than none.
19
-
20
- ## Keyboard and focus
21
-
22
- - [ ] Every interactive element is reachable and operable with Tab, Shift+Tab, Enter, Space, and arrow keys where the pattern expects them (menus, tabs, radios).
23
- - [ ] Focus order follows the visual order. No positive `tabindex`.
24
- - [ ] Focus is always visible, with at least 3:1 contrast against its background. Never `outline: none` without a replacement.
25
- - [ ] Focused elements are not hidden behind sticky headers or footers (2.4.11).
26
- - [ ] Dialogs: focus moves in on open, is trapped inside, Escape closes, focus returns to the trigger. Prefer `<dialog>`.
27
- - [ ] No keyboard traps. A "Skip to content" link when there is repeated navigation.
28
-
29
- ## Names, labels and images
30
-
31
- - [ ] Every control has an accessible name: visible `<label for>`, or `aria-label` for icon-only buttons.
32
- - [ ] The accessible name contains the visible label text (2.5.3).
33
- - [ ] Informative images have `alt` describing their purpose; decorative ones have `alt=""`. Icon SVGs inside labelled buttons get `aria-hidden="true"`.
34
- - [ ] Link text makes sense out of context: "View invoice 1042", not "Click here".
35
-
36
- ## Colour and contrast
37
-
38
- - [ ] Body text at least 4.5:1; large text (24px, or 18.7px bold) at least 3:1.
39
- - [ ] UI component boundaries and meaningful icons at least 3:1.
40
- - [ ] Colour is never the only signal: errors also have text or an icon; links in text are underlined or otherwise distinct.
41
- - [ ] Check both light and dark themes if the app has them.
42
-
43
- ## Layout and input
44
-
45
- - [ ] Works at 320px wide without horizontal scrolling (except tables, maps, code), and at 200% zoom.
46
- - [ ] Text spacing can be increased without clipping; no fixed heights on text containers.
47
- - [ ] Target size at least 24x24 CSS px, or enough spacing around it (2.5.8). Aim for 44x44 on touch.
48
- - [ ] Drag-only interactions have a single-pointer alternative (2.5.7).
49
- - [ ] Nothing depends on hover alone; tooltips are reachable by keyboard and dismissable.
50
-
51
- ## Forms
52
-
53
- - [ ] Labels are visible and persistent (placeholders are not labels).
54
- - [ ] Required fields are marked in text, not only with colour or `*` without explanation.
55
- - [ ] Errors identify the field and say how to fix it; linked via `aria-describedby`; focus or summary on submit.
56
- - [ ] Correct `type` and `autocomplete` (`email`, `name`, `one-time-code`, …).
57
- - [ ] Don't ask for information already given in the same flow (3.3.7); allow paste in password and code fields (3.3.8).
58
-
59
- ## Dynamic content and motion
60
-
61
- - [ ] Status changes that don't move focus (saved, count updated, results loaded) are announced via `role="status"` / `aria-live="polite"`. Errors that need attention: `role="alert"`.
62
- - [ ] Loading states are announced, or the busy region has `aria-busy="true"`.
63
- - [ ] Respect `prefers-reduced-motion`: disable non-essential animation and parallax.
64
- - [ ] No content flashes more than 3 times per second. Auto-playing or moving content can be paused.
65
- - [ ] Session timeouts warn and allow extension.
66
-
67
- ## How to check quickly
68
-
69
- 1. Tab through the changed UI from the top without a mouse. Can you do the whole task? Can you always see where focus is?
70
- 2. Run axe-core if available: `@axe-core/playwright` in the Playwright script, or the project's a11y tests. Treat violations as findings, but remember axe catches roughly a third of issues.
71
- 3. Inspect accessible names in Playwright: `page.getByRole("button", { name: "Save" })` should find the control. If role-based locators cannot find it, neither can a screen reader user.
72
- 4. Zoom to 200% and resize to 320px.
73
-
74
- ## Severity when reviewing
75
-
76
- `blocker`: keyboard trap, primary action unreachable by keyboard or unlabelled. `major`: any other AA failure in the changed UI. `minor`: best-practice gaps beyond AA.
@@ -1,83 +0,0 @@
1
- ---
2
-
3
- name: code-review
4
- description: Checklist, severity rubric and finding format for reviewing a code change. Use when reviewing a branch or PR diff for correctness, tests, security and maintainability, when deciding finding severity, or when judging whether a fixer resolved a finding.
5
- ---
6
-
7
- # Code review
8
-
9
- Find the problems that would hurt users or the team after merge, and say each one so precisely that it can be fixed without a conversation. A short list of real issues beats a long list of preferences.
10
-
11
- ## Read before judging
12
-
13
- - `git log <base>..HEAD` and `git diff <base>...HEAD --stat` to see the shape.
14
- - Read the plan's acceptance criteria and implementation steps; the diff should match them.
15
- - For each non-trivial hunk, open the whole function and its callers. Most real bugs sit at the edges of the diff.
16
- - Run tests, lint and typecheck. Do not assume CI will.
17
-
18
- ## Checklist (in priority order)
19
-
20
- **Correctness**
21
- - Does it do what the plan says for every input, including empty, null, zero, very large, duplicate and unicode input?
22
- - Off-by-one, wrong comparison, inverted condition, missing `await`, unhandled promise, race between concurrent requests.
23
- - State updates: stale state, cache not invalidated, partial writes without a transaction.
24
- - Changed function signatures or behaviour: are all callers updated?
25
-
26
- **Tests**
27
- - Does each acceptance criterion have a test that would fail if the feature were removed?
28
- - Do tests assert outcomes, or only that mocks were called?
29
- - Unhappy paths covered? No skipped, weakened or deleted tests?
30
-
31
- **Security**
32
- - Input validated at trust boundaries; output encoded (no raw HTML from user input).
33
- - Queries parameterised; no string-built SQL, shell commands or paths from user input.
34
- - Authorisation on every new endpoint, action and data query (can user A read user B's data?).
35
- - No secrets, tokens or personal data in code, logs, fixtures, screenshots or error messages.
36
- - New dependencies: maintained, reasonably sized, licence compatible.
37
-
38
- **Data and operations**
39
- - Migrations safe on existing data and reversible, or the irreversibility is stated.
40
- - Backward compatibility of APIs, events and stored formats.
41
- - Errors surfaced to the user or logged with enough context; not swallowed.
42
- - Obvious performance traps: N+1 queries, unbounded lists, work inside render loops.
43
-
44
- **Maintainability**
45
- - Follows `project-conventions` and the patterns of neighbouring code.
46
- - Reuses existing utilities instead of duplicating them.
47
- - Names say what things are; no dead code, commented-out code or leftover debug output.
48
- - Complexity proportionate to the problem; no speculative abstractions.
49
-
50
- ## Severity rubric
51
-
52
- | Severity | Meaning | Blocks merge |
53
- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
54
- | `blocker` | Wrong behaviour on a main path, data loss or corruption, security hole, failing tests/build, acceptance criterion untested and broken | Yes |
55
- | `major` | Bug in an edge case users will hit, missing test for a criterion, broken error handling, convention violation that will spread, risky migration | Yes |
56
- | `minor` | Real but low-impact issue: unclear naming, small duplication, missing test for a rare edge case | No |
57
- | `nit` | Preference or polish. Use sparingly; at most 3 per review | No |
58
-
59
- When unsure between two levels, pick the lower one and explain the risk.
60
-
61
- ## Writing a finding
62
-
63
- Each finding has: location, what is wrong, why it matters, and a suggested fix.
64
-
65
- > `src/invoices/service.ts:84` — `total` is computed before discounts are applied, so invoices with a discount code show the undiscounted amount (criterion 3). Move the `applyDiscounts` call above the sum, and add a test with a 10% code.
66
-
67
- - One problem per finding. Merge repeats into one finding listing all locations.
68
- - Point at the line in the new version of the file.
69
- - Show a failure scenario ("a user with no projects gets a 500") rather than a principle ("this is not robust").
70
- - Suggest the fix, and code only if short.
71
- - Ask a question only when you genuinely could not determine the answer by reading; say what you checked.
72
-
73
- ## Avoid
74
-
75
- - More than ~10 findings. If you have more, keep the most important and summarise the rest in one finding.
76
- - Nit storms: formatting, import order and style a linter or formatter covers.
77
- - Requesting scope beyond the plan. Suggest a follow-up issue as a `nit` at most.
78
- - Rewriting the author's working approach to your preferred one without a concrete defect.
79
- - Approving with an unresolved `blocker` or `major`.
80
-
81
- ## Re-review rounds
82
-
83
- For each previous finding: fixed (drop it), not fixed (repeat with the same id and what is still wrong), or the fixer disagreed (accept the reasoning, or explain once more why it matters). Check that fixes did not introduce new problems.
@@ -1,177 +0,0 @@
1
-
2
- Apache License
3
- Version 2.0, January 2004
4
- http://www.apache.org/licenses/
5
-
6
- TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
-
8
- 1. Definitions.
9
-
10
- "License" shall mean the terms and conditions for use, reproduction,
11
- and distribution as defined by Sections 1 through 9 of this document.
12
-
13
- "Licensor" shall mean the copyright owner or entity authorized by
14
- the copyright owner that is granting the License.
15
-
16
- "Legal Entity" shall mean the union of the acting entity and all
17
- other entities that control, are controlled by, or are under common
18
- control with that entity. For the purposes of this definition,
19
- "control" means (i) the power, direct or indirect, to cause the
20
- direction or management of such entity, whether by contract or
21
- otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
- outstanding shares, or (iii) beneficial ownership of such entity.
23
-
24
- "You" (or "Your") shall mean an individual or Legal Entity
25
- exercising permissions granted by this License.
26
-
27
- "Source" form shall mean the preferred form for making modifications,
28
- including but not limited to software source code, documentation
29
- source, and configuration files.
30
-
31
- "Object" form shall mean any form resulting from mechanical
32
- transformation or translation of a Source form, including but
33
- not limited to compiled object code, generated documentation,
34
- and conversions to other media types.
35
-
36
- "Work" shall mean the work of authorship, whether in Source or
37
- Object form, made available under the License, as indicated by a
38
- copyright notice that is included in or attached to the work
39
- (an example is provided in the Appendix below).
40
-
41
- "Derivative Works" shall mean any work, whether in Source or Object
42
- form, that is based on (or derived from) the Work and for which the
43
- editorial revisions, annotations, elaborations, or other modifications
44
- represent, as a whole, an original work of authorship. For the purposes
45
- of this License, Derivative Works shall not include works that remain
46
- separable from, or merely link (or bind by name) to the interfaces of,
47
- the Work and Derivative Works thereof.
48
-
49
- "Contribution" shall mean any work of authorship, including
50
- the original version of the Work and any modifications or additions
51
- to that Work or Derivative Works thereof, that is intentionally
52
- submitted to Licensor for inclusion in the Work by the copyright owner
53
- or by an individual or Legal Entity authorized to submit on behalf of
54
- the copyright owner. For the purposes of this definition, "submitted"
55
- means any form of electronic, verbal, or written communication sent
56
- to the Licensor or its representatives, including but not limited to
57
- communication on electronic mailing lists, source code control systems,
58
- and issue tracking systems that are managed by, or on behalf of, the
59
- Licensor for the purpose of discussing and improving the Work, but
60
- excluding communication that is conspicuously marked or otherwise
61
- designated in writing by the copyright owner as "Not a Contribution."
62
-
63
- "Contributor" shall mean Licensor and any individual or Legal Entity
64
- on behalf of whom a Contribution has been received by Licensor and
65
- subsequently incorporated within the Work.
66
-
67
- 2. Grant of Copyright License. Subject to the terms and conditions of
68
- this License, each Contributor hereby grants to You a perpetual,
69
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
- copyright license to reproduce, prepare Derivative Works of,
71
- publicly display, publicly perform, sublicense, and distribute the
72
- Work and such Derivative Works in Source or Object form.
73
-
74
- 3. Grant of Patent License. Subject to the terms and conditions of
75
- this License, each Contributor hereby grants to You a perpetual,
76
- worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
- (except as stated in this section) patent license to make, have made,
78
- use, offer to sell, sell, import, and otherwise transfer the Work,
79
- where such license applies only to those patent claims licensable
80
- by such Contributor that are necessarily infringed by their
81
- Contribution(s) alone or by combination of their Contribution(s)
82
- with the Work to which such Contribution(s) was submitted. If You
83
- institute patent litigation against any entity (including a
84
- cross-claim or counterclaim in a lawsuit) alleging that the Work
85
- or a Contribution incorporated within the Work constitutes direct
86
- or contributory patent infringement, then any patent licenses
87
- granted to You under this License for that Work shall terminate
88
- as of the date such litigation is filed.
89
-
90
- 4. Redistribution. You may reproduce and distribute copies of the
91
- Work or Derivative Works thereof in any medium, with or without
92
- modifications, and in Source or Object form, provided that You
93
- meet the following conditions:
94
-
95
- (a) You must give any other recipients of the Work or
96
- Derivative Works a copy of this License; and
97
-
98
- (b) You must cause any modified files to carry prominent notices
99
- stating that You changed the files; and
100
-
101
- (c) You must retain, in the Source form of any Derivative Works
102
- that You distribute, all copyright, patent, trademark, and
103
- attribution notices from the Source form of the Work,
104
- excluding those notices that do not pertain to any part of
105
- the Derivative Works; and
106
-
107
- (d) If the Work includes a "NOTICE" text file as part of its
108
- distribution, then any Derivative Works that You distribute must
109
- include a readable copy of the attribution notices contained
110
- within such NOTICE file, excluding those notices that do not
111
- pertain to any part of the Derivative Works, in at least one
112
- of the following places: within a NOTICE text file distributed
113
- as part of the Derivative Works; within the Source form or
114
- documentation, if provided along with the Derivative Works; or,
115
- within a display generated by the Derivative Works, if and
116
- wherever such third-party notices normally appear. The contents
117
- of the NOTICE file are for informational purposes only and
118
- do not modify the License. You may add Your own attribution
119
- notices within Derivative Works that You distribute, alongside
120
- or as an addendum to the NOTICE text from the Work, provided
121
- that such additional attribution notices cannot be construed
122
- as modifying the License.
123
-
124
- You may add Your own copyright statement to Your modifications and
125
- may provide additional or different license terms and conditions
126
- for use, reproduction, or distribution of Your modifications, or
127
- for any such Derivative Works as a whole, provided Your use,
128
- reproduction, and distribution of the Work otherwise complies with
129
- the conditions stated in this License.
130
-
131
- 5. Submission of Contributions. Unless You explicitly state otherwise,
132
- any Contribution intentionally submitted for inclusion in the Work
133
- by You to the Licensor shall be under the terms and conditions of
134
- this License, without any additional terms or conditions.
135
- Notwithstanding the above, nothing herein shall supersede or modify
136
- the terms of any separate license agreement you may have executed
137
- with Licensor regarding such Contributions.
138
-
139
- 6. Trademarks. This License does not grant permission to use the trade
140
- names, trademarks, service marks, or product names of the Licensor,
141
- except as required for reasonable and customary use in describing the
142
- origin of the Work and reproducing the content of the NOTICE file.
143
-
144
- 7. Disclaimer of Warranty. Unless required by applicable law or
145
- agreed to in writing, Licensor provides the Work (and each
146
- Contributor provides its Contributions) on an "AS IS" BASIS,
147
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
- implied, including, without limitation, any warranties or conditions
149
- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
- PARTICULAR PURPOSE. You are solely responsible for determining the
151
- appropriateness of using or redistributing the Work and assume any
152
- risks associated with Your exercise of permissions under this License.
153
-
154
- 8. Limitation of Liability. In no event and under no legal theory,
155
- whether in tort (including negligence), contract, or otherwise,
156
- unless required by applicable law (such as deliberate and grossly
157
- negligent acts) or agreed to in writing, shall any Contributor be
158
- liable to You for damages, including any direct, indirect, special,
159
- incidental, or consequential damages of any character arising as a
160
- result of this License or out of the use or inability to use the
161
- Work (including but not limited to damages for loss of goodwill,
162
- work stoppage, computer failure or malfunction, or any and all
163
- other commercial damages or losses), even if such Contributor
164
- has been advised of the possibility of such damages.
165
-
166
- 9. Accepting Warranty or Additional Liability. While redistributing
167
- the Work or Derivative Works thereof, You may choose to offer,
168
- and charge a fee for, acceptance of support, warranty, indemnity,
169
- or other liability obligations and/or rights consistent with this
170
- License. However, in accepting such obligations, You may act only
171
- on Your own behalf and on Your sole responsibility, not on behalf
172
- of any other Contributor, and only if You agree to indemnify,
173
- defend, and hold each Contributor harmless for any liability
174
- incurred by, or claims asserted against, such Contributor by reason
175
- of your accepting any such warranty or additional liability.
176
-
177
- END OF TERMS AND CONDITIONS