docs: collect work as issues during the day, clear it in one sitting

[tkc]

Writes down the working pattern you described — capture during the day, clear in the evening — and fixes the one thing that was actually missing for it to work.

The gap this closes

There was no CLAUDE.md. Every fresh agent rediscovers the rules or ignores them; I have re-derived "English commits, Japanese docs, branch → PR → CI → squash, never commit to main" from memory in every session. An @claude run in CI would not have had even that. Anthropic's own best-practices section names CLAUDE.md as the first thing to set up, and warns to keep it short because it is read on every run.

It now carries the six rules that have actually bitten here:

• the scope test (## Why / ## Not goals) before adding a feature
• rules in config, not in the binary — the convention [agent] and [paste] already follow
• branch → PR → CI → squash, never main; one issue, one branch, one PR
• English commits and PR bodies, Japanese comments and docs/
• measure before diagnosing, with the tool table — reasoning from the code has given the wrong cause twice; a measurement has found it every time
• test conventions, and checking that a new test fails when the fix is reverted

Templates are deliberately thin

.github/ISSUE_TEMPLATE/ has two short forms and leaves blank issues enabled. A form demanding reproduction steps, expected behaviour and environment raises report quality and lowers capture rate — and an idea not captured in the moment is gone. The bug form asks for the one-line symptom, optionally a log line (with the TERMIT_FRAME_LOG / TERMIT_KEYLOG incantations inline so you do not have to remember them), and the build. The feature form asks for the problem, not the solution, plus a soft scope question with "not sure" as an allowed answer.

Quality is added at triage, not at capture.

docs/issue-workflow.md

The procedure: capture in one line during the day; triage everything in one 15-minute pass before touching any of it; then clear one issue per branch. It includes the parts specific to this repo — triage means measuring, not guessing at a cause; "is this the terminal's job?" is a triage question and not one to hand to a machine.

What it takes from how others run this, with sources:

Taken	Why
Issues as a coordination surface independent of the working tree	survives branch switches and machines; a local TODO file does not
One issue per branch	several agents editing one plan file is the most commonly reported source of silent corruption
CLAUDE.md, kept short	read on every run
Templates to cut round trips	fewer turns is directly less cost
worktrees for parallel work	two agents in one working tree tread on each other

It also covers what the autoContinueAtUsageLimit behaviour means for evening work — a session left open resumes by itself when the limit resets, and quitting during the wait cancels that.

No workflow file

claude.yml is not included. It needs a secret only you can add, and it spends Actions minutes and tokens on every run. The setup steps (/install-github-app, the two secret options) and the cost controls (--max-turns, timeout-minutes, concurrency) are documented, and the decision is left to you.

Test

cargo test — 233 pass, 1 ignored (unchanged; no code touched). The three issue-form YAML files parse.

Left unmerged for your review, as asked.

🤖 Generated with Claude Code