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.
- package/README.md +8 -8
- package/package.json +1 -1
- package/schema/config.schema.json +38 -8
- package/src/agents/load.ts +11 -0
- package/src/agents/sync.ts +8 -8
- package/src/capabilities.ts +157 -0
- package/src/color.ts +16 -0
- package/src/commands/board.ts +14 -7
- package/src/commands/doctor.ts +206 -19
- package/src/commands/init.ts +15 -3
- package/src/commands/sync.ts +1 -1
- package/src/commands/upgrade.ts +20 -1
- package/src/config.ts +38 -8
- package/src/daemon/derive.ts +41 -0
- package/src/daemon/loop.ts +2 -0
- package/src/jobs/prompts.ts +25 -5
- package/src/jobs/run.ts +61 -22
- package/src/known-hashes.json +42 -57
- package/src/providers/claude.ts +40 -30
- package/src/providers/codex.ts +60 -30
- package/src/providers/mcp.ts +71 -0
- package/src/schemas/results.ts +2 -5
- package/templates/.agents/skills/approach-designer/SKILL.md +1 -1
- package/templates/.agents/skills/kanbot-admin/SKILL.md +21 -4
- package/templates/.agents/skills/kanbot-guide/SKILL.md +26 -7
- package/templates/.agents/skills/kanbot-idea/SKILL.md +1 -1
- package/templates/.agents/skills/plan-template/SKILL.md +14 -6
- package/templates/.agents/skills/pr-description/SKILL.md +7 -3
- package/templates/.agents/skills/project-conventions/SKILL.md +23 -35
- package/templates/.agents/skills/review-findings/SKILL.md +47 -0
- package/templates/.agents/skills/spec-review/SKILL.md +10 -27
- package/templates/.agents/skills/user-stories/SKILL.md +1 -1
- package/templates/.github/pull_request_template.md +6 -0
- package/templates/.kanbot/agents/acceptance-reviewer.md +43 -0
- package/templates/.kanbot/agents/fixer.md +7 -5
- package/templates/.kanbot/agents/implementer.md +49 -0
- package/templates/.kanbot/agents/plan-critic.md +3 -3
- package/templates/.kanbot/agents/planner.md +10 -9
- package/templates/.kanbot/agents/reviewer.md +42 -0
- package/templates/AGENTS.md +2 -3
- package/templates/.agents/skills/accessibility/SKILL.md +0 -76
- package/templates/.agents/skills/code-review/SKILL.md +0 -83
- package/templates/.agents/skills/frontend-design/LICENSE.txt +0 -177
- package/templates/.agents/skills/frontend-design/SKILL.md +0 -76
- package/templates/.agents/skills/tdd/SKILL.md +0 -51
- package/templates/.agents/skills/verify-ui/SKILL.md +0 -104
- package/templates/.kanbot/agents/implementer-backend.md +0 -57
- package/templates/.kanbot/agents/implementer-docs.md +0 -55
- package/templates/.kanbot/agents/implementer-frontend.md +0 -54
- package/templates/.kanbot/agents/implementer-technical.md +0 -53
- package/templates/.kanbot/agents/reviewer-code.md +0 -46
- package/templates/.kanbot/agents/reviewer-spec.md +0 -49
- package/templates/.kanbot/agents/test-writer.md +0 -35
- 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,
|
|
10
|
-
subagents: [explorer
|
|
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
|
|
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
|
|
30
|
-
7. If the PR description is now wrong (behaviour, copy,
|
|
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.**
|
|
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
|
|
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.
|
|
27
|
-
4.
|
|
28
|
-
5.
|
|
29
|
-
6.
|
|
30
|
-
7.
|
|
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,
|
|
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`:
|
|
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.
|
package/templates/AGENTS.md
CHANGED
|
@@ -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**:
|
|
15
|
-
5. **Review**: `reviewer
|
|
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
|