claude-playground/CLAUDE.md

claude-playground

A tiny zero-dependency Node.js todo CLI, used as a sandbox for trying Claude Code features.

Commands

• npm test — run the test suite (built-in node:test, no install needed)
• npm start -- add "something" / npm start -- ls — run the CLI (data in todos.json, override with TODO_FILE)

Conventions

• ES modules, Node >= 20, no third-party dependencies.
• src/todo.js holds pure functions; keep I/O in load/save and src/cli.js.
• Every behavior change gets a test in test/.
• Commit messages: short imperative subject line.

Workflow (required)

Never commit, merge, or push to main. Only a human (Christian) merges into main. This is also enforced outside this file: Gitea branch protection on main and a deny rule in .claude/settings.json.

1. Start every change from a fresh main: git fetch origin && git switch -c <type>/<short-name> origin/main (e.g. fix/duplicate-ids, docs/readme).
2. Commit on that branch; run npm test before every push.
3. Push the branch and open a PR against main (see "Gitea API" below).
4. Review it with /code-review <branch>. Always name the branch: with no target, the review diffs against the just-pushed upstream and sees nothing.
5. Post the result as a PR comment. Its first line is Approved or Needs fixes, its second is _Automated self-review by Claude; not an independent review._, then the findings.
6. If it needs fixes, fix the correctness findings on the same branch and repeat steps 2–5. At most 2 fix rounds: after that, post what's left and hand off to the human.
7. Stop there. Do not merge the PR, even if approved; tell the human it's ready.

Gitea API

No gh/tea: use curl with $GITEA_TOKEN (set in the git-ignored .claude/settings.local.json). If it's unset, stop and ask the human; don't work around it.

API=https://code.westerkam.org/api/v1/repos/christian/claude-playground
# Open a PR
jq -n --arg head "$BRANCH" --arg title "$TITLE" --arg body "$BODY" '{head:$head, base:"main", title:$title, body:$body}' \
  | curl -s -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" -d @- "$API/pulls"
# Comment on PR number $N
jq -n --rawfile body comment.md '{body:$body}' \
  | curl -s -X POST -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" -d @- "$API/issues/$N/comments"

Run git commit and git push as standalone commands (no cd … && prefix): only then do they run outside the sandbox, which commit signing needs.

Remote

Gitea at code.westerkam.org — origin = git@code.westerkam.org:christian/claude-playground.git.