Ihre Agenten kollidieren. Reichen Sie einen FlightPlan ein.
Bevor die Arbeit beginnt, erklärt jeder Ihrer Agenten, wohin er unterwegs ist, und sieht, was bereits in der Luft ist. Sie koordinieren sich um Konflikte herum und hinterlassen, was sich geändert hat und warum.
Hinweisgebend, niemals blockierend.
Ein Nebenprodukt der Agentenarbeit, kein weiterer zu wartender Prozess.
FlightPlan koordiniert Codierungsagenten, bevor ihre Arbeit kollidiert. Dieses Repository enthält die CLI, den MCP-Server und den Installer für den gehosteten Dienst unter getflightplan.com.
Vom Stammverzeichnis Ihres Repositorys aus:
uvx getflightplan installDas installiert FlightPlan für Claude Code. Für Codex hängen Sie --agent codex (oder --agent both) an. Der Befehl kann sicher erneut ausgeführt werden. Beim ersten Mal auf einem Rechner führen Sie als nächstes uvx getflightplan login aus – es verbindet Ihr Konto und schließt die MCP-Einrichtung ab.
Der gehostete Dienst befindet sich in der Beta-Phase; melden Sie sich mit Ihrem GitHub-Konto unter getflightplan.com an. Das Paket ist auf PyPI, daher reicht der obige Befehl aus. Um stattdessen einen Branch oder Commit festzulegen, installieren Sie aus der Quelle: uvx --from git+https://github.com/sledmonkey/getflightplan getflightplan install.
Versions- und Kompatibilitätsrichtlinie: docs/versioning.md.
Related MCP server: asynkor
Arbeit einreichen. Vor dem Bearbeiten erklärt ein Agent seine Aufgabe und die Dateien, die er voraussichtlich berühren wird.
Sehen, was in der Luft ist. FlightPlan gibt überlappende aktive Arbeiten zurück, einschließlich nicht festgeschriebener Änderungen, die Git nicht sehen kann, während des Codierens getroffener Entscheidungen sowie relevanter aktueller Ergebnisse.
Koordinieren. Überlappungen sind hinweisgebend: die Arbeit eingrenzen, sequenzieren oder mit Kontext fortfahren.
Nachbesprechung. Der Agent zeichnet auf, was sich geändert hat, was ihn überrascht hat und was er versucht hat, damit die nächste Sitzung nicht kalt startet.
.flightplan.toml — legt den Repository-Namen fest, unter dem jeder Agent postet, sowie die Registry-URL. Absichtlich committet; keine Geheimnisse.
Ein verwalteter Agent-Ausschnitt in CLAUDE.md und/oder AGENTS.md.
/registry-digest — ein bedarfsgesteuerter Befehl "Was ist kürzlich passiert".
Ein Stop-Hook am Sitzungsende (.claude/hooks/flightplan_stop_hook.py plus seine Einstellungsverkabelung), der den Agenten daran erinnert, offene Intents abzuschließen.
Es überprüft auch die MCP-Registrierung und die Erreichbarkeit des Dienstes und repariert die Registrierung, wenn der Rechner über eine Anmeldeinformation verfügt – keine Aufforderungen. Die Überprüfung ist hinweisgebend und führt nie zu einem Fehlschlag des Laufs.
Um alles zu entfernen, was der Installer geschrieben hat, führen Sie getflightplan uninstall vom Repository-Stammverzeichnis aus (--dry-run zur Vorschau, --purge-key um auch den gespeicherten API-Schlüssel zu löschen).
getflightplan login erhält eine Anmeldeinformation ohne kopierten API-Schlüssel. Es öffnet Ihren Browser, Sie genehmigen dort, und die Anmeldeinformation wird in ~/.config/flightplan/env mit Modus 600 gespeichert. Die Anmeldeinformation wird nie ausgegeben. Nachdem die Anmeldeinformation gespeichert ist, registriert der Login auch den MCP-Server für die Agent-Binärdateien auf Ihrem Rechner – den Schritt, den die Installation überspringen muss, solange der Rechner keine Anmeldeinformation hat.
Auf einem Rechner ohne Browser führen Sie getflightplan login --headless aus. Der Befehl zeigt einen kurzen Code und eine Adresse an. Öffnen Sie diese Adresse auf einem anderen Gerät und geben Sie den Code ein.
getflightplan logout entfernt die gespeicherte Anmeldeinformation von diesem Rechner. Um sie im Dienst zu widerrufen, verwenden Sie die Seite /devices.
Nach einem Login fragt der Client die Registry, welches Repository dieser Checkout ist. Er sendet die Adresse Ihres origin-Remotes und bis zu 1000 Commit-IDs, die beweisen, dass Sie einen Klon haben. Wenn Ihr Konto Zugriff hat, werden die ID und der Name in .flightplan.toml eingetragen. Wenn die Registry das Repository nicht kennt, bietet der Client an, es in Ihrem Browser zu registrieren. Wenn Ihr Konto keinen Zugriff hat, bietet der Client an, es anzufordern.
getflightplan login --no-register überspringt die Überprüfung. getflightplan register führt sie später eigenständig aus. Eine fehlgeschlagene Überprüfung führt nie zu einem fehlgeschlagenen Login.
Ein mit uncommitted: true abgeschlossener Intent besagt, dass die Arbeit im Arbeitsbaum von jemandem und sonst nirgendwo ist. Die Registry kann Ihren Baum nicht sehen, also warnt sie weiterhin jeden, der diese Pfade berührt, bis ihr mitgeteilt wird, dass die Arbeit gelandet ist.
Agenten tun dies mit dem Tool mark_intent_landed. Sie können es von Hand tun:
getflightplan landed <intent-id> --commit <sha> --commit <sha>Die Commits sind optional; der Zeitstempel ist die Korrektur. Geben Sie die SHAs nur weiter, wenn Sie sie kennen – der Client errät nie, welche Commits zu einem Intent gehören. Das Landen kann sicher wiederholt werden und überschreibt niemals den abgeschlossenen Datensatz.
FLIGHTPLAN_URL — https://api.getflightplan.com
FLIGHTPLAN_API_KEY — Ihr Schlüssel (die Umgebung des MCP-Servers; der Stop-Hook liest auch ~/.config/flightplan/env).
.flightplan.toml — der pro-Repository-Pin: ein repo-Name und eine url, oder eine target_id mit einem lesbaren name, sobald das Repository eine ID festgelegt hat.
Der Installer fügt den folgenden verwalteten Vertrag mit Ihrem festgelegten Repository-Namen hinzu.
Dieses Repository nimmt an der Team-Intent-Registry teil (MCP-Server: flightplan).
Bevor Sie mit nicht-trivialer Arbeit beginnen, rufen Sie post_intent auf. Der Test: Wird die Arbeit das Verhalten, die Voreinstellungen oder Verträge ändern, auf die ein anderer Agent stoßen würde – oder, bei reiner Untersuchung, würden die Erkenntnisse dem nächsten Agenten eine Stunde sparen? Ja zu einem von beiden → posten; Q&A und Korrekturen auf Tippfehlerebene, nein. Senden Sie eine ein Absatz umfassende Zusammenfassung (was + warum), kind (build oder explore/spike für Wegwerfuntersuchungen) und touches-Globs für die Bereiche, die Sie voraussichtlich ändern werden. Behalten Sie die zurückgegebene ID für später. Verwenden Sie für repo den Basisnamen des Git-Origin-Remotes (oder den Namen des Repository-Stammverzeichnisses, wenn es kein Remote gibt) – jeder Agent in diesem Repository muss denselben Namen verwenden, sonst übersehen sich Kollisionsprüfungen stillschweigend. Die Antwort kann context enthalten: kürzlich abgeschlossene Arbeiten, die für Ihre Aufgabe relevant sind – lesen Sie diese Ergebnisse vor dem Start; die Überraschungen und Sackgassen darin sind tragend.
Wenn die Antwort Überlappungen auf der Stufe warn enthält, überprüfen Sie, worum es sich bei der Überlappung handelt, bevor Sie pausieren. Zwei Fälle benötigen keine Bestätigung – erwähnen Sie die Überlappung und machen Sie weiter: Der überlappende Intent ist genau die Arbeit, zu der Sie aufgefordert wurden (sie zu überprüfen, zu verifizieren, nachzuverfolgen), oder Ihre Aufgabe ist schreibgeschützt. Andernfalls teilen Sie Ihrem Benutzer mit, wer was tut und welche Globs kollidieren, und fragen Sie, wie Sie fortfahren sollen, bevor Sie weitermachen. fyi/nudge-Stufen: kurz erwähnen und weitermachen.
Wenn die Arbeit ihre Form ändert oder länger dauert, rufen Sie update_intent auf: Überarbeiten Sie die Zusammenfassung/Globs, wenn der Umfang wächst (Kollisionsprüfungen laufen gegen sie – veraltete Globs übersehen echte Kollisionen), oder rufen Sie es nur mit der ID auf, um die TTL für Arbeiten zu verlängern, die mehr als einen Tag dauern. Die Antwort enthält frische overlaps – dieselbe Kollisionsprüfung wie beim Posten, glob-basiert – und ein warn dort erhält dieselbe Behandlung wie ein warn zum Zeitpunkt des Postens.
Wenn die Arbeit abgeschlossen oder aufgegeben wird – einschließlich wenn die Sitzung zu Ende geht – rufen Sie complete_intent mit einem ein Absatz umfassenden Ergebnis auf: was sich tatsächlich geändert hat, alles Überraschende, ausprobierte und verworfenen Ansätze, alles absichtlich Belassene. Wenn eine warn-Überlappung den Verlauf der Arbeit geändert hat (koordiniert, Umfang eingeschränkt, trotzdem fortgefahren), geben Sie an, welche. Fügen Sie die Git-Fakten hinzu, die Sie bereits kennen: tatsächlich geänderte files (git diff --name-only), erstellte commits und uncommitted: true, wenn ein Teil der Arbeit noch nicht committet ist – dieses Flag ist es, das die Kollisionsprüfungen anderer Agenten laut statt leise warnen lässt. Das Abschließen eines Intents beendet den Abschnitt, nicht die Sitzung: Folgearbeit nach einem Abschluss, die Verhalten, Voreinstellungen oder Verträge ändert, erhält einen neuen Post – "gleiche Sitzung" befreit nicht davon.
Wenn Sie erfahren, dass als nicht committet deklarierte Arbeit gelandet ist, rufen Sie mark_intent_landed mit der ID dieses Intents auf (und den Commit-SHAs, wenn Sie sie kennen): Bis jemand dies sagt, warnt die Registry weiterhin jeden, der diese Pfade berührt.
Überprüfen Sie erneut auf Kollisionen, wann immer Ihr Bild von laufenden Arbeiten veraltet sein könnte – das Posten prüft einmal, und es wird über eine lange Sitzung hinweg veraltet. Momente für erneute Überprüfung: Eine Datei hat sich zwischen Ihrem Lesen und Ihrem Bearbeiten geändert, oder eine Bearbeitung schlägt auf Text fehl, den Sie gerade gelesen haben – jemandes Arbeit ist unter Ihnen gelandet; vor dem Bearbeiten eines gemeinsam genutzten Dokuments oder Artefakts, das Sie nicht in dieser Sitzung erstellt haben; bei Wiederaufnahme nach einer Übergabe von einem anderen Agenten; und vor dem Berühren von Dateien, die in einem früheren warn genannt wurden. Die günstigste erneute Überprüfung ist update_intent nur mit Ihrer Intent-ID (verlängert die TTL, gibt frische overlaps zurück); verwenden Sie list_intents (übergeben Sie overlaps-Globs, plus summary für eine semantische Überprüfung, oder q/since für den Verlauf), wenn Sie keinen offenen Intent haben oder neue Arbeit abgrenzen.
Wenn eine Entscheidung im Gespräch getroffen wird (ein Ansatz gewählt, eine Alternative verworfen, eine Richtung festgelegt), zeichnen Sie sie in dem Moment auf, in dem sie sich festigt: post_intent mit kind: "decision", die Frage als Zusammenfassung und die Auflösung in outcome – was entschieden wurde, was verworfen wurde und warum. Ein Aufruf; keine Berührungen, keine spätere Vervollständigung. Entscheidungen kollidieren nie und werden zu durchsuchbarem Teamgedächtnis. Entscheidungen sind auch der Korrekturmechanismus: abgeschlossene Ergebnisse sind unveränderlich, wenn sich also eines später als falsch erweist, posten Sie eine Entscheidung, die zitiert, was tatsächlich Bestand hatte.
Die Registry ist hinweisgebend und darf die Arbeit niemals blockieren: Wenn ihre Tools fehlen oder einen Fehler melden, fahren Sie mit der Arbeit fort und teilen Sie Ihrem Benutzer einmal mit, dass er uvx getflightplan install ausführen kann (siehe getflightplan.com), um der Registry dieses Repositorys beizutreten.
Was Ihren Rechner verlässt, ist der Koordinationsdatensatz: Intent-Zusammenfassungen und Ergebnisabsätze, Glob-Muster, geänderte Dateipfade, Branchnamen und Commit-IDs – nur an den FlightPlan-Dienst gesendet. Quellcodeinhalte werden nie hochgeladen. Alles, was die Registry weiß, erfährt sie als Nebenprodukt der Arbeit Ihrer Agenten.
Die Details – was nie verlässt und wo was gespeichert wird – finden Sie in docs/data-flow.md. Meldung von Sicherheitslücken: SECURITY.md.
Apache-2.0
Close out an intent when work finishes or is abandoned. The outcome summary is required for done and is the most valuable artifact this system produces: write one paragraph covering what actually changed, anything surprising, approaches tried and rejected, and anything deliberately left in place. Gather git facts as exhaust — you already have them at completion time: files = repo-relative paths actually changed (git diff --name-only over the work, committed or not); commits = SHAs created for this work; uncommitted = true if ANY of the work is not yet committed (untracked/unstaged/staged-only) — this flag is what lets other agents' collision checks warn loudly instead of quietly. Omit anything unknown. Any overlaps that come back carry excerpts, and overlaps_omitted counts the ones the server cut per level — use get_intent(id) for a full record.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id returned by post_intent. | |
| files | No | Repo-relative paths actually changed (from `git diff --name-only` over the work). Omit if unknown. | |
| status | Yes | done = landed; abandoned = stopped without landing. | |
| commits | No | Commit SHAs produced for this work. Omit if unknown. | |
| outcome | Yes | One paragraph: what actually changed, surprises, dead ends, things deliberately left alone. | |
| uncommitted | No | True if ANY of the work is not yet committed (untracked/unstaged/staged-only). This flag escalates collision warnings for other agents. False = all committed. Omit if unknown. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers real behavioral context: the outcome is required for `done`, the `uncommitted` flag escalates collision warnings for other agents, and overlaps_omitted counts server-side cuts per level. It stops short of describing idempotency or what happens if the intent is already closed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the required-outcome instruction are front-loaded, and most sentences (collision warning escalation, overlaps_omitted) earn their place. The git-fact paragraph is somewhat verbose and duplicates schema text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the meaningful return signals (overlap excerpts and overlaps_omitted) and the required outcome artifact. It omits error/edge behavior for an already-completed intent, so it is strong but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters, and the description's git-fact explanations largely restate them. Baseline 3 applies because the description adds no syntax or format detail beyond what the structured fields provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Close out an intent') plus the triggering condition ('when work finishes or is abandoned'). It also names get_intent as the route to a full record, so an agent can place it among its siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear timing context (completion or abandonment) and points to get_intent for full records. It does not differentiate from close siblings like update_intent or mark_intent_landed, leaving a possible ambiguity about which tool ends the lifecycle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one intent's full record — the whole summary and outcome — by id or by a unique 8-char prefix. Overlap, context and list entries carry excerpts only, so call this when the excerpt is not enough: an overlap you have to describe to your user, or a context outcome you want to read in full before starting. Read-only; it records nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id, or a unique 8-char prefix of one (as shown in overlaps and the digest). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden, and it does state the key trait: 'Read-only; it records nothing.' However it is silent on other relevant behavior for a lookup tool, such as what happens when an 8-char prefix is not unique or how the full record is shaped.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and scope, then the routing rationale, then the safety trait. No filler, and each sentence adds information the structured fields do not provide.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no annotations and no output schema, the description covers what the tool does, when to reach for it, and that it is non-mutating. It stops short of covering prefix-ambiguity or lookup-failure behavior, which would fully close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole parameter's description already explains the id-or-unique-8-char-prefix semantics. The description repeats the same id/prefix detail without adding format or edge-case meaning (e.g., prefix ambiguity), so this sits at the baseline for well-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch one intent's full record') plus the scope of what is returned ('the whole summary and outcome'). It also differentiates itself from the excerpt-bearing surfaces ('Overlap, context and list entries carry excerpts only'), so an agent can separate it from list_intents without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete triggers for calling it ('when the excerpt is not enough: an overlap you have to describe to your user, or a context outcome you want to read in full before starting'). Alternatives are implied via the excerpt-only surfaces rather than named directly, and there is no explicit when-not rule, so it falls just short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query in-flight and recent work across the team. Three distinct uses — pick exactly one: (1) pre-planning semantic check — pass summary (and optionally overlaps globs) to get judge-assessed semantic overlap before you post_intent; this is the strong collision check; (2) fast glob collision check — pass overlaps alone (no summary, no q) for deterministic prefix matching; (3) context search — pass q and since (add match=any for recall if a precise query returns nothing) to search summaries and outcomes including completed work. q and overlaps are AND-combined: a descriptive q alongside overlaps filters out overlapping intents whose summaries don't contain your words — for a collision check, omit q. q matches per-word (all words must appear, any order). Each returned intent carries an alert_level when overlaps is given: warn = surface loudly to your user; fyi = quiet mention; nudge = possible duplicate spike, suggest comparing notes. Rows carry outcome_excerpt by default; pass detail="full" for whole outcomes.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Plain-text search over summaries and outcomes. | |
| kind | No | Filter results by kind. | |
| repo | No | Filter to one repository. Use the basename of the git origin remote (or the repo root directory name if there is no remote) — must match the name used in post_intent, or the filter silently returns nothing. | |
| limit | No | ||
| match | No | How q terms combine: all (default) = every word must match — precise; any = recall mode, use when a context search with several descriptive words comes back empty. | all |
| since | No | ISO-8601 timestamp or shorthand like '24h', '7d'. | |
| author | No | Filter to one person's intents, e.g. 'sarah' — for questions like 'what did Sarah's agent work on last week?'. | |
| branch | No | YOUR git branch. Overlaps on the same branch are flagged `same_branch` — your own line of work, likely already in your tree, but verify (it may be uncommitted in another session). | |
| detail | No | How much of each row comes back: compact (default) = an `outcome_excerpt` per row, enough to scan; full = whole rows with full outcomes — use it for a digest, or whenever you will actually read the outcomes. | compact |
| status | No | Comma-separated of: active, done, abandoned, expired. Omit for all (history included). | |
| my_kind | No | The kind of YOUR planned work; sets alert levels. | build |
| session | No | Filter to one agent session. Pass 'current' for this session's own intents — e.g. to find your still-open intent before wrapping up. Any other value passes through verbatim. | |
| summary | No | Your planned task, one paragraph. Provide it to get semantic (judge) collision assessment instead of glob-prefix matching — use for a pre-planning check before you're ready to post_intent. | |
| overlaps | No | Globs you expect to touch; filters to overlapping intents and computes alert levels. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the disclosure burden: it explains q and overlaps are AND-combined, that omitting q is required for a clean collision check, that alert_level carries warn/fyi/nudge meanings, that same-branch hits are flagged as your own line of work, and that rows default to outcome_excerpt with detail='full' returning whole outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the three-way branching before any detail, and nearly every sentence carries distinct information. It runs long with stacked clauses, but the density is earned rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter read tool with no output schema and no annotations, the description covers the return shape (alert_level values, outcome_excerpt vs full detail) and all decision-relevant modes, leaving no material gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 93%, but the description adds genuine semantics beyond it: how q terms combine word-by-word and across filters, when match=any is warranted, that session='current' targets this session's own intents, and how detail trades excerpt against whole outcomes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('query in-flight and recent work across the team') and situates itself against a sibling by naming post_intent as the downstream action. An agent can distinguish list_intents from get_intent/post_intent without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly enumerates three distinct, mutually exclusive uses ('pick exactly one') with the exact parameter combinations that select each, plus exclusions ('no summary, no q', 'for a collision check, omit q') and the alternative (post_intent after the pre-planning check). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that work an already-COMPLETED intent declared uncommitted is now in git. Call this the moment you learn it: you committed and pushed that work yourself, or you can see in the tree that the work another session left uncommitted has since landed. Until someone says so, the registry keeps warning every agent who touches those paths and keeps re-telling the same story about work that is no longer at risk — a tree it cannot see is the one thing it cannot check for itself. Pass the commit SHAs if you know them; landing without them is fine and complete, the timestamp is the correction. Idempotent, and it never rewrites the completion record — the outcome, the reported files and the original uncommitted declaration all stand.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id whose work has landed. | |
| commits | No | Commit SHAs that carried the work, if you know them. Omit if you don't — do not guess. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses that the tool is idempotent, never rewrites the completion record, and that providing commit SHAs is optional ('pass the commit SHAs if you know them; landing without them is fine and complete'). It also explains behavioral nuance ('the tree it cannot see is the one thing it cannot check for itself').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that front-loads the core action ('Record that work... is now in git'), then adds context about when and why to call it. Every sentence contributes meaningful information — no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description covers the tool's purpose, usage cues, behavioral traits, and parameter guidance comprehensively. The tool has low complexity (2 params, 1 required), and the description provides everything needed for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the purpose of the `commits` parameter in context ('if you know them. Omit if you don't — do not guess'), and emphasizes that the timestamp is the correction when commits are unknown. This added guidance justifies above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('Record', 'mark', 'landed') and clearly identifies the resource ('work an already-COMPLETED intent declared uncommitted is now in git'). It distinguishes this tool from siblings like complete_intent (which marks intent completion) and post_intent (which creates a new intent) by focusing on the post-completion git state update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to call this ('the moment you learn it') and provides clear examples ('you committed and pushed that work yourself, or you can see in the tree that the work another session left uncommitted has since landed'). It explains the consequences of not calling it ('registry keeps warning', 'keeps re-telling the same story'), which strongly implies when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register what you are about to work on so other developers' agents can avoid collisions. Call this before starting any non-trivial coding task (anything touching more than a trivial fix). Infer kind: build for work meant to land, explore/spike for throwaway investigation, decision for a resolved decision worth recording (post it the moment a debate settles: pass the resolution in outcome — what was decided, what was rejected, and why; no touches needed; it is stored complete, never collides, and needs no complete_intent). Infer touches from your plan as repo-relative glob patterns. Returns the intent id — keep it to post the outcome later. Also returns any overlapping in-flight intents — active work (alert warn/nudge/fyi) and recently-completed work that may not have landed in git yet (always fyi): overlaps are the COLLISION signal — if overlap level is warn, tell your user before proceeding; for fyi, check whether that work is already in your tree before redoing it. The response also includes context — recently-completed work relevant to THIS task: read those outcomes before you start, the surprises and dead ends in them are load-bearing (a rejected approach you might retry, a gotcha you will hit). Overlap entries carry summary_excerpt; context entries carry summary_excerpt and outcome_excerpt. overlaps_omitted counts what the server cut per alert level — a non-zero warn there means more warnings exist than are shown. Call get_intent(id) for any full record.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | build = meant to land; explore/spike = throwaway investigation; decision = a resolved decision recorded for the feed (requires `outcome`). | build |
| repo | Yes | Repository name, e.g. 'raveneye'. Use the basename of the git origin remote (or the repo root directory name if there is no remote) — every agent on the same repo must derive the same string or collision checks silently miss each other. | |
| title | No | Short headline for the work, ≤80 chars, like a commit subject line (e.g. 'FTS5 search + recall mode'). Cheap to write and the feed reads far better with one — provide it. | |
| branch | No | Git branch, if known. | |
| outcome | No | kind=decision only: the resolution — what was decided, what was rejected, and why. Other kinds write outcomes at completion instead. | |
| summary | Yes | One paragraph: what you're doing and why. | |
| touches | Yes | Repo-relative glob patterns you expect to touch, e.g. ['central/services/scorecard*']. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden and largely delivers: it explains that decision-type intents are stored complete, never collide, and need no complete_intent; that it returns the intent id to keep for the later outcome post; and describes the overlap alert levels warn/nudge/fyi and what each obliges the agent to do. This is exactly the behavioral context annotations would otherwise supply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core guidance is front-loaded well, but the second half becomes a dense run-on packed with field names and conditional alert logic. It is information-rich but strains readability; a few of the parentheticals could be trimmed without loss.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with a rich implied return shape and no output schema, this covers the important ground: kind inference, touch inference, the intent id, overlap warnings, context of prior outcomes, and the overlaps_omitted count. It stops short of describing the full response envelope or pagination/limits, but it is close to complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes beyond by giving decision-specific semantics (outcome contents, no touches needed) and explains how touches should be inferred (repo-relative globs from the plan), adding operational meaning to the parameters rather than restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Register') and resource ('what you are about to work on') with a concrete goal ('so other developers' agents can avoid collisions'). Clearly distinguishes this write/registration tool from the read-oriented siblings list_intents and get_intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to call it ('before starting any non-trivial coding task (anything touching more than a trivial fix)') and gives kind-specific guidance, including that decision should be posted 'the moment a debate settles' with no touches needed. Routes the agent to get_intent for full records, effectively naming the alternative for consuming results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an in-progress intent. Call when the work changes shape (revise summary or touches — collision checks run against these fields, so stale globs silently miss real collisions) or when work runs long (a call with just the id renews the TTL heartbeat; active intents expire after ~48h without one). Calling with just the id ALSO returns fresh overlaps — the cheap mid-session collision re-check, since a post-time check goes stale over a long session. Treat a warn here exactly like a warn at post time: tell your user before proceeding. Overlaps carry excerpts, and overlaps_omitted counts any the server cut per level — use get_intent(id) for a full record. Never use this to finish work — call complete_intent for that.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The intent id returned by post_intent. | |
| title | No | Revised short headline, ≤80 chars. | |
| branch | No | Git branch, if it has changed. | |
| summary | No | Revised one-paragraph summary: what + why. | |
| touches | No | Revised repo-relative glob patterns. Replaces the existing list — include all globs, not just new ones. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly: it discloses the ~48h TTL expiry, that an id-only call renews the heartbeat, that stale globs cause silent collision misses, and that warn must be surfaced to the user. It also explains overlaps carry excerpts and that overlaps_omitted counts truncations — behavioral context well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then conditions, then returns, then the exclusion. Dense but every clause carries distinct information; the parenthetical asides make it read long, though little is truly expendable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly compensates by explaining return values (overlaps, overlaps_omitted, excerpts) and directing to get_intent for a full record. Nothing needed to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: an id-only call still renews TTL and returns fresh overlaps, and touches replacement semantics drive collision checks. It goes past restating the per-field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Update an in-progress intent') and scopes it to in-progress work, immediately distinguishing it from complete_intent and get_intent by name. An agent can tell it apart from its siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit triggers ('when the work changes shape', 'when work runs long'), the id-only heartbeat case, and a hard exclusion ('Never use this to finish work — call complete_intent for that'). Both when-to-use and when-not-to-use are spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.15.0get_intentlist_intents1 field changedInput schema / properties / detailAdded value: +{
+ "default": "compact",
+ "description": "How much of each row comes back: compact (default) = an `outcome_excerpt` per row, enough to scan; full = whole rows with full outcomes — use it for a digest, or whenever you will actually read the outcomes.",
+ "enum": [
+ "compact",
+ "full"
+ ],
+ "title": "Detail",
+ "type": "string"
+}v0.1.0complete_intentlist_intentsmark_intent_landedpost_intentupdate_intentScored across 6 tools
The lifecycle roles (post, list, get, update, complete, mark_landed) are clearly distinct, but collision-check functionality is spread across three tools: post_intent returns overlaps, list_intents offers glob/semantic checks, and update_intent re-runs them mid-session. An agent could reasonably hesitate over which to use for a given check, though the descriptions do clarify the intended contexts.
All names are snake_case with a leading verb (post_intent, list_intents, get_intent, update_intent, complete_intent, mark_intent_landed). The pattern is predictable and the slightly longer mark_intent_landed still fits the verb_noun convention.
Six tools is well-scoped for a lightweight intent-coordination registry: each tool maps to a distinct lifecycle step (create, query, read, revise, close, correct-landing-status). Nothing feels padded or missing at the count level.
The surface covers the full intent lifecycle: create, list/search, get, update/heartbeat, complete (including abandonment), and post-hoc landing correction. The main minor gap is the absence of an explicit delete/retract for erroneous intents, and querying is limited to summary/glob/time rather than author or kind filters.
Coding agents from Claude Code, Cursor and Codex claim jobs and lock files on one shared board.
Coordination for AI coding agents: declare plans, catch design conflicts early, share team memory.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Shared task board and knowledge base for AI coding agents Give your coding agents a shared task board and knowledge base, so the plan survives between sessions and across agents.
