# The System — starter kit An obligation ledger, a written rulebook and a session ritual for the AI assistant you already use. Fifteen minutes to install. A free hosted Postgres is enough. No API key, no server, no code to deploy. The idea in one line: **the assistant stops being a clever chat and becomes a colleague that holds every open obligation, reads the same rules every time, and leaves a handoff for its next session.** --- ## What you have at the end - **An obligation ledger.** Tasks, decisions and open threads, each with an owner (`founder` or `system`) and a `next_check_at` date. A trigger makes sure nothing open is ever left without a date. - **Two views that say what to look at.** - `v_due_for_check` — *completeness*: everything whose check date has passed. Every row gets acted on or re-dated. Nothing silently rots. - `v_next_up` — *importance*: open work scored, with a plain-text `why` column that shows exactly how each score was built. - **An approval lattice the assistant reads every time.** Read and draft are automatic. Create needs approval. Delete, spend, send and anything that widens reach always ask first. - **A session ritual.** A fixed open (five reads, then a proposal) and a fixed close (a transaction, not an essay) that writes a typed handoff the next session starts from. --- ## What is inside ``` starter/ ├── README.md this file ├── LICENSE MIT ├── schema/ │ └── obligations.sql the whole database, one idempotent migration ├── ritual/ │ ├── SESSION_CONTEXT.md the operating doctrine the assistant reads │ ├── OPEN.md how a session opens │ ├── CLOSE.md how a session closes │ └── DOCTRINE_TEMPLATE.md versioned laws learned from incidents ├── skills/ │ ├── session-ritual/SKILL.md open and close, step by step │ ├── approval-lattice/SKILL.md what may happen without asking │ └── capture/SKILL.md turning conversation into ledger rows └── scripts/ ├── open.sql the three reads of the open ritual ├── close.sql the close, as a fill-in template └── seed.sql optional example rows for day one ``` --- ## Install (about 15 minutes) ### 1. Create a free Postgres project (3 min) Sign up for a free hosted Postgres such as Supabase, or use any Postgres 15+ you already run. Create a new project. Note the database password somewhere safe; you will not need it for the rest of this guide if you use the browser SQL editor. ### 2. Run the schema (2 min) Open the project's **SQL editor**. Paste the entire contents of `schema/obligations.sql` and run it. You should see it finish without errors. Running it a second time is safe; it creates nothing twice and deletes nothing. Optional: paste and run `scripts/seed.sql` too. It adds six example tasks, one decision, one open thread and one handoff, all tagged `[example]`, so the first open has something to show. A cleanup block at the bottom of the file removes them. ### 3. Give the assistant its doctrine (3 min) Open `ritual/SESSION_CONTEXT.md`. Read it once — it is one page — and change anything that does not fit how you work. Then paste it into your assistant's standing instructions: | Assistant | Where it goes | |----------------------|-------------------------------------------------| | Claude | a Project → project instructions | | ChatGPT | a Project's instructions, or custom instructions | | Gemini | a Gem → instructions | | Anything else | wherever it keeps text it reads on every chat | If your assistant also accepts files, add `ritual/OPEN.md`, `ritual/CLOSE.md` and the three `skills/*/SKILL.md` files as project knowledge. If it supports skills natively, install the `skills/` folders as skills instead. ### 4. Open the first session (5 min) Start a new chat in that project and type: ``` Open the session ``` Then give it the ledger. Two ways: - **By hand.** Run `scripts/open.sql` in the SQL editor, copy the three result tables, paste them into the chat. - **Connected.** If your assistant can connect a database tool (for example through an MCP server for Postgres), connect it to your project and the assistant runs `scripts/open.sql` itself. Read-only access is enough for the open. The assistant should act on or re-date every `system`-owned row, list every `founder`-owned row as one grouped list, and offer two or three ways to spend the session. If it does something else, it has not read the doctrine: check step 3. ### 5. Close the first session (2 min) When you are done, type: ``` Close the session ``` The assistant fills in `scripts/close.sql` for this session — which rows to close, which to re-date, what shipped, what was ruled, what was learned, and the handoff. **Read it**, then run it in the SQL editor. It is one transaction: either all of it lands or none of it does. The handoff insert fails if `measured`, `ruled`, `in_flight` or `do_not` is empty; that is on purpose. The next open reads that handoff. The loop is now closed. --- ## Daily use - **Start every working session with "Open the session".** Five minutes. - **Talk normally in between.** The capture skill turns decisions, ideas and tasks you mention into proposed ledger rows. You approve them; it does not write them silently. - **End with "Close the session".** Two minutes. Never skip it; the handoff is the only memory the next session is guaranteed to have. - **Once a week, ask for an evolution session.** "What did we do by hand twice this week?" Each answer becomes a task, not a paragraph. --- ## How the two views think `v_due_for_check` answers *what has to be looked at*. It does not judge. A someday item whose check date passed shows up next to an urgent deadline, because the only rule is: nothing open goes unseen. `v_next_up` answers *what matters*. The score is deliberately simple: | Component | Points | |-----------------------------------|---------| | Serves a horizon (`horizon` set) | +100 | | Due within 7 days (or past due) | +35 | | Due within 30 days | +8 | | Unblocks other work | +25 | | Priority high | +15 | | Days past check date (max 10) | +0..10 | The `horizon` bonus is large on purpose: work that serves a goal you have written down outranks everything else. Open decisions count as "unblocks", because something is always waiting on a ruling. Change the numbers in the view if they do not match how you weigh things; the `why` column will follow. --- ## The approval lattice, in one table | Action class | Default | |-------------------------------------------------|----------------------| | Read anything, draft anything | automatic | | Create (a row, a file, an event, a document) | needs your approval | | Delete, spend, send, or widen reach | always asks first | A class of action can graduate to automatic only when it passes all four parts of the test in `SESSION_CONTEXT.md`: reversible, internal, objective, bounded. Anything that changes power or reach — new credentials, new outbound channels — never graduates. --- ## What is NOT in v1 Described here so the shape is clear, not shipped in this kit. These are the later tiers of the guide at . - **A job runner.** v1 has no process that does work while you are away. Every action happens inside a chat you are part of. - **Scheduled loops.** No morning brief, no escalation of overdue items, no nightly reflection. The views are there; nothing reads them on a timer yet. - **Chat channels.** No push messages to your phone, no inbound email. The assistant only speaks when spoken to. - **Credential handling.** The assistant holds no keys to anything. If you connect a database tool, that tool holds the connection, and the lattice still governs what the assistant may do with it. Each of these adds reach, and reach is exactly what the approval lattice is for. Add them one at a time, after the ritual has run for a few weeks. --- ## Using your own schema Everything lands in `public` for simplicity. To use a dedicated schema: ```sql create schema if not exists ops; ``` Then add `set search_path = ops;` as the first line of `schema/obligations.sql`, run it, and add the same line to the top of the scripts. If your host exposes tables over an automatic HTTP API, check its settings for which schemas are exposed; the kit does not need any to be. --- ## Security defaults - Row level security is **on** for every table, with **no policies**. A public API key, if your host issues one, can read and write nothing. The SQL editor and direct database connections are unaffected. - Both views use `security_invoker`, so they follow the same rule instead of running with the owner's rights. - Nothing in the kit stores a credential, calls an external service or schedules anything. --- ## Troubleshooting **`function gen_random_uuid() does not exist`** Your Postgres is older than 13, or the `pgcrypto` extension is missing on a very old setup. The kit expects Postgres 15+. Hosted free tiers are already there. On an old self-hosted server, upgrade, or run `create extension if not exists pgcrypto;` first. **`unrecognized parameter "security_invoker"`** Same cause: Postgres 14 or older. Upgrade to 15+. As a last resort, delete the two `with (security_invoker = true)` lines; the views will then run with the owner's rights, so do not expose them over a public API. **The assistant ignores the ritual and just chats.** It is not reading `SESSION_CONTEXT.md`. Check it is pasted into the project's standing instructions, not into a single message, and that you started the chat inside that project. Then say "Open the session" as the very first message. --- ## License MIT. See `LICENSE`. Copy it, change it, ship it in your own tools.