My Claude Code pyramid: one lead, role agents, mission agents

Paste it into Claude Code, in a project folder (terminal, or Claude app, Code tab). It only writes in that folder and deletes nothing. Claude will ask you to allow what it writes: read it, then allow it.

Install "the pyramid" in my current folder: one LEAD (this session) that talks with me and splits the work, ROLES (one sub-agent per area, with its own rules and its own STATUS.md) and MISSIONS (one sub-agent per task, which delivers, archives its trace and stops). Plus a relay: when a session gets too heavy, it writes its notes into a handoff, restarts from zero and reads them back. An automatic summary loses detail; written notes don't.

Do all the steps yourself, in order. If a step fails, stop and tell me why.

Rules for the whole install:
- Write only in the current folder: nothing in my home folder or in ~/.claude, no global setting changed.
- Install nothing, no internet, no MCP server.
- Delete and overwrite nothing. If CLAUDE.md exists, add your section at the end. If .claude/settings.json exists, merge into it. Any other file already there: leave it alone and tell me. Show me any text added to an existing file.
- Never a secret (key, password, token) in these files.
- Already installed (a "## Pyramid" section in CLAUDE.md, or a hook group that contains STATUS.md): do not add it a second time, tell me.

0. Print the current folder. If it is my home folder (~) or the root /, stop and tell me to restart Claude Code in a project folder. Otherwise list what exists (CLAUDE.md, .claude/, STATUS.md, roles/, missions/, handoffs/) without changing anything.

1. Ask me ONE question only: "What are your 2 to 4 areas of work, a few words each?" Wait for my answer before creating anything. If there is no clear answer (nothing, "default", I don't know): product, communication, admin. More than 4: keep the first 4. For each, a short lowercase <name>, with no accent and no space.

2. Add at the end of CLAUDE.md (or create it):

## Pyramid
The LEAD is the main session: it talks with me, splits the work and does not do the long work itself. The ROLES are sub-agents (.claude/agents/): <name> (role in one line), etc. MISSIONS go through the "mission" sub-agent: one task, one deliverable, then stop. A role or a mission follows its own agent file. Rules for everyone:
1. The lead delegates the long work and launches the missions itself.
2. Reports of 5 lines at most: the lead follows delegated work through these reports, not through the details. A mission sends only one, at the end.
3. At the end of the work, update your own STATUS.md (the lead: the root one; a role: roles/<name>/STATUS.md; 15 lines at most: Done, In progress, Next step, Key files).
4. Never invent a fact, above all in a STATUS.md or a handoff. "I don't know" is allowed.
5. Never a secret (key, password, token) in a file.
6. Long session, or one that is losing details: suggest /relay to me.

3. In .claude/agents/, one <name>.md per role. The description comes from my words only, nothing invented ("to be specified" if I said nothing); front matter values in quotes, so the YAML stays valid:
---
name: <name>
description: "Role <name>: <what I do in this area>. For any work in this area."
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
---
Body of 10 lines at most: role in one sentence; first read roles/<name>/STATUS.md, then handoffs/<name>.md if it exists; stay within its area; no secret and no invented fact; at the end of the work, update its STATUS.md; finish with a report of 5 lines at most (done, deliverable and path, blocker, next step).
Plus mission.md: same front matter, with name: mission and description: "One-off mission: one brief, one deliverable, then stop." Body: a single mission, nothing more; no secret and no invented fact; write its trace to missions/archive/YYYY-MM-DD-<short-name>.md (today's date from `date +%F`; brief, what was done, deliverable and path, what is left; if the file already exists, change the short name); never edit or delete an archive; a single report of 5 lines at most, then stop.

4. Create roles/<name>/STATUS.md for each role, and STATUS.md at the root (if it already exists: leave it as it is and tell me), with this template:
# STATUS: <folder name, or role>
Updated: YYYY-MM-DD
## Done
-
## In progress
-
## Next step
-
## Key files
-
At the root (if you create it), under "Done", only: pyramid installed on <date>. Also create the empty folders missions/archive/ and handoffs/.

5. In .claude/commands/ (front matter, values in quotes: description, plus argument-hint if there is an argument):
- relay.md: role = $ARGUMENTS (one lowercase word, no space or /), or "lead" if empty. Write handoffs/<role>.md in 40 lines at most: where I am, decisions made, pitfalls, a precise next step, files to re-read. Rewrite the file keeping what is still true; verified facts only, otherwise "to check". Then tell me: "Type /clear: I will read this handoff back on restart."
- catchup.md: read STATUS.md, the roles/*/STATUS.md and handoffs/lead.md (say if there are other handoffs in handoffs/). Answer in 5 lines at most: where we stand, what is blocking, next step. Missing info: say so.
- mission.md: launch the mission sub-agent with the brief $ARGUMENTS (empty or vague: ask me a single question first), then relay its report in 5 lines at most and update the root STATUS.md if needed.

6. In .claude/settings.json, add this group to hooks.SessionStart (keep everything that exists, create the missing keys):
{"hooks": {"SessionStart": [{"matcher": "startup|clear|compact", "hooks": [{"type": "command", "timeout": 10,
"command": "cd \"${CLAUDE_PROJECT_DIR:-.}\" || exit 0; if [ -f STATUS.md ]; then echo '--- STATUS.md ---'; head -n 20 STATUS.md; fi; if [ -f handoffs/lead.md ]; then echo \"--- Lead handoff (a role ignores it) ---\"; head -n 60 handoffs/lead.md; fi; exit 0"}]}]}}
It only reads back the lead's handoff (handoffs/lead.md); a role reads its own through its agent file. Its output goes into your context at startup, after /clear and after an automatic summary.

7. Check: list the files created or modified; the JSON of .claude/settings.json is valid (re-read it, without installing any tool); each agent starts with a front matter between two --- lines with name (equal to the file name), description, tools and model; run the hook command once with sh -c, without creating any temporary file outside the folder, it must print STATUS.md without error. Fix what is missing.

8. Conclusion for me, 8 lines at most:
- what was created;
- quit and restart Claude Code in this folder to load agents, commands and hook;
- the 3 phrases: /catchup (where we stand), /mission <brief> (a one-off task), and /relay then /clear when a session gets heavy (the lead reads its own handoff back);
- a session dedicated to a role: claude --agent <name> in another terminal, then /relay <name>;
- in one sentence, what it does not do: no side-by-side view of several sessions, no automatic relay (I type /relay then /clear myself), no session archiving in an app; roles and missions are sub-agents.