what BOSS believes
The harness is the architecture
For long-running agent work, the thing that determines whether it succeeds isn't the prompt. It's the agent-computer interface: what tools exist, what they return, how failure is surfaced, what gets verified. BOSS treats harness design as an architecture decision with an owner, not as prompt-tuning.
Verifiability decides what to automate
Work whose output can be checked automates well; work that can't be checked doesn't, no matter how good the demo looks. That line, not model capability, is how BOSS decides where an agent belongs and where a human stays in the loop.
Capability shapes, never model names
BOSS pins no model name anywhere it ships. It routes by shape (cheap and mechanical, deliberate and hard, fast and interactive) so a new model release doesn't rot anything. A new tier that changes what "cheap" means is what triggers a re-look.
Green is not the same as right
The failure mode that matters with coding agents: they rewrite assertions to match broken behaviour. So a weakened assertion is a red flag even when the suite passes, and assertion churn with no change to acceptance criteria is the loudest signal on a diff.
Most teams should not build RAG yet
The practice's whole value is telling you what not to build. Long context has eaten a lot of what retrieval used to be for; recall@k comes before anything clever; and context rot is real, so more stuffed context is not linearly better.
CLAUDE.md and AGENTS.md do different jobs
The split is not cosmetic. Host-neutral rules, how this repo is built, tested and
shipped, belong in AGENTS.md, where any agent can read them.
CLAUDE.md is for what's genuinely Claude-specific. Steering neutral rules into
the Claude-only file is the common mistake, and it quietly locks your project to one host.
Both stay short. A context file that has grown past a screen isn't documentation; it's budget you're spending on every single turn.
A skill is a trigger before it's instructions
Most skills that don't work aren't badly written; they're never invoked. The description is the load-bearing part: it decides whether the model reaches for the skill at the right moment. Name the trigger phrases explicitly, keep one skill to one job, and put the judgment in the skill rather than expecting the caller to supply it.
Rent the runner, own the decision
Most founder "automation" is a cron job, and the categories most advice starts from are a rung too high. So it's a four-rung ladder climbed upward, and the rule at every rung is the same host-seam rule: don't author what the host already runs. Rent the execution; keep the judgment.
Three questions before anything runs unattended: what breaks if it runs wrong at 3am, who finds out, and how do you turn it off? If those don't have answers, it isn't ready to be unattended; it's ready to be a command you run.
Docs have two readers now
One is your user. The other is the model working in your repo, and it reads differently: it needs structure, canonical paths and unambiguous naming more than it needs prose. Writing for only one of them is why AI-built projects end up with docs that are simultaneously too long for a human and useless to an agent.
Agent security is its own discipline
Not web security with a chatbot on top. The lethal trifecta (private data, untrusted content, and a way to exfiltrate) is the shape to design against, and classifiers are non-deterministic, so they are mitigation and never a boundary.
The ones that change what you'd actually do
The positions above are the shape. These four are the ones with a specific mechanism underneath, and they're the reason the rest is worth holding.
The bug that is invisible from inside your own product
The most common way an AI-built app leaks its users' data is a schema the model generated correctly and secured not at all: row-level security never configured. And the reason it survives every test you'd think to write is that the app works. Logged in as yourself, every screen is correct.
RLS-off is not a functional defect. It's a missing security property, so no happy-path test, no amount of clicking, and no screenshot will ever show it. The agent isn't confused, either: ask and it will explain RLS correctly. It simply doesn't apply it unless told. That's why BOSS treats schema as a threat topic rather than a craft one, and why the spec asks up front who must not be able to see a thing.
Sourced to the Lovable RLS class (CVE-2025-48757, rated critical, and disputed by the vendor, which the practice says out loud rather than quietly dropping).
Read the test diff harder than the code diff
When writing code was expensive, tests protected work you'd already paid for. When generating code is nearly free, verification is the only scarce thing left. The suite stops being insurance and becomes the bottleneck.
Which produces one concrete review rule: a test file that changed in the same commit as the code it tests is the highest-signal thing in the whole diff. Not automatically wrong (an intentional behaviour change should move its test) but never routine, and the one thing that must never be skimmed. The fix is ordering rather than effort: write the acceptance criteria, or the failing test, before.
And for a path a model decides: run it k times and require all k to pass. One green run against a non-deterministic system is a coin that landed your way.
Documented conventions rot. Enforced conventions compound.
An agent re-derives your codebase's conventions from scratch every session. That single fact reorganises architecture work: anything you only wrote down drifts, and anything you encoded as a check compounds. It's the difference between a convention and a gate, and with an agent in the loop the gap widens weekly rather than yearly.
So the advice is two moves, not one. Defer the architecture costs you can defer: modular monolith first, extract when a real constraint forces it, where the modular half is the load-bearing word. And spend the rigor on the one-way doors, of which the schema is the obvious one: migrations as code from day one, versioned and replayable.
And BOSS held this as a rule with no runner for about 130 releases — the exact
failure it quotes. The design rung got six hooks; the code's own gate got none until
smoke-guard: a dormant Stop hook that runs the smoke
/smoke recorded (and the strict typecheck it folds in) when Claude finishes a
turn that touched source, reports green in one line, and hands red back as a reason to keep
going — once, never twice on the same failure. The Thoughtworks Radar (vol 34,
April 2026) names the shape feedback sensors for coding agents and puts it at
Trial: deterministic gates “wired into agentic workflows so that failures trigger
timely self-correction … before a commit is made.”
A number that can only move one way
Codebases don't decay in a bad commit. They accumulate anys, TODOs, skipped
tests, untyped boundaries and bundle bytes one reasonable-looking change at a
time: no single diff looks bad, and the trend is the damage.
A ratchet turns the trend into a gate: pick one number, write it down, let it move only in the direction you want. And the honest limit ships with it: don't ratchet something that punishes legitimate growth, or a number that can be gamed. A metric that makes the right change look wrong gets bypassed, and a bypassed gate is worse than none.
You never have to read any of this
The practices aren't a library you're expected to study. Each one is distilled into the prompt of the agent whose job it is, so the knowledge is already in the room when the work happens, not sitting in a file you'd have to remember to open.
mentor-architect already knows about row-level
security and tester already knows that agents rewrite assertions to match broken
behaviour. boss craft <name> is there if you want the full reasoning.what each builder already knows
| Agent | Already carries |
|---|---|
mentor-architect |
agent-security automation data-schema feature-flags git-workflow harness-engineering mcp model-routing retrieval scalable-architecture ship-it-live |
product-lead |
context-discipline documentation outside-claims quality-ratchet revalidation seed-to-scale skill-authoring |
designer |
accessibility ai-ux-patterns celebration-of-done deceptive-patterns design-system |
mentor-customers |
activation analytics-for-ai-products landing-page retention |
mentor-founder |
conscience-voicing founder-role-shifts harm-taxonomy |
mentor-capital |
first-dollar monetization-in-practice |
mentor-cofounder |
ai-adoption-culture |
tester |
testing-with-agents |
“It works” is not a claim you can make about a model
If the thing you're shipping is itself AI-mediated, the usual build gates stop being enough: a smoke test proves the endpoint answered, not that it answered correctly, and nothing in your CI has an opinion about what a good answer looks like. So MVP carries a set of verbs for exactly that gap.
/ai-cost sets per-user and per-feature budgets and wires a per-call
ledger; run again, it reads that ledger back and produces a dated review against
the budget. An AI product whose unit cost you first meet on the bill has already made the
pricing decision for you.
None of these pin a model name, same rule as everywhere else. They pin the discipline, which outlives the model.
Every one of these has a receipt.
22 technical practices, each carrying who it was learned from, the date it was last checked against reality, and the curve that says how fast its ground moves. The table below is generated from those files, attribution that has to be retyped is attribution that goes stale.
Building with agents
The harness, the context window, what gets written down — and what stays deterministic.
Harness engineering (design the thing around the model, not just the prompt)
learned from Anthropic engineering Dex Horthy — 12-factor agents Andrej Karpathy — the verifiability thesis GitHub Spec Kit / AWS Kiro Haytham (arslan70) — system-evolution ADRs Quantifying Overclaiming Propensity in Frontier LLM Agents (OverclaimBench, arXiv 2609.20812)
where this came from
Distilled from Anthropic's engineering writing on harnesses for long-running agents, scaling managed agents, and the Agent-Computer Interface; Dex Horthy's 12-factor agents; Karpathy's verifiability thesis; and the spec-driven-development lineage (GitHub Spec Kit, AWS Kiro). Two independent research threads named the harness as the biggest gap in how BOSS was building.
Context discipline
learned from Rule Taxonomy and Evolution in AI IDEs (Cai, Li, Liang, Li, Shahin — arXiv 2606.12231)
where this came from
Vetted against BOSS's principles rather than adopted on popularity. The AGENTS.md / CLAUDE.md split is re-verified against the host's own memory documentation each time this is swept — that ground moves with the host, not with us, and the practice had once gone silent about a scaffold BOSS itself shipped.
Documentation for a project built with AI
learned from Michael Nygard — Documenting Architecture Decisions Marty Cagan (SVPG) Anthropic engineering Hartwig Grabowski — Spec Growth Engine
where this came from
Consolidated from BOSS's own shipped capture discipline: seven artifacts spread across eight skills and no practice, so nothing could refresh, cite, or hold them to a standard. Externally grounded in Anthropic's Effective context engineering for AI agents (compaction, structured note-taking, JIT retrieval), Hartwig Grabowski's Spec Growth Engine (arXiv 2606.27045, June 2026 — spec-anchored, code-coupled, drift-enforced), and Marty Cagan's Discovery vs. Documentation. The formatting layer is new and unvetted by anyone outside BOSS; the llms.txt adoption claim is the fastest-moving thing in the doc and is caveated in the text.
Skill authoring, or writing skills the model actually triggers and follows
learned from Anthropic — the Agent Skills spec and template
where this came from
Adapted from Anthropic's own skill-creator skill — the wisdom, not the harness. The with/without eval machinery is deliberately left out; see "What's left out".
Route by capability, never by model name
source BOSS’s own practice, extracted from its build, not from outside
where this came from
Extracted from a real mistake. BOSS pinned a model alias in eight shipped agent files and hardcoded model ids and per-token prices. Within four weeks the pin was stale, the prices were unverifiable, and nobody could confirm the alias even resolved in a founder's install. Root cause is BOSS's own PRINCIPLE #3 — a model name buried in an agent file is locked into code; the reusable thing is the intent, which is stable, not the name, which is not.
Automation (rent the runner, own the decision)
source BOSS’s own practice, extracted from its build, not from outside
where this came from
Written to close a coverage gap: BOSS had been shipping the load-bearing line — the hardest line to fill honestly is what stays deterministic — with no practice behind it. The four-rung ladder deliberately starts one rung lower than the usual categories, because most founder "automation" is a cron job. The vendor tier follows PRINCIPLE #4: name the rung, never the stack.
Security
The failure modes specific to agentic systems, and the ones AI-written code introduces.
Agent security (a deterministic guard around a non-deterministic model)
learned from Simon Willison OWASP — LLM Top 10 (2026) + Top 10 for Agentic Applications Veracode (2026 GenAI Code Security Report) Anthropic containment + Redwood control
where this came from
Distilled from Simon Willison's agentic-security writing (the lethal trifecta; "Agents Rule of Two"; classifiers are non-deterministic), then hardened against the 2026 agent-native surface: OWASP's Agentic ASI Top 10, agentic misalignment, Anthropic containment and Redwood control, insecure AI-generated code and client-side key exposure, MCP confused-deputy and token-passthrough, tool-layer memory poisoning, AI-code iteration degradation, and Veracode's 2026 code-security measurements. UI dark patterns are treated here as an injection surface, not only an ethics problem, and a poisoned tool description is goal-hijack rather than supply-chain.
Data & schema (the layer an agent gets functionally right and dangerously wrong)
learned from CVE-2025-48757 (Lovable/Supabase RLS class) The MoltBook credential exposure OX Security 2026 PostgreSQL row-level-security docs Martin Kleppmann — DDIA
where this came from
Written to close a gap where the knowledge lived only inside one V1 agent's prompt and a migrations section — so nothing could sweep it and no earlier mode could see it. Sources: CVE-2025-48757 (the Lovable RLS class — rated critical, and disputed by the vendor), the MoltBook exposure (~4.75M records including 1.5M agent API tokens), the Veracode 2025 GenAI Code Security Report (45% of AI-generated code samples fail security tests against the OWASP Top 10, and that rate has stayed flat as models improved), the Postgres RLS documentation, and Kleppmann (DDIA) on schema evolution.
Testing & quality
Why an agent going green is not the same as the code being right.
Testing when an agent writes the code
learned from Hamel Husain + Shreya Shankar How Coding Agents Fail Their Users (arXiv 2605.29442) Professional Software Developers Don't Vibe, They Control (arXiv 2512.14012) Veracode (2026 GenAI Code Security Report) METR Andrej Karpathy — the verifiability thesis Haytham (arslan70) — system-evolution ADRs
where this came from
Written after BOSS's own library README had advertised a testing practice that did not exist. Sources: Hamel Husain and Shreya Shankar (error analysis, evals-as-spec, judge validation), How Coding Agents Fail Their Users (20,574-session misalignment analysis, arXiv 2605.29442), Professional Software Developers Don't Vibe, They Control (arXiv 2512.14012), Veracode Spring-2026, METR, and Karpathy's verifiability thesis. The seed line — agents rewrite assertions to match broken behavior — was BOSS's own, stranded in the git practice until it had a home.
The quality ratchet (a baseline that only moves the right way)
source BOSS’s own practice, extracted from its build, not from outside
where this came from
Ported up from a dogfooded product's own code-health gate: a ratchet file plus a check that is only ever allowed to tighten.
Git workflow for AI-native building (trunk-based, review-bounded)
learned from DORA / Accelerate Addy Osmani METR
where this came from
Distilled from founding-teams research on dev process — DORA/Accelerate, Addy Osmani on AI code review, the METR n=16 perception-gap study, and the worktree-as-parallelism-primitive practitioner pattern. A later citation-hygiene pass found unverified vendor multipliers sitting next to a DORA attribution: the numbers were cut, the direction kept and correctly sourced to DORA's ROI of AI-Assisted Software Development (2026.01). The commit/local/public tiers section comes from BOSS's own repo practice rather than that research — BOSS runs the same three tiers on itself, and got the boundary wrong for long enough to be worth writing down.
Revalidation (the 3-line gate before paused work re-enters build)
source BOSS’s own practice, extracted from its build, not from outside
where this came from
Ported up from a dogfooded product's own revalidation lifecycle.
Data, retrieval & protocols
What NOT to build yet, mostly.
Retrieval (a ladder, not a vector database; climb only when it hurts)
learned from Anthropic engineering Chroma — context rot Jason Liu — systematically improving RAG
where this came from
Distilled from Anthropic (contextual retrieval; the ~200k-token skip-RAG line; the native memory tool), Chroma on context rot, Jason Liu on systematically improving RAG (recall@k first; inventory versus capability), and the hybrid-search/RRF plus recursive-512 chunking consensus. The whole value of this one is telling a founder what NOT to build yet.
MCP (decide whether it matters yet, before you wire anything)
learned from MCP specification (2026-07-28) MCP deprecated-features registry Simon Willison
where this came from
Distilled from the protocol's own record — MCP donated to the Linux Foundation / Agentic AI Foundation (Dec 2025), WorkOS and Anthropic ecosystem reads, Willison on MCP prompt injection — then refreshed against the shipped 2026-07-28 revision, read from the primary changelog. What changed on that pass was the judgment, not just the date: this doc had called the ground "still moving" and said build against it rather than toward it, and then the revision landed with a formal feature-lifecycle and a 12-month deprecation policy, which is the ground acquiring rules for how it moves. A later sweep found the extensions under-weighted rather than wrong — MCP Apps (GA Jan 2026) makes the integration shape a product-surface call and not only a distribution one, and Tasks is the long-running seam. The registry is still preview. The security half lives in agent-security.md, deliberately not duplicated here.
Shipping & scale
Getting it live, and what to do when it grows.
Ship it live (the CD half: localhost is not shipped)
learned from DORA / Accelerate Martin Fowler Simon Willison OWASP — LLM Top 10 (2026) + Top 10 for Agentic Applications CVE-2025-48757 (Lovable/Supabase RLS class) The MoltBook credential exposure
where this came from
Distilled from a CD/deploy deep-research pass — 21 sources, 25 claims adversarially verified by 3-vote, 22 confirmed and 3 killed. DORA/Accelerate 2022–2024, Fowler's ParallelChange, Willison's lethal trifecta and the OWASP LLM Top 10, with CVE-2025-48757 (Lovable) and the MoltBook breach as the named vibe-coded incidents.
Feature flags (decouple deploy from release, and flag the model, not just the feature)
learned from GrowthBook ConfigCat Unleash / LaunchDarkly Shape Up Addy Osmani
where this came from
Distilled from GrowthBook ("flag the model, not just the feature"; A/B-testing non-deterministic LLMs), ConfigCat (flags as a vibe-coding safety net), Unleash and LaunchDarkly (trunk-based flags plus flag-debt hygiene), Shape Up (the circuit-breaker and appetite), and Addy Osmani on the 70%-to-80% problem.
Architecture that survives the climb (defer the tax, enforce the conventions)
learned from Martin Fowler Shopify's modular monolith Factory.ai
where this came from
Distilled from founding-teams research on technical scaffolding that survives the climb — Fowler's MonolithFirst, Shopify's 2.8M-line modular monolith, Bezos's one-way and two-way doors, Factory.ai ("documented conventions rot; enforced conventions compound"), and Notion's eslint ratchet.
Seed to scale: does it exist, what rung is it on, and what seam does it leave?
source BOSS’s own practice, extracted from its build, not from outside
where this came from
Generalized from a shape BOSS had already solved four times without naming it — a measurement seam, a schema's one-way doors, a token file that gets dearer per screen, and a refactor one existing component first rule — into one practice: does the thing exist, what rung is it on, and what seam does it leave. No outside source is claimed; it is a pattern found in BOSS's own practices and named once.
Design & interface
The failure modes that appear by default when AI writes your UI.
Design system, or style never locked into code
learned from Brad Frost — Atomic Design Nathan Curtis — design tokens W3C Design Tokens Community Group UXBench (Wang et al.) GitHub Primer — contributor docs & ADRs zeroheight — Design Systems Report 2026 Feature-Sliced Design Alan Alickovic — bulletproof-react Radix Primitives Omlet Chromatic
where this came from
The limits of an AI-run design review — it reliably improves feedback and scannability, and barely moves whether the flow itself is right — come from UXBench (2026), read as direction rather than magnitude. Generalized from a dogfooded design system — design tokens as the single source of truth, central badge and pill style utilities, an enforcement hook that rejects raw framework colors, and a prototype registry — then stripped of everything product-specific so it would transfer. The AI-failure-mode catalog was written in the same pass.
AI-native interface patterns (2026)
learned from Shape of AI Microsoft HAX guidelines Google PAIR Nielsen Norman Group (2026) Apple HIG — generative AI CDT — Dark Patterns in AI Chatbots (2026) Vaccaro et al., CHI'26
where this came from
Distilled from an AI-UX scan across Shape of AI, Microsoft HAX, Google PAIR, IBM Carbon, LangChain HITL, NN/g 2026 and Apple's HIG for generative AI. The dark-pattern checklist and its humane alternatives come from CDT's Dark Patterns in AI Chatbots (2026, CC-BY); the classic web pattern families and their regulatory teeth (effect-not-intent, symmetry-in-choice) from the first humane sweep; the cohort and frontier patterns — accessibility, minors, agentic, algorithmic management — plus junk-fee teeth from the second. Later additions: generated code injects dark patterns (Vaccaro, CHI'26) and the dev-tool metering surface. The dark-pattern catalog has since moved to its own practice and data file so it can grow without growing what any one founder reads.
Accessibility: the guidelines, not the compliance theatre
learned from W3C Web Accessibility Initiative (WAI) ARIA Authoring Practices Guide
where this came from
Structured on W3C's own framing — the four POUR principles and the WCAG conformance levels — so a recommendation can always be followed back to the standard it came from. The split between what a tool can check and what needs a person is BOSS's, inherited from the observed/inferred discipline its after-code review already uses.
Judgment
What to do when a stranger tells you how to build.
Outside claims (when a stranger tells you how to build)
source BOSS’s own practice, extracted from its build, not from outside
where this came from
Distilled from BOSS's own discipline for judging unproven outside claims, and from thirteen times it got the attribution wrong itself.
What happens when this goes out of date
It will. The interesting question is whether anything catches it. Each practice's curve routes it to a discipline that owns re-checking it (the model curve, the protocol curve, the threat curve, the craft curve) and reviews fire on events, not just dates: a spec revision, a new frontier model, a breach, a ruling.
That matters because cadence alone provably misses. On the first freshness run everything reported fresh while the MCP practice was already wrong, seven days after it was written, because the spec had shipped in the meantime and the doc still described it as forthcoming. A calendar would not have flagged it until October.
And because boss sync pushes this guidance into live projects, a stale practice
isn't inert; it actively ships bad advice. So the sweep hunts for what's wrong,
not just what's missing.
How a claim gets in here in the first place, and how BOSS decides when to speak.