Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.
| Chat and workspace agents: channels, DMs and named agents you talk to | 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. |
