stubthing
A kind · a reason · an end date
Notes that clean up after themselves.
Every agent session leaves a markdown file behind, and nothing ever removes one. stubthing keeps the notes about the work out of the repos: each has a kind, a reason to exist and a date it ends, and agents write through tools that refuse anything else.
Act I
Every repo, its own pile.
Plans, handoffs, checklists, TODOs. Each one is written in a minute, true for a day, and kept forever, because nothing says when it ends.
01 · One repo
A README, and then the rest.
Twelve files in one infrastructure repo. Which of them is still true? Opening each one is the only way to know.
02 · Every session
Every agent leaves one more.
An agent ends its session with a handoff, so the next one can pick up. The next one writes its own. None of them deletes the last.
03 · A week later
The handoff still says next.
The next step was done three weeks ago. The file still asks for it, and the next agent reads it and believes it.
04 · And the phone
Plus the list on your phone.
Ideas, questions, half-done tasks, in a notes app no agent can read and no repo knows about. Which are done? Nobody can say.
That was one week.
- markdown files
- 4
- out of date
- 2
- lost track of
- 3
- notes with an end date
- 0
Here's the same week, in stubthing.
Act II
The stubthing way.
A repo keeps one markdown file, its README, and the why of its code lives in the code. Everything with a lifecycle lives here.
01 · A kind for everything
Every note says what it is.
Task, question, decision, handoff, idea or doc. Each kind has its fields, and every field has a limit. Anything that doesn't fit is refused, never cleaned up.
02 · The tools are the rules
Agents write through tools that say no.
An agent sees one tool per kind, with the limits in its schema. Too long, a field missing, a kind it may not write: refused, with the reason, so it fixes the note and tries again.
03 · A handle that survives
A note is a UUID, not a file path.
Code, commits and pull requests name a note as stub:<uuid>. Move the code, rename the repo: grep still finds it from either side.
04 · Nothing stays by accident
Every note ends.
Handoffs live a week, tasks three months, docs a year. When the date passes the note is archived: out of sight, never deleted. Keeping one is a choice you make.
Act III
What every note carries.
Three questions a markdown file never has to answer. stubthing doesn't accept a note until it does.
-
1
What it is
A kind, with its own fields and limits, and a title. A plan is a set of tasks; a handoff names its branch and its next step.
-
2
Why it's kept
A purpose in under 200 characters, written when the note is. A note that can't say why it exists doesn't get to.
-
3
When it ends
A date, from the kind's lifetime, that a writer may bring closer but never push back. After it, the archive.
| Measure | Markdown in the repo | stubthing |
|---|---|---|
| Shape | whatever was typed | a kind, with limits |
| Why it exists | unknown | required, on every note |
| When it goes | never | a date, then the archive |
| What an agent may write | anything, anywhere | its kinds, its repos, its token |
Drowning in PLAN.md?
Tell me what your agents leave behind. stubthing is where every project here will keep its notes.