Articles / AI Workflow
I don’t prompt.
I build the
machine that prompts.
Skills, hooks, MCP servers, subagent fleets, and a context budget. This is the actual apparatus — config, guardrails, numbers and all.
One task, start to PR. Every line below is a real surface: a skill trigger, an MCP tool call, a hook denying a command, three subagents in their own worktrees.
43
Skills authored
loaded on trigger, not on boot
9
MCP servers wired
61 tools, deferred until needed
7
Subagents in the fleet
one git worktree each
~2.4M
Tokens/day
78% served from cache
71%
PRs agent-drafted
100% human-approved
Architecture
Six layers between
an idea and a merge.
Most people describe their AI workflow as a vibe. Mine has an architecture, and every layer has something you can actually inspect. Click through it.
Layer 00
Intent
A goal, its constraints, and how we will know it worked.
- ▸Every run starts with a written goal and a definition of done — not a prompt.
- ▸If success is checkable, it becomes a rubric the agent grades itself against.
- ▸Ambiguity is resolved here, by me. It is the cheapest place to resolve it.
- ▸The spec goes in whole, up front. Long-horizon models do worse when you dribble it out over turns.
Layer 02 · Context
43 skills.
None of them loaded right now.
A skill is a folder with a SKILL.md. Only its one-line description sits in context; the body loads when a task actually triggers it — that is how you carry a lot of expertise without paying for it every turn. Twelve of the forty-three are below. Open one and you get the real frontmatter.
---
name: rag-eval-harness
description: Use when changing chunking, embeddings, search, fusion, or
reranking. Freezes the eval set before the change, runs it after, and
blocks a regression in recall@5, MRR, or faithfulness.
allowed-tools: Read, Grep, Glob, Write, Bash(python scripts/eval.py:*)
---Freeze first, change second. An eval set written after the change grades the change it was written for.
---
name: qdrant-ops
description: Use for any Qdrant collection work — creating, tuning, migrating,
or debugging recall. Covers HNSW m/ef, scalar vs product quantization,
payload indexes, and multi-tenant partitioning.
allowed-tools: Read, Write, mcp__qdrant__*
---Reads the live collection config through MCP first. Refuses to reason about a collection it hasn't looked at.
---
name: pii-redaction
description: Use before any dataset, log dump, or prompt leaves the VPC.
Runs the redaction pipeline, then verifies on a held-out sample and
reports measured recall rather than asserting success.
allowed-tools: Read, Write, Bash(python pipelines/redact.py:*)
---">99% redaction" is only a number if something measured it. This skill measures it every time.
---
name: prompt-regression
description: Use when editing any production prompt, tool description, or
skill body. Runs the golden set before and after and reports per-case
deltas, so a prompt change is reviewed like a code change.
allowed-tools: Read, Edit, Bash(python evals/golden.py:*)
---A prompt is production code with a terrible type system. It gets the same regression discipline.
---
name: no-mistakes
description: Use before pushing, opening a PR, or declaring work complete.
Runs the full validation pipeline and reports what actually failed with
the real output — never a summary claiming success.
allowed-tools: Read, Bash(make verify:*), Bash(git status:*)
---Paired with a Stop hook that runs the same commands, so it can't be talked out of failing.
---
name: adversarial-review
description: Use after implementation, before the PR. Reviews the diff from
a cold context with no memory of why the choices were made. Reports every
finding with confidence and severity; filtering happens downstream.
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
---Told to report everything, including low-confidence findings. Ask a reviewer to be conservative and it will be — silently.
---
name: bigquery-cost-guard
description: Use for any BigQuery work. Dry-runs every query, reports bytes
scanned and estimated cost, verifies partition and cluster pruning, and
refuses to run anything above the configured ceiling without approval.
allowed-tools: mcp__bigquery__dry_run, mcp__bigquery__query, Read
---The one $400 SELECT * taught this skill. It has not happened again.
---
name: observability-wiring
description: Use when adding a service, endpoint, or background job. Ensures
structured logs, a latency histogram, an error counter, and trace spans
exist before the path is considered done.
allowed-tools: Read, Edit, Grep
---Debugging production without telemetry is just guessing with extra steps.
---
name: terraform-review
description: Use on any terraform plan output. Flags resource replacement,
public ingress, IAM widening, and state-destroying changes. Summarises
blast radius before anything is applied.
allowed-tools: Read, Bash(terraform plan:*), Bash(terraform show:*)
---'It's just a config change' is how infrastructure incidents start.
---
name: paper-to-repro
description: Use when reproducing a method from a paper. Extracts the exact
setup, builds a minimal runnable baseline, and reports where the numbers
diverge from the paper instead of quietly matching them.
allowed-tools: Read, Write, WebFetch, Bash(python:*)
---Five IEEE papers of my own taught me how much a method's description leaves out. This skill asks about the gaps.
---
name: ablation-planner
description: Use before running experiments. Enumerates the variables worth
isolating, proposes the minimum run set, and states in advance what result
would falsify the hypothesis.
allowed-tools: Read, Write
---Deciding what counts as failure before the run is the only defense against reading the result you wanted.
---
name: decision-log
description: Use after any non-obvious decision. Writes one lesson per note
with a one-line summary, records what was rejected and why, and updates an
existing note rather than duplicating it.
allowed-tools: Read, Write, mcp__obsidian__*
---Memory the agent can read back is worth more than memory I can. Same vault, retrievable by both.
Layer 04 · Guardrails
Asking politely
is not a safety system.
A hook is a shell command the harness runs at a fixed point in the loop. It is deterministic code, not a suggestion in a prompt — which means it holds at 2am on the hundredth turn, when a prompt wouldn't.
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": ".claude/hooks/warm.sh" }] }
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": ".claude/hooks/deny-destructive.py" }]
},
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": ".claude/hooks/protect-paths.py" }]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": ".claude/hooks/format.sh", "timeout": 30 }]
}
],
"Stop": [
{ "hooks": [{ "type": "command", "command": ".claude/hooks/gate.sh", "timeout": 300 }] }
]
}
}SessionStartPrints the branch, the open PR, last night's CI result, and today's error budget into context.
The session starts grounded in reality instead of asking me for it.
PreToolUseBashParses the command and rejects destructive shapes — force pushes, collection drops, prod migrations, curl-to-shell.
Exits 2. The call never runs, and the reason goes back to the agent as feedback it can act on.
PreToolUseEdit|WriteBlocks writes to migrations already applied, lockfiles, and anything under infra/prod/.
Same exit 2. Some files are mine to change, not the agent's.
PostToolUseEdit|WriteReads the tool payload from stdin, formats and type-checks only the files that actually changed.
Style stopped being a review comment about two years too late.
StopRuns the full gate: lint, types, tests, secret scan, and the frozen eval set.
Refuses to let the turn end while anything is red — and hands back the actual failure output.
Layer 03 · Tool plane
Give it the system,
not a description of it.
MCP servers are how the agent stops guessing. It reads the live index config, the real schema, the actual stack trace. Nine servers, sixty-one tools, loaded on demand rather than all at once.
| Server | Transport | Surface | What it buys me |
|---|---|---|---|
qdrant | stdio | collection_info · search · upsert | Read the live index instead of trusting a stale diagram of it. |
postgres | stdio (read-only role) | query · schema · explain | Real schemas, real cardinalities, zero write path. |
bigquery | stdio | dry_run · query · table_info | Cost estimate before the scan, every time. |
github | http | PRs · reviews · checks · issues | The agent opens and updates its own PRs, and reads its own CI failures. |
gcp-logging | stdio | tail · query · metrics | Production errors become a first-class input, not a screenshot I paste. |
sentry | http | issues · events · releases | Reproduce from the real stack trace and the real release. |
playwright | stdio | navigate · click · screenshot | The UI agent looks at the page. Vision plus tools beats vision alone. |
obsidian | stdio | search · read · append | My decision log, retrievable by the agent that helped write it. |
linear | http | issues · cycles · comments | The ticket is the spec. It should be readable where the work happens. |
And then I made it installable.
All of it is packaged as one plugin, `am-ai-stack`, published to a private marketplace.
A plugin.json bundles the skills, the subagent definitions, the slash commands, the hook config, and the MCP server list into a single installable unit.
New machine, new repo, or a teammate who wants the same guardrails: one install command and the whole workflow comes with it — versioned, reviewable, revertible.
Parallelism
Seven specialists
beat one generalist.
An agent carrying every tool picks the wrong one. An agent with a narrow prompt and four tools doesn't. So the work fans out to a fleet — each with its own model, its own allowlist, and its own git worktree.
spec-writerclaude-opus-5-5tools: Read, Grep, Glob, Write
Turns a rough ask into constraints, edge cases, and a definition of done.
implementerclaude-sonnet-5-5tools: Read, Edit, Write, Bash
Executes a settled spec file by file. Never decides architecture.
adversarial-reviewerclaude-opus-5-5tools: Read, Grep, Glob
Cold context, no memory of the rationalizations. Reports everything.
test-writerclaude-sonnet-5-5tools: Read, Write, Bash
Writes tests against the spec, not against the implementation.
bench-runnerclaude-sonnet-5-5tools: Read, Bash
Runs the frozen eval set and reports deltas with the raw output.
log-triagerclaude-haiku-5-5tools: Read, Grep, mcp__gcp-logging__*
Reads 50k PLC logs a day so nothing upstream has to.
docs-writerclaude-fable-5-1tools: Read, Write
Turns a merged diff into a changelog entry and a PR description a reviewer will actually read.
Each agent is a markdown file in .claude/agents/ with its own model, its own tool allowlist, and its own system prompt. Narrow prompts and narrow tools beat one agent carrying everything.
Parallel agents run in separate git worktrees, so three of them can edit the same repo at once without touching each other's files.
They don't share a context window — only reports come back. That's the whole point: the reading happens somewhere I don't pay for it.
---
name: bench-runner
description: Runs the frozen retrieval eval and reports deltas. Use for any
change touching chunking, embeddings, search, fusion, or reranking. Give it
the branch and the baseline commit; it returns a table plus raw output.
tools: Read, Grep, Glob, Bash
model: claude-sonnet-5-5
---
Run the eval set at scripts/eval.py against both commits. Report recall@5,
MRR@10, faithfulness, and p95 latency as a delta table, then paste the raw
output underneath. Never summarise a failure as a success. If a run errors,
report the error and stop — do not substitute a partial result.Layer 02 · Context
The window is a ledger.
Every line item is a choice.
A million tokens of context is not permission to use a million tokens of context. Quality degrades from clutter long before you hit the ceiling, so every slice of the window has a rule attached to it.
System prompt + CLAUDE.md
~4k
Frozen bytes. Nothing dynamic above the cache breakpoint, ever.
Skill metadata (43 skills)
~1.8k
One line each, always resident. Bodies load only when a task triggers them.
Tool schemas (61 tools)
deferred
Tool search loads the handful this turn needs. Loading all 61 costs more than it's worth.
Retrieved code
~30k
Agent-selected through grep and read. I never bulk-paste a directory.
Working transcript
the rest
Compacts around 150k. Tool results get cleared before thinking does.
Subagent exploration
0
Happens in their windows. Only the report crosses back into mine.
In practice
What the hours
actually look like.
AI didn't change what I build. It moved almost all of my hours upstream, into deciding what should be built and proving that it was.
08:40
Read the night shift
Three overnight PRs, one red. The SessionStart hook has already put CI results and the error budget in context. I'm reviewing decisions, not diffs.
09:15
Write the goal, not the prompt
One page: constraints, edge cases, definition of done. If it's gradeable, it becomes a rubric. This is where I'm most useful and it takes the longest.
10:00
Fan out
Spec goes to the fleet. Implementer, test-writer, and bench-runner in three worktrees. I read reports, not transcripts.
12:30
Argue with the reviewer
Adversarial-reviewer flags an unbounded fan-out. It's right. We loop back to the plan rather than patching the symptom — the plan was wrong, not the code.
14:45
Watch the number
Bench-runner posts the eval delta into the PR. recall@5 up, p95 up too. That tradeoff is mine to make, and it's the one decision here a model shouldn't own.
16:30
One approval
CI green, gate green, benchmark in the body. I approve and merge. The approval is the job.
22:10
Queue the dark hours
Well-scoped, low-blast-radius work on the local model — migrations, test backfills, dependency bumps. Clear specs in, results waiting at 08:40.
Four things I’d tell you at the start
The agent writes the code. I own the decision. That line never moves.
Anything I'd explain twice becomes a skill. Anything I'd enforce twice becomes a hook.
Context is a budget with line items. Treat it like a bucket and quality drops before cost does.
Freeze the eval set before the change. An eval written afterwards grades the change that wrote it.
