workspace

workspace

概要

チームで共有するコンテキストを管理する、複数リポジトリ用ワークスペースコーディネーターです。親リポジトリには、product-specify、architect-specify、team-levelup が作成する共有の決定事項（PDR、ADR、CDR）が .adlc/ の下に格納されます。深さ 1 の子実装リポジトリを検出し、必要に応じて Git サブモジュールとしてリンクすることで、ワークスペース全体を git clone --recursive でクローンできます。

workspace.yml もレジストリファイルもありません。規約のみで構成されています。

• 親リポジトリ = 現在の作業ディレクトリ（Git リポジトリである必要があります）
• 子リポジトリ = .git/ を含む深さ 1 のサブディレクトリ
• 共有コンテキスト = 親リポジトリのルートにある .adlc/

使用する場面

• 初回セットアップ（--init）：.adlc/ ディレクトリ構造を作成し、.gitignore の規約を設定して、必要に応じて子リポジトリをリンクします。
• product-specify または architect-specify の実行後：親リポジトリに共有 PDR／ADR が作成され、複数の実装リポジトリが並んでいる場合に使用します。
• 新しい子リポジトリをクローンしたとき：ワークスペースにクローンした子リポジトリをサブモジュールとして登録（--link）するか、無視（--ignore-only）する場合に使用します。
• ワークスペースの健全性を監査するとき：作業ツリーの変更、未プッシュのコミット、親のサブモジュール参照と子の HEAD の SHA のずれを確認します。
• 子リポジトリから親の .adlc/ 共有コンテキストを参照できることを確認するときに使用します。

--init を使用しない場面

• ワークスペースがすでに初期化済みの場合：代わりに /workspace --status で監査します。
• 子リポジトリの状態だけを監査する場合：/workspace を使用します（読み取り専用の検出とステータス表示）。
• 初期化後に子リポジトリを追加でリンクする場合：/workspace --link を直接使用します。

ユーザー入力

$ARGUMENTS

コマンド

コマンド	目的
/workspace --init	初期化：.adlc/ 構造の作成、.gitignore の設定、子リポジトリの検出
/workspace	子リポジトリを検出し、ステータスの概要を表示（読み取り専用）
/workspace --link	子リポジトリを Git サブモジュールに変換（親の作業ツリーがクリーンである必要があります）
/workspace --status	詳細な監査：ブランチ、変更、未プッシュ、SHA のずれ、.adlc の有無
/workspace --ignore-only	子リポジトリをサブモジュールにせず、.gitignore に追加
/workspace --init --link	初期化と子リポジトリのリンクを一度に実行
/workspace --init --ignore-only	初期化し、子リポジトリを .gitignore に追加
/workspace --dry-run	実行せずに変更をプレビュー（--init、--link、--ignore-only と組み合わせて使用）
/workspace --force	親のインデックスですでに追跡されているリポジトリを変換（作業ツリーがクリーンである必要があります）

実行

初期化モード（--init）

初期化セットアップスクリプトを実行し、.adlc/ 構造を作成して、.gitignore の規約を確認し、子リポジトリを検出します。

# Bash
scripts/bash/setup-workspace.sh --json

# PowerShell
scripts/powershell/setup-workspace.ps1

初期化セットアップの出力（JSON）：

{
  "REPO_ROOT": "/path/to/parent",
  "ADLC_DIR": "/path/to/parent/.adlc",
  "ADLC_DIRS_CREATED": [".adlc/product", ".adlc/drafts", ".adlc/drafts/pdr"],
  "GITIGNORE_EXISTS": true,
  "GITIGNORE_RULES_MISSING": [".adlc/"],
  "CHILD_REPOS": [
    {"name": "backend-api", "path": "/path/to/parent/backend-api", "remote": "[email protected]:org/backend-api.git", "is_submodule": false, "is_tracked": false}
  ],
  "CHILD_COUNT": 1,
  "BRANCH": "main"
}

作成されるディレクトリ：

.adlc/
├── product/           # PDRs (product-specify, product-init)
├── architecture/      # ADRs (architect-specify, architect-init)
├── context/           # CDRs (team-levelup, team-init)
├── skills/            # Team skills metadata
└── drafts/            # Draft artifacts before clarification
    ├── pdr/
    ├── adr/
    ├── cdr/
    ├── skills/
    └── evals/

初期化セットアップ後、--link または --ignore-only も指定されている場合は、以下の対応するアクションモードに進みます。

監査／リンクモード（デフォルト、--link、--status、--ignore-only）

ワークスペースコーディネータースクリプトを実行します。

# Bash
"$(dirname "$0")/../scripts/bash/workspace.sh" --json [--link] [--status] [--dry-run] [--force] $ARGUMENTS

JSON 出力を解析してユーザーに提示します。

出力仕様

初期化モードの出力

setup-workspace.sh --json が出力します（上記を参照）。

監査／リンクモードの出力

workspace.sh --json が出力します。

{
  "PARENT_REPO": "/abs/path/to/parent",
  "PARENT_BRANCH": "main",
  "PARENT_HAS_ADLC": true,
  "MODE": "discover|link|status",
  "DRY_RUN": false,
  "DISCOVERED_COUNT": 3,
  "REGISTERED_COUNT": 2,
  "SKIPPED_COUNT": 1,
  "ERROR_COUNT": 0,
  "REPOS": [
    {
      "name": "backend-api",
      "path": "/abs/path/to/parent/backend-api",
      "remote": "[email protected]:org/backend-api.git",
      "branch": "main",
      "dirty": false,
      "unpushed": 0,
      "is_submodule": true,
      "parent_sha": "abc1234",
      "child_sha": "abc1234",
      "sha_drift": false,
      "has_adlc": false
    }
  ],
  "ERRORS": []
}

初期化フェーズ

フェーズ 1：.adlc/ 構造の作成

セットアップスクリプトは、.adlc/ ディレクトリツリーが存在しない場合に作成します（product/、drafts/、およびファミリーごとのドラフトサブディレクトリ。共有レイアウトでは、.adlc/ をマシンパイプラインの状態に限定しています）。これは、他のスキルがドラフトやパイプラインの状態を書き込む共有コンテキストディレクトリです。公開済みの決定記録とコンパイル済みの成果物は docs/adlc/ の下に格納されます。

べき等：すでに存在するディレクトリは再作成されません。

フェーズ 2：.gitignore の設定

セットアップスクリプトは、ワークスペースの規約について .gitignore を確認し、不足しているルールを報告します。

許可リスト方式 — .adlc/ を一括して無視することはなくなりました。マシンのパイプライン状態は、追跡対象の例外を再度含めたうえで .adlc/* によって無視されます。公開コンテンツである docs/adlc/ 以下は常に追跡されます。

# agent-install surface (regenerated)
.agents/
.opencode/
.claude/
.cursor/
.codex/
.gemini/
.qwen/
.devin/
.tabnine/
skills-lock.json
.skills.json
.mcp.json
.events.json
.pytest_cache/
.ruff_cache/

# machine pipeline + runtime state (tracked exceptions follow)
.adlc/*
!.adlc/init-options.json
!.adlc/workspace.yml
!.adlc/drafts/
!.adlc/evals/
.adlc/evals/results/
!.adlc/memory/
.adlc/memory/*
!.adlc/memory/evals/
!.adlc/memory/evals/holdout.json

# generated reports (legacy name kept during transition)
.adlc/team-learn-report.md
.adlc/team-levelup-report.md

# knowledge graph (generated)
graphify-out/

許可リストは scripts/bash/paths.sh（GITIGNORE_RULES_ALLOWLIST。scripts/powershell/paths.ps1 にも反映）で一元的に定義されています。セットアップスクリプトはこの定義を読み込み、不足しているルールを報告します。追跡済みの既存ファイルは引き続き機能します。gitignore が適用されるのは未追跡ファイルのみです。

対応：GITIGNORE_RULES_MISSING が空でない場合、不足しているルールを .gitignore に追加します。既存のルールは削除しないでください。変更を加え、--dry-run モードではない場合は、メッセージ [workspace] Configure .gitignore for workspace conventions でコミットします。

フェーズ 3：子リポジトリの検出

セットアップの出力から、検出された子リポジトリを確認します。

検出されたリポジトリ：

## Discovered Child Repos

| # | Repo | Remote | Submodule? | Tracked? |
|---|------|--------|------------|----------|
| 1 | **backend-api** | [email protected]:org/backend-api.git | No | No |
| 2 | **frontend** | [email protected]:org/frontend.git | Yes | N/A |

Reply: Y to proceed with --link/--ignore-only, or adjust.

フェーズ 4：子リポジトリへの対応（任意）

--link または --ignore-only を --init と組み合わせた場合は、初期化のセットアップ後に対応するアクションを実行します。

--link（サブモジュールの登録）

workspace.sh --link に処理を委譲します。次の安全チェックが適用されます。

• 親の作業ツリーがクリーンであること（子リポジトリ外に未コミットの変更がないこと）
• 子リポジトリにリモート origin URL が設定されていること
• リモート URL が許可されたスキーム（https://、git@、ssh://）を使用していること — それ以外（例：http://、file://）はエラーとして報告され、スキップされます
• すでに登録済みのサブモジュールはスキップされます（冪等性）
• 親のインデックスで追跡されているリポジトリには --force が必要です
• まず --dry-run でプレビューし、ユーザーに確認してからリンクします

--ignore-only（サブモジュールではなく無視）

サブモジュールを作成する代わりに、検出された各子リポジトリを .gitignore に追加します。

各子リポジトリに対して：

1. 親のインデックスで追跡されている場合：git rm --cached <name>（インデックスから削除し、ディスク上には残す）
2. まだ存在しない場合は、<name>/ を .gitignore に追加する
3. すでに .gitignore にあるリポジトリはスキップする（冪等性）

変更を加えた場合は、メッセージ [workspace] Add child repos to .gitignore でコミットします。

使用する場合：子リポジトリが完全に独立したプロジェクトで、チームメンバーが個別に管理する場合です。

フェーズ 5：出力の概要

## Workspace Init Complete

### .adlc/ Structure
- Created: 7 directories under `.adlc/` (`product/`, `drafts/`, `drafts/{pdr,adr,cdr,skills,evals}/`)

### .gitignore
- Rules added: 5
- Rules verified: 12

### Child Repos
- Discovered: 3
- Registered as submodules: 2
- Ignored: 0
- Skipped (already submodules): 1

### Next Steps
1. Create product decisions: `/product-specify`
2. Create architecture decisions: `/architect-specify`
3. Audit workspace health: `/workspace --status`

検出ルール

ルール	動作
深さ	1 階層のみ（親ルートの直下にあるサブディレクトリ）
検出	ディレクトリに .git/ ディレクトリまたは .git ファイルが含まれている
除外対象	node_modules、.venv、venv、dist、build、target、.idea、.vscode、.git、.cache、.specify
設定ファイルなし	workspace.yml はなく、自動検出のみ

チーム共通コンテキスト（.adlc/）

親リポジトリの .adlc/ ディレクトリは、チームコンテキストの唯一の情報源です。 --init によって作成され、他のスキルによって維持されます。

成果物	パス	作成元
PDR のドラフト	.adlc/drafts/pdr/（承認後 → docs/adlc/memory/pdr/）	product-specify、product-init
ADR のドラフト	.adlc/drafts/adr/（承認後 → docs/adlc/memory/adr/）	architect-specify、architect-init
CDR	team-ai-directives の adlc ブランチ（ローカルのドラフトは .adlc/drafts/cdr/）	team-levelup、team-init
スキル	エージェントスキルのディレクトリ（.agents/skills/ ミラー）	team-skills
ディレクトリ構成	.adlc/ ツリー	workspace --init（このスキル）

監査モード（デフォルト）では、このスキルは .adlc/ の内容を作成または変更しません。次の確認のみを行います。

1. 親に .adlc/ があることを確認します（ない場合は警告します）。
2. 各子リポジトリに独自の .adlc/ があるかを確認します（情報提供のみ）。

安全性

• --init は安全です：ディレクトリを作成し、.gitignore に不足しているルールを報告するだけです。既存の内容を上書きすることはありません。
• .gitignore の変更は追加のみです：不足しているルールだけを追加し、既存のルールを削除することはありません。
• デフォルトでは読み取り専用です：/workspace と /workspace --status は変更を加えません。
• --link には親ツリーがクリーンであることが必要です：子リポジトリの外に未コミットの変更がある場合、処理を中止します。
• --force は、子ディレクトリを親の Git インデックスから削除（git rm --cached）してから、サブモジュールとして再追加します。作業ツリーがクリーンである必要があります。
• 冪等性があります：すでに登録済みのサブモジュール、すでに無視対象のリポジトリ、すでに作成済みのディレクトリは、再実行時にスキップされます。
• リモートの origin がない子リポジトリはエラーとして報告され、--link の実行中はスキップされます。
• --dry-run は、実行せずにすべての変更をプレビューします。

よくある誤った正当化

誤った正当化	なぜ誤りなのか	代わりに行うこと
「.adlc/ を手動で mkdir すればよい」	完全なディレクトリツリーと .gitignore の規約が反映されません	--init を実行して完全に初期化します
「リポジトリの一覧を明示するために workspace.yml を追加しよう」	設定の負担が増えます。自動検出のほうが簡単で十分です	深さ 1 の検出を使用し、必要に応じて .gitignore で除外します
「.gitignore の設定は省略しよう」	ローカルのエージェント状態（.agents/、.opencode/）をコミットするリスクがあります	--init に規約を設定させます
「子リポジトリにも .adlc/ を作成しよう」	単一の信頼できる情報源というモデルから外れます	.adlc/ は親にのみ置き、子は親を参照します
「--link のクリーンツリーチェックは省略しよう」	親の未コミット変更を失うリスクがあります	ツリーがクリーンであることを必須とし、先にコミットまたはスタッシュするようユーザーに伝えます
「サブモジュールではなくワークツリーを使おう」	ワークツリーは機能の分離用であり、複数リポジトリの連携用ではありません	追跡対象の複数リポジトリをリンクするにはサブモジュールを使用します
「すべてにサブモジュールではなく --ignore-only を使おう」	ワークスペース連携のメリットが失われます	追跡対象のリポジトリには --link を使い、独立したプロジェクトに限って --ignore-only を使います

危険な兆候

• 親の作業ツリーがクリーンか確認せずに --link を実行する。
• 子リポジトリの外に未コミットの変更がある親で --force を実行する。
• 子リポジトリに .adlc/ の内容を作成する（単一の情報源は親です）。
• workspace.yml またはレジストリファイルを追加する（規約のみで、設定はありません）。
• 検出対象に .specify を再度含める。スクリプトでは明示的に除外されており（Discovery Rules を参照）、この除外は意図的なものです。
• --link の実行中に子リポジトリの内容を変更する（変更されるのは親のインデックスのみです）。
• ローカルのエージェントディレクトリがあるのに .gitignore の設定を省略する。

検証

• 親リポジトリが Git リポジトリである。
• --init がサブディレクトリ（product/、drafts/、drafts/{pdr,adr,cdr,skills,evals}/）を含む .adlc/ を作成する。
• --init が .gitignore に不足しているルールを報告する（追加のみで、削除はしない）。
• --init が冪等である（2 回目の実行では、作成されたディレクトリが 0 と報告される）。
• 親の .adlc/ が存在する（監査モードでは、ない場合に警告する）。
• 子リポジトリが深さ 1 で検出される（node_modules、.venv などは除く）。
• --link は、親の作業ツリーがクリーンな場合にのみ実行される。
• すでに登録済みのサブモジュールはスキップされる（冪等）。
• リモート origin がない子リポジトリはエラーとして報告される。
• --status は、子リポジトリごとにブランチ、変更状態、未プッシュ数、SHA の差異、.adlc の有無を報告する。
• --ignore-only は、リポジトリを .gitignore に追加し、親のインデックスから削除する。
• --dry-run はファイルを変更しない。
• JSON 出力が、init モードと audit モードの両方で Output Contract スキーマに準拠する。

既存のスキルとの連携

スキル	関係
product-specify	--init 後に親の .adlc/drafts/pdr/ に PDR のドラフトを作成します
architect-specify	--init 後に親の .adlc/drafts/adr/ に ADR のドラフトを作成します
team-levelup	--init 後に CDR のドラフトを作成します（team-ai-directives の adlc ブランチに公開されます）
team-boot	セッション開始時に親の .adlc コンテキストを読み込みます
team-setup	エージェントのディレクトリ（.agents/、.opencode/）を設定します — --init を補完します

12-Factor との整合性

Factor XI（ディレクティブをコードとして扱う）— 共有の決定事項を親に置き、 実装リポジトリをサブモジュールとしてリンクするか、慣例に従って無視する、バージョン管理されたマルチリポジトリの ワークスペースを確立します。