# Set up with an agent (https://docs.owndiff.com/agent-setup) Install the GitHub App first ([Quickstart](/quickstart)). Then open your coding agent in the repository and paste this prompt: ```text title="Prompt" Set up owndiff in this repository. 1. Read https://docs.owndiff.com/llms-full.txt. It is the source of truth for owndiff.json and the .owndiff/ folder. 2. Explore the repository: any existing owndiff.json and .owndiff/, the README, docs, ADRs, PRDs and specs, and the main product areas in the code. 3. Write only what owndiff can't find by itself: - owndiff.json, only if it is needed: `context` when docs live outside the default paths, `ignore` for generated code, `areas` only when the code structure doesn't show them. - .owndiff/.md for business rules you found in code or docs that are not written down anywhere else: prices, plan limits, roles, legal requirements. One topic per file, short and in plain language. - .owndiff/.md for the main user flows that no PRD or spec describes: a user story with acceptance criteria, scoped with `include` to the code of that flow. - Don't copy existing docs into .owndiff/. owndiff reads them in place. 4. Add `check: true` only for rules whose breach should get its own check run, and ask me before you do. 5. Open a pull request with the configuration. List every rule you wrote down and the file or code you took it from. ``` ## What the agent does [#what-the-agent-does] The agent writes as little as it can. owndiff already reads your README, `docs/`, ADRs and PRDs, so the useful work is the rules nobody wrote down: a free plan limit hard-coded in a constant, an invoice that must never change after it is issued, a role only admins may grant. You review its pull request like any other. That pull request changes the rules owndiff reviews with, so owndiff marks it as a product decision: it is never **Aligned** until someone records the decision. ## Why a prompt and not a button [#why-a-prompt-and-not-a-button] owndiff is read-only on GitHub. It never writes to your repository, which keeps the app easy to approve in a security review. Your agent already has write access, works in your branch and opens a pull request your team reviews. ## Keeping it current [#keeping-it-current] Run the same prompt again when the product changes a lot, for example after a new pricing model or a new area. The agent reads the current `.owndiff/` first and updates it instead of starting over. # The .owndiff/ folder (https://docs.owndiff.com/configuration/owndiff-folder) `.owndiff/` holds what owndiff should know and check. Every Markdown file in it, including subfolders, is read on every review. ```text .owndiff/ review.md instructions for the main reviewer (fixed name) billing.md knowledge and rules (any name) team/ plan-limits.md subfolders only organize files README.md ignored, for people ``` Only `review.md` has a fixed name. Without it owndiff uses its default product reviewer. Folder names carry no meaning: the frontmatter decides what a file is. ## Knowledge [#knowledge] A file without frontmatter is always part of the main review. ```md title=".owndiff/billing.md" # Billing Amounts are stored in cents. An issued invoice never changes; a correction is a new document. ``` Write rules in plain language, the way you would explain them to a new teammate. Keep one topic per file and say why a rule exists when it isn't obvious. ## Scoped knowledge [#scoped-knowledge] `include` limits a file to pull requests that touch matching paths. ```md title=".owndiff/onboarding.md" --- include: ["apps/web/src/onboarding/**"] --- # Onboarding A new account always starts on the free plan. The trial starts only when someone picks a paid plan. ``` ## User stories [#user-stories] Code shows what the product does, not what it is meant to do. A user story with acceptance criteria tells owndiff the intent. Write it like any other knowledge file: ```md title=".owndiff/invites.md" --- include: ["apps/web/src/invites/**"] --- # Team invites As a workspace admin, I invite a teammate by email so they can join my workspace. - Only workspace admins can send invites. - An invite link expires after 7 days. ``` owndiff treats the story as a requirement and each acceptance criterion as a rule. A pull request that works on the story lists it in the summary with how far it is delivered. A change that contradicts a criterion breaks a rule. Stories that already live in a PRD or a `stories/` folder need no copy here; owndiff reads them in place. ## Checks [#checks] `check: true` also runs the file as a separate, narrow review with its own check run, `owndiff / `. Each check is a separate model run, so add one only for rules that need it. ```md title=".owndiff/team/plan-limits.md" --- check: true include: ["apps/billing/**", "packages/plans/**"] conclusion: failure --- # Plan limits Free: 3 projects, Pro: unlimited, 14-day trial. Any change to limits, prices or the trial length is a product decision. Flag it unless the pull request links a recorded decision. ``` ## Frontmatter [#frontmatter] Every field is optional. | Field | Default | Meaning | | ------------- | ---------------------------- | ---------------------------------------------------------- | | `title` | first heading, then the name | name in the summary and in the check run | | `description` | first paragraph | one line in the index the reviewer starts from | | `include` | every change | file globs that make the file relevant | | `exclude` | none | with `include`, file globs that never make it relevant | | `check` | `false` | `true` runs a separate check run | | `conclusion` | `neutral` | with `check: true`, `failure` lets the check block a merge | `conclusion` without `check: true` is an error. An invalid file shows up as a warning with the reason in the pull request summary and the `owndiff` check run instead of being skipped silently. ## Which revision counts [#which-revision-counts] owndiff reads `.owndiff/` from the pull request's head, so a new rule applies to the pull request that adds it. A pull request could also weaken the rule it is judged by. Any change to `.owndiff/` or `owndiff.json` is therefore a product decision and never **Aligned** without a recorded decision. # owndiff.json (https://docs.owndiff.com/configuration/owndiff-json) `owndiff.json` sits in the repository root. Every field is optional, and without the file the defaults apply. Most repositories don't need it. ```json title="owndiff.json" { "$schema": "https://docs.owndiff.com/schema/config.json", "version": 1, "areas": { "billing": ["apps/billing/**", "packages/stripe/**"], "onboarding": ["apps/web/src/onboarding/**"] }, "context": ["docs/adr/**/*.md", "docs/product/**/*.md"], "ignore": ["**/*.generated.ts", "migrations/**"], "triggers": { "excludeAuthors": ["dependabot[bot]"] } } ``` ## Fields [#fields] | Field | Meaning | | ------------------------- | ------------------------------------------------------------------------------------------------------ | | `areas` | Product areas and the files in them. owndiff finds areas from the code; setting `areas` replaces them. | | `context` | Docs owndiff reads as knowledge in place. Replaces the default discovery. | | `ignore` | Files that don't count toward the diff limit, such as generated code. | | `triggers.excludeAuthors` | Pull request authors owndiff skips, such as dependency bots. | | `triggers.skipDrafts` | `true` by default: drafts wait until they are marked ready. `false` reviews drafts on every push. | | `triggers.mode` | `auto` by default. `tag_only` reviews a pull request only while it has the `owndiff` label. | owndiff reads `triggers` from the pull request's latest commit. With `tag_only`, adding the `owndiff` label starts the review. ## Default docs [#default-docs] Without `context`, owndiff reads these as knowledge: ```text README.md docs/**/*.md doc/**/*.md adr/**/*.md **/*ADR*.md **/*PRD*.md **/stories/**/*.md **/user-stories/**/*.md **/*user-stor*.md **/*USER-STOR*.md ``` The reviewer reads the content of these docs, not only their titles. The ones that matter most for the pull request come first: docs its description or a linked issue names, docs whose path or title names a touched area, then PRDs and user stories. The pull request summary lists every file owndiff read and how it read it, so a wrong match is easy to spot. Set `context` when your docs live somewhere else, or when the defaults pick up files that aren't about the product. ## Validation [#validation] [`/schema/config.json`](/schema/config.json) is the JSON Schema. With `$schema` set, editors complete and check the file as you type. An invalid file is not applied. owndiff reviews with the defaults and shows a warning with the reason in the pull request summary and the `owndiff` check run. # owndiff (https://docs.owndiff.com/) owndiff reads every pull request for what it means for the product. It checks which requirement the change delivers, which product decisions it makes without a record, which business rules it breaks, and whether it stays in scope. It leaves code quality, bugs, style and security to your code review tools. ## Set up with your agent [#set-up-with-your-agent] owndiff is set up by a coding agent. Install the GitHub App, then give your agent the prompt from [Set up with an agent](/agent-setup). It reads your repository and writes the few files owndiff can't work out by itself. <Cards> <Card title="Quickstart" href="/quickstart"> From sign-in to the first reviewed pull request. </Card> <Card title="Set up with an agent" href="/agent-setup"> One prompt for your coding agent. </Card> <Card title="The .owndiff/ folder" href="/configuration/owndiff-folder"> Business rules and checks, in Markdown. </Card> <Card title="Reading a review" href="/pull-requests"> Verdicts, findings and check runs. </Card> </Cards> ## For agents [#for-agents] - [`/llms.txt`](/llms.txt) lists every page. - [`/llms-full.txt`](/llms-full.txt) has the whole documentation in one file. - Add `.md` to any page URL for its Markdown, for example [`/quickstart.md`](/quickstart.md). - [`/schema/config.json`](/schema/config.json) is the JSON Schema of `owndiff.json`. # Reading a review (https://docs.owndiff.com/pull-requests) owndiff posts one summary comment on each pull request and keeps it up to date on new commits. It also sets an `owndiff` check run and, when something needs attention, a label. ## Verdicts [#verdicts] | Verdict | Check run conclusion | Label | Meaning | | ------------------ | -------------------- | ------------------------- | ---------------------------------------------------------- | | **Aligned** | success | none | The change matches what the product should do. | | **Needs decision** | action required | `owndiff: needs decision` | The change makes a product decision nobody has recorded. | | **Breaks rules** | failure | `owndiff: breaks rules` | The change breaks a business rule from your docs or rules. | There are no scores. A finding quotes the source it relies on: a rule file, a doc, the pull request description or a linked issue. **Not recorded** has no source, because nothing records the decision. ## Findings [#findings] | Finding | Meaning | | ------------------------------- | ------------------------------------------------------------------------------ | | Breaks a rule | The code contradicts a written rule. | | Not recorded | The change decides something about the product without a record. | | Requirement not fully delivered | The pull request claims a requirement the code only partly delivers. | | Out of scope | The change adds behavior your docs or rules place outside the project's scope. | A finding marked **Not recorded** is settled by recording the decision in owndiff. The summary on the pull request updates and the decision is kept for later reviews. ## Checks from `.owndiff/` [#checks-from-owndiff] Every file with `check: true` that matches the change gets its own check run, `owndiff / <title>`. With `conclusion: failure` it can block a merge through branch protection. See [the .owndiff/ folder](/configuration/owndiff-folder). ## When owndiff doesn't review [#when-owndiff-doesnt-review] - Draft pull requests wait until they are marked ready, unless `triggers.skipDrafts` is `false`. - With `triggers.mode` set to `tag_only`, pull requests without the `owndiff` label are skipped. - Authors in `triggers.excludeAuthors` are skipped. - A pull request above the project's diff limit (3,000 changed lines by default) gets a short note instead of a review. Files in `ignore` don't count toward the limit. # Quickstart (https://docs.owndiff.com/quickstart) <Steps> <Step> ### Create a project [#create-a-project] Sign in at [owndiff.com](https://owndiff.com) and name a project. A project is one product, or one client's product if you are an agency. Knowledge from one project never reaches another. owndiff is in private beta. Signing up puts you on the waitlist, and you get an email invitation once you're approved. If someone invites you to their organization, you skip the waitlist. </Step> <Step> ### Connect GitHub [#connect-github] Install the owndiff GitHub App and pick the repositories that belong to the project. The app reads code and writes only checks, comments and labels. It never pushes to your repository. </Step> <Step> ### Let owndiff read the code [#let-owndiff-read-the-code] owndiff scans the repositories, which takes about a minute. It finds product areas, business facts such as prices and limits, and docs that disagree with the code. Pick the facts that must not change without a decision and copy them into `.owndiff/rules.md`. </Step> <Step> ### Add what owndiff can't find [#add-what-owndiff-cant-find] owndiff already reads your existing docs, ADRs and PRDs. Give your coding agent the prompt from [Set up with an agent](/agent-setup), and it writes down the business rules that live only in code or in people's heads. Merge the pull request it opens. </Step> <Step> ### Open a pull request [#open-a-pull-request] Every pull request gets a summary comment and an `owndiff` check run. Draft pull requests are reviewed once they are ready, unless [`owndiff.json`](/configuration/owndiff-json) says otherwise. [Reading a review](/pull-requests) explains the result. </Step> </Steps> Without any configuration owndiff still reviews pull requests. It reads the PR description, linked issues and the docs it finds. Configuration makes the review sharper. It is not required.