Agent Instructions¶
Funny Movies: a Java 24 / Spring Boot 4 API (api/) and a React 19 + Vite webapp (webapp/). These instructions apply to any coding agent working in this repo, not just Claude Code. Project detail lives in CLAUDE.md and webapp/CLAUDE.md.
Where Things Live¶
.claude/— skills (user-invoked workflows + knowledge library), rules, hooks, and worker agent definitions (adapted from claude-agentic-framework v5)docs/— durable planning documents, committed:docs/adr/,docs/prd/,docs/specs/,docs/plans/, plusdocs/tracking.md(feature status)./scratchpad/— ephemeral working notes and draft content; gitignored, disposable./artifacts/— design images (Stitch exports, previews), not planning docs
Task Tracking¶
- Durable record:
TASKS.mdanddocs/tracking.md(features with an ADR/PRD/plan); GitHub Issues for follow-ups. - In-flight work: your tool's native task/todo list, owned by whichever agent is orchestrating — sub-agents receive focused prompts and return results rather than sharing mutable state.
- Handoffs: reference concrete artifacts under
docs/by file path.
Landing the Plane (Session Completion)¶
This protocol has two modes. Check which one applies — it depends on whether the current agent's frontmatter declares isolation: worktree.
Mode A — Isolated workers (isolation: worktree in agent frontmatter)¶
An isolated worker runs in its own throwaway git worktree, not the shared checkout, so parallel workers never race on one git index. The worker does not push; the orchestrator does.
- Run quality gates (if code changed) — see Quality Gates below
- Commit on the assigned worktree branch — atomic, complete, working changes only
- Report back to the orchestrator: the commit SHA and a summary of files changed, tests added/modified, and any follow-up work discovered
- Stop there — do NOT
git push, do NOT merge, do NOT switch branches. The orchestrator merges the worktree branch, re-runs gates, and cleans up the worktree.
Recovery¶
- Worker stops at its
maxTurnsceiling without a completion report. Inspect the worktree (git -C <worktree-path> status,git -C <worktree-path> log), then resume the SAME worker with a focused continuation message rather than respawning one. - Orchestrator session is lost after a worker committed but before merge. List worktree branches (
git branch --list 'worktree-agent-*') and diff each againstmain(git log <branch> --not main) to find unlanded commits. Merge or discard deliberately. git merge --ff-onlyis rejected becausemainadvanced. Rebase the worker branch onto the currentmain, re-run gates, then retry the fast-forward merge.
Mode B — Non-isolated agents and sessions¶
- File follow-ups — anything left over goes to
TASKS.mdor a GitHub Issue - Run quality gates (if code changed)
- Update status —
TASKS.md;docs/tracking.mdwhen a feature/plan/ADR status changed - Commit with explicit pathspecs (never
git add -A); never commit.claude/settings.local.jsonor*.stackdump -
Ask the user before pushing. Every push to
maindeploys through CI, and approval for one push does not carry over to the next. Once approved: -
Verify — watch the CI runs for the pushed SHA ("Funny App Build and Deploy", "Deploy Frontend (React Build)", "Publish Docs") and smoke-test prod
- Hand off — leave clear context and artifact references for the next session
Rules:
- Never force-push; never push without the user's go-ahead
- If a push is rejected,
git pull --rebaseand retry once; still rejected → stop and report - Work goes straight to
mainhere; open a PR only when the user asks for one
Quality Gates¶
- API:
cd api && mvn verify(tests + LINE coverage ≥api/.coverage-threshold) - Webapp:
cd webapp && npm run lint && npx vitest run --root . && npm run build