Skip to content

README.md

Latest commit

 

History

History
46 lines (34 loc) · 2.27 KB

README.md

File metadata and controls

46 lines (34 loc) · 2.27 KB
Raw

Knowledge base

This folder is Terrakin's shared memory. Humans and agents both read it and write to it. If something you learned would save the next person an hour, it belongs here.

Start with INDEX.md. It lists every entry and is generated by pnpm kb, so it never drifts.

What goes where

Folder Write one when Lifetime
decisions/ You made a choice someone might later question: a library, a data shape, a rule, a tradeoff. Permanent. Supersede, never delete.
learnings/ Something surprised you, broke in a non-obvious way, or took a while to figure out. Until it's no longer true. Then edit or delete it.
handoffs/ You're ending a session with work in flight, or you finished something others will build on. Historical. The newest one is the one that matters.

Bigger proposals that need discussion before code go in docs/rfcs/. An accepted RFC usually produces one or more decision records.

Creating entries

pnpm kb new decision "Use Postgres for world state"
pnpm kb new learning "Vite proxy drops websocket on reload"
pnpm kb new handoff "Plot claiming done, towns next"
pnpm kb            # rebuild INDEX.md

Each command copies the folder's TEMPLATE.md, fills in the title and date, and prints the new path. Edit it, then run pnpm kb and commit both files. CI runs pnpm kb:check and fails if the index is stale or an entry is missing its frontmatter.

Rules

  • Keep entries short. A decision record is usually under a page. A learning can be three lines.
  • Write for someone with zero context: a new contributor, or an agent in a fresh session. Link to code with repo-relative paths (packages/sim/src/apply.ts).
  • One topic per file. Parallel agents writing separate files don't conflict; agents editing one shared file do.
  • Facts only. If you're guessing, say so.
  • Never put secrets, tokens, personal data, or private conversations here. This repo is public.
  • When a decision changes, write a new record and set the old one's status: superseded with a link forward.

Frontmatter

---
title: Short plain-words title
date: 2026-10-02
status: accepted        # decisions only: proposed | accepted | superseded | rejected
tags: [sim, protocol]
---