ContributingDraft

How a project ties Vyre together

A project (core/projects, owner: projects) is a home folder declared by <home>/.vyre/project.json, plus the threads, people and watchers picked into it. Nothing is automatic: a person picks sessions from the catalogue by hand. Every other part below reads or writes through the project, never around it.

Sessions and threads (owner: sessions)#

A thread belongs to a project either because it ran in one of the project's folders, or because a person picked it (spec 7.2). projects.context {project} builds the brief: what the project is, its people, its other threads by name, its folders, and memory facts, capped near 600 tokens, from that project only. A new Vyre-owned session appends the brief once at start (--append-system-prompt, or the plugin's SessionStart hook when the harness plugin is present). A session can be picked into several projects later (attach-later, cohesion item 19: person-only, preview then one confirm, no Touch ID).

Built: projects.context, the brief, pick/unpick, folder membership. Gap: attach-later's exact tool shape is still being settled between projects and memory-iq (below); vyre resume against real Claude Code (only run against the fake so far).

IQ and memory (owner: memory-iq)#

Memory (branded Vyre Memory) rooms are per-project: a project's picked threads become members of its room (projects.list's picks field feeds this), and memory.facts {project_cwds} answers only from that room, never another project's. Project graphs connect a project's people, facts and threads for retrieval (recall.search with a sessions filter over the project's folders and picks). memory.today is a running line ("Lately in this project") that harness.brief folds into every new session's brief, so IQ's memory of the last few days rides in for free instead of being asked for.

Built: memory.facts, project graphs, memory.today in the brief. Gap: attach-later's graph join when a thread moves projects; host-to-server sync of a project's room (contract agreed with federation, ADR 0008 amendment, federation itself paused).

Watchers (owner: cohesion for the glue, various for the underlying signal)#

A watcher is a name on the project marker (watchers, spec 7.2): someone who should hear about this project's Needs without running a session in it. Cohesion's core/waiting module is the glue: it turns a project's asks, merge failures and stuck teammates into one Needs you feed a watcher's own surfaces poll, keyed off link.pending's created field rather than a TTL guess.

Built: core/waiting (6 tests, on main). Gap: watchers as a first-class field on the project marker and a UI to add/remove one are not built; today only the owning person sees Needs rows.

Teammates (owner: teammates, ADR 0031)#

A project may have named teammates, at most one per role (design, backend, research, ...). Each is a Vyre agent scoped to that project (agent = <role>-<project>), with its own worktree, notes file under <project home>/.vyre/team/<role>/notes.md, and a serial inbox. Any session in the project gets a team.ask tool and is told in its append: send this project's design work to design, keep subagents for one-offs. A shared teammate keeps one inbox and notes file but a separate per-project notes section and a separate sleeping session per project, so one client's work never bleeds into another's.

Built: nothing yet, design only (ADR 0031 complete, app-design's boards approved). Blocked on sessions' slot ledger and usage pause (section 14 of the ADR), which sessions builds next as part of core/team's first migration step. Gap: everything in the ADR's Migration section (9 steps).

Helpers and subagents (owner: sessions)#

Inside a project's concurrency, a subagent slot limits how many Task-tool subagents run at once across every session in that project (teammates' helpers, a person's own Chat or terminal subagents, jobs), bounded because Claude Code runs subagents inside the parent process, so slots cap tokens, not processes. An active-teammate slot is separate and covers a teammate's own running request. Presets (Light/Balanced/Max/Custom) are set per project, capped by a box-wide ceiling, with a fair FIFO queue and an ETA, and pause automatically when the plan's usage window gets close to its limit.

Built: sessions.slots (take/release/status), the per-auth usage pause, purposes teammate (Opus) and helper (faster model). Gap: the settings screen for presets (native-core owns the Settings surface; not yet wired to a live project); the Task-tool hold in canUseTool waiting on a free slot is built for owned sessions but not yet exercised end-to-end with a real teammate, since teammates itself hasn't started building.

Chat (owner: chat / pwa for the surface, sessions for the data)#

The Deck's project picker lists projects from projects.list; a new session started from inside a project's context (context.now, cohesion's glue module) starts in that project: its cwd, its brief, its teammates if any, rather than needing the person to say which project they mean. context.now is also what a teammate's summon box and the Capsule's @role read to guess the right project from where the person already is.

Built: projects.list/projects.context (sessions/projects side); core/context (cohesion, 9 tests). Gap: the Deck's actual project-picker UI and "new session starts in this project" wiring are chat/pwa work, paused during the native-core refocus; not confirmed shipped.

The vault (owner: vault)#

Grants are per agent today (vault_agent_grants), not yet per project. ADR 0031 asks for a project column so a shared teammate's grant only releases for requests from the project it names, and vault-next's own notes list "agent grants per project: project column, check on every use, revoke by project" as a queued Next item. Credentials injected as env vars at a session's start (the pattern this map was asked to point to) has no design doc yet: docs/design/ session-credentials.md does not exist in either the vault or the sessions worktree as of this writing. What does exist: sessions' own Next list carries "threads record origin (the Capsule) for vault's surface mapping" and "Claude sign-in as a vault need (needs.credentials on threads, onboard.claude callable by module:vault)": the shape, not the doc.

Built: agent-level grants, vault usage logging, revoke on agent removal. Gap: the project column on grants (vault-next, queued); the session-credentials design doc; per-project env injection at session start.

Files and Vyre Drive (owner: projects + files, cohesion item 19)#

A project's files live under its home and workspaces today, addressed by folder membership alone. Item 19 (cohesion's cross-team spec, direction-and-owners only, not built) adds a files router so a file can be attached to a project without living in its folder tree, an attach-a-session-to-a-project-later flow shaped like projects.move (person-only: preview, one confirm, no Touch ID; an agent may suggest, never call it), and Vyre Drive as the branded front end (built on Tailscale's Taildrive) with a moved-file event federation credits so the right device sees the change.

Built: the folder-membership case (already part of core/projects). Gap: the router itself, the attach flow's exact tool, the graph join when a thread's project changes (memory-iq to settle), and Vyre Drive's UI, all queued for 0.1.1; no owner has started code.

A day in Harlow Legal#

Harlow Legal is the sample-world firm (home ~/Work/harlow-site) used across the design docs.

1. Morning. Dana opens the Deck. The project picker (chat/pwa) shows Harlow Legal alongside Northwind Bakery. She picks Harlow; context.now records it.
2. A new session starts in context. She starts a session without naming a project; it lands in Harlow automatically (context.now), gets the brief (projects.context: Harlow's people, its other threads, memory facts from Harlow's room only) and memory.today's "Lately in this project" line.
3. She asks for design work. The session's append already says "this project has teammates: design, backend: send their work to them." She types @design make the intake form calmer. That becomes a team.ask request, queued in design's one inbox (teammates, once built), holding an active-teammate slot (sessions) for as long as it runs.
4. Design finishes. Its result posts back to Dana's thread as a teammate-result inbox item, labelled as design's report, not her own words. It touched intake/estate.tsx on branch team/design.
5. The integrator merges. A merge request queues to Harlow's integrator teammate, which merges team/design, runs the project's test command, and fast-forwards main, or raises a "Merge failed" Needs-you row naming the failing test.
6. IQ remembers. The whole exchange becomes part of Harlow's project graph; a fact learned about Harlow ("the client signs with a middle initial") goes through learn.add into memory, never into design's notes file, which stays about how the role works.
7. A watcher hears about it. Alex, who watches Harlow but runs no sessions there, sees the merge and any stuck items in his own Needs feed (cohesion's core/waiting) without opening a Harlow session at all, once watchers are wired to the project marker (gap, above).
8. A file gets attached. Dana drags a signed retainer PDF into the project from outside its folder tree; item 19's attach flow (once built) previews where it lands, she confirms once, and Vyre Drive shows it credited to her device.
9. Grants stay scoped. Design's teammate never sees Northwind's vault credentials: today because grants are per-agent and design's agent only serves Harlow; once vault-next's project column lands, the same holds for a teammate shared across both firms.

Open findings (cohesion's one-product audit, 2026-09-28)#

• Project identity has four unrelated shapes: the marker plus slug (projects), memory's folder-path list (memory-iq), a teammate's agent-name suffix <role>-<project> (teammates), and soon a vault grants column (vault). Nothing declares them the same thing. Fix: one canonical project-id type in core/projects; the others become derived views, not separate truths.
• Watchers have no on-ramp beyond the session owner: the marker field and add/remove call named as a gap above don't exist yet, so a person who isn't the session owner has no way to watch a project at all today.
• No session-credentials doc exists (env injection at a session's start): vault is now writing docs/design/session-credentials.md per the lead; coordinate the shape with them directly rather than duplicating it here.

core/projects has no active teammate right now (its own work doc shows "Doing: Nothing," and no projects agent is in the current roster): these three need an owner assigned before they can be built, flagged to the lead.

Owner and status summary#