AGENTS.md

This repository is the source of https://brightspark.bonsung.me, a one-page job application site by Bonsung Koo. The spec, the plan, these rules and the lessons in docs/solutions/ are published on the site, so write for a public reader. These rules apply to every coding agent working here.

Where the work comes from

• A change to what the page does starts as a change to docs/spec.md.
• Work follows docs/plan.md, one task at a time.
• Read current library documentation through the Context7 MCP server before using an API (Next.js 16, Tailwind 4, Vitest, Playwright, unified, unpdf).
• docs/solutions/ holds lessons from problems already solved here, one per file with searchable frontmatter, relevant when planning or changing code in the same area.

Branches and pull requests

• Never commit on main or develop.
• One branch and one pull request per task. Every pull request for a task targets develop.
• A pull request from develop to main publishes the site.
• Never merge a pull request. Bonsung merges, in GitHub, with a merge commit.
• Write pull request titles and bodies in plain English about what changed and why, with no dates or durations, and follow the style rules below.
• Agent commits use a feat:, fix:, test:, docs: or chore: prefix and end with the co-author line: Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.

Checks before a pull request

npm run lint, npm run typecheck, npm run build and npm test must all exit 0. From the third task on, npm run test:e2e must too. Tick the task's boxes in docs/plan.md, then push the branch, open the pull request, and watch its checks until they pass.

Style rules for text written for the page

• No em dash, no en dash and no semicolon in sentences.
• airie is always lowercase.
• Do not claim hours or days of work.
• No dates or times on the /built pages.

No third-party files

Do not add any font, image, logo or icon file that belongs to any other company. The favicon is drawn in code, in src/app/icon.tsx. The fallback font comes from next/font/google.

What the hooks block, and why

Two hooks keep the rules above from being skipped by accident.

• .claude/hooks/guard.mjs runs before every shell command an agent makes. It blocks skipping git hooks (--no-verify, commit -n, changing core.hooksPath), pushes to main or develop, merging pull requests (gh pr merge and the merge API), and merging into main or develop. It is deliberately cautious, so a command that only mentions one of these is blocked too.
• .githooks/pre-commit refuses any commit made on main or develop.

Anything outward facing, such as creating the repository, a push to main, a deployment, a token or DNS, waits for Bonsung's go-ahead at that moment.