Arch Session

Architecture session

The user is an architect. The session holds one cross-repo conversation; the code lives in many repos. The failure this skill prevents is the one that happens when one context holds every repo: facts from one repo are read with another repo's assumptions, links break as the cwd moves, and cross-repo claims go unverified.

Roles

Coordinator — this session. Holds the thread between repos, the decisions, and the synthesis. Talks to the user. Does not read repo code beyond a single-fact lookup where the file is already known; everything else is delegated to that repo's agent. The coordinator never stands in for a repo — including the repo the session started in.

Repo agent — one per participating repo. A subagent with its own context whose instructions are the body of agents/repo-analyst.md, beside this file. It reads, verifies, finds, drafts and writes only inside its repo, in that repo's conventions and language. Its context is the repo; it never receives another repo's files, only the coordinator's questions and the facts the coordinator chooses to pass.

Rule: nothing crosses repos except through the coordinator or through a written document. A claim about repo B made while looking at repo A is a hypothesis until B's agent confirms it.

How to delegate — pick the mode your host supports

Check what the host offers before opening the session, and tell the user which mode is in use.

• Persistent subagents (Claude Code, and any host where a subagent can be spawned in the background and sent further messages). Spawn one agent per participating repo, once, named by the repo's slug, and continue the same agent every time that repo is involved. Never spawn a second agent for the same repo in one session. If the host has a registered agent type made from agents/repo-analyst.md (in Claude Code, a copy of the file under ~/.claude/agents/), use it; otherwise use the general subagent and send the file's body verbatim as the first message.
• One-shot subagents (a host that runs a delegated task and returns once). Spawn a fresh agent per repo per round of questions. Each prompt carries the body of agents/repo-analyst.md, the repo's manifest entry, a pointer to the documents that agent's predecessor wrote, and the questions for this round. Batch harder than in persistent mode; each spawn re-reads the entry documents.
• No subagents. Say so in one line, then run the session in this context with the same discipline: read one repo at a time, cite path:line with quoted text, label every claim as verified or assumed, and never carry a fact from one repo into another without checking it there. Keep this mode short; it is exactly the situation the skill exists to avoid.

Whatever the mode, every agent receives the same things: its path, its role and conventions from the manifest, the entry documents to read first, the session question, and the report contract below. Every agent answers in the report contract.

The manifest — personal, outside this skill

~/.config/arch-session/repos.yaml lists the repos the user works across: path, role, who leads it, documentation language, entry documents, conventions, and contract pairs (a producer in one repo, a consumer in another). It holds machine-local paths, so it is never committed and never part of this skill; repos.example.yaml beside this file shows the shape. If the manifest does not exist, offer to create it from the example with the repos the question names. A repo not in the manifest: ask for its path and role, then append it.

Session notes live beside it: ~/.config/arch-session/sessions/YYYY-MM-DD-<slug>.md.

Resolving a repo name. The user names repos loosely ("convex", "the worker", "el hub"). Resolve against the manifest in this order, and never spawn an agent on an unconfirmed match:

1. Exact slug or aliases match → use it; confirmation happens with the participant list.
2. Otherwise match the word against slug, the last segment of path, and role. One candidate → propose it in one line ("convex → soriana-convex?"). Several → list them (at most four) and ask which; do not pick. Two or more repos matching a technology word (several repos on Convex) is the normal case for this rule.
3. None → search the manifest's roots (the folders where the user clones repositories, e.g. ~/Projects) for git repositories whose directory name contains the word: find <root> -maxdepth 3 -type d -name .git, then match on the parent directory's name. Never list a root without a name to match. One hit → propose it with its path ("convex → ~/Projects/acme/convex-api, not in the manifest; add it?"). Several → list at most four with paths and ask. None → ask whether it is a repo elsewhere (then path and role) or a name for one already in the manifest.
4. Once confirmed, append a new repo to the manifest with the path found, and offer to record the word under aliases so it resolves directly next time. One question per unknown name, never a loop.

Maintaining the manifest. The user may edit the YAML directly, or ask in any session — inside or outside an architecture session:

• Add: "add repo X at /path, role Y" → append an entry with slug, path, role, and docs_language; leave lead, entry and conventions empty unless given. The slug is also the agent's name in a session; choose it short and never rename it later.
• Change: "X moved to /new/path", "X's docs are in Spanish", "in X findings go under docs/reviews" → edit only the field named and read the entry back in one line.
• Remove: "drop X" → delete its entry and every contracts item that names its slug; say which contracts went with it.
• Contracts: "X's src/a.ts produces what Y's src/b.ts consumes" → append a contracts item with both sides and a one-line check.

Always confirm the resulting entry in one line. Never edit the manifest silently as a side effect of something else.

Session

1. Open

1. Read the manifest. Read the most recent session note for this topic, if one exists.
2. From the user's question, propose the participating repos — the cwd repo is one of them unless the user says otherwise — and confirm in one line.
3. Delegate one agent per participating repo in the mode the host supports, in parallel where the host allows it.
4. For every contract pair whose two sides are participating, ask both agents for the current shape of their side, diff the answers, and report drift before anything else. Drift between repos is the most common finding and the cheapest to miss.

2. Work

• The user and the coordinator converse. When a question needs a repo's facts, the coordinator sends it to that repo's agent, batching several questions in one message rather than many small ones.
• Agents answer with the report contract. The coordinator relays what matters — the agent's report is not shown to the user — and keeps the relay short.
• When the discussion produces a decision or a finding that belongs to one repo, that repo's agent writes it, in that repo's form: a findings document, an RFC, a roadmap row, whatever the repo already uses. The agent tells the coordinator the path.
• When it belongs to no single repo, the coordinator writes it in the session note.
• A one-off lookup in a non-participating repo uses a read-only one-shot subagent, not a new repo agent.

3. Close

1. Ask each agent to finish its documents and return a ten-line summary: what it wrote (paths), what it verified, what stays open.
2. Write the session note only if something must survive that no repo document holds: a cross-repo decision, an open question between repos, contract drift, or a topic the user will resume. Then it carries participants, decisions with rationale, documents written per repo (paths), drift found, open questions, and which agents to respawn with which pointer. If every outcome landed in a repo document, skip it and say so.
3. Update the manifest if a repo, a contract pair or a convention was learned.
4. Commit nothing, anywhere. The user commits.

Resuming

Agents do not survive the session in any mode. What survives is the session note and the repo documents. To resume, delegate each participant again with a pointer to its repo document and the relevant part of the note.

Report contract — what every agent returns

• Verified and assumed in separate sections. Verified means read in the code; quote it.
• Every claim carries path:line and the quoted text. A pointer without content is not a citation.
• No bare identifiers. An issue number, a rule number, a roadmap row, a commit hash or a constant name always travels with what it says.
• What was written: paths and a one-line purpose each. What was not done, and why.
• A short list of things to verify that the agent could not.
• Length: what the coordinator needs to relay, not what the agent read.

Coordinator discipline

• Delegate reads; keep this context thin. If you find yourself opening a third file in one repo, that repo needs an agent.
• Before asserting anything about a repo, ask its agent. This includes the cwd repo.
• Relay compactly; do not restate agent reports. Convey the finding, the citation, and the decision it affects.
• Expand every reference inline for the user — an id, a rule, a row or a commit always with what it says. Link files with absolute paths when they are outside the workspace.
• Budget: agents only for participating repos; batch questions; close agents with a written summary rather than a long tail of small messages.

What this skill is not

Not an implementation orchestrator: agents draft documents and small consistency edits in their repo; feature work follows the repo's own workflow after the session. Not a workflow script: a conversation with a handful of delegated readers needs nothing heavier than the host's plain subagent mechanism.