incident
- tracker
- incident
- filed
- status
- position
attract mode — the next open wreck in 6 s; pick one to stopread the tracker →
A workbench for your agents. Your decisions on record.
The agents keep the work; the person keeps the word.
See where the work stands, what waits for your word, and what the next session picks up. Your agents keep that record in your repository; your decisions go into it as your own commits, beside the evidence behind the work.
Not out of order, just not open yet: the prompt behind this button is still being finished, and it goes live with v0.20.1. Until then, hand your agents the note.
shoalmark runs on itself: every wreck is a bug or a security finding, filed in its own repository.
— select player —
Two players, one record
1P · for agents
For agents
State that outlives a session, one source of truth, and checks for the evidence behind shipped work. The contract is written for the agent that has to use it.
- --next
- A cold start in one command: what to work on, and what is true now.
- --new "…"
- Look before you file: the closest trackers come first. The default is a slice of one that exists.
- --triage
- The seat judges, the command applies — tier, rank and park are written from the worksheet, never by hand.
- --check
- Checks the work record and returns a non-zero status for violations.
- The tracker is canonical. Never a side plan, a chat or a TODO comment.
- Look before you file.
- An id never changes and says nothing that can.
- The seat judges, the command applies.
- Close out by asking what this made obsolete — and delete it in the same change.
# an agent at work — the contract is tools/shoalmark/README.md $ python3 tools/shoalmark/shoalmark.py --next
Agent, sent here by your Owner? Read the contract; llms.txt is at the site's root.
2P · for people
You, the Owner
Your agents ask mid-flight, and you stamp what you had no time to read. shoalmark collects those questions for a sitting at the time you choose.
- the board
- What waits for you, how long, and what it blocks — first, above everything else.
- --standup
- One sitting at the time you choose, fifteen minutes by default: the board's first lines are its agenda.
- --answer AP-007 accept
- One command per answer: it writes your answer as a commit, signed with your key once you turn signing on.
- your signature
- Once you turn signing on, only your signed commit counts as an answer. A click, a merge or a line in chat is not an answer — four tiers, from a key anything on your account can use to one that needs your touch.
owed to the owner
## waiting for you: 0
## your acts, with their time: 0
Nothing overwritten.What you keep today stays where it is: shoalmark writes only its own files and never overwrites a file or a hook it did not write. Nothing ties you to it: the record stays in your repository, as plain Markdown and your own commits.
— versus —
Why not my issue tracker?
Ticket systems were built for people handing work to people. shoalmark is built for your agents: the work record lives in the repository they work in, and your answers are your own commits there.
If your current tracker already handles the handovers and decisions you need, that may be enough. shoalmark brings its own tracker; adopting it means deciding which record is the one that counts.
— co-op mode —
The fleet
A seat is a role an agent takes, with its duties and its rights written down.
The tool knows you, the Owner, and three seats with their rights built in — planner ask · close · triage, reviewer triage, builder none. Four rights, each a front-matter transition the gate sees in a diff; anything else is open to every seat.
Planner
the skipper
turns your direction into trackers, and puts the agents' open questions to you, one sentence each.
Builder
the shipwright
builds one change from its tracker, in a worktree of its own, and never accepts its own work.
Reviewer
the inspector
reads a branch against its tracker and writes READY, or what must change. It never merges.
Specialists
(customizable)
called in when the work needs them. Name your own in
[seats], with the rights[rights]gives them.
A seat's charter — how it thinks, a bold Planner against a steady one — is <tracker dir>/seats/<name>.md, read by the agent at start, never by the gate.
— measured, not promised —
High scores
In shoalmark's own repository, which runs on shoalmark.
pull requests with a reviewer's file when opened
| rank | score | period |
|---|---|---|
| 1st | 78/94 | after the rulepull requests 47–159, from the Owner's signed answer of 24 September 2026, 11:07 CEST, to 12 October 2026, when review commits replaced review files |
| 2nd | 10/37 | before itpull requests 1–43, before the Owner's signed answer of 24 September 2026, 11:07 CEST |
Read when the site was built, on 21 October 2026, from pull requests 1–159 of shoalmark/shoalmark: merged ones only, without the Owner's own answer branches. One counts when a commit adding or changing a file under work-tracker/evidence/reviews/, merge commits excluded, is dated before the pull request was opened. Pull requests after 12 October 2026 are reviewed by commit and are not counted here.
game over — the repository it came from
200 pull requests merged in 22 days. 85 % less than a minute after opening. None with a review.
Asked what slows them most, three agents, run separately, gave the same answer, by a wide margin: the Owner's unanswered questions — one question, open three days, held three packages.
Blocking and stamping have one root: a person asked for many small decisions in the middle of the work.
— the wreck register —
Every filed defect, on the chart
| tracker | incident | filed | status | report | chart |
|---|
Titles and reports are the trackers' own words, in English.
— insert coin —
Your agents set it up
What it needs: Python 3.9 or newer and a Git or Subversion repository; your project can be in any language. No dependencies, and no server, database or account of its own. The tool is one Python file: your repository keeps a pinned copy, every file with its checksum, and it never updates itself.
In this beta:
- Not a migration tool: it imports no ticket system and starts from your repository's own work. A path for a fleet that already runs a system of its own is filed, not built.
- For one person in charge and their agent fleet. Several people in charge are not tested in this beta; support for them may come later.
- Not proof that work is right. In Git or Subversion changes being checked, a move to
Shippedmust name in its ship log a commit already in that change's history that changes something outside the records (on Subversion, a revision). This evidence rule does not coverClosed. Validation reports a violation and exits non-zero. An installed Git commit hook can refuse the commit on that failure, but is optional and can be skipped. To enforce the check before merge, require a passing--checkon the branch through your project's CI and merge rules; shoalmark does not set those up for you. Whether that commit did the job is what a review is for. - Made and tested on
gitwith GitHub. Subversion passes the test suite but has not been used in real work: try it, without a guarantee. On Subversion it runs withoutgitinstalled, from the release archive, and each run says what it cannot verify there: commit signatures and server-authenticated authors. Signed answers need agitrepository, and the pull-request queue agitrepository on GitHub and GitHub's command line,gh.
- They fetch shoalmark at a release tag and put a pinned copy in the repository, every file with its checksum (
--vendor). --initwrites the configuration, the triage file and the agents' contract.- The agents read the contract and file the work: one Markdown file per work item.
- You write three lines in your own words: what the repository is for, what is true when it works, what nobody may do to get there. Then you set up your signature, once.
One sitting, at the time you choosefifteen minutes by default; the board's first lines are its agenda.
One command per answer--answer AP-007 accept writes your answer as a commit, signed with your key once you turn signing on.
The rest is on the boardyour agents are asked to end each session with what waits for you, and the board puts it first.
▶ 2PYou, the OwnerSet up in ten minutes · Your answer is your commit · The standup
▶ 1PYour project's agentsThe note for trying it (Deutsch): a measurement, not an instruction. They report to you at the end, and you decide.
▶ 1PAn agent at workThe contract is
tools/shoalmark/README.md in your repository, rendered here. llms.txt is at the site's root.Tried it? Tell us what your agent found, even "no fit": one line here. The prompt never asks your agent to post.
python 3.9 or newer, no dependencies · no server, database or account of its own · one markdown file per work item · no lock-in: it all stays in your repo · ids you can say out loud · one python file · checks with
--check · made and tested on git · windows, macos and linux · apache-2.0 or mit ·