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.
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.
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.
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
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.
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;}
HELP ARTICLE · GENERATED
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.
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
DAY 11
“Your trial ends in 3 days.” It doesn’t.
DAY 14
Stripe charges the card. The pricing page states 30 days.
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.
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.
// @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
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.
| checkout/pricing/discount-codes3 test files, all passed | passed |
|---|---|
| checkout/cart/apply-vouchervoucher.spec.ts failed | failed |
| account/profile/export-datano report for export_test.go | unmeasured |
| account/auth/magic-linkrecord names no test file | unmeasured |
| navigation/search/recent-queries2 test files, all passed | passed |
| billing/invoices/pdf-downloadrunner exited 0, wrote nothing | unmeasured |
$ 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
A commit identifies a fix
fix(checkout): reject an expired codeIts subject matches the project's stated convention for bugfix commits.
The changed file carries an anchor
src/checkout/discount.tsAttribution follows the code anchors in the current working tree.
The feature record retains the evidence
checkout/pricing/discount-codesThe defect ledger keeps the commit, date and affected files. Linked test evidence is read separately.
| Feature | Fixes |
|---|---|
checkout/pricing/discount-codessrc/checkout/discount.ts | 7 |
billing/subscriptions/free-trialsrc/billing/trial.ts | 3 |
account/access/password-resetsrc/account/password-reset.ts | 1 |
Seven recorded fixes do not mean seven open bugs. A feature with no ledger is absent rather than presented as an apparently clean zero.
facet defects backfill \ --since=90.days --limit=500 --dry-run facet defects --top 3
--dry-runpreviews the import without changing records. Without it, only theirdefectsblock 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.
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.
Agree scope and effort
First settle the area, languages and where the run protocol lives. A cost estimate comes before the actual run.
Turn code into feature drafts
The workflow surveys existing code into capabilities and drafts the corresponding records with their connections.
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.
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.
Start in
/facet:setupSetup leads into adoption of existing code. This is an agent workflow, distinct from importing recorded fixes with facet defects backfill.
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.
- 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
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 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.
WriteEditBashWebFetchWebSearchTask
Where do we refuse an expired discount code — and does the record agree?
- reading docs/facets/features/checkout/pricing/discount-codes.yaml
- reading internal/checkout/discount.go
- 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
05 · KNOWLEDGE
Five questions.
Every feature explained.
- 01What must the user already understand to use this feature?
- 02When is this the wrong tool for the job?
- 03Where does the user enter this flow in the product?
- 04What mistakes do users typically make with this feature?
- 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.
Four ways in. One record underneath.
- CLIOne binary. 25 (measured by facet --help) commands, an MCP server for agents, a language server for editors.
- AtlasYour registry in the browser. Seven (source: the Atlas docs, Seven roles) reader roles, Atlas AI for questions, and plugins for wiki editing, decisions and processes.
- for ClaudeHooks at five (measured by jq '.hooks | keys' hooks/hooks.json) moments of a session, 13 (measured by ls skills) skills, 4 (measured by ls agents/*.md) subagents.
- Facet UI48 (measured by ls src/components/ui | wc -l in facet-ui) components that show the requirements and the gaps. Its own site, the same family.
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?
Why does the code point to the record, and not the other way round?
Why exactly three levels in every id?
Why can’t a domain be a team?
Why prefer a bigger record with more scenarios?
Why is a missing answer left out instead of filled in?
Isn’t “proves:” just a claim?
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.What doesn’t FACET try to own?
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.
- 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
- 02 · WIZARD
Run the setup wizard
/facet:setupIt 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
- 03 · ADOPT
Back-fill the records
/facet:setup adoptSurveys 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
- 04 · CHECK
Check what you have
facet lintThe 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.