AGENTS.md — BuilderOS

The shared contract for any agent working in this repository, and the project instructions for hosts that read AGENTS.md while working in this checkout. Host-specific additions live in CLAUDE.md, which explicitly imports this file. Installed plugins rely on their loaded components, not these root files.

What This Is

BuilderOS is the operating system for taking an idea or a problem to a product running in production. Eight gated phases, each with its own skills:

FRAME → DISCOVER → DEFINE → IDEATE → SHAPE → BUILD → SHIP → LEARN
  0        1          2        3        4       5      6      7

Phases 0–4 are design thinking. Phases 5–7 are delivery and learning. Phase 7 re-enters the loop rather than ending it.

Architecture

Lifecycle hub (builder-os) → phase skills → artifacts in .builderos/
                                  ↓                    ↑
                          capabilities resolved    gates enforced
                          at runtime               between phases

Standalone question → specialist skill → an answer, no state

Entry for both: using-builder-os (reads memory, briefs, routes)

Components

Project memory lives in the user's working directory: PRODUCT.md, DOMAIN.md and TECH.md at the root, and .builderos/ with ROADMAP.md, decisions/, evidence/ and one folder per initiative holding its own state.json and evidence/. Layout and rules in references/builderos-state-schema.md. Read memory before starting a phase; write it after finishing one.

Entry point on every host: skills/using-builder-os. Hosts with a session-start hook inject it; elsewhere, read it first. It briefs from the memory and routes.

Two kinds of work: the lifecycle (builder-os plus the phase skills) walks the pipeline, stateful and gated; a standalone task uses the relevant method and supplied context, preserves the requested format and destination, and writes no lifecycle state. A PRD, research plan or delivery plan can be standalone. Read references/operating-modes.md when mode is unclear.

Design Principles

1. Zero dependencies — only Node.js built-ins in the plugin loader and in scripts/bos.mjs
2. Data over guessing — every number comes from a real source and carries a source tag
3. Structured output — every phase has a completion marker and a handoff contract
4. Capabilities, not tools — name a capability and resolve it at runtime; never a literal tool identifier
5. Graceful fallback — every capability has a degradation ladder ending in "state the gap, ask the user, tag the answer"
6. Host-agnostic — skills run on any agent that reads SKILL.md; host features are adapters, never requirements

Non-Negotiables

Never invent data. Every factual claim in a lifecycle artifact carries a source tag per skills/evidence-ledger, and every lifecycle source tag points at a file in evidence/. Standalone answers may cite their direct sources without creating pipeline files. Gates count them and check the files. If a number cannot be retrieved, say so and ask; a plausible-sounding guess is worse than a stated gap.

Never skip a gate. skills/gate-checks holds structural checks and explicit model judgments for the eight phases. Failing one means refusing to advance and naming the condition. Overrides exist, are logged in state.json with a reason, and stay visible afterwards.

Never name a tool in a skill. Skills name capabilities (analytics.query, docs.search, subagent.dispatch, …) and resolve them against whatever this session exposes. See references/capability-map.md. A hardcoded tool name breaks on another host, another analytics stack, and another user's connector.

Prerequisites are zero. Every method can report useful work with nothing connected. Missing capabilities do not waive evidence or execution required by a lifecycle gate; unknown values stay unavailable. Inline work needs no file writes. Never tell the user to install or connect a named product: state the capability gap and the question closing it would answer.

Analytics is a contract, not a vendor. Five question shapes in references/analytics-contract.md. A skill asks for a shape; whichever provider resolved answers it.

Never require a host feature. Where a host can delegate to a separate agent, phases run in isolated contexts. Where it cannot, the identical procedure runs inline. No phase is unavailable because of the host.

Host Portability

BuilderOS must run on Claude Code and on Codex, and degrade sanely anywhere else. Contract in docs/specs/2026-09-21-host-portability.md, capability names in references/capability-map.md, host setup in docs/hosts.md.

The test: delete the host adapters while retaining the complete portable bundle (skills/, references/, scripts/); the same methods and gates must remain available. Manual discovery must preserve that bundle and resolve resources from the loaded skill’s real installation root; see docs/hosts.md.

Rules, enforced on every change:

1. No literal tool identifiers in any skill, agent or command. No mcp__*, no connector instance names, no vendor names as requirements. Name the capability.
2. Procedure lives in the skill. An agent containing numbered execution phases has stolen them from its skill.
3. No host-specific syntax in skills. No subagent dispatch calls, no slash commands. A skill may say "delegate if the host supports it, otherwise run inline".
4. Capitalized tool names belong to one host. Skills say "search the repository", not Grep.
5. Vendor names in prose only as examples: "a session-replay capability (PostHog, FullStory, …)".
6. Every phase states its capability requirements and its floor. A phase with no floor is not portable, only lucky.

File Naming

• Skills: skills/{skill-name}/SKILL.md
• References: references/{topic}.md
• All names hyphenated, lowercase

Skill Frontmatter

---
name: skill-name
description: "Does [what, in a sentence]. Use when [the requests and situations that should load it]."
---

The description says what the skill does and when to use it, in the third person, in the words a user would type, at most 250 characters. It is how a host decides to load the skill, and every description is in context in every session, so it carries no procedure. A description change is measured with the eval suite (evals/, claude plugin eval), never judged by eye.

Skill Contract

Every skill that drives work (as opposed to pure reference) MUST:

1. State when to use it, in triggering-condition form
2. Say in one Mode line how standalone and lifecycle use differ, pointing at references/operating-modes.md for the rest
3. Hold its method in ## Procedure: numbered steps, each ending on Done when and a checkable condition
4. List its capability requirements and the floor for each
5. Define its output contract and its completion marker
6. Write guidance as the behavior wanted; contrasts go in a Watch for table (Do / Instead of). Disclose reference the steps do not all need into references/, reached by a pointer

tests/scripts/skill-writing.test.mjs checks all of it, plus the line and word ceilings, the prohibition count and every relative link. The standard comes from Pocock's writing-for-agents: context pointers, completion criteria, leading words, positive phrasing, no-ops cut.

Testing

Three layers, cheapest first:

1. Script tests (pnpm test, which runs every tests/scripts/*.test.mjs). Deterministic: every gate condition the script decides, the briefing, roadmap regeneration, migration, and the host adapters (manifest versions agree, every command small enough for Codex to import), and the writing standard of every skill. Run them on every change to scripts/, skills/, the state schema, commands/ or a manifest.
2. Behavioral scenarios (tests/scenarios/). A real host runs a prompt on a copy of a fixture project, and the runner checks what it did to the files: state written, gate refused, nothing past phase 1 on a spike. This is the pressure-scenario method (run without the skill, load it, plug the rationalizations) made repeatable. Every failure found in a live run becomes a case.
3. Triggering prompts (tests/skill-triggering/). Which skill a message loads; checked by hand, per its README.

Contributing

• Read two or three existing files before creating a new one. Follow their shape.
• No placeholder content: no TBD, no TODO, no "implement later".
• Every skill change includes updated examples.
• Every capability change updates references/capability-map.md.
• Every change to what BuilderOS asks of analytics updates references/analytics-contract.md.