The Precedent handbook
Connect your AI assistant
Give your assistant the decisions your team has already made. Choose your app, approve access, and try one useful question.
Connect in three steps
1 Connect Claude
Install the Precedent plugin to add the connection and decision-librarian skill together. No Python, npm package, or local server is required.
In Claude, open Customize → Plugins → Personal → Add marketplace. Paste the repository URL below, then install and enable Precedent. Plugin availability depends on your assistant and organisation settings; if unavailable, use manual setup.
Already connected through a script or manual setup? Remove the old installation first to avoid duplicate connections and skills.
Manual setup
Add this remote HTTP server in your assistant’s MCP settings, authorise it, and install the skill separately.
https://precedent.biz/mcp2 Approve access
Connect the server to open Precedent’s authorisation screen. Sign in and select your workspace.
Read access lets the assistant retrieve decisions you can see. Draft access also allows proposals, evidence, links, and review observations. Decide covers approving and the other changes to a decision, and the assistant asks you before each one.
3 Try it in a fresh conversation
Set up Precedent for this project and load the decisions that apply.
In a git repository already recorded in Precedent, the assistant asks nothing more. Otherwise it asks which Areas the repository should follow, up to three, and where its new decisions are recorded. If you are the only person in the workspace and it has at most one Area, the assistant uses that Area, or creates one named after the repository, once you accept. If there are no Areas yet and others share the workspace, create one in Precedent and retry.
This page cannot check which local files or skills your app has loaded. Complete this read in your assistant to verify the connection.
Optional automatic reminders can surface decisions when you send a prompt. The standard setup has no hooks, blocking checks, or transcript capture.
Set a repository up
Install once and approve a whole-workspace connection. In a git repository, your assistant tells Precedent the repository's remote. If the repository is already recorded, setup is done: Precedent knows which Areas it follows. If it is not, the assistant asks which Areas it should follow, up to three, and where its new decisions are recorded, and adds it to Precedent once for everyone. If you are the only person in the workspace and it has at most one Area, your assistant adds the repository and records its decisions in that Area, or in a new one named after the repository, once you accept.
The assistant saves a small, credential-free .precedent.json in the project root. For a recorded repository it names the workspace and the repository; otherwise it names the Areas you chose. Future sessions validate and reuse it. A version 1 file from an earlier release is refused; ask the assistant to set the project up again. To change what a repository follows, open its page in Precedent. Assistants without project files keep the selection for the conversation.
Your assistant uses decisions tagged with any Area the repository follows, with duplicates removed. The recording Area is used only when the repository also follows it. Conflicts are reported for human review. New drafts attach only to the recording Area and still need approval.
.precedent.json guides the assistant; it does not restrict the connection’s authorised access. An Area-bound connection can use only its own Area, both to follow and to record in. Deleted or inaccessible Areas need a new choice.
Connect to one project or domain
Open an area where you have Member access or higher, or any area as a workspace administrator, expand For integrations at the bottom of its page and copy the server URL (MCP) from Connect an assistant here. Add that URL manually in your assistant and approve the matching area on the consent screen. Use a distinct connection name for each area. The public plugin uses whole-workspace discovery; use manual setup when authorisation must be limited to one area.
Reads include decisions explicitly tagged with the selected Area. New drafts default to this area and cannot broaden their scope. A direct decision reference or another area argument cannot widen the connection.
Call get_area_context without arguments to verify the selected context. Read every page indicated by nextOffset. The first page starts with the Area's decided rules, under rules, up to 50 of them. rules.omitted counts the rest: call search_decisions with type: "rule", status: ["decided"], the Area, limit 20 and offset 50 to list them. Then come its decided terms, under terms: what words mean in this Area, up to 50 of them, A to Z, each with its meaning in full. terms.omitted counts the rest: call search_decisions with type: "term", status: ["decided"], the Area and limit 20, paging with offset, to list them. Then come its decided lessons, under lessons: what has caught the team out in this Area and what to do instead, up to 25 of them, newest first. lessons.omitted counts the rest: call search_decisions with type: "lesson", status: ["decided"], the Area, limit 20 and offset 25 to list them. Then come the Area's decided how-tos and facts, under listed, by title and summary, up to 50 of them together, newest first; listed.omitted counts the rest: call search_decisions with type: "how_to" and again with type: "fact", each with status: ["decided"], the Area and limit 20, paging with offset, to list them. Call get_decision for a how-to's steps. A fact's row carries lastVerifiedAt, the day its current text was last approved, and its expiry; get_decision returns lastVerifiedAt for a fact too, null for one never decided. Settings → Assistants shows the context and lets you revoke each connection independently. Changing context requires a new approval.
Choose what the assistant can do
The approval screen lists the permissions the assistant asks for, each ticked; an assistant that asks for none in particular is offered all three. Read decisions is always granted. Draft decisions lets the assistant create and update drafts, link decisions, propose supersessions and add a repository. Decide is the permission for approving, revising, reaffirming, superseding, reversing and archiving through the assistant, which asks you before each change and can do only what you can do in Precedent. See approving a draft and changing a decision. Untick Decide for an assistant that runs unattended.
A workspace administrator can turn off Assistants can decide under Settings → Approvals. Reading and drafting are unaffected, and the change applies from each connection's next call without reconnecting. A Viewer's connection never decides. A connection approved before Decide existed does not have it: approve a new connection and check that Decide is listed and ticked. If it is not listed, the assistant asked only to read and draft: remove Precedent in the assistant and connect again. Settings → Assistants shows whether each connection can decide.
Update or remove the plugin
Use your assistant’s plugin manager to refresh the Precedent marketplace and update, disable, or uninstall the plugin. Start a fresh conversation after changes. The plugin includes the skill and remote MCP configuration; you do not need Python or an npm package.
Remove project reminders before uninstalling the plugin. Keep .precedent.json if you plan to reconnect. Uninstalling local files does not revoke remote access: revoke unused connections under Settings → Assistants after checking no other installation uses them.
Move from the script or manual setup
Use one Precedent connection and one copy of the skill per assistant. Before installing the native plugin, remove your old managed installation with the original client, scope, and area options:
bash /tmp/precedent-install.sh --client codex --scope project --uninstall
Use --client claude for Claude Code, --scope user for an account installation, and the original --node value for an area-bound installation. Managed uninstall preserves edited files and reports them for review. For manual installations, remove the old MCP entry and standalone decision-librarian skill through your assistant. Preserve unrelated configuration and your project’s .precedent.json.
Remove old Precedent hook entries before enabling new reminders. Then install the plugin, authorise its connection, and run the first prompt above. Revoke old connections only when no other installation uses them. A shared connection may still be needed by another project.
Advanced legacy installer
The deployment-specific Python installer remains available for existing managed setups and compatibility. It requires Python 3.10 or later and the assistant’s CLI on macOS or Linux. It is not needed for native plugin installation.
curl -fsSL 'https://precedent.biz/install.sh' -o /tmp/precedent-install.sh bash /tmp/precedent-install.sh --client codex --scope project
Use --dry-run to preview changes, --doctor to check managed files, and --uninstall to remove unchanged managed configuration. Rerun with the same client, scope and area options to update. The legacy integration bundle includes checksums and the deployment’s endpoint.
The decision-librarian skill
The skill tells your assistant to search before consequential choices, cite conflicts, answer from recorded rationale, and draft only with agreement. These core rules also travel with the MCP server. Instructions guide the model; they do not guarantee compliance.
Start with the brief. get_project_brief returns one short list of the decisions in force for the project: warnings first, then each decision's reference, Type and title. When the list is long it says how many it left out. It is small enough to load at the start of every session. Your assistant opens the full record of a decision only when the task needs it.
For manual Codex project setup:
mkdir -p .agents/skills/decision-librarian curl -fsSL 'https://precedent.biz/skill/decision-librarian' -o .agents/skills/decision-librarian/SKILL.md
Claude Code uses .claude/skills/decision-librarian/SKILL.md. User skills use the equivalent directory under your home folder. Other skill-compatible assistants can use the same file.
For Acme Robotics, ask why Postgres was chosen over Elasticsearch for search. The assistant should retrieve AR-041, cite the recorded rationale, and link to the decision. It should say when the record does not contain an answer.
Bring in what you already have. Ask your assistant: “Record what is in AGENTS.md in Precedent.” It reads that file, lists the rules, how-tos, facts, lessons and terms it finds, skips any that are already recorded, and offers the rest one at a time. Each one is a draft until a person approves it. Each draft counts towards your plan’s monthly allowance.
Keep a copy in the repository
Tools that cannot reach Precedent, such as a code review bot or a teammate's assistant with no Precedent connection, read only the repository's instructions file. Your assistant can add a Precedent section to AGENTS.md: a short copy of the decisions in force, with a pointer back to Precedent.
Precedent writes the section and your assistant inserts it unchanged, after you agree to the diff. Change a decision in Precedent, never in the section: an edit there is overwritten.
<!-- precedent:begin v1 digest=sha256:265b7499b67caccd1c6a2a30ecd9a1dbc6818fc2525f3185fb98b701e8e3ea85 --> ## Decisions kept in Precedent This repository follows decisions kept in Precedent, where each has an owner and a review date or condition. Before you plan or change code, load the current decisions with the Precedent tool `get_project_brief`, and open any you need with `get_decision`. Where Precedent and this copy differ, Precedent is right. If you cannot reach Precedent, follow this copy. This section is written by Precedent. Change the decisions in Precedent, not here: edits here are overwritten. Areas: `Inspection`, `Platform`. ### Decisions in force - `AR-041` · `Choice` · `Use Postgres rather than Elasticsearch for catalogue search` - `AR-097` · `Rule` · `Keep raw inspection images for no more than 7 days` - `AR-112` · `Choice` · `Do not use Moneyman for payments` Exceptions in force: 1. Their titles are not copied here; call `get_project_brief` to read them. <!-- precedent:end -->
The section lists decisions from the Areas the repository follows. It leaves out restricted Areas, and it counts exceptions without naming them, because everyone who can read the repository can read the section. For a public repository your assistant asks a second time before writing.
If the repository has a CLAUDE.md with its own content, the section goes into both files, because Claude Code then reads only CLAUDE.md.
Access and tools
The remote endpoint uses Streamable HTTP and OAuth with PKCE. It serves the 2026-07-28 MCP protocol and the 2025 revisions, so older clients keep every tool. It keeps no session between requests. Each connection belongs to the person who approved it and one selected workspace. Restricted areas and workspace roles still apply.
Read tools search decisions, retrieve rationale, Area context and the project brief, trace impact, and list Areas, reviews due and decision Types. search_decisions accepts a type, a Type's key such as exception, to return only decisions of one Type. get_decision includes the decision's outcome history: each resolved review with its outcome, who resolved it, when, and the reason given. For a how-to it returns the steps of the revision it returns: the one in force, or the one revisionNo names, under revision.body; a draft's steps are not in force. A decided decision with a change waiting for approval also returns proposedChange: its kind, who proposed it and when, each changed field with its proposed text, the reason, its approvals, and whether you can approve it. Proposed steps appear only under proposedChange. The optional reminder uses the read-only get_agent_context tool.
get_area_context and get_agent_context also return warnings: recorded facts about decisions you can see in the checked Areas, or that the prompt names by ref. There are four kinds: expired_exception, expiring_exception (within 14 days), superseded_referenced (with the successor to follow) and review_overdue. Each carries the ref, title, a one-line reason, the decision URL and an escape hatch: propose an exception with propose_decision and the Exception Type, or a replacement with propose_supersession. Search matches are returned separately as suggestions and never produce a warning. The decision-librarian skill tells the assistant to show you each warning before it acts. For example, if the exception AR-120 to AR-041 expired yesterday, an assistant working in that Area says so, says AR-041 applies again in full, and offers to propose a new exception rather than relying on AR-120.
propose_decision, update_draft, and propose_supersession use the same save service as the web editor. propose_decision, update_draft and revise_decision take a how-to's steps as body, in markdown, at most 3,000 characters; leaving it out keeps the steps. Each prompt that sets, changes or approves steps shows their first 300 characters on one line, with their length in characters. Checks use the workspace model or the app-funded Luna default when available. Each response includes conflictCheck: a clear, conflicts, unavailable, not_configured, or not_applicable status (How-to, Fact, Lesson and Term decisions are not checked for conflicts), how many of the applicable decisions were compared, and findings with references and source quotations. Each finding carries two flags: incompatible marks a conflict, and replaces marks guidance that decides the same question and that the proposal would make obsolete. Only visible, currently effective confirmed guidance sharing an Area tag is compared, and only the closest matches by similarity. A draft remains saved on a provider failure. Conflicts require a person to review and acknowledge them before asking for approval. Through approve_decision and ask_for_approval, the prompt names each unresolved conflict, and accepting it is the acknowledgement; the assistant cannot acknowledge without the prompt. Replacements need no acknowledgement; ask the person to review the Supersede control on that finding in the web app. For a How-to, Fact, Lesson or Term draft, propose_decision and update_draft also return similar: up to three decided decisions of those Types that share an Area with the draft and read alike, nearest first, each with its url and type, or an empty list. It is a hint and never blocks approval. Choices, Rules and Exceptions have no similar.
When a draft conflicts with confirmed decisions, either side can change. The assistant names every conflicting decision and can offer to revise the draft, or to change an old decision: amend its wording, reverse it, or have the draft supersede it. check_conflicts returns the findings, the changes already staged on the draft, and for each decision what you may stage and its current text. It runs the check again only when the stored one is out of date. suggest_conflict_fix asks the workspace model for one suggestion and lists the tool calls that would use it; it changes nothing. stage_conflict_change stages a change on the draft and remove_staged_change removes one. Every change is optional, and the skill tells the assistant to stage nothing without your agreement. For example, while drafting AR-042 to move catalogue search to Elasticsearch, an assistant cites AR-041, which keeps search on Postgres, and asks whether to revise AR-042, to stage a supersession or a change of AR-041, or to leave both as they are.
Staged changes are draft content. Nothing changes on an old decision until the draft becomes Decided, which applies the staged changes all or none; the changed decision's Areas must approve too. You can remove any change first in the web app, and approving with nothing staged is allowed. An assistant can stage only on a draft you can edit, and only a change you could make yourself. An Area-bound connection stages only on records tagged with its own Area alone. Staged changes record that an assistant proposed them and the person it acted for.
The propose_decision and propose_supersession responses also include feedback: current decisions with recorded links to the draft, to the decisions it explicitly supersedes, and to the decisions the check says it may replace. An unavailable check or feedback does not undo the draft.
With draft access, an assistant can propose or revise drafts, propose a successor, stage changes to conflicting decisions on a draft, attach evidence, link decisions, record review observations, and add a repository, each after a prompt when its app can show one. Supporting evidence, links, and observations take effect when saved.
With the Decide permission, an assistant can also approve a draft when you ask it to, with approve_decision. A draft becomes Decided when it has the approvals its Areas require. Your app shows a prompt naming the draft and its revision, each Area and what it still needs, whether your approval decides it, each decision it supersedes, each staged change it applies and each unresolved conflict. If nobody has asked for approval yet and you may ask (you own the draft, or administer one of its Areas or the workspace), approving asks first. When your own approval does not count, ask_for_approval asks the people its Areas require. request_changes records that you want changes, with your note; the draft cannot become Decided until you approve it or withdraw the request in the web app. Withdrawing an approval or a request, dismissing a request and moving a draft back to draft happen on the decision page. A call that cannot succeed is refused before any prompt with the reason, for example: you are not eligible in any of its Areas, nobody has asked and you may not ask, the Type's checklist is incomplete, or a reason or a current conflict check is missing. Superseding a decided decision needs your written reason when approval has not been asked yet, which the assistant passes and the prompt shows. Another person approving after the prompt was shown does not stop yours, unless it changes whether yours makes the draft Decided, or it also asks for approval again. If the draft, a decision it changes or the conflict check changes after the prompt was shown, or someone else's approval decides the draft first, nothing is written and the assistant asks again. An app that cannot show a prompt is refused, with the draft's link to approve in the web app. An approval that decides the draft runs the same follow-up as in the web app: owners of dependent decisions are asked to review them, open inbox items close and the Areas' channels are told. The decision's history records the assistant's app and that its prompt was accepted.
With the Decide permission, an assistant can also change a decision when you ask it to. Each tool makes the change the web app makes, with your own rights, after you accept a prompt that names the decision, the change and your note or reason, and says how many dependent decisions are sent for review. On a decided decision the change waits for the approvals its Areas require unless yours completes them; the result's applied says which. A change that waits is a proposed change: the prompt and the result say what it still needs, and the decision stays Decided, with its text in force unchanged, until the change is approved, in the web app or through an assistant.
revise_decisionsaves a new revision of a decided decision, with a change note. The record must stay complete: every field its Type requires, an Area, and a review date in the future or a condition. Drafts are changed withupdate_draft.reaffirm_decisionrecords that a decided decision still holds, with a note saying why, and sets a new review date or condition. For a Type whose date is an expiry, such as an Exception, it needs a date, and the prompt says the expiry moves from and to which dates.supersede_decisionreplaces a decided decision with a successor, with a reason. A draft successor records your approval in the same call, and is Decided only when its Areas' approvals are met; the target stays decided until then.reverse_decisionreverses a decided decision, with a reason. The owner, a Maintainer or Area administrator on its Area, or a workspace administrator can reverse it.archive_decisionarchives a decision, with a reason, and is how a draft is discarded. A draft's creator or owner can archive it; only a workspace administrator archives a decided, superseded or reversed decision.change_ownerreassigns a draft or a decided decision at once, without waiting for approvals. Its open inbox items move to the new owner.
A change you could not make in the web app is refused before any prompt, with the reason: a Member who does not own a decision cannot reverse it, a reason or note is missing, a review date is in the past, or the revision would leave the record incomplete. An Area-bound connection changes only decisions tagged with its own Area alone, including the other decisions a change writes to. If the decision changes after the prompt was shown, nothing is written and the assistant asks again. An app that cannot show a prompt is refused, with the decision's link. Reversing, superseding and archiving send a review to the owner of each decided decision that depends on it once they apply, as in the web app.
approve_decision and request_changes also act on a proposed change to a decided decision. The prompt names the kind of change and who proposed it, each changed field with its proposed text, each Area and what it still needs, and whether your approval applies the change now. An approval that applies it runs the same follow-up as in the web app, and the result says what changed; otherwise it says what the change still needs, and nothing has changed yet. A request for changes stops the change from applying until you approve or withdraw the request in the web app. A call that cannot succeed is refused before any prompt with the reason, for example: no change is waiting, your approval would not count in any Area it needs, the change can no longer be applied as proposed, or an Area-bound connection would write outside its Area. If the proposed revision is edited, or the change is withdrawn or applied, after the prompt was shown, nothing is written and the assistant asks again. Withdrawing a proposed change, editing a proposed revision and dismissing a request for changes happen on the decision page.
A prompt before each change
Before an assistant changes anything in Precedent, Precedent asks in a prompt that your assistant's app shows: a dialog with Accept and Decline. This covers proposing or updating a draft, linking decisions, proposing a successor, staging or removing a change to a conflicting decision, attaching evidence, adding a repository, recording that a condition was met, approving a draft or a proposed change, asking for approval, requesting changes, and revising, reaffirming, superseding, reversing, archiving or reassigning a decision. The first lines of the prompt say the change: which decision, and what is created or changed. What else it affects follows, such as approvals of the draft that stop counting, whose people must approve again. Nothing is written until the prompt is accepted. Declining or dismissing it writes nothing, and the assistant is told so.
A prompt belongs to the person and the connection it was shown to, and lasts ten minutes. If the assistant then sends different inputs, or the decision changes after the prompt was shown, the change is refused and the assistant has to ask again. An accepted prompt makes its change once: sending the same answer again is refused. Each event it writes says prompt accepted in the assistant's app in the decision's event log. The audit export lists every prompt shown, accepted and declined.
Apps that speak the 2026-07-28 MCP protocol and can show these prompts ask before each change. Claude Code is one. Apps on an earlier protocol version cannot be shown a prompt by this server, so they make these changes with one call and no prompt, as before. Approving, asking for approval, requesting changes and the changes under changing a decision are the exception: they need a prompt, so those apps are refused with the decision's link. check_conflicts, suggest_conflict_fix and the read tools change no decision and never prompt. The skill still tells the assistant to show you the change in chat and get your agreement before it calls a tool.
Manage connected assistants
Settings → Assistants shows one card per assistant name and person in the workspace. Reconnecting can create another connection under that card. Expand Manage connections to see each connection’s context, permissions, authorisation time, and activity. Revoke an unused connection individually; this does not disconnect the others. Connections belonging to different people remain separate.
Troubleshooting
- Project setup tool missing: the deployment needs an update before
.precedent.jsonand project reminders can work. Installing the plugin does not deploy server changes. - No tools: check that the server is enabled and authorised in your assistant, then start a fresh conversation.
- Wrong workspace: check the Areas the assistant lists after the verification prompt, revoke the unwanted connection, and authorise the intended workspace.
- No matching decision: try a known title or ref. Empty results can be correct, including when permissions restrict what you can see.
- Request too large: MCP accepts at most 1 MiB of JSON per request and 10,000 array elements and object keys per tool call. Split large requests or attach a link to the evidence. A rejected request does not invoke the tool.
- Plugin controls missing: update your assistant or use manual remote MCP setup and the skill download. Organisation policy may restrict custom marketplaces.
- Duplicate tools or reminders: complete the migration steps above, then start a fresh conversation.
- Self-hosted or staging: use this deployment’s server URL (MCP) and skill. The public plugin points to precedent.biz. HTTPS is required except for localhost development, and cloud assistants must be able to reach the server.
- Rate limit reached: wait for the response’s Retry-After interval before retrying. Assistant requests and pull-request checks share a per-connection allowance. On self-hosted installations, all assistants currently share 20 new OAuth registration attempts per minute; this does not limit ordinary web activity. Registration metadata must fit within 64 KiB.
- Reminder does not run: check native MCP hook support and hook trust in your assistant. See automatic reminders.