Feature deep dive
In Jack, AI coding agents cooperate by reading and writing plain files in your repo — _shared/specs/, _shared/api/, _shared/decisions/, AGENTS.md — the way a human team would. There is no DAG, no manager agent, no proprietary protocol. The "protocol" is your repo: every boundary is diffable, blamable and revertible. Roles are portable agent.md files that work outside Jack too.
Two agents are working on the same project. A backend-dev on Claude Code implements an authentication endpoint and writes the API contract to _shared/api/auth.md. A reviewer on Codex reads the same file, opens the diff, and leaves notes. They never call each other. They never share a runtime. The bridge between them is a markdown file in the repo.
That is file-mediated cooperation. The shared substrate is the repo, not a runtime. You don't need a message bus, you don't need a graph engine, you don't need to learn a new protocol. You need git diff.
_shared/?your-repo/ ├── AGENTS.md # who owns what — read by every agent ├── _shared/ │ ├── specs/ │ │ └── magic-link-login.md # product → backend-dev │ ├── api/ │ │ └── auth.md # backend-dev → frontend-dev, reviewer │ ├── decisions/ │ │ └── 0007-jwt-rotation.md # sticky ADRs │ ├── tasks/ │ │ └── reviewer-0042-auth.md # cross-agent assignments │ └── questions.md # cross-agent open questions ├── apps/ │ ├── api/ # backend-dev's folder │ └── web/ # frontend-dev's folder └── .jack/ └── agents/ # role overrides — committed if you want
specs/ — feature specs, implementation-agnostic. Product writes, dev reads.api/ — interface contracts between agents. The producer writes before landing the code; the consumer reads before adapting.decisions/ — numbered ADRs. Sticky by convention.tasks/ — handoff tasks one agent assigns to another. Lifecycle in-place: status: pending → done.questions.md — append-only file for blocking questions between agents. Resolved by replacing the bullet with the answer.AGENTS.md, and what does it look like?
AGENTS.md at the repo root is the ownership map. One file says who owns what — which agent writes to which folder, which boundaries are read-only, who reviews whose work. Every agent reads it before touching the tree.
The format is plain markdown. A typical file looks like this:
# Agents - **backend-dev** — ownsapps/api/. May readapps/web/,_shared/. - **frontend-dev** — ownsapps/web/. May readapps/api/,_shared/. - **reviewer** — read-only across the repo. Writes notes only inside_shared/tasks/. ## Coordination - API contracts go in_shared/api/. - Decisions go in_shared/decisions/as numbered ADRs. - Open questions go in_shared/questions.md.
Conflicts you would otherwise resolve in PR get caught at write-time. An agent that tries to edit a folder it does not own gets stopped before the file write happens.
Orchestrators define a graph: nodes (agent steps) and edges (transitions, often typed). A scheduler walks the graph. The strength is rigour; the weakness is fragility — when the framework changes its node API, your graph breaks. We watched three orchestrators deprecate inside a year.
File-mediated cooperation is the opposite trade-off. There is no graph, no scheduler, no manager. The shared substrate is the repo. The cost is less rigour at the framework level — but you trade it for handoffs that survive outside the framework. If Jack disappeared tomorrow, the same _shared/ structure and the same agent.md roles would still work in plain Claude Code, plain Codex, plain Gemini.
Yes — that is the design constraint. Roles are plain agent.md files in a format Claude Code, Codex and Gemini already understand. Coordination artefacts are markdown in _shared/. Open the same repo in plain Claude Code or in someone's vim plugin: the roles and shared docs still make sense. Jack adds the UX (workspace board, activity log, permission inbox, handoff triggers), not the dependency.
Yes. The same backend-dev slot can host one Claude session implementing the feature and one Codex session reviewing it, side by side. Different providers, different roles, same workspace, same files. The slot is a position; the session is the runtime. Drag-positioned in the workspace canvas, persisted per-workspace.
AGENTS.md declares ownership at the folder level: each agent has a primary folder and read-only access to others. When an agent tries to write outside its zone, the workspace catches the conflict at write-time rather than at PR review. If you need shared write access (rare), file-level lockfiles or per-section conventions in the file itself are the standard pattern.
Yes. Roles are plain agent.md files — the same format Claude Code, Codex and Gemini already understand. Drop them in your agents folder, in your repo, or in your home dir. Open the same repo in plain Claude Code or Codex CLI without Jack and the roles still apply.
Three locations, in order of precedence: the workspace (.jack/agents/ — committable to your repo if you want), the project root (the repo's existing agents folder), and your home dir (your personal defaults). Jack reads them in that order and lets you see exactly which file is winning.
Yes. Cooperation is mediated by files in your repo, not by a runtime contract. A backend-dev role on Claude Code writing to _shared/api/auth.md is read by a reviewer role on OpenAI Codex without either side knowing about the other. The provider is a per-session choice that does not affect the cooperation surface.
_shared/questions.md is an append-only file for blocking questions between agents (one bullet per question, [author → recipient] format). _shared/decisions/ holds ADRs (architectural decision records) — sticky, supersede a decision with a new file rather than editing the old. Both are version-controlled, both are diffable, both survive outside Jack.
_shared/decisions/ as numbered ADR files (e.g. 0007-jwt-rotation.md). Lead with the decision, then context, alternatives, consequences. Sticky by convention: if a decision changes, supersede with a new ADR. Every agent reads them before touching the relevant code.
_shared/