Agents & How We Work

Repo taxonomy

• Domain repos vs. the coordination layer. ReqDoc, flme-release-coordination, ux-template, backend-template, and FLME-Site each belong to one agent and hold that agent's own STATE.md. flme-agents (this repo) is the home for agents that coordinate across those repos instead — Nora, Sage, Marlowe, Hearth — plus the shared conventions every agent reads. An agent belonging to one domain repo keeps its state there, never duplicated here, to avoid two copies that could drift. See the Repo Atlas for the full inventory across all ~15 FLME repos, not just the ones with a named agent.
• Folder-per-agent, one STATE.md each. No per-session subfolders — a session claiming an agent's identity edits that agent's one file; git itself (commit history, session-ID provenance, fetch-before-edit) catches two sessions colliding, rather than forking into files that could disagree.
• STATE.md is current truth; engineering logs are history. If they ever disagree, the STATE.md wins. One level up, flme-agents/README.md's "who's who" table is the tiebreaker if any agent's own docs disagree about another agent's scope — update the README first, then fix the stale reference. This same rule is why the wiki's own Repo Atlas and Open Questions pages are pointer pages, not a competing source of truth — README.md and each STATE.md stay canonical.
• .claude/skills/ holds generic, reusable Claude Code skills shared across FLME agents — one folder per skill, each with a SKILL.md. Lives under .claude/ because that's the location Claude Code actually discovers skills from (confirmed directly against a real Claude Code install before moving it there, 2026-08-24) — not a plain top-level skills/. Owned by Nora.

SYNC.md — the cross-cutting conventions

A small set of rules apply to every FLME agent, in every repo, regardless of home repo or runtime — kept in one file (flme-agents/SYNC.md) instead of copy-pasted into every agent's own STATE.md, where copies could drift apart as each got edited independently. If any agent's file ever states one of these differently, SYNC.md wins. Every agent reads it every session — auto-loaded for the four whose home repo is flme-agents; an explicit pointer in STATE.md for Sam, Wren, and Herald, whose home repos don't pick up a sibling repo's CLAUDE.md automatically.

• Commit-vs-push, sharpened. "Commit" alone never authorizes a push, even if push was authorized last time — committing on an agent's own judgment is fine, but push always needs Jake's own separate, explicit word, every time. "Commit and push," said together in one instruction, is real and sufficient authorization for both at once — no need to hold and ask again.
• The goldfish readability test — see Elephant & Goldfish below; this is the second, distinct use of a Goldfish beyond execution.
• Push problems: pause and ask, don't self-resolve. An ordinary rejected push still follows its repo's own documented recovery (fetch, rebase once, retry, stop on a second failure) — that's routine. But a real conflict, another session's in-flight uncommitted work, or anything else unexpected means stop and ask Jake what to do, rather than improvising a stash/rebase/hand-crafted-patch workaround — even one that would technically work. (Established 2026-09-01, after exactly that happened on flme-release-coordination.)

Elephant & Goldfish

• Two roles within either local-CLI runtime, not a fourth runtime. An Elephant is the persistent identity: reads and maintains STATE.md, is who gets addressed by the agent's plain name. A Goldfish (<Name>-GF, memoryless — never reads STATE.md) has two genuinely distinct uses:
• 1. Executor (the original use, piloted by Wren's WRENS-GF before the role had a name) — takes a fully self-contained task from its Elephant or from Jake and executes it: file writes, git commits, even STATE.md updates — freeing the Elephant's own context for coordination rather than execution. Not every agent needs one; Sam and local-CLI Nora decided against a Goldfish since direct git-write already gives them what one would offload.
• 2. Reader — the goldfish readability test (added to SYNC.md 2026-08-31/09-01, a distinct concept from the executor use above). Before a design doc, plan, or brief moves from the Elephant conversation that produced it to a session that wasn't part of that conversation — another Goldfish, another agent, a local-CLI implementer — spin up a throwaway, memoryless session and give it only the document. Ask it to restate the plan or attempt the first concrete step. If it can't do that cold, the document isn't ready — fix the document, not the goldfish. This use never requires creating or naming a persistent agent; it's discarded once the check is done, and doesn't belong in README.md's roster the way a named <Name>-GF would.
• Starting or resuming any agent — Elephant or Goldfish, in any of the three runtimes (Cowork; standalone local Claude Code CLI; local CLI moved to Desktop via /desktop) — follows one fixed shape via flme-agents/README.md's "Starting a new instance" section and scripts/start-agent.sh. See the usage page for the full walkthrough.

Lessons learned

• Identity comes from your kickoff message and session name — never from what STATE.md says, and never inferred from which runtime you're running under. On 2026-08-23, a session was kicked off explicitly as Wren ("You're Wren, the UX Build Agent") but misidentified itself as WRENS-GF instead, because ux-template/STATE.md's own text at the time hard-coded "a local CLI session here is WRENS-GF" — true right up until that same day, when Wren herself first became able to run as a standalone local-CLI Elephant too. The session read the stale rule, correctly noticed it was local CLI, and (reasonably, given what the file said) drew the wrong conclusion — overriding its own explicit kickoff message. Fixed in ux-template/STATE.md (identity split by name, not runtime) and generalized in CLAUDE.md project-wide, with this incident as the worked example. Worth remembering any time an agent's runtime options expand: old runtime-based identity language is a candidate for the same bug.
• Independent verification is a first-class practice. No agent's report — including its own — counts as done until it's checked directly against source: real diffs, real command output, real cross-checks, not a trusted summary.
• Freeze is always a human/team decision. A clean gate report makes a release freeze-eligible, never freezes it automatically.
• None of the agents have direct git-write access to a domain repo via the remote-device bridge — implementation, commits, and pushes route through a local Claude Code CLI session.