/workspace

name: workspace
description: Use when coordinating a multi-repo workspace — init the .adlc/ structure, discover and link child repos as submodules, or audit workspace health (branch, dirty, unpushed, SHA drift).

workspace

Overview

A multi-repo workspace coordinator for shared team context. The parent repository holds shared decisions (PDRs, ADRs, CDRs) under `.adlc/`, created by `product-specify`, `architect-specify`, and `team-levelup`. Child implementation repositories are discovered at depth 1 and optionally linked as Git submodules so the entire workspace can be cloned with `git clone --recursive`.

No `workspace.yml`, no registry file. Pure convention:

• Parent repo = current working directory (must be a Git repo)
• Child repos = depth-1 subdirectories containing `.git/`
• Shared context = `.adlc/` in parent root

When to Use

• **First-time setup** (`--init`): Create `.adlc/` directory structure, configure `.gitignore` conventions, and optionally link child repos.
• **After `product-specify` or `architect-specify`** has created shared PDRs/ADRs in the parent repo and you have multiple implementation repos alongside.
• **When you've cloned new child repos** into the workspace and want to register them as submodules (`--link`) or ignore them (`--ignore-only`).
• **To audit workspace health**: dirty working trees, unpushed commits, SHA drift between parent submodule reference and child HEAD.
• **To verify child repos** can see the parent `.adlc/` shared context.

When NOT to Use `--init`

• **Workspace already initialized**: Use `/workspace --status` to audit instead.
• **Only auditing child repo state**: Use `/workspace` (read-only discovery + status).
• **Linking additional child repos after init**: Use `/workspace --link` directly.

User Input

$ARGUMENTS

Commands

| Command | Purpose | |---|---| | `/workspace --init` | Initialize: create `.adlc/` structure, configure `.gitignore`, discover child repos | | `/workspace` | Discover child repos, show summary status (read-only) | | `/workspace --link` | Convert child repos to Git submodules (requires clean parent tree) | | `/workspace --status` | Detailed audit: branch, dirty, unpushed, SHA drift, `.adlc` presence | | `/workspace --ignore-only` | Add child repos to `.gitignore` instead of creating submodules | | `/workspace --init --link` | Initialize + link child repos in one step | | `/workspace --init --ignore-only` | Initialize + add child repos to `.gitignore` | | `/workspace --dry-run` | Preview changes without executing (combine with `--init`, `--link`, `--ignore-only`) | | `/workspace --force` | Convert repos already tracked by parent index (requires clean tree) |

Execution

Init Mode (`--init`)

Run the init setup script to create `.adlc/` structure, check `.gitignore` conventions, and discover child repos:

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

# PowerShell
scripts/powershell/setup-workspace.ps1

**Init setup output** (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": "git@github.com:org/backend-api.git", "is_submodule": false, "is_tracked": false}
  ],
  "CHILD_COUNT": 1,
  "BRANCH": "main"
}

**Directories created**:

.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/

After init setup, if `--link` or `--ignore-only` is also specified, proceed to the corresponding action mode below.

Audit/Link Mode (default, `--link`, `--status`, `--ignore-only`)

Run the workspace coordinator script:

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

Parse the JSON output and present it to the user.

Output Contract

Init Mode Output

Emitted by `setup-workspace.sh --json` (see above).

Audit/Link Mode Output

Emitted by `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": "git@github.com: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": []
}

Init Phases

Phase 1: `.adlc/` Structure Creation

The setup script creates the `.adlc/` directory tree if it doesn't exist (`product/`, `drafts/`, and the per-family draft subdirectories — the shared layout scopes `.adlc/` to machine pipeline state). This is the shared context directory where other skills write drafts and pipeline state; published decision records and compiled deliverables live under `docs/adlc/`.

**Idempotent**: already-existing directories are not recreated.

Phase 2: `.gitignore` Configuration

The setup script checks `.gitignore` for workspace conventions and reports missing rules.

**Allowlist model** — `.adlc/` is no longer ignored wholesale. Machine pipeline state is ignored via `.adlc/*` with tracked exceptions re-included; published content under `docs/adlc/` is always tracked:

# agent-install surface (regenerated)
.agents/
.opencode/
.claude/
.cursor/
.co