init-workspace

ワークスペースを初期化する

空または既存のリポジトリを、エージェント型ワークフローで動作するようにします。 汎用のひな形をコピーしてから、そのままのプレースホルダーを残すのではなく、このプロジェクトに合わせて調整します。

ターンの契約 — ターンを終える前に確認

✓ Required user inputs were answered concretely (not defaulted). Consent for
  every install, hook, and overwrite is explicit; a consent gap runs the
  three-tier dispatch and stops with the dispatcher's `open-questions@1` block
  — against a scratch unit folder when no unit exists yet (§Consent).
✓ The adapted scaffold and repository-state ledger are written (or the merge/abort decision was asked) and remaining placeholders are listed
✓ Nothing was installed, registered (MCP) or overwritten — including the global
  Serena config — without an explicit yes
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

チェックが入っていない項目がある状態でターンを終えようとしていますか？そのターンはまだ完了していません — 先に未完了の項目を完了してください（性能の低いモデルは文書末尾のタスクを見落としやすいため、このリストを最初に置いています）。

使用するタイミング

• このスキルを使うようリポジトリを設定する際に、ドキュメントの基盤（AGENTS.md + docs/ のマップ + テンプレート）を、単にコピーするのではなくプロジェクトに合わせて調整したい場合。
• インタビュー形式でゲートコマンド、アーキテクチャ、ドキュメントの領域を埋めたい場合は、静的な npx degit gtrabanco/agentic-workflow/template よりこちらを選んでください。

同意 — 必須。デフォルトで同意と見なすことは禁止

ツールのインストール、フックの接続、既存ファイルの上書きには、それぞれ明示的な同意が必要です。コンテキストを同意と見なすことはできません。また、リポジトリの状態が曖昧（部分的にひな形が適用されているなど）でも、推測で進めてはいけません。同意が不足している場合は未解決の質問として扱います：（0）出所（リポジトリ内のドキュメントを検索し、どこに記載されているか記録）→（1）調査（具体的な選択肢）→（2）停止：node scripts/needs-input.mjs <unit-dir> を実行し、open-questions@1 ブロックをそのまま貼り付け、質問を記載した状態で停止します。ディスパッチャーにはユニットフォルダーが必要です。同意不足は通常どのユニットよりも先に発生するため、実行時にはまずスクラッチ用のものを作成します（mktemp ディレクトリ内に SPEC.md + decisions.md を用意し、貼り付け後に削除）。そのスクラッチ用のものを対象にディスパッチャーを実行します。構文と終了コードについては、orchestration-envelope の references/TURN_CONTRACT.md §Open questions を参照してください。 [target-dir] は省略可能です。省略した場合はカレントディレクトリが対象となり、その旨が記録されます。

ステップ 0 — プロジェクトを把握する（必ず最初に実行）

何かを変更する前に、対象ディレクトリ（[target-dir]。デフォルトは cwd）を調べます。

• 既存のエージェントガイド（AGENTS.md または旧形式の CLAUDE.md）、docs/、.github/ がある場合は、上書きしないでください — まず、それがagentic-workflow のひな形かどうかを確認します（目印：エージェントガイドがあり、かつ docs/features/ROADMAP.md または docs/workflow/ ディレクトリがある）。両方の目印があれば、Upgrade mode の説明に従い、マージ／既存の内容に合わせた調整／中止と並べて、デフォルトのアクションとしてアップグレードを提案します。エージェントガイドまたは docs/ はあるものの目印がない場合（別のひな形の場合）は、ブートストラップを続け、これまでどおりマージ／既存の内容に合わせた調整／中止を尋ねます。
• マニフェスト（package.json、pyproject.toml、go.mod、Cargo.toml、Gemfile、…）から技術スタックを検出し、ゲートコマンドと命名規則を提案します。
• Git の状態を確認します（リポジトリかどうか、デフォルトブランチ、リモート URL → フォージ：github.com → GitHub/gh、gitlab → GitLab/glab、その他の場合は確認します）。

段階的な読み込み — ブートストラップかアップグレードのどちらか一方のみ

参照許可リストは、以下にリンクされた6つのパスだけです。ほかの references/ パスを作成したり読み込んだりしないでください。ステップ0では、ルートを1つだけ選択します。

既存の Claude Code、Cursor、Copilot、または OpenCode のスキャフォールドに関する厳守ルール： references/UPGRADE.md だけを読み込みます。コミット済みの安全アダプターがない場合はアップグレード作業であり、ベンダープリミティブの不足ではありません。ランタイムプラットフォームに対応する名前付きアダプターがまったくない場合を除き、ブートストラップやポータビリティを読み込まないでください。

• 裸のリポジトリ／別のリポジトリ： ブートストラップの検出を読み、そこでの聞き取りを完了してから、ブートストラップの書き込みを読みます。検出ルートと書き込みルートの両方で、スタック検出のために SERENA 言語サーバーを読み込みます。
• 既存のエージェント型ワークフローのスキャフォールド： アップグレードだけを読みます。追加のみというルールは絶対です。ブートストラップを再実行しないでください。アップグレードルートでは、追加のプロビジョニング手順のために SERENA 言語サーバーを読み込みます。
• pi パッケージがないホストでの Engram のプロビジョニング： Engram のプロビジョニングを読みます — 検出、確認、登録または手順の案内、報告を行います。ブートストラップの書き込みルートでのみ読み込まれます（pi パッケージは自身をプロビジョニングします。機能66）。
• 検出されたランタイムプラットフォームに名前付きアダプターがない場合：そのフォールバックに限り、ポータビリティを追加します。Claude Code、Cursor、Copilot、OpenCode は名前付きのサポート対象アダプターです。アダプターファイルがない場合はアップグレードで修復し、ポータビリティの読み込みは行いません。

すべてのリソースは、このファイルから1階層先にあります。既存ファイル、フックへの同意、インストールへの同意、残存項目の報告は、固定された契約です。テンプレート／移行の根拠がない場合は、選択したルートで報告し、推測で補完しないでください。安全アダプターだけが欠けている既存の OpenCode スキャフォールドでは、アップグレードだけを読み込み、ブートストラップとポータビリティはスキップします。

ガードレール

• 明示的な同意なしに、既存のエージェントガイド（AGENTS.md、またはレガシーな CLAUDE.md）やdocs/を上書きしないでください。
• ガイドは1つ、名前も1つです。 ガイドはAGENTS.mdです。レガシーなCLAUDE.mdを廃止するのはアップグレードモードの場合に限り、明示的な同意を得たうえで、そこにしかない内容を先にAGENTS.mdへ統合した後に限ります。AGENTS.md対応前のClaude Codeリリースを使っているユーザーは、CLAUDE.mdを残すことができます。その選択は残存事項として報告し、修正すべき差分として扱いません。
• 追加のみとし、決して上書きしない（アップグレードモード）。 アップグレードモードでは、プロジェクトにないブロックの追加と、未入力のプレースホルダーの補完のみを行います。現在のテンプレートでそのブロックが変更されていても、プロジェクトがすでに調整したブロックを書き換えたり削除したりすることはありません。本格的な再調整は、明示的に依頼されたブートストラップの適合モード実行として別途行い、アップグレードモードが独自に実施することはありません。緊急度ラベルの初期設定も同様に追加のみです。 urgent／fix-nextラベルがない場合は作成し、すでに存在する場合は（プロジェクトがカスタマイズした名前、色、説明を含め）変更しません。
• Serenaの規約 — ツールと設定に関する同意確認は1回のみです。 .serena/project.yml はコミット対象です。project.local.ymlとcacheはローカルに保ちます。明示的な同意なしに、.serena/の設定を書き込んだり、ツールをインストールしたり、MCPサーバーを登録したり、グローバルのserena_config.yml（trusted_project_path_patterns）を変更したりしてはいけません。SERENAが唯一の確認と、定型のプロビジョニングレポートを担当します。LSPはドキュメントを検証しません。ファイル形式のサーバーが一覧にない場合（markdown／yaml／jsonは自動検出されません）に誤検出が発生し、起動に失敗したサーバーは削除する必要があります（1つでも失敗すると、プロジェクト内のすべてのサーバーが無効になります）。また、LSPのエビデンスはTypeScript／JavaScriptのみを対象とします。ドキュメントの検証はスクリプトの役割です。
• Engramのプロビジョニングは、必ず先に確認し、前提としません（feature 66）。 engramバイナリを検出し、ホストのMCP設定を書き込む前に確認し、正確なmcp --tools=agent argvとともに絶対パスを書き込み、書き込んだ内容を正確に報告します。既存のengram宣言は上書きしません。バイナリがない場合は残存事項として記録します。記載されているインストール方法はpi install npm:gentle-engram@latestです。CLI独自のセットアップサブコマンドは使用しません。このサブコマンドは、再実行されるまで実行時点のバージョンを提供し続けるためです。
• 検索インデックスの足場とGitフックの導入には同意が必要です（AC22）。 インデックス一式（コミット対象の.agentic-workflow/index.json設定と、3つの鮮度維持フック（post-merge、post-checkout、post-rewrite。すべてindex-sync.shを.git/hooks/にインストール））は、「ドキュメント検索インデックスの足場とGitフックをインストールしますか？」という質問に対して明示的な同意を得た後に限りインストールします。同意がない場合は何もインストールせず、残存事項として記録します（エントリーポイントは引き続き実行され、最初のクエリでインデックスを構築します。フックは鮮度を保つための高速処理にすぎません）。また、新たに明示的な同意を得ない限り、後日の訪問時にも.git/hooks/や設定を書き込みません。契約上、フックはベストエフォートです（doc --sync --quietを実行し、常に終了コード0を返します。高速処理によってGitを妨げることはありません）。
• ここで緊急度ラベルの語彙を再定義しないでください。 skills/triage-issue /SKILL.mdがurgent／fix-nextの名前、色、適用ルールを定める唯一の場所です。このスキルはリポジトリにこの2つのラベルを初期設定するだけであり、3つ目のラベルを作ったり、2つのラベルの意味を変更したりしません。
• ドキュメントのみの足場であり、アプリケーションコードの変更や、促されていない依存関係のインストールは行いません。
• アーキテクチャに依存せず、プロジェクトのパターンを記録するだけで、押し付けません。
• 具体的な内容を捏造するより、正直なプレースホルダーを優先し、未記入の項目を明示します。
• ワークフロー規約が定められている場合はそれに従います。既存のリポジトリではデフォルトブランチで作業せず、依頼がない限りコミットやプッシュを行いません。

ユニットドキュメントの規約（適応型レーン）

適応型レーン（機能 61）は、固定パイプラインを単一のユニットドキュメントモデルに置き換えます。新しいユニットごとに、docs/features/<NN>-<slug>/ の下に 14 セクションからなる SPEC.md を 1 つ作成します。セクションは、Objective、Why、User outcome、Acceptance criteria、Impact、 Non-goals、Future cost、Applicable tests、Known pre-existing issues、Tasks、 Evidence、Progress log、Next、References です。

プロジェクトの AGENTS.md に書き込まれる規約：

• トリアージ：レーンの進行役（/unit-lane / workflow-status）は、順序が決定的なステップ一覧（調査、設計、計画、実装、テスト、証拠、レビュー、ドキュメント、リリース）を返します。
• ガード：scripts/diff-guard.mjs は各境界で git diff --stat を計測します。超過した場合は、トリアージを必ずやり直します。不正な操作の防止：「コメント、空行、ドキュメント、テストを削除して差分を縮小してはなりません。」
• 証拠の行：AC ごとに 1 行を記録し、実行した内容、終了コード／ダイジェスト、出力（2 行以内）、検証者を記載します。申告ではなく、検証済みであること。
• 進捗ログ：実施した各ステップについて、日付付きの記録（YYYY-MM-DD HH:MM）を残します。
• コミット形式：type(scope): description（Conventional Commits）。
• ロードマップのステータス：idea → defined → planned → in-progress → done。

これらは bootstrap（新規作成）と upgrade モード（レーン導入前のインストールに対する追加のみ）によって書き込まれます。レーン導入前のプロジェクトに追加されるのは、AGENTS.md のレーン規約セクション、docs/features/_TEMPLATE/ のユニットドキュメントテンプレート、ユニットドキュメント用の docs-map の行だけです。

正規化されたリポジトリ状態

テンプレートを基に docs/workflow/REPOSITORY_STATE.md を作成します。計画の前に調査によって証拠を確定し、事実を更新するのはリゾルバーのみであることを説明します。

アーキテクチャ上の不変条件

長期にわたるアーキテクチャ上のルールを定める任意のプロジェクト契約として、docs/architecture/ARCHITECTURAL_INVARIANTS.md を用意します。各項目には、安定した ID、リポジトリ内の証拠、ルールを変更できる権限者を明記する必要があります。実装や機能 SPEC からルールを推測してはなりません。このドキュメントがないプロジェクトも引き続き互換性があります。その場合は、後続のワークフロー成果物に n/a: no project invariants declared と記録し、暗黙のうちに作成しないでください。

移植性

このスキャフォールドはベンダーに依存せず、異なるのはフックの有効化方法だけです。検出されたエージェントに名前付きアダプターがない場合は、移植性に従い、明示的な残存課題として扱ってください。サポート対象の Claude Code、Cursor、Copilot、OpenCode アダプターは、このフォールバックを読み込みません。

他のスキルとの関係

• npx degit gtrabanco/agentic-workflow/template — このスキルが適応させる静的コピーです。元のスキャフォールドをそのまま使用し、自分で内容を埋めたい場合はこちらを使います。
• docs/workflow/PORTABLE_PROMPT.md — プロジェクトに適応させたスキル（動作）を再生成します。このスキルは基盤（ドキュメント）を適応させます。相互に補完します。
• 初期化後：discover-repository-state → workflow-status（開始可能な項目を確認）→ /unit-lane（レーンの進行役）の順に実行します。audit-docs を実行して、スキャフォールドに一貫性があることを確認します。

完了条件

• 対象に、プロジェクトに合わせた AGENTS.md、docs/ のひな形、.github/ テンプレートが存在し、未使用のフォルダーが削除され、残っているプレースホルダーにフラグが付けられ、プラットフォームの関連レビュー用スキルが記録され（導入も提案され）、urgent／fix-next ラベルがシードされる（ひな形作成時）か、追加分を調整され（アップグレード時）、承認されたすべての安全アダプターが有効化され、フィクスチャでテストされていること。フック API または依存関係を利用できない場合は、未対応項目として明示的に記載されていること。 アダプティブレーンの規約（単位ドキュメント、トリアージ、カタログの手順、ガード、エビデンス、コミット形式）が AGENTS.md に記載されていること。

• Serena がセットアップされ、結果が報告されていること：同意確認の質問が 1 回行われ、プロジェクト設定が書き込まれている（または理由を添えてスキップされている）こと、ツールがインストールされ、検出されたプラットフォーム用に MCP サーバーが登録されていること。または、拒否された項目や存在しない項目が、それぞれ理由とともに未対応項目として記録されていること。所定のセットアップ報告に、記載された各サーバーのヘルスチェック結果が示されていること。いずれの場合も実行が完了すること。

• 最後の → Next: ブロックが出力されること（スキルのインストール提案も含む）：

  → Next: /discover-repository-state — freeze repository evidence before planning
    · raw idea → /workflow-status → /unit-lane (the lane conductor)
    · next roadmap entry → /unit-lane (tridirection decides catalog steps)
    · confirm the scaffold is coherent → /audit-docs