Guides · 3 min read
How your team and agents work issues in Known
How people and agents file, update and close issues in Known without overwriting each other, with examples from Known's own backlog.
Once issues are records in Known, everyone works the same backlog: people in the browser and the CLI, agents over MCP. This guide shows how that works day to day, with examples from Known's own backlog, where two founders and their agents file, update and close issues.
It assumes you've set up an issues table.
Who does what
| Who | Through | Typically |
|---|---|---|
| People | The browser, or the known CLI | Read the backlog, decide priorities, review |
| A coding agent (Claude Code, Codex, Cursor) | MCP, as the person who connected it | Files issues it finds, updates status while it works, adds commit and deploy links when it ships |
| A chat agent (ChatGPT, Claude) | MCP, as the person who connected it | Files issues from a conversation, summarises the backlog, triages |
Every change records who made it. An agent's change shows as that agent, acting for the person who connected it, so the history says "Claude Code for Nikolai", not just "Nikolai".
File an issue from where you are
A coding agent that hits a bug can file it without leaving the task:
"This test fails because the cache key ignores the locale. File it as a bug and keep going."
The agent reads the table's page and schema, finds the next free key, and writes the record. Because the schema has a customer field with a link pattern, it asks which customer reported it, or leaves it empty. It can't invent a name.
From a chat:
"Northwind says exports time out over 10,000 rows. File it, priority p1, and link it to Northwind."
Work an issue with its context
The point of keeping issues in Known is what's around them. When an agent picks up ISS-014, it can follow the links: the customer record and its recent meetings, the decision page that made it urgent, related issues. You don't paste any of it in.
"Pick up ISS-014. Read the customer and the related issues first, then propose a fix."
Update without overwriting each other
Two people, or a person and an agent, can update the same issue at once. Every record has a version (_v). Writes pass the version they read with --if-version, so a stale write is refused instead of overwriting the other change:
known acme wiki get product:issues/ISS-014 --json
known acme wiki set product:issues --file iss-014.json --if-version 3Agents do the same through the wiki_get and wiki_set tools. When a write is refused, they read the issue again and redo the change.
Close the loop when you ship
Our rule: whoever ships a change adds where it happened. A coding agent finishing ISS-014 sets status: done and adds the commit and the deploy:
"links": [
{ "kind": "commit", "url": "https://github.com/acme/app/commit/3f2c1ab" },
{ "kind": "deploy", "url": "https://app.acme.com" }
]Known doesn't watch your repository, so this is a step in the agent's routine, written on the table's page, rather than an integration.
See what changed
| Question | Where |
|---|---|
| What happened to this issue? | wiki history product:issues/ISS-014, or History on the issue's page |
| What did an agent change? | wiki diff product:issues/ISS-014 --version 4 |
| What changed in the backlog this week? | wiki changes product: |
Keep agents writing good records
Agents write what the table lets them. In our backlog, the faults came from gaps: an agent guessed a value the schema allowed, or put a fact in the wrong field. Each fix was a rule, not a reminder:
- a
patternon fields that reference other records, so only real links get through; - a
descriptionon every field, which agents read before writing; - rules on the table's page: find the next free key first, update with
--if-version, keep links two-way; nullfor anything unknown, never a guess.