# Agent Artisans

AI coding agents build most of this project, working straight from plain files in a git repo.
This page describes what actually happens — including a real mistake one of them made, and how
it got fixed.

## The setup

I run Claude Code agents against this workspace's repos (this one, and a sub-repo per game
attempt). An agent works on exactly what it's asked to work on. Nothing more.

## Why files instead of a project-management tool

Every piece of tracked work in /epics is a plain markdown file with YAML frontmatter on top —
an epic's overview.md, a regenerated status.md, one file per task for whichever epics are
actually being worked. No issue tracker, no separate login.

## The default is: do what you were asked

Earlier on, this ran the other way for a bit — tell an agent to "pick up an epic" and it would
invent its own tasks and open questions. Which produced a board with dozens of questions nobody
actually asked, nearly all of them premature. I deleted all of it, on purpose, no archive. The
rule now, in /epics/PICKUP.md: an agent does what the prompt says, generates nothing beyond
that, and when it hits real ambiguity it assumes, says what it assumed, builds, and reports —
it doesn't stop to ask. A question only gets raised (at most one a session) if it clears a real
bar: costs money, can't be undone, is public-facing, or reaches outside the repo. Most epics in
/epics are honestly marked parked — ideas worth keeping, not work happening — and that's
exactly why.

## One page for what needs me, kept small on purpose

/now ("Now") shows what's finished and waiting on my review, what's ready for agents, and the
small number of real, live choices I'm actually weighing
right now — not an inbox, not a queue an agent tops up. If it looks short, that's the design
doing its job, not a sign nothing's happening.

## Who edits what

The game's own design thinking —
[land-of-lor/docs/](https://github.com/krisrandall/land-of-lor/tree/master/docs), root and
[thought-specs/](https://github.com/krisrandall/land-of-lor/tree/master/docs/thought-specs) and
[historic/](https://github.com/krisrandall/land-of-lor/tree/master/docs/historic) alike — is
mine, human-owned; an agent reads it only when a task points there and never tidies,
reorganises, or "fixes" it, no matter how raw a voice-transcript note looks.
[epics/](https://github.com/krisrandall/land-of-lor/tree/master/workshop/epics),
[brand/](https://github.com/krisrandall/land-of-lor/tree/master/workshop/brand), and
[deliverables/](https://github.com/krisrandall/land-of-lor/tree/master/workshop/deliverables) are shared
ground — I edit them and so do agents, both validated the same way.
This site (site/) is agent-built, human-directed: I never hand-edit it, I just ask for what I
want and correct what comes back. It's also the line between public and private — this site is
public; the repositories behind it are all private, and this site is the project's one public
window into them. (These are all links to private repos — most visitors won't have access; the
live site shows a warning before following one.)

## What an agent actually did to make this site

Read every design doc in land-of-lor/docs/ (including raw voice-transcript notes), the existing
proofs of concept, and the workspace's conventions; wrote the epics and weekly
deliverables from that material; exported a working Godot proof of concept to WebAssembly so it
could be embedded and played in a browser; built this Astro site, then extended its own
epic-tracking mechanism into a formal Epic/Task/Question model — then, after over-decomposing
most of the board into premature questions, deleted nearly all of them and rewrote the pick-up
protocol around explicit asks instead of default autonomy. All in the same ongoing session.

## Built to be read by agents, not just people

- /llms.txt — a summary of the site with links to key markdown sources.
- Every content page is also available as raw markdown at its own path plus .md.
- /epics/index.json — every epic's frontmatter, tasks, and questions, in one machine-readable fetch.
- /questions/index.json — the small number of currently open decisions, in one fetch.