kanbot 0.0.0-stage → 0.2.0

package/templates/.agents/skills/kanbot-idea/SKILL.md

@@ -0,0 +1,56 @@
+---
+
+name: kanbot-idea
+description: Turn an idea into an issue on a kanbot board. Use when the human wants to capture, explore or file an idea, feature or task for kanbot agents to plan later.
+---
+
+# kanbot idea
+
+Help the human shape an idea, then file it as a GitHub issue. The board's auto-add workflow puts new issues in **Ideas**, where no agent touches them. Planning happens later, when the human drags the card to **Planning**.
+
+You shape the _problem_. The planner agent designs the solution later.
+
+## 1. Find the repo
+
+Use the repo the human names. Otherwise read `repo:` from `.kanbot/config.yml` in the current directory. Otherwise ask.
+
+GitHub access: `gh` if it is installed and logged in, else the GitHub MCP server's issue tools. If neither works, write the finished issue as markdown for the human to paste.
+
+## 2. Shape it
+
+Decide the kind with the human:
+
+- **User need**: who needs what, and why. The default.
+- **Technical**: refactoring, tooling, infra. What should be true when done, and who benefits.
+
+Ask one question at a time, each with your best guess, until you can write the need (or goal) in two or three plain sentences, plus constraints and links. Capture what the human already knows about solutions as notes, not as the plan.
+
+If it is really several ideas, propose one issue each.
+
+## 3. Check for duplicates
+
+Search open issues with the idea's key terms (`gh issue list --repo <repo> --search "<terms>"`). If one is close, show it and ask: add a comment there instead, or file a new one?
+
+## 4. Draft
+
+Match the repo's issue template, so the issue reads like one filed through GitHub. Read `.github/ISSUE_TEMPLATE/user-story.yml` or `technical.yml` from the repo (locally, or with `gh api repos/<repo>/contents/<path>`). Use each field's `label` as a `### ` heading and put the answer under it. Without templates:
+
+```markdown
+### Who needs what, and why?        (technical: ### Goal)
+
+<two or three sentences>
+
+### Notes, constraints, links
+
+<notes, or _None._>
+```
+
+Title: the outcome in under 70 characters. Technical issues get the `technical` label. Leave `type:*` labels to the planner.
+
+Show the title and body. File it only after the human says yes.
+
+## 5. File it
+
+`gh issue create --repo <repo> --title "<title>" --body-file <file>` (add `--label technical` when it applies), or the MCP equivalent.
+
+Done when the issue exists and the human has its link. Tell them it is in **Ideas**, and that dragging it to **Planning** starts the planner.

package/templates/.agents/skills/plan-template/SKILL.md

@@ -0,0 +1,85 @@
+---
+
+name: plan-template
+description: The exact markdown structure for an kanbot issue plan, with an example. Use whenever writing, revising or critiquing a plan in the Planning column, or when an implementer or reviewer needs to know which plan section holds what.
+---
+
+# Plan template
+
+The plan lives in the issue body. It is the contract for the implementer and both reviewers, and a human approves it by reading it. Keep it short: the reader should grasp it in one minute. Say what and why; the implementer decides how.
+
+```markdown
+## User story
+
+As a <user in context>, I want <capability>, so that <outcome>.
+Need: <one or two sentences: what hurts today and how we'll know it worked.>
+<!-- `technical` issues: "## Technical goal" instead, naming who benefits. -->
+
+## Acceptance criteria
+
+- [ ] Given <context>, when <action>, then <observable result>.
+<!-- 2-6 items. Cover the happy path plus the edge cases that matter. -->
+
+## Out of scope
+
+- <Only what a reader would otherwise expect. Omit the section if nothing.>
+
+## Design notes
+
+<UI: placement, key copy, states that differ from the obvious. Non-UI: API or data shape. 1-4 lines. Omit if nothing beyond the criteria.>
+
+## Implementation steps
+
+1. <Atomic step, with its test.> Files: `path/a.ts`
+<!-- 1-5 steps. -->
+
+## Approaches
+
+<!-- Only with explore:N. Exactly N, see the approach-designer skill. -->
+
+## Open questions
+
+- <Only what blocks the human's approval, with the default you assume. Omit if none.>
+```
+
+## Rules
+
+- Required: User story (or Technical goal), Acceptance criteria, Implementation steps. Omit other sections when empty; don't write "None."
+- One line per bullet. No prose paragraphs, no repeating the issue text.
+- Acceptance criteria are shared by all approaches. Approach-specific steps go inside each `### Approach k`.
+- File paths come from reading the code, not guesses. Mark new files "(new)".
+- No code blocks. Aim for under 30 lines (excluding approaches); much longer means split the issue.
+
+## Example
+
+```markdown
+## User story
+
+As a freelancer invoicing at month end, I want to see time entries with no project, so that I fix them before invoicing.
+Need: entries without a project silently drop off invoices; users find out when clients complain.
+
+## Acceptance criteria
+
+- [ ] Given entries this month have no project, when I open the month view, then a "Needs a project" list shows them, newest first.
+- [ ] Given I assign a project in that list, when it saves, then the entry leaves the list without a reload.
+- [ ] Given every entry has a project, when I open the month view, then the list is hidden.
+- [ ] Given loading fails, when I open the month view, then the list shows "Couldn't load entries" and "Try again".
+
+## Out of scope
+
+- Bulk-assigning projects (new issue).
+
+## Design notes
+
+List sits above the calendar, collapsed to 5 rows with "Show all (n)". Reuse `ProjectSelect` per row.
+
+## Implementation steps
+
+1. Add `missingProject` filter to `GET /entries`, with tests. Files: `api/entries/routes.ts`
+2. Add `MissingProjectSection` with its states and tests. Files: `web/entries/MissingProjectSection.tsx` (new)
+3. Mount it in the month view and refresh after assignment. Files: `web/month/MonthView.tsx`
+
+## Open questions
+
+- Include earlier months? Default: current month only.
+```

package/templates/.agents/skills/pr-description/SKILL.md

@@ -0,0 +1,44 @@
+---
+
+name: pr-description
+description: Template and rules for writing a pull request title and body (Summary, What changed, How to test, Screenshots, Notes for reviewer). Use when filling prTitle/prBody at the end of an implementation, or whenever writing or rewriting a PR description.
+---
+
+# PR description
+
+The reader is a busy reviewer with the issue open in another tab. They should know in 30 seconds what changed and how to check it. The daemon adds the `Closes #N` line, plus your `risks` and `testsRun`; don't repeat them in the body.
+
+## Title
+
+Conventional commit, imperative, under 72 characters, naming the user-visible effect: `feat(time): show entries that are missing a project`.
+
+## Body template
+
+```markdown
+<One sentence: what this PR does, in user terms. Explore variants: "Approach k: <name>.">
+
+## What changed
+
+- <By behaviour, not by file. 1-5 bullets. Call out new dependencies, migrations, env vars.>
+
+## How to test
+
+1. <Steps a human follows, ending in what they should see. 1-5 steps.>
+
+## Screenshots
+
+![<state, width>](.kanbot/screenshots/<branch>/<name>.png)
+<!-- UI changes only; 1-3 images that show the change. -->
+
+## Notes for reviewer
+
+- <Only decisions or deviations from the plan the reviewer must know. Omit if none.>
+```
+
+## Rules
+
+- One line per bullet. No "Why" section; the issue has it.
+- Describe what the code does now, not how you got there.
+- Anything you could not verify goes in `risks`, not the body.
+- Screenshot paths must match the `screenshots` output field.
+- Aim for under 20 lines.

package/templates/.agents/skills/project-conventions/SKILL.md

@@ -0,0 +1,79 @@
+---
+
+name: project-conventions
+description: This project's stack, exact commands (install, test, lint, typecheck, build, dev server), code conventions and recorded decisions. Read first before planning, implementing, reviewing or fixing anything in this repository, and whenever you need to know how to run tests or start the app.
+---
+
+# Project conventions
+
+> **TEMPLATE — fill this in.** Replace every `<placeholder>` with the real value for this repository and delete lines that do not apply. Agents treat this file as the source of truth; wrong commands here cause wrong work everywhere. Until it is filled in, agents must discover commands from manifests and CI config and say so in their output.
+
+## Instructions for agents
+
+- Read this skill before doing anything else in the repository.
+- Use the commands below exactly. Do not guess alternatives when one is listed.
+- If something here is wrong or missing and you learned the right answer (a command, a convention, a gotcha), propose an addition: edit this file in the same branch as a separate commit (`docs(conventions): …`) and mention it under "Notes for reviewer" in the PR. Only add durable facts about commands, stack and conventions. Lessons from human corrections go in `project-memory`. Planners and reviewers, who do not edit files, mention the proposed addition in their summary instead.
+
+## Product
+
+- What it is: `<one sentence: what the product does and for whom>`
+- Primary users: `<roles>`
+- Language/locale of the UI: `<e.g. Norwegian bokmål, English>`
+
+## Stack
+
+- Language and runtime: `<e.g. TypeScript 5, Node 22 / Bun 1.x>`
+- Frontend: `<framework, router, styling approach, component library / design system location>`
+- Backend: `<framework, API style (REST/GraphQL/RPC)>`
+- Data: `<database, ORM/query builder, migration tool>`
+- Package manager: `<pnpm | npm | bun | yarn>` (use only this one)
+
+## Commands
+
+| Task            | Command                                  |
+| --------------- | ---------------------------------------- |
+| Install         | `<pnpm install>`                         |
+| Dev server      | `<pnpm dev>` → `<http://localhost:5173>` |
+| Test (all)      | `<pnpm test>`                            |
+| Test (one file) | `<pnpm vitest run path/to/file.test.ts>` |
+| Test (one name) | `<pnpm vitest run -t "name">`            |
+| E2E             | `<pnpm playwright test>`                 |
+| Lint            | `<pnpm lint>`                            |
+| Format          | `<pnpm format>`                          |
+| Typecheck       | `<pnpm typecheck>`                       |
+| Build           | `<pnpm build>`                           |
+| DB migrate      | `<pnpm db:migrate>`                      |
+| Seed data       | `<pnpm db:seed>`                         |
+
+Environment: `<how to get a working .env for local dev and tests, e.g. cp .env.example .env; which variables have safe defaults>`
+
+## Layout
+
+```
+<src/            app code>
+<src/components/ shared UI components>
+<src/server/     API handlers>
+<tests/          …>
+```
+
+## Code conventions
+
+- Naming: `<files kebab-case, components PascalCase, …>`
+- Error handling: `<e.g. return Result types in domain code; throw HttpError in handlers>`
+- Validation: `<e.g. zod schemas at API boundaries in src/schemas>`
+- State/data fetching: `<e.g. TanStack Query; no fetch in components>`
+- Styling: `<e.g. CSS modules + tokens in src/styles/tokens.css; no inline colors>`
+- Tests: `<framework, location (co-located *.test.ts), factories in tests/factories>`
+- Commits: Conventional Commits (`feat`, `fix`, `refactor`, `test`, `docs`, `build`, `ci`, `chore`) with a scope.
+- Do not: `<things that look tempting but are wrong here>`
+
+## Decisions
+
+Record decisions that agents should not relitigate. One line each, newest first.
+
+- `<YYYY-MM-DD>`: `<decision>` because `<reason>`.
+
+## Gotchas
+
+- `<e.g. tests need Docker running for Postgres>`
+- `<e.g. generated files in src/gen/ — never edit, run pnpm codegen>`

package/templates/.agents/skills/project-memory/SKILL.md

@@ -0,0 +1,39 @@
+---
+
+name: project-memory
+description: Lessons learned in this repo, mostly from human corrections on PRs. Read before planning, implementing, reviewing or fixing. Write to it when a human correction reveals a rule you'd otherwise break again.
+---
+
+# Project memory
+
+Facts later agents need and can't see in the code: why a choice was made, a gotcha, a correction the human gave once and shouldn't have to give again. Commands and setup belong in `project-conventions`; this skill holds what the team _learned_.
+
+## Read
+
+Scan the index below. Open a fact when its line bears on your task. A fact the human wrote or merged outranks your own judgement, but not the plan or the human's comments on the current issue or PR.
+
+## Write
+
+Add a fact when a human correction on your issue or PR shows a **lesson** that applies beyond this change. One-off details of the task are not lessons.
+
+1. Check the index for a fact that covers it. Update that file instead of adding a second one.
+2. Create `facts/<short-kebab-slug>.md`:
+
+   ```markdown
+   <The rule, one or two sentences.>
+
+   **Why:** <the reason the human gave, with a link to the PR or issue comment.>
+   ```
+
+3. Add one line to the index: `- [<slug>](facts/<slug>.md): <the rule in a few words>`.
+4. Commit it on your branch as its own commit (`docs(memory): …`) and mention it in the PR description. The human approves it by merging.
+
+Agents that don't edit files (planners, reviewers) suggest the fact in their summary instead.
+
+## Keep it true
+
+A fact the code now contradicts is **stale**. If you edit files, fix or delete it in your branch. If you review, a stale fact is a `minor` finding.
+
+## Index
+
+<!-- One line per fact, newest last. -->

package/templates/.agents/skills/spec-review/SKILL.md

@@ -0,0 +1,73 @@
+---
+
+name: spec-review
+description: "Verify a change against its plan: every acceptance criterion with evidence, fit with the user need, UX states, accessibility, scope creep and docs. Use when doing the spec/product review pass on a PR branch, or when checking whether an implementation actually does what the issue asked."
+---
+
+# Spec review
+
+You review the change from the outside, as the user and the product owner. The question is not "is the code good?" but "did we build the right thing, completely, and nothing else?"
+
+## 1. Criteria evidence table
+
+For each acceptance criterion in the plan, record:
+
+| #   | Criterion (short)              | Evidence                                                                                    | Verdict          |
+| --- | ------------------------------ | ------------------------------------------------------------------------------------------- | ---------------- |
+| 1   | Missing-project entries listed | `MissingProjectSection.test.tsx` "lists entries newest first"; screenshot `filled-1280.png` | met              |
+| 2   | Count updates after assignment | test asserts count; not visible in screenshots                                              | met              |
+| 3   | Section hidden when none       | no test; no screenshot of empty state                                                       | **not verified** |
+
+Valid evidence: a test that asserts the behaviour (read it, and check it would fail without the feature), a screenshot of the state, or behaviour you observed by running the app or the command. The PR body's claims alone are not evidence.
+
+"Not verified" is a finding. "Not met" is a `blocker`.
+
+## 2. User need
+
+Re-read the user story and problem. Then walk through the change as that user:
+
+- Can they complete the job from where they start in the app, without knowing it was just built? Is it discoverable?
+- Does the copy use their words, say what will happen, and tell them what to do on error?
+- Is there feedback after every action (saving, saved, failed)?
+- Any dead ends: a state with no way forward or back?
+- Does it solve the problem in the plan, or only satisfy the letter of the criteria?
+
+## 3. UX states (UI changes)
+
+Check each state exists and looks right at 390px and 1280px:
+
+- [ ] Loading (no layout jump when content arrives)
+- [ ] Empty (explains why and what to do)
+- [ ] Error (says what went wrong and offers a way to recover)
+- [ ] Success / filled, including long text and many items
+- [ ] Disabled and in-progress controls
+- [ ] No horizontal scroll at 390px; tap targets at least 24x24px (44 preferred)
+
+Use committed screenshots under `.kanbot/screenshots/<branch>/` first. Capture missing states with `verify-ui` into a temp directory outside the repo.
+
+## 4. Accessibility
+
+Run through the `accessibility` checklist for the changed UI. WCAG 2.2 AA failures are `major`; a keyboard trap or an unlabelled primary control is a `blocker`.
+
+## 5. Scope
+
+- Diff against the plan's implementation steps: files changed that no step explains?
+- Features, options or settings nobody asked for?
+- Anything listed under `## Out of scope` that was built anyway?
+- Unrequested refactors or renames mixed in?
+
+Scope creep is `major` when it adds risk or review burden, `minor` otherwise. Ask for it to be removed or moved to a follow-up issue.
+
+## 6. Docs and communication
+
+- User-facing behaviour changed: are help text, README, changelog or docs updated where the project keeps them?
+- Does the PR body explain how to test, with steps a human can follow?
+- For exploratory variants: does the PR say which approach it implements, and does it actually follow that approach?
+
+## Writing findings
+
+Quote the criterion or plan line, state what you observed and your evidence, and say what would satisfy it:
+
+> Criterion 3 ("Given all entries have a project … the section is not shown") has no test and no screenshot. Add a component test for the empty case and an `empty-390.png` / `empty-1280.png` screenshot.
+
+Lead the summary with the tally ("4/5 criteria met, 1 not verified") so a human can scan it.

package/templates/.agents/skills/tdd/SKILL.md

@@ -0,0 +1,51 @@
+---
+
+name: tdd
+description: Test-driven development loop for agents (red, green, refactor) driven by acceptance criteria. Use when implementing a planned change, fixing a bug or review finding, or refactoring; covers which tests to write, running the narrowest test command first, and never weakening tests to make them pass.
+---
+
+# TDD for agents
+
+Tests are how you prove to the reviewers, and to yourself, that each acceptance criterion holds. Write them first so they test the behaviour you were asked for, not the code you happened to write.
+
+## Loop
+
+1. **Pick one criterion** (or one finding, for fixes). Work on one at a time.
+2. **Red.** Write a test that expresses it through the public interface (rendered UI, HTTP endpoint, CLI, exported function). Run it with the narrowest command. Confirm it fails **on the assertion**, for the reason you expect. A failure from an import error, typo or missing fixture is not red yet; fix the test.
+3. **Green.** Write the simplest production code that makes it pass. Run the narrow command again.
+4. **Refactor.** Remove duplication and clarify names while the test stays green. Keep refactors in the code you just touched.
+5. **Commit** test and code together (`feat: …`, `fix: …`), then move to the next criterion.
+6. After all criteria: run the full suite, lint and typecheck once.
+
+## Running tests efficiently
+
+- Narrowest first: a single file or test name (`bun test path/to/file.test.ts -t "name"`, `npx vitest run file -t name`, `pytest path::test_name`, `go test ./pkg -run TestName`). Use the commands in `project-conventions`.
+- Full suite only after the narrow tests pass, and before you finish.
+- When a test is slow because of setup, still run it; do not replace it with a weaker unit test.
+- Read failure output fully. The first error is usually the real one.
+
+## What to test
+
+- Each acceptance criterion: at least one test, named after the behaviour.
+- Unhappy paths named in the plan: invalid input, empty data, failures from dependencies, permission denied.
+- For bugs: a regression test that reproduces the bug and fails before the fix.
+- For refactors: characterization tests that pass before and after; behaviour must not change.
+
+Mock only at boundaries you do not own (network, clock, randomness, third-party services). Mocking your own modules makes tests pass while the integration is broken.
+
+## When the test is hard to write
+
+- Hard to set up usually means the design is too coupled. Introduce a seam (pass the dependency in) rather than reaching into internals.
+- Purely visual criteria (layout, colour) are verified by screenshot (`verify-ui`), not by snapshot tests of markup.
+- If a criterion genuinely cannot be tested automatically, say which and why in the PR body's "How to test".
+
+## Never
+
+- Weaken an assertion, add `.skip`/`xit`/`@pytest.mark.skip`, delete a test, or loosen a type or lint rule to get green.
+- Change a test's expected value to match the code's output without first confirming the code is right and the test was wrong. If so, explain it in the commit message.
+- Leave `only`/`focus` markers or debug output in committed tests.
+- Claim tests pass without having run them in this session. Report the actual command and result in `testsRun`.
+
+## If the existing suite is already red
+
+Run it before you change anything. Record pre-existing failures, make sure you add none, and list them in `risks`. Do not fix unrelated failures unless the plan asks.

package/templates/.agents/skills/user-stories/SKILL.md

@@ -0,0 +1,82 @@
+---
+
+name: user-stories
+description: Write issues and plans as user stories framed around a user need, with Given/When/Then acceptance criteria. Use when writing or rewriting an issue, a plan's user story or acceptance criteria, a new issue proposed from a split, or a `technical` goal; also when an issue reads like a feature list or prescribes a solution.
+---
+
+# User stories
+
+A story describes a change in what a person can do, and why it matters to them. It is a promise of a conversation, not a specification. The plan's other sections hold the detail.
+
+## Format
+
+```markdown
+As a <specific user in a specific situation>,
+I want <capability, phrased as what they can do, not UI widgets>,
+so that <the outcome they care about>.
+```
+
+- **Who**: a role in context, not "user". "A team lead reviewing last week's time entries", not "an admin".
+- **Want**: a capability. "see which entries are missing a project", not "a red badge on the table row".
+- **So that**: the real outcome. If it restates the want ("so that I can see entries"), dig one level deeper ("so that invoices go out on Monday without manual checks").
+
+## Find the need first
+
+Before writing the story, answer these for yourself; put the essence in the plan's one-line `Need:`:
+
+1. Who is struggling, and in what situation does it happen?
+2. What are they trying to get done (the job)? Use the Jobs-to-be-done lens: _When <situation>, I want to <motivation>, so I can <expected outcome>._
+3. What do they do today instead (workaround), and what does that cost them (time, errors, risk)?
+4. How will we know it worked (observable signal)?
+
+If the issue only states a solution ("add export to CSV"), work backwards: who needs the data outside the app, and for what? The real need might be met by something smaller.
+
+## Acceptance criteria
+
+Write as checkboxes in Given/When/Then. Each criterion is one observable behaviour a reviewer can verify from the PR (via a test, a screenshot, or running it).
+
+```markdown
+- [ ] Given I have time entries without a project, when I open the week view, then those entries are listed under "Needs a project" with a count.
+- [ ] Given all entries have a project, when I open the week view, then no "Needs a project" section is shown.
+- [ ] Given the entries fail to load, when I open the week view, then I see an error with a "Try again" action.
+```
+
+Rules:
+
+- Cover the happy path, the empty case, the error case and invalid input. Add permission cases when access differs by role.
+- Use concrete values where they matter ("more than 50 items", "within 2 seconds on the seeded dataset").
+- Describe behaviour, not implementation: no table names, component names or endpoints in criteria.
+- Banned words without a measure: fast, easy, intuitive, user-friendly, properly, robust, support, handle, seamless.
+- 3 to 7 criteria. More than 7 usually means the story should be split (see `issue-splitting`).
+
+## The `technical` exception
+
+When the issue has the `technical` label (refactor, infra, tooling, CI, dependency work), replace the story with a technical goal. It still names who benefits.
+
+```markdown
+## Technical goal
+
+Move session storage from in-memory to Redis
+so that the API can run on more than one instance
+which unblocks zero-downtime deploys for the ops team.
+```
+
+Acceptance criteria for technical work are verifiable outcomes: "Given two API instances behind the load balancer, when a user logs in on one, then requests routed to the other are authenticated", "CI build time stays under 6 minutes", "no change in public API responses (contract tests pass)".
+
+Do not use `technical` to dodge user framing. If users will notice the change, it is a story.
+
+## Anti-patterns
+
+| Smell                   | Example                                      | Fix                                                       |
+| ----------------------- | -------------------------------------------- | --------------------------------------------------------- |
+| Feature list            | "Add filters, sorting, export and bulk edit" | One story per user outcome; split the rest.               |
+| Solution in story       | "I want a modal with a dropdown"             | State the capability; put UI ideas in Design notes.       |
+| System as user          | "As the system, I want to cache…"            | Use `technical` with a technical goal, or find the human. |
+| Hollow "so that"        | "so that I can use the feature"              | Ask "why?" until you reach an outcome.                    |
+| Untestable criteria     | "The page is intuitive"                      | Name the observable behaviour.                            |
+| Horizontal slice        | "Build the database tables for X"            | Slice vertically through UI → API → data.                 |
+| Epic disguised as story | 10+ criteria, many screens                   | Split with `issue-splitting`.                             |
+
+## New issues you propose
+
+Bodies of new issues follow the same format: the story, a one-line need, and draft acceptance criteria. Mark anything you assumed with "Assumption:".

package/templates/.agents/skills/verify-ui/SKILL.md

@@ -0,0 +1,104 @@
+---
+
+name: verify-ui
+description: Run the app and use Playwright to screenshot key UI states at 390px and 1280px, save them under .kanbot/screenshots/<branch>/, and check console errors. Use after implementing or fixing a UI change, when reviewing a UI PR, or when asked to verify, screenshot or visually check the app. Degrades gracefully when there is no UI or dev server.
+---
+
+# Verify UI
+
+Screenshots are how a human reviewer sees the change without checking out the branch. Capture every state the plan's design notes list, at mobile and desktop width, and look at them yourself before anyone else does.
+
+## 1. Decide if this applies
+
+Skip with a note in `risks` ("no UI to verify") when the change has no visual effect. If there is a UI but no way to run it (no dev script, needs secrets or external services you do not have), say exactly what is missing and rely on component tests.
+
+## 2. Start the app
+
+1. Get the dev command, port and required env from `project-conventions` (or `package.json` scripts: `dev`, `start`, `preview`).
+2. Install dependencies if `node_modules` is missing, with the project's package manager.
+3. Start it in the background, logging to a file, and wait until it responds:
+
+```bash
+(bun run dev > "$TMPDIR/kanbot-dev.log" 2>&1 &)
+for i in $(seq 1 60); do curl -sf http://localhost:5173 >/dev/null && break; sleep 1; done
+```
+
+4. If it does not come up within ~60s, read the log, make one reasonable fix attempt (missing env default, seed step), then give up and report.
+
+## 3. Get Playwright
+
+Prefer the project's own Playwright if it has one (`@playwright/test` in devDependencies, a `playwright.config.*`). Otherwise use it ad hoc without adding a dependency:
+
+```bash
+bunx playwright --version || npx -y playwright --version
+bunx playwright install chromium   # once; may be unavailable offline
+```
+
+Do not add Playwright to the project's dependencies unless the plan asks for it.
+
+## 4. Capture states
+
+Write a throwaway script outside the repository (e.g. `$TMPDIR/kanbot-shots.mjs`):
+
+```js
+import { chromium } from "playwright";
+const [base, outDir] = process.argv.slice(2);
+const states = [
+	{ name: "filled", path: "/month", setup: async (page) => {} },
+	{ name: "empty", path: "/month?fixture=empty", setup: async (page) => {} },
+	// reach error/dialog states via setup: route interception, clicks, etc.
+];
+const browser = await chromium.launch();
+const problems = [];
+for (const width of [390, 1280]) {
+	const page = await browser.newPage({
+		viewport: { width, height: width === 390 ? 844 : 800 },
+	});
+	page.on(
+		"console",
+		(m) =>
+			["error", "warning"].includes(m.type()) &&
+			problems.push(`${width} ${m.type()}: ${m.text()}`),
+	);
+	page.on("pageerror", (e) =>
+		problems.push(`${width} pageerror: ${e.message}`),
+	);
+	for (const s of states) {
+		await page.goto(base + s.path, { waitUntil: "networkidle" });
+		await s.setup(page);
+		await page.evaluate(() => document.fonts.ready);
+		await page.screenshot({
+			path: `${outDir}/${s.name}-${width}.png`,
+			fullPage: true,
+		});
+	}
+	await page.close();
+}
+await browser.close();
+console.log(problems.join("\n") || "no console problems");
+```
+
+Run it with `node`/`bun` from a directory where `playwright` resolves. Use `page.route()` to simulate error and loading states instead of breaking the app.
+
+## 5. Where to save
+
+- Implementers and fixers: `.kanbot/screenshots/<branch>/<state>-<width>.png`, committed (`chore: add screenshots for review`). Replace old screenshots of the same state rather than accumulating them.
+- Reviewers: a temp directory outside the repo. Reviewers never commit.
+- List the committed paths in the `screenshots` output field and embed them in the PR body.
+
+## 6. Look at them
+
+Open each screenshot and check:
+
+- [ ] Nothing overflows or forces horizontal scroll at 390px
+- [ ] No clipped, overlapping or truncated text that hides meaning
+- [ ] Alignment and spacing consistent with surrounding UI
+- [ ] Contrast readable; focus visible where captured
+- [ ] Empty, error and loading states look intentional, not broken
+- [ ] No console errors or uncaught exceptions attributable to the change
+
+Fix what you find, recapture, then report.
+
+## 7. Clean up
+
+Stop the dev server (`pkill -f "<dev command>"` or kill the PID you started) and delete the throwaway script. Leave no running processes behind.

package/templates/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

package/templates/.github/ISSUE_TEMPLATE/technical.yml

@@ -0,0 +1,15 @@
+name: Technical task
+description: Refactoring, tooling, infrastructure or other work without a direct user-facing story.
+labels: [technical]
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: What should be true when this is done, and who benefits?
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes, constraints, links

package/templates/.github/ISSUE_TEMPLATE/user-story.yml

@@ -0,0 +1,15 @@
+name: User need
+description: Something a user needs. The planner agent turns it into a user story and plan.
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: Who needs what, and why?
+      description: Describe the user, what they are trying to do, and what gets in the way today. Don't prescribe the solution.
+      placeholder: As a returning customer I lose my cart when I switch devices, so I give up…
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes, constraints, links