I recently built the same kind of dashboard twice, once as custom Apache Superset plugins and once as a MotherDuck Dive. This article compares the effort and shows how I built the Dive. The numbers come from one test, so read them as my results, not as a benchmark.

TL;DR

• Superset needed five custom plugins, 30+ prompt revisions, 8+ hours to a first working plugin, and a Kubernetes redeployment for every change.
• The Dive needed 2 prompt revisions and half an hour to a first working version. The finished dashboard took about a day, including learning the tool.
• The result depends on the data: mine was a golden layer, one flat table with joins and metrics already done. Multiple raw tables are untested.
• For customer proposals, a Dive on anonymized data can turn an idea into a clickable demo within a day.

Where I’m coming from

I’m a Data Visualisation Specialist at arconsis. I build dashboards for customers, in the tools they already have, the tools they ask for, or the tool I believe fits their needs best.

I started in Tableau and have also worked with Power BI and GoodData. I tested Metabase, Lightdash, and Fastero. For an internal project, I built custom React visualization plugins for Apache Superset, because the existing charts did not cover what we needed.

I found MotherDuck by accident. I wanted a quick way to load a test CSV and explore it in Lightdash. Then I saw Dives and the prompt library behind them (MotherDuck Dives). My first reaction was “what the heck?” A few days later I tried it.

Others have already tested MotherDuck’s speed. Artefact’s benchmark, for example, compares query and dashboard performance on Superset against BigQuery and PostgreSQL (MotherDuck Explained). Artefact is a MotherDuck launch partner in Europe, so read it as partner content. I looked at something different: how much effort it takes to build the dashboard.

The starting point

The data was one flat table: a CSV exported from PostgreSQL, with all joins and metrics already calculated. In other words, a golden layer, which is the best case for an agent. This matters for the comparison. The agent did not have to find join paths or decide how a metric is defined.

What Dives are

Dives are interactive visualizations you create with natural language, directly on top of your data in MotherDuck. You ask an AI agent, and it generates a persistent component that lives in your workspace next to your SQL.

Technically, a Dive is a React component. It uses a hook called useSQLQuery to run SQL against your MotherDuck databases, Recharts for the charts, and Tailwind CSS for styling. The component queries live data, so a reload always shows current numbers.

That is the same React and SQL stack I already use for Superset plugins, without the plugin plumbing.

The Superset way: one week

The goal: two tables with four-level dropdowns, plus a pivot table where users add columns interactively and pick them from dropdowns.

Why custom plugins: the existing Superset charts did not cover three things:

• Drill-down: the existing table options did not offer it.
• A flexible pivot: the existing pivot table did not let users freely add columns and rows, so they could not adjust the report on the go.
• A branded header and footer: I wanted a page with the company branding, showing the customer name and the date range selected in the filters. A chart that pulls both from a dataset that includes the company branding is not something the existing charts offer, so I built one.

What it took: five custom React plugins, built with five agents:

• Analytics: clarifies the data and the questions the dashboard must answer
• Design: knows all of the company’s design rules and constraints, from logo usage to colors, typography, and tone
• UI: writes the React plugin
• Grill: challenges the result and looks for weaknesses
• Judge: decides whether it is ready to ship

The numbers:

• 30+ revisions of the Superset prompt
• 8+ hours until the first plugin ran
• one week until the tables and the pivot were usable

After that came the manual work:

• add the plugin to the dashboard by hand
• set up every filter
• find a workaround for the date filter
• apply the company design and logo in Superset itself
• choose the right chart type

On production, every change and every new plugin meant redeploying Superset on Kubernetes. That is part of working with open source: you control everything, and you also run everything. I’m not complaining, I’m showing what it takes to build something like this.

Why it matters: each change cost a round of build, deploy, and manual testing. For a small request like an additional button, that is a lot of overhead.

The Dives way: two revisions

Setup

Connect an AI client to the MotherDuck MCP server. With Claude Code, it is one command:

claude mcp add MotherDuck --transport http https://api.motherduck.com/mcp

Ask explicitly for a Dive, for example “create a Dive” or “save this as a Dive in MotherDuck”. Otherwise the agent may create a chart without saving it as one.

The prompt

I wrote one prompt in plain English, using a sample prompt with eight sections as the structure.

The design rules I had given a whole agent in Superset became two sections in this prompt: Visual design and Wording.

Here is the full sample prompt. Copy it, fill in what applies, and skip the rest.

DIVE: <name>
DATA
- Source: <database.schema.table, or several tables and how they join>
- One row is: <what a single record represents>
- Key columns:
  - <column>: <meaning, unit, allowed values>
  - <value with special meaning>: <how to treat it>
- Leave out: <columns, values or records to ignore>
- Sensitive data: <fields to hide, aggregate or never show>
- Data quirks: <known gaps, duplicates, odd formats, update frequency>

AUDIENCE AND PURPOSE
- Who uses it: <role, device, how often>
- Questions it must answer:
  - <question 1>
  - <question 2>
  - <question 3>
- Level of detail: <aggregate only | individual records allowed>

STRUCTURE
- Tabs (about 3, split bigger ideas into separate Dives):
  - <tab 1>: <metrics, charts, tables>
  - <tab 2>: <metrics, charts, tables>
- Default state: <time range, preselected filters, landing tab>

FILTERS AND INTERACTION
- Filters: <dimensions, single or multi-select, with search>
- Click behavior: <drill down or cross-filter, what happens>
- Filters in shared link: <yes | no>
- Other: <search, sorting, keyboard shortcuts, detail panels>

VISUAL DESIGN
- Theme: <light | dark | both | special style>
- Colors (hex): primary <...>, accent <...>, neutrals <...>
- Fonts: <...>
- Icons: <style, e.g. line icons only>
- Logo: <file or none>
- Accessibility: <e.g. contrast at least 4.5:1, respect reduced motion>

WORDING
- Tone: <e.g. neutral, friendly, formal>
- Rules: <style rules, terms to use or avoid>
- Empty and loading states: <what they should say>

EXPORTS
- Format: <format, or none>
- File naming: <e.g. include active filters>

OUT OF SCOPE
- <what not to build or show>

The sample prompt does the thinking up front. The more the agent knows about the people and the questions, the more it gets right on its own.

The result

The Dive had three tabs, working filters, and the fun facts and notes in the style I defined under Wording.

It also had something I never asked for: a clickable pop-up with the details behind each number. The prompt described the audience and their questions, and the Dive added drill-down on its own. That is the request I have heard in every BI tool I have used, and here it was already there.

The numbers:

• 2 revisions of the prompt
• 0.5 hours until the first working version
• about a day until the finished dashboard, including learning the tool

Adjusting the code

A Dive is plain React and SQL, so I could open it and change it. There is also a Git-based workflow for developing, previewing, and deploying Dives as code. In my test, a change showed up as soon as I saved it.

Restyling

For fun, I asked for a terminal theme. I wrote a detailed prompt, but a sentence like “make it terminal style” also works. It took around 3 minutes. The prompt changed only the look and wording. The data and structure stayed the same.

My prompt uses the same structure as the sample above:

THEME: Terminal mode for this Dive
TASK
- Add a theme toggle with two options: "Standard" and "Terminal mode"
- Store the selected theme in useDiveState
- Keep data and filters the same, change only the look and wording

DATA CHECK
- Inspect the Dive's data and identify:
  - measure: <main metric, e.g. hours, revenue, orders>
  - dimensions: <main filters, e.g. customer, region, product>
  - date: <date column>
  - detail: <detail or text column, if any>
- Use the real column names in lowercase snake_case

VISUAL DESIGN
- Fonts: JetBrains Mono or IBM Plex Mono (Google Fonts), everywhere
- Colors (hex): background #000000, primary text <default #5e7dff>,
  secondary text #88898c, highlights #FFFFFF
- Accent: <default #fc3e46>, used for one highlight badge only
- Effects: subtle CRT scanlines, slight text glow, blinking block
  cursor after the last line of each panel
- Panels: terminal windows with a thin border and a title bar
  e.g. "● ● ●  user@<dive-name>:~/<measure>"
- Shape: no rounded corners, no shadows, 1px borders #404044

BOOT SEQUENCE
- Show on first load for about 1.5 seconds, skippable on click:
    > booting <dive-name> v1.0 ...
    > connecting to motherduck ........ [ OK ]
    > loading <table> ................. [ OK ] <row count> rows
    > agents online ................... [ OK ]
    > welcome. <optional tagline>

FILTERS AS COMMANDS
- Show active filters as a live command line that updates with the dropdowns:
    $ <measure> --<dimension_1>="Value A" --<date>=2026-01..2026-06
- Allow typing: one flag per filter, applied on enter
- Unknown flags: friendly "command not found", hint "try: help"
- help: print the available flags
- clear: reset all filters

OVERVIEW
- KPIs as aligned key/value lines:
    <measure>_total ..... 1,240.0
    records ............. 3,412
- ASCII bar charts for the top 2 dimensions:
    Value A  ████████████████░░░░  42%  520.5
- Summary as a log line:
    [INFO] <period> · <total> <measure> across <n> <dimension_1>s
- Fun translations as [FUN] lines, if they fit the measure
  e.g. hours to working weeks, revenue to coffees

LOGS
- Detail rows as log lines, newest at the bottom, auto-scroll:
    <date>  <dimension_1>  <dimension_2>  <measure>  "<detail>"
- Search box styled as "grep: ▌", matches highlighted
- Click on a line: expand the full record

TABLES AND PIVOTS
- Section title as a command e.g. "$ pivot"
- Controls as CLI flags: --rows=... --cols=... --values=...
- Monospace table with aligned columns, totals row separated by "────"
- Download button labelled "$ export --format=csv"

EASTER EGGS
- sudo coffee: prints "☕ permission granted."
- whoami: prints "operator of <dive-name>"
- matrix: brief falling characters in the primary color, then back to normal

EMPTY STATES
- No results: "[WARN] 0 results for this filter."
- No search match: "grep: no matches. try a broader search."

WORDING
- Tone: short, neutral, slightly informal
- Rules: aggregates only, no rankings of individual people

ACCESSIBILITY
- Contrast at least 4.5:1
- Respect prefers-reduced-motion: skip boot animation, glow and matrix effect

In Superset, a restyle means CSS work or a rebuild. Here it was one prompt.

A fair comparison

These numbers are not a lab test. Superset needed custom plugins and a deployment pipeline. The Dive came with a sample prompt and a prepared data layer. The Superset week covered two drill-down tables, an interactive pivot, and a branded header and footer. Both are honest timelines of what I actually spent.

Why a golden layer matters

Everything I read pointed in the same direction: Dives work best on a golden layer, meaning data that is already cleaned, joined, and defined before the agent sees it. My own result fits that. With one flat table where joins and metrics were already done, the first working version took half an hour, and the quality surprised me.

The reason is simple. The agent does not have to guess join paths or decide how a metric is defined, so there is less room for wrong numbers. MotherDuck’s own tests on a small question set point the same way: agents with good context make far fewer query errors. That is the vendor’s benchmark, not independent proof, so treat it as a hint.

What this means in practice: put the effort into the data layer first, and the prompt second.

What my test did not cover

My data was a single flat CSV, uploaded by hand. That is the easy case for an agent.

Flights. Flights are scheduled Python jobs that run inside MotherDuck. An agent connected to the MCP server can write the pipeline, create the Flight, and schedule it. I did not need them for this test. If the data has to refresh on a schedule, that is where Flights would come in. They are in public preview, so check their status first.

Guides and the semantic layer. MotherDuck’s answer to the semantic layer question is Guides: versioned markdown documents stored in the warehouse that give agents business context, such as what a column means and how tables relate. With a pre-joined table, I had no need for them. How a Dive behaves across several raw tables is still untested.

Why it matters: a golden layer made my result possible. Multiple raw tables will be the real test, and I plan to try that next.

Where Dives fit, and where they don’t

• Cloud only. MotherDuck is cloud infrastructure. It runs in AWS regions across the US, Europe, and Asia Pacific, including Frankfurt and Dublin in Europe. You choose the region when you create the organization, and you cannot change it afterward. If data must stay on premises, it is not an option.
• Access control. MotherDuck has role-based access control. I only looked at it briefly, so check the documentation for how it applies to Dives. MotherDuck is SOC 2 Type II and GDPR compliant, with HIPAA BAAs available on request for Business plan customers.
• Cost. Pricing is pay-as-you-go. The Lite plan has no platform fee and includes 10 compute unit hours and 10 GB of storage per month. It is limited to the smallest instance type and 3 users. The Business plan costs $250 per month plus usage. Dives are available on all plans at no extra charge, while embedding needs Business.
• Workflow. You switch between your AI client and the browser, which does not match the otherwise integrated workspace.
• Verification. A generated dashboard can still be wrong. Check the SQL behind every number.

When I would still pick Superset

Superset is open source, self-hosted, and gives you full control over code, deployment, and where your data lives. I would still choose it when data has to stay on premises, when a project needs deep customization that you want to own, or when open source is a requirement. I would reach for a Dive when I want a fast, good-looking dashboard on a prepared data layer in the cloud.

Where this helps at arconsis: demos and proposals

Many of our customers work in regulated industries and have strict rules about their data. That limits what we can show them before a project starts. With anonymized or synthetic data, a Dive turns an idea into a working, branded dashboard within a day. In a proposal or a presentation, customers can click through an idea instead of reading a description.

Data location is one of the first questions customers ask. If you choose a European region when you create the organization, the data stays in the EU. Two cautions: the AI client you connect also sees your prompts and query results, so check that setup with the same care, and for demos I use anonymized data only.

Why this matters

Generated output only helps if you can check it. A dashboard still needs correct numbers, traceable logic, and controlled access. Dives give you the SQL and the code, so a review is possible. Whether the setup is enough for your data depends on your requirements, so test it with a small project first.

Takeaway

Superset and Tableau are not going away, and I still build custom plugins when a project needs full control. But the work that cost me a week, wiring tables, pivots, filters, and drill-downs, took me about a day in Dives, with two prompt revisions, including learning the tool. The result depends heavily on the data layer: with a golden layer behind it, a Dive worked very well for me.

The right tool depends on the customer: what they already run, where their data must live, and how much control they need. A Dive is one more option I can offer for quick, good-looking dashboards on a prepared data layer, and a fast way to turn an idea into something a customer can click through before a project starts. That leaves more time for the part that matters: checking that the numbers are right.

A week in Superset, a day in MotherDuck Dives was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

Watch a coding agent work on an unfamiliar repo and you see the same loop every time. It greps for a symbol. It reads a file, that file points somewhere else, so it reads that one too. Then it guesses, reads a third file to check the guess, backtracks. Four tool calls and twenty thousand tokens later it finally has enough context to make a one-line change.

That loop works fine until the repo gets big, and then you pay for it on every single task.

I’ve been running Graphify as a default on my projects for a while, and here’s the pitch I’d make to anyone still pasting files into context: your agent is redoing search work that a graph could have done once, ahead of time. A bigger context window doesn’t help with that. A map does.

The problem is the search, not the model

The standard way an agent gathers context is naive injection. Find the files that look relevant, dump them in, hope the answer is in there. On a small repo that’s fine. On anything real it falls apart for three reasons at once: you hit hard token limits, long contexts measurably degrade the model’s output, and cost and latency climb with every file you stuff in.

Retrieval-Augmented Generation (RAG) was the first answer. Instead of injecting everything, you chunk the codebase, embed the chunks, and retrieve only what’s semantically close to the question. That helps, but pure vector search has a blind spot that matters enormously for code: it finds things that look similar, when what you usually need is the things that are connected.

That distinction does most of the work here. When I ask “what breaks if I change this function,” I don’t want the five functions that read like it. I want the callers, the things it depends on, and where it sits in the architecture. Embeddings can’t give me that, because the relationship I care about is a call edge, an import, a dataflow. None of those has anything to do with surface similarity.

What a graph gives you that a vector store can’t

A code knowledge graph models the repo as typed nodes (symbols, files, modules, docs) joined by typed edges (calls, imports, depends-on, defines, uses). This is the code graphRAG pattern, and once the graph exists, questions that used to be a cascade of reads collapse into a single traversal.

“What depends on this, directly and indirectly?” becomes a reverse walk instead of a dozen greps. “How do these two modules connect?” is a shortest-path query. “Where’s the architectural heart of this system?” falls out of degree counting, the high-connection “god nodes” that usually mark your coupling problems.

The payoff is concrete, and it lands on the context window, the one resource you can’t buy more of. The agent’s blind exploration loop (search, read, read, guess, read) collapses to a query or two. Every token the agent spends finding the code is a token it can’t spend changing it, and a graph moves that finding cost out of the hot path and pays it once.

There’s a measured number behind this. On a mixed corpus of code and papers, Graphify gets a 71.5× reduction in query-time tokens versus injecting whole files: a subgraph query that costs around 1.7k tokens replaces around 123k tokens of naive context. Even if you discount the exact figure, the win is one to two orders of magnitude. A change that size reorganizes how you work; it isn’t a 10% tuning tweak you’d squint at on a dashboard.

How I actually use Graphify

Graphify is a Python tool (MIT-licensed, Tree-sitter parsing across 19+ languages, NetworkX under the hood) that ships as a Claude Code skill. You point it at a repo and it runs a single pipeline: detect files, extract nodes and edges, build the graph, cluster it with the Leiden algorithm, analyze for hubs and surprise edges, write a report, and export.

You get back three artifacts, and they’re the reason I like it:

• graph.json: the queryable graph itself. It's portable, so you can commit it, ship it to a remote agent, or grep it.
• GRAPH_REPORT.md: a human-readable map of the god nodes, the surprising edges, and suggested questions to ask the codebase.
• graph.html: an interactive visualization for when I want to eyeball the structure myself.

Day to day I’m mostly in the query commands: graphify query "what connects auth to the database?", graphify explain "SomeSymbol", graphify path "A" "B". On a new repo, reading GRAPH_REPORT.md first does more for my orientation in two minutes than half an hour of clicking through folders.

One design choice is what makes this usable at work: only semantic descriptions ever leave the machine, and the raw source stays local. If you’re somewhere you can’t ship proprietary code upstream, that constraint is the whole reason you’d be allowed to use a tool like this at all.

The fork in the road: a map or an oracle

Graphify isn’t the only way to do this, and the main alternative is worth looking at because it comes from a genuinely different philosophy. CodeGraph (Rust, SurrealDB for a fast vector index, exposed as an MCP server) doesn’t hand you a graph. It hands you four questions (agentic_context, agentic_impact, agentic_architecture, agentic_quality) and runs its own reasoning agent inside the indexer to answer them with citations.

The split is worth deciding on deliberately:

Graphify CodeGraph What you get back an inspectable graph a synthesized answer Where the reasoning lives your outer agent inside the indexer Strength portability, token cost, privacy answer quality, low caller load Operating cost lightweight, local a service to run (DB + reasoning LLM)

Graphify treats the graph as a portable artifact and keeps your agent the smart one. CodeGraph absorbs the search-and-synthesis work and hands back “what depends on UserService and why,” file and line included. Reach for the first when you want to inspect and ship the graph, when privacy is non-negotiable, or when your agent already reasons well and just needs a smaller haystack. Reach for the second when your outer agent is context-constrained, or when you want boundary enforcement and architectural fitness signals as first-class features.

I default to Graphify. The portability and privacy posture line up with how I work, and unless your outer agent is too context-constrained to do the reasoning itself, it’s where I’d tell you to start.

Where it’s worth it, and where it isn’t

I won’t pretend this is free or universal. On a small repo the agent can hold in its head, the graph is overhead for no gain, so skip it. And the honest caveats stack up: nobody’s published a head-to-head benchmark on answer correctness, indexing a 500k-LOC monorepo isn’t instant, and CodeGraph’s promise to hand back synthesized answers instead of search results leans on a capable reasoning LLM, so a weak local model collapses it back into fancy search.

Where it earns its place: large or unfamiliar codebases, onboarding, impact analysis before a risky change, and any workflow where you’re feeding one well-scoped prompt to a remote or context-limited agent. That covers most of what I do on a serious project, which is why I leave it on by default.

Where this leaves you

If you run agents on a large codebase, the missing graph layer is a line item you’re already paying in latency, token spend, and the answers a bloated context quietly degrades. You just haven’t named it yet. The bottleneck was never model size. It’s the blind search your agent runs before it touches a line of code, and a graph pays that cost once instead of on every task.

The map-or-oracle choice is cheaper to make now than to unwind after your first agent-driven feature ships, so make it deliberately: a portable graph you inspect and ship (Graphify), or a reasoning service that answers questions (CodeGraph). But either one beats the real default, which is no graph at all.

Your agent is already mapping your codebase on every task you hand it, one grep at a time, badly. Hand it a real one.

Give your agent a map: why your codebase needs a knowledge graph was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

I had 34 Claude Code skills sitting in one flat folder. They were symlinked into ~/.claude/skills straight out of my dotfiles repo, so editing a skill meant editing the repo and the change went live on the next session. Nice and simple.

The names had grown ugly, though. coding-conventions, coding-tdd, second-brain-ingest, swiftui-pro, swift-testing-pro. The prefixes were the only grouping I had. They weren't categories, just a naming convention I'd talked myself into.

So I asked what felt like an obvious question: can I just make subfolders? Drop tdd into a coding/ folder, ingest into second-brain/, and let the folder be the category?

The answer is no. And chasing why it’s no led me somewhere much better.

A quick note on scope. This is written for people who manage their own Claude Code setup out of a dotfiles repo and want their skills grouped without giving up live edits. If you’re a team packaging skills for other people to install, you want a marketplace and most of what follows won’t apply to you. And because plugin specifics move fast: everything here was verified on Claude Code 2.1.170, so check your own version as you read.

The dead end

Claude Code discovers skills flat. It walks the skills directory, and for each folder that holds a SKILL.md, the folder name becomes the invocation name. That's it. There's no recursion into category subfolders, no notion of a parent group.

So skills/coding/tdd/SKILL.md does not give you a coding category with a tdd skill inside it. At best the discovery just doesn't find it. My naive mental model (folders are categories) simply isn't the model the tool uses.

That’s annoying, but it’s also a useful forcing function. If the filesystem won’t carry the category, something else has to. The question becomes: what’s the actual mechanism for grouping skills, and does it survive a symlinked dotfiles setup?

Three ways Claude Code loads skills

It turns out there are three, and they’re easy to conflate. Here’s the whole picture:

Why the marketplace is a trap for personal setups

This is the counterintuitive part, so it’s worth being concrete about it.

When you install a plugin from a marketplace, Claude Code copies it into ~/.claude/plugins/cache/. Your repo is no longer the live source. Edit a skill in your dotfiles and nothing happens until you run /plugin marketplace update. For a collection I tweak constantly, that copy step quietly kills the one property I cared about most.

It gets worse for a dotfiles bootstrap. Adding a marketplace and installing from it trigger interactive trust prompts. On a fresh machine, where I want a non-interactive script to lay everything down, those prompts block the whole thing.

And none of that ceremony buys me anything. Marketplaces exist to distribute to other people and to pin versions. I’m distributing to exactly one person, me, across machines I already trust. I’m paying for publishing infrastructure I don’t use.

The skills-directory plugin, concretely

Here’s the mechanism that does what I want.

Any folder directly under a skills directory that contains a .claude-plugin/plugin.json loads as a plugin on the next session. No install, no registration, no trust prompt. (claude plugin init <name> scaffolds the manifest if you don't want to write it by hand.)

The namespace comes from the name field in plugin.json. A plugin named coding exposes its skills as coding:tdd, coding:conventions, and so on. Same for agents: coding:pr-reviewer.

And it’s a full plugin, not a skills-only thing. One bucket can carry skills and agents and commands and hooks, all namespaced together. That last part matters more than I expected. My agents could move inside the same bucket as the skills they relate to.

Because discovery happens in place rather than by copying, the symlink workflow survives intact. Symlink the bucket into ~/.claude/skills/, and Claude Code follows the link and reads the files where they really live. Live edits work.

The dotfiles change is one line

# before: one symlink for everything, flat, no namespaces
ln -sfn "$DOTFILES/DragonAgents/skills" ~/.claude/skills
ln -sfn "$DOTFILES/DragonAgents/agents" ~/.claude/agents

# after: point at the buckets' parent; each bucket auto-loads, namespaced.
# agents now live inside their buckets, so the agents symlink goes away.
ln -sfn "$DOTFILES/DragonAgents/plugins" ~/.claude/skills

Two symlinks become one. The agents symlink disappears entirely because agents are part of the buckets now.

I didn’t trust the docs, so I ran a smoke test

The behaviour above is the kind of thing that’s easy to get subtly wrong, especially the “agents load too” and “symlinks are followed” claims. Before migrating 34 skills, I built a throwaway bucket and checked.

# bucket layout:
#   coding/.claude-plugin/plugin.json
#   coding/skills/hello/SKILL.md
#   coding/agents/echo-bot.md

ln -sfn /tmp/.../coding ~/.claude/skills/smoketest-coding

claude plugin list
#   -> smoketest-coding@skills-dir, enabled, installPath = the symlink

claude plugin details 'smoketest-coding@skills-dir'
#   Component inventory: Skills (1) hello | Agents (1) echo-bot
#   Projected token cost: always-on ~78 tok

That confirmed all three things at once: discovery works through a symlink, it reads in place rather than copying, and agents load from a skills-directory plugin, not just skills.

Two things I learned here are worth keeping:

First, claude plugin list and claude plugin details run as fresh processes. They trigger discovery on their own, so you can verify a newly-dropped plugin without restarting your running session.

Second, claude plugin details reports a projected token cost per component: always-on versus on-invoke. That's a real budgeting tool. It tells you how much context each bucket costs you just by existing, before you've invoked anything.

Migrate less: the dedup pass

Here’s the part I almost skipped, and I’m glad I didn’t. Before moving anything, I shrank the surface area.

The repo had the same capability expressed three different ways. Take code review: there was a review skill, a pr-review command, and a pr-reviewer agent. The skill and the agent carried near-identical bodies. They'd already drifted apart, so they didn't even agree with each other anymore.

That’s the teachable moment, because it forces you to be honest about what each of these things is actually for:

• A skill is a reusable procedure or piece of expertise. It runs inline in your context, and it auto-triggers from its description.
• An agent (subagent) is a separate context window with its own tool sandbox. You reach for it when you need isolation (its file-reading doesn’t bloat your main context, only its summary comes back), tool restriction (read-only, say), or parallel fan-out.
• A command is a saved prompt behind a typed trigger. Pure glue. And it’s largely superseded by skills, which can both auto-trigger and be invoked as /name.

Commands and agents predate skills. That’s why old setups like mine accumulate redundant pairs: I built the agent before the skill existed, then built the skill and never deleted the agent.

The fix is a clean, reusable pattern. Keep the procedure in the skill, and make the agent a thin wrapper that loads the skill and adds only what’s genuinely its own: the isolation, the tool limits, an output override. My oss-scout agent is the example of this done right: about 20 lines that just run the oss-research skill in a subagent. The procedure lives in one place.

I went through and deleted:

• 4 slash commands, thin launchers I never actually typed.
• 1 agent (pr-prepper) that nothing invoked.
• 2 skills (second-brain-lookup, second-brain-propose) that were orphaned. The three agents they'd been built for had been removed in an earlier migration, so nothing called them anymore.

That last cut is the one I want to underline. Those two skills weren’t obsolete. The audit found nothing technically wrong with them. They were just dead by usage: no agent invoked them, so they were weight with no lever. A well-designed skill you never call is still dead weight. Trim by usage, not only by obsolescence.

The net: ~34 skills, 6 agents, 4 commands became 32 skills, 5 thin agents, 0 commands, with each capability’s procedure living in exactly one place.

The payoff

What I ended up with is six namespaced buckets, each a skills-directory plugin: coding, swift, planning, writing, obsidian, second-brain.

Here's the shape of it on disk:

DragonAgents/plugins/                    # ← the one symlink, into ~/.claude/skills
├── coding/
│   ├── .claude-plugin/plugin.json       #   name: "coding"  → coding:*
│   ├── skills/
│   │   ├── tdd/SKILL.md                 #   → coding:tdd
│   │   ├── conventions/SKILL.md         #   → coding:conventions
│   │   └── review/SKILL.md              #   → coding:review
│   └── agents/
│       ├── pr-reviewer.md               #   → coding:pr-reviewer
│       └── oss-scout.md                 #   thin wrapper over oss-research
├── swift/
│   ├── .claude-plugin/plugin.json       #   name: "swift"   → swift:*
│   └── skills/
│       ├── ui/SKILL.md                  #   → swift:ui      (was swiftui-pro)
│       └── testing/SKILL.md             #   → swift:testing (was swift-testing-pro)
├── planning/
├── writing/
├── obsidian/
└── second-brain/
```

Invocation now reads the way I always wanted it to. coding:tdd. second-brain:ingest. swift:ui. The namespace carries the category, so the old prefixes just fall away (coding-conventions becomes coding:conventions), and the Swift skills get normalized along the way: swiftui-pro to swift:ui, swift-testing-pro to swift:testing.

The grouping is a namespace now, instead of a naming convention I was enforcing by hand. That’s the whole difference. The category used to be a string I prepended and hoped everyone respected. Now it’s structural, and the tool enforces it for me.

I wrote the decision down as an ADR in the repo, so future-me doesn’t re-litigate the marketplace question from scratch in six months.

A few honest caveats

• Plugin specifics move fast (I verified against 2.1.170, noted up top). Date your post and check your own version before trusting the exact command output.
• Skills-directory plugins are the right call for personal use. If you’re genuinely distributing to other people, a marketplace is correct. That’s what the versioning, trust, and discovery machinery is for.
• Renames have a cost. Agents reference skills by name, so when you rename a skill you have to update those references in lockstep or you’ll break the wiring. Do them together.

If you’ve got a flat pile of skills and you’ve felt that prefix-naming itch, this is the way out. You don’t need a marketplace. You need a manifest and one changed symlink.

I hope this saves you the dead end I walked into 😉

Claude Code skills don’t do subfolders — here’s what to do instead was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

You ask a hard question that wants more than one kind of expert. Should we adopt Rust for our backend? A good answer needs an engineer on feasibility, someone on cost and ROI, someone on the market, someone on the failure modes. The obvious way to get those four takes from a model isb to ask for them one prompt at a time, or to cram them into a single mega-prompt and hope the model wears four hats at once.

Both are wrong. Asked one at a time, you wait four times as long for no reason; none of those analyses needs another to start. Asked all at once, you get a flattened, hedged answer where every perspective bleeds into the next. The fix is the oldest trick in distributed systems, pointed at LLMs: fan the work out, run it concurrently, fan the results back in. That’s the parallel / concurrent multi-agent pattern, and the Rust question above is the example I’ll build out as we go. This is the pitch for when to reach for it, and the honest account of when it’ll hurt you.

What the pattern actually is

Strip it to the shape and it’s two moves: fan-out and aggregate. You take one input and hand it to N specialist agents (each just one LLM doing one job) that run at the same time. Then you feed all their outputs to one coordinator: a final LLM call that reads everything and writes a single answer.

The specialists don’t have to be different models — they can be, but they don’t need to be, and often aren’t. What actually differentiates them is the system prompt (the standing instruction that fixes each agent’s role before it ever sees the question), not the model underneath; run all five on the same model and the pattern holds just fine. That one choice is the whole engine. For the Rust decision, you stand up five agents, each pinned by its system prompt to a single lens: technical feasibility, cost and ROI, market, risk, and UX. None of them is a general “analyst.” Each is told what to cover and, just as important, what to leave alone.

Here’s the whole input, so it’s concrete. One question fans out to all five agents, unchanged:

Should we adopt Rust for our backend services?

and each agent carries a one-line system prompt that fixes its lane:

• technical-feasibility — can our stack and team actually ship and run it? Leave cost and market alone.
• cost-ROI — migration effort, hiring, long-run savings. Leave the technical merits alone.
• market — who else has adopted it, what it signals, how deep the talent pool runs.
• risk — what breaks, what’s irreversible, the worst cases. Failure modes only.
• UX — what users actually feel: latency, reliability, stability.

No agent sees another’s prompt or answer; every one of them sees only that single question. That’s the whole worked example — the rest of this piece is what happens to those five answers.

That role-per-agent split is deliberate, and it’s worth being concrete about why it beats one prompt asking for “a thorough analysis.” A lens that owns its own system prompt and its own context window (the limited span of text a model can hold in mind at once) spends all of that budget on one thing: the risk assessor hunts failure modes for its entire run instead of giving them one balanced paragraph and moving on. You also get coverage you can name and audit. With five named seats at the table, you can check at a glance that every angle is actually covered — and if you’d forgotten to give UX a seat, that gap stares back at you, instead of hoping UX surfaced somewhere in a single agent’s wall of text. And because each agent is sealed off, seeing only the original question and never another agent’s output, the five reads stay genuinely independent. The coordinator is the only place the threads ever meet.

That isolation is the whole point, and it’s worth saying out loud because it’s counterintuitive: the agents are better for not communicating. Diversity of thought is the product here. Five experts who can’t see each other’s notes give you five independent reads; five who can immediately start converging on the loudest one. On the Rust question that independence is exactly what surfaces the real tension: technical-feasibility comes back enthusiastic, cost-ROI comes back wary of the migration bill, and risk flags the thing neither of them was looking at — the hiring pool for Rust engineers is thin. Let them confer first and the loudest voice sands that disagreement down; keep them apart and the coordinator gets all three and has to reconcile them out loud.

Why not just run them in sequence

Because nothing forces you to. Running them in sequence (agent one finishes, then agent two starts) is the right call when step B needs step A’s output. Here it doesn’t. Each analysis stands alone, so paying for them one after another is pure dead waiting.

Single-agent-broad-prompt is fast but shallow; it’s the mega-prompt that hedges. Sequential gives you depth but makes you wait. Parallel is the only row that gets all three, and the speedup is real but bounded: in practice it lands around 2–4× versus sequential, because your total time is set by the slowest single agent plus the coordinator, not the sum of all of them. One slow specialist caps the whole run. It’s the old rule from parallel computing in miniature: the one step you can’t split up, the final synthesis, sets your floor no matter how many agents you add.

How it’s wired

This section is for whoever builds it. If you don’t write code, the three headers below (stateless agents, resilient fan-out, event-driven streaming) are the whole takeaway; skip the snippets and meet me at “The economics.”

A minimal version of this wires up on LangGraph (a library for connecting LLM steps into a graph) as a static fan-out/fan-in shape, the same diagram you’d draw on a whiteboard:

START ──┬── technical-analyst ──┐
        ├── financial-analyst ──┤
        ├── market-researcher ──┼── synthesize ── END
        ├── risk-assessor ──────┤
        └── ux-strategist ──────┘

The start fans out to every agent at once, every agent feeds into synthesize, and synthesize runs only once all of them have finished. Three design decisions are what make it hold up in practice, and they're the parts worth stealing even if you never touch LangGraph:

Stateless agents

Each agent receives only the question and its own system prompt. No shared scratchpad, no cross-talk. That’s what makes the thing trivially parallel: there’s no shared state to fight over, so adding a sixth specialist is one more system prompt and zero coordination changes. This is the same statelessness-per-step discipline that shows up everywhere in reliable agent systems (the Ralph pattern takes it to the extreme: a fresh agent per task, with everything it needs written to disk instead of carried in memory).

Resilient fan-out

Every agent handles its own errors and returns a “failed” marker instead of crashing. A rate-limited or timed-out specialist doesn’t take the whole run down; the coordinator just synthesizes from the four that came back. One expert being out sick shouldn’t cancel the meeting. The mechanism is small: as each result lands it’s simply appended to the list of results, so a missing one is a normal, handled case rather than a crash.

Event-driven streaming

The orchestrator emits a stream of typed events (agent started, agent produced a chunk of text, agent finished, synthesis started, and so on) instead of going silent and returning one blob at the end. That separates the work from how you watch it: one engine can feed a web page, a terminal view, or a logging script without changing the core. You see each agent’s text appear live instead of staring at a spinner.

The economics, stated honestly

This pattern is a way of spending money to buy time. Every call to a model is billed in tokens (the chunks of text it reads and writes), and the meter runs on both what you send in and what comes back. N specialists plus one coordinator is N+1 calls for what a single agent would do in one. You don’t get the answer cheaper; you get a better, faster answer for more tokens.

Anthropic’s own write-up of their multi-agent research system is the cleanest data point I’ve seen on the cost: their setup, with one lead agent directing several worker agents, outperformed a single agent by 90.2% on research tasks, and it burned roughly 15× the tokens of a normal chat. They go further and credit about 80% of the performance difference to token usage alone. The architecture is, in their words, a way to throw more computation at the problem (Anthropic, “How we built our multi-agent research system”, accessed 2026–06–17).

So the rule I’d write on the wall: parallelism only pays off when the task genuinely breaks into independent pieces. If the pieces lean on each other, the 15× just buys you a pile of clashing assumptions.

When it bites back

Which is exactly the argument Cognition (the team behind the Devin coding agent) makes in their post “Don’t Build Multi-Agents,” and you should take it seriously before you fan anything out. The claim is sharp: every action an agent takes carries a hidden decision, and agents working in parallel make conflicting ones. Agents with no view of each other’s work each quietly assume things: about scope, about what the question means, about what “the system” even is. Stitch their outputs together and those assumptions clash. Their recommendation is to keep things to a single agent that sees the full history (compressing it when it gets too long), on the principle that every step should ideally see everything else (Cognition, “Don’t Build Multi-Agents”, accessed 2026–06–17).

This is the dividing line for using the pattern. It’s safe precisely where the work is read-only and independent: analysis, review, assessment, research. Five agents reading the same proposal and reporting back can’t conflict, because none of them is changing anything; the coordinator reconciles their opinions, and disagreement there is a feature. The danger zone is write-heavy, interdependent work, coding being the obvious one, where two agents editing in parallel make incompatible changes to the same file and there’s no clean way to merge them. Anthropic landed in the same place from the opposite direction: their system shines on research that splits into parallel strands and is less effective for tightly coupled work like coding.

So: parallel agents to think, not to act. The moment your pieces have to agree on a single changing thing, you want them in sequence, or one agent with the full picture instead. One internal orchestrator we run draws the line in exactly this spot. It runs four reviewers (security, performance, correctness, architecture) in parallel, because reviewing is independent, then funnels them through a single synthesizer and a final check before anything is trusted. Read concurrently, decide centrally.

Even inside the safe zone, the pattern has failure modes worth designing against:

• Redundant analyses. Specialists with fuzzy, overlapping instructions produce near-identical takes. Fix it by making each one explicit about its lane and what it must not cover.
• Coordinator bias. The synthesizer over-weights the longest or most confident analysis. Make it address each perspective in turn, and consider trimming everyone to a similar length.
• Silent partial failure. An agent dies and the coordinator never mentions the missing perspective. Tell the coordinator which agents succeeded, and have it flag reduced confidence when one is absent.

Where it earns its place

Reach for the parallel pattern when three things are true at once: the task wants multiple independent perspectives, the pieces don’t depend on each other, and wall-clock time matters. Decision support, multi-lens document review, due-diligence assessments, anything where you’d otherwise convene a panel of humans. That’s the sweet spot, and both the speedup and the diversity of thought are real.

Skip it when the task is inherently step-by-step, when the agents need to debate and converge (a different pattern), or when one agent already suffices. And the big one: skip it when the pieces have to change the same shared thing, where the 15× cost premium buys you conflict, not coverage.

Mechanically, the pattern is simple: kick off all the agents at once, wait for them to finish, and hand the pile to a synthesizer. The work is in the discipline around it. Keep the specialists independent, make the run survive a dropped agent, give the coordinator enough to flag what’s missing, and fan out only the work that’s genuinely independent. Get that right and one slow, hedged answer becomes several sharp ones, reconciled into a single verdict. Build it once, point it at a decision that deserves five expert opinions, and let them argue in parallel.

Spend tokens to buy time: the parallel agent pattern was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

Part 2: A Real Feature, End to End: the Trending Badge.

In Part 1, we described the Agent Orchestration Framework we built for arconsis Eats: the agents, the lifecycle, the file-based state, and the safety rails. Here we let it run. The feature is a Trending Badge on restaurant feed cards. The pipeline is the same one we just described. Everything below is what actually happened.

A Real-Life Example: The Trending Badge

The feature itself is simple to describe: a "Trending" pill appears on a restaurant's feed card when it has seen a burst of recent review activity. The user-facing surface is small. The cross-module work is not.

How the architect planned it

The architect produced plan.md, 153 lines of file paths, function signatures, and acceptance criteria, along with the corresponding state.json. There were no open questions: the product decisions were all resolvable by sensible defaults. A 7-day window, a 3-review threshold, both tunable via application.properties:

eats.trending.window-days=7
eats.trending.min-reviews=3

The slice graph it came up with had six steps, each depending on the one before:

• backend-domain: backend-author implements the server-side trending logic
• backend-tests: qa-tester adds test coverage for the new backend behavior
• shared-contracts: kmp-shared-author updates the shared DTO layer
• api-client-data: api-client-author propagates the field through the client cache and repository
• frontend-ui: frontend-author renders the badge in the Compose UI
• final-integration: code-reviewer reviews the full branch as one integrated system

Two things stood out in the plan.

First, no migration. The architect figured out the trending flag is derivable from the existing reviews table through a GROUP BY place_id HAVING count(*) >= :minReviews query scoped to the window. The plan explicitly forbids creating a new migration file. If a reviewer sees one, that's a defect.

Second, it flagged a cross-caller risk ahead of time. The trending flag would be computed in the home feed, but the profile screen renders the same reviews through a different code path. If that second path wasn’t updated, the same restaurant could show as “Trending” on the feed and not trending on your profile, for the exact same review data. The architect explicitly noted this in the reviewer instructions before any code existed. That’s the kind of seam that’s invisible when you’re reviewing one slice at a time.

The plan reviewer caught an issue on the first pass. The command ./gradlew :shared:compileKotlinMetadata is a SKIPPED no-op task on this project. The architect re-ran, swapped it for :shared:compileCommonMainKotlinMetadata, and the second pass got APPROVE_PLAN.

What each agent committed

The branch history tells the story. Each agent’s work is one or two commits: a feat: commit with the production change, and a chore(infra): checkpoint that records the slice's state transition. 13 commits total, every slice checkpointed, every verdict preserved.

695c6aa chore(infra): complete frontend-ui layer for trending-badge
fff2b69 feat(frontend): add trending badge to home feed cards
7a7fadf chore(infra): complete api-client-data layer for trending-badge
e049c5c feat(api-client): propagate isTrending through client cache layer
36f1305 chore(infra): complete shared-contracts layer for trending-badge
a003958 feat(kmp-shared): add isTrending field to ReviewResponse DTO
d80ba57 chore(infra): complete test layer for trending-badge backend
33bdd57 chore(deps): move MockK to version catalog and record review state
c0efe61 test(server): fix reviewer-rejected test issues for trending-badge
f8b0d40 fixup(server): replace @QuarkusTest with pure MockK unit tests
c0dc778 test(server): add trending-badge test coverage for FeedService
1e82dfb chore(state): update trending-badge progress for backend-author
c578d7d feat(server): add trending badge flag to feed responses

A quick note on those commit messages. Every one follows the commit-messages skill we built: conventional-commit prefixes, subject under 72 characters, body that explains why, plus Slice: and Agent: footers. This isn't cosmetic. Six months from now, when someone runs git blame on ReviewResponse.isTrending, the commit message will explain the backward-compatibility reasoning.

🔴 backend-author

The first slice extended the backend API to support trending places. The agent added a query to identify places with a spike in recent review activity, wired the result into the feed response, and made sure the trending flag flowed through every path that returns review data to a client. No migration needed; the data was already there. Server compiles clean.

🟡 qa-tester and the retry loop that earned its keep

This is the slice where the framework proved its value.

Attempt 1. The qa-tester wrote integration tests per the plan, but hit an environment issue: Docker wasn’t running, so the database-backed test setup couldn’t start. Fair enough. The agent pivoted to unit tests with a mocking library, but introduced two problems in doing so: it added the new test dependency by hardcoding a version directly in the build script, bypassing the project’s pinned dependency catalog, and it quietly dropped the test that was supposed to verify feed/profile parity, the exact cross-layer seam the architect had flagged as the highest-risk integration point.

The code-reviewer rejected it. Both findings were BLOCKING.

Attempt 2. The agent fixed both: the dependency was moved into the version catalog where it belonged, and the missing parity test was written properly, covering the scenario where the same restaurant shows up on both the home feed and a user’s profile, and verifying they agree on its trending status. 21 tests, 0 failures. Re-review → APPROVE.

The honest take: the agent got it wrong the first time, and that’s fine. The framework caught it. The findings were specific enough to fix without a human round-trip. The retry cost about $3 on top of the original $2.37, versus a human catching it in PR review three days later, or worse, it landing on main and silently degrading coverage.

🟦 kmp-shared-author

The smallest slice in the branch was a single new field added to the shared DTO that both server and clients rely on. The code was trivial. The reasoning in the commit message was the point: the field needed a default value not for convenience, but for backward compatibility. Older installed app builds receiving a payload that doesn’t yet include the field must not crash. They should just silently treat the place as non-trending. The agent got this right and explained why in the commit, which matters more than it sounds six
months from now when someone wonders if the default is safe to remove.

🟢 api-client-author

The client slice threaded the trending flag through the offline cache layer and up to the repository that the UI reads from. The key concern here was the same backward-compatibility one: the cached data model also needed a default so that older locally-stored payloads wouldn’t break on app update. No new infrastructure, no new dependencies. Just making sure the new field traveled all the way from the network response to the UI without getting dropped.

🟠 frontend-author

The final slice rendered the badge in the Compose UI. The agent overlaid a “Trending” pill on the place photo in the feed card, and handled accessibility correctly. The badge is announced as a single unit by screen readers rather than reading the icon and label separately.

One deliberate choice: the trending field was added to the UI model without a default value, which forces the compiler to catch any mapping function that forgets to pass it through. Defaults are convenient; their absence is a contract.

What the final integration review caught

The code-reviewer’s review.md ran the whole branch against origin/develop. Verdict: APPROVE, no critical or major issues. Six nits, three worth mentioning.

It caught a minor issue where a service function was accepting a parameter it never actually used. Small thing, but it creates real cognitive overhead: anyone reading that code later would naturally assume the function’s behavior depends on what you pass in, when it doesn’t.

There’s no empty-feed short-circuit. A user with zero reviews still triggers a JPQL round-trip to compute trending places. One-line fix, but the kind of thing that adds up at scale.

And the finding that points back at usω: the MockK catalog edit straddles the automation boundary. The framework handled it eventually, but the architect should have anticipated the missing test dependency in the first place. That’s a prompt update for next time, not a framework limitation.

The numbers

The full feature, from /feature trending-badge to integration-review approval:

Wall time was about 4.5 hours, of which maybe 30 minutes required a human present. Total tokens: 24.2 million (22M cache-read, 2M cache-write, 192k output). Total cost: $22.33, roughly $13.50 on Opus for the architect and reviewer, $8.83 on Sonnet for the authors and tester. There were 5 retries across the whole pipeline (the plan got revised twice, the backend-tests slice took three attempts). The feature touched 10 production files and added 3 test files.

The retries move the cost. A first-pass slice runs $0.30–$0.70. A reviewer rejection adds $1.50–$2.00. The MockK round-trip alone (plan-review retry, qa-tester retry, re-review) was about $7 of the $22.

We’d take that trade. The alternative, a human catching the catalog-edit issue in PR review three days later, isn’t free either.

What the framework still doesn’t do

iOS-native code is out of scope. Swift, SwiftUI, signing, provisioning: the architect emits OPEN QUESTION: and stops. Platform-specific Compose (androidMain / iosMain / jvmMain), like cameras, file pickers, push notifications, anything needing expect/actual, is a human job. Gradle and version-catalog edits straddle the boundary, as the MockK incident demonstrated. CI/CD workflow edits are out of scope entirely.

And the agents still make mistakes. The qa-tester missed the cross-caller test. The reviewer missed the unused computeTrendingFlags parameter on the first per-slice pass and only caught it in the final integration review. The framework's value is catching mistakes through layered review, not preventing all of them.

The framing we keep coming back to: this is a delivery pipeline, not an autonomous engineer. The pipeline does planning, sequencing, writing, verifying, reviewing, checkpointing. The human does the judgement calls: approving the plan, adjudicating two-strikes rejections, pushing the branch, opening the PR. That’s a much smaller surface than “build me a feature,” and a much bigger lever than “autocomplete my next function.”

What we got out of this wasn’t a snippet or a half-built prototype. It was a working feature across every layer of a real Kotlin Multiplatform system: backend logic, shared contracts, client integration, and the UI. Think of it as a marathon. The pipeline carries you through the first 41 kilometers: design, implementation, and the cross-module coordination that usually eats the most time. The last kilometer is still yours. You review with fresh eyes, fix the edge cases, fight over naming, and decide whether the result clears the bar you’d actually ship against. The framework doesn’t remove that work. It makes sure that’s the only work left.

The trending badge took five slices, one retry loop, about five hours of mostly-unattended runtime, and $22 of API cost. The branch was green on /verify the first time we ran it. The next morning we opened the PR.

We didn’t ask an AI to build it. We gave it a pipeline.

Stay tuned!!

Special thanks to my colleague Alex Koufatzis for co-authoring this series.

We Didn’t Ask an AI to Build a Feature. We Gave It a Delivery Pipeline. was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

Part 1: The Framework: seven AI agents, file-based state, and one human gate.

At arconsis, we spend a lot of time thinking about the tools, frameworks, and practices that shape how software actually gets built, across very different customer contexts: e-commerce, automotive, finance, healthcare. The question we keep coming back to, regardless of the stack, is always the same: what does it take to deliver software that is reliable, maintainable, and honest about its trade-offs?

AI-assisted development is the latest thing forcing that question into the open. And honestly, we’re not interested in it for the novelty. “An LLM wrote a function” stopped being interesting around the time autocomplete grew a brain. The real question, the one our customers will eventually ask us about, is whether AI agents can meaningfully contribute to a real production codebase. One with multiple modules, strict migration discipline, cross-platform targets, conventions that took years to settle, and a definition of “done” that includes things like backward compatibility for already-installed builds. That’s a very different problem from generating a snippet.

So this article isn’t a model benchmark or a tool comparison. It’s about process: how we structured agent collaboration so that the output is reviewable, auditable, and recognisable as code our team would have written by hand. To make any of that concrete, we did the obvious thing: we built the framework against one of our own Kotlin Multiplatform projects and let it ship a real feature end to end. Everything below comes from that exercise.

The arconsis eats App

is one of our internal apps, a restaurant-discovery product we also use as a sandbox for tooling questions like this one. The shape of the codebase is what makes it useful for the experiment, not the product itself.

It’s a Kotlin Multiplatform monorepo with three layers. server/ is a Quarkus backend with a Flyway-managed database. Migrations are forward-only, no exceptions. shared/ is a module with the serializable DTOs that both server and clients use. composeApp/ is a Compose Multiplatform UI targeting Android, iOS, and Desktop, with an offline cache layer in between.

Those three layers have a strict dependency order: server → shared → client → UI. A single feature can require changes at every level, and each layer has to be correct before the next one can build against it.

This is exactly the kind of codebase where unsupervised AI coding (vibe-coding) falls apart.
If a client-side field name drifts from what the server actually emits, nothing fails at build time. The server emits isTrending, the client deserializes is_trending, everything compiles green. You find out in production.

A model allowed to “just keep coding” through a stack like this leaves you with a green build and a broken product. The question isn’t “can it write Kotlin?” It’s whether it can ship a feature without you watching every keystroke.

The Agent Orchestration Framework

A pipeline, not a prompt

We didn’t build an AI that writes features. We built a delivery pipeline that uses AI agents as a team:

architect → author → verify → review → fix → checkpoint → integrate → CI gate.

Each step has a defined input, a defined output, a verification command, and a place to write its findings. None of the steps are “an LLM decides what to do next.” Routing is a deterministic Markdown state machine. LLMs do the work. They never decide what work happens.

The agents

The roster lives in .claude/agents/. Each agent is one Markdown file with a role description, allowed tools, and the prompt the model loads when invoked.

The 🔵 architect (Opus) reads the codebase and produces the plan and the slice graph. It understands the system, decides what needs to change, and never touches production code.
The 🔴 backend-author (Sonnet) owns the server layer: database schema, business logic, and API endpoints.
The 🟡 qa-tester (Sonnet) writes unit and integration tests.
The 🟦 kmp-shared-author (Sonnet) owns the client-server contract, making sure field names match the server JSON exactly.
The 🟢 api-client-author (Sonnet) takes those contracts and wires them through the client data layer: network calls, local cache, and the repository the UI reads from.
The 🟠 frontend-author (Sonnet) builds the screens and view logic that the user actually sees.
And the 🟣 code-reviewer (Opus) reviews the plan, every per-slice diff, and the final integration diff, but never writes a line of code.

The Opus/Sonnet split is deliberate. Opus does judgement: planning and reviewing. Sonnet does throughput: writing code against a clear spec. The cost breakdown below shows it paying off: about 60% of the spend goes to Opus on the architect and reviewer, 40% to Sonnet on the actual code.

The lifecycle of a feature

One command starts the whole thing:

/feature trending-badge "Show a Trending badge on feed cards for popular places"

That looks like a prompt.

It isn’t.

In our framework, /feature is not a request for an LLM to “go build something.” It is the entry point into a deterministic delivery pipeline. The command validates the repository state, creates the feature branch, and immediately kicks off the first three steps of the workflow: the architect reads the codebase and produces the plan, the reviewer sanity-checks that plan before a single line of code is written, and then the pipeline pauses for human approval. Only after that gate does implementation begin, dispatching the right author agents in dependency order, enforcing verification at every slice, recording checkpoints, and finishing with a full integration review.

The important part isn’t that an AI writes code. It’s that the AI operates inside a workflow that looks much closer to CI/CD than chat.

Here’s what happens, end to end.

Start clean. Before any model is invoked, the framework checks the basics: clean working tree, branch cut from develop, no uncommitted changes for an agent to accidentally overwrite. If any of that isn't true, the workflow stops. A surprising amount of "AI went off the rails" behavior starts with an ambiguous workspace. We decided the framework should remove that ambiguity rather than ask an agent to reason about it.

The architect plans, but never codes. The first agent reads the codebase and decides what needs to happen: which layers, which files, whether a migration is actually necessary, where the integration risks are. It produces two files: plan.md (human-readable blueprint with file paths, strategy, acceptance criteria, and reviewer notes) and state.json (machine-readable slice graph with dependency edges, owning agents, verification commands, retry state, and completion status). That second file is what makes the whole pipeline resumable. If the session dies midway, /implement trending-badge reads state.json, finds the first incomplete slice, and picks up from there. No reconstructing state from conversation history.

The plan is reviewed before any code exists. The code-reviewer checks whether the workflow is actually executable: slices in the right order, file paths plausible, verification commands valid, migration rules respected, integration risks visible. Findings land in reviews/00-plan.review.md. For Trending Badge, the reviewer caught a real problem before a single line was written. The architect had selected a Gradle task that was a skipped no-op on this project. The plan was revised and corrected before implementation was allowed to proceed. The reviewer wasn't checking code quality. It was checking whether the pipeline itself was safe to run.

One human gate, before coding starts. After the reviewer approves, the pipeline pauses. You read the architecture, check the slice decomposition, answer any OPEN QUESTION: markers the architect couldn't safely resolve. This is the last mandatory stop before multiple agents start changing a multi-module codebase. Once you approve, the state machine takes over.

The state-machine loop. One slice at a time, in dependency order. Each slice has one owner, one scope, one verification command, and one review step. Backend compiles before shared contracts are touched. Shared DTOs compile before client code depends on them. Client propagation works before the UI renders the new field. The verification command isn’t improvised by the agent. It’s in the plan, stored in state.json. After verification, the reviewer inspects only the current slice diff ($pre_sha..HEAD), keeping findings focused. One retry on rejection; two rejections surfaces the issue to you. No unbounded autonomous repair loops.

Final integration review, then /verify. Once all slices are done, the reviewer sees the whole branch against origin/develop, checking the seams that per-slice review can't see: does the server emit the field the client expects, do DTO defaults preserve backward compatibility, is anything locally correct but globally wrong? After that comes the CI gate: five Gradle tasks, all must pass. No auto-fixing at this stage. Auto-fix at the final gate is how you ship something that's technically green but no longer the thing that was reviewed. /verify passing is the only definition of done.

The key design decision: agents communicate through files

Most multi-agent systems try to pass context through conversation history. That’s expensive, unbounded, and impossible to audit after the fact. We went the other direction entirely: agents don’t share conversation history. At all. Every agent communicates through files on disk.

plan.md says what to build. state.json tracks where we are in the build. progress.md records what's been done. reviews/<agent>.md contains what the reviewer found for each slice. review.md holds the final integration review. One agent writes, the next one reads. The orchestrator never asks an agent "what did you do?" It reads progress.md. The reviewer never asks an author "why?" It reads the diff.

Three things fall out of this almost for free.

Auditability. Every decision is a file sitting in git history. No black box. You can reconstruct any feature’s entire AI-assisted development story from the files on the branch.

Resumability. If your laptop dies mid-feature, /implement trending-badge reads state.json, finds the first not-done slice, and picks up exactly where it left off. It's a query against a file, not a vibe check.

Clean separation of state from model memory. The framework’s state is the file tree. The model’s memory is a single agent’s invocation context. These are different things and they should live in different places.

Safety rails (the parts that can’t be talked out of)

LLM agents are remarkably good at finding the direct path to “this looks done.” Some of that creativity is how you end up editing a released Flyway migration. For the non-negotiables we use harness-level hooks, not prompts you can talk your way around. They live in scripts/claude/ and are wired in .claude/settings.json.

guard-migrations.sh is the most critical one. It fires on every file edit or write. If the target is a Flyway migration that already exists on origin/main or origin/develop, the hook blocks it outright. There's an escape hatch (ALLOW_MIGRATION_EDIT=1), but a human has to set it. No agent can flip it on its own. The second hook, record-subagent-cost.sh, fires on every subagent exit, reads the transcript, aggregates token usage, prices it, and appends one line to costs.jsonl. That's how we got the cost breakdown later in this article.

These hooks run automatically and outside the agents’ control. They can’t be argued with, prompt-engineered around, or skipped.

The rest of the safety surface lives in settings.json and the state machine itself. On the permissions side: git push, git reset, git rebase, gh pr create, and gh pr merge all require explicit human approval. Gradle compile/test, read-only git, and read-only gh are auto-allowed. The bottom line: no agent can push or open a PR. The branch is yours to inspect first.

On the process side: a plan-level human gate means no code gets written until you’ve read and approved the architecture. A 1-retry cap per review finding prevents infinite fix loops. Two rejections and it’s surfaced to you. Per-slice diffs are scoped so the reviewer only sees $pre_sha..HEAD for the current slice, not the entire branch. And a BLOCKED: signal lets agents flag problems instead of silently skipping them. The qa-tester used this twice on the worked example below.

Things we deliberately left out

No parallel agents: the dependency graph (server → shared → client → UI) is sequential by nature, and trying to parallelize it buys you deserialization crashes. No meta-planner: an LLM picking which agent runs next would make the whole system non-reproducible, and frankly we don’t trust that. No shared memory across agents. Each one gets the plan, its task, and the artifacts. Nothing else. Boring is reliable.

That’s the framework. In Part 2, we put it to work on a real feature: a Trending Badge that spans every layer of the stack, from backend query to Compose UI. We walk through what each agent did, where the retry loop earned its keep, and what the whole thing actually cost.

Stay tuned!!

Special thanks to my colleague Alex Koufatzis for co-authoring this series.

We Didn’t Ask an AI to Build a Feature. We Gave It a Delivery Pipeline. was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

So far in this series, we’ve mostly treated GitHub Copilot as a very smart pair-programmer: it understands your code, your repo, your instructions, and your agents and it helps you write and review code faster.

But there’s still a big problem in most AI-assisted workflows:

We often start coding before we’ve really agreed on what we’re building.

Vibe-driven coding (“let’s see what Copilot comes up with”) is fun for prototypes, but risky for real products. Specs are written late or not at all. AI suggestions drift. Requirements move in people’s heads instead of in one shared place.

SpecKit is GitHub’s open-source answer to that. It’s a toolkit for spec-driven development that sits on top of your AI coding assistants and forces a bit of structure into the chaos.

Instead of “ask Copilot and pray,” you build from a shared, living spec that both humans and AI can follow.

What SpecKit Actually Is

SpecKit is:

• a CLI tool (specify) you run in your project simplifying the setup process
• a set of files and prompts added to your repo
• a workflow built around specs instead of ad-hoc prompts

It doesn’t replace GitHub Copilot. It wraps Copilot (and other agents like Claude Code, Gemini CLI, Cursor) in a structured process so that all the code it generates is grounded in a single source of truth: your spec.

At a high level, SpecKit organizes work into phases:

1. define project principles (the “constitution”)
2. write a clear specification
3. clarify gaps
4. create a plan
5. break it into tasks
6. implement with an AI assistant
7. analyze for gaps and inconsistencies

Spec-Driven Development in a Nutshell

Spec-driven development means:

• You start with a spec, not a prompt.
• The spec is written in a structured way and lives in your repo.
• AI agents read this spec (plus your code) to plan, generate, and validate changes.

Instead of “Copilot, build me a dashboard,” you first write down:

• what the dashboard must show
• how it should behave
• how it fits into the system
• constraints, edge cases, success criteria

SpecKit then turns that into a repeatable flow your AI assistant can follow. You get less guesswork and more predictable outcomes.

The SpecKit Workflow: From Idea to Code

You can install SpecKit on your machine first or simply run:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

This bootstraps your project with SpecKit’s structure. During the setup steps you can select your preferred coding agent.

From there, SpecKit gives you a set of structured commands (usually exposed as slash-commands in the agent’s chat) such as:

• /constitution — define your project’s governing principles (quality, testing, UX, performance).
• /specify — describe what you want to build and why (requirements, scenarios, user stories).
• /clarify — have the agent ask you targeted questions about missing or ambiguous details.
• /plan — turn the spec into an implementation plan with architecture and technology choices.
• /tasks — break the plan into concrete, actionable tasks.
• /analyze — check consistency between spec, plan, and tasks.
• /implement — let the agent execute the tasks and generate code according to the plan.

The phases are simple, but powerful:

1. Foundation — /constitution, /specify, /clarify
2. Design — /plan
3. Execution — /tasks, /implement
4. Verification — /analyze

You’re always working against an explicit, versioned artifact.

How SpecKit Works With GitHub Copilot

SpecKit is deliberately agent-agnostic: it supports GitHub Copilot, Claude Code, Gemini CLI, Cursor, and others. But the GitHub story is especially nice.

When you run specify init and select copilot, SpecKit adds a .github folder with prompt definitions and custom agents for Copilot. This wires up the slash-commands so they’re available inside Copilot Chat in your project but also usable on GitHub.com. It gives Copilot a structured way to walk through specify → plan → tasks → implement

From your point of view as a developer you open the repo in VS Code with GitHub Copilot enabled. You see commands like /speckit.specify, /speckit.plan, /speckit.tasks in Copilot’s chat and it also suggests the next step automatically.

Copilot then uses the spec and plan artifacts SpecKit created as context when generating or editing code. Over time, the spec becomes the source of truth for your AI-assisted development.

A Day in the Life With SpecKit + Copilot

Picture this as a dev or tech lead:

You want to add a new “Team Reports” feature to your internal dashboard. Instead of opening the editor and immediately typing “build a reporting view” into Copilot, you start in SpecKit.

You run /constitution once for the project and encode rules like “always write tests for data access,” “prefer accessibility-friendly UI patterns,” and “error messages must be actionable.”

Then for this feature:

1. /specify — you describe what Team Reports should do: which metrics, which filters, who uses it, performance requirements, empty state behavior, export options.
2. /clarify — SpecKit (via Copilot) asks clarifying questions:
   - Do reports need to be exportable to CSV?
   - How should permissions work?
   - What’s the time range we must support?
3. /plan — based on the clarified spec, SpecKit and Copilot propose architecture choices: where to put the API, which existing components to reuse, which database access patterns to follow.
4. /tasks — the plan is broken into tasks: backend endpoint, data aggregation layer, UI components, tests, documentation.
5. /implement — Copilot starts implementing tasks in your repo, guided by the spec and the plan instead of one giant prompt.

At each step, you can inspect and edit the generated spec, plan, and tasks. They live as files in your project, under version control. Copilot’s job is to fill in code and details that align with those documents.

You end up with:

• a written, reviewable spec
• a traceable plan
• a set of tasks you could assign to humans or to Copilot
• code that reflects the agreed-upon design

This is the kind of workflow that makes AI coding feel less like gambling and more like engineering.

Where SpecKit Really Helps

SpecKit is especially useful when:

The problem is non-trivial. If a change touches multiple services, involves real business rules, or has long-term impact, investing in a spec up front saves you from speculative coding and rewrites.

Multiple people and agents are involved. A shared spec gives both humans and agents the same reference point. It reduces misunderstandings, and makes code reviews easier because there’s a “contract” to review against.

You care about repeatability. Instead of each prompt being a unique snowflake, you follow a reproducible pattern: constitution → spec → plan → tasks → implement. This is appealing for teams that want to standardize how they use AI.

You’re sick of vibe-coding. If you’ve ever thought “I don’t trust AI to touch this part of the code,” SpecKit is one way to tighten the guardrails so that both you and Copilot have a clear, shared understanding first.

For team leads, the big win is transparency: you can read the spec and plan, give feedback there, and only then let Copilot loose on the implementation.

Limitations and Gotchas

SpecKit isn’t magic, and it’s not a good fit for everything.

A few practical limitations:

You pay an up-front cost. Writing specs, clarifying them, and reviewing plans takes time. For very small one-off changes, this overhead may not be worth it.

Quality depends on the spec. Garbage in, garbage out still applies. If the spec is vague or contradictory, AI-generated code will be too. SpecKit helps you structure your thinking but it can’t make decisions for you.

It doesn’t replace design or reviews. SpecKit supports good engineering; it doesn’t replace architectural thinking or human oversight. You still need to decide what’s right for your system and review what the agent produces.

Used thoughtfully, though, SpecKit is one of the more promising ways to make AI coding less chaotic and more trustworthy.

Takeaway

SpecKit shifts the focus from “prompting harder” to planning better.

Instead of throwing vague tasks at coding agents and hoping for the best, you:

• capture your intent as a structured spec
• refine it until it’s unambiguous
• turn it into a plan and tasks
• let Copilot implement within that frame

For developers and leads who care about reliability, traceability, and long-term maintainability, SpecKit + Copilot is a compelling combination: AI as an accelerator, but anchored in an explicit specification you can read, review, and evolve.

Other articles of this GitHub Copilot series:

Part 1: Coding & Review Agents
What the new Copilot agents do, how they open PRs, and how they fit into your day-to-day workflow.

Part 2: Custom Instructions
How to teach Copilot your team’s conventions, from repo-wide rules to path-specific instruction files.

Part 3: Custom Agents
Creating specialized AI teammates (like a Testing Coach or Docs Agent) that act on your code and open PRs.

Part 4: Copilot Spaces
Turning Copilot into a project-aware assistant by giving it curated context from your code and documentation.

Part 5: SpecKit
Using spec-driven development with SpecKit so Copilot implements features based on a shared, versioned specification.

Useful Links

• SpecKit — Official site — Overview, philosophy, usage guide, and examples for spec-driven development with AI.
• GitHub — SpecKit repository — Source code, issues, docs, and CLI reference.
• GitHub Blog — Spec-driven development with AI — Background on why SpecKit exists and how it fits into AI-assisted workflows.

Part 5: SpecKit. Turning GitHub Copilot Into a Specification-Driven Teammate was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

Copilot Spaces are dedicated workspaces in GitHub where you bundle the materials Copilot should use as context for a specific topic, project, or initiative. Think of a Space as a curated knowledge pack for Copilot. You decide which sources matter, and Copilot uses those sources when you chat inside that Space or when you work with agents connected to it.

A Space is not a new documentation system and it is not related to the older concept of “GitHub Spaces.” It is a Copilot feature that lives directly on GitHub and allows you to assemble a stable, reusable context. That context stays the same across conversations and can be shared with others, which makes it useful for ongoing work rather than one-off questions.

What is a Copilot Space?

A Copilot Space is a workspace tied to your GitHub account or organization that contains all the important context for a particular project, domain, or feature area.

Inside a Space you can bring together:

• code files or entire repositories
• architecture and design documents
• API specifications
• onboarding guides and internal FAQs
• additional supported files uploaded directly to the space
• custom instructions that describe how Copilot should behave in that Space

All of this becomes searchable context for Copilot. When you ask questions or request help inside the Space, Copilot answers based on these sources.

Why Copilot Spaces Matter

As projects grow, knowledge spreads across many places. Code lives in repositories, decisions live in pull requests and issues, requirements live in documents, and context often lives in people’s heads. Copilot Spaces matter because they provide a way to bring this information together in a form that can be reused consistently.

Spaces create a single, shared place where important project materials are collected. Instead of repeatedly gathering files, links, and documents for every conversation, you define the relevant sources once and reuse them. This makes it easier to work against the same references over time, whether you are exploring an unfamiliar part of the system or returning to a topic after a break.

They also reduce maintenance effort. When a Space includes repositories or files from GitHub, the content is always taken from the current state of the default branch. There is no separate copy to keep in sync and no manual updates required when the code changes. The Space naturally reflects how the project evolves.

Another important aspect is consistency. Because the same Space can be used across conversations and shared with others, Copilot’s answers are grounded in the same set of sources for everyone. This helps avoid situations where different people receive different explanations simply because they provided different context.

Finally, Spaces are designed for collaboration. A Space can be owned by an organization and shared with individuals or teams. That makes it possible to establish common reference points for onboarding, planning, or documentation work, and to ensure that everyone is working with the same curated context.

What You Put Into a Space

You don’t have to mirror your whole repository layout; it’s usually better to be deliberate. A Space works best when you select the materials that answer the most common questions.

For example, you might attach just the core modules of a service, the top-level architecture diagram, a couple of ADRs, and the main API spec. For a front-end project, you might include the design system, a style guide, and examples of “good” components. For onboarding, you might bring in the README, a “getting started” doc, and a few representative files.

On top of the sources themselves, each Space has a panel for custom instructions. Here you describe Copilot’s role in that Space. You might say:

“You are an expert on our billing system. Use the attached docs and code to explain how it works, and prefer linking to files when you refer to implementation details. If something is unclear, indicate which source appears inconsistent.”

This simple description gives Copilot a persona and a purpose. Combined with the attached sources, that persona becomes surprisingly effective.

How You Use Copilot Spaces Day to Day

Spaces change how you interact with Copilot, both in the browser and in your IDE.

On GitHub.com, each Space has its own chat. You open the Space, see the instructions and the list of attached sources, and then ask questions directly in that context. You might ask for an explanation of a subsystem, a summary of a spec, suggestions for how to extend an existing feature, or help locating the right place to implement a change. Copilot’s answers are drawn from the sources in the Space.

In the IDE, Copilot can be connected to a Space via MCP. That means when you’re working in VS Code or JetBrains, you can ask things like “Explain the architecture from the Copilot Space” or “How does the payment flow fit into this function?” and Copilot will reach into the Space, take its context, and respond based on your project.

Typical Workflows Copilot Spaces Improve

Spaces are useful in many situations, but a few stand out as especially impactful.

Onboarding

A dedicated onboarding Space can collect the core pieces of knowledge a new developer needs: where the important services live, how the system is deployed, what the main data flows look like, and how to run things locally. Instead of scheduling multiple “explain the system” meetings, you give new colleagues access to the Space and encourage them to ask Copilot questions there. If something is missing or unclear, you update the Space once and every future newcomer benefits.

Project or Feature Spaces

When you start a new project or major feature, you can create a Space just for that effort. You attach the product spec, the current implementation, any diagrams or prototype code, and maybe key issues or PRs. Then you use Copilot to break down the spec into tasks, to highlight possible risks, or to check whether the code matches the intent in the documents. As the feature evolves, the Space becomes the central place where its context lives.

Troubleshooting and Incident Response

For a tricky bug or incident, a temporary Space can be set up with logs, recent changes, and the relevant parts of the code. The team can ask Copilot to spot patterns, relate current logs to past issues, or suggest likely failure points. It doesn’t replace human debugging, but it can speed up pattern recognition and help correlate things that would take a while to triage manually.

Documentation and Knowledge Extraction

Spaces are a natural home for documentation work. If you collect specs, code comments, and configuration in a Space, Copilot can help you write or update user-facing docs, API references, or internal runbooks. You ask it to “draft a high-level description of this service for the onboarding guide” and it uses what you attached. People still review and edit the drafts, but they no longer start from a blank page.

Sharing and Permissions

Spaces are built to work in team environments.

You can create them for yourself or under an organization. Organization-owned Spaces can be shared with specific people or teams and have roles that roughly match what you’d expect: admins manage settings and sharing, editors curate the content, and viewers just use the Space.

For personal Spaces, you can still share with individual collaborators, and you can even make some Spaces public as read-only for documentation or open-source use cases. Public spaces are only useful if the underlying repos or docs are public, and GitHub still enforces all normal repository permissions: a Space never becomes a shortcut around access control.

The key idea is that once a Space is shared, everyone on the team has access to the same curated context, and Copilot gives them consistent, up-to-date answers based on that context.

Takeaway

A Copilot Space lets you:

• collect and curate the context that really matters
• guide Copilot’s behavior with targeted instructions
• share that context safely across your team
• keep knowledge alive and accessible even as people and code change

Combined with Custom Instructions and Custom Agents, Copilot Spaces turn Copilot from “smart autocomplete with chat” into a genuine collaborator that knows your systems, your standards, and your history.

If you’re already using Copilot, creating one or two carefully chosen Spaces is an easy next step that can noticeably improve how useful Copilot feels in everyday work.

Other articles of this GitHub Copilot series:

Part 1 — Coding & Review Agents
What the new Copilot agents do, how they open PRs, and how they fit into your day-to-day workflow.

Part 2 — Custom Instructions
How to teach Copilot your team’s conventions, from repo-wide rules to path-specific instruction files.

Part 3 — Custom Agents
Creating specialized AI teammates (like a Testing Coach or Docs Agent) that act on your code and open PRs.

Part 4 — Copilot Spaces
Turning Copilot into a project-aware assistant by giving it curated context from your code and documentation.

Part 5 — SpecKit
Using spec-driven development with SpecKit so Copilot implements features based on a shared, versioned specification.

Useful Links

• About GitHub Copilot Spaces — Copilot Spaces overview
• GitHub Copilot Spaces — How to create, use and share copilot spaces

Part 4: GitHub Copilot Spaces. Giving Copilot Real Understanding of Your Project was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

Appium MCP is a Model Context Protocol (MCP) server that exposes the Appium mobile automation framework as a structured set of tools for AI assistants.

In practical terms, this means an agent, whether in an IDE, chat interface, or development environment, can control Android and iOS simulators, emulators, and real devices through Appium, without requiring you to manually write every imperative test step.

Instead of writing everything yourself, you describe what you want in natural language and the MCP server translates that into actual Appium commands executed on the device.

The Reality of UI Testing

From experience, across both small and large projects, UI tests are often:

• Missing entirely
• Implemented with low coverage
• Started with good intentions, but eventually abandoned

The common pattern I’ve noticed: A team invests effort, writes tests, but over time they become brittle, outdated, and expensive to maintain. Eventually, they’re disabled. This is where AI can make the difference.

What the MCP Provides

The MCP server exposes structured tool categories such as:

• Platform & Device Setup
• Session Management
• Context Management
• Element Discovery & Interaction
• Screen & Navigation
• App Management
• Test Generation & Documentation

Instead of writing complex test scripts or knowing the mechanics of Apple’s XCUIAutomation (or Android equivalents), you simply describe your intent. The MCP server handles:

• Translating natural language into Appium commands
• Executing actions on the device
• Resolving platform-specific differences

Getting started

My setup was straightforward and focused on iOS only, but the Android setup should look very similar.

• macOS with Xcode & Command Line Tools installed
• iOS Simulator set up
• WebDriverIO installed (via npm), the CLI sets ups everything you need, e.g. the Appium Server

After that, I configured the MCP server in VS Code:

{
  "servers": {
    "appium-mcp": {
      "command": "npx",
      "args": ["appium-mcp@latest"],
      "env": {
        "CAPABILITIES_CONFIG": "capabilities.json"
      },
      "type": "stdio"
    }
  }
}

And defined device capabilities in a capabilities.json file (iOS example):

{
  "ios": {
    "appium:app": // Path to your app,
    "appium:deviceName": "iPhone 17 Pro",
    "appium:platformVersion": "26.1",
    "appium:automationName": "XCUITest",
    "appium:udid": "92964687-3100-4CD2-9207-51D7CB10D037"
  }
}

First Results: Letting the Agent Explore

To test its capabilities, I intentionally used vague prompts, such as:

Open the app and go through all list items. Open the respective screens and try to interact with UI elements like toggles, sliders, and buttons. Make assumptions about expected behavior. Add tests for all screens in a file.

Despite the lack of specificity, the results were surprisingly solid.

The agent:

• Navigated through screens
• Identified interactive elements
• Generated structured test files
• Made reasonable assumptions about expected behavior

Without any prior Appium experience, I ended up with a generated test file that was around 600 lines long, covering initial screens. With minor adjustments, the scripts were fully functional.

Lowering the Barrier to Entry

It becomes clear very quickly: anyone can start contributing to UI test automation almost immediately. You no longer need deep expertise in Appium internals, platform-specific selectors or device-specific quirks to get started.

The AI analyzes the page source, suggests fixes intelligently, adapts to platform differences, and assists with debugging. Hours of manual effort, especially when it comes to identifying the correct selectors, are drastically reduced.

That said, platform knowledge does not become irrelevant. In more complex applications, unexpected action sheets may appear, permission dialogs may need to be dismissed, or platform-specific behaviors can interrupt flows in non-deterministic ways. Handling these edge cases still requires an understanding of how iOS, Android, or other platforms behave in real-world scenarios. However, the fundamentals and the majority of repetitive work are covered, which significantly lowers the entry barrier and accelerates productivity.

Beyond Testing: Appium as a Structured App Crawler

Writing UI tests is only one part of the story. Once you realize that the MCP has access to the full UI graph exposed by Appium, it becomes clear that this setup can be used for far more than test automation. In practice, it turns Appium into a structured, controllable crawler that can explore your app, understand what is rendered on screen, and generate meaningful output based on what it discovers.

App Exploration & Documentation

One powerful use case is automated app exploration and documentation. Instead of manually maintaining feature documentation that inevitably drifts out of sync, the agent can traverse real user flows such as onboarding, checkout, or settings. While navigating through the app, it can capture screenshots, extract screen titles, and generate short descriptions of each view.

Because this documentation is derived directly from the running application, it stays aligned with what is actually shipped. In addition, the agent can outline the full navigation hierarchy, which can serve as a foundation for UX reviews, stakeholder communication, or even as input for information architecture work. Over time, this approach can replace static documentation with continuously updated, living artifacts.

Accessibility Reports

Another compelling application is automated accessibility auditing, which becomes more and more important as accessibility requirements are increasingly enforced by law in many countries. Since the MCP can inspect every reachable screen, it can systematically analyze accessibility metadata such as labels, traits, focus behavior, and enabled states. This allows it to identify missing labels, ambiguous controls, or common accessibility anti-patterns.

Instead of generic reports, the output can reference the exact screens and UI elements involved, making the findings directly actionable for developers and designers.

Finding Dead Ends

By building a navigation graph of the application, the agent can detect structural issues in user flows. It can identify screens where users have no valid next actions, encounter broken back navigation, face permanently disabled call-to-action buttons, or become trapped in navigation loops.

More importantly, it can provide reproducible paths that show exactly how to reach these problematic states. This transforms vague UX concerns into concrete, testable scenarios and makes it significantly easier to resolve navigation issues early.

Detecting Runtime Issues

Exploratory navigation on real devices and across different OS versions also helps uncover runtime issues that often remain invisible in CI pipelines. Certain problems, race conditions, permission prompt edge cases, or memory pressure crashes, may only surface under real-world conditions.

By automatically exploring flows and device context, the agent provides valuable debugging information. This shortens the feedback loop and makes it far easier to reproduce and fix issues that would otherwise be difficult to trace.

The Other Side of the Coin

Appium MCP is powerful, but it also comes with trade-offs. Because the agent needs to inspect the UI tree, reason about navigation flows, and generate or adjust code, it can consume a significant number of tokens, which may become costly for large applications or extended sessions. In addition, typical action latency ranges from two to four seconds. When testing a complex app with many screens and interactions, this can result in very long execution times.

Complex applications may also still require solid platform knowledge. If accessibility standards are not properly followed, for example, if identifiers are missing or inconsistent, automation becomes less reliable and more difficult to maintain. In those cases, human expertise is still necessary to stabilize and guide the system.

Integrating into Day-to-Day Development

Here’s how I would incorporate Appium MCP into a real-world workflow:

Define AI Instructions

Create an instruction file for the agent that defines:

• Test structure conventions
• Naming patterns
• Commenting guidelines
• Development best practices

This ensures consistency in AI-generated tests.

Generate a Full Cross-Platform Test Suite

Use the agent to generate:

• Feature-based test suites
• Tests derived from structured feature documentation (in an ideal scenario, the AI is fed user stories)

Separate AI from CI Cost

Running AI-powered tests on every commit may be too expensive. Instead:

• Use pure Appium for CI runs
• Run the full suite nightly
• Keep AI out of critical CI paths

Self-Healing Tests

When nightly UI tests fail:

• Trigger MCP to analyze failures
• Suggest fixes
• Automatically create pull requests

The next morning, developers review and merge. Maintenance overhead drops significantly and human interaction stays minimal.

Automated Weekly Documentation

Set up a weekly job that:

• Crawls the app
• Generates a Markdown overview of main screens
• Embeds screenshots
• Updates feature descriptions

This becomes the single source of truth for exports, PDFs, and internal documentation.

Final Thoughts

Appium MCP changes how we can think about UI automation. Instead of building brittle tests that gradually become outdated and unreliable, we can move toward AI-assisted automation that evolves alongside the product. It lowers the barrier to entry, reduces maintenance effort, and opens the door to capabilities that go beyond traditional testing.

AI-Powered Testing Automation with Appium MCP was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.

If Custom Instructions teach Copilot how your team works, Custom Agents let you decide who Copilot is in a given moment.

Instead of one generic AI assistant, you can define specialized personas: a testing expert, a UI layout helper, a backend service guru, a documentation partner. Each Custom Agent has its own profile, scope, and behavior.

This article explains what Custom Agents are, how they differ from Custom Instructions, and how they can help with both code and recurring tasks.

Why Custom Agents?

Even with good repository instructions, you often need deeper specialization.

Maybe your tests follow strict patterns, your backend services have complex rules, or your UI must adhere to a design system. You can write all of that down, but a single global Copilot persona will always feel a bit average.

Custom Agents solve this by letting you define separate AI “teammates” for different concerns. Instead of “Copilot, please be good at everything,” you can say:

• “Use the Testing Coach for test design and coverage questions.”
• “Use the UI Agent when working on layouts and design-system usage.”
• “Use the Docs Agent for changelog updates and release notes.”

Each agent gets a dedicated profile, so it can focus on one job and do it well.

What a Custom Agent Actually Is

Technically, a Custom Agent is just a configuration file in your repository (for example under .github/agents/) that describes a persona:

• who it is
• what it knows
• how it should behave
• what it should avoid

You can think of it as a “mini spec” for a role on your team.

Conceptual example: the Testing Coach

Imagine a file named: .github/agents/testing-coach.agent.md

Inside, you describe the agent like you would brief a new team member:

---
name: testing-coach
description: Agent specializing in helping developers design and improve automated tests
---

You are the Testing Coach for this repository.
You help developers design and improve automated tests.
You know our testing framework, naming conventions, and folder structure.
You prefer small, focused tests with clear Arrange/Act/Assert structure.

When asked to add or update code, you always think about test impact.
Propose missing edge cases. Highlight untested behavior.
Never remove tests unless explicitly requested.
Don't introduce new test frameworks without agreement.

The optional name will be shown when selecting the custom agent, and the mandatory description helps Copilot to know when to use your agent.

There are also options to specify handoffs to other agents and configure the tools the agent is allowed to use

Once this is in place, you can explicitly pick the Testing Coach in Copilot’s UI when:

• writing or refactoring tests
• reviewing test coverage on a PR
• planning how to test a new feature

Instead of a generic assistant, you get a focused test expert.

How Developers Use Custom Agents

Custom Agents show up in several places and workflows. When you assign an issue to Copilot, you can choose which agent should handle it. If you pick the Testing Coach for a “add tests for X” ticket, Copilot will:

• spin up a Coding Agent under that persona,
• generate or refactor tests according to the profile,
• and open a pull request with the changes.

That PR behaves just like one created by a human: new branch, commits, and a summary. The difference is that the AI writing it is specialized in testing.

The same is true for other agents you define: a documentation agent can open a PR updating release notes; a backend agent can open a PR updating an API handler and its tests.

Recurring tasks: documentation and information extraction

Custom Agents are also useful for non-code tasks that repeat every week or sprint.

For example you could create agents like:

• Docs Agent: writes changelog entries or update notes based on PRs or issues.
• Release Summary Agent: scans merged PRs and produces a human-readable release summary.
• Info Extraction Agent: reads code or docs and extracts specific information (feature flags, endpoints, database tables, public APIs).

Because these agents have a defined role, they are better at producing consistent, predictable output.

Custom Instructions vs Custom Agents

Custom Instructions and Custom Agents complement each other, but they are not the same:

• Custom Instructions describe the general rules of the repository: architecture boundaries, coding style, review expectations, testing basics. They apply broadly, often to everyone and everything.
• Custom Agents describe a specific role: the Testing Coach, the UI Helper, the Payment Service Expert, the Docs Agent. They are used when you explicitly select that persona.

You usually want both. Instructions set the baseline; agents specialize.

Where Custom Agents Really Shine

Custom Agents are most useful when:

• the work is repetitive but non-trivial (tests, docs, summaries),
• the architecture has strict patterns (e.g. Clean Architecture, MVVM, specific layering),
• or you have parts of the codebase that constantly attract the same questions.

The Docs Agent is a great example. It can reliably draft release notes or API docs every time a set of PRs merges, so engineers don’t have to start from a blank page.

Designing a Useful Custom Agent

When you design a Custom Agent, think like a tech lead onboarding a new colleague. The profile should make clear:

• What the agent is responsible for (e.g. tests, docs, a specific service).
• Which parts of the codebase and docs it should focus on.
• What “good” looks like (e.g. small focused tests, use of a specific test library, consistent tone in docs).
• What it must not do (e.g. changing DB schemas, introducing new dependencies, ignoring existing patterns).

Limitations You Should Keep in Mind

Custom Agents are powerful, but they have limits:

• They rely on your existing instructions, code, and docs. If those are weak, the agent will be too.
• They don’t replace senior engineers. They assist; they don’t decide architecture.
• They need maintenance. When your testing strategy or docs style changes, you should update the profiles.
• They can still produce wrong or incomplete results, so human review and CI remain essential.

Takeaway

Custom Agents turn GitHub Copilot from “one generic AI assistant” into a small team of specialists that you design:

• A Testing Coach that helps design and maintain tests, and can open PRs to add or improve them.
• A Docs Agent that drafts changelogs and documentation updates.
• Other agents tailored to your architecture, domain, or recurring workflows.

Combined with Custom Instructions and path-specific rules, Custom Agents give you a way to embed your engineering culture and recurring processes directly into Copilot.

In the next article, we’ll look at Copilot Spaces. How to give Copilot rich context from your code, docs, and issues, so these agents can work with a more complete picture of your project.

Other articles of this GitHub Copilot series:

Part 1: Coding & Review Agents
What the new Copilot agents do, how they open PRs, and how they fit into your day-to-day workflow.

Part 2: Custom Instructions
How to teach Copilot your team’s conventions, from repo-wide rules to path-specific instruction files.

Part 3: Custom Agents
Creating specialized AI teammates (like a Testing Coach or Docs Agent) that act on your code and open PRs.

Part 4: Copilot Spaces
Turning Copilot into a project-aware assistant by giving it curated context from your code and documentation.

Part 5: SpecKit
Using spec-driven development with SpecKit so Copilot implements features based on a shared, versioned specification.

Useful Links & References

• About Custom Agents — official GitHub documentation describing what custom agents are and how they work
• Creating Custom Agents — guide showing how to create an agent profile in your repo
• Custom Agents Configuration — full documentation how to configure your custom agent

Part 3: Custom Agents. Turning GitHub Copilot into a Team of Specialists was originally published in arconsis on Medium, where people are continuing the conversation by highlighting and responding to this story.