Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Start a project

Every chapter so far taught one piece of gonk. This part puts them together over a real project: a small library-lending system, with specs, two artifacts, tests and two changes in flight, generated by the gonk starter. You will start it, change its spec, turn the change into ledger items, claim one, reproduce and fix it, close it with evidence, run a second agent beside the first, ask the project questions in SPARQL, and let a model draft one of those questions.

A spec in the repository taught the openspec/ tree and the items it becomes. Solo on one machine and Spec first showed the starter’s packaging in passing. Here the starter is the subject, and tools/gonk.py does what those pages wrote out by hand.

What you need

ikigai-gonk and ikigai, as Which gonk installs them, plus git, jq, and Python 3.11 or later. The sample’s tests and tools/gonk.py use only Python’s standard library.

⚠ Each $ line below runs from this chapter’s directory, so a command that works inside the project is written (cd library && …). The parentheses keep your shell where it is.

Generate the sample

In a new empty directory, as in every chapter. Clone the starter at the revision this book checks and generate from it. --process solo,spec says how you work: you are your own dispatcher, and a change in behavior starts as a spec change.

$ git clone --quiet https://github.com/ikigai-rs/ikigai-gonk-starter starter
$ git -C starter checkout --quiet 2a5f08cdeec2535d0addb03fcb5b6b62bb870e4a
$ (cd starter && python3 tools/new.py ../library --process solo,spec)
generated the library-lending sample (python, process solo, spec) in …/library: 98 files
next, in that directory:
  git init -b main, then commit everything it wrote (the one commit where every file is yours; -b main because the worker loop branches from origin/main, and git's own default is still master where init.defaultBranch is unset)
  python3 scripts/test.py                      every test, as CI runs them
  python3 tools/gonk.py init --ledger <name> --socket ~/.ikigai/gonk.sock --holder <you>
  python3 tools/gonk.py seed                   file the open changes' tasks as items
  python3 tools/gonk.py next                   what to do first, and why
AGENTS.md holds this process's rules; README.md walks through the sample.

Do what it says: make it a repository and run its tests. --target rust, deno or go generates the same sample in another language, against the same spec.

$ git -C library init -q -b main
$ git -C library add -A
$ git -C library -c user.name=Ada -c user.email=ada@example.com commit -q -m 'Generate the library sample'
$ (cd library && python3 scripts/test.py 2>&1 | tail -1)
all 3 suites passed

What it gave you

pathholds
AGENTS.mdthe rules, for every agent and every person; CLAUDE.md imports it
openspec/specs/what the library does now, one capability per directory
openspec/changes/what is proposed: cap-late-fees (small) and add-holds (both artifacts)
openspec/vectors.jsonevery scenario of the specs, as steps any language’s tests run
artifacts/one directory per deployable thing: service and cli
.gonk/which ledger, the process, the saved queries and the workflow scripts
tools/gonk.pythis repository’s one way to reach gonk
$ LC_ALL=C ls library/openspec/specs library/openspec/changes library/artifacts
library/artifacts:
README.md
cli
service

library/openspec/changes:
README.md
add-holds
cap-late-fees

library/openspec/specs:
README.md
catalog
loans
members
overdue
renewals

Nothing connects it to a gonk yet, and status says exactly what is missing:

$ (cd library && python3 tools/gonk.py status)
gonk.py: no ledger is named in .gonk/gonk.toml: `python3 tools/gonk.py init --ledger <name>`
this working tree does not say how to reach gonk (.gonk/local.toml): `python3 tools/gonk.py init --socket <path>` or `init --quic quic://host:port --cert-dir <bundle>`
process: solo, spec

A gonk on this machine

If the gonk from Harness engineering is still running, stop it first, since this one takes the same port. The page starts a scratch gonk; on your own machine yours is probably already running, at ~/.ikigai/gonk.sock.

Run the next command in a second terminal, from the same chapter directory. Leave it running and return to the first terminal for the commands that follow.

$ ikigai-gonk --config-home "$PWD/.config/ikigai" --data-home "$PWD/.ikigai" --port 1070 --no-backup 2>&1 | tee gonk.log
ikigai-gonk 0.1.1 — holding the store at …/.ikigai/store
…

init writes what its flags say, then checks everything it can reach. The ledger name goes in a committed file, so every clone works in the same ledger. The socket and the holder, the name this working tree claims under, go in a git-ignored one, because they belong to this machine and this tree.

Name the ledger after the project, as this one does. One gonk can hold many projects, and each repository’s saved queries are published under its ledger’s name.

⚠ Do not use default as a project’s ledger at the starter revision this book pins. gonk answers an append in default with #3 … and in any other ledger with library#3 …, and seed reads only the second form, so it files every task, calls each one failed, and links none of them.

$ (cd library && python3 tools/gonk.py init --ledger library --socket ../.ikigai/gonk.sock --holder ada)
gonk init: …/library
  ok       layout    openspec at openspec/; artifacts at artifacts/; queries at .gonk/queries/; scripts at .gonk/scripts/
  note     harness   4 harness question(s) in .gonk/queries/ are asked by `python3 tools/gonk.py harness` through gonk's store, not published: gonk runs a script under a ceiling of ledger reads, and they read the harness graph
  note     openspec  8 open task(s) in 2 change(s) in flight: `python3 tools/gonk.py seed` files them as ledger items (again is a no-op)
  ok       process   solo, spec (.gonk/process.toml)
  note     solo      one person and their agent: you are your own dispatcher, and close after checking your own evidence
  note     role      you: both the dispatcher and whoever does the work
  note     spec      spec first: every change in behavior starts as an openspec change, seed files its tasks, next orders them
  note     hook      the Claude Code claim hook is optional and off: merge hooks/claude/settings.sample.json into .claude/settings.json to turn it on
  note     hook      the commit-msg hook that refuses a bare #N is off: `git config core.hooksPath hooks/git` turns it on
  ok       ikigai    ikigai … at …/ikigai
  ok       ledger    `library` (.gonk/gonk.toml)
  ok       holder    `ada` (.gonk/local.toml, this working tree only)
  ok       identity  the socket's owner: every request over it is `owner`, so the log cannot tell this tree from any other process of yours. A machine that must be named uses QUIC
  ok       gonk      socket …/.ikigai/gonk.sock answers
  note     items     `library` holds nothing yet, or this identity may not read it. A ledger has no create: it exists once something is filed in it (`python3 tools/gonk.py file "<title>"`)
  ok       scripts   gonk offers `urn:script:catalog`: saved queries and workflow scripts (ikigai-script)
  ok       scripts   published 4: urn:script:library-open-items-for-artifact, urn:script:library-open-work-by-change, urn:script:library-requirements-with-open-work, urn:script:library-next-for-artifact
  absent   nl        gonk does not offer `urn:nl:sparql` yet, so a query is written by hand rather than drafted from a sentence (ikigai-nl); nothing to do until it does

agents over MCP (configure the agent with this command):
  ikigai mcp --grant agent --override urn:iki:ledger:=…/.ikigai/gonk.sock

ready.
$ git -C library status --short
 M .gonk/gonk.toml
$ git -C library -c user.name=Ada -c user.email=ada@example.com commit -q -am 'Work in the library ledger'

Read the rows as a checklist. ok is checked, note is something to know, and missing would stop you, with the command that fixes it. absent means gonk mounts no model, so it offers no drafting; A query from a sentence, later in this part, changes that. Only .gonk/gonk.toml changed in the repository. That is the one line every clone shares.

A gonk on another machine

A remote gonk is reached over QUIC with a client certificate per machine, so the same page can show it by enrolling a second working tree against this gonk’s QUIC door. On the machine that will do the work, make an identity. Its private key never leaves that machine.

$ ikigai cert generate --dir laptop-cert
wrote server.{crt,key} and client.{crt,key} to laptop-cert
to attach a client on another machine, copy client.crt, client.key, and server.crt there.

Then, in a clone there, init with --quic and --cert-dir. This gonk does not know the certificate yet, so init reports what is missing and prints the two lines the operator chooses between: --worker for an unattended machine, which claims and comments and cannot close, and =write for a person’s, which also files, closes and relabels. git worktree stands in for that clone:

$ git -C library worktree add -q ../laptop -b laptop
$ (cd laptop && python3 tools/gonk.py init --holder laptop --quic quic://127.0.0.1:1070 --cert-dir ../laptop-cert | grep -E ' identity  |missing  |client add laptop|thing\(s\)')
  ok       identity  urn:iki:host:gonk:client:… (from …/laptop-cert/client.crt)
  missing  gonk      quic quic://127.0.0.1:1070 (certificates in …/laptop-cert) did not answer: …
    ikigai-gonk client add laptop --cert client.crt --worker library
    ikigai-gonk client add laptop --cert client.crt --ledger library=write
1 thing(s) missing.

The operator runs one of those on gonk’s machine, restarts gonk, because it reads the certificates it trusts at startup, and sends back the server.crt from the bundle it wrote. That copy replaces the one cert generate made, which is not gonk’s. Here gonk’s machine is this one:

$ ikigai-gonk client add laptop --cert laptop-cert/client.crt --ledger library=write --port 1070 --config-home "$PWD/.config/ikigai"
$ cp .config/ikigai/gonk/quic/clients/laptop/server.crt laptop-cert/server.crt

After the restart, init in that tree ends ready., and every command in the rest of this part works the same. The differences are who gonk says you are, which matters in Claiming, and what the grant lets you do:

the socketQUIC
reachesgonk on this machinegonk on any machine
gonk knows you asowner, with every other process of yoursthis machine’s certificate
may doeverythingwhat the operator granted: --worker claims and comments, =write also closes
choose it foryourself, on your own machinea laptop, a build box, an unattended worker

The three doors and A QUIC client teach that door properly.

What you have now

A repository whose tests pass, a ledger named in it, a working tree that knows how to reach gonk and what to call itself, and four saved queries already published. The ledger is still empty. The next chapter fills it from the spec.