あなたのエージェントが衝突する。FlightPlanを提出せよ。
作業を始める前に、各エージェントは向かう先を宣言し、すでに進行中のものを確認します。競合を調整し、その後、何が変わったのか、なぜ変わったのかを残します。
助言であり、ロックではありません。
エージェントの作業の副産物であり、維持すべき別のプロセスではありません。
FlightPlanは、コーディングエージェントの作業が衝突する前に調整します。このリポジトリには、getflightplan.com のホステッドサービスのCLI、MCPサーバー、インストーラーが含まれています。
リポジトリのルートから:
uvx getflightplan installこれでClaude Code用にFlightPlanがインストールされます。Codexの場合は、--agent codex（または --agent both）を追加してください。このコマンドは再実行しても安全です。マシンで初めての場合は、次に uvx getflightplan login を実行してください。アカウントを接続し、MCPのセットアップを完了します。
ホステッドサービスはベータ版です。getflightplan.com でGitHubアカウントを使ってサインインしてください。パッケージはPyPIにあるため、上記のコマンドだけで十分です。代わりにブランチやコミットを固定する場合は、ソースからインストールしてください:
uvx --from git+https://github.com/sledmonkey/getflightplan getflightplan install
バージョンと互換性ポリシー: docs/versioning.md
Related MCP server: asynkor
作業を登録する。 編集前に、エージェントはタスクと、触れる予定のファイルを宣言します。
進行中の作業を確認する。 FlightPlanは、重複するアクティブな作業を返します。これには、Gitが認識できない未コミットの変更、コーディング中に行われた決定、関連する最近の成果が含まれます。
調整する。 重複は助言です。作業を絞り込むか、順序付けるか、コンテキストを持って進めてください。
報告する。 エージェントは、何が変わったか、何に驚いたか、何を試したかを記録します。これにより、次のセッションが冷えた状態から始まることがなくなります。
.flightplan.toml — すべてのエージェントが投稿するリポジトリ名と、レジストリURLを固定します。意図的にコミットされます。秘密情報はありません。
CLAUDE.md および/または AGENTS.md 内の管理されたエージェントスニペット。
/registry-digest — オンデマンドの「最近何が起こったか」コマンド。
セッション終了時のストップフック（.claude/hooks/flightplan_stop_hook.py とその設定の配線）で、エージェントに未完了のインテントをクローズするよう促します。
また、MCPの登録とサービスの到達可能性をチェックし、マシンに資格情報がある場合は登録を修復します。プロンプトは表示されません。検証は助言であり、実行を失敗させることはありません。
インストーラーが書き込んだものをすべて削除するには、リポジトリルートで getflightplan uninstall を実行してください（--dry-run でプレビュー、--purge-key で保存されたAPIキーも削除）。
getflightplan login は、APIキーをコピーすることなく資格情報を取得します。ブラウザが開き、そこで承認すると、資格情報は ~/.config/flightplan/env にモード600で保存されます。資格情報は決して表示されません。資格情報が保存された後、ログインはマシン上のエージェントバイナリ用にMCPサーバーも登録します。これは、インストール時にマシンに資格情報がないためにスキップしなければならなかった手順です。
ブラウザがないマシンでは、getflightplan login --headless を実行してください。コマンドは短いコードとアドレスを表示します。別のデバイスでそのアドレスを開き、コードを入力してください。
getflightplan logout は、このマシンに保存された資格情報を削除します。サービス上で取り消すには、/devices ページを使用してください。
ログイン後、クライアントはレジストリに、このチェックアウトがどのリポジトリかを尋ねます。origin リモートのアドレスと、最大1000のコミットIDを送信します。これにより、クローンを持っていることが証明されます。アカウントにアクセス権がある場合、IDと名前が .flightplan.toml に書き込まれます。レジストリがリポジトリを知らない場合、クライアントはブラウザで登録するよう提案します。アカウントにアクセス権がない場合、クライアントはリクエストするよう提案します。
getflightplan login --no-register はチェックをスキップします。getflightplan register は後で単独で実行します。チェックに失敗してもログインが失敗することはありません。
uncommitted: true で完了したインテントは、作業が誰かのワーキングツリーにあり、それ以外の場所にはないことを示します。レジストリはあなたのツリーを見ることができないため、作業が完了したと通知されるまで、それらのパスに触れるすべての人に警告を出し続けます。
エージェントは mark_intent_landed ツールでこれを行います。手動で行うこともできます:
getflightplan landed <intent-id> --commit <sha> --commit <sha>コミットはオプションです。タイムスタンプが修正です。SHAを知っている場合のみ渡してください。クライアントはどのコミットがどのインテントに属するかを推測しません。完了のマークは安全に繰り返し実行でき、完了したレコードを上書きすることはありません。
FLIGHTPLAN_URL — https://api.getflightplan.com
FLIGHTPLAN_API_KEY — あなたのキー（MCPサーバーの環境変数。ストップフックも ~/.config/flightplan/env を読み取ります）。
.flightplan.toml — リポジトリごとの固定: repo 名と url、またはリポジトリにIDが固定された後の読み取り可能な name を持つ target_id。
インストーラーは、リポジトリ名が固定された以下の管理された契約を追加します。
このリポジトリは、チームインテントレジストリ（MCPサーバー: flightplan）に参加しています。
重要な作業を始める前に、post_intent を呼び出してください。判断基準: その作業が、別のエージェントが遭遇する動作、デフォルト、または契約を変更するか、あるいは純粋な調査の場合、その発見が次のエージェントの1時間を節約できるか？ どちらかに該当する場合は投稿。Q&Aやタイポレベルの修正は不要です。1段落の要約（何を、なぜ）、kind（build、または使い捨て調査の場合は explore/spike）、および変更予定の領域を示す touches グロブを送信してください。返されたIDは後で使用するために保持してください。repo には、gitのoriginリモートのベース名（リモートがない場合はリポジトリルートディレクトリ名）を使用してください。このリポジトリのすべてのエージェントは同じ名前を使用しないと、衝突チェックが互いに見逃されます。レスポンスには context が含まれる場合があります。これは、タスクに関連する最近完了した作業です。開始する前にそれらの成果を読んでください。そこにある驚きや行き詰まりは重要な情報です。
レスポンスに warn レベルの重複が含まれている場合、一時停止する前に重複の内容を確認してください。確認不要で、重複に言及して続行してよい2つのケースがあります: 重複しているインテントが、あなたが行動を依頼されたまさにその作業である場合（レビュー、検証、フォローアップ）、またはあなたのタスクが読み取り専用である場合。それ以外の場合は、誰が何をしていて、どのグロブが衝突しているかをユーザーに伝え、続行方法を尋ねてから進めてください。fyi/nudge レベル: 簡単に言及して続行してください。
作業の範囲が変わったり、長引いたりした場合、update_intent を呼び出してください。スコープが拡大した場合は要約/タッチを修正（衝突チェックはこれらに対して実行されます。古いグロブは実際の衝突を見逃します）。または、IDのみを渡して、1日以上にわたる作業のTTLを更新してください。レスポンスには新しい overlaps が含まれます。これは投稿時と同じグロブベースの衝突チェックであり、warn がある場合は投稿時と同じ扱いを受けます。
作業が完了したか、放棄された場合（セッションが終了する場合を含む）、complete_intent を呼び出し、1段落の成果を記述してください。実際に何が変わったか、驚いたこと、試したが却下されたアプローチ、意図的に残したもの。warn の重複が作業の進め方に影響を与えた場合（調整、範囲の絞り込み、そのまま続行など）、その旨を記載してください。すでに把握しているgitの事実を添付してください: 実際に変更された files（git diff --name-only）、作成された commits、および作業の一部がまだコミットされていない場合は uncommitted: true。このフラグにより、他のエージェントの衝突チェックが静かにではなく、大声で警告するようになります。インテントの完了はスライスの終了であり、セッションの終了ではありません。完了後のフォローアップ作業で動作、デフォルト、契約が変更される場合は、新たに投稿してください。「同じセッション」だからといって免除されるわけではありません。
宣言された未コミットの作業が完了したことを知った場合、そのインテントのID（およびコミットSHAがわかればそれも）を指定して mark_intent_landed を呼び出してください。誰かがそう言うまで、レジストリはそれらのパスに触れるすべての人に警告を出し続けます。
進行中の作業の状況が古くなっている可能性がある場合は、いつでも衝突を再確認してください。 投稿時には一度だけチェックされ、長時間のセッションでは古くなります。再確認のタイミング: 読み取りと編集の間でファイルが変更された場合、または編集が読み取ったばかりのテキストで失敗した場合（誰かの作業があなたの下で完了した）、このセッションで作成していない共有ドキュメントやアーティファクトを編集する前、別のエージェントから引き継いだ後に再開するとき、以前の warn で名前が挙がったファイルに触れる前。最も安価な再確認は、インテントIDのみを指定した update_intent です（TTLを更新し、新しい overlaps を返します）。オープンなインテントがない場合や新しい作業の範囲を決めている場合は、list_intents を使用してください（overlaps グロブを渡し、意味チェックには summary、履歴には q/since を追加）。
会話の中で決定が確定した場合（アプローチが選ばれた、代替案が却下された、方向性が決まった）、それが決まった瞬間に記録してください。post_intent を kind: "decision" で呼び出し、質問を要約として、決定内容を outcome に記述します。何が決定され、何が却下され、その理由。1回の呼び出し。タッチも後での完了も不要です。決定は決して衝突せず、検索可能なチームの記憶になります。決定は修正メカニズムでもあります。完了した成果は不変であるため、後で間違っていることが判明した場合は、実際に成立したことを引用した決定を投稿してください。
レジストリは助言であり、作業をブロックしてはなりません。ツールがないかエラーが発生した場合は、作業を続行し、ユーザーに一度、uvx getflightplan install を実行できること（getflightplan.com を参照）を伝えて、このリポジトリのレジストリに参加してください。
あなたのマシンから送信されるのは、調整記録です。インテントの要約と成果の段落、グロブパターン、変更されたファイルのパス、ブランチ名、コミットIDです。これらはFlightPlanサービスにのみ送信されます。ソースコードの内容は決してアップロードされません。レジストリが知るすべては、エージェントの作業の副産物として学習されます。
詳細（何が決して送信されないか、どこに保存されるか）は docs/data-flow.md にあります。脆弱性の報告: 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.
