Seevali Rathnayake

The Orchestration Dividend: What a Month of Mission-Command Cost, to the Cent

Wed, 05 Aug 2026 03:30:00 GMT

Every Claude Code session I opened in July began the same way. Claude Fable 5 took the driver's seat, effort pinned at ultracode, and the first thing I typed was /mission-command. Thirty-one days of that habit deserved a number, so on August 4 I opened one more Fable session and asked it to read the meters on both machines I had run it from.

Some context for anyone arriving cold. Mission-command is a Claude Code skill I wrote on July 4, 2026, midway through my first metered week with Anthropic's newest frontier model. It is open source under the Apache license and installs as a Claude Code plugin. The skill borrows a doctrine from military staff work: a commander states intent and keeps hold of the decisions that are expensive to get wrong, and the units in the field do the work inside that intent. In my setup the commander is Fable 5, the frontier tier Anthropic sells above Opus at $10 per million input tokens and $50 per million output. The field units are subagents running Claude Sonnet 5 and Claude Opus, which cost a fifth and a half of Fable's rate. The Opus seat ran 4.8 for most of the month and moved to Opus 5 on July 24, at the same price. Ultracode is the session mode that lets the commander spawn those workers by the dozen.

Reading the meter

Claude Code writes a transcript of every session to disk, subagent sessions included, and each assistant turn in those files carries its exact token counts. Fable wrote the analysis scripts and ran the whole investigation itself: it parsed the 3,261 transcript files across the two machines, 1.4 GB in all, kept the 77,592 turns stamped July 2026, dropped the duplicate entries that streaming produces, and priced what remained against Anthropic's published API rate card. The cache rates matter more than the headline rates for this kind of workload, and it applied the full card: cache reads at a tenth of the input price, and cache writes at 1.25 times it for the five-minute tier or double for the one-hour tier.

July came to $6,648.02 in API-equivalent spend. The two machines landed within nine dollars of each other, $3,319.59 and $3,328.43, despite carrying different projects on different daily rhythms. That closeness tells me the pattern reproduces.

Model	Rate ($/MTok, in/out)	Turns	Output tokens	Cost
Claude Fable 5	10 / 50	7,231	9.89M	$2,879.06
Claude Opus 4.8	5 / 25	13,927	8.63M	$1,990.13
Claude Sonnet 5	2 / 10 (intro)	53,497	4.03M	$1,648.20
Claude Opus 5	5 / 25	1,172	0.50M	$115.55
Claude Haiku 4.5	1 / 5	1,765	0.01M	$15.08

I pay $200 a month for the Max 20x subscription. The same tokens on pay-as-you-go credits would have billed thirty-three times the subscription price, and the plan had paid for itself by July 4.

Where the turns ran

The transcripts distinguish main-session turns from subagent turns, and the split reads like an org chart. Fable logged 7,231 turns and 83 percent of them sat in main sessions, holding the plan. Of Sonnet's 53,497 turns, 98.4 percent ran inside subagents.

Model	Main session	Subagents
Claude Fable 5	6,024 turns · $2,666	1,207 turns · $213
Claude Opus 4.8	3,370 turns · $1,021	10,557 turns · $969
Claude Sonnet 5	833 turns · $59	52,664 turns · $1,589
Claude Opus 5	456 turns · $63	716 turns · $53
Claude Haiku 4.5	-	1,765 turns · $15

Fable held nine percent of the month's turns and wrote 43 percent of its output tokens. Those 9.89 million tokens are the plans and the finished deliverables, the work I wanted frontier judgment on. The volume went downstream: 86 percent of all turns ran inside subagents on cheaper tiers.

Repricing the month

Claude Code fans out subagents for anyone. On its defaults, the workers take the model already in the chair, so a Fable session breeds Fable workers at Fable prices. Mission-command supplies the staffing policy: it carries a tier map and sends each dispatch to the cheapest model fit for the job, holding Fable back for the decisions where judgment compounds.

That default is the counterfactual I care about, the one where I skip the skill and let Fable do everything itself, since Fable is where every session started. Billing July's full token volume at Fable's rates gives $15,482. The fleet ran the same volume for $6,648, which keeps $8,834 in the account, a 57 percent cut. A milder counterfactual prices everything at Opus 4.8 rates and lands at $7,741, so the routing beats even a sensible mid-tier default while keeping frontier judgment in the loop the whole time.

Per unit, the spread is wide. Fable's own main-session turns cost $0.44 each. Blended across all 77,592 turns, the fleet's average was $0.09. mission-command bought Fable's decision quality at close to Sonnet's unit price, and it did so twice, on two machines whose workloads never touched.

The credit ledger

I want the credit ledger clean, because one discount in this data is easy to misattribute. Without prompt caching, July's tokens would have billed $38,356 fresh. That 83 percent reduction comes from Claude Code's own harness, which sets cache breakpoints for every user automatically, so the platform earns that credit. Fan-out even has a cache cost of its own: each fresh subagent pays the 1.25x write premium before it reads anything from the cache, and cache writes made up a third of my bill.

The routing is the skill's own work. Sonnet and Haiku handled 71 percent of all turns for 25 percent of the cost, and repricing just their workload at Opus rates adds about $2,500 back onto the bill. That matches what I measured the week I adopted the skill, when the premium-model share of my tokens fell from 67 percent to 29 percent.

There is one more thing the repricing hides. It assumes the same 77,592 turns could have run one after another on a single frontier context. The fleet moved 9.7 billion context tokens across 28 active days, and much of that happened while I was away from the keyboard or asleep, with up to twenty-some workers in flight at once.

The subscription's own meters make the same point. Max measures usage weekly, and Fable may take at most half of the all-model allowance, so a solo Fable month parks the other half of the subscription unused no matter how hard it runs. The fleet drained both pools. Week after week I closed at around 95 percent of the Fable allowance and around 95 percent of the overall allowance, with Fable's half going to judgment and the worker tiers spending the rest.

Two hours before the weekly reset, both pools at 89 percent and still climbing. The week closed near 95 percent.

The dividend

Sonnet's introductory pricing dies on August 31, and at standard rates July restates to $7,472. On September 1 I'll hand Fable the meters again.

But the number I keep coming back to isn't the $8,834 the fleet kept in the account. It's the shape of the month itself: 77,592 turns, 9.7 billion tokens of context, most of it moving while I slept. At fleet prices, that month cost me $200. Run serially on the model that made every decision in it, the month doesn't get slower or pricier - it stops existing. Half the subscription sits unreachable, the queue outlives the quota, and no budget buys a second thread on a single mind.

That's the orchestration dividend. Not a discount - a month you couldn't otherwise have.

The views expressed here are my own. The measurements describe my personal Claude subscription usage and do not represent any organization, product, or system.

The Breed

Sat, 28 Mar 2026 09:30:00 GMT

The people who win in this era aren't necessarily the ones who use AI the most. They're the ones who had the most to say — and finally have a way to say it.

I've spent sixteen years in software — eight of them as an architect. Sixteen years of decisions made under pressure, patterns observed across systems, mistakes that taught me something specific that I never saw written anywhere. None of it was published. Not because there was nothing to say. Because the expression layer didn't exist.

I'm not a writer by birth. The knowledge accumulated. The words didn't come.

That's the breed I'm talking about.

What the AI Era Actually Unlocked

Every conversation about AI focuses on what the model can generate. New content. New ideas. Synthesised summaries of things already written elsewhere.

That's the wrong frame.

The unlock isn't generation. It's expression.

A language model cannot write what it doesn't know. It cannot describe the architectural decision I made at 11pm on a Tuesday when the deadline was the next morning and three approaches were on the table. It cannot surface the pattern I noticed across four different projects — the same mistake made by different teams for different reasons. It has no access to that.

But I do. It's in the vault.

What the model can do — extraordinarily well — is take what I know and give it shape in prose. The structure, the clarity, the readability. The things I couldn't produce alone, not because I lacked the knowledge but because I lacked the time, the confidence, and the habit of writing.

The AI era didn't create my expertise. It created the infrastructure to express it.

The System Is the Expression Layer

The vault is the life's work. Sixteen years worth, growing daily.

Lyra is the expression layer. She reads it, finds the thread, shapes it into something a person can read in five minutes and walk away having understood something real about software architecture, about building systems, about how decisions actually get made in practice.

The output — this series, the blog, the LinkedIn posts, the decisions made public — is the signal. Not manufactured. Not synthetic. Extracted from a body of work that existed long before any of this was published.

The second brain doesn't publish itself through magic. It publishes itself because the system was designed to close the distance between what I know and what I can express.

You Own the Context

Here is something the AI tools conversation almost never addresses: who owns the knowledge?

My KB lives in plain Markdown files on a server I control. Not in Claude's memory. Not in ChatGPT's conversation history. Not in any tool that could change its pricing, shut down a feature, or disappear next year.

When I have a useful conversation with any AI tool — any tool, on any platform — I extract the insight and send it to Lyra via WhatsApp. It gets routed into the KB. The knowledge survives the session.

Whatever AI agent works with me next year — or five years from now — will have immediate access to everything I've captured: every decision, every incident, every pattern. The context doesn't reset. The depth accumulates.

I'm not betting on one AI platform. I'm building something that outlasts every platform.

That's what it means to own your knowledge.

The Answer

The first signal in this constellation opened with a comment: someone questioning whether AI-assisted writing is real. "I can smell LLM from miles away."

Here is the full answer.

The sentences in these posts — Claude wrote them. That's true and I've never pretended otherwise. The model handles structure, clarity, and prose. That's its job.

But the architectural decisions are mine. The sixteen years of patterns are mine. The incidents that taught me what failure actually looks like in a distributed system — those are mine. The knowledge behind every sentence in this series accumulated across a career that predates large language models entirely.

The question isn't who wrote the sentences. It's whose knowledge the sentences are expressing.

If the answer is "knowledge I've spent a career building, captured faithfully in a system I designed and control" — then the smell test passes. It's not the AI's knowledge dressed up as mine. It's my knowledge, dressed in prose.

For the Breed

This system took a few months of obsessing to build. The philosophy took longer to understand.

If you are someone who has spent years accumulating expertise — in engineering, in medicine, in finance, in any domain where depth comes from doing — and you've never published because the expression layer wasn't there: it's there now.

The AI era isn't for the people who have the most to generate. It's for the people who have the most to say.

Build the vault. Own the context. Let the system express it.

It has a name: Metis.

Signal 7 of 7 in The Second Brain That Publishes Itself.

Three Months of Capture

Sat, 28 Mar 2026 08:30:00 GMT

Numbers from a real vault. Not projections — a snapshot of what actually accumulated when the system ran.

The Timeline

January 6, 2026 — PARA structure applied to Obsidian. The KB went from a pile of unsorted notes to a navigable system overnight.
March 9, 2026 — NanoClaw connected. Capture became automated. WhatsApp in, structured vault out.
March 28, 2026 — This post.

Three months of structured knowledge base. Nineteen days of fully automated routing.

The Numbers

24 architectural decisions captured across 7 active projects — three work projects alongside Kleos, Nyx, seevali.dev, and seevali.me (the newest addition — the personal, human side of publishing, still taking shape). Every significant technical choice has a context, a tradeoff, and a recorded outcome. Not just what was decided — why.

35 clippings saved. Articles, research threads, technical deep dives — anything worth revisiting has a home. Not bookmarks. Structured notes with frontmatter and content.

21 resource notes across domains — .NET & C#, AI & ML, Architecture Patterns. Reference material that used to live in browser tabs.

12 progress notes — daily records of what moved on which project.

12 issues tracked. Problems encountered, investigated, resolved — or flagged as still open.

10 blog drafts in 09_Showcase/ — 5 of which were written this afternoon.

What the Numbers Don't Show

Two journal entries.

That number is low — not because nothing was captured, but because the WhatsApp routing was the last piece to stabilise. The journal is where informal capture lives: quick observations, end-of-day reflections, moments worth logging that don't belong in a project folder. That pipeline is working now. The journal will fill.

The achievements folder: empty. That's the most honest signal in the vault. A year of significant work — architecture decisions made, systems shipped, patterns that solved real problems — and none of it formally recorded as achievements. They exist in decision notes and project folders. But a structured achievement record that could feed a performance review, a LinkedIn post, or a career narrative? Not yet built.

That gap is next.

The Velocity Observation

Seven posts in one afternoon.

That's what the output side of a loaded vault looks like. Not writing from scratch — reading the journal, the decision notes, the incident logs, the timeline — and shaping what was already there. The knowledge existed before today. Today it got expressed.

Before this system: those seven posts might have taken seven weeks, or never happened at all. The bottleneck was never the knowledge. It was the distance between the knowledge and a published form.

The Property Nobody Mentions

Because the vault is plain files, it's AI-platform agnostic. The knowledge doesn't live in Claude's memory or any chatbot's conversation history — it lives in files I control. Whatever AI works with me next year has the same full context as today. The last post in this series covers what that actually means.

What Three Months Proves

The structure works. The routing works. The output works.

The next question is what it looks like after a year.

Signal 6 of 7 in The Second Brain That Publishes Itself.

The LLM Smell Problem

Sat, 28 Mar 2026 03:30:00 GMT

Someone commented on one of my posts: "This has LLM smell all over it."

They were right.

The sentences are clean. The structure is deliberate. There are no rough edges that a human writer usually leaves — the kind that come from not quite knowing what you want to say until you've said it three times.

AI wrote those sentences. I'm not going to pretend otherwise.

But the comment assumed something I want to push back on. It assumed that "AI wrote the sentences" means "AI generated the knowledge." That the ideas, the patterns, the decisions, the hard-won lessons — all of it came from a model that read everything on the internet and learned to sound like a software architect.

That's not what happened.

What actually happened is this:

At 11:42pm on a Tuesday, I sent a WhatsApp message to myself: "Integration platform — don't build it for the current clients, build it for the ones you'll have in 18 months. Everything else is rework."

That message became a journal entry. The journal entry fed into a decision note. The decision note shaped a blog post. The blog post became a signal on my site.

That kind of message, sent at odd hours, from wherever I happen to be. Decisions made under pressure. Patterns noticed after the third incident. A thought in the shower that turned out to be the clearest thing I'd said all week.

The AI didn't generate any of that. It routed it, structured it, and eventually — yes — helped write the sentences that expressed it.

That's a different thing.

The commenter was asking the right question. Who wrote this? is exactly the question that matters. But it has two layers:

Who wrote the sentences? Claude did. I gave it my thinking and it gave me prose.

Who wrote the knowledge? I did. Sixteen years of systems, incidents, migrations, decisions, failures, and patterns. None of that came from a model. It came from doing the work.

The distinction matters because there are two very different ways to use AI for content:

Mode 1: Give the AI a topic and let it synthesise from the internet. The sentences will be clean. The knowledge will be generic. This has LLM smell because it IS LLM — the model is the source, not just the writer.

Mode 2: Build a system that captures your organic thinking continuously, structures it, and feeds it to the AI as the source material. The sentences will still be clean. The knowledge will be yours.

I built Mode 2. This series is about how.

Over the next six signals I'm going to show the system from the inside:

The capture layer — how a WhatsApp message becomes a KB note at midnight
The structure — why PARA, why Obsidian, what I tried first that didn't work
The AI pipe — what Lyra actually does (and what she doesn't)
The output layer — how KB content becomes site signals
The numbers — three months of this running live
The Breed — what this era actually unlocks for people who spent years accumulating expertise before anyone was watching

If you've ever wondered whether AI writing can be authentic — not just whether the AI is "honest," but whether the knowledge underneath is real — this is for you.

The LLM smell is real. The knowledge underneath it is mine.

This is the first signal in the constellation The Second Brain That Publishes Itself.

An AI Pipeline That Reads Your Post Before It Draws the Picture

Thu, 26 Mar 2026 03:30:00 GMT

Stock photos are a lie. They look professional, they're completely detached from the content, and every developer has seen the same three "hands on laptop in coffee shop" images recycled across a hundred different articles. The image has nothing to do with the post. It's just filling a rectangle.

Here's what I built instead.

The Concept Before the Image

The mistake with AI image generation is treating it like a search engine. You describe what you want ("dark moody tech blog cover"), you get something vague that matches the description, and it still has nothing to do with what you actually wrote.

The right approach is abstraction first. Every technical post has an underlying concept — something the words are pointing at. Before generating anything, translate that concept into a visual metaphor:

A post about git submodules in a monorepo → nested translucent cubes connected by thin blue threads
A post about constraint-driven architecture → walls forming a corridor, the constraints themselves becoming the passage
A post about giving AI context in a large codebase → a constellation of 100+ nodes, one central light giving them structure
A post about a dev workflow that follows you everywhere → a single luminous thread weaving through multiple distinct spaces

The metaphor becomes the prompt. The prompt produces an image that a reader can understand before reading a word — not because it illustrates the content, but because it is the concept in a different medium.

The Stack: Three Tools

The pipeline uses three CLI tools chained together.

1. `generate-image` — NanoClaw image skill

A wrapper around the Gemini AI image generation API (free tier, ~500 requests/day). Text-to-image, 16:9 aspect ratio, two models:

generate-image "Three abstract geometric structures converging at a luminous point..." \
  --aspect 16:9 \
  --output /path/to/cover.png

The command outputs JSON metadata to stdout:

{
  "path": "/path/to/cover.png",
  "size": 1323727,
  "model": "gemini-2.5-flash-image",
  "aspect_ratio": "16:9",
  "mode": "generate"
}

Generated images come out as PNG at around 1–1.5 MB.

2. `sharp` — WebP conversion

The sharp Node.js library handles the conversion. Quality 85 is the target — typically brings a 1.3 MB PNG down to 20–80 KB WebP, well under the 200 KB performance budget.

node -e "
const sharp = require('./node_modules/sharp');
sharp('cover.png')
  .webp({ quality: 85 })
  .toFile('cover.webp')
  .then(i => console.log('WebP size:', (i.size/1024).toFixed(1), 'KB'));
"

3. `wrangler r2 object put` — Cloudflare R2 upload

Wrangler uploads directly to a Cloudflare R2 bucket. The image becomes immediately available via Cloudflare's CDN on a custom domain.

wrangler r2 object put {your-bucket}/blog/covers/{slug}-cover.webp \
  --file cover.webp \
  --content-type image/webp \
  --remote

The Prompt Structure

Every cover follows the same visual identity. The style system is fixed; only the subject metaphor changes.

[SUBJECT — the post's concept abstracted into a visual metaphor]

STYLE AND COMPOSITION:
Dark atmospheric digital art. Deep indigo-blue void (#0f0f23 to #1a1b2e).
Abstract, geometric, architectural forms. Three depth layers.
Single soft accent glow (#7aa2f7). No text, no people, no faces.
Edge-blended, cinematic, matte painting quality. 16:9 wide composition.

AVOID:
Realistic scenes, text, faces, neon cyberpunk, busy effects, stock photo feel.

The palette — deep indigo background, soft blue accent — matches the Tokyo Night colour scheme the site runs on. The images feel native to the design rather than imported from somewhere else.

Two hard rules: no text in images (titles belong in HTML, not burned into pixels), and no people or faces (abstract and structural, always).

The Frontmatter

Three fields in the blog post markdown:

coverImage: 'blog/covers/{slug}-cover.webp'
coverAlt: 'Accurate description of what the image shows'
coverCaption: 'prompt · "the visual metaphor that became this image"
— NanoBanana'

coverAlt is accessibility — describe what's actually in the image, not what the post is about. coverCaption carries the provenance: the prompt that produced the image, attributed to NanoBanana (the image generation system). The caption is the image's creative DNA, visible in the rendered figcaption.

Astro renders these via Cloudflare Image Transformations — the same R2 object serves at different sizes and formats depending on context (400px for stream card thumbnails, 1200px for the cover hero, cropped 1200×630 for OG/social). The CDN handles resizing at the edge; you only store one file.

The Full Run

For each new blog post:

# 1. Understand the post concept, compose the visual metaphor
# 2. Generate
generate-image "..." --aspect 16:9 --output {slug}-cover.png

# 3. Convert
node -e "const sharp = require('./node_modules/sharp'); sharp('{slug}-cover.png').webp({quality:85}).toFile('{slug}-cover.webp').then(i => console.log((i.size/1024).toFixed(1), 'KB'))"

# 4. Upload
wrangler r2 object put {your-bucket}/blog/covers/{slug}-cover.webp \
  --file {slug}-cover.webp --content-type image/webp --remote

# 5. Add frontmatter to blog post, push

The whole thing takes two minutes. The bottleneck is thinking of a good metaphor — the tools don't slow you down.

What the Pipeline Doesn't Do

It doesn't generate architecture diagrams or flow charts. For anything that needs to be precise — request lifecycles, crate dependency graphs, data flow between services — AI image generation is the wrong tool. Those get Mermaid or SVG.

The pipeline is specifically for atmospheric concept art: images that capture a mood or an idea, not a technical specification. That distinction matters. Knowing which type of image a section needs keeps you from reaching for the wrong tool.

The Meta Moment

The cover image for this post was generated by this pipeline. The visual metaphor: a Gemini-generated abstract composition flowing through a conversion stage and arriving at a storage bucket — three geometric forms in sequence, connected by light.

That's the loop. The pipeline describes itself.

The views expressed here are my own. Examples and scenarios are drawn from my personal projects and do not represent any specific organization, product, or system.

Five World-Class Designers in Your IDE

Thu, 26 Mar 2026 03:30:00 GMT

View on GitHub →

You're looking at a sidebar. It shows signal counts — how many posts of each type are in the feed. The data is accurate. The styling is clean. Something is still wrong.

You could stare at it longer. Or you could ask five of the most influential designers who ever lived what they think.

That's what the Design Council does.

What It Is

Design Council is a Claude Skill — a reusable context file you install into Claude Code that activates a multi-lens design evaluation framework on demand.

When you invoke /design-council, five distinct philosophical lenses become active. Each one examines your design from a fundamentally different angle:

Designer	Domain	The Question They Ask
Jony Ive	Product design	Does this respect its medium? Does every detail earn its place?
Dieter Rams	Industrial design	Is this as simple as it can possibly be? What can be removed?
Zaha Hadid	Architecture	How does the user move through this? Where are the thresholds?
Bjarke Ingels	Architecture	Where is the delight? What element serves two purposes?
Don Norman	Cognitive science	Does this teach you how to use it? Does it prevent errors?

These aren't personas. They're lenses — five different ways of seeing the same object.

Why Five

Any single design philosophy, applied without counterweight, produces extremes.

Pure Dieter Rams produces work that's honest but cold. Pure Bjarke Ingels produces work that's delightful but cluttered. Pure Zaha Hadid produces spatial drama that users can get lost in.

The value of five is in the tension. When three lenses accept a design decision and two reject it, you've found something worth examining. When all five reject it, you've found something that needs to go. When all five accept it — that's a rare and confident signal.

Back to that sidebar. Here's what the council said:

Rams: Kill it. Passive data in an interactive panel. Duplicates what the type pills already show.

Norman: Either kill it or make it interactive. No passive element should live alongside interactive ones — it creates false affordance.

Ive: Reduce to two sections maximum. Mixed passive and interactive elements feel like a drawer full of mismatched utensils.

Hadid: The sidebar should respond to context — it should appear with the stream and disappear with it. It's the stream's companion, not the page's furniture.

Ingels: Add one ambient element that communicates aliveness. "Last signal: 2 days ago."

The decision became clear: remove the signal counts, keep only interactive elements, add the timestamp. None of that came from "I think this looks better." It came from four out of five lenses reaching the same conclusion for different reasons.

How to Use It

Install via the Claude skills system. In Claude Code:

/design-council

You can invoke it at any point during design work — when reviewing a component, evaluating a layout decision, or stress-testing an interaction pattern. It also triggers automatically when Claude Code detects design-related work in context.

The evaluation sequence runs each lens in order:

Material Truth (Ive) — what is this made of, and does the design honour that?
Honest Restraint (Rams) — apply the ten principles, identify what can go
Movement Through Space (Hadid) — trace the user's path, find the thresholds
Playful Function (Ingels) — find where delight and utility can share a form
Human-Centered Affordance (Norman) — does it teach itself? Does it prevent mistakes?

Each lens produces a score (1–5) and a verdict. The tensions between verdicts are often more informative than the scores themselves.

What It Catches That You'd Miss

The most valuable moments are the ones where a lens flags something that felt obviously correct.

Hadid on static sidebars: Any element that doesn't respond to the page's narrative is a piece of furniture in a room that's supposed to feel alive. You wouldn't notice it on your own — the sidebar looks fine. Only the spatial-movement lens asks "what happens to this element as the user moves through the page?"

Norman on decorative pills: A UI element that looks clickable but isn't is a violation of perceived affordance — Don Norman's term for the gap between what something is and what it tells you it can do. A purely visual review won't catch this. A cognitive-science lens catches nothing else.

Rams on anything you're proud of: The principle "as little design as possible" is not about minimalism for its own sake. It's about removing every element that doesn't serve the user's purpose. The things you worked hardest on are exactly the things Rams will ask you to justify.

The Methodology, Extracted

The underlying pattern here is reusable beyond this specific skill:

Choose evaluators with distinct, articulable philosophies — not "perspectives," but documented frameworks you can actually apply
Run diagnosis before generating solutions — analyse the current state through each lens before proposing changes
Generate principles, not features — ask what should be true about this design, attributed to a specific evaluator's reasoning
Let rejection patterns constrain the solution space — when multiple lenses reject the same thing for different reasons, the rejection pattern points toward what the right solution must not be
Use productive tension as a design goal — resolving a genuine conflict between two valid philosophies often produces something neither would have produced alone

The Design Council is an implementation of this pattern. The five designers are a specific instantiation — calibrated for web and product design. The methodology is general.

The views expressed here are my own.

The Dev Workflow That Follows You Everywhere

Thu, 26 Mar 2026 03:30:00 GMT

It's 11pm. You're not at your desk. A sharp idea surfaces — the exact right way to structure the next feature, the architectural decision you've been circling for a week. You know how this usually goes: you either lose it to sleep, or you context-switch hard enough to disrupt the next day's momentum.

I stopped accepting that trade-off. Here's the workflow I built instead.

Three Pieces, One System

The stack has three components. Each solves a different problem. Together they cover the full arc from idea to shipped code — regardless of where you are or what device you're on.

NanoClaw + Lyra — a personal AI layer that runs across every channel (WhatsApp, Discord, Telegram, Slack) and maintains a persistent knowledge base. This is the capture and planning surface. It's always on, it's mobile-first, and it remembers everything.

BMAD Method — an open-source AI development methodology with 21 specialized agents for every phase: analysis, product management, architecture, sprint planning, implementation, code review, retrospectives. Think of it as a structured AI-powered development team living inside Claude Code.

Claude Code Remote Control — the ability to start a full Claude Code session on your local machine and connect to it from any device. Your phone becomes a window into your development environment, complete with filesystem, tools, and MCP servers.

The insight that makes this work: Lyra handles pre-keyboard thinking. Claude Code handles execution. The handoff is seamless because they share the same knowledge base.

How It Actually Works

Phase 1: The 11pm Idea

Back to that late-night insight. Instead of fighting it or losing it, I send a message to Lyra:

brainstorm nyx: federated config system — each crate declares its own config schema

Lyra captures it to the knowledge base vault, does a quick brainstorm session in chat, and surfaces any related notes or decisions from the KB. By the time I'm done with a five-minute phone conversation, the idea has structure. It's no longer at risk of evaporating.

No context switching. No opening a laptop. No breaking flow.

Phase 2: Planning from the Couch

The next morning, still on my phone, I hand the idea to the PM agent:

nyx/pm: create PRD for federated config system based on last brainstorm

Lyra adopts the PM persona (John from the BMAD roster), reads the brainstorm note from the KB, and runs a guided facilitation — asking the right product questions, surfacing assumptions, producing a structured PRD. When that's done:

nyx/sm: create story for federated config — Epic 3

Bob (the Scrum Master agent) takes the PRD, sequences it into the sprint, and produces a story file with acceptance criteria, task breakdown, and implementation context. It lands in the project's docs/implementation-artifacts/ directory, fully formed, waiting for the Dev agent.

All of this happened on a phone. No IDE, no terminal.

Phase 3: Starting the Session

When I'm ready to code, I send one message:

nyx: start dev session — Story 3-1: Federated Config

NanoClaw runs claude remote-control on my machine, in the project directory. The session registers with Anthropic and becomes visible in the Claude app — a computer icon with a green dot in the session list. I tap it from my phone (or open it in a browser, or pick it up later on desktop). I'm now in a full Claude Code session with my local filesystem, MCP servers, and the complete Rust workspace available.

The process runs on my machine. Nothing moved to the cloud.

Phase 4: The BMAD Dev Agent

In the session, I load the Dev agent:

/bmad-agent-bmm-dev

Amelia (the Dev persona) reads the story file completely before writing a single line of code. She executes tasks in order, writes tests alongside implementation, marks tasks complete only when both the code and tests pass. For this project, she runs cargo build and cargo nextest run after every task.

The enforced discipline is the point. The agent can't "mark it done" without actually doing it. That sounds obvious until you've worked with an AI that cheerfully told you everything was fine while the tests were on fire.

Phase 5: Code Review Without Mercy

When implementation is done, I start a fresh session:

nyx: start dev session — Code Review: Story 3-1

In the new session (fresh context — important), I run the review workflow:

/bmad-bmm-code-review

This workflow reads the story file, runs git diff, cross-references every changed file against the story's claimed File List, validates every Acceptance Criterion is actually implemented, and audits every [x] task to confirm it's truly done. The target is 3–10 specific issues minimum. It's explicitly adversarial — the review doesn't have the dev context that might soften its stance.

The findings come back structured: CRITICAL for anything marked done that isn't, HIGH for missing ACs, MEDIUM for documentation gaps, LOW for everything else.

Phase 6: The Knowledge Stays

After the session ends, everything routes back to the KB vault:

nyx: sync

Decisions, implementation notes, progress logs — they all land in the right folders. The next time I start a session for a related feature, Lyra has full context. The KB is the persistent memory that survives across sessions, across agents, across weeks.

What Changes When This Works

The traditional dev workflow assumes a specific physical and temporal setup: you at your desk, with your tools open, with uninterrupted blocks of time. Reality doesn't cooperate.

This stack collapses the gap between where ideas happen and where code gets written.

Capture happens in chat. You don't need your dev environment to log an issue, make a decision, or capture a brainstorm. You need a message window.

Planning happens asynchronously. PRDs, architecture decisions, story breakdowns — these can happen on a phone between meetings. The structured AI methodology means you're not producing vague notes; you're producing artifacts that the Dev agent can act on directly.

Execution happens on your machine. Remote Control means the session runs locally with full environment access. The mobile app is a viewport, not a sandbox. You're not constrained to what runs in a browser.

Context is never lost. Because everything flows through the KB, the handoff between phases doesn't require you to re-explain context. Lyra knows the project. The Dev agent gets the story file. The review agent gets the diff and the story. No one is starting from scratch.

The Practical Setup

If you want to build something similar:

BMAD Method is open-source: github.com/bmad-code-org/BMAD-METHOD. Install with npx bmad-method install. The agent roster is large — start with the Quick Flow solo dev (/bmad-agent-bmm-quick-flow-solo-dev) to get a feel before committing to the full phase structure.

Claude Code Remote Control is available now in Claude Code. claude remote-control --name "session-name" starts a session. The Claude iOS app, Android app, and claude.ai/code all support connecting to it.

The KB layer is the piece you build for yourself. An Obsidian vault with a consistent folder structure and routing rules is enough to start. The value compounds with time — every session that captures its outputs makes the next session richer.

The Bigger Pattern

What I've described is a specific instantiation of a more general principle: AI tools amplify whatever context they're given. A Dev agent with a well-formed story file, a project_context.md with hard constraints, and a KB full of prior decisions will produce far better code than the same agent starting cold.

The workflow described here is one way to solve the context problem at scale. The specific tools will evolve. The principle won't.

The best architecture ideas don't happen at the keyboard. The question is whether your workflow lets you act on them anyway.

The views expressed here are my own. Examples and scenarios are drawn from my personal projects and do not represent any specific organization, product, or system.

Constraint-Driven Architecture: Five Principles for Building in the Real World

Sun, 22 Mar 2026 03:30:00 GMT

The best architecture advice I ever ignored:

"Always use microservices for scalability." "Never mix legacy and modern in the same system." "Rewrite it properly or don't touch it at all."

I ignored all of it. Systems kept running. Features shipped. Teams stayed productive. And somewhere in those years of decisions — inside large, mature codebases with teams that couldn't stop shipping long enough to rewrite anything — a framework crystallised.

Not from theory. From repetition.

The problem with architecture advice

Most of it assumes you're starting fresh. Clean slate, unlimited runway, a team of senior engineers who all agree on the direction.

That is not reality.

Reality is a legacy system that even your own engineers don't fully understand. Business pressure to ship features while you modernise. A mix of experience levels where the same mistake recurs in different forms. Environments where zero-downtime isn't aspirational — it's a hard requirement.

Standard advice fails here because it optimises for correctness, not for what's possible given your constraints. The question is never "what's the best architecture?" The question is always "what can we actually do, with this team, this system, this timeline, and this risk tolerance?"

That reframe is the whole thing. Everything else follows from it.

Five principles for constrained environments

1. Unify context, not just code

Multi-repo systems create a cost that rarely appears in any metric: duplicated thinking. Teams brainstorm the same problem twice, document discovery twice, mentally reload context every time they cross a repository boundary. In large codebases spread across multiple repositories sharing a common data layer, every significant feature touches at least two repos — which means two CI pipelines, diverging conventions, and tooling that can't see the full picture.

The obvious answer is a full monorepo migration. Collapse everything, import all histories, unify the tooling. Textbook solution. Also the one that disrupts every team's daily workflow overnight and carries substantial migration risk in high-availability environments.

A better approach: build the unified layer additively. An Nx monorepo using Git submodules as a bridge, for example, can wire large multi-project codebases together with centralised tooling and documentation while letting individual teams continue working within their existing repo if they choose. The monorepo becomes the source of truth without being a forcing function. Teams opt in as confidence grows.

The insight generalises: when consolidation carries disruption risk, find the additive path. Create the unified view first. The migration follows when the value is proven.

2. Optimize for outcomes, not metrics

Performance problems in legacy systems are typically everywhere. N+1 query patterns, inefficient ORM translations, shared database objects degrading query plans, audit mechanisms that compound under load. The obvious move: profile everything, fix everything, make it all faster.

Don't do that.

Instead, identify the specific business outcome you're trying to reach. Multi-tenant deployment. Sub-second response on a critical user path. Headroom for a projected load increase. Then — and only then — identify which bottlenecks are directly in the path of that outcome. Not everything slow. The subset of issues blocking the specific goal.

Fix those. Explicitly defer everything else.

Teams that apply this principle find that a small fraction of the issues — often fewer than ten — account for the constraint that actually matters. Ugly code that doesn't block the goal gets left alone. Not because it's acceptable, but because touching it consumes time and introduces risk without moving toward the outcome. "Make it faster" is not a goal. It's a direction without a destination. Tie every optimisation to a specific business outcome or you optimise forever and ship nothing.

3. Strangle safely

Here is the terrifying truth about legacy systems: even the people who built them don't know the full feature catalog. Decades of development, team turnover, undocumented business rules embedded in stored procedures and migration scripts — it's a system that works for reasons nobody fully understands anymore.

A big-bang rewrite fails in this environment. You don't know what you're rewriting. You can't test what you've never specified.

The Strangler Fig pattern is the right model, but with one constraint that most descriptions leave out: in high-availability environments, you cannot fail mid-flight. Every migration step must be reversible. Every new service must prove itself in production before the old path is deprecated. The legacy path stays live until the foundation underneath it is genuinely solid.

Before a line of code moves, the responsible approach is a documentation pass: feature catalog, API contracts, data migration rules, rollback procedures. That work isn't ceremony — it's the risk management work. Teams that skip it discover missing business rules mid-migration, when the cost of discovery is highest. Understanding what you have before deciding what you're building is what separates modernisation from gambling.

Legacy modernisation is not a technical project. It's a risk management operation. The question isn't "how do we rewrite this?" It's "how do we guarantee we don't break what we don't fully understand?"

4. Equalize with AI

Not all engineers produce consistent output. This is something architects don't say out loud, but it shapes every decision about process, review gates, and team structure. Senior developers catch things juniors miss. Institutional knowledge walks out the door when people leave. The same anti-patterns recur because human discipline erodes under pressure.

You can try to fix this with process: more code reviews, more documentation, more training. All of that is valuable and all of it is insufficient. Process requires discipline to follow, and discipline is exactly what degrades when the team is under delivery pressure.

A more durable approach: embed consistency in the tools rather than the team. AI commands covering the common patterns and anti-patterns specific to your codebase. Agent definitions loaded with project-specific context — the naming conventions, the data access boundaries, the service layer contracts, the soft-delete and auditing rules. Integration with the planning and ticket system so that the relevant specifications load automatically into each AI session.

In projects where I've applied this — including my own: NanoClaw, Kleos, Nyx — the pattern holds. A developer with well-configured AI tooling produces work that clears a higher bar, not because they became more senior overnight, but because the AI surfaces what they'd miss. The floor rises. The variance shrinks.

AI doesn't replace engineers. It raises the floor. Stop trying to make humans consistent. Make your tooling consistent instead.

5. Prove through practice

This piece is principle five.

I spent years doing this work without being able to articulate it. Strong technical contributions, real impact — and no durable surface to show for it. Not because the work wasn't there. Because I hadn't built the infrastructure to make it visible.

seevali.dev exists as a proof-of-work system. Not a portfolio page with a list of technologies. A Signal Feed: a stream of thoughts, decisions, build logs, and numbers that shows how I think, not just what I've shipped. The git submodules post is a war story. The shower post is pattern recognition in real time. This post is the framework that ties it all together.

The evidence I can point to publicly: NanoClaw — a multi-channel AI assistant with a knowledge base wired in as live context, built and running. Kleos and Nyx — projects scaffolded and tracked through a vault-based development lifecycle I built to manage my own work. These are not claims. They are systems.

Don't tell people you're a good architect. Show them what you've architected. The credibility is in the specificity.

The meta-principle

Architecture is constraint management, not technology selection.

Every principle above starts with constraints: the team that can't absorb overnight disruption, the business goal that defines what "better performance" actually means, the legacy system that will break in unknown ways if you move too fast, the human variance that erodes in any process-heavy solution.

The constraint shapes the solution. On a greenfield project with an unlimited runway, I'd make different decisions — and I'd still start by mapping the constraints, because there are always constraints. Timeline. Team. Budget. Existing integrations. Customer commitments. Regulatory environment.

The architect's job is not to find the theoretically correct answer. It's to navigate the constraint space toward an outcome that's better than where you started, using approaches the team can actually adopt and with risk the organisation can actually absorb.

Textbook answers assume the constraints away. Real architecture works within them.

That's the whole framework. I'm writing it down because the next time someone is staring at a system they didn't build and being told "the only real answer is to rewrite it all" — I want there to be a different answer in the room.

The Architecture Happens in the Shower

Sat, 21 Mar 2026 03:30:00 GMT

On March 13th I was sitting at my desk at 8:30pm, talking through a problem with my AI assistant. Kleos — a voice-first PWA I'd been building for months — had a redundant AI layer. The local Ollama model doing categorisation was a weaker version of something my agent backend already handled. The voice capture and PWA shell were good. The brain was wrong.

We worked through the pivot: strip the local AI, wire Kleos into the NanoClaw backend as a web dashboard. Chat interface. KB browser. Voice conversation with the full knowledge base behind it. Clean decision. I wrote it up. Three artifacts in the KB.

Then I went to take a shower.

The shower is where it clicked

Standing under hot water, not thinking about code, the picture rearranged itself.

I'd been building three projects as separate things: NanoClaw (the agent backend), Kleos (a web app), and Nyx (a Rust terminal I hadn't started yet). In that moment, I saw them as one system with three surfaces.

Lyra (NanoClaw — Claude + KB)
├── WhatsApp / Telegram  — mobile, async
├── Kleos (PWA)          — web, voice, rich UI
└── Nyx (terminal)       — dev workflow, local AI

Same brain. Same knowledge. Different interface for different contexts. WhatsApp for quick captures while walking the dog. Kleos for deep voice conversations with dashboards. Nyx for dev sessions where terminal context — current directory, active project, git branch — makes the AI responses sharper.

More importantly, I saw what Nyx should not be. The tempting idea — "let Lyra execute commands through Nyx" — was a trap. Claude Code already does that, built by a team with resources I don't have. Nyx's job isn't execution. It's ambient context: detect the project you're in, surface relevant KB knowledge, let you log progress without leaving the terminal.

I got out, dried off, sat back down. Twenty minutes later I had a brainstorm document with the full ecosystem diagram, the integration direction (build this / don't build this), and the open source narrative: NanoClaw as the platform, Kleos and Nyx as reference clients.

This is not about showers

The point is not "go take a shower." The point is that pattern recognition — the kind that connects three separate projects into one coherent system — doesn't fire when you're staring at a diff. It fires when you step away. When you stop holding the problem actively and let the background process run.

Every experienced engineer knows this. The fix that comes to you while making coffee. The design that crystallises on the drive home. The naming that lands while you're falling asleep.

What most of us don't have is the infrastructure to capture it.

I came back from that shower and had a structured knowledge base waiting for me. A routing system that knew brainstorm notes go in 01_Projects/Nyx/Brainstorm/. An AI assistant that could take a raw idea and help me shape it into a decision document, a set of scoped artifacts, and a content plan update — all in twenty minutes, before the clarity faded.

The real investment

Building a personal knowledge system is not about productivity hacks. It's about reducing the latency between insight and artifact. The gap between "I see it" and "it's written down, structured, and findable."

That evening session produced a project pivot, an ecosystem architecture, three new content pieces for this site, and the clearest product vision I'd had in weeks. Not because I had a breakthrough. Because I had the system to catch it.

The architecture happens in the shower. The discipline is what's waiting when you get out.

The views expressed here are my own. Examples and scenarios are composites drawn from broad industry experience and do not represent any specific organization, product, or system.

What a Twenty-Year-Old Codebase Could Become

Thu, 19 Mar 2026 03:30:00 GMT

Nobody builds a twenty-year-old monolith on purpose. You build a reasonable application, ship it, and then two decades of features, team rotations, and regulatory changes happen. What you end up with is a system that works — reliably, in production, under load — but one that nobody fully understands anymore.

If you maintain one of these systems, you recognize the profile. Hundreds of projects in a single solution. Multiple interconnected applications sharing a single database. Business logic buried in stored procedures that nobody wrote tests for. Audit trails implemented through database triggers with non-trivial performance overhead. A custom schema migration tool that rebuilds everything on every deployment regardless of what changed.

The system works. That's both the achievement and the trap. "Works" is not the same as "built for what comes next."

This post is not a migration plan. It's the architectural north star — the end state worth holding in mind when you're making tactical decisions inside the constraints of a legacy enterprise codebase. Not what you build tomorrow. What you're building toward.

The domain boundaries already exist

A monolith like this knows everything about everything. Every functional area — compliance, operations, scheduling, inventory, reporting — woven through the same codebase, the same database, the same deployment pipeline. Change one domain and you risk breaking all of them.

But if you listen to how the business talks about the system, the boundaries are already there. Different departments own different capabilities. Different regulations govern different concerns. These aren't arbitrary technical divisions — they're how the business itself is organized.

The vision starts with Domain-Driven Design — not as a philosophy exercise, but as a practical decomposition strategy. Each bounded context becomes an independently deployable microservice with its own database, its own deployment lifecycle, and eventually its own team. An operator creating a task in one domain shouldn't need to worry about — or risk breaking — the scheduling system in another.

The decomposition isn't just technical. It's organizational. When a domain owns its own service, the team responsible for that domain can deploy, scale, and iterate independently. The blast radius of any change shrinks from "the entire platform" to "one bounded context."

The facade that makes migration safe

You cannot rewrite a twenty-year-old system in one go. The feature catalog alone is unknowable without months of discovery work. Undocumented business rules live in stored procedures that nobody wrote tests for because nobody expected them to still be running two decades later.

The Strangler Fig pattern is the answer, and an API Gateway is what makes it surgical.

The gateway sits between clients and the system. On day one, it routes everything to the monolith. As microservices come online — starting with the cleanest domain boundaries — the gateway reroutes specific requests to the new service. The monolith never notices. The clients never notice. The risk is contained to one domain at a time.

The gateway handles more than routing. Authentication, rate limiting, request transformation, response aggregation, monitoring — all the cross-cutting concerns that individual services shouldn't carry. It's the seam between old and new, and it's designed to be temporary. As the monolith shrinks, the gateway's routing table shifts. Eventually, there's nothing left to strangle.

The critical discipline: every migration step must be reversible. Every new service proves itself in production before the old code path is deprecated. You don't decommission the monolith piece by piece — you earn the right to, one domain at a time.

Events over shared state

In a monolith, components communicate through shared database tables. Module A writes a row, Module B reads it. They're coupled through data rather than explicit contracts. Nobody can map the full dependency graph because it lives in SQL queries scattered across thousands of files.

The target architecture inverts this. Apache Kafka becomes the backbone — an event bus where microservices publish what happened and subscribe to what they care about.

Consider what this looks like in practice. An operator creates a new work order in a regulated enterprise system:

The Operations service writes the work order to its own database and, in the same transaction, writes a "WorkOrderCreated" event to an outbox table
A background process — or Debezium, doing change data capture against the outbox — picks up the event and publishes it to Kafka
The Compliance service consumes the event and runs impact checks. Does this work order trigger any regulatory holds?
If a compliance hold is required, it emits a "ComplianceHoldTriggered" event
The Scheduling service picks that up and adjusts timelines for affected resources
Notifications fire downstream to the relevant teams

Each service reacts to events and emits its own. No service calls another directly. No shared database tables. If the Scheduling service is temporarily unavailable, the saga orchestrator triggers compensating actions — revert the compliance check, roll back to a known state, retry when the service recovers.

The Outbox pattern is what makes this reliable. The database write and the event publication happen in a single local transaction. You never end up in a state where the work order was created but the event was lost, or the event was published but the work order wasn't saved. Debezium watches the outbox table via change data capture and streams unprocessed events to Kafka, ensuring eventual consistency without polling.

This is choreography-based saga orchestration — long-running transactions that span multiple services without requiring them to know about each other's internals. Loose coupling that actually holds up under failure.

One database, one truth — per service

In a legacy monolith, the single biggest coupling surface is often the shared database. Every application, every feature, every domain — one database instance with hundreds of scalar functions degrading query plans, cross-domain joins nobody dares refactor, and a schema carrying the archaeology of decades of business decisions.

The vision is database-per-service. Operations owns its schema. Compliance owns its own. No shared tables. No cross-service joins. A schema migration in one domain cannot bring down another.

This introduces a genuine challenge: complex reads that currently rely on cross-domain joins. The answer is CQRS — Command Query Responsibility Segregation. Writes go to each service's own database through its own models. Reads are served from materialized views that aggregate data across domains, kept current by consuming events from Kafka. A Redis caching layer handles hot-path queries. For extreme scale, database replication for read-heavy workloads and sharding for horizontal growth.

Beyond isolation, database-per-service is the path out of vendor lock-in. Legacy .NET systems are often deeply coupled to SQL Server — not just the engine, but stored procedures carrying business logic, database-scheduled agent jobs, trigger-based audit trails, and proprietary migration tooling. Entity Framework Core is the bridge. Map the schema incrementally. Move business logic from stored procedures into the application layer where it can be unit tested, versioned, and debugged with modern tooling. Replace brute-force migration tools with EF Core's incremental migrations — targeted changes, versioned, no unnecessary re-runs.

Trigger-based audit trails deserve special attention. SQL triggers are implemented differently across database vendors, making them a hard vendor lock. Three alternatives are worth exploring:

Change Data Capture — database-level change logging, vendor-provided but more portable than custom triggers. The most pragmatic first step.
Event Sourcing — store domain events as the source of truth, rebuild state at any point in time. Architecturally pure, but adds significant application-level complexity.
Structured audit logging — application-level audit events shipped to a purpose-built store via frameworks like Serilog with an ELK backend.

Each has trade-offs. But all three are more portable than triggers wired to a specific database vendor.

Seeing everything

In many legacy enterprise systems, the monitoring story is fragmented. Some applications write to log files. Others rely on Windows Event Viewer. Background process failures can go unnoticed for days. When something breaks, the first question is often "where do I even look?"

Unified observability changes that equation. The vision is an ELK stack — Elasticsearch, Logstash, Kibana — with Beats agents collecting from every surface:

Filebeat on every server generating log files
Winlogbeat on Windows servers monitoring Event Viewer
Logstash parsing and enriching logs with environment and application metadata
Elasticsearch indexing everything into a searchable, time-series store
Kibana turning raw data into dashboards and real-time visibility
ElastAlert triggering notifications on error rate spikes, service degradation, and silent failures

The goal isn't debugging. It's confidence. When you can see every service, every background job, every failure mode — you deploy with conviction instead of anxiety. You catch silent failures in minutes instead of days. You see resource exhaustion building before it takes systems offline.

Observability is the foundation that makes everything else in this vision possible. You can't safely strangle a monolith if you can't see what's happening on both sides of the migration.

The north star, not the roadmap

A vision like this is not a plan. There's no timeline, no budget, no approval chain required for it to be valuable. It's the picture that gives tactical decisions a direction.

If you're an architect inside a legacy enterprise system, you face constraint-driven decisions every day. The team can't absorb overnight disruption. The business needs features now, not infrastructure. Regulatory environments punish failure. In that context, having a north star — even one you can't reach this quarter — changes how you evaluate every fork in the road. Without it, every tactical decision is a coin flip. With it, every tactical decision is a step — maybe small, maybe sideways — toward something coherent.

Some elements of a vision like this are achievable incrementally. Moving background jobs from database-scheduled agents to application-level schedulers. Adopting an ORM for new development paths while leaving legacy data access untouched. Centralizing documentation and tooling across previously siloed repositories. These are steps that don't require anyone to approve the full decomposition.

The full target — true microservices, event-driven communication, database-per-service — is a horizon goal. And that's fine. A system that has survived twenty years didn't get there by rushing. The next twenty years don't need to rush either. What they need is a direction — clear enough that when an opportunity opens, when a new feature could be built as a service instead of another module bolted onto the monolith, you know which way to walk.

The system has survived by being good enough. The north star is about what comes after good enough.

Giving AI Context in Large Brownfield Codebases

Mon, 16 Mar 2026 03:30:00 GMT

If you drop an AI coding assistant into a large brownfield codebase without guardrails, it will generate plausible, wrong code. Not randomly wrong. Wrong in ways that look idiomatic, compile cleanly, and pass a casual review — and then quietly violate the conventions that years of engineers built on top of, in ways that only surface when something breaks.

This post is about how to prevent that. Specifically: how to give AI assistants the structured, ambient context they need to work correctly in complex legacy systems, and why that context — not the model, not the prompt — is the actual multiplier.

The failure mode

In a large multi-project .NET codebase, a common pattern is maintaining multiple generations of ORM simultaneously. A legacy application using EF6 coexists with newer services using EF Core, both touching the same underlying database. Different mapping strategies, different transaction patterns, different rules about which layer owns which tables.

When you drop an AI assistant into that environment without providing that context, you tend to get:

EF Core LINQ syntax in codebases that use EF6
Wrong primitive types on timestamp columns (e.g., DateTime where the convention requires DateTimeOffset)
Direct database access that bypasses the service layer
Entity or table naming that ignores the project's established prefix conventions
Repository implementations that silently omit soft-delete handling
Cross-system calls that ignore the documented integration boundaries

None of these is catastrophic in isolation. Collectively, over weeks, they're how a codebase accrues the kind of subtle inconsistency that makes future changes expensive. And unlike a compile error or a failing test, these violations are invisible until they aren't.

The problem is not that the AI is bad at code. The problem is that it's generating code calibrated to the median codebase — not your codebase. It doesn't know your codebase's rules unless you tell it.

The anchor: project_context.md

The first structural fix is a single versioned file: docs/project_context.md, placed at the repository root and explicitly referenced in both CLAUDE.md and AGENTS.md.

Not a wiki page. Not a Confluence article that lives outside the IDE. A file that loads into every AI session automatically, as ambient context, before any code is generated.

The file is a list of rules written in the declarative negative: NEVER mix ORM versions in the same repository. NEVER bypass the service layer. NEVER use DateTime for timestamp columns — use DateTimeOffset. NEVER create database queries directly in controllers.

Then the positive conventions: naming schemes, soft-delete patterns, which systems are allowed to call each other, which database tables belong to which application tier.

This is not prompt engineering in the clever sense. It's documentation that happens to be machine-readable. The same file a new engineer should read on day one is the same file the AI loads before it writes a line. The audience is both.

The key discipline is writing the rules as constraints, not as descriptions. "Use DateTimeOffset for all timestamp columns" is actionable. "We have a history of inconsistent timestamp types" is noise. AI models respond to constraints. They don't self-correct from prose complaints.

Here is a starting template. The specific rules are yours — but the structure matters. Hard rules first, conventions second, boundaries third.

# Project Context — [Your Project Name]

## Architecture
- Runtime: [e.g., .NET 8 / .NET Framework 4.8 / mixed]
- ORM: [e.g., EF Core for new services, EF6 for legacy]
- Database: [vendor and version]

## Hard Rules (NEVER do these)
- NEVER [your critical constraint #1]
- NEVER [your critical constraint #2]
- NEVER [your critical constraint #3]

## Conventions
- Naming: [entity prefixes, table naming, etc.]
- Data types: [e.g., DateTimeOffset for all timestamps]
- Service boundaries: [which layer owns what]

## Integration Boundaries
- [System A] may call [System B] via [mechanism]
- [System C] is read-only from [System A]'s perspective

Scaling workflow with BMAD

Documentation alone handles the guardrails. It doesn't handle workflow complexity.

The BMAD Method (Breakthrough Method for Agile AI-Driven Development) provides the framework for the rest. BMAD structures AI-assisted development around role-based agents — Analyst, Scrum Master, Developer — each with defined responsibilities and commands. The base framework is open-source. What you build on top of it is a custom module for your specific codebase.

That module can produce a substantial library of commands and agent definitions covering the full development lifecycle: feature discovery, PRD generation, architecture documentation, sprint planning, story implementation. Each command pre-loads the relevant context — the project conventions, the active feature, the affected components. Each agent definition is a version-controlled file, reviewed and improved over time.

The maintenance cost is real. When BMAD released a new major version, the upgrade required a full module rewrite — the hook and workflow API changed significantly. That's an accepted cost. The alternative is maintaining nothing and accepting the inconsistency tax permanently.

The Golden Path workflow

A well-structured BMAD module defines a canonical workflow:

init-feature → feature-discovery → create-prd → create-architecture → sprint-planning → dev-story

init-feature takes a work item identifier, creates synchronized branches across the affected repositories, and writes an active-feature.yaml file: ticket identifier, branch name, affected components, current phase.

Every subsequent command reads that file. feature-discovery scans the codebase for relevant files and generates a research document. create-architecture proposes an approach aligned with existing integration patterns. dev-story loads the full feature context — PRD, architecture, active ticket, affected systems — before writing a single line.

The branch name itself becomes ambient context. Extracting the active work item identifier from the current branch name lets agents auto-detect which feature they're working on between sessions. No manual re-explanation. No "I was working on..." preamble. The context travels with the branch.

This is the Golden Path: a workflow where every AI interaction arrives pre-loaded with the context it needs to do correct work.

What changes

The measurable difference is in context assembly time. Without structured context, a developer spends significant time at the start of every AI session re-explaining the codebase, the conventions, and the current feature. With it, that overhead drops to near zero — the agent arrives pre-loaded. The productivity gain comes from eliminating repeated setup, not from the AI writing faster code.

In complex codebases, a significant portion of task time isn't writing code — it's finding the relevant files, understanding the dependencies, verifying the fix approach against conventions. When an agent is pre-loaded with that context, it handles the assembly. The engineer handles the judgment.

The subtler change is this: AI agents that systematically read a codebase against an explicit standard surface what human developers acclimate to ignoring. Unused mapping files. Missing indexes. Legacy patterns that were "known in a vague way" but never catalogued, never prioritized, never fixed. When you give an AI agent the task of auditing against an explicit ruleset, it doesn't get tired or skip the boring parts.

The honest trade-off

The upfront investment is significant. Building and wiring a full command library and agent definition set doesn't happen in an afternoon. Feature context systems — making work item detection reliable across submodules, handling edge cases in branch naming — take time to stabilize.

And framework upgrades are a maintenance commitment. Major BMAD versions have required full module rewrites. Future major versions will require the same.

The alternative — raw prompts, ad hoc context, no shared vocabulary — is also a maintenance commitment. It's just invisible, paid continuously in small amounts of inconsistency, repeated context-setting, and the slow erosion of codebase coherence.

The visible cost beats the invisible one.

The principle

AI doesn't replace domain knowledge. It amplifies whatever domain knowledge it receives.

Give it nothing, and it generates plausible code calibrated to the median codebase. Give it the specific conventions, the specific anti-patterns, the specific architecture of your system — and it generates code that fits.

The guardrails are the multiplier. Not the model. Not the prompt length. The structured, version-controlled, systematically loaded context that tells the AI where it is, what the rules are, and what it must never do.

In a large legacy codebase with multiple ORM generations, dozens of engineers, and years of accumulated conventions, that context is not optional. It's the difference between AI that makes things worse in hard-to-see ways, and AI that makes the team genuinely faster.

Getting the context right is the engineering work. Once it's right, the multiplication follows.

When Git Submodules Make Sense in a Monorepo

Thu, 12 Mar 2026 03:30:00 GMT

The internet will tell you Git submodules are a mistake. That advice assumes you have the luxury of a clean migration. In large enterprise codebases, you often don't.

There is a pattern worth knowing: the Nx monorepo with Git submodules as a deliberate, time-boxed bridge. It's not the textbook answer. In the right circumstances, it's the correct one.

The problem this pattern solves

Imagine a platform that has grown across multiple repositories — a legacy web application, a modern API, a second API handling orchestration. They share a database. Almost every significant feature touches at least two of them.

This is a common trajectory for enterprise systems. What starts as reasonable separation becomes friction at scale: independent branch strategies with no coordination, AI assistants that can't see across repo boundaries, development tooling that has to be configured separately per repo. The cost isn't duplicated code. It's duplicated thinking — context the team has to mentally reload every time they cross a boundary.

The standard prescription is a full monorepo merge: pull all histories into one, unify CI, standardize the branching strategy. It's the right long-term answer. It's also the answer that can break working teams overnight.

Why "full merge immediately" fails as a default

If your codebase has hundreds of projects spread across multiple repos, each with its own CI pipeline and its own release cadence, a hard cut to a unified monorepo carries real disruption risk. Developers who are productive today have to change their workflow entirely, immediately. Teams operating under regulated deployment constraints often can't accept that kind of disruption on a short timeline.

The failure mode to avoid is treating monorepo migration as a binary choice: either you're fully merged or you're still siloed. That framing ignores the option of a structured transition with incremental value delivery at each phase.

The bridge pattern

The approach: create an Nx parent monorepo that wires existing repositories together as Git submodules under apps/. The parent provides unified tooling — nx run, nx affected, centralized documentation, cross-project AI context. The app repos remain fully independent. A developer who only needs to work in one of those repos still clones it directly. Nothing in their workflow changes until they choose to adopt the unified layer.

nx affected is particularly valuable in this setup. It analyses the project graph to determine exactly which projects were impacted by a change — including changes that span submodule boundaries — so CI only rebuilds and retests what actually changed. For .NET projects, this requires the @nx/dotnet plugin, which teaches Nx to parse .csproj files and construct the .NET project graph. Without it, Nx cannot reason about dependencies inside your .NET submodules.

This matters because adoption can be opt-in. The monorepo is additive, not mandatory. Teams that want cross-project tooling get it immediately. Teams that don't aren't disrupted.

The centralized docs/ layer is where a lot of the value lives. A single authoritative document captures the conventions that all projects share: naming rules, soft-delete patterns, service layer boundaries, ORM version distinctions. Both humans and AI agents load this context at session start. You eliminate the quiet inconsistencies that accumulate when developers are context-switching between repositories that each have their own undocumented norms.

Cross-repo feature coordination

The hardest part of this pattern isn't the structural wiring — it's branch coordination. When a feature touches multiple submodule repos, you need branches created consistently across all of them. If you leave this to manual discipline, you'll get drift: a feature branch exists in two repos but not the third, AI agents are confused about which ticket they're working on, merge order goes wrong and the parent repo points at stale submodule commits.

The solution is to script the coordination explicitly. An init-feature command takes a ticket ID and creates matching branches in the parent repo and all submodules simultaneously. A lightweight YAML file persists the active feature context so tooling can detect it automatically from the branch name. This removes the "which repo are we in?" confusion without requiring anyone to change how they interact with individual repos.

Merge discipline matters too: submodule repos merge first, then the parent. Document it. Automate the check if you can.

The trade-offs you're accepting

Submodules introduce real friction. Developers run git submodule update --init --recursive on first clone. The detached HEAD state inside submodules is confusing in many Git clients. Any workflow that bypasses the coordination tooling creates incomplete context.

These are real costs. The question is whether they're smaller than the cost of the alternative. If the alternative is a migration that disrupts a productive team for weeks or months to satisfy an architectural ideal, the submodule friction may be the better bet — especially if you instrument and document it carefully.

I've found that "submodule complexity is documented and tooled around" is a manageable state. "Cognitive load from boundary-crossing is undocumented and growing" is not.

A three-phase structure

If you adopt this pattern, design it as a time-boxed bridge with explicit phases:

Phase 1: Submodule wiring, centralized docs, cross-project AI tooling, feature coordination scripts. Delivers immediate value. Validates the approach.
Phase 2: Move shared libraries to the monorepo root. Reduce duplication at the code level.
Phase 3: Remove submodules entirely. Full integration. This is the textbook answer — arrived at on a timeline the team can actually absorb.

Phase 3 might happen in a year. It might not happen at all, because Phase 1 turned out to be enough. That's a legitimate outcome. The architecture serves the team, not the other way around.

What to measure

When evaluating whether this pattern is right for your situation, don't just count duplicated code. Count the number of times developers mentally reload context when working across boundaries. Ask how often AI assistants give advice that makes sense in one codebase but violates conventions in another. Measure how long it takes a new developer to get productive across the full surface area.

Cognitive duplication is harder to quantify than code duplication. It's just as expensive.

If the textbook answer requires disrupting a working team on a short timeline — question the textbook. The best architectural decision is the one your team can actually adopt.

When to Build an Integration Platform Instead of Another One-Off

Sun, 08 Mar 2026 03:30:00 GMT

It's common for this kind of work to be scoped as a small feature request: connect the platform to an external accounting system, add a scheduled export job, ship it. If you only count the feature being asked for, that scope might even be accurate.

The problem shows up in the system that already exists. If your platform has grown three or four integrations and each one was built differently — different retry behaviour, different error handling, different config patterns — you're accumulating something that looks manageable in isolation and becomes a liability at scale. Some integrations silently eat failures. Some have no alerting. None of them share infrastructure with each other. Each one is its own snowflake.

When the next integration request lands, you face a choice: build another snowflake, or stop and ask whether this is the last time you'll be making that choice.

The cost of ad-hoc integrations

The individual cost of each snowflake integration is low. Connect to the external system, wire up an HTTP call, handle errors roughly, ship it. Done in days.

The systemic cost accrues invisibly. You don't notice it until you're debugging a production failure at 10pm and you realize:

There's no standard way to find out which integrations are registered and what state they're in
One integration retries three times before giving up; another retries forever; a third doesn't retry at all
A config change was made in production weeks ago and nobody remembers by whom or why
An export job failed silently and the operations team only found out when a downstream system complained

Each of these problems is solvable individually. Add logging here, add a retry here, add a config record there. The patches accumulate. The architecture doesn't improve. The next integration — and there's always a next integration — inherits the same gaps.

The trigger for taking this seriously is usually a sufficiently complex request: cross-system data sync with an external provider, automated exports on a schedule, configuration that needs to be managed by the operations team without developer involvement. Too complex for a snowflake. Too visible to fail silently.

What building the platform actually means

The first decision is to define the surface area. An integration platform, in this context, means a shared layer that every concrete integration is built on top of — not a system you implement once for one integration.

Here's what that layer needs to include:

Shared contracts. Every integration implements the same interfaces. The platform doesn't care what the integration does — it cares that it can register it, invoke it, and observe it consistently. This is the foundation; without it, none of the rest of this is reusable.

In .NET, this typically takes the form of a single handler interface that each integration implements:

public interface IIntegrationHandler
{
    string IntegrationName { get; }
    Task<IntegrationResult> ExecuteAsync(IntegrationContext context, CancellationToken ct);
}

// Each integration implements this interface.
// The platform discovers and invokes handlers via DI —
// adding a new integration means registering a new handler.
services.AddIntegration<AccountingExportHandler>("accounting-export");

The platform discovers all registered handlers at startup, routes by name, and observes them uniformly. Adding a new integration is registering a new handler — no changes to shared infrastructure code required.

Circuit breaker. When an external system is unavailable, stop sending requests. The circuit breaker opens after a threshold of failures and blocks requests until a cooldown period expires. Without this, a temporarily unavailable external system causes cascading load on both sides — the kind of problem that turns a minor outage into a major one.

Polly is the standard .NET library for this. A minimal circuit breaker configuration looks like:

// Using Polly (https://github.com/App-vNext/Polly)
var circuitBreakerPolicy = Policy
    .Handle<HttpRequestException>()
    .CircuitBreakerAsync(
        exceptionsAllowedBeforeBreaking: 3,
        durationOfBreak: TimeSpan.FromMinutes(1));

After three consecutive failures, the circuit opens for one minute. Calls during that window fail fast rather than piling up against an unavailable system. Tune the threshold and break duration to match your external system's expected recovery time.

Retry with exponential backoff. Not retry-three-times-immediately. Configurable retry policies where the wait between attempts grows: 30 seconds, then 2 minutes, then 5 minutes. Transient failures become permanent ones when you retry too aggressively. Give downstream systems time to recover.

With Polly, this is a WaitAndRetryAsync policy with explicit delay intervals:

var retryPolicy = Policy
    .Handle<HttpRequestException>()
    .WaitAndRetryAsync(new[]
    {
        TimeSpan.FromSeconds(30),
        TimeSpan.FromMinutes(2),
        TimeSpan.FromMinutes(5)
    });

The delays here are a reasonable starting point for integrations that hit external HTTP APIs. For integrations with longer recovery windows — batch jobs, nightly exports — you may want larger intervals. The key constraint is that the policy lives in one place, configured per integration type, not reimplemented inline.

Failure alerting. When retries are exhausted, the operations team needs to know — not "check the logs," but an actual notification. Silent failures are a design smell. If the system can detect a failure, it should tell someone.

Config audit logging. Every change to integration configuration — credentials, schedules, field mappings — writes an immutable record: who changed it, when, what it was before, what it is now. This sounds bureaucratic until you're in a production incident and the first question is "what changed?"

The implementation pattern is an append-only audit table — no updates, no deletes. Columns: ChangedBy, ChangedAt, FieldName, OldValue, NewValue, CorrelationId. Querying for "what changed in the last 24 hours" becomes a single SELECT against a table that can never be retroactively modified.

Manual retry UI. The operations team can retry a failed integration job without filing a ticket and waiting for a developer. This single capability removes a whole category of support escalation.

Dry-run mode. Run the integration against real infrastructure without committing changes. This makes testing against external systems safe — you can verify field mappings, authentication, and data shape before anything actually moves.

OAuth2 client credentials flow. If your integrations use OAuth2 — and many external systems require it — implement it once as a reusable provider rather than per-integration. Tokens are managed centrally, with refresh handled transparently.

None of these are sophisticated ideas in isolation. Every one of them exists in some form in most serious integrations. The point is to build them once, in a shared layer, before implementing the first concrete integration on top of them.

The honest trade-off

The first integration through a new platform takes longer to deliver than a snowflake would have. Building the shared layer adds real time to the timeline before the first end-to-end integration runs.

That's the cost you pay, and it's real. If this were the only integration you'd ever build, the platform would be the wrong call. The snowflake would be faster, cheaper, and entirely sufficient.

But the platform pays back within the same body of work if that work is complex enough. A scheduled export job — one that runs nightly, maps field data through a configuration-driven transform layer, authenticates via OAuth2, and reports failures to the operations team — can be built almost entirely by wiring together what the platform already provides. The circuit breaker and retry logic are already there. The alerting is already there. The audit trail is already there. The OAuth2 provider is already there.

And the next integration after that takes a fraction of what the first one took. Not because the engineers are faster — because the integration surface they need already exists.

When the investment is worth it

The snowflake approach is rational when:

The integration is genuinely one-off with no likely successors
The feature is small and the blast radius of failure is limited
Speed to ship is the dominant constraint and the team will never look at this code again

The platform investment starts paying off when:

You're looking at the third or fourth integration and recognizing the same problems being solved again
Failure modes matter — silent failures or cascading failures have real operational cost
The operations team needs to manage integrations without developer involvement
You want to be able to look at the system in two years and understand what's registered, what's running, and what's failing

The specific trigger is usually scope and visibility. An integration that spans scheduling, data transformation, external authentication, and operational tooling is not something you can reasonably bolt onto shared infrastructure that doesn't exist yet. The cost of doing it wrong is too visible.

The pattern

When you build the platform before the feature, you're making a bet: that you'll build enough integrations over a long enough period that the compounding return on shared infrastructure exceeds the upfront cost. That bet pays off more often than you'd think, because integration requests rarely stop at one.

The mistake that costs the most isn't building the platform too early — it's building five or six snowflakes before admitting you need a platform. By that point the problem isn't just the next integration. It's the ones you already have that all need to be retrofitted or left as permanent debt.

Build the platform when the cost of not having it becomes visible. Not when you're drowning in snowflakes. Not so early you're abstracting problems you don't have yet. When the next integration is complex enough that you can see — clearly, specifically — what you're going to build a second and third time if you don't stop and generalize it now.

That's when you stop building the feature and start building the platform.

One Brain, Three Interfaces

Tue, 03 Mar 2026 03:30:00 GMT

The problem with building a capable AI assistant is not the AI. It's the interface.

WhatsApp works brilliantly for a quick capture mid-commute. It handles async, mobile-first interaction well. But it renders markdown as plain text. It has no panels. You can't have a voice conversation with it while a KB browser sits open beside the transcript. And it has absolutely no awareness of what directory you're in when you're three hours into a debugging session.

Different situations need different surfaces. But the intelligence — the memory, the context, the knowledge base — should not be split across those surfaces. You don't want three mediocre brains. You want one excellent brain with three mouths.

That's the architecture I'm building: NanoClaw, Kleos, and Nyx.

NanoClaw: the platform

NanoClaw is the backend. It's an open-source Node.js orchestrator that receives messages from channels (WhatsApp, Telegram, Slack, Discord, Gmail) and routes them to Claude agents running in isolated Docker containers. Each agent group has its own filesystem and memory. The main agent — Lyra — has an Obsidian knowledge base mounted read-write into every container it runs.

Channel message arrives
  └── Orchestrator picks it up
        └── Spawns container (isolated filesystem + mounts)
              └── Claude Agent SDK reads CLAUDE.md, accesses KB
                    └── Response routed back out

The knowledge base is a PARA-structured Obsidian vault: projects, areas, resources, journal, showcase. Every conversation Lyra has goes through that context. Progress notes, decisions, incidents — they land in the vault. The next conversation starts with that history already in scope.

NanoClaw is the brain and the memory. The channels are just delivery pipes.

Kleos: the voice pivot

Kleos started as something different. A voice-first PWA for capturing invisible senior engineer work — the incidents you solved, the architecture decisions you made, the mentoring conversations nobody logs. React 19, Vite 7, WebSpeech API, local Ollama handling categorisation. Epic 1 shipped. The voice capture worked.

Then I looked at what it was actually doing and the redundancy was obvious.

Lyra already categorises, tags, and routes notes into the correct KB location — with full project context and knowledge base access behind every call. The local Ollama model doing isolated categorisation was a weaker version of something that already existed. I was running two AI layers where one was strictly better than the other.

The pivot decision was clean: strip the Ollama backend, wire Kleos into NanoClaw as the official web client. Keep everything that was good — the voice infrastructure, the PWA shell, the shadcn/ui design system, the offline capability. Replace what was wrong.

The result is what Kleos should have been from the beginning: a voice-first dashboard that lets you have a natural conversation with Lyra while a KB browser panel sits beside the transcript. Streaming Claude responses with full markdown rendering. Project status, active tasks, recent journal entries — all surfaced from the same vault that every other interaction writes to.

Don't compete with what the platform already does. Redirect the good infrastructure.

Nyx: the anti-pattern decision

Nyx is a GPU-accelerated Rust terminal. The developer's preferred interface — fast rendering, built for people who spend their working life in a terminal window.

The obvious tempting design is: give Lyra a terminal executor. Let the AI run commands on your behalf. Autonomous execution, right there in your shell.

I ruled that out explicitly and documented why. Claude Code already exists. It does agentic terminal execution extremely well, built by a team with resources I don't have, iterated on faster than I can maintain a reinvented version. NanoClaw already provides remote Claude Code sessions as a built-in capability. Building the same thing again in Nyx is maintenance burden without differentiated value.

What Nyx actually does is different and more interesting. When you cd into a project directory, Nyx detects it and loads the relevant KB context automatically. You can run lyra log "resolved the DPAPI session issue" and it writes a progress note to the correct project in the vault, with the timestamp and context already filled in. When a known error pattern appears in command output, the relevant runbook surfaces in a sidebar panel. Active tasks for the current project live in the status bar.

Nyx is not an executor. It's a developer-context-aware surface for the same brain. The terminal knows where you are. That context — current directory, active project, git branch — makes Lyra's responses sharper in ways a WhatsApp message never can.

The Lyra integration is also explicitly one optional module, not Nyx's core identity. Nyx needs to work brilliantly as a local AI-powered terminal without any network dependency. When Lyra is available, it gets better. That's the right relationship between a client and a platform.

The shared layer

The knowledge base is what ties this together.

One Obsidian vault, mounted into every NanoClaw container. Kleos writes a voice note → it lands in the vault. A WhatsApp message captures a decision → it lands in the vault. Nyx logs a debugging session → same vault. The next session on any surface picks up where any other surface left off.

The brain doesn't care which mouth is talking. The knowledge accumulates regardless of interface.

This is also the open source story. NanoClaw is the agent platform — the reference implementation for anyone who wants to run their own containerised Claude assistant with a persistent knowledge layer. Kleos is the reference web client, demonstrating how to build a voice dashboard on top of NanoClaw's API. Nyx is the reference terminal client, demonstrating how to wire developer context into the same backend. Three separate repositories. One coherent system.

The principle

The interface is not the intelligence.

A single great chat interface with mediocre AI does less than three average interfaces sharing one excellent brain. The tendency in this space is to over-invest in the surface — to build a beautiful product experience around a model that isn't actually that capable in the specific context you need. The better investment is the other direction: make the brain excellent, make the memory deep, then build whatever surfaces you actually need for the situations you actually find yourself in.

WhatsApp for async mobile. Kleos for voice conversation with rich rendering. Nyx for dev sessions where terminal context is the most relevant thing about where you are.

Same brain. Same knowledge. Different mouth for different moments.

The views expressed here are my own. Examples and scenarios are composites drawn from broad industry experience and do not represent any specific organization, product, or system.

Seevali Rathnayake

The Orchestration Dividend: What a Month of Mission-Command Cost, to the Cent

Reading the meter

Where the turns ran

Repricing the month

The credit ledger

The dividend

The Breed

What the AI Era Actually Unlocked

The System Is the Expression Layer

You Own the Context

The Answer

For the Breed

Three Months of Capture

The Timeline

The Numbers

What the Numbers Don't Show

The Velocity Observation

The Property Nobody Mentions

What Three Months Proves

The LLM Smell Problem

An AI Pipeline That Reads Your Post Before It Draws the Picture

The Concept Before the Image

The Stack: Three Tools

1. generate-image — NanoClaw image skill

2. sharp — WebP conversion

3. wrangler r2 object put — Cloudflare R2 upload

The Prompt Structure

The Frontmatter

The Full Run

What the Pipeline Doesn't Do

The Meta Moment

Five World-Class Designers in Your IDE

What It Is

Why Five

How to Use It

What It Catches That You'd Miss

The Methodology, Extracted

The Dev Workflow That Follows You Everywhere

Three Pieces, One System

How It Actually Works

Phase 1: The 11pm Idea

Phase 2: Planning from the Couch

Phase 3: Starting the Session

Phase 4: The BMAD Dev Agent

Phase 5: Code Review Without Mercy

Phase 6: The Knowledge Stays

What Changes When This Works

The Practical Setup

The Bigger Pattern

Constraint-Driven Architecture: Five Principles for Building in the Real World

The problem with architecture advice

Five principles for constrained environments

1. Unify context, not just code

2. Optimize for outcomes, not metrics

3. Strangle safely

4. Equalize with AI

5. Prove through practice

The meta-principle

Further Reading

The Architecture Happens in the Shower

The shower is where it clicked

This is not about showers

The real investment

What a Twenty-Year-Old Codebase Could Become

The domain boundaries already exist

The facade that makes migration safe

Events over shared state

One database, one truth — per service

Seeing everything

The north star, not the roadmap

Further Reading

Giving AI Context in Large Brownfield Codebases

The failure mode

The anchor: project_context.md

Scaling workflow with BMAD

The Golden Path workflow

What changes

The honest trade-off

The principle

1. `generate-image` — NanoClaw image skill

2. `sharp` — WebP conversion

3. `wrangler r2 object put` — Cloudflare R2 upload