| 1 | # The workspace: chat, agents, docs and code in one place |
| 2 | |
| 3 | A g1t workspace is where a team and its agents talk, write things down and |
| 4 | ship code. Four modes share one identity, one inbox, one search, one audit |
| 5 | log and one bill: |
| 6 | |
| 7 | | Mode | What it is | |
| 8 | | --- | --- | |
| 9 | | **Chat** | Channels, threads and direct messages. People and agents are members alike. | |
| 10 | | **Agents** | The workspace's agents: who they are, what they are doing right now, what they cost. | |
| 11 | | **Docs** | The workspace's written knowledge: specs, runbooks, decisions, onboarding. Agents read it and keep it current. | |
| 12 | | **Code** | Projects, issues, pull requests, checks, deploys. Exactly as today. | |
| 13 | |
| 14 | Home and Inbox sit above the modes and span all of them. |
| 15 | |
| 16 | This plan supersedes `docs/CHANNELS.md`. It keeps that document's data |
| 17 | shapes for channels and messages. It changes how agents run, adds |
| 18 | coordination between agents, and adds Docs. |
| 19 | |
| 20 | ## The bet |
| 21 | |
| 22 | Every team already runs three tools that don't know about each other: |
| 23 | |
| 24 | - a chat app; |
| 25 | - a wiki; |
| 26 | - a forge. |
| 27 | |
| 28 | Agents are bolted onto each one separately. A bot in the chat app can talk |
| 29 | but can't safely touch code. A coding agent can touch code but forgets the |
| 30 | conversation that asked for it. The wiki goes stale the week it is written. |
| 31 | |
| 32 | g1t puts the three in one system of record, and agents are members of it: |
| 33 | |
| 34 | - **Agents are teammates, not features.** Each has a name, a face, a job, a |
| 35 | personality, a budget and a desk. You DM it, invite it to a channel, add |
| 36 | it to a doc's owners, assign it an issue. |
| 37 | - **Conversation starts work; the forge records it.** A request in chat |
| 38 | becomes a task. Code changes become pull requests. Knowledge becomes doc |
| 39 | edits. Everything links back to the thread that asked for it. |
| 40 | - **Agents work like real sessions.** An agent works the way a Claude Code |
| 41 | session does: it reads, edits, runs things, keeps its context across |
| 42 | days, can be steered mid-flight, and can hold several jobs at once. |
| 43 | - **Agents coordinate in the open.** Before an agent touches something, it |
| 44 | claims it. When two agents' work would collide, they negotiate in a |
| 45 | thread a person can read, not in a hidden log. |
| 46 | - **The rails are the product.** Budgets, scopes, approvals and audit are |
| 47 | decided by policy, not by the agent's judgment, and they are visible on |
| 48 | every card. |
| 49 | |
| 50 | ## Agents |
| 51 | |
| 52 | ### What an agent is |
| 53 | |
| 54 | An agent is a member of a workspace, of kind `agent`. It appears everywhere |
| 55 | a person does: member lists, mentions, assignees, reviewers, doc authors, |
| 56 | the audit log. |
| 57 | |
| 58 | `@g1t` stays what it is today: the platform's own agent, reachable from any |
| 59 | workspace with no setup. A workspace's own agents are created by its |
| 60 | members and belong only to that workspace. g1t's built-in roles (planner, |
| 61 | implementer, reviewer, triage, documenter) ship as templates you can adopt, |
| 62 | rename and change. They are not hidden system actors. |
| 63 | |
| 64 | ### The definition |
| 65 | |
| 66 | An agent is a versioned record in the workspace. It can also be mirrored |
| 67 | to a repository as `.g1t/agents/<handle>.md`: front matter for settings, |
| 68 | the body for its job. Edits from either side create a new version, and |
| 69 | every run records which version it ran. |
| 70 | |
| 71 | | Field | What it controls | |
| 72 | | --- | --- | |
| 73 | | Identity | Display name, `@handle`, avatar, a one-line role ("Release manager for g1t"). | |
| 74 | | Job | Instructions: what it is responsible for, how it works, what good looks like. | |
| 75 | | Personality | Voice only: tone, verbosity, formality, emoji, language, how it asks questions. Presets (Crisp, Friendly, Socratic, Terse operator) plus free text. Personality never changes policy. | |
| 76 | | Models | Routed per step by need, never picked when assigning work. See [Model routing](#model-routing). The definition only sets limits on the routing: a floor, a ceiling, and which providers it may use. | |
| 77 | | Budget | A monthly cap, a per-task cap, and an optional daily cap. See [Budgets](#budgets). | |
| 78 | | Scopes | Which projects, channels and doc spaces it can read and which it can write. Default: read what it is invited to, write nothing. | |
| 79 | | Autonomy | What it may do alone and what needs a person. For example: open pull requests (alone); merge (needs approval); deploy to production (needs approval); publish a doc page (alone in spaces it owns, a suggestion elsewhere). Rulesets and branch protection still apply on top. | |
| 80 | | Capacity | How many tasks it works at once (default 3). Beyond that, tasks queue on its desk. | |
| 81 | | Triggers | What wakes it without a mention: a schedule, any g1t event, a message in a channel it watches, a webhook, a doc page going stale. | |
| 82 | | Skills | Saved procedures it can repeat ("cut a release", "write the weekly update"), made by walking it through once. | |
| 83 | | Tools | g1t's MCP tools allowed by its scopes, plus MCP servers the workspace connected. | |
| 84 | | Memory | What it has learned. Readable and editable on its profile, with sources. | |
| 85 | |
| 86 | ### Like a colleague |
| 87 | |
| 88 | Agents are treated like employees, not like settings: |
| 89 | |
| 90 | - **They belong to teams.** An agent can be added to any team, the same as |
| 91 | a person. It then: |
| 92 | - gets that team's channels and mentions; |
| 93 | - can be requested as a reviewer through the team; |
| 94 | - shows up on the team's page. |
| 95 | - **They post updates on their own.** |
| 96 | - When a task changes state (started, opened a pull request, blocked, |
| 97 | done), the agent says so in the thread that asked for it. |
| 98 | - A daily or weekly summary, if you turn it on, goes to the channels it |
| 99 | works for: what it shipped, what it is waiting on, and what it spent. |
| 100 | - Everyone always knows what each agent is doing without asking. |
| 101 | - **They have a manager.** Every agent has an owner: the person who |
| 102 | approves its budget and gets its escalations. |
| 103 | - **Chat comes first, and issues still work.** You can give an agent work |
| 104 | just by talking to it. Creating an issue and assigning it to the agent |
| 105 | still works the same way, for planned work and for anyone who prefers |
| 106 | it. |
| 107 | |
| 108 | ### Creating one |
| 109 | |
| 110 | Agents can be created in three ways: |
| 111 | |
| 112 | - **In chat.** Write something like "make a release manager called Ship that |
| 113 | cuts g1t releases on Tuesdays and asks me before tagging". g1t answers with |
| 114 | a draft card holding every field. You edit the card and confirm. |
| 115 | - **From a template**, on the Agents page. |
| 116 | - **By committing** `.g1t/agents/ship.md`. g1t offers to adopt it into the |
| 117 | workspace. |
| 118 | |
| 119 | Once saved, the agent: |
| 120 | |
| 121 | - introduces itself in the channels it was added to; |
| 122 | - opens a DM with the person who created it; |
| 123 | - shows up as idle on the Agents page. |
| 124 | |
| 125 | ### Agents mode |
| 126 | |
| 127 | The sidebar lists: |
| 128 | |
| 129 | - agents you talk to; |
| 130 | - agents working right now, each showing its live tasks; |
| 131 | - agents waiting on you; |
| 132 | - all agents. |
| 133 | |
| 134 | An agent's page has five tabs: |
| 135 | |
| 136 | | Tab | What it shows | |
| 137 | | --- | --- | |
| 138 | | **Desk** | Every task it holds, as live cards (like Claude Code tabs): steps, files touched, cost so far, what it is waiting on. Open one to read the full transcript, steer it, pause it or take it over. | |
| 139 | | **Profile** | The definition, with version history. | |
| 140 | | **Memory** | What it remembers, with the source of each fact. Each fact can be pinned, edited or forgotten. | |
| 141 | | **Spend** | Spend this month against its budget, by task and by model. | |
| 142 | | **Activity** | Everything it did, from the audit log. | |
| 143 | |
| 144 | ## How agents run |
| 145 | |
| 146 | ### Two kinds of turn |
| 147 | |
| 148 | Most messages to an agent don't need a computer. A reply should take a |
| 149 | second and cost a fraction of a cent. Spinning up a sandbox for every |
| 150 | message would make chat slow and expensive. |
| 151 | |
| 152 | - **Replies** run in a Worker with no sandbox. The model gets the thread, |
| 153 | the agent's definition and memory, and g1t's MCP tools within the agent's |
| 154 | scopes: |
| 155 | - read code, issues, pull requests, checks, deploys and docs; |
| 156 | - search context; |
| 157 | - post a message; |
| 158 | - open a task; |
| 159 | - claim something; |
| 160 | - ask another agent. |
| 161 | |
| 162 | Questions, summaries, triage, planning and doc reads are all replies. |
| 163 | - **Sessions** run in a sandbox, exactly as today's runs do. They are used |
| 164 | for anything that edits a repository, runs code or tests, or works for |
| 165 | longer than a reply. A reply escalates to a session by opening a task. |
| 166 | |
| 167 | ### Sessions persist |
| 168 | |
| 169 | Today each run is a fresh headless `claude --print`. Sessions become |
| 170 | resumable: |
| 171 | |
| 172 | - Each task has a session: the Claude Code session id, its transcript |
| 173 | (stored in R2), the branch it works on, and its claims. |
| 174 | - A sandbox lives only while the session is doing something. When it goes |
| 175 | idle the sandbox stops. The transcript is saved, and the work is pushed |
| 176 | to the task's branch. Idle agents cost nothing. |
| 177 | - The next message to that task resumes the session in a new sandbox: the |
| 178 | saved transcript is restored and the run uses `claude --resume <id>`. It |
| 179 | could be a reply in its thread, a review comment, a failed check or an |
| 180 | answer from another agent. The agent picks up with full context, as if |
| 181 | it never left. |
| 182 | - Steering keeps today's after-tool-call hook (`crates/runner/src/steer.rs`). |
| 183 | It now reads from the task's thread, not only from the pull request. |
| 184 | - A person can open any session and see what Claude Code would show: |
| 185 | - the transcript; |
| 186 | - the diff so far; |
| 187 | - the terminal output. |
| 188 | |
| 189 | From there they can send a message, pause it, or take it over. Taking |
| 190 | over hands them the branch and the transcript. |
| 191 | |
| 192 | ### The desk |
| 193 | |
| 194 | Each agent has one desk: a Durable Object keyed by agent id. Everything |
| 195 | addressed to the agent arrives at the desk: |
| 196 | |
| 197 | - mentions; |
| 198 | - DMs; |
| 199 | - assignments; |
| 200 | - triggers; |
| 201 | - messages from other agents. |
| 202 | |
| 203 | The desk decides what each one is: |
| 204 | |
| 205 | 1. **A question or chat** goes to a reply. |
| 206 | 2. **About a task it already holds** (same thread, same pull request, or |
| 207 | it says so) steers that session. |
| 208 | 3. **New work** opens a task. If the desk is at capacity, the task queues |
| 209 | with its position shown to whoever asked. |
| 210 | |
| 211 | The desk also enforces the agent's capacity, schedules its triggers, and |
| 212 | holds the agent's presence (idle, working, waiting on you, out of budget). |
| 213 | Workspace-wide concurrency stays the plan's entitlement |
| 214 | (`maxConcurrentAgents`), checked as today. |
| 215 | |
| 216 | ### Tasks |
| 217 | |
| 218 | A task is one job an agent took on. It records: |
| 219 | |
| 220 | - who asked, and in which thread; |
| 221 | - the goal, and what done means; |
| 222 | - status: `queued`, `working`, `waiting`, `done` or `cancelled`; |
| 223 | - its budget and spend; |
| 224 | - its session; |
| 225 | - its claims; |
| 226 | - what it produced: issues, pull requests, deploys, doc pages, answers. |
| 227 | |
| 228 | Issues and pull requests stay as they are. A task that touches code ends in |
| 229 | pull requests. A task that is planned work opens issues through the |
| 230 | planner. A task appears in the issue list only if it produced an issue. |
| 231 | Each project gets a Tasks tab for the rest. |
| 232 | |
| 233 | Assigning an issue to an agent creates a task for it, so every existing |
| 234 | entry point keeps working: |
| 235 | |
| 236 | - assignment; |
| 237 | - mentions in pull requests; |
| 238 | - label rules; |
| 239 | - the planner. |
| 240 | |
| 241 | ## Coordination |
| 242 | |
| 243 | Several agents working at once on the same codebase, docs and deploys will |
| 244 | collide unless the system prevents it. Today's protection is a list of |
| 245 | in-flight pull requests in the prompt (`describeInFlight`). It becomes a |
| 246 | real protocol. |
| 247 | |
| 248 | ### Claims |
| 249 | |
| 250 | Before acting, a task claims what it will touch. Claims are held by a |
| 251 | coordinator: one Durable Object per workspace, a single writer so that |
| 252 | grants are atomic. They are shown on the task card. |
| 253 | |
| 254 | | Claim | Kind | Example | |
| 255 | | --- | --- | --- | |
| 256 | | An issue | Exclusive | Only one task works #412. | |
| 257 | | A branch | Exclusive | A task's own branch, always. | |
| 258 | | An environment | Exclusive | Production deploys of `flagon-io/g1t`. | |
| 259 | | A doc section | Exclusive while editing | "Runbook › Rollback". | |
| 260 | | Paths in a repository | Shared, with overlap detection | `crates/git/**`. Declared from the plan, then widened automatically to the files the diff actually touches. | |
| 261 | |
| 262 | Rules: |
| 263 | |
| 264 | - **Exclusive claims** that are already held return the holder. The task |
| 265 | either waits (it subscribes and resumes when the claim is released) or |
| 266 | asks the holder. |
| 267 | - **Overlapping path claims** don't block. Both tasks are told who else is |
| 268 | in those paths, and the later one must say how it will avoid the |
| 269 | conflict. It can sequence after the other, split the work differently, or |
| 270 | agree a boundary with the other agent in a thread. The merge queue stays |
| 271 | the final referee. |
| 272 | - **Claims are leases.** They expire if the session dies, and are renewed |
| 273 | while the task is alive. A person can break any claim. |
| 274 | - **People claim too.** Assigning yourself an issue or opening a pull |
| 275 | request counts, so agents route around humans as well as each other. |
| 276 | |
| 277 | ### Talking to each other |
| 278 | |
| 279 | Agents message each other through the existing `agent_messages` exchange |
| 280 | (message, question, handoff). It is widened from pull request numbers to |
| 281 | task addresses, and it always appears in a visible thread: |
| 282 | |
| 283 | - the requesting task's thread when there is one; |
| 284 | - otherwise the project's channel; |
| 285 | - otherwise a workspace `#agents` channel. |
| 286 | |
| 287 | Agents also get two new kinds: |
| 288 | |
| 289 | - **review**: "look at my change before I ask a human"; |
| 290 | - **claim request**: "can I have the deploy lock after you?". |
| 291 | |
| 292 | Safety rails: |
| 293 | |
| 294 | - **Hop limit.** An agent-to-agent chain started by one human request |
| 295 | stops after a set number of hops (default 6) and asks a person. |
| 296 | - **Addressed only.** Agents answer other agents only when addressed or |
| 297 | mentioned, never because a message appeared in a channel they watch. |
| 298 | - **Rate limit.** An agent posts at most a set number of messages per |
| 299 | thread per minute without a person in the loop. |
| 300 | - **Shared budget.** Work done for another agent's task is charged to the |
| 301 | task that asked for it, so a chain can't escape its budget. |
| 302 | |
| 303 | ### A lead, when you want one |
| 304 | |
| 305 | Any agent can be made the lead of a project or channel. A lead receives |
| 306 | new work there first, splits it into tasks, hands them to the right agents, |
| 307 | and reports progress in one place. The built-in planner is a lead template. |
| 308 | Without a lead, the agent that was asked owns the work and hands off |
| 309 | pieces itself. |
| 310 | |
| 311 | ## Docs |
| 312 | |
| 313 | ### What it is |
| 314 | |
| 315 | Docs is the workspace's knowledge base: |
| 316 | |
| 317 | - **spaces** (one per team or project, plus a workspace space); |
| 318 | - holding a tree of **pages**; |
| 319 | - edited together in real time, with mentions of people, agents, issues, |
| 320 | pull requests, channels and other pages. |
| 321 | |
| 322 | Every page has history, comments, backlinks and owners. |
| 323 | |
| 324 | ### Agents and docs |
| 325 | |
| 326 | This is where Docs earns its place: |
| 327 | |
| 328 | - **Agents read it.** Pages are indexed by `services/context`, so the |
| 329 | knowledge reaches every reply, session and plan. A space can be pinned to |
| 330 | an agent as required reading. |
| 331 | - **Agents write it.** An agent with write access to a space edits pages |
| 332 | directly. Without it, the edit becomes a **suggestion**: tracked changes |
| 333 | a person accepts or rejects inline, the same review loop as a pull |
| 334 | request. Every edit is attributed and in the page history. |
| 335 | - **Pages know what they describe.** A page can cite code: paths, symbols, |
| 336 | endpoints, environment variables. When a merged pull request changes |
| 337 | something a page cites, the page is marked possibly stale and its owners |
| 338 | are notified. If an agent owns the page, it drafts the update. |
| 339 | - **Conversations become pages.** "Write this up" in a thread makes a page |
| 340 | from the thread, linked both ways. Decisions made in chat get a home. |
| 341 | - **A documenter agent** (a template) keeps a space current. It updates |
| 342 | pages after merges, writes release notes and the weekly summary, and |
| 343 | turns incident threads into postmortems. |
| 344 | |
| 345 | ### Docs and repository docs |
| 346 | |
| 347 | Repository docs (README, `docs/`) stay in the repository and change through |
| 348 | pull requests. Docs mode can show a project's `docs/` folder as a read-only |
| 349 | space next to the workspace's own spaces. One search and one tree cover |
| 350 | both. Editing a repository page from Docs opens a pull request. |
| 351 | |
| 352 | ### How it is stored |
| 353 | |
| 354 | - **Live editing.** Each open page is a Durable Object holding a CRDT |
| 355 | (Yjs), reached over a WebSocket. |
| 356 | - **Durable storage.** On idle, the page is saved as Markdown. Each space |
| 357 | is a git repository in g1t's own git storage, so: |
| 358 | - history, blame and export come free; |
| 359 | - agents can work on a space with the same tools they use on code; |
| 360 | - self-hosted installs keep everything in git. |
| 361 | - **Metadata** lives in `services/docs`' D1: tree, owners, permissions, |
| 362 | citations, staleness, comments. |
| 363 | |
| 364 | ## Chat |
| 365 | |
| 366 | Channels, direct messages, threads, reactions, read state and the |
| 367 | scaled sidebar follow `docs/CHANNELS.md` (data model in its "Data" |
| 368 | section). The additions: |
| 369 | |
| 370 | - **Cards.** Everything that happens is a card in the right channels, and |
| 371 | its actions work in place: |
| 372 | - tasks, with live status; |
| 373 | - pull requests, checks, deploys and incidents; |
| 374 | - doc changes; |
| 375 | - approvals; |
| 376 | - claims, for example "@ship is waiting on the deploy lock held by |
| 377 | @oncall". |
| 378 | - **One timeline.** Replying in a thread about an issue or pull request is |
| 379 | commenting on it, so the conversation and the record stay one thing. |
| 380 | - **Channels link to projects and doc spaces.** A linked channel gets those |
| 381 | events, and Code and Docs show it in the side dock (as in the mockup). |
| 382 | - **Search** covers messages, pages and tasks the viewer can see. This |
| 383 | joins the site-wide search, separate from context search. |
| 384 | |
| 385 | ## Budgets |
| 386 | |
| 387 | Spend is limited at four levels. Each level is checked before work starts |
| 388 | (reserve) and enforced while it runs (settle). These are the same |
| 389 | mechanisms as today (`docs/SPEND-GUARDRAILS.md`), widened: |
| 390 | |
| 391 | 1. **Workspace.** The owner's spend limit and the AI credit wallet. A hard |
| 392 | stop. |
| 393 | 2. **Agent.** Monthly, and optionally daily, caps on the agent definition. |
| 394 | At 80% the agent tells the channel that pays for it. At 100% it stops |
| 395 | taking new tasks and finishes nothing past its per-task reserve. |
| 396 | 3. **Task.** A cap per task, defaulting from the agent. The card shows |
| 397 | spend against the cap live. Going over is an approval card, not a |
| 398 | silent overrun. |
| 399 | 4. **Session.** Today's per-run caps and guardrails: minutes, tokens, |
| 400 | network. |
| 401 | |
| 402 | Replies are metered as Agent tokens at the same rates as runs. An idle |
| 403 | agent costs nothing. Usage and the agent's Spend tab break cost down by |
| 404 | agent, task and model. |
| 405 | |
| 406 | ## The whole company |
| 407 | |
| 408 | Chat is for everyone in the company: support, sales, finance, design and |
| 409 | leadership as well as engineers. Most of them never change code, and |
| 410 | agents must not become a way around that. They still get the full value: |
| 411 | they can ask questions, look things up, hand over customer data, and have |
| 412 | their requests reach the right team. |
| 413 | |
| 414 | ### Members without Code |
| 415 | |
| 416 | Every workspace member gets Chat, Docs, Agents and the Inbox. Code is a |
| 417 | per-member switch: **Code access**, on by default, which owners turn off |
| 418 | for people who don't work on code. |
| 419 | |
| 420 | A member without Code access: |
| 421 | |
| 422 | - **Sees a rail without Code.** Home shows their channels, DMs, docs and |
| 423 | inbox, not projects. |
| 424 | - **Has no repository access at all.** No repository, issue, pull request, |
| 425 | check or deploy page is open to them. The workspace's base permission and |
| 426 | team repository grants don't apply. Turning Code access back on restores |
| 427 | what their teams and roles give them. |
| 428 | - **Still sees work reach them in chat.** Cards about issues, pull requests |
| 429 | and deploys appear in the channels they're in as summaries: title, state |
| 430 | and who is on it. Opening one asks for Code access instead of showing the |
| 431 | page. |
| 432 | - **Can ask agents anything about the product.** Agents explain how things |
| 433 | work and what changed, but never show them source code. Owners can tighten |
| 434 | this so agents only answer from Docs. |
| 435 | - **Doesn't count against anything.** There are no seats, so adding the |
| 436 | whole company costs nothing until they use agents. |
| 437 | |
| 438 | This is stored as `code_access` on the membership (identity service). Every |
| 439 | service that authorizes a repository checks it, and the site hides Code |
| 440 | when it is off. |
| 441 | |
| 442 | ### The asker's access caps the agent |
| 443 | |
| 444 | An agent never does more for someone than that person could do themselves. |
| 445 | |
| 446 | - **What it does.** An agent acts with the *intersection* of its own scopes |
| 447 | and the access of the person asking. |
| 448 | - Someone without write access to a repository can't get an agent to |
| 449 | change it, whatever the agent's own scopes are. |
| 450 | - A task always records who asked. Approvals go to people who hold the |
| 451 | access the task needs. |
| 452 | - **What it says.** An agent answers only with what everyone who can read |
| 453 | the reply can see. |
| 454 | - In a DM, that is the asker's access. |
| 455 | - In a channel, it is the access of the channel's audience: everyone in |
| 456 | the channel, or the whole workspace for a public channel. |
| 457 | - A private repository, doc space or channel never leaks into a place |
| 458 | with a wider audience. When it can't answer here, the agent says so |
| 459 | and offers to answer in a DM. |
| 460 | - **No new roles to manage.** This falls out of the access people already |
| 461 | have: |
| 462 | - workspace roles; |
| 463 | - repository roles; |
| 464 | - team membership; |
| 465 | - doc space permissions. |
| 466 | |
| 467 | A support lead with read access to the product repository can ask "how |
| 468 | does proration work?" and get an answer grounded in the code. They can't |
| 469 | get it changed. |
| 470 | |
| 471 | ### Requests become intake, not changes |
| 472 | |
| 473 | When someone who can't change the code asks for a change, the agent |
| 474 | doesn't refuse and doesn't do it. It turns the request into intake: |
| 475 | |
| 476 | 1. It drafts a request: a bug or a feature request, in the asker's words, |
| 477 | with the agent's understanding and links to the conversation. |
| 478 | 2. It routes the request to the team that owns the area. The owner comes |
| 479 | from code owners, the project's team, or the workspace's intake |
| 480 | settings. |
| 481 | 3. It tells the asker where the request went. |
| 482 | 4. It tells them again when the request is triaged, scheduled and shipped: |
| 483 | "the export fix you asked for is live". |
| 484 | |
| 485 | People with write access can still say "just do it" and get a task. |
| 486 | |
| 487 | ### Agents that listen |
| 488 | |
| 489 | A channel can let agents listen. This is off by default and shown in the |
| 490 | channel header. A listening agent watches for: |
| 491 | |
| 492 | - complaints; |
| 493 | - bug reports; |
| 494 | - feature requests; |
| 495 | - questions nobody answered. |
| 496 | |
| 497 | It doesn't reply to every message. It groups related messages ("three |
| 498 | customers hit the CSV export timeout this week") and files or updates one |
| 499 | intake item linked to every source message. It answers only when it's |
| 500 | asked, or when it can close a loop: "this was fixed yesterday in #418". |
| 501 | |
| 502 | Typical setups: |
| 503 | |
| 504 | - a triage agent listening in `#support`, `#sales` and `#feedback`; |
| 505 | - an on-call agent in `#incidents`; |
| 506 | - a docs agent that notices the same question asked twice and writes the |
| 507 | page. |
| 508 | |
| 509 | ### Files and customer data |
| 510 | |
| 511 | People upload whatever their work needs: spreadsheets, contracts, exports, |
| 512 | screenshots. Agents work with these, under rules the workspace sets: |
| 513 | |
| 514 | - **Classification.** Every file has a level: |
| 515 | - Public; |
| 516 | - Internal (the default); |
| 517 | - Confidential; |
| 518 | - Customer data. |
| 519 | |
| 520 | The uploader sets the level. An agent may suggest raising it when it |
| 521 | sees personal data. |
| 522 | - **Which models may see it.** Each level lists the providers allowed to |
| 523 | process it. For example, customer data may go only to the workspace's |
| 524 | own provider with zero retention. An agent that may not send a file to |
| 525 | any allowed model says so; it never quietly skips the file. |
| 526 | - **Memory.** Agents never write customer data into their memory, and |
| 527 | never put it into issues, pull requests or channels with a wider |
| 528 | audience than the file's. |
| 529 | - **Retention.** Each level has a retention period, and deletions are |
| 530 | final. |
| 531 | - **Audit.** Every time an agent reads a Confidential or customer-data |
| 532 | file, the audit log records it with the task and the person who asked. |
| 533 | |
| 534 | ### Not just code |
| 535 | |
| 536 | Agents work across the company's tools, not only the repository, through |
| 537 | MCP connectors the workspace adds (a CRM, a help desk, a data warehouse). |
| 538 | The same rules apply: |
| 539 | |
| 540 | - the asker's access caps the agent; |
| 541 | - the channel's audience caps what it says; |
| 542 | - classification decides which models see the data. |
| 543 | |
| 544 | ## Working from another chat app |
| 545 | |
| 546 | Some companies will keep their existing chat app for the whole |
| 547 | organization. Often only the engineers use g1t, or nobody does at first. |
| 548 | That has to be a good experience, not a punishment. The agents are the same |
| 549 | agents wherever you talk to them, and the work lands in the same place. |
| 550 | g1t earns the move over time by being better, never by making the |
| 551 | integration worse. |
| 552 | |
| 553 | User-facing text calls this "the chat app integration" and, on its |
| 554 | integration page, by the app's own name. Marketing never compares the two. |
| 555 | |
| 556 | ### One agent, many places |
| 557 | |
| 558 | Where a conversation happens is just a *surface*. Each surface has an |
| 559 | adapter in `services/integrations`: |
| 560 | |
| 561 | - g1t Chat; |
| 562 | - a connected chat app; |
| 563 | - later, email. |
| 564 | |
| 565 | Everything else is shared, whichever surface a message arrived on: |
| 566 | |
| 567 | - the agent; |
| 568 | - its memory; |
| 569 | - its tasks; |
| 570 | - its budget; |
| 571 | - its claims; |
| 572 | - the audit log. |
| 573 | |
| 574 | - **Every external conversation has a home in g1t.** When an agent is used |
| 575 | in an external channel or DM, g1t keeps a linked conversation: the |
| 576 | messages the agent was given or posted, with permalinks back. Tasks, |
| 577 | issues and pull requests link to it like any thread. "Why was this |
| 578 | changed?" leads back to the external thread. The agent's memory learns |
| 579 | from it the same way. |
| 580 | - **A task started in one place can be followed from either.** A task |
| 581 | started in the external app posts its updates there. Its live card, |
| 582 | session and diff are one click away in g1t. Steering works from both: |
| 583 | - a reply in the external thread; |
| 584 | - a message on the task in g1t. |
| 585 | - **Approvals settle everywhere.** An approval is a button in the external |
| 586 | message, a card in g1t and an item in the inbox. Acting in any one |
| 587 | settles all three. |
| 588 | |
| 589 | ### The app in their chat |
| 590 | |
| 591 | The workspace installs one app into its external chat workspace from |
| 592 | Integrations. The app's name is g1t. |
| 593 | |
| 594 | - **Each agent speaks as itself.** Messages are posted with the agent's |
| 595 | name and avatar. |
| 596 | - Mention the app and name the agent: "@g1t ask @reviewer to look at |
| 597 | #418". |
| 598 | - Or use a shortcut per agent: `/g1t reviewer …`. |
| 599 | - In the app's DM, a picker chooses which agent you are talking to. |
| 600 | - **Invite it to a channel** to let agents answer there when mentioned. |
| 601 | Turn on listening to let a triage agent group feedback, the same as in |
| 602 | g1t (see [Agents that listen](#agents-that-listen)). |
| 603 | - **Cards render natively** in the external app: tasks, pull requests, |
| 604 | checks, deploys and approvals, with buttons. "Open in g1t" goes to the |
| 605 | full view. |
| 606 | - **Bridged channels** (optional). Link an external channel to a g1t |
| 607 | channel and the two mirror each other: messages, threads, edits and |
| 608 | reactions. Engineers stay in g1t while the rest of the company stays |
| 609 | where it is, in one conversation. Each message shows where it came from. |
| 610 | |
| 611 | ### Who is asking |
| 612 | |
| 613 | The rules from [The whole company](#the-whole-company) apply unchanged. |
| 614 | They depend on knowing who the person is. |
| 615 | |
| 616 | - **Linked people.** The first time someone talks to an agent from the |
| 617 | external app, the agent asks them to link their account: one click to |
| 618 | sign in to g1t. From then on they act with their own g1t access. |
| 619 | - **Unlinked people** are treated as members without Code access: |
| 620 | - they can ask questions and get answers from Docs; |
| 621 | - their change requests become intake; |
| 622 | - they never get code changed, or see code an agent wouldn't show |
| 623 | them. |
| 624 | |
| 625 | Owners can require linking before an agent answers at all. |
| 626 | - **Audience.** In an external channel, the audience is everyone in that |
| 627 | channel. Agents answer there with only what all of its linked members |
| 628 | can see, and treat unlinked members as having no Code access. Private |
| 629 | g1t content stays out of external channels unless an owner allows it |
| 630 | for that channel. |
| 631 | - **Data.** Messages from the external app are stored only as part of |
| 632 | linked conversations, under the workspace's retention and classification |
| 633 | rules. Files shared there follow the same model-routing rules as |
| 634 | uploads. |
| 635 | |
| 636 | ### Why people move over anyway |
| 637 | |
| 638 | The external app gets the agents, the answers and the approvals. g1t |
| 639 | keeps what only it can do: |
| 640 | |
| 641 | - live task cards with sessions and diffs you can steer; |
| 642 | - the one timeline where replying is commenting on a pull request; |
| 643 | - Docs side by side with the conversation; |
| 644 | - presence that shows what every agent is doing; |
| 645 | - no limit on history or seats. |
| 646 | |
| 647 | These are pointed to in context with "Open in g1t", never with nags. |
| 648 | |
| 649 | ### Build |
| 650 | |
| 651 | The adapter interface comes with the agents service now. Replies read a |
| 652 | conversation and post through a surface port, so the external app is one |
| 653 | more adapter later, not a rewrite. |
| 654 | |
| 655 | The app itself ships after Chat and tasks, in this order: |
| 656 | |
| 657 | 1. install; |
| 658 | 2. agents speaking as themselves; |
| 659 | 3. account linking; |
| 660 | 4. linked conversations; |
| 661 | 5. approvals; |
| 662 | 6. bridged channels; |
| 663 | 7. listening. |
| 664 | |
| 665 | ## Model routing |
| 666 | |
| 667 | Nobody picks a model to get work done. g1t routes each step of an agent's |
| 668 | work to the tier it needs, using today's `AGENT_ROUTING`: |
| 669 | |
| 670 | | Step | Tier | |
| 671 | | --- | --- | |
| 672 | | Chat replies, triage | small | |
| 673 | | Implementation, routine review | large | |
| 674 | | Planning, hard reviews, retries after a failure | frontier | |
| 675 | |
| 676 | As today, routing steps up after failures and steps back down when the |
| 677 | cheaper tier worked. |
| 678 | |
| 679 | The agent definition limits the routing; it does not replace it: |
| 680 | |
| 681 | - **Floor.** For example, "never below large" for a reviewer that must be |
| 682 | careful. |
| 683 | - **Ceiling.** For example, "never frontier" for a cheap triage agent. |
| 684 | - **Providers.** Which models it may use: g1t's hosted models, the |
| 685 | workspace's own providers from Integrations (Anthropic, OpenAI, |
| 686 | compatible endpoints), or both. When the workspace has its own providers, |
| 687 | each tier maps to a provider and model in the workspace's routing |
| 688 | settings. An agent restricted to the workspace's own keys never touches |
| 689 | g1t's. |
| 690 | - **Pinned model.** An advanced escape hatch for own endpoints. Not shown |
| 691 | by default. |
| 692 | |
| 693 | Every step records the model that ran. It is shown in the session and on |
| 694 | the agent's Spend tab, so routing is visible without anyone having to |
| 695 | choose. |
| 696 | |
| 697 | ## Pricing |
| 698 | |
| 699 | This follows the standing pricing rule: measured cost plus a modest, |
| 700 | uniform overhead, and no seats. |
| 701 | |
| 702 | | What | How it is charged | |
| 703 | | --- | --- | |
| 704 | | People chatting: messages, threads, reactions, read state, live delivery | Included on every plan, the free plan too. It costs very little (a message is a few row writes and one Durable Object request; idle sockets hibernate). History is never cut off. It is still metered raw, so the daily reconciliation sees the real cost. | |
| 705 | | Docs: pages, editing, history | Included on every plan, like chat. | |
| 706 | | An agent replying in chat | Agent tokens from the AI credit wallet: provider price plus the g1t agent rate. Charged to that agent's budget and, inside a task, to the task. | |
| 707 | | An agent's sessions | Agent tokens as above, plus sandbox time at cost +20%. | |
| 708 | | An agent's model calls on the workspace's own provider | The provider bills the workspace directly. g1t charges the agent rate only. | |
| 709 | | Files in chat and docs | The storage meter (served from g1tusercontent.com), at cost +20%. | |
| 710 | | Calls and huddles (later) | Media relay at cost +20%. | |
| 711 | | Idle agents | Nothing. | |
| 712 | |
| 713 | Free workspaces get chat and docs with protective caps: a file storage |
| 714 | cap, and no agents until the workspace buys AI credit. That keeps the free |
| 715 | plan free of compute. |
| 716 | |
| 717 | ## Rails, summarized |
| 718 | |
| 719 | | Concern | Decided by | |
| 720 | | --- | --- | |
| 721 | | What an agent can see | Its scopes, and the channels and spaces it was invited to. An invite grants read, never write. | |
| 722 | | What it can change | Its scopes, then rulesets, branch protection and environment rules. | |
| 723 | | When it must ask | Its autonomy settings plus policy. Approvals are cards in the thread and items in the inbox; acting in either settles both. | |
| 724 | | What it can spend | Workspace, then agent, then task, then session. | |
| 725 | | Who did what | The audit log. Every action records the agent, its definition version, the task, and the person who asked. | |
| 726 | | Not colliding | Claims, the coordinator and the merge queue. | |
| 727 | | Not looping | Hop limits, addressed-only replies, rate limits, shared budgets. | |
| 728 | |
| 729 | ## Shell |
| 730 | |
| 731 | A rail on the left, as in the mockups: Home, Code, Chat, Docs, Agents, |
| 732 | Inbox, then the account. |
| 733 | |
| 734 | - Each mode has its own sidebar, and no mode's sidebar lists another mode's |
| 735 | things. |
| 736 | - Code keeps today's sidebar. |
| 737 | - A side dock shows the current project's or page's linked channels in Code |
| 738 | and Docs, and the linked project and docs in Chat. |
| 739 | |
| 740 | Concretely: |
| 741 | |
| 742 | - `shell.tsx` gains a `mode` above today's drill-down stack; |
| 743 | - `workspace-nav.ts` gains a `ModeKey`; |
| 744 | - each mode keeps its own `SidebarKey`s. |
| 745 | |
| 746 | ## Services |
| 747 | |
| 748 | Following the architecture principles: separate services, interfaces in |
| 749 | `packages/contracts` and `crates/contracts`, side effects through |
| 750 | `services/events`. |
| 751 | |
| 752 | | Service | Owns | |
| 753 | | --- | --- | |
| 754 | | `services/chat` (new, TS) | Channels, members, messages, threads, reactions, read state; one Durable Object per channel for live delivery with WebSocket hibernation. | |
| 755 | | `services/agents` (new, TS) | Agent definitions and versions, the desk Durable Object per agent, the coordinator Durable Object per workspace (claims), replies (the no-sandbox model loop over g1t MCP). | |
| 756 | | `services/docs` (new, TS) | Spaces, pages, the page Durable Object (CRDT), suggestions, comments, citations and staleness, git-backed storage. | |
| 757 | | `services/work` | Tasks and task links beside `agent_runs` (which gains `task_id`); `agent_messages` widened to task addresses. | |
| 758 | | `services/runner` | Resumable sessions: transcript save and restore in R2, `--resume`, the steer hook reading task threads, claims checked at start and widened from diffs. | |
| 759 | | `services/context` | Indexes doc pages and channel decisions; serves them to replies and sessions. | |
| 760 | | `services/events` | New event types (`chat.message.created`, `task.*`, `claim.*`, `doc.page.*`); inbox reasons for mentions, approvals, suggestions, stale pages. | |
| 761 | | `services/billing` | Agent-level budgets in the reserve/settle contract; Agent-token metering for replies. | |
| 762 | |
| 763 | Every Cloudflare primitive used here stays behind an adapter, so |
| 764 | self-hosting keeps working: |
| 765 | |
| 766 | - Durable Objects; |
| 767 | - WebSockets; |
| 768 | - R2; |
| 769 | - D1. |
| 770 | |
| 771 | ## Build order |
| 772 | |
| 773 | Each step ships something usable. |
| 774 | |
| 775 | 1. **Contracts.** Agent definition and version, task, claim, channel, |
| 776 | message, card, page; RPC methods; event types. |
| 777 | 2. **Agents as members.** `services/agents` with definitions, templates |
| 778 | (planner, implementer, reviewer, triage, documenter) and the Agents mode |
| 779 | list and profile. Assigning an issue to a workspace agent works through |
| 780 | today's runner, as a task. |
| 781 | 3. **Shell.** The rail and modes; Chat, Docs and Agents sidebars (empty |
| 782 | states where needed); the dock. |
| 783 | 4. **Channels.** `services/chat`, live delivery, threads, reactions, read |
| 784 | state, mentions into the inbox. |
| 785 | 5. **Talk to an agent.** The desk; replies with no sandbox; DMs and |
| 786 | mentions; personality applied. |
| 787 | 6. **Tasks and resumable sessions.** Tasks from chat; live task cards; |
| 788 | sessions saved and resumed; steering from the thread; opening a session |
| 789 | and taking it over; capacity and the queue. |
| 790 | 7. **Budgets and approvals.** Agent and task budgets in billing; approval |
| 791 | cards that settle with the inbox. |
| 792 | 8. **Coordination.** The coordinator; claims on issues, branches, |
| 793 | environments and paths; overlap negotiation in threads; widened |
| 794 | `agent_messages`; hop and rate limits; leads. |
| 795 | 9. **Docs.** Spaces, pages, live editing, history, comments, mentions; |
| 796 | indexed by context; agents reading. |
| 797 | 10. **Agents in Docs.** Suggestions, citations and staleness, "write this |
| 798 | up", the documenter template, repository docs as spaces. |
| 799 | 11. **Create in chat, skills and triggers.** The draft-card flow; skills |
| 800 | from a walkthrough; schedules, events, watched channels and webhooks as |
| 801 | triggers. |
| 802 | 12. **Scale and reach.** |
| 803 | - Team sections, browse, muting, and search across messages, pages and |
| 804 | tasks. |
| 805 | - Installable desktop and mobile apps. |
| 806 | - Bridges for teams that keep another chat tool: one app per workspace, |
| 807 | a handle per agent. |
| 808 | |
| 809 | Steps 2, 5 and 6 are the turning point: from then on, talking to an agent |
| 810 | is the everyday way work starts. Step 8 lets a workspace run many agents at |
| 811 | once safely. Step 10 is where Docs stops being a wiki and becomes the |
| 812 | thing that keeps itself true. |
| 813 | |
| 814 | ## Decisions to confirm |
| 815 | |
| 816 | - **Model choice on the agent.** Per-agent preferred models, set when the |
| 817 | agent is defined, with Auto as the default. Choosing a model when |
| 818 | assigning work stays out. |
| 819 | - **Replies without a sandbox.** Chat answers come from a Worker-side model |
| 820 | loop, not a container. Recommended for speed and cost. |
| 821 | - **Docs stored in git.** Each space is a git repository, and live editing |
| 822 | is a CRDT saved to it. |
| 823 | - **Agent edits to docs** are suggestions unless the agent has write access |
| 824 | to that space. Recommended default. |
| 825 | - **Default capacity** of 3 concurrent tasks per agent, and a hop limit |
| 826 | of 6. |