The shelf

The shelf is a lightweight, per-workspace jobs board curated with Kin. It holds work that is larger than the current turn’s todos: a future rock can stay local for a later session or run on Outpost from its own git branch.

Outcome

Park a self-contained job as .kin/shelf/<slug>.md, see what is ready or blocked, and later pick it up from the card alone. Outpost jobs return on shelf/<slug> with their own verified return brief committed into the card.

Fast path

1. Run /shelf park <idea> and review the proposed rock-sized card.
2. Run /shelf or /shelf board to groom blockers and choose what is ready.
3. Use /shelf pickup <slug> for local work, or /shelf submit <slug> for an Outpost run.
4. When a remote branch returns, use pickup. Kin reads the card on the branch, summarizes it in its own words, and verifies git history, the diff, and every Done-means item before merging.
5. Use /shelf recover <slug> only when a submitted card is overdue.

Cards are durable cursors

Frontmatter carries status, lane, branch, optional blockers and Outpost identity. The body records Intent, checkable Done means, durable Context pointers, and an append-only Trail. The bundled shelf skill contains the canonical template.

For an Outpost lane, the final branch commit must update its own card with status done or stuck, the standard Return brief, and verification evidence. Kin refuses to merge a branch that omits that evidence. Git is the work-product channel and the completion-notification channel; no GitHub pull request is required.

Awareness without polling

On each root turn, Kin sees a compact board hint only when the tracked cards changed. In the TUI, a background watcher checks the fixed refs/heads/shelf/* refspec every 120 seconds and correlates submitted cards with the existing 45-second Outpost attention snapshot. It adds no Outpost API traffic.

A new branch raises one informational toast and a metadata-only reminder. If Kin is idle, it quietly announces the change and offers pickup; it never starts the job without you. Branch appearance means only that the remote job believes it is done—the pickup verification remains mandatory. Delivery is at least once across TUI restarts, with card status as the durable deduplication cursor.

Set shelf_enabled = false (or KIN_SHELF_ENABLED=0) to disable board hints and the watcher. shelf_watch_interval / KIN_SHELF_WATCH_INTERVAL changes the git probe cadence with a 30-second minimum; it is read once when the TUI mounts.

Sharing .kin/shelf

Most .kin/ state is machine-local. Shelf cards are the exception. A repo that ignores .kin/ must use:

.kin/*
!.kin/shelf/

Git cannot re-include a directory beneath a blanket .kin/ ignore. Kin proposes this change during first-time initialization but never makes it silently.

Reference

• Beam work to Outpost
• Skills
• Slash commands
• Decision record 0133