northstar

Northstar

Northstar は、リポジトリの知識を最新に保ち、計画を明確にすることで、あらゆるエージェントが会話から意図を再構築せずに作業を引き継げるようにします。

リポジトリには 知識とコード を保持します。オーケストレーター（現在は Paseo Queue プラグイン、将来は Nucleus）には、プロセスと計画 を保持します。つまり、計画（レーン、そのドキュメントと順序）、リード（ブリーフを含む）、ペーパーカット、タスク、ステータス、レビュー、完了処理、成果です。これらをリポジトリに書き込んではいけません。

リポジトリの構成

対象	保持するもの
AGENTS.md	全体像：このリポジトリの概要、ドキュメントの案内図、ガードレール、検証コマンド
docs/README.md	現在の事実をまとめたページと、トピック別のリンク
docs/knowledge/	現在の事実。各事実の管理元は1つ：ビジョン、アーキテクチャ、契約、ドメイン
docs/knowledge/retired.toml	すでに存在しない概念と、それに置き換わったもの
docs/knowledge/questions.md	未解決の質問と、それぞれの回答が現在記載されている場所
docs/knowledge/contracts/release.md	このプロジェクトのリリース手順を、順を追って説明します。各プロジェクトに1つ必要です

docs/plan.md、docs/triage/、タスクカード、ロードマップ、生成物、引き継ぎファイル、ライフサイクル記録、デリバリーログ、PAPERCUTS.md はありません。履歴は Git の履歴とオーケストレーターの成果記録に残ります。

全体像を把握する

AGENTS.md、次に docs/README.md を読み、その後、作業に関係するナレッジファイルだけを読みます。次に何をするかを確認するには、プロジェクトの Queue 計画（plan.get）と、そこに記載されているレーンのドキュメントを読みます。概念を前提に計画を立てる前に、retired.toml を確認します。オペレーターに何かを尋ねる前に、questions.md と該当するナレッジファイルを確認します。すでに回答済みの質問をもう一度尋ねるより、調べるほうが効率的です。

作業の進め方

1. 計画。 プロジェクトが目指す成果ごとに、作業用ドキュメントを持つ Queue レーンを作成します。プロジェクトの計画でレーンの順序を定めます。未計画のアイデアや先送り事項はリードに記録します。計画を参照してください。
2. ブリーフ。 各タスクは Queue リード内のブリーフとして開始します。ブリーフには、成果、コンテキストへのリンク、制約、受け入れ条件、停止するタイミングを記載します。ブリーフを参照してください。
3. ディスパッチ。 オペレーターの承認を得たら、リードを承認してタスクに昇格させます。Queue がワーカー、レビュー、マージ、完了処理を実行し、成果を記録します。
4. レビュー。 独立したレビュアーが、ブリーフに照らして対象のヘッドを確認します。レビューを参照してください。
5. ナレッジを最新に保つ。 作業によって事実が変わる場合は、同じ PR で該当するナレッジファイルを更新します。ナレッジを参照してください。

重要なルール

• 事実ごとに管理元を1つにします。 管理元へのリンクを使い、内容を繰り返して記載しないでください。複製すると、将来矛盾が生じます。
• 引き継ぐ前に決定事項を反映します。 会話でオペレーターから得た回答は、スレッドを終了または引き継ぐ前に、該当するナレッジファイルに記録するか、questions.md の質問を解決済みにします。
• 廃止する対象を明記します。 概念を廃止する場合は、対象となる用語、パス、設定キーを列挙したエントリを retired.toml に追加し、同じ変更で現行の参照を削除または修正します。
• ステータスを複製しません。 「完了」「マージ済み」「レビュー中」などをリポジトリに書き込んではいけません。ステータスは Queue が管理します。
• 次の読者のために書きます。 後で必要になる情報だけを残します。簡潔で平易な表現にし、判断の理由が分かるようにします。
• 問題を正直に明らかにします。 変更によって呼び出し元や契約に影響が出る場合は、そのことを明記し、関連箇所も同時に更新します。判断を覆い隠すシムは作りません。
• タスクごとに対象を絞ったチェック、マイルストーンで完全な QA（Tom、2026-09-30）。タスクでは、その変更を検証するためのチェックだけを実行します。全スイートは、リリース時点または大きな作業のまとまりが完了した後に、プランナーが main で実行します。タスクごとの完全な QA はマシンに過剰な負荷をかけていました。
• マシンの負荷を理由に作業を保留しません。 負荷が高いときだけ失敗するテストは不具合です。マシンが空くのを待つのではなく、記録して修正します（Tom、2026-09-28）。

シェルコマンド

ここでエージェントが使うシェルは、通常 macOS の zsh です。次のミスが繰り返し発生しています。

• リテラルパターンはシングルクォートで囲みます。ダブルクォート内のバッククォートと $(...) はコマンドとして実行されます。rg 'use `foo`' docs のようにし、rg "use `foo`" docs とはしないでください。
• パスのリストは配列に保持します。zsh は文字列変数を単語に分割しないため、スペース区切りのリストはひとつの引数として渡されます。 files=(a.md b.md); for f in "${files[@]}"; do …; done
• status、path、home など、zsh の特殊な名前を変数に使わないでください。status への代入は失敗し、path をループ変数にするとコマンドの検索に支障が出ます。exit_code や rel_path のような名前を使ってください。
• コロンの前では変数を波括弧で囲みます。git show "${rev}:tools/x.md" のようにします。zsh は $rev:t… を修飾子として読み取り、"$rev:tools/x.md" は HEADools/x.md になります。
• macOS には BSD 版の sed と grep があります。\b は使えず、sed -i には '' が必要で、GNU のアドレス形式は使えません。テキストの抽出には rg、awk、または短いスクリプトを使ってください。
• パターンを指定してプロセスを終了しないでください。pkill -f、killall、pgrep … | xargs kill は使わないでください。他のタスクのワークツリーもマシンを共有しているため、pkill -f effigy はそのマシン上のすべての Effigy 実行を終了させます。終了させるのは、自分が起動したプロセスだけにしてください。$! の PID、または自分で作成したプロセスグループを使います。
• 検証は生の cargo、bun、vitest ではなく、リポジトリの Effigy セレクターを通じて実行します。絞り込んだセレクターを使ってもかまいません。Effigy はマシン全体で負荷の大きい実行を調整しますが、生のツールはその調整を回避するため、すべてのワークツリーで競合が悪化します。
• バックグラウンドジョブの終了コードを記録します。たとえば、cmd > run.log 2>&1; echo "exit=$?" >> run.log のようにします。終了したプロセスは正常に完了している場合もあるため、「見つからない」ことを失敗と判断しないでください。

小さな不便と手掛かり

後で修正する価値のある、小さく繰り返し発生する不便は「小さな不便」として Queue に登録します。リポジトリには登録しません。Queue の呼び出しは、プラグインのルート（~/Dev/projects/paseo-northstar-queue）から行い、ペイロードは標準入力で渡します。共有ペイロードファイルは使わないでください。別のスレッドが、2 回の呼び出しの間に上書きする可能性があります。

node bin/queue-cli.mjs papercut.add - <<'JSON'
{"repository": {"origin": "owner/name", "path": "/abs/checkout"},
 "title": "...", "happened": "...", "impact": "..."}
JSON

小さな不便には repository、title、happened、impact が必要です。area と fix は省略可能です。（papercut.list の repository には、オリジン文字列 "owner/name" を指定します。）記録してからタスクを続けてください。プランナーは papercut.promote-task（概要を参照）で小さな不便をタスクに昇格させるか、papercut.set-lanes でレーンに割り当てるか、完了または非推奨としてクローズします。

不便よりも大きく、まだ計画されていない観察、アイデア、質問は手掛かりです。lead.add（計画を参照）を使ってください。どちらもファイルには記録しないでください。

オペレーターに確認する場合

• 計画を見ても次に何をすべきか決まらない場合。
• 選択によって互換性が損なわれる、元に戻せない、セキュリティに関わる、または製品の方向性が変わる場合。
• 計画が変わるような形で検証に失敗した場合。

それ以外は実行してください。すでに決まっていることについて、再び許可を求めるのはコストになります。

ターンの終了時にオペレーターの判断が必要な場合は、チャットで尋ねるだけでなく、Queue の決定事項としても記録してください。ボードに表示され、回答が戻ってくるようにするためです。

node bin/queue-cli.mjs decision.add - <<'JSON'
{"question": "...", "askedBy": "<your agent ID>", "options": ["A", "B"],
 "recommendation": "A, because ...", "context": "...",
 "project": {"origin": "owner/name", "path": "/abs/checkout"}}
JSON

関連するタスク、手掛かり、小さな不便をリンクします（tasks、leads、papercuts：ID の配列）。質問が別の事情によって不要になった場合は、decision.withdraw（id、version、reason、withdrawnBy）で撤回します。内容が変わった場合は、2 件目を追加するのではなく、decision.supersede で差し替えます。チャットで判断が示された場合は、オペレーターの発言を一字一句引用し、note にオペレーターの名前を記載して、decision.answer で記録します。いずれの場合も、判断内容はその判断を管理するナレッジファイルに反映するか、questions.md の該当項目をクローズします。決定事項は、現在確認中の依頼であって、記録そのものではありません。

役割

• Planner（Chatterbox スレッド）：プロジェクトの Queue 計画、レーン文書、リード、ナレッジの整備、ブリーフ、ディスパッチ承認リクエストを担当します。自身が行う小規模なリポジトリ変更（質問、ナレッジファイルに反映する決定、リンクの修正）は、リポジトリのドキュメントチェックを実行して終了コードを確認したうえで、直接 main にコミットしてプッシュします。ディスパッチ前に、小規模なナレッジ編集の PR を作成しないでください。ブランチと自身でマージする PR は、ナレッジの再構成、移行の一括実施、コード、QA 設定、スクリプトに触れる変更など、規模が大きい変更やリスクの高い変更に使用します。その場合、「成功」とは、実際に確認済みの終了コードが 0 であることを意味します。Planner はまた、リリース時および大きな作業のまとまりの後に、ローカルではなく Queue 経由で main のリポジトリ全体の QA を実行します。project.qa.run に {"repository": "owner/name", "baseBranch": "main"} を指定して実行し、その後 project.qa.get で結果を取得します。見つかった問題の修正をブリーフにまとめます。オペレーターは Planner の変更をレビューしません。独立したレビューが必要なものはすべて、Queue を通じてブリーフとして依頼します。
• Worker： Queue から割り当てられたワークツリーで 1 件のブリーフを実装し、対象を絞ったチェック（変更したコードのテスト、変更箇所のコンパイル、ドキュメントを変更した場合はドキュメントチェック）を 1 回実行し、PR を 1 件作成して、Queue を通じて報告したら、作業から離れます。全体テストスイートは実行せず、チェックを繰り返しません。
• Reviewer： 正確な head を独立して確認します。差分を読み、同じ対象を絞ったチェックを実行し、動作を検証して、指摘事項を報告します。テストスイートは実行しません。

調整（復旧、レビューの割り当て、マージ、完了処理）は Queue の役割であり、スレッドの役割ではありません。Planner は引き継ぎを使って新しい後任者に引き継ぎます。引き継ぎファイルはありません。

リポジトリの採用または移行

adopt とスターターの template/ を使用してください。旧式の Northstar 構成のリポジトリは、意図的に一度で移行し、Queue マニフェストを削除します。

オプションモジュール

UI デザインの納品と、言語品質パッケージは別々のモジュールです。リポジトリがオプトインしている場合に限り、いずれかを読み込んでください。

• UI： ネストされた northstar-ui スキルは、承認済みのデザインブリーフに基づいて UI の作業を構築し、レビューします。ルートは構築とレビューです。
• 言語パッケージ： Rust または TypeScript/Svelte の品質監査を明示的に行う場合は、インストール済みパッケージのルートに従ってください。スキルの language:route タスクを実行します。通常のコーディングから監査を開始しないでください。
• ワークツリー： paseo:worktree は、Paseo ワークツリー用の兄弟チェックアウトを準備してリンクします。プロジェクトは paseo.json のセットアップおよびティアダウン処理からこれを呼び出します。