Briefs as Code

I’ve argued before that your PM tool was designed for humans and that product engineering is the new superpower. Briefs-as-code is the tooling that lets a single person do both jobs: the engineer writes the architecture, the agent produces the exec brief.

The Problem with Planning Artifacts

Strategic planning lives in at least four places: Miro boards, Linear projects, Confluence pages, and someone’s PowerPoint deck from last quarter. The exec reads a stale version of one. The engineer reads a different stale version of another. Nobody is looking at the same thing.

The artifacts that matter most to leadership (delivery briefs, Gantt charts, exec summaries) are the ones with the worst tooling. They’re manually produced in PowerPoint by a PM who context-switches between 6 workstreams. They go stale the day after the steering committee meeting. They’re not diffable, not version-controlled, and not connected to the source of truth.

Meanwhile, the source of truth (architecture docs, meeting notes, API specs, codebase, live infrastructure state) sits in git repos, Linear boards, and running clusters reachable from the CLI. The information exists. It’s just not in a form anyone with 3 minutes can consume.

The Technique: Briefs as Code

The fix is simple and possibly obvious: put everything in one repo. Structured markdown. AI agents synthesize it. Polished HTML comes out.

Here’s the shape:

docs/
  landscape.md         # what we have today
  north-star.md        # where we're heading
  roadmap.md           # what's in flight
  in-flight.html       # Gantt chart (standalone HTML)
  workstreams/
    platform/          # architecture, principles, diagrams, brief
    product-a/         # architecture, API specs, delivery plan
    product-b/         # architecture, meeting notes, brief
    ...

Each workstream has a README with structured planning content: current state, target, phases, risks, team. The deeper workstreams also have architecture.md, D2 diagrams, API specs, and meeting notes.

The consumable output is brief.html: a hand-crafted, print-ready delivery document that answers six questions in one page:

• What are we doing and why
• Where are we (status bar: 4 metrics at a glance)
• What are the tracks (card grid with status pills)
• When (timeline with milestones and dependencies)
• What do we need (numbered asks with owner tags)
• What could go wrong (risk cards with mitigations)

How the Agents Fit

The AI agent isn’t writing strategy. It’s doing the synthesis work that humans skip because it’s tedious:

• Exploration: read Miro boards, Linear projects, git repos, even CLI tooling to inspect running infrastructure and understand current state. The Miro ingestion runs through a plugin from my claude-tools marketplace, which turns sticky-note chaos into structured markdown the rest of the pipeline can consume.
• Consolidation: pull planning content from scattered sources (Miro boards, PowerPoint decks, Confluence pages, meeting transcripts) into one canonical location. Sanitize as you go. Track what moved so the originals can be archived.
• Generation: /brief platform reads the workstream’s README, architecture doc, and principles, then produces a polished HTML delivery brief following the template
• Maintenance: architecture diagrams live as D2 source files next to the markdown. A post-edit hook pipes them through the D2 CLI to SVG whenever the source changes (with a freshness check so unchanged diagrams don’t re-render). Same pattern for the brief HTML itself: edit the markdown, the export regenerates.

The agent does in one session what would take a PM a week of context-gathering. And the output is diffable: when priorities change, git diff shows exactly what shifted.

One Source, Many Consumers

The obvious-in-hindsight thing: this format is native to agents too.

When I open Claude Code in the repo, the agent doesn’t need a briefing. It reads the workstream README, the architecture doc, the D2 diagrams, the meeting notes. The same structured markdown that feeds the brief template feeds the agent’s context.

One source, three consumers:

• Executives read brief.html: polished, one page, print-ready
• Engineers and product owners read the workstream README: current state, phases, team, decisions
• Agents read everything, and can now write code, regenerate diagrams, or produce the next brief with full context

No context-loading ceremony. No separate summary doc for the bot. Your AGENTS.md is already a liability; don’t stack another one. The plan IS the agent’s context, and every future task starts with the agent already oriented.

The application logic of the software is being defined and edited as markdown, and the actual code that is generated by the agent is sort of becoming a low-level implementation detail.

— Hartley Brody

That’s the broader 2026 shift: llms.txt, AGENTS.md under the Linux Foundation, Cloudflare’s Markdown for Agents. Briefs-as-code applies the same pattern one level up, at the planning layer.

Capex vs Opex: Making Invisible Work Visible

One thing that fell out naturally: tagging workstreams as capex (funded project, dedicated team, deadline) or opex (done alongside capex work, no budget, same people).

This distinction matters because opex work (tech debt, resilience, migrations, performance, observability) is the stuff that prevents the next incident but has no project sponsor. It competes for the same engineers’ time as the funded projects. Making it visible in the same repo, with the same brief format, forces the conversation: “this work has no budget protection, and the risk of not doing it is the next production incident.”

The cost of not doing opex work is invisible until the incident. The brief makes it visible before the incident.

In a Gantt chart, capex bars are blue (committed). Opex bars are gold (alongside, not committed). The visual distinction is immediate: leadership can see at a glance which work has budget behind it and which is riding on borrowed time.

What This Replaces

This isn’t replacing Jira or Linear. Those still track tickets. It’s replacing the layer above: the strategic planning artifacts that connect “what are we building” to “why does this matter.”

• Confluence pages that go stale because updating them is a chore. Markdown in git updates naturally because the architecture docs ARE the source.
• PowerPoint decks produced for steering committees. The brief is better: it’s one page, it prints on A4, it has a consistent design system, and it regenerates from current data.
• Miro boards as the canonical roadmap. Miro is great for brainstorming. It’s terrible as a system of record. The board becomes an input to the repo, not the other way around.
• Verbal status updates in meetings. The brief exists. Read it. If you have questions, they’re better questions because you’ve read the brief first.

This is Amazon’s six-pager principle applied to platform planning, except the six-pager writes itself from the architecture docs you’re already maintaining.

Try It

The technique is straightforward enough to try on any multi-workstream project:

1. One repo with docs/workstreams/ for each initiative
2. Structured README per workstream: type (capex/opex), timeline, status, current state, target, phases
3. A brief template: shared CSS with components for status bars, cards, timelines, risks, team grids
4. An AI skill (/brief) that reads the workstream docs and generates brief.html
5. D2 for diagrams: text-based diagram source committed alongside the markdown, compiled to SVG via the D2 CLI
6. Post-edit hooks that regenerate HTML exports and re-render D2 diagrams when their sources change

The hard part isn’t the tooling. It’s the discipline of keeping the markdown current. But that’s easier than keeping a Confluence page current, because the markdown is in the same repo as the architecture decisions. You update the plan and the brief follows.

The repo is the PM tool. The brief is an artifact, not a ceremony. And the tech leader stays in flow.