Decision 0023 · Accepted
Agent-first, API-first
principle
docs/principles.md already describes an optional "Agentic" theme: build for agents and humans, API-first, with MCP where appropriate.
- Status
- Accepted
- Built from:
- da88c48
Status: Accepted (2026-10-28). Amended by 0066 (contracts where agents or other systems depend on a capability, not in every spec). Amends 0007 (seven official principles become eight). Related: 0022. Spec: 011. Amended by 0049 (Flow's own agent uses CLIs, MCP, and APIs first; principle 3 becomes human-directed, agent-executed).
Context
docs/principles.md already describes an optional "Agentic" theme: build for agents and humans, API-first, with MCP where appropriate. No skill acts on it, so briefs and specs default to human-only products and UI-first slices. Agents increasingly use products directly, through APIs, MCP tools, and MCP Apps rendered inside agent hosts.
Decision
- Add an official principle to
PRODUCT.md: Agent-first, API-first. Every product is built for agents and people; capabilities are defined as contracts before interfaces. The "Agentic" theme indocs/principles.mdbecomes its elaboration. exploreasks who the agent users are in every brief: an agent journey beside the human ones, and agent alternatives. A brief with no agent users says so.- Slice 1 defines its capability as a typed API contract that the UI uses. When the brief names agent users, the same capability ships as an MCP tool.
- Specs use MCP Apps only when a journey needs the product's UI inside an agent host. Otherwise plain MCP tools suffice.
to-specwrites interfaces contract-first: API shape, MCP tool definitions, and errors and permissions an agent can act on.
Rationale
Asking about agent users is cheap and changes what gets built; shipping MCP for every product is not, which is why the rule is a default question and a conditional deliverable. A shared contract lets the UI, agents, and tests use one surface.
Alternatives
- Lens only, no principle. Rejected: the theme already existed as optional judgment and did not change behavior.
- Mandatory MCP everywhere. Rejected: conflicts with minimal process for products without agent users.
Consequences
PRODUCT.md,docs/principles.md, and documents that count the principles change together.exploreandto-specgain the agent lens; spec 011 applies it to slice 1.