brightspark.bonsung.me, design

Why

Bonsung is applying for an AI Led Software Engineer role through BrightSpark Recruitment. In that role most of the code is written by AI agents, and the engineer's value is in framing the problem, specifying the work, deciding when it is ready and proving the result is correct. His cover letter explains how he works that way: work starts from a written spec, checks that give the same answer every time keep the agents within bounds, hooks stop them committing straight onto main, and nothing reaches production until he merges it. A letter can only claim that. This site shows it.

The site does two things. It is the digital version of his CV. It shows how he works with coding agents, step by step, on the work that built the site itself. Each step comes with one real thing from that build, such as a rule the agents follow, a problem a review caught, or a decision an agent wrote down.

Goals

Show the agent workflow on real, inspectable work, not describe it.
Read as a clean CV for anyone who only wants the CV.
A calm, neutral look, with a hero that plays on the role's title.

Non-goals

A blog, a contact form or a CMS.

Anti-goals (a failure even if it works)

A showcase quotation that is not in the file it cites. The evidence is the point.
Evidence made up to fill a step. A step where nothing happened says so plainly.
A showcase so long that the CV above it is hard to find.

Decisions

Show the agent workflow by building this site with it.
The workflow as a showcase. The page closes with How this page was built: the rules the work rests on, then the workflow in seven steps, each with one real piece of evidence from building this site, kept short enough to read in full.
The site is the digital CV. The CV's text is on the page. The cover letter points to the site as the digital CV that also shows how he works with agents.
The working documents are published. The spec, the plan, the agents' rules and the lessons are pages of the site.
The hero's look: the hero's light slate background and ink text, a medium-weight headline with tight line spacing, the role line in teal, and a teal button. The dark slate serves the showcase and the footer.
Hero copy, a play on the role's title. The role is AI Led Software Engineer. The hero reads:

Kia ora, AI-led code. Engineer-led AI. Bonsung Koo AI Led Software Engineer Hire (a button)

The headline turns the title around: the agents lead the code, and an engineer leads the agents. His name sits on its own line above the role line, and the role line is the title as written. Nothing moves. Hire is a teal button that opens an email to developer@bonsung.me. The share card shows the same hero, his name above the role line too, and the link's description is its greeting and headline together.
A plain footer with his name and contact links.
Address brightspark.bonsung.me.
The tab shows a BK monogram, drawn in code for this site.
Each section shows how it was built, beside it. On a wide screen a column on the left holds the rules and the seven step titles and, level with each CV section, that section's card: what happened at each of the seven steps while that section was built, faded where nothing did. The cards are written from the build record and kept true by tests. On a phone each CV section ends with the same card, closed, and the rules and the seven steps stay after Education.

Look

Token	Value	Use here
ink	`#0f172a`	body text, headings on light bands
hero	`#e8eef5`	hero background
mist	`#f1f5f9`	the rail, light sections
line	`#e2e8f0`	rules and borders
paper	`#f8fafc`	alternate light sections
white	`#ffffff`	cards, white sections
slate	`#1e293b`	the showcase
night	`#0f172a`	footer
fog	`#e2e8f0`	text on slate
snow	`#f8fafc`	titles on slate
teal	`#0f766e`	the Hire button, links, the role line

Font: "Avenir Next", Avenir, … first, which Apple devices already have, then a free, openly licensed fallback of a similar shape for other devices.
Shapes: buttons with a 5 px radius.
Contrast: every text and background pair meets WCAG AA.

The page, top to bottom

Hero (Decision 6).
Introduction: the CV summary, in his own first-person words.
Key strengths: the CV's five strengths, which hold the claims about agent-driven work that this site sets out to prove.
Experience: airie, Shopl and Company, PJ FACTORY, with the CV's job titles and dates. airie is always lowercase.
Projects: Sentinel, with its two public links.
Education.
How this page was built: the showcase (below).
Footer: his name, GitHub and an email address.

On a wide screen the rail (below) sits beside sections 1 to 6.

The text of sections 2 to 6 is the CV's text. It is not rewritten for the site.

How this page was built

A dark slate section after Education. It opens with one line:

How I work with coding agents, shown on the page you are reading.

Then the rules, numbered 0 under a small caption, Before every session, since they are in place from the start of every agent session rather than a step of their own. Then seven numbered steps. The rules and each step have a title, one sentence, and one short piece of evidence set apart from the text, under a small label naming where it comes from.

Refined, not exhaustive. The showcase is meant to be read in full, so it shows one clear piece of evidence per step. The full spec and plan are one link away for a reader who wants them.

The showcase's Read the rules, Read the spec, Read the plan and Read the lessons open the rules, the spec, the plan and the list of lessons from the top.

Every word in the Title, Says, Label and Evidence columns is the page's copy, as written. Typographic quotation marks and apostrophes on the page are fine. Code names (main, docs/spec.md) are set as code.

#	Title	Says	Label	Evidence	Checked against
0	Keep the rules in the repository.	Hooks stop the agents committing or pushing to `main`, and merging.	The agent hook	"Agents never merge pull requests. Bonsung merges." Read the rules (a link)	the agent hook's own output for a merge command
1	Agree the spec first.	I talk each change through with the agent until we agree a written spec.	From AGENTS.md	"A change to what the page does starts as a change to `docs/spec.md`." Read the spec (a link)	the line in `AGENTS.md`
2	Plan small tasks, with their tests.	Each task names its tests before any code exists, and Context7 keeps the plan on current library documentation.	From the plan	"every experience line is the CV's text" Read the plan (a link)	the test name in the CV's task in `docs/plan.md` and in the content tests
3	One agent builds, another reviews.	A fresh agent checks each task against the spec.	From a review	A review found the CV check would still pass a bullet cut in half. Each section is now also checked against the PDF's length, and deliberate cuts fail.	the length check in `tests/cv.test.ts`
4	Write down judgement calls.	Each one records what was decided, why, and what it costs if wrong.	From the decision log	White on teal reaches about 5.5 to 1, so every colour pair meets the stricter contrast rule and no exception for large text was kept.	`TEXT_PAIRS` in `src/content/theme.ts` holds white on teal, and no large-text list exists
5	Checks decide, and I merge.	Every pull request passes checks that give the same answer every time, and only I merge into `main`.	On every pull request	Build, test, lint, typecheck, history	the job names in the CI workflow
6	Review the whole at the end.	A more capable model reviews the finished site at once.	From the final review	It found a card describing a judgement call that was never made. That step now says None needed.	the Key Strengths card's quiet step 4 in `docs/spec.md`
7	Write down what was learnt.	Compound Engineering writes the lessons from solved problems into `docs/solutions/`, where the agents look when they plan.	From docs/solutions	Tests that could not fail Read the lessons (a link)	the title of that file in `docs/solutions/`

The evidence is real. A test fails if a quotation is not in the file it comes from, or if what a story points to is missing from the repository (the last column). Until a step's evidence has happened, the step says so plainly and is shown faded.
Tone: short, plain English, no jargon a hiring manager would trip on.
On a phone the steps stack, and the evidence sits under its text.

The rail

On screens 1024 px wide and wider, a light slate column, the rail, runs down the left of the page and scrolls with it. It is 26rem wide, and its steps are set at the size of the CV's body text, with each card's title one step larger. It holds two things.

The rules and the seven steps, beside the hero: the showcase's titles, the rules numbered 0, each a link to it in the showcase below.
One card per CV section, all shown at once, each with its title level with its section's heading, except the hero's card, which sits under the steps. A card's title is the section's heading, or Hero for the hero. Under it, a short timeline of the seven steps, each numbered as in the list above, with its name and one line of what happened at that step for this section. Steps where nothing happened stay in the timeline, faded. The spec line links to the first block of the published spec that contains it, and test names are set as code. Each step whose source is published links to it. Step 2's plan task links to its heading on /built/plan, and each of its tests to the block of that task where the test is written. Step 7's lesson links to its page under /built/lessons/. Steps 3 to 6 have no link. The rules are not on the cards, since they hold for every section alike.

On narrower screens there is no rail. Each CV section ends with a closed How this section was built that opens to the same card. The showcase itself stays after Education on every screen.

A keyboard reader meets a Skip to the CV link first, so the rail's links never stand between them and the CV. The footer lines up with the CV beside the rail.

The cards' copy is written from the build record when the rail is built, and kept here, one table per card, word for word. A step marked quiet is one where nothing happened for that section, and it is shown faded.

Hero

#	Step	What happened
1	Spec	“Hero copy, a play on the role's title.”
2	Plan	Task 3, with `the Hire button writes to developer@bonsung.me` named first
3	Built and reviewed	The review found a contrast test that checked an empty list, so it could never fail. The list and the test were removed.
4	Judgement call	The icon is built once with the site, since the static export refuses an icon made on request.
5	Checks and merge	Pull request #2, five checks passed, merged by me.
6	Final review	It found no name on the first screen. The name now sits above the role line.
7	Lesson	Tests that could not fail

Introduction

#	Step	What happened	Quiet
1	Spec	“the CV summary, in his own first-person words”
2	Plan	Task 4, with `the introduction is the CV summary` named first
3	Built and reviewed	The review found a shortened introduction would still pass. Its length is now checked against the PDF.
4	Judgement call	None needed.	quiet
5	Checks and merge	Pull request #3, five checks passed, merged by me.
6	Final review	It found step 4 described a rule, not a decision. It now says None needed.
7	Lesson	A CV check that passed cut and added text

Key Strengths & Achievements

#	Step	What happened	Quiet
1	Spec	“the CV's five strengths, which hold the claims about agent-driven work”
2	Plan	Task 4, with `every key strength is the CV's text` named first
3	Built and reviewed	The review found the last strength could be cut short and still pass. Each section's length now has to match the PDF.
4	Judgement call	None needed.	quiet
5	Checks and merge	Pull request #3, five checks passed, merged by me.
6	Final review	It found step 4 described a decision that was never made. It now says None needed.
7	Lesson	A CV check that passed cut and added text

Work Experience

#	Step	What happened
1	Spec	“airie, Shopl and Company, PJ FACTORY, with the CV's job titles and dates”
2	Plan	Task 4, with `every experience line is the CV's text` named first
3	Built and reviewed	The review found a bullet cut in half would still pass. The check now also measures each section against the PDF.
4	Judgement call	The PDF lists some job headings after Education, so Work Experience, Selected Projects and Education are measured together.
5	Checks and merge	Pull request #3, five checks passed, merged by me.
6	Final review	It added an unmarked sentence here and every test still passed. Each section's whole text is now compared with the PDF.
7	Lesson	A CV check that passed cut and added text

Selected Projects

#	Step	What happened	Quiet
1	Spec	“Sentinel, with its two public links”
2	Plan	Task 4, with `every project line is the CV's text` and `every external link is on the allowed list`
3	Built and reviewed	The review noted its links are checked against the allowed list, not against their link text.
4	Judgement call	None needed.	quiet
5	Checks and merge	Pull request #3, five checks passed, merged by me.
6	Final review	It found step 3 made the review sound fuller than it was. It now says what the review noted.
7	Lesson	A CV check that passed cut and added text

Education

#	Step	What happened	Quiet
1	Spec	“The text of sections 2 to 6 is the CV's text.”
2	Plan	Task 4, with `every education line is the CV's text` named first
3	Built and reviewed	The review found a dropped entry would still pass. The number of lines is now counted too.
4	Judgement call	None needed.	quiet
5	Checks and merge	Pull request #3, five checks passed, merged by me.
6	Final review	Nothing for this section.	quiet
7	Lesson	A CV check that passed cut and added text

The cards are true. A test fails if a card's spec line is not in docs/spec.md, if a plan task it names is not a task in docs/plan.md, if a test it names is not a test in the repository, if a lesson it names is not the title of a file in docs/solutions/, or if a CV section has no card or a card does not have all seven steps.
Refined, not exhaustive, as for the showcase. One line per step, never a list.

The published documents (`/built`)

Plain pages in the site's style, reached from the links on the page, not from the main navigation. Each page's header links back to the page, then to the rules, the spec, the plan and the lessons, in the order the showcase gives them.

/built/rules: AGENTS.md, the rules every coding agent follows here, each line addressable.
/built/spec: the published spec, each line addressable.
/built/plan: the step-by-step plan the agents worked from, task by task.
/built/lessons: the list of lessons, each title a link to its page.
/built/lessons/<name>: each lesson in docs/solutions/, without its frontmatter.

How the repository works

The repository uses the workflow the letter describes.

Agent instructions in the repository: an AGENTS.md (and a CLAUDE.md that imports it) telling coding agents how to work here: spec first, the plan, the checks, the branch rules, the style rules.
Spec first: the spec and the plan live in the repository. Changes to what the page does start as changes to the spec.
Checks that give the same answer every time: tests, a production build, lint, a type check and the history check, run in CI on every pull request.
Hooks:
- a git pre-commit hook that refuses commits made directly on main or develop,
- a coding-agent hook that stops an agent skipping the git hooks (for example --no-verify), pushing to main or develop, or merging a pull request.
Work reaches main through develop: each task's pull request targets develop, and a pull request from develop to main publishes the site.
Only Bonsung merges, into develop and into main, after the checks pass. The history check fails if the history of main or develop holds anything but merged pull requests, or a merge by anyone else.
Commits by agents say so: agent-written commits carry a co-author line for the agent.

Checks

At least these, run in CI and locally:

Content: every Introduction, Key strengths, Experience, Projects and Education line on the page equals the text of the CV. The CV's PDF is kept with the tests as their source.
The evidence is real: as above.
The cards are true: as above.
main is merges only: as above.
Style, for text written for the site: no em dash, en dash or semicolon, airie never capitalised, no hours or days claimed. The CV's own text is checked against the CV instead.
Third-party material: no font, image, logo or icon file from another company.
Links: every external link on the page is one of an allowed list.
Build, lint, type check.

Deploy

Hosting: Vercel. main publishes to brightspark.bonsung.me, and develop is previewed at Vercel's address for the branch before it is published. Pull requests get preview deployments. The build needs nothing from git or GitHub, so it needs no token.
Domain: a DNS record for brightspark pointing at Vercel.
Analytics: Vercel Web Analytics counts page views without cookies, and keeps production apart from previews.

Verification before the link is shared

CI is green on main.
https://brightspark.bonsung.me opens in a real browser with a valid certificate.
The showcase reads well on a desktop and a phone width, and its links open the rules, the spec, the plan and the list of lessons.
Nothing in the hero moves.
The share card shows when the link is pasted into a chat or a social site.
On a desktop each card sits beside its section and shows all seven steps. On a phone the rail is gone and each section's note opens.

Out of scope

A contact form, a blog, other languages, a CMS, a CV download, and any page other than this one and its published documents.