Skip to content

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.

One markdown file per project.

  • projects/*.md — active projects.
  • projects/proposed/*.md — ideas not started yet. Move the file up into projects/ 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 name
summary: One line: the goal, as shown in the project tables
status: draft | active | blocked # folder says proposed/done/shelved
lead: infra-lead | pm | marketing | architect # persona that drives it
owner: <maintainer>
started: YYYY-MM-DD
---
## Goal / ## Context / ## Plan (tagged tasks) / ## Decisions / ## Log

Tasks 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).