/umbrella

version: 1.0.0
description: >
  Create and manage umbrella workspaces for multi-repo projects.
  Activate when the user wants to: create umbrella, umbrella init, wrap in umbrella,
  create workspace, setup multi-repo, migrate repos to umbrella, umbrella create,
  new workspace, restructure into umbrella, "wrap this repo", "create umbrella for these repos",
  "setup workspace with repos", "move repos into umbrella".
  Do NOT activate for: add a repo to existing umbrella (use sw:get), add a feature,
  add an increment, clone a repo (use sw:get).
triggers:
  - "create umbrella"
  - "umbrella init"
  - "wrap in umbrella"
  - "create workspace"
  - "setup multi-repo"
  - "migrate repos"
  - "new workspace"
  - "restructure into umbrella"
  - "wrap this repo"
negative_triggers:
  - "add a repo"
  - "clone a repo"
  - "add a feature"
  - "create increment"

sw:umbrella — Create & Manage Umbrella Workspaces

Automates the creation of SpecWeave umbrella workspaces for multi-repo projects. Handles directory structure, repo cloning/migration, symlinks, `.env` consolidation, and SpecWeave initialization in a single flow.

Modes

| Mode | Use Case | |------|----------| | **init** | Create a new umbrella from scratch with remote and/or local repos | | **wrap** | Wrap an existing local repo (or set of repos) into a new umbrella |

Detect mode from context:

• User provides repo URLs or org/repo references → **init**
• User is in a repo and says "wrap" or "restructure" → **wrap**
• Ambiguous → ask which mode

---

Mode: init

Create a new umbrella workspace from scratch.

Step 1: Gather inputs

Extract from the user's message or ask:

| Input | Required | Default | |-------|----------|---------| | Umbrella name | Yes | — | | Target directory | No | `~/Projects/{name}` | | Repos to include | Yes | — |

**Repo source formats** (same as `sw:get`):

• GitHub shorthand: `owner/repo`
• Full URL: `https://github.com/org/repo`
• SSH: `git@github.com:org/repo`
• Local path: `~/Projects/my-repo` or `./my-repo`
• Mixed: any combination of the above

For local paths, also ask:

• Custom local name? (e.g., clone `owner/repo-long-name` as `repo`)

Step 2: Create umbrella root

TARGET="${HOME}/Projects/${NAME}"
mkdir -p "${TARGET}"
cd "${TARGET}"

**Guard**: If directory already exists and contains `.specweave/`, warn and ask whether to add repos to existing umbrella (delegates to `sw:get`) or abort.

Step 3: Initialize SpecWeave

specweave init "${NAME}"

This creates `.specweave/`, `config.json`, `CLAUDE.md`, `AGENTS.md`.

**Guard**: If `.specweave/config.json` already exists, skip this step.

Step 4: Add repos

**For each remote repo:**

specweave get <source> [--prefix PREFIX]

`specweave get` handles: clone into `repositories/{org}/{repo}/`, register in config.json, run `specweave init` in the repo.

**For each local repo:**

Local repos need special handling — `specweave get` expects a URL, not a local move.

# 1. Detect org/repo from git remote
REMOTE_URL=$(git -C "${LOCAL_PATH}" remote get-url origin 2>/dev/null)
# Parse org and repo name from URL (handle HTTPS, SSH, GitHub shorthand)
# Example: git@github.com:antonoly/claude-code-anymodel.git → org=antonoly, repo=claude-code-anymodel

# 2. Allow custom local name (user may want 'claude-code' instead of 'claude-code-anymodel')
REPO_DIR="${CUSTOM_NAME:-${REPO_NAME}}"

# 3. Create target directory
mkdir -p "${TARGET}/repositories/${ORG}"

# 4. Move repo (REQUIRES USER CONFIRMATION — destructive operation)
mv "${LOCAL_PATH}" "${TARGET}/repositories/${ORG}/${REPO_DIR}"

# 5. Create symlink at original location for session compatibility
ln -s "${TARGET}/repositories/${ORG}/${REPO_DIR}" "${LOCAL_PATH}"

# 6. Register in config.json
# Read current config, add to umbrella.childRepos array

**Registration** — after moving a local repo, add it to `.specweave/config.json`:

{
  "umbrella": {
    "childRepos": [
      {
        "id": "{repo-dir}",
        "path": "repositories/{org}/{repo-dir}",
        "name": "{repo-dir}",
        "prefix": "{FIRST_3_UPPERCASE}",
        "githubUrl": "{remote-url}"
      }
    ]
  }
}

Use `jq` to merge into existing config:

jq --arg id "${REPO_DIR}" \
   --arg path "repositories/${ORG}/${REPO_DIR}" \
   --arg name "${REPO_DIR}" \
   --arg prefix "${PREFIX}" \
   --arg url "${REMOTE_URL}" \
   '.umbrella.childRepos += [{"id": $id, "path": $path, "name": $name, "prefix": $prefix, "githubUrl": $url}]' \
   .specweave/config.json > .specweave/config.tmp && mv .specweave/config.tmp .specweave/config.json

Step 5: Consolidate .env files

Scan all repos for `.env` files and merge unique keys into umbrella root:

# 1. Find all .env files in repos (never display values)
ENV_FILES=$(find repositories -maxdepth 3 -name ".env" -not -path "*/node_modules/*" 2>/dev/null)

if [ -n "${ENV_FILES}" ]; then
  echo "Found .env files:"
  for f in ${ENV_FILES}; do
    echo "  ${f} ($(grep -c '=' "${f}" 2>/dev/null || echo 0) variables)"
  done

  # 2. Merge unique keys (preserving first occurrence of each key)
  # NEVER display values — only key names and counts
  for f in ${ENV_FILES}; do
    while IFS= read -r line; do
      KEY=$(echo "${line}" | cut -d'=' -f1)
      if [ -n "${KEY}" ] && ! grep -q "^${KEY}=" "${TARGET}/.env" 2>/dev/null; then
        echo "${line}" >> "${TARGET}/.env"
      fi
    done < "${f}"
  done

  echo "Consolidated $(grep -c '=' "${TARGET}/.env" 2>/dev/null || echo 0) variables into umbrella .env"
fi

**Guard**: If umbrella `.env` already exists, only add NEW keys (don't overwrite existing).

Step 6: Track symlinks

Write a manifest for future cleanup/reference:

# Create or update symlink manifest
cat > .specweave/state/symlinks.json << EOF
{
  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "symlinks": [
    {
      "target": "${TARGET}/repositories/${ORG}/${REPO_DIR}",
      "link": "${LOCAL_PATH}",