Enough Tool

I love Linear. Genuinely. It’s one of the few tools in this space that was clearly built by people who actually write software. The keyboard shortcuts work. The issue model makes sense. The UI doesn’t get in your way.

Jira can go fuck itself.

But even a great tool is wrong in the wrong circumstances. I’m a solo dev. My daily work doesn’t need a sprint board, a roadmap view, or a place to manage other people. The non-code work lives elsewhere — that’s a company problem, not a terminal problem. What I needed was something to answer one question, reliably, at any given moment:

What am I doing right now, and what happened to the thing I was doing before?

That sounds simple. It wasn’t.

My head’s been a bit foggy lately. Nothing dramatic — just the kind of cloudy where context doesn’t stick the way it used to. Which turned the Monday morning problem into a Monday, Tuesday, Wednesday, Thursday, Friday problem.

You probably know the feeling even without the fog. You left something in-progress. You close the laptop. You come back. And now half the time you’re not even coding yet — you’re trying to remember what you’d already figured out, what you’d already ruled out, just to get back to the place you were at on Friday. Every day. Before anything real starts.

Nothing was getting lost. The issue was that nothing had a record of ownership transitions. “In progress” meant “I touched this at some point.” No claim timestamp. No close event. No trail.

Here’s what I didn’t fully realize until I started writing issues for AI agents: the detailed format wasn’t just for them.

To get an agent to work without hallucinating or going sideways, you have to write the issue properly. Context. Objective. Constraints. Acceptance criteria. Turns out, writing clearly enough for an agent to follow is also writing clearly enough for you to pick up three days later with zero context in your head. The issue file becomes externalized memory — not a ticket, not a todo item, but a complete enough description that whoever reads it next doesn’t have to reconstruct anything.

Claim a task: commit. Close it: commit. Come back on Tuesday morning and the state is still there.

The agent piece extended this in a direction I didn’t anticipate.

I started handing work to Claude Code. The silent failure wasn’t bad output — it was two agents picking up the same task, or one abandoning something mid-session with no record it was ever started. Same problem, except now it’s two agents stepping on each other at 3am.

Lease-based claiming fixed it. Agents claim tasks with a TTL. If the lease expires without a close or release, ./task doctor puts it back to open automatically. The claim is in git. The expiry is in git. The next agent — or me — picks it up with full context of what happened.

Humans don’t need a TTL. But we use the same primitives. Same ledger. Same commit on every transition.

The ingestion piece is smaller, but it changed my daily rhythm more than I expected.

I take notes in meetings — one-liners, half-thoughts, things that only make sense because I was in the room. After the meeting, the scratchpad looks something like this:

- pix endpoint missing, check api docs
- nav should be cms-driven, ask about payload collections
- something wrong with mobile checkout, safari maybe?
- follow up on audit timeline

./task ingest reads that, calls the API for each bullet, and either scaffolds a full structured issue or flags it as a question if it can’t determine scope. Ambiguous lines get a single clarifying prompt.

The first few issues it drafts are usually too vague to use directly — that’s a prompt tuning problem, not a structure problem — but they exist, and they have the right shape, which is more than the notes file ever managed. I do a review pass, fix what needs fixing, and move on.

Thirty seconds versus never.

Now the honest part.

This is not bulletproof. At all.

No git repo: crashes. No Bun: crashes. No ANTHROPIC_API_KEY: task ingest crashes. The error handling is minimal. The edge cases are probably not covered. I didn’t try to make this robust — I tried to make it enough.

It’s a single TypeScript file with a shebang. No node_modules. No build step. No install beyond chmod +x. Fork it, rewrite it in Go or Bash or whatever you actually think in — I’m not attached to the language, and I’m definitely not attached to the idea. These are markdown files and a YAML ledger. The concept isn’t novel. The implementation is barely held together.

But it’s enough tool for what I need.