In the last post I talked about separating creative thinking from analytical building — using AI as a bridge between the two. A brainstorm becomes a structured brief, the brief becomes buildable work. That part clicked fast.
What took me longer to figure out was where that work should live.
Longer than I'd like to admit, honestly.
The Folder Trap
If you've used AI coding tools for more than a week, you've probably built some version of this: a folder inside your project — maybe .claude/, maybe docs/ai/, maybe planning/ — stuffed with constitution files, phase definitions, workflow state, decision logs, and whatever else your AI agent needs to stay on track.
I did exactly this. It felt natural. The project is in the repo, the orchestration lives next to the project. Everything in one place.
It felt right.
It works right up until it doesn't.
Here's what happened to me. I had three things in flight — a plugin, a feature for a client project, and a side product I was scoping. Each had its own set of planning artifacts. Each was at a different stage. I'd open a folder, read through the state files, try to remember where I'd left off, reconstruct context from a mix of markdown docs and half-finished notes. Then I'd do the same for the next one.
I was spending cognitive budget on figuring out where things stood instead of moving them forward. The orchestration layer — the thing that was supposed to help me build faster — had become overhead.
Overhead, not progress.
The Question I Couldn't Answer
The frustration crystallized one afternoon when I realized I couldn't answer a simple question: what are the three most important things I should work on this week?
Not because I didn't know. Because the answer was scattered across repo folders. There was no single surface where I could see everything, compare priorities, and decide what to tackle next.
I'd been a developer for 20 years. I'd spent most of those years working with ticket boards — Jira, Azure DevOps, whatever the shop used. And for 20 years, that board was how I thought about work. Not as files in a directory. As cards on a surface I could scan, sort, drag, and reprioritize in seconds.
Which is embarrassing, honestly.
I'd accidentally abandoned the tool that matched how my brain actually organizes work — and replaced it with something worse, just because it was closer to the code.
Closer to the code isn't always closer to the answer.
Externalizing the Source of Truth
So I moved everything out. Brainstorm artifacts, briefs, implementation plans — the project state stopped living in the repo and started living in a ticket system.
The mechanics were straightforward. I built a plugin pipeline with three commands:
Brainstorm — An exploration phase. No tickets, no commitments. The AI researches the codebase, identifies approaches, surfaces questions. The output is a structured brief saved locally. This is throwaway — it's a thinking artifact, not a source of truth.
Brief-to-Ticket — Takes that brief and creates real tickets. Analyzes it for gaps, asks clarifying questions, assesses scope, and creates stories (or an epic with child stories if the work breaks down into multiple pieces). Now the work exists outside the repo, on a board, with status and priority.
Start — Takes a ticket key, fetches the full context from the ticket system, transitions it to "In Progress," and runs the implementation workflow. When done, it pushes a PR and moves the ticket to the next status. The ticket is the record. The repo is just where the code happens.
The local artifacts my plugin creates during implementation — exploration notes, architecture proposals, review scores — those still exist in the repo. But they're ephemeral. Working memory, not long-term state. The moment the PR is up, the ticket tells the real story.
Here's what that actually looks like. This is a real ticket generated from a brief:
BRO-47: Implement worklog auto-generation from commit analysis
Status: To Do | Priority: Medium | Assignee: mariano
Description:
Auto-generate Jira worklog entries by analyzing git commit
history for the current ticket. Should infer time spent from
commit spacing and map commit messages to work descriptions.
Acceptance Criteria:
- Given a ticket key, analyze all commits referencing that ticket
- Generate draft worklog with time estimates
- Allow manual correction before submission
- Track correction patterns for future calibration
Scope: Single-repo, single-ticket (multi-repo is BRO-48)
Epic: Thoth Plugin SuiteThat's a ticket. Not a markdown file. Not a phase definition. A thing I can sort, prioritize, hand off to someone else — or to another AI agent — without explaining where the planning docs live.
Why the Board Changes Everything
The shift sounds like a tooling detail. It's not. It changed how I think about my work across projects.
With folders, I had depth but no width. I could dive into one project's state, but comparing across projects meant opening three repos and mentally assembling a picture. With a board, I open one surface and see everything: what's blocked, what's ready, what I've been ignoring.
Prioritization became a drag operation instead of a mental exercise. I could look at my week and decide — this ticket first, that one can wait, this other one is a good candidate to hand to an AI agent while I focus on the hard one. Parallel work across agents and my own hands became manageable because the coordination layer was visible.
I know that sounds minor. It isn't.
And there's a subtler benefit: tickets are a natural handoff surface. When a brief becomes a ticket, it carries structured context — problem statement, acceptance criteria, scope decisions. Any agent (or human teammate) can pick it up cold. You don't need to explain the folder structure or which markdown file has the latest state (versus "read the README in .claude/phases/phase-2.md and also check the decisions log"). The ticket is the context.
The Circular Dependency I Didn't See
Here's the thing I wish I'd seen earlier: keeping your orchestration state inside the repo creates a circular dependency. The AI agent needs context to work on the project, and that context lives inside the project it's working on. Every branch, every stash, every reset risks corrupting your workflow state along with your code.
This happened to me. Once. I rebased a branch and lost a week of planning artifacts that hadn't been committed to main yet. The code was fine — I'd pushed it. The brain was gone.
Externalizing to a ticket system breaks that coupling. The project state lives on a server you're not rebasing. The code stays clean — no planning artifacts in your tree, no merge conflicts on workflow files, no .gitignore entries for your AI's scratchpad.
It's the same principle behind not putting your CI config logic inside the application it builds. Separation of concerns, applied to how you manage work itself. Except this time I actually followed my own advice.
When It Breaks
This isn't a perfect system. I want to be clear about that before it sounds like a product pitch.
Ticket sprawl is real. It's easy to generate tickets faster than you can act on them. I've had weeks where my board had forty items and I'd mentally tune out the whole thing. If every brief becomes five tickets, you've just moved the noise from folders to cards. The board only works if you curate it.
Context loss happens. Tickets are great for "what" and "when." They're worse at "why." A good exploration document captures the reasoning, the rejected alternatives, the gut feeling that led to a decision. Tickets compress that into acceptance criteria. Sometimes you need the full picture.
You're coupling to a tool. If Jira goes down — or if I decide to switch to Linear — my project brain moves with it. That's a trade-off I'm accepting knowingly, but it's a real one.
I still keep working notes in the repo during implementation. The ticket is the record, but the exploration happens where the code is. The pattern isn't pure. It's practical.
The signal I watch for: if I'm spending more time managing tickets than doing the work they describe, I've over-indexed on the board. That's my cue to consolidate, not create more.
You Don't Need Jira
I use Jira because my day job runs on it and I wanted one board for everything. But this pattern works with anything that gives you a board, an API, and structured fields. GitHub Projects, Linear, YouTrack, even a well-structured Notion database.
The bar is low: the tool needs to hold your tickets with enough structure that an AI agent can read and write to them programmatically, and it needs to give you a visual surface to scan, sort, and prioritize. If it has both, it works.
The point isn't the tool. It's that your project's brain shouldn't live inside your project.
Where This Lands
The two-phase approach from the last post — creative brainstorm → structured brief → build — still holds. That's the cognitive pattern. What changed is the infrastructure underneath it.
The brief used to be the end product of the creative phase and the starting input for the build phase. Now it's an intermediate artifact. The brief gets analyzed, turned into tickets, and the tickets become the durable state. The brief can be thrown away once the tickets exist.
The pipeline is: think → capture → externalize → build. The first two steps happen in your head and in a conversation with AI. The third step moves it to a system designed for tracking work. The fourth step pulls from that system and executes.
I'm still iterating on the plugin that automates this. But the pattern itself is already how I work every day. If you've been running your orchestration from inside your repo — or if you've solved this a completely different way — I'd like to hear about it. The pattern works. But I'm still calibrating.
— Mariano, building at brolio.dev