Building with brainstorms, specs, and Beads

I had the privilege of starting a new job recently, and I kicked it off with what felt like hundreds of conversations with new folks about the state of the industry and the latest in tooling.

Whether talking to AI skeptics, extreme power users, or anyone in between, every conversation would drift into the same territory:

“What tools are you using? What is your process?”

It was fantastic that I could point people over to my mega brain-dump of my latest AI tooling setup, and that post has been surprisingly well-received. (Thanks everyone who has taken the time to read and share!)

But I realized I missed a big piece of the puzzle in my last post: I failed to give clear examples of how I use my tools.

This post talks about how I use spec-driven development (mainly via my own brainstorm skill), the Beads tool, and some simple context-management tricks to break huge projects down into pieces and run agents for hours at a time until the job is finished.

Below, I’ll answer in gory detail what I do and how I got there, but if you only have two minutes to read, here are the cliff notes:

1. I describe to Codex what I want to build, and tell it to use my brainstorm skill to help me tease out assumptions and produce a detailed spec.
2. I then tell Codex to write the spec to a markdown file. This includes the context leading to the spec, a detailed description of the solution, acceptance criteria, and lots more.
3. I run my beads-create skill to break the plan down into tasks. It creates an epic (for example, proj-123) and subtasks (proj-123.1, proj-123.2, etc.), each tying back to the spec, and each with dependencies (blockers, sequencing) specified.
4. I start a brand-new Codex session and simply say “beads-implement proj-123”. At this point, I can usually walk away for a while. Codex will spin up subagents to implement, make commits and close beads with detailed implementation details, and generally stay on task until the project is done. You can also tell it to stack PRs with Graphite, run code review in subagents, or otherwise splice in other steps.

With this flow, I’ve managed to write well over a million lines of code in the past few months. This includes launching a brand new hobby website, building out a skills library, creating AI tools, contributing to OSS libraries, writing several blog posts, and so much more in between.

What is spec-driven development?

Let’s start by talking about how to get the right kind of context to your agents.

Agents adhere to “garbage in, garbage out.” Conversely, agents can perform pure magic when given the right instructions.

Spec-driven development is the philosophy of providing the right kind of context to agents (and humans).

At a high level, it really comes down to two principles:

1. Separate planning from execution. Front-load the planning. Sweat the details.
2. Produce a spec and persist it somewhere accessible to agents so they can implement it.

There are plenty of ways to do this. Built-in plan mode is the obvious starting point, and for a lot of people, it’s good enough.

I use my brainstorm skill instead because it fits my workflow better and produces more consistent specs.

Sometimes, for really large or fuzzy problems, I’ll start with ChatGPT Deep Research, then feed that output into brainstorm.

There are more structured systems for spec generation such as Spec Kit or OpenSpec, but I usually find them more complicated than the job requires.

The main takeaway here is that you should leverage whatever tool works best for you and your environment to capture the requirements in great detail.

What are Beads?

If you’ve never heard about Beads, I’ll catch you up. If you’ve heard about Beads but you haven’t read about it in a while, it’s probably worth a refresher. In either case, allow me to be your guide.

On its surface, Beads is task tracking like Jira or Linear for agents. But it’s more fundamental than that:

Beads carries context between agentic sessions.

As I touched on in my last post, this plays an important role in coordinating multiple agents, whether they’re working in parallel or across multiple related sessions.

Beads → Installation

If you want to install Beads, you need three pieces:

1. Install Beads from npm or brew. See instructions from the official package.
2. Install the beads plugin/skill. Using npx skills add steveyegge/beads is the easiest way to install this for Codex, Claude Code, Cursor, or any other harness.
3. Also install beads-create and beads-implement from my custom skills repo: npx skills add btraut/skills. I explain how to use these below.

Agents use Beads via the bd CLI app. Installation takes seconds, and agents are generally pretty good at using it out of the box. The skills help supercharge its use in your workflow.

> A quick note to folks who first read about Beads in Steve Yegge’s Welcome to Gas Town: Yegge originally admitted that Beads was haphazardly vibe-coded, complete with instability and bugs to match. Since that post, more than 500 contributors have put up more than 2,500 PRs to improve Beads and Gas Town, and both have transformed into mature tools with tons of support.

Beads → Usage

When you choose to build anything of significant complexity, you’ll get the best results by leveraging more than one agent to split up responsibilities. However, you’re then left with the challenge of passing context from one session to the next. By using Beads and associated skills, this context management becomes trivial.

The basic use case for Beads looks like this:

1. Take a series of tasks, often originating from a project spec, and break it into individual units of work (aka: beads).
2. Ask a new agent to implement the beads using subagents.

When I use Beads, I’m never actually the one interacting with them. Beads belong to the agents. It’s not a task backlog or wish list for my projects, nor is it shared with teammates. Beads has fancier modes, but I’ve never found them as useful as basic single-player usage.

Get Brent Traut’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Part of the value of Beads is how little ceremony it needs; let the agents queue up work, then let other agents execute it.

A practical end-to-end example

Let’s take a look at how I pull all these concepts together to create a new feature.

Example → Brainstorming

My prompts usually start with something like this:

Performance is becoming a problem on my API calls. Let's $brainstorm
how we may implement instrumentation to identify bottlenecks.

Codex will then spend a few minutes reading docs, code, and server logs. When it has the full picture, it’ll start asking me questions.

I scanned the API: it already boots telemetry in apps/api/src/main.ts,
but the shared setup in packages/telemetry/src/index.ts just exports
spans and metrics to the console, and the request middleware in
apps/api/src/app.ts logs method/path without latency, route templates,
DB timing, or downstream call breakdown. So the first decision is the
sink, because instrumentation with nowhere useful to look is just
expensive noise.

Which target do you want first?
1. OTLP traces + metrics to something like Grafana/Tempo/Datadog
   (Recommended) - best for finding real bottlenecks across requests,
   SQL, Redis, and external APIs.
2. Sentry Performance - quickest if you want one vendor and decent
   tracing with less setup.
3. Pino timing fields only - simple and cheap, but pretty blunt.
4. Local profiling only - useful for dev hotspots, weak for production
   bottlenecks.
5. Other: _

When the brainstorm skill asks you questions, you don’t need to feel the pressure to answer directly. Sure, you can just respond “1” and move on, but you can also talk to it like any coworker: discuss your motivations behind the choice, pose alternatives, or even reject the premise outright if it doesn’t fit the plan.

One thing that may not be obvious at the onset of this process: Brainstorming with an agent often helps both the agent and me learn more about the project. It tends to ask questions about parts of the project that weren’t on my roadmap at all, and I’m left with a lot more confidence that the plan is comprehensive.

Example → Design Review

After navigating the barrage of questions from the agent, the brainstorm skill switches over to “design review.” In this mode, it breaks its understanding of the design into separate segments and feeds them to you a couple paragraphs at a time for easier consumption. You can either agree and move forward or you can iterate and refine.

I'm switching from questions to a concrete design. I'm assuming:
production-first OTLP, one shared telemetry implementation in
@manavault/telemetry, baseline coverage for every API request plus
Postgres/Redis/outbound HTTP, and minimal churn inside the API
itself.

Section 1: Instrumentation Architecture

The current shape is almost useful already, which is annoying in the
classic "90% done, 0% usable" way. The API initializes telemetry in
apps/api/src/main.ts, but packages/telemetry/src/index.ts only wires
console exporters. The first move is to turn that package into the
single real telemetry bootstrapper for all services: keep
initTelemetry, but make it choose OTLP exporters for traces and
metrics when enabled, with console export only as an explicit
local-debug fallback.

[a few paragraphs later]

Does this architecture look right so far?

And a few more sections like this:

Section 2: What To Measure And How To Keep It Useful

The failure mode here is collecting mountains of telemetry that
answer nothing. So I’d keep phase one brutally opinionated. For
metrics, expose a request-duration histogram.

[a few paragraphs later]

Does that sound right?

Example → Create Beads

After the final review, the brainstorm skill will tell you it’s ready to produce a spec.

What do you want next?

1. Create a concise implementation plan (Recommended) - turns this
   spec into concrete files, steps, and verification.
2. Create a single bead - good if you want to track it as one
   cohesive chunk of work.
3. Create an epic with milestone beads - better if you want plumbing,
   API shaping, and verification split apart.
4. Pause here - spec is done and ready to pick up later.

Here’s where I hand the project off to Beads.

Save the spec into the docs folder and $beads-create.

It’s all created for us.

The spec is saved at docs/work/2026–03–15-api-otel-instrumentation.md.

Beads are filed as an epic with clean child tasks:

- manavault-8y6 API OTLP instrumentation for bottleneck detection
- manavault-8y6.1 Build OTLP exporter and env plumbing
- manavault-8y6.2 Shape API request traces and route metrics
- manavault-8y6.3 Verify telemetry output and document operator usage

Dependencies are set the sane way: .2 depends on .1, and .3 depends
on both. No blockers surfaced.

The dependency graph specified by the agent matters a lot. It dictates whether certain steps can be implemented by subagents in parallel. Some projects lend themselves to lots of parallelism, and others must be implemented serially. In either case, both Beads and the beads-implement skill are good at routing subagents.

Example → Implementation

At this point, we can hand the work off to agents. However, it’s vital that we start a new agent session; the previous session has filled its context window with tons of exploration, skills and processes meant for creativity, and requirements gathering bloat. This was useful for producing a detailed spec, but not for implementing it.

A quick side note: One of the most important skills in the realm of agentic coding to learn is context management and knowing when to start a fresh session. For me, this took a lot of experimentation and reps to refine, but I can offer some high-level advice.

Each agent should have a very specific job, and when that job is complete, you should retire it. You can always return or have other agents review its transcript, but you don’t want to make one agent do another’s job, and you don’t want to incur the cost of compaction boundaries and context rot.

It’s finally time to implement the feature.

$beads-implement manavault-8y6

The beads-implement skill is meant to implement the specified beads end-to-end with little interruption. The implementing agent will do the following:

1. Read the beads epic and all subtasks as well as the associated spec
2. Choose an implementation sequence that includes parallelism where possible
3. Spawn subagents and assign each one of the beads
4. Wait for all subagents to implement, commit the code, close the bead, and pass a summary up to the parent
5. Close the epic
6. Produce a detailed summary of all the work

For simple projects, this is pretty quick. For complex projects, this can take hours. A major benefit of separating the parent agent from its subagent implementors is that the parent’s context takes a long time to fill, and thus, it can stay focused for a long time.

If you’d like to add additional steps to each phase of the build process, you simply need to ask. For instance, you may wish to put up separate PRs for each commit, perform code reviews or testing between each step, or even pause for manual validation or steering.

Next Steps

It may feel like a lot, but imagine how long each of these steps would take if done manually. Imagine what you can now accomplish outside your skillset that would’ve been impossible before.

As always, I’ll leave you with a call to action:

Go try this on something real. Spec it. Break it down. Hand it off. Then come back and tell me where the process held up and where it fell apart.

And perhaps most importantly: Stay curious!

If this kind of systems-level thinking around agent workflows interests you, I write and build in public.

Follow along on X: https://x.com/btraut

Or check out what I’m shipping on GitHub: https://github.com/btraut