alignfirst-setup-guide

AlignFirst セットアップガイド

ユーザーの意図に応じて案内します。そのルートで必要な参照だけを読み込みます。Docmap、workspace、AlignFirst スキルは、それぞれ個別に導入できます。

用語

AlignFirst CLI は、alignfirst npm パッケージとバイナリです。guide、ticket、sync、 plans、docmap、conventions、context、config、doctor を提供します。

AlignFirst スキルは、CLI を実行するスタブです。9 つのコマンドスキル alspec、alplan、 al、almerge、alreview、aldescription、alcatchup、alcatchupaad、alcatchupspec では、 disable-model-invocation: true を維持します。人間は Claude Code、GitHub Copilot、 Cursor では /alspec、Codex では $alspec、Pi では /skill:alspec として実行します。任意の alignfirst スキルを使うと、エージェントは文章中に記載されたプロトコルを認識できます。プロジェクトの指示ファイルが標準の alignfirst context セクションから始まる場合は、この機能がすでに備わっています。

work-files リポジトリは、alignfirst plans setup で設定する任意の CLI モードです。

AlignDev CLI の aligndev は、アシスタント用のプレイブック、コーディングエージェントへの委任、プロジェクトの検出を担います。OpenClaw アシスタントホストではこれをインストールし、コーディングエージェントのアシスタントでは npx 経由で実行します。

未変更のリポジトリ

ユーザーがリポジトリ内に何も書き込まないことを希望する場合、以下のすべてのルートでcompanion-setup.mdに従います。その場合、プロジェクトの AlignFirst ファイルはコンパニオンディレクトリに置かれ、そのモードがサポートするツールのみが適用されます。

ツールの指定がある場合

ユーザーがツールを指定した場合は、リポジトリを確認して、そのツールに直接進みます。インストールまたはアップグレードするのは、ユーザーが求めたものだけです。

• AlignFirst CLI、プロトコル、またはスキル：alignfirst-skills-setup.md。要求されたコンポーネントのみをインストールします。スキルは別途インストールせず、npx 経由で CLI を呼び出します。 既存の v1、v2、または v3 のインストール、~/.config/alignfirst/ があるマシン、または paths を含むコンパニオンレジストリの場合は、まず alignfirst-upgrade.mdを確認します。
• Work-files リポジトリ：plans-setup.md。
• docmap：docmap-setup.md。古い docmap 本文（「すべてのタスクで必須」）を含む指示ファイルには、Docmap スニペットを更新する必要があります。
• workspace：workspace-setup.md。workspace.mjs に ports グループまたは setupProfiles がある場合は、Workspace のポートを Dev-Server に移動する必要があります。
• AlignDev（aligndev）：OpenClaw アシスタント向けか、コーディングエージェント（Claude Code、Codex、Pi）向けかをユーザーに確認します。OpenClaw の場合は、OpenClaw 向け AlignDevに従います。コーディングエージェントの場合は、aligndev スキルをグローバルにインストールするコーディングエージェント向けアシスタントに従います。古い ~/.alignfirst/aligndev.config.json がある場合は、AlignDev の設定名を変更する必要があります。

このルートでは、ツールの一覧を提示したり、関係のないツールを追加したりしないでください。

ツールの推奨

ユーザーからプロジェクトに何をセットアップできるか尋ねられた場合は、コンテキストに記載されたスキルを確認し、リポジトリを調査します。グローバルスキルとプロジェクトのツールは分けて提示します。インストールまたは設定の前に、任意の組み合わせをユーザーに選んでもらいます。

グローバルスキル

コンテキスト内のスキル一覧を使って、現在のエージェントで利用可能なスキルを確認します。

• aligndev：コーディングエージェント向けアシスタントのプレイブックです。
• alignfirst：文章中で言及されているプロトコルを認識します。
• paseo-alignfirst-workspace：Paseo ユーザー向けの推奨スキルです。Paseo で AlignFirst ワークスペースを使用する方法を説明します。
• コマンドスキル：alspec、alplan、al、almerge、alreview、aldescription、alcatchup、alcatchupaad、alcatchupspec。

利用可能なスキルを報告し、利用できないスキルについては、現在のエージェントにグローバルインストールすることを提案します。一覧にない名前のスキルは、このセッションでは利用できません。ただし、ディスク上にそのスキルが存在しないことを意味するものではありません。ホストがスキル一覧を提供しない場合は、利用状況を不明と報告します。この確認にファイルシステムのスキャン、インストーラーコマンド、または doctor の実行は必要ありません。

承認されたインストールは、AlignFirst スキルのセットアップまたはグローバルな aligndev スキルの手順に従います。グローバルスキルをインストールしても、プロジェクトの設定や Pi ツールのインストールは行われません。アシスタントの準備手順では、ユーザーが別途ショートカットをリクエストしない限り、コマンドスキルのインストールは省略されます。

Paseo ユーザーには、承認を得て paseo-alignfirst-workspace をグローバルにインストールします。<agent> は現在のエージェントのインストール対象（claude-code、codex、または pi）に置き換えます。

npx -y skills add https://github.com/paleo/alignfirst --global --yes \
  --agent <agent> --skill paseo-alignfirst-workspace </dev/null

プロジェクトのツール

プロジェクトの言語やスタックにかかわらず、グローバルスキル、AlignFirst プロトコル、Docmap を推奨します。既存の導入状況と、すでに利用可能なものを区別するため、既存の痕跡を確認します。

• AlignFirst プロトコルは、CLI を通じて仕様策定、計画、実装、マージ、レビュー、説明、キャッチアップの各ワークフローを提供します。コマンドスキルはショートカットを追加するもので、単独でインストールできます。作業ファイル用リポジトリは任意の追加オプションです。
• docmapは、リポジトリの docs/ ツリーをエージェントと人が見つけやすくします。AlignFirst CLI 経由、またはスタンドアロンの @alignfirst/docmap パッケージとして利用できます。docs/ ディレクトリがない場合は、ドキュメントを整備する機会として活用します。推奨を省略する理由にはなりません。
• workspaceは、分離された git worktree 開発環境を作成します。Node プロジェクトでは、workspace のセットアップに従い、@alignfirst/workspace のインストールと使用を推奨します。プロジェクトのランタイム宣言、スクリプト、依存関係、ドキュメントから Node の使用状況を検出します。ツールにのみ使用されている package.json は、Node を使用している根拠として不十分です。すでに workspace ツールが存在する場合は、置き換えを勧めるのではなく、文書化されたワークフローを推奨します。他のスタックでは、リクエストがある場合、またはリポジトリ内の根拠に基づく場合にのみ workspace を提示し、既存の非 Node 実装を優先します。

このオプションを提示する前に、作業ファイル用リポジトリの有無を確認します。

プロジェクトの指示

プロジェクトで採用されているツールに応じて、AGENTS.md または CLAUDE.md のディスカバリーセクションを選びます。

• AlignFirst スキルまたはプロトコルを採用している場合： AlignFirst セットアップの alignfirst context セクションを使用します。これは Docmap - Seek Documentation に置き換わります。重要なドキュメントの一覧とプロジェクト固有の指示は維持します。
• AlignFirst スキルまたはプロトコルを採用せず、Docmap のみを使用する場合： Docmap セットアップの Docmap - Seek Documentation を、プロジェクトで実際に使われている Docmap コマンドとともに使用します。
• Workspace のみを使用する場合： workspace の指示を追加します。

Docmap または workspace だけをインストールしても、プロジェクトが AlignFirst プロトコルを採用することにはなりません。スキルをグローバルにインストールしても、すべてのリポジトリでそれらが採用されるわけではありません。

OpenClaw 向け AlignDev

OpenClaw 向け AlignDev は、OpenClaw のアシスタントを AlignFirst と連携する開発者に変えます。 アシスタントはチャット上のアイデンティティ、そのチャネルとセッションを保持し、AlignFirst プロトコルを使用してコーディングエージェント（Claude Code、Codex、または Pi）経由でリポジトリ作業を行います。

1 つのデプロイでは、専用の Linux サービスアカウントが、Slack または Discord、および OpenClaw アプリ上で、独自の名前とチャネルアイデンティティを使ってアシスタントを実行します。このスキルと、それが生成するリポジトリ全体を通して、以下の 2 つの用語を使用します。

プロジェクトを準備すると、そのリポジトリがアシスタントと互換性を持つようになります。アシスタントを作成すると、そのビルドとデプロイが行われます。レンダリングまたはアップグレードの前に、デプロイ境界をお読みください。3 つのオーバーレイはすべて、名前付きプロファイルと、インベントリ登録されたネイティブストアを使用します。Pi では、明示的に書き込み可能な例外である auth.json を通じてネイティブ認証を維持します。それ以外のすべての管理対象リソースには、引き続き制御された保守の保護が適用されます。オフラインでのテンプレートチェックは、実環境でのデプロイ受け入れに代わるものではありません。

アシスタント向けのプロジェクト準備

リポジトリを変更する前に調査してください。準備済みのプロジェクトには、以下のすべてが揃っています。

1. AGENTS.md または CLAUDE.md にある標準のブートストラップセクション。タイトルと導入部の後に続く最初の ## セクションとして配置します。README では、利便性のためにグローバル CLI のインストール方法を案内してもかまいません。アシスタント管理対象のプロジェクトでは .alignfirst.json が必須で、それ以外では任意です。
2. .alignfirst.json を書き込んだ後、ワークスペースを設定する前に、aligndev project doctor --root <projects-directory> の結果がクリーンであること。インベントリに問題がある場合は、準備を中止してください。
3. 利用可能な有効な作業ファイルがあり、プロジェクト自身のリポジトリでは追跡されていないこと。別の作業ファイル用リポジトリで追跡してもかまいません。チケットやコーディングセッションに関わる操作を行う前に、プランがない場合、またはプロジェクトで追跡されている場合は、aligndev の work-files-setup ガイドトピックに従ってください。認可されたコンパニオンの選択では、プロジェクトの内容を変更せず、コピーもしません。
4. プロジェクトのスクリプトや CLI の手順を含む docmap。リポジトリに docs/ ディレクトリがない場合は、準備の一環としてdocmap-bootstrapping.mdに従い、ドキュメントをブートストラップしてください。
5. 文書化された worktree の手順。Node 以外の実装も含め、既存のプロジェクト用ワークスペースツールを引き続き優先します。ワークスペースシステム全体のインストールは任意です。選択する場合は、AlignDev コントラクトを満たしてください。選択しない場合は、aligndev worktree を使用し、インストール／ビルド／テストのコマンドと、アプリケーションのライフサイクルコマンドをそれぞれ文書化してください。
6. プロジェクトのランタイム要件。Node プロジェクトでは、fnm がバージョンを選択できるよう、バージョンを宣言してください（.nvmrc、.node-version、または engines.node）。何も存在しない場合は、どのバージョンを使用するか確認してください。その他のランタイムについては、それぞれの文書化されたツールに従ってください。
7. 不慣れな開発者向けの、プロジェクト固有の DEVELOPERS.md。コマンド、アーキテクチャ、ドキュメントマップ、開発ワークフロー、検証手順を記載してください。

ユーザーがリポジトリを変更せずに維持するよう求めた場合は、代わりにcompanion-setup.mdのアシスタント向けセクションに従ってください。

アシスタントとしてのコーディングエージェントを含め、アシスタント向けにプロジェクトを準備するすべての手順では、AlignFirst のコマンドスキルとグローバルブートストラップ行を省略します。項目 1 のブートストラップセクションは省略しません。アシスタントのサービスアカウントには、委任先のコーディングエージェント用に、このガイドのグローバルインストールを維持します。

パッケージマネージャー、ランタイム、ビルド、テスト、lint、開発サーバー、ポート、共有ディレクトリ、シード済み設定ファイル、チームプランの詳細を検出して確認してください。リポジトリで確認できた事実だけを記述してください。上記の該当するツールリファレンスに従ってから、Node のバージョン宣言を明記し、DEVELOPERS.md を完成させてください。

アシスタントを作成する

アシスタントのデプロイ自体を作成または運用する場合は、 aligndev-openclaw.md をお読みください。通常の ツール設定では、このワークフローを読み込まないでください。

アシスタントとしてのコーディングエージェント

OpenClaw を使わずに、1 つのプロジェクトでアシスタントとして動作する Claude Code、Codex、または永続的な Pi セッションについては、coding-agent-assistant.md をお読みください。Pi は /skill:aligndev と、別途インストールされた汎用バックグラウンドツールを使用します。Pi の子エージェントは、計画やレビューの委任に独立したサブエージェントパッケージを使用します。スキルをインストールしただけでは、実行可能なツールは提供されません。

共通の調査ルール

package.json の packageManager からパッケージマネージャーを検出し、次にルートのロックファイルを確認します。 package-lock.json は npm、pnpm-lock.yaml は pnpm、yarn.lock は yarn、bun.lock または bun.lockb は bun を意味します。判別できない場合は npm を使用します。

コマンドをそのパッケージマネージャーに合わせてください。npm ではスクリプトのフラグの前に -- が必要です。pnpm と yarn では run と区切り文字を省略します。bun では run を残し、区切り文字を省略します。

変更を提案する前に、既存の利用状況を確認します。

• docmap：docmap スクリプト、@alignfirst/docmap、指示ファイル内の alignfirst docmap、または docs/ があること。
• workspace：Node.js 以外のツールを含む、文書化されたワークスペースの手順があること。workspace スクリプトまたは @alignfirst/workspace も利用状況を示すものです。
• @alignfirst 導入前のインストール：マニフェストに @paleo/docmap または @paleo/workspace があること。それ以外の変更を提案する前に、依存関係を @alignfirst の名前に置き換え、ラッパースクリプト（scripts/workspace/*.mjs）内の @paleo/ インポート指定を書き換えてください。2 つのスコープは並行してインストールされるため、マニフェストだけを変更すると、ラッパーは古いパッケージをインポートしたままになります。
• AlignFirst：.alignfirst.json、.plans/、alignfirst context または npx alignfirst context を実行するブートストラップセクション、AlignFirst の指示セクション、正規のスキルインストール、または npx alignfirst config が報告する関連ツールがあること。
• work-files リポジトリ：.plans のシンボリックリンク、または .alignfirst.json 内の plans.repositoryFolder があること。
• アシスタントの準備：上記の 7 部構成の契約がすべて揃っていること。

プロジェクトに変更を加える直前に、作業ツリーがクリーンであることを必須とします。読み取り専用の調査や推奨事項には、クリーンな作業ツリーは必要ありません。