Set up issue tracking in Known

This guide sets up an issues table that your team and your agents share: one record per issue, with fields the schema checks and a page that tells everyone how to use it. It takes about 15 minutes. It's the setup we use for Known's own backlog.

You need a Known organization and the known CLI, or an agent connected to Known. The examples use the organization acme and a wiki called product.

1. Create the table

An issues table is a page with a key. Write the page, then set its key:

known acme wiki write product:issues --title "Issues" --text "Every bug, feature and task, one record each."
known acme wiki meta product:issues --text '{"key": "id"}'

Or ask your agent: "Create a table at product:issues, keyed by id."

2. Add a schema

A schema makes every issue have the same fields. Agents read it before they write, so the descriptions double as instructions. Save this as issues.json:

{
  "key": "id",
  "schema": {
    "type": "object",
    "required": ["id", "title", "type", "status", "priority", "created_at", "content"],
    "properties": {
      "id": { "type": "string", "pattern": "^ISS-\\d{3,}$", "description": "ISS- plus the next free number." },
      "title": { "type": "string", "minLength": 1, "description": "What is wrong or wanted, in one short line." },
      "type": { "enum": ["bug", "feature", "improvement", "task"] },
      "status": { "enum": ["backlog", "planned", "in_progress", "in_review", "done", "cancelled"] },
      "priority": { "enum": ["p0", "p1", "p2", "p3"], "description": "p0 urgent, p1 high, p2 normal, p3 low." },
      "assignee": { "type": ["string", "null"], "pattern": "^\\[\\[people:contacts/[^\\]|]+\\]\\]$", "description": "Who is doing it, as a link to their contact." },
      "customer": { "type": ["string", "null"], "pattern": "^\\[\\[people:organizations/[^\\]|]+\\]\\]$", "description": "The customer who reported it, as a link." },
      "related_to": { "type": "array", "items": { "type": "string", "pattern": "^\\[\\[issues/[^\\]|]+\\]\\]$" }, "description": "Related issues, as links. Keep it two-way." },
      "links": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": ["commit", "pull_request", "deploy"] }, "url": { "type": "string" } }, "required": ["kind", "url"] }, "description": "Where the work happened." },
      "created_at": { "type": "string", "description": "When the issue was filed, in UTC." },
      "content": { "type": "string", "minLength": 1, "description": "The problem, evidence and acceptance criteria." }
    },
    "additionalProperties": false
  }
}

Apply it:

known acme wiki meta product:issues --file issues.json

Three choices in this schema matter most:

Choice	Why
pattern on id	Keys stay ISS-001, ISS-002, so people and agents can say "ISS-014" and mean one thing.
Links, not names, in assignee, customer and related_to	A link opens the record it points to and shows up in that record's backlinks. A name is only text.
additionalProperties: false	An agent can't invent a field. New fields are added to the schema on purpose.

3. Write the rules on the page

Agents read the page before they write records, so the page is where you say how your team uses the table. Edit the page text:

known acme wiki write product:issues --title "Issues" --file issues.md

What we put on ours:

• New issue: read the last key with wiki records product:issues --reverse --limit 1, then wiki get the next one to check it's free. wiki set replaces a record with the same key.
• Update: wiki get the issue, change only what changed, and write it back with --if-version. If the write is refused, someone changed it first: get it again and redo the change.
• Content starts with the problem. Don't repeat the fields in it.
• Links go both ways: when ISS-014 is related to ISS-009, add the link to both.

4. Add your first issues

known acme wiki set product:issues --file iss-001.json

Or tell an agent what's wrong. With the schema and page in place, "File a bug: the login page loops after a password reset, reported by Northwind" becomes a record with a key, a type, a priority and a link to the customer.

5. Read it

To see	Use
All issues, as a table you can sort and filter	The page in Known, in your browser
One issue, with its history	wiki get product:issues/ISS-001, and wiki history product:issues/ISS-001
What links to an issue	The issue's page in the browser, or wiki links product:issues/ISS-001
Issues by text	wiki search "login" product:issues

What Known doesn't do

Known shows issues as a table, not a board with columns per status. It doesn't send notifications, and it doesn't link commits automatically: in our backlog, the agent that ships a change adds the commit and deploy links itself. If your team lives in a board and notifications, keep a dedicated tracker for that, and keep the context in Known.

Next

How your team and agents work issues in Known