Instructions for AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini, …) in this repository. Humans start at CONTRIBUTING.md; the rules are the same.
If AGENTS.local.md exists in the repository root, read it next. It holds maintainer-local
instructions, is never committed, and wins where it conflicts with this file.
LeafWiki is a self-hosted wiki: Markdown files on disk are the source of truth, SQLite indexes
are derived and rebuildable, one binary for Linux, Windows, macOS and Raspberry Pi.
Backend: layered Go (cmd/leafwiki → internal/wiki composition root → slices →
internal/core/*). Frontend: React SPA in ui/leafwiki-ui with feature-local Zustand stores.
Read before changing code — docs/development/: rules (the short list, same for people and agents), conventions (the reference behind them), source map, architecture, processes, ADRs.
| What | Command | Where |
|---|---|---|
| Backend tests / lint | go test ./... / golangci-lint run (v2) |
repo root |
| Windows build check | GOOS=windows go build ./... |
repo root |
| Frontend typecheck + build | npm run build (not npx tsc --noEmit, it checks nothing) |
ui/leafwiki-ui |
| Frontend tests / lint / format | npm test / npm run lint -- --max-warnings=0 / npm run format |
ui/leafwiki-ui |
| E2E | make run-e2e; lint/format in e2e |
repo root |
| Local dev | backend: go run . --jwt-secret=dev --admin-password=dev --public-access=true --allow-insecure=true in cmd/leafwiki; frontend: npm run dev |
A fresh worktree has no node_modules: run npm ci --ignore-scripts in ui/leafwiki-ui first.
The rules live in docs/development/rules.md, nowhere else. Read them before changing code; don't restate them in prompts, skills or roles, link there. Much of it is enforced in CI (import boundaries, ESLint XSS guard, i18n key parity, golangci-lint, Prettier); a red check is a real finding.
- Committing locally is fine when the history is clean: one logical change per commit,
Conventional Commits (
type(scope): description), refactoring, behaviour change andtest: tidyin separate commits, formatters run, tests green. Never commit secrets, generated files or local overlays. - Pushing, opening PRs and commenting on GitHub need the person's explicit OK.
- PR size and scope: rules and conventions; process in CONTRIBUTING.md and AI-assisted contributions.
Changes run through independent roles, scaled by tier (details in the develop skill):
trivial (typo, rename, docs) → implement + CI; normal (change inside one slice) →
implement + tester + architecture-reviewer + reviewer; feature (new feature, extension
point, API or format change) → all roles with a plan gate; + security for anything touching
rendering, uploads, served files, auth, routes or paths.
Roles in .claude/agents/ (plain Markdown prompts): planner, architecture-reviewer,
implementer, reviewer, tester, security-reviewer. Each runs with a fresh context; the
checking roles see only the plan and the diff. Without subagent support, run each role in its
own session with its file as instructions.
Runbooks in .claude/skills/<name>/SKILL.md: develop (the workflow above), tidy-tests
(restructure a package's tests with proof nothing was lost), run (start backend + frontend),
docs-review (docs vs. code), worktree-cleanup.