discussion: per-architect state files: convention, role-doc instructions, CLI tooling, gitignore (full proposal)

[amrmelsayed]

Status

Discussion / pre-spec. Establishes per-architect state files as a first-class Codev concept across multiple components: convention, role-doc instructions in CLAUDE.md / AGENTS.md / architect.md, tooling (CLI + VS Code surface), and the small .gitignore rule that lets it work cleanly in team environments. Lands as a spec or PIR once the open questions converge.

Problem

A Codev architect accumulates context that has no good home today.

• The conversation buffer loses it on /clear or session end.
• The auto-memory system is per-user-cross-project; private to one machine, not shared with the team, not tied to the project.
• codev/roles/architect.md is the architect's system instruction; permanent, generic, not for evolving working memory.
• Builder thread files (codev/state/<builder-id>_thread.md) are per-builder and time-bound.

The four surfaces above don't cover: project-scoped architect-level working memory that survives across sessions. Decisions in flight, handoff notes, cross-cycle continuity, half-formed designs waiting for a moment to file, conventions that apply to this project but aren't yet Codev framework-level. Some engineers (this architect included) have started writing this to codev/state/<architect-name>.md by hand, in symmetry with the existing builder-thread convention. The pattern works at the personal level; it has no Codev support and no team-environment story.

This issue scopes the work to make per-architect state a recognized concept with documentation + tooling + scaffolding, not just a personal habit.

Components

1. Convention

• Path: codev/state/<architect-name>.md, paralleling the existing <builder-id>_thread.md pattern at the same level. One file per architect, named after the architect's name in Tower.
• Visibility: local-only by default (see component 4). Treated as personal working memory, not team-visible coordination state. Architects who want to surface something cross-team commit it elsewhere (PR description, separate handoff doc, an issue).
• Shape: flexible markdown. Recommend top-of-file snapshot (what's true right now) followed by append-only log (how we got here), but no schema enforcement.
• Lifetime: persists across sessions, across releases, across builder lifecycles. Survives /clear. Owned by the architect for as long as the architect exists in Tower.

2. Role-doc instructions (CLAUDE.md / AGENTS.md / codev/roles/architect.md)

The single biggest leverage point. Without an instruction in the role-doc, architects won't volunteer to maintain the file. Proposal: add a new section to codev/roles/architect.md (and reflect in CLAUDE.md / AGENTS.md per their existing sync discipline) covering:

• What the file is for: persistent architect-level working memory, scoped to this project.
• Path it lives at: codev/state/<your-architect-name>.md.
• When to read it: at session start, especially after a /clear or a fresh session.
• When to update it: at natural pause points , end of a release, after spawning a batch of builders, after making a non-obvious decision, before the user is likely to /clear. Not per-turn. Not for things already captured in commits, PR bodies, or builder threads.
• What to write: in-flight decisions and their rationale, things you're mid-considering and don't want to lose, handoff context, references that tie issues together (e.g. "consult: pre-flight auth-state cache for agy to prevent N-spawn browser-tab burst on unauthenticated state #1077 depends on the verdict-parser landing, video script lives in tmp/release-videos/").
• What NOT to write: noise, per-turn updates, things already in the git history.
• The "surface the question" clause: when in doubt about whether something is worth recording, the architect should ask the user rather than silently write. Prevents both over-recording and under-recording.

CLAUDE.md / AGENTS.md must stay byte-identical (per the existing repo convention , they ship to two tool ecosystems).

3. Tooling

Minimum useful CLI additions to afx once the pattern is supported:

• afx state , open the current architect's state file in $EDITOR. If the file doesn't exist, scaffold it with a frontmatter snapshot and a starter section.
• afx state cat , print the file to stdout without opening an editor. Useful from scripts and for piping to other tools.
• afx state <architect-name> , open another architect's state file (errors cleanly if local-only and not present).
• afx state list , list all state files in codev/state/ that are not builder threads. Shows the architect names, last-modified date, line count.

Resolution: the "current architect" is the one Tower has registered for the active terminal (the CODEV_ARCHITECT_NAME env var Tower injects, per existing convention from #1058).

VS Code surface (optional, can land later):

• An "Open State" action on each architect row in the Workspace tab's Architects tree. Mirrors the existing "Open Architect Terminal" right-click action.
• A Cmd+K S keyboard shortcut bound to codev.openArchitectState for the current architect.

4. Scaffolding (.gitignore)

In team environments, multiple humans each running an architect named main would collide on codev/state/main.md. The cleanest resolution per the discussion that led to this issue: treat architect state files as personal and gitignore them. Architects who want team-visible coordination state surface it through other channels.

Add to codev-skeleton/.gitignore (and this codev repo's .gitignore):

# Per-architect state files: personal working memory, local-only.
# Builder thread files (codev/state/<protocol>-<id>_thread.md) stay tracked.
codev/state/*.md
!codev/state/*-*_thread.md

The negation pattern preserves the existing per-builder thread tracking. Anyone not using the per-architect pattern is unaffected.

Open questions for discussion

1. Should the state file be local-only (gitignored) or team-visible (committed under an owner-namespaced subdirectory)? This issue leans local-only for v1 simplicity. The team-visible model (codev/state/architects/<owner>/<name>.md, with <owner> derived from git config) is reversible if a concrete coordination use-case emerges.
2. Does the role-doc instruction live in codev/roles/architect.md only, or also in CLAUDE.md / AGENTS.md? The latter ships to every project; the former is local. Probably both, given the existing byte-identical discipline.
3. Is afx state the right command name? Possibly conflicts with future state-related tooling. Alternatives: afx note, afx memo, afx architect-state. The shorter the name the more useful in practice.
4. VS Code surface: ship in v1 or defer? A "Open State" action on the Architects tree is small. Defer if v1 should be CLI-only and validate the pattern first.
5. Should the file scaffold include a frontmatter convention? E.g. architect: main, created: 2026-06-21, last_session: .... Useful for future tooling; adds discipline cost for the writer.
6. Symmetry with builder threads is intentionally broken (builders are tracked-on-merge, architects are local-only). Should we be explicit about this asymmetry in the role-doc, or let it pass without comment? The architect-vs-builder lifetime difference (time-bound vs persistent persona) makes the asymmetry defensible.
7. afx state list showing only your own files (because team files are gitignored) breaks the natural "see what siblings are thinking" flow. Is this acceptable, or does it argue for the team-visible model?

Proposed acceptance criteria (subject to discussion)

If the discussion converges on the proposal above:

• Convention documented in codev/roles/architect.md with path, shape, lifetime, update-trigger guidance, and the "surface the question" clause.
• CLAUDE.md and AGENTS.md updated with a brief pointer to the convention (per the existing byte-identical sync rule).
• codev-skeleton/.gitignore updated with the per-architect state-file exclusion + builder-thread negation pattern.
• This codev repo's .gitignore updated with the same rule.
• afx state, afx state cat, afx state <name>, afx state list implemented in packages/codev/src/agent-farm/commands/. Resolves the current architect via CODEV_ARCHITECT_NAME.
• Scaffolding helper: afx state on a missing file generates a starter template with a one-line snapshot section and an empty log section.
• Tests: unit tests for the CLI command resolver + integration test for the scaffold-on-missing path.
• (Optional, separate sub-issue) VS Code: codev.openArchitectState command + "Open State" action on the Architects tree row + Cmd+K S default keybinding.

Out of scope

• Sharing architect state files team-wide (option B / C from the prior conversation). Revisit if a concrete coordination use-case emerges that local-only state can't serve.
• Auto-prompting the architect at session-end ("save your state?"). Too aggressive; the role-doc instruction + manual prompts cover the trigger model adequately.
• Auto-syncing architect state files to a hosted backend (Linear, Notion, etc). Out-of-band integration; not a Codev concern.
• Changing the per-builder thread convention. Builder threads stay as they are (tracked, lands on main post-merge).
• Forking architect identity in Tower's state.db to add an owner column. Architect rows stay name-only.
• A formal schema or YAML frontmatter requirement (see open question 5).

Related

• Multi-architect coordination layer for codev/afx (roster · board · dedup-at-spawn · lifecycle · bounded state · checkout isolation) #984: Multi-architect coordination layer for codev/afx. Broader umbrella that this issue sits inside.
• afx: handoff / pickup commands for transferring in-flight builders between team members #1008: afx handoff / pickup CLI. Composition consideration: gitignored state files can't be the source of handoff context, so afx: handoff / pickup commands for transferring in-flight builders between team members #1008 has to source it elsewhere (PR description, separate handoff doc, etc).
• vscode: handoff / pickup UI (right-click handoff, incoming pickup surface, read-only state on donor) #1009: VS Code handoff / pickup UI. Same composition consideration as afx: handoff / pickup commands for transferring in-flight builders between team members #1008.
• feat(vscode): Architects tree — Add Architect UI, Cmd+K A picker, label casing #841 / PR feat(vscode): Architects tree — Add Architect UI, Cmd+K A picker, UPPERCASE labels #1082: Add Architect UI shipped in v3.2.1. Establishes the Workspace tab Architects tree where the optional "Open State" action would live.
• feat: VS Code Workspace sidebar — list all architects (multi-architect follow-up to #761) #770: Multi-architect sidebar listing. Foundation for the VS Code surface.
• afx skill missing workspace recover / add-architect / remove-architect subcommands #889: afx skill missing workspace recover / add-architect / remove-architect subcommands. afx state would be added in the same module.
• Standardize architect capabilities, strict validation, and Codex skills scaffolding #1078: Standardize architect capabilities, strict validation, and Codex skills scaffolding. Architect state is one capability/dimension this could touch.
• codev/roles/builder.md:145-158: the per-builder thread convention this pattern is symmetric to (with the deliberate lifetime asymmetry noted above).

[waleedkadous]

Thanks for this, Amr. I had suggested something similar in #984. I was thinking we could do something even simpler. I was thinking that we only need `afx whoami` that returns who the architect is. Then we rely on file system naming to work out the rest, e.g. codev/state/architect/main.md (maybe we want to expand this to other ones in future too?). The `afx state` seems like overkill to me and makes us have to use a command (which goes wrong with ai since it forgets how to use afx every so often.

I am actually pretty open to the idea of them being in the team structure. This really does open things up to give others visibility in the team. What I'd recommend is a setting in .codev/config.json something like COMMIT_STATE_FILES -- and it would be good if commits to the codev/state directory did not trigger emails to people. I don't know if github has a way to do that.

Does it make sense to pull anything from #984 into this since you'll be touching the same components?