How projects work
What’s in progress, proposed, finished or shelved. On the site, the list of projects is generated by the build
from each project file: its folder gives the group, its title: (or first heading) the name, and its summary: the goal.
Nobody edits it by hand; on GitHub, browse the folders instead.
Project files
Section titled “Project files”One markdown file per project.
projects/*.md— active projects.projects/proposed/*.md— ideas not started yet. Move the file up intoprojects/when work starts.projects/done/*.md— finished projects.projects/shelved/*.md— rejected or postponed indefinitely. Add a dated line saying why.
A project file starts as a title, a one-line summary: in its frontmatter (the goal in the tables) and a
one-paragraph goal; add sections as the project needs them
(e.g. Done / Remaining, or Now / Soon / Distant). Larger projects with many steps or approval
gates can use the fuller shape, as aws-migration.md does:
---title: Short namesummary: One line: the goal, as shown in the project tablesstatus: draft | active | blocked # folder says proposed/done/shelvedlead: infra-lead | pm | marketing | architect # persona that drives itowner: <maintainer>started: YYYY-MM-DD---
## Goal / ## Context / ## Plan (tagged tasks) / ## Decisions / ## LogTasks are checkboxes tagged with who executes them:
@agent— an agent can do it unattended (read-only, or reversible and inside this repo)@pair— agent does the work, human reviews/approves before it takes effect@human— needs the human (console logins, payments, credentials, judgement calls)
- [ ] @pair Write Terraform for the Route53 zones · - [x] @human Create AWS account (2026-10)
When a task becomes real work, link it: an @human task gets an hq issue (labels project + area),
a @pair task gets the PR the agent built. See “Issues and PRs” in AGENTS.md.
Rules for agents working a project: work the first unblocked task you’re allowed to; never cross a
@pair gate without recorded approval in Decisions; add a Log entry each session; if
blocked, say on what (in frontmatter status if the file has it, otherwise in the Log).