Most of ikie is built by Claude. Of the 882 commits on main, 828 (94%) come from Claude sessions. When a person writes a request in the project chat, a Claude picks up each thread, changes the code, opens PRs and uploads builds to TestFlight.
Those Claudes log their own work in ikie. One request becomes one task in a work calendar, and the checklist shown in the thread becomes the steps inside that task. PRs and artifacts are attached as links, TestFlight build numbers as notes. When the work is done, the task is finished with a one-line result. Opening ikie, the person who asked sees which work is in progress and which is waiting on their answer.
This post is about how that's put together.
First, we built an AI-only system
What we built first, on October 11, was a work system just for AI: its own tables for work, receipts so a retry is recorded only once, progress reports, its own REST and MCP endpoints, and a report screen. All in one day.
Early the next morning we took it out. Looking again, everything that system said could be said with what ikie already had.
- What's being done → a task
- In progress, or waiting → the task's status
- How far along → steps nested inside
- What came out → links and notes
- What kind of work → tags
A migration moved old records into tasks, notes, links and tags. We dropped two dedicated tables and two dedicated item fields. The removal PR alone took out 2,503 lines (#266, #268).
October 11
A path only AI uses grows on its own. Features people use stay the same.
From October 12
Fixing what Claude missed improves features people use.
No AI-only tables, fields or rules. What Claude needs is done with app features.
Since the removal, everything Claude said it missed became an app feature: attaching links to items, finding by link address, changing in-progress and waiting in the detail view, Markdown notes, editing a single field. People use them the same way on the web and iPhone.
Through the same door as people
A connected Claude comes in through MCP. The MCP server is a thin adapter that calls the same use cases as the public API, with the same value schemas (#261). Who can see and change what goes through the same decision as for people. The only difference is that the change history records it as a "connected app".
There are 39 tools, and two are only for logging work.
start_work: makes a task, sets it in progress and attaches the thread address as a link. It calls the create-item use case once.finish_work: adds a one-line result to the notes and finishes the task. If unfinished steps remain inside, it refuses (#604).
Neither adds storage or fields. They bundle what used to take several calls into one write.
A test keeps the door the same. When someone a calendar is shared with puts the same values into the owner's Google calendar, through the public API or through MCP, it checks that the results match and that the owner's account syncs once (#391). The routes and MCP handlers are real; only what's below them is an empty database (PGlite).
Rules in one place, the rest generated
Claude follows 22 rules. Nine are how any Claude should use ikie's tools; 13 are how a Claude working in this repository logs its own work. The rules are written as data in one file (#296). Each has when it applies, one sentence, the tools it uses and whether the hook enforces it.
- Source
packages/policy/src/agent.ts22 rules: one sentence, tools used, when, whether the hook enforces it
- MCP guidance
lib/mcpThe 9 tool rules go in the MCP server's instructions. Every Claude connected to ikie gets them.
- Work rules
CLAUDE.mdAll 22 are written into a generated block of the repository's instructions (npm run policy).
- Hook
scripts/ikie-hook.tsInjects 4 at session start and checks 7 at stop.
- Ontology
packages/ontologyLinks each rule to its tools. CI blocks a rule that names a tool that doesn't exist.
What sessions do without asking (calling work-log tools, merging their own green PRs, builds) works the same way. It's written in the source with a reason, and the settings file is generated (#423). Editing it by hand fails a test.
The hook checks at the end
Rules that live only as text get forgotten. So a Claude Code hook checks when a session tries to stop. It reads the tool calls in the transcript in order and finds where outputs appeared (a commit, a PR, a merge, a TestFlight upload, an artifact, a shared-folder file). Then it checks whether the rule's tools were called before or after.
| Rule | When | What it checks |
|---|---|---|
| Task | Before the first commit or PR | A task was made or found |
| In progress | Before the first PR | That task was set in progress |
| Thread | Before the first PR | The thread address was attached to the task |
| Link | After a PR or artifact | That address was attached to the task |
| File | After a shared-folder file | The path was written in the notes |
| Build | After TestFlight | The build number was written in the notes |
| Finish | After a merge | The task with that PR was finished |
If a rule is missed, the hook says why and blocks once. It doesn't block again for the same reason, so a session without ikie's tools never gets stuck.
At first the hook could only see the transcript. It couldn't tell whether another session had already made the task, so it sometimes guessed wrong. So we gave the hook a narrow read path (#362). A work-log key reads only the calendars a person picked, and can only set steps on a task that carries this thread's address. Keys are stored only as hashes, and since the path ignores cookies, another site can't make a browser call it.
With a key, the hook can do more.
- Merged PRs: it reads the tasks carrying that PR's address in ikie and checks that they're finished or still have open steps inside (#389). Work spanning several PRs just keeps the remaining PRs as steps. It works the same whoever merges, from whichever session.
- Checklists: every time the thread's checklist changes, it's mirrored into the task's steps (#393). The steps a person sees in the thread and in ikie are the same.
41 gaps found by using it
One rule says: "When something in ikie gets in the way, write it down right away, one line in the findings collection." That collection became ikie's most honest user feedback. 41 have piled up so far, and 36 are fixed.
A few of them:
- Tools didn't return the ids they made. To attach a link after making a task, Claude had to reread the board and search for it. Creating tools now return ids.
- A week's board was 55 KB. It went over the tool result limit. Boards are read a day at a time, and a week only when really needed.
- There was no search. A session couldn't find its own task again. Now there's search by title, link address and status, and searching by the thread address finds that thread's work.
- Merging one PR demanded finishing the task. The work still had an iOS PR left after the server PR. Now open steps count as following the rule.
- New tools don't show in open sessions. A session gets its tool list when it starts. That can't be fixed, so the rule now says "they show from the next session".
How we got here
- Oct 11AI-only work system: own tables, receipts, report screen, work API
- Oct 12Thin MCP over the same use cases (#261), AI work removed (#266, #268), work-log hook (#293), rule source (#296), reading split from creating (#318)
- Oct 13Work-log key so the hook reads ikie directly (#362)
- Oct 14Checking tasks of merged PRs (#389), door test (#391), checklists as steps (#393), permissions from the source too (#423)
- Oct 16start_work and finish_work (#576), refusing to finish with open steps (#604)
What we learned
- What an agent misses, people miss too. Once the dedicated system was gone, Claude's complaints became the app's next feature list.
- Keep rules as data, not prose. Written once, the guidance, hooks and checks can't drift apart. Change a rule and all three change.
- Block, but don't trap. The hook blocks once per reason. A session without the tools can still finish its work.
- Let everyone in through the same door. When Claude rides the same use cases as people, permissions, history and external calendar sync don't need building twice.
The principle of splitting layers and keeping each decision in one place is in the principles post, and how documents grew out of task notes is in the editor post.