Getting started

First run

Create a project

A project is the top-level container: a name, a one-liner, an optional repository — GitHub or GitLab — and deploy URL, and — where the Atlassian integration is enabled and once you attach them — a Jira project key and a Confluence space key. A new project is a name, a first release, and an empty Documents tab. Nothing is pre-created: folders and documents appear as the work asks for them, so what you see in a project is what somebody actually put there.

Releases live inside the project. A release has a version string and a stage — idea, exploring, planning, handoff, building, shipped, parked — and its own document box. The box is a set of named slots rather than a set of files: a folder is created the first time a document files into one of its slots.

Every project belongs to exactly one owner: a person's own workspace, or an organization. That is what each query scopes by, so the same account sees different projects depending on the context it has active. A project is not stuck where it started — the Danger zone on its Settings tab offers a transfer to any other context you can move it into, which is your personal workspace plus the organizations you administer. The transfer is refused rather than fudged when the destination already has a project with the same slug; rename one of them and try again. See Organizations for how the contexts themselves work.

The board

/board is the one cross-project view: every release you own, from every project, as a kanban. Its Releases tab draws three columns by default — Idea, Building, Shipped — where Building holds everything between having the idea and shipping it. The Display menu's Grouping swaps that for the full six-stage ladder (Stage, full ladder) whenever you want it; Work items is the tab beside it.

The grouping is display only. A release drawn under Building keeps whatever stage it is really in, the stage dropdown on each card still offers every rung, and every gate runs on the real stage rather than the column. parked is not one of the stage columns in either view. It gets its own Parked column at the end, collapsed by default and still a live drop target, so parking a release is a drag rather than a menu and parked work stops competing for attention without disappearing.

The board's numbers sit in the side panel's Board card: active releases with the project and parked counts under them, how many are in flight (handoff plus building), open pull requests, and a document count. A figure that reads — means the answer was not knowable — the forge is not connected, no project names a repository, or the read failed. A real zero renders as 0, because "checked, found none" and "couldn't check" are different answers.

Dragging a card between columns changes the release's stage, and it is guarded: the drop runs the same stage gates the stage dropdown does, so a release cannot skip a check by being dragged instead of clicked — the shipped preflight still blocks on a missing Release Notes or Retrospective. Dragging a card within its own column does nothing; stage order comes from the release rows themselves, and there is no server action that reorders inside a stage.

A drop sets the stage the column stands for, which is worth knowing on the three-column board: dropping a card into Building puts that release in building itself, not at the next rung along. The four stages folded into Building are therefore not reachable by dragging — moving something to planning or handoff is the card's stage dropdown, or the full ladder.

The document tree

Kairoku knows a template tree, and nothing in it is created up front. The names below are the app's vocabulary — the folders it will make when work files into them, and the documents the New-document dialog offers you with a sentence each explaining what they are for. Picking one creates it; not picking one leaves nothing behind.

Structure therefore arrives three ways. Work creates it: accepting a feature makes Planning/, keeping a thought as a note makes Notes/, and a document filing into a box slot makes that box's folder — one folder at a time, only the one asked for. You create it, by choosing a suggested document from the New-document dialog. Or you ask for all of it at once: the adoption wizard on a project's Documents tab lays down the full tree and every release box in one confirm-first pass, which is the way to get the whole shape deliberately rather than by accident.

Two trees, answering different questions.

The project tree is release-agnostic. Four groups:

The release box is the same set of slots for every release, under Releases/<version>/:

• Release Brief — expected from the idea stage on.
• PRD — expected from planning. Titled with its release, e.g. PRD — v2.
• Specs/ — expected from planning.
• Implementation Plan — expected from handoff.
• Release Checklist — expected from handoff.
• Release Notes and Retrospective — required to ship.
• Design/, Research/, Agent Briefs/, Amendments/ — never required; they fill on demand.

Laying the tree down is idempotent and matches on folder slot and document title, so running the wizard against a project that already has real work in it adopts what is there instead of duplicating it.

Document classes

Class lives on the folder, not the document, and it decides who may write and when. One guard runs on every write seam — the app's own editor, MCP, the AI workspace, and the Confluence pull — so a rule cannot hold in one place and leak in another. The rules run in order, first match wins:

1. A frozen box refuses everyone. Once a release is shipped or parked, its box is sealed regardless of class — including a create into its Research/.
2. reference allows a create and refuses edits. Reference material is superseded by a new document, not rewritten in place.
3. living documents — Vision, Roadmap, Test Strategy, the design system — are amendment-governed. An agent may edit one directly, with no confirmation and no override: every agent edit is kept as a recoverable revision, visible in the document's History. A human instead has to confirm past the editor's banner, and that confirmation owes a Decision Log entry and an activity trail. An amendment in Amendments/ remains a valid route for either, just no longer the mandatory one for an agent.
4. ledger documents — Decision Log, Build Journal, Risk Register — are append-only. A write must add a row rather than replace the body, and the appended row's first line must carry an open release's tag or it is refused.
5. working documents — everything in a live release box — are ordinarily writable.

Every refusal comes back as a sentence an agent can recover from on its own, through the same channel as any other result. There is no side channel telling a caller which rule fired.

Release boxes

A release box is the unit that seals. While the release is open, its documents are working class and agents write them freely. When the release ships or is parked, the whole box freezes: the PRD, the specs, the plan and the notes stop being editable, and stay as the record of what that version actually was. Work that arrives afterwards belongs to the next release's box, or — where it changes something already agreed — to an amendment in Amendments/, which carries its own disposition footer once applied or deferred.

Attachments

Documents carry image attachments — PNG, JPEG, GIF or WebP — and their storage is private by construction. An attachment is a private object in Kairoku's artifact storage, uploaded through a short-lived signed policy for that one key; fetching the object without a signature is refused. Every read by a signed-in viewer is a short-lived signed URL scoped to that one file, so a link cannot be replayed against another attachment.

The trade is deliberate: no permanent link to an attachment exists anywhere, and a link that leaks dies when its window closes rather than outliving the share it came from. A share page does not hand out signed links at all: its attachments are read through the API under that page's share token.