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.
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 quality-ratchet revalidation seed-to-scale skill-authoring |
mentor-customers |
activation analytics-for-ai-products landing-page retention |
designer |
ai-ux-patterns celebration-of-done deceptive-patterns design-system |
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; /cost-review 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.
21 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
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
source BOSS’s own practice — extracted from its build, not from outside
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 — write 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 — Agentic ASI Top 10 / LLM Top 10 Veracode (Spring 2026) 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 Spring-2026 refresh. 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/Supabase RLS class), the MoltBook 1.5M-credential exposure, OX Security 2026 (62% of AI-built apps ship a critical vulnerability), 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 (Spring 2026) METR Andrej Karpathy — the verifiability thesis
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).
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 — Agentic ASI Top 10 / LLM Top 10 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
Design & interface
The failure modes that appear by default when AI writes your UI.
Design system — style never locked into code
learned from Brad Frost — Atomic Design Nathan Curtis — design tokens W3C Design Tokens Community Group
where this came from
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.
Also on the shelf
Practices that ship but have not been sorted into a group above yet.
Deceptive patterns (the catalog is data; this is the judgment)
source BOSS’s own practice — extracted from its build, not from outside
where this came from
The named patterns come from CDT's Dark Patterns in AI Chatbots (2026, CC-BY), Brignull's deceptive.design, Mathur et al.'s Dark Patterns at Scale, Gray et al.'s CHI-2024 ontology, and successive research sweeps covering accessibility, minors, agentic products, algorithmic management, and the patterns a model writes into generated code (Vaccaro et al., CHI 2026).
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 → · how BOSS decides when to speak →