How it works

shoalmark keeps your project's work as plain files inside the project, so every agent that works on it reads the same current state. It shows you first what is waiting for your answer, and its checks report work marked as shipped when no saved change (a commit) in the project's history backs it.

A week in four steps

What needs your word waits for it; no agent answers for you.

1. The agents work and record where the work stands. Each work item is a Markdown file with what is true now and what comes next. A move to Shipped with no commit behind it is reported by the checks.
2. What only you can decide becomes a question. When an agent needs your decision it writes it down as one sentence, with the options and its own proposal, and carries on with other work. Between standups nobody interrupts you, except for what cannot be undone.
3. You sit, at the time you chose. At the time you chose, the standup prints the agenda: your decisions first, each with how long it has waited and what it holds up. You answer with one command per question; it writes your answer as a commit, signed with your key once you turn signing on.
4. The agents act on your answer, and a reviewer judges before the merge. A seat that holds the right to do so records your answer in the work item and moves on. Before work reaches a merge, a reviewer checks it; the board says whether that pass was independent, meaning it came from another session than the code. That is a report, not a proof. --queue lists the open pull requests in the order to merge them.

next: owner
ask: "Do the status-line scripts for Claude and Codex and the addressing rule ship with shoalmark, so a pinned copy carries them?"
ask-kind: ruling
ask-since: 2026-09-28
ask-options: "all three: --statusline, … | the status line only: … | the rule only: …"
ask-proposal: "all three: --statusline, --install-statusline for Claude and Codex, and the AGENTS.md rule with --whoami"

-next: owner
+next: build
+answer: "accepted - all three: --statusline, --install-statusline for Claude and Codex, and the AGENTS.md rule with --whoami"
+answered: 2026-09-28
+answered-by: …

Not everything needs you. A seat that holds the right to close closes work without asking you. Shipped with the tool are three seats with fixed rights: the planner may ask, close and triage, the reviewer may triage, the builder holds none of the four. For any other seat you set the rights yourself. Only a seat you give the right may answer, and by default that is you alone.

How firmly "no agent answers for you" holds is set by your signature. A signature proves the key, not the hand: whoever can use your key can answer as you. There are four tiers, from a key anything on your account can use to one that needs your touch. Your answer is your commit helps you choose.

Your part

• Once: you write three lines in your own words in TRIAGE.md (what the repository is for, what is true when it works, and what nobody may do to get there) and the current path, what comes first. And you set up your signature, in about ten minutes.
• Each week: one standup each weekday, fifteen minutes at the time you chose (the length can be set), and one command per answer.
• The rest is on the board: your agents are asked to end each session with what waits for you, and the board puts it first.

What shoalmark does not do

• It does not scan your code for security problems or data leaks.
• It does not prove that work is right. Its checks report a move to Shipped with no commit behind it; whether that commit did the job is what a review is for.
• It is not a migration tool: it imports no ticket system and starts from your repository's own work.
• Today it fits a project with one person in charge. Several people in charge are not tested in this beta.
• It needs Python 3.9 or newer; a git repository needs git installed. On Subversion it runs without git installed, from the release archive, and each run says what it cannot verify there: commit signatures and server-authenticated authors. It needs no server, database or account of its own.

Try it

The button "Copy the prompt" is taped over until v0.20.1: the prompt behind it, which will ask your agent to check whether shoalmark fits your project, is still being finished. Until then, the note for your project's agents, ADOPT.md, invites them to a measurement, not an instruction: about twenty minutes, everything in a throwaway folder, nothing in the real working directory. At the end the agents report to you, and you decide.

Read on

• Set up in ten minutes
• Your answer is your commit
• Your word in TRIAGE.md
• The standup