Facet
DeutschInstall

A documentation standard for AI-assisted development

Your agent says it's done. Check it against the feature record.

FACET is a documentation standard with one file per feature: a FACET record. Like a spec handed to your agent before development, it describes the expected behavior. With every change, the record is kept up to date alongside code references and test evidence.

  • facet testRuns the tests linked to each feature and reports their results per scenario.Read more
  • knowledgeFive Knowledge answers describe prerequisites, limits, entry points, common mistakes and success signals.Read more
  • facet lspStarts the language server that connects source anchors with their records in your editor.Read more
  • commit gateThe configured pre-commit gate requires review of changed anchored code before a commit can proceed.Read more
  • AtlasAtlas lets different roles read the same records, their requirements and the available evidence.Read more
  • —A dash indicates that no measurement is available; it does not claim a measured zero.Read more
  • ask the codeThe Atlas companion answers from records and source references. General file-editing tools are disabled; plugin actions require separate AI grants.Read more
  • facet mcpStarts the MCP server so an agent can use FACET tools to inspect and work with the registry.Read more
  • facet docs checkChecks whether generated help is stale compared with the Knowledge it was generated from.Read more

WHAT A RECORD HOLDS

Not just scenarios. Everything your team keeps re-explaining.

A feature record has seven facets, each answering a question somebody asks every week. And three more record types hold what no single feature owns: the rules, the beliefs and the data.

One stripe per facet2 / 7 · Contract

Feature · seven facets

Alongside · own records

FACET · contract

What behavior is required?

Scenarios in Given / When / ThenGherkinGherkin is the plain-language format that describes how software should behave as concrete examples, written as Given, When and Then.Read more about Gherkin, plus business rules in plain sentences. Rules carry the numbers that tend to be scattered through the code — the 14 days, the 50 %.

WHO READS IT

Product, QA, the agent before it edits.

YAMLcheckout/pricing/discount-codes.yaml
contract:  business_rules:    - id: discount-cap      rule: A discount never exceeds 50 % of the cart.  scenarios:    - id: expired-code-rejected      Given a code that expired yesterday      When the customer applies it      Then the total is unchanged

Field names from the schema/facet.schema.jsonOriginal excerpt from the English source.[…] Schema for a FACET feature record (FACET spec 1.3.0, Appendix A.1). […]View on GitHub · examples from FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub

THREE LEVELS. NEVER FOUR.

Your product already has a shape. The id is that shape.

Every record is named domain/capability/feature. DomainsDomain-Driven DesignDomain-Driven Design shapes software around the business domain and the words the people who know it use.Read more about DDD in FACET and capabilities are declared once, in one file. Write a record under a capability nobody declared and the lint stops you — while the id is still cheap to fix.

DOMAIN · what the product is about

CAPABILITY · what it can do there

FEATURE · one user, one sitting, one outcome

  • discount-codes

    5 scenarios · 2 rules

  • free-shipping-threshold

    2–9 scenarios

  • tax-display

    2–9 scenarios

The id these three choices build: checkout/pricing/discount-codes

  • too big

    “Manage my music”

    A goal across many sittings. That’s a capability, not a feature.

  • feature-sized

    “Create a playlist”

    One outcome someone would call done. Two to nine scenarios, at least one failure.

  • too small

    “Validate the playlist title”

    Nobody asks for it on its own. That’s a scenario of the feature above.

Domains name the product, not the org chart. Teams reorganise; ids don’t. Ownership has its own field, so the two can change apart.

HOW IT WORKS

The code moves. Everything that depends on it finds out.

account/access/password-resetexample repository · loops every 16 s

RECORD · password-reset.yaml

intent:  summary: A customer who forgot their    password gets a link by email. It works    once and stops after 60 minutes.contract:  scenarios:    - id: link-expires-after-60-minutes

CODE · src/reset.ts

// @facet: account/access/password-reset// @facet-role: primaryexport const LINK_LIFETIME_MINUTES = 60; export function isLinkValid(sentAt, now) {  return now - sentAt    < LINK_LIFETIME_MINUTES * 60_000;}

Resetting your password

We email you a link. It works once, for 60 minutes. After that, ask for a new one.

regenerated · fresh

record updated · link-expires-after-60-minutes$ facet docs checkstale: help/password-reset.md — written from an older revision of its recordregenerated from the record · every sentence cited

Replay · example repository · drift line in facet’s real format; hook and docs-check wording paraphrased

WHEN THE SPEC CHANGES

Change the requirement. See every place that has to follow.

Product moves the free trial from 14 to 30 days. The constant gets changed. The pricing page gets changed. The reminder still goes out on day 11 — and billing still charges on day 14.

RECORDbilling/subscriptions/free-trial.yaml
business_rules:  - id: trial-length-   rule: A new account gets 14 days free.+   rule: A new account gets 30 days free.contract:  scenarios:    - id: reminder-before-trial-ends      Given a trial that ends in 3 days      Then the customer gets one reminder    - id: first-charge-after-trial      Given the trial has ended      Then the card is charged once

One requirement changed. Five anchored locations and one referenced test need review.

anchor_list billing/subscriptions/free-trial6 places · 3 changed

The rows abbreviate source files opened after anchor_list. Surrounding code is hidden here; select an entry to see its example context. Line numbers mark anchors; the test location comes from record.verification.

  • src/billing/trial.ts:7Illustrative source after opening this file. The highlighted implementation line is separate from the anchor location; surrounding lines are abbreviated. anchor_list itself does not return this code.…// @facet: billing/subscriptions/free-trial// @facet-role: primaryexport const TRIAL_DAYS = 30export function trialEndsAt(start: Date) { return addDays(start, TRIAL_DAYS);}…Read about anchors
  • web/pricing/PricingPage.tsx:42Illustrative source after opening this file. The highlighted implementation line is separate from the anchor location; surrounding lines are abbreviated. anchor_list itself does not return this code.…// @facet: billing/subscriptions/free-trial// @facet-role: relatedexport function PricingPage() { return <h1>Start your 30-day free trial</h1>;}…Read about anchors
  • test/billing/trial.spec.ts:18This example test is referenced by record.verification, not returned as an anchor with a verification role. Surrounding test code is abbreviated.…describe('free trial', () => { it('expires after 30 days', () => { expect(trialEndsAt(start)).toEqual(addDays(start, 30)); });});…Read about anchors
  • src/jobs/trial-reminder.ts:23Illustrative source after opening this file. The highlighted implementation line is separate from the anchor location; surrounding lines are abbreviated. anchor_list itself does not return this code.…// @facet: billing/subscriptions/free-trial// @facet-role: relatedexport function scheduleReminder(start: Date) { return scheduleEmail({ sendAt: addDays(start, 11), template: 'trial-ending', });}…Read about anchors
  • config/billing/stripe.yaml:4Illustrative source after opening this file. The highlighted implementation line is separate from the anchor location; surrounding lines are abbreviated. anchor_list itself does not return this code.…# @facet: billing/subscriptions/free-trial# @facet-role: configsubscriptions: defaults: trial_period_days: 14 currency: EUR…Read about anchors
  • emails/trial-ending.mjml:9Illustrative source after opening this file. The highlighted implementation line is separate from the anchor location; surrounding lines are abbreviated. anchor_list itself does not return this code.…<!-- @facet: billing/subscriptions/free-trial --><!-- @facet-role: related --><mj-text> Your 14-day trial ends in 3 days</mj-text>…Read about anchors

WHAT THE CUSTOMER GETS — 3 PLACES MISSED

  1. DAY 11

    “Your trial ends in 3 days.” It doesn’t.

  2. DAY 14

    Stripe charges the card. The pricing page states 30 days.

  3. DAY 15

    A support ticket, a refund, a customer who doesn’t come back.

The list comes from the anchors in your code. Working through it is still the agent’s job — unanchored code still needs separate review.

anchor_list returns anchor locations, not matching code lines · test from record.verification · illustrative excerpts after opening each file

INSIDE AN AGENT SESSION

Your agent opens a file. The requirements arrive with it.

The plugin hooks into five moments of every session. Nobody has to remember to look anything up: when the agent reads anchored code, the record’s requirements and its scenarios are already in its context — before the first edit.

PostToolUse · Read · read-context.sh

The requirements arrive with the file.

The agent reads a file with an anchor. In the same step it gets the expected behavior and the ids of every scenario — before it changes a line. For the tests that stand behind them, it’s one call away.

Once per record and file per session; again after compaction. Capped at 8 KB.

AGENT CONTEXTcontext added to the read
read src/billing/trial.tsFACET claims for src/billing/trial.ts, before editing: billing/subscriptions/free-trial  promises: A new account gets 30 days free, one  reminder three days before the end, and the first  charge the day after.  contract: trial-length, reminder-before-trial-ends,  first-charge-after-trial, no-second-trial Check these existing claims before changing observable behaviour.Use read_facet for the full intent or contract; update the recordwhen its claims change.

hooks/hooks.json · context wording from the binary’s read hook · example feature

01 · ANCHOR

Hover a line of code. Read the expected behavior.

One comment ties the code to its record. Your editor follows the thread: hover for the requirements, jump to the record, rename it everywhere at once.

CODEinternal/checkout/discount.go
// @facet: checkout/pricing/discount-codesfunc Redeem(code string, c Cart) (Cart, error) {    d, err := lookup(code)    if d.Expired(now()) {        return c, ErrExpired(d.Until)    }    return c.Apply(d), nil}

checkout/pricing/discount-codes · active

A valid code lowers the cart total once. An expired code is refused, and the refusal names its expiry date.

3 scenarios · F12 go to record · F2 rename

RECORDdocs/facets/features/checkout/pricing/discount-codes.yaml
id: checkout/pricing/discount-codeslifecycle: activecontract:  scenarios:    - id: expired-code-is-refused      given: a code that expired yesterday      when: the customer redeems it      then: the total is unchanged and            the expiry date is shown

facet lsp · stdio server; requires a configured LSP client · example feature · Which editors can connect?In principle: Neovim and Helix with a custom server configuration; Emacs with Eglot and Sublime Text with the LSP package. VS Code needs a client extension; JetBrains IDEs can use LSP4IJ. These are client capabilities, not verified FACET integrations. File mappings and project roots must be configured; multiple language servers are client-dependent.Read the CLI reference

02 · facet test

Not lines covered. Features kept.

Run facet test and every feature gets its own verdict, from the tests its record names — fresh reports only. A green exit code alone doesn’t count.

facet test: verdict per feature
checkout/pricing/discount-codes3 test files, all passedpassed
checkout/cart/apply-vouchervoucher.spec.ts failedfailed
account/profile/export-datano report for export_test.gounmeasured
account/auth/magic-linkrecord names no test fileunmeasured
navigation/search/recent-queries2 test files, all passedpassed
billing/invoices/pdf-downloadrunner exited 0, wrote nothingunmeasured

$ facet test2 passed1 failed3 unmeasuredexample run

  • passedfresh report, every named test passed
  • faileda named test failed
  • unmeasuredno fresh report — unmeasured, not assumed green

Where should the next review go?

Make that decision with more than memory. FACET connects recorded fixes in Git history to the features they touched, keeping the commit, date and files. That gives you evidence for deciding where another review or better tests might help.

Give a recorded fix its product context

  1. A commit identifies a fix

    fix(checkout): reject an expired code

    Its subject matches the project's stated convention for bugfix commits.

  2. The changed file carries an anchor

    src/checkout/discount.ts

    Attribution follows the code anchors in the current working tree.

  3. The feature record retains the evidence

    checkout/pricing/discount-codes

    The defect ledger keeps the commit, date and affected files. Linked test evidence is read separately.

Illustrative values · not a measurement of this project
Features ranked by recorded fixes
FeatureFixes
checkout/pricing/discount-codessrc/checkout/discount.ts7
billing/subscriptions/free-trialsrc/billing/trial.ts3
account/access/password-resetsrc/account/password-reset.ts1

Seven recorded fixes do not mean seven open bugs. A feature with no ledger is absent rather than presented as an apparently clean zero.

CLIStart bounded; preview before writing
facet defects backfill \  --since=90.days --limit=500 --dry-run facet defects --top 3
  • --dry-run previews the import without changing records. Without it, only their defects block is updated.
  • Not every fix has a matching commit subject. Missing anchors and renamed or deleted paths also limit attribution.
  • The ranking counts bugs that were found and fixed. Read it beside test evidence and usage; it is not a verdict on today's bug count.
Explore the defect ledger and commands

Start with the software you already have.

An existing project does not need a restart to become traceable. Guided back-filling surveys the code, drafts feature records and makes the depth of review visible, including the questions that still need an owner's answer.

  1. Agree scope and effort

    First settle the area, languages and where the run protocol lives. A cost estimate comes before the actual run.

  2. Turn code into feature drafts

    The workflow surveys existing code into capabilities and drafts the corresponding records with their connections.

  3. Choose the depth of review

    A draft, review against code and observation in the product are different evidence. The report names which depth was used.

  4. Continue from what remains open

    Unresolved questions go to owners. An interrupted run resumes from its checked protocol instead of drafting everything again.

Compare every draft with the code

A separate review reads every draft against the implementation. Findings are revised, rejected with a reason or left as open work, including missing tests.

  • Feature drafts and format checksincluded
  • Review and revise every draftincluded
  • Reproduce deviations in the running productnot included

Result: reviewed and revised descriptions with a traceable list of remaining gaps.

/facet:setup

Setup leads into adoption of existing code. This is an agent workflow, distinct from importing recorded fixes with facet defects backfill.

Read the back-filling guide

Large runs can consume a substantial AI usage allowance. The examples show the workflow, not verified coverage of this project.

Zero means we looked. A dash means we didn’t.

MEASURED

0

failing tests. The suite ran, the report is fresh, nothing failed.

UNMEASURED

failing tests. No report came back. We won’t dress that up as a zero.

Atlas draws the difference everywhere — and doesn’t print a percentage without the number underneath it.

ATLAS

Your whole product. Readable by people who don’t read YAML.

One command opens your repository as a product map in the browser. Requirements, linked tests and drift become visible for seven kinds of reader. Atlas AI answers questions; plugins can add editing workflows such as wiki proposals.

Coming soonExplore Atlas
7 (source: the Atlas docs, Seven roles)
reader roles
3 (source: navigation/atlas/visible-depth)
depths: register, record, acceptance criterion
127.0.0.1 (source: internal/ui/server.go)
the only address Atlas serves on

checkout › pricing › discount-codesDeveloper

Redeem a discount code

  • A valid code lowers the total oncenamed ×2
  • An expired code is refusednamed ×1
  • Two codes don’t stackno test
  • The discount is capped at 50 %named ×3
  • src/checkout/discount.ts changeddrift

ASK ATLAS

Does the code still refuse expired codes?

Yes — redeem() returns ErrExpired before the total changes.

read 3 files · wrote none

03 · ATLAS

Seven readers. The page rebuilds for each.

Atlas reads your repository and lays out the same records for whoever is looking — not filtered, rebuilt. Leadership gets a report without schema words. Agents get raw data, with null where nothing was counted.

  • REPORT

    Where the product stands, in one sentence. No schema words.

  • THIS WEEK

    What changed

  • WATCH

    What is at risk

  • OWNERS

    Who holds what

  • OPEN

    Questions without an owner

  • UNMEASURED

    — shown as a dash

facet ui · runs on 127.0.0.1 next to your code · example layouts of the role surfaces

04 · ASK

Ask the code. Answers with controlled access.

Atlas AIAtlas with linked records as sources for AI answers.Atlas AI answers questions and drafts summaries using your existing sign-in; subscription use needs no extra FACET token purchase, while provider limits and any explicitly configured API billing still apply.View nowRead more here answers from your records and code and names its sources. Its standard tools cannot edit files or run a shell. Separately granted plugin tools can add specific actions; the wiki editor already proposes changes on a branch.

  • Write
  • Edit
  • Bash
  • WebFetch
  • WebSearch
  • Task

Where do we refuse an expired discount code — and does the record agree?

  1. reading docs/facets/features/checkout/pricing/discount-codes.yaml
  2. reading internal/checkout/discount.go
  3. reading internal/checkout/discount_test.go

In Redeem(), before the total changes: an expired code returns ErrExpired with its date. That matches the record’s scenario expired-code-is-refused.

Sources: internal/checkout/discount.go:15 · discount-codes.yaml

example

05 · KNOWLEDGE

Five questions.
Every feature explained.

  1. 01What must the user already understand to use this feature?
  2. 02When is this the wrong tool for the job?
  3. 03Where does the user enter this flow in the product?
  4. 04What mistakes do users typically make with this feature?
  5. 05How does the user know it worked?

Answer them once. FACET writes the help article, the FAQ and the onboarding — every sentence cited, every open question left out instead of made up.

Same answers. Five readers.

Answer “does it do that?” from the record, not from memory.

WHY IT’S BUILT THIS WAY

Every rule has a reason. Written into the specification.

Answers from the FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub. Read the whole argument there.

Why one record per feature — not per service or per page?
Because a feature is what people ask about. A service is implementation and gets an anchor; a page is where a user enters a flow and answers one Knowledge question. A feature passes five tests: you can name it without “and”, one person finishes it in one sitting, it has two to nine scenarios, removing it loses something a user can name, and one team could own it.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §2.1Original excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub, FACET §2.1.1Original excerpt from the English source.[…] It has between two and nine observable scenarios, including at least one failure path. […]View on GitHub

Why does the code point to the record, and not the other way round?
Because features don’t live in one folder. A keyboard-shortcut system may span forty files in twelve directories. One record, forty anchors — and when code moves, the anchor moves with it. A record listing paths would be wrong after the first refactor.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §2.3Original excerpt from the English source.[…] FACET does not require a feature-based repository layout. […]View on GitHub, FACET §3.3Original excerpt from the English source.[…] Where in the codebase the feature is implemented. […]View on GitHub

Why exactly three levels in every id?
Domain, capability, feature is the decomposition a product actually has. A fourth level means you are describing scenarios. Domains and capabilities are declared in one file, so a wrong id fails the lint while it is still cheap — ids don’t change once created.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §2.2Original excerpt from the English source.[…] Every feature has a canonical, stable identifier of the form: […]View on GitHub, FACET §4.4Original excerpt from the English source.[…] which is the decomposition a product actually has. […]View on GitHub

Why can’t a domain be a team?
Teams reorganise; ids don’t. An id built from the org chart is wrong on a schedule. Ownership has its own field so the two can change independently.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §2.2Original excerpt from the English source.[…] Every feature has a canonical, stable identifier of the form: […]View on GitHub

Why prefer a bigger record with more scenarios?
Because the two mistakes don’t cost the same. Splitting a record later is mechanical. Merging two retires two immutable ids and leaves a redirect behind for good. So when both readings pass, take the coarser one.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §2.1.1Original excerpt from the English source.[…] It has between two and nine observable scenarios, including at least one failure path. […]View on GitHub

Why is a missing answer left out instead of filled in?
Because a plausible answer nobody wrote is worse than a visible gap. Generated docs cite every sentence; an empty slot is omitted, and the owner sees it’s open. The same goes for numbers: unmeasured is a dash, not a zero.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §8.5Original excerpt from the English source.[…] The Knowledge facet exists precisely to feed this pipeline. […]View on GitHub

Isn’t “proves:” just a claim?
Yes, and we say so. The lint only checks that the scenario exists. That’s why facet test runs the named files and reports per feature — and calls a feature unmeasured when no fresh report came back, even if the runner exited 0.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §3.4Original excerpt from the English source.[…] The tests and property checks that prove the contract holds. […]View on GitHub · facet test

What doesn’t FACET try to own?
Strategy and rationale (they live in ADRs), UX and copy, ML behaviour that is only statistically correct, sprint planning. FACET records feature requirements and expected behavior.

Source: FACETOriginal excerpt from the English source.[…] a named, coherent capability of the product that can be reasoned about, changed, and owned independently. […]View on GitHub FACET §9Original excerpt from the English source.[…] FACET is a single source of truth for a defined domain of claims about features. […]View on GitHub

GET STARTED

Set up FACET before your agent's next change.

Four steps. A wizard walks you through them — it measures what’s already there, asks before it writes, and checks each step where it takes effect.

  1. 01 · PROJECT

    Open your project

    Nothing in your repository changes yet. The plugin stays silent in a project that hasn’t adopted FACET.

    check: the agent is in your project folder

  2. 02 · WIZARD

    Run the setup wizard

    /facet:setup

    It sees code and no records, and proposes the back-fill profile: scaffold, taxonomy of your domains, agent layer, git.

    check: every step checked where it acts

  3. 03 · ADOPT

    Back-fill the records

    /facet:setup adopt

    Surveys your code into capabilities and drafts a record for each — then hands back what only an owner can answer. Pick how thorough below.

    check: a protocol you can resume, a list of open questions

  4. 04 · CHECK

    Check what you have

    facet lint

    The lint checks every drafted record against the schema and the anchors in your code, and names each one that fails.

    check: one lint report for the whole registry

BACK-FILL · THREE WAYS TO ADOPT AN EXISTING CODEBASE

  • Quick

    tokens: low · quality: drafts

    Drafts only, unverified. On complex software, expect the records to be wrong in places.

  • Thorough

    tokens: higher · quality: good

    Reviews every draft against the code and revises it. Ends with a checklist of deviations and missing tests.

  • Evidenced

    tokens: very high · quality: very good

    Also reproduces each deviation in the running product. What it reports as a bug was observed.

You see a cost estimate before it starts. Every run keeps a protocol it can resume from. Questions only the owner can answer are handed back, not invented.