workspace-init

Description

Initialize a new workspace configuration for managing multiple related projects/repositories.

Arguments

• --from <url> - Import workspace configuration from a gist or repository URL

Instructions

When the user wants to create a new workspace, follow this interactive process:

Step 0: Check for GitHub MCP Integration

Before starting, check if GitHub MCP tools are available (e.g., mcp__github__list_repos, mcp__github__search_repositories).

If available:

• Offer to fetch the user's repositories automatically
• Show a list of their repos to select from
• This saves time entering repo URLs manually

Example:

I noticed you have GitHub MCP configured. Would you like me to:
1. Fetch your repositories from GitHub to help set up the workspace
2. Enter repository information manually

Step 1: Gather Basic Information

Ask the user for:

1. Workspace name - A short identifier (e.g., "acme", "mycompany")
2. Company/Project name - Full display name (e.g., "Acme Corp")
3. Description - Brief description of the workspace

Step 2: Add Projects

For each project, collect information with clear path display:

1. Name - Project identifier

   • If using GitHub MCP: default to the actual repo name (e.g., "neosophia-amap-api")
   • User can optionally provide a shorter alias
   • Do NOT substitute with generic names like "api" or "admin"

2. Repository URL - Git clone URL

   • If GitHub MCP is available, offer to select from their repos
   • Otherwise ask for the URL directly

3. Local path - Where the project lives locally

   IMPORTANT: Auto-detect existing repos first!

   Before asking where to clone, search for existing local folders that match the repo name:

   • Check current directory and common locations (~/Sites, ~/work, ~/projects, ~/code, ~/dev)
   • Use find or ls to locate folders matching the repo name
   • If repo is neosophia-amap-api, look for folders named neosophia-amap-api

   If found: Auto-use that path. Don't ask the user.

   ✓ Found neosophia-amap-api at /Users/patricio/Sites/neosophia-amap-api
   

   If NOT found: Then ask where to clone it.

   Where should neosophia-amap-api be cloned?
   
   Suggested: /Users/patricio/Sites/neosophia-amap-api
   

   This saves time when users already have repos cloned locally.

4. Stack - Technologies used (e.g., "Node, Express, PostgreSQL")

5. Port - Development server port (if applicable)

After each project, show a summary:

Project added:
  Name: api
  Repo: git@github.com:acme/api.git
  Path: /Users/patricio/Sites/acme/api
  Stack: Node, Express
  Port: 3000

Add another project? (y/n)

Step 3: Define Relationships (Optional)

Ask if any projects depend on others. Format:

• frontend -> api means frontend calls the api

Step 4: Add Documentation Links (Optional)

Collect any relevant documentation URLs:

• API docs
• Design files (Figma, etc.)
• Wiki/Notion
• Slack channels

Step 5: Define Commands (Optional)

Ask for common workspace-level commands:

• start-all - Start all services
• stop-all - Stop all services
• test-all - Run all tests

Step 6: Generate Configuration

Create the workspace directory at ~/.claude/workspaces/<name>/ and generate the WORKSPACE.md file.

Step 7: Offer to Clone

Ask if the user wants to clone all repositories now using /workspaces:clone all.

Import from URL

If --from <url> is provided:

1. Fetch the content from the URL
2. Parse it as WORKSPACE.md format
3. Create the workspace with that configuration

GitHub MCP Integration Details

If GitHub MCP is available, you can use these tools:

1. List user's repos: Use mcp__github__list_repos to show available repositories
2. Search repos: Use mcp__github__search_repositories to find specific repos
3. Get repo details: Fetch clone URLs, descriptions, and default branches

IMPORTANT: When showing repos from GitHub, display the actual repository names exactly as they appear in GitHub. Do NOT substitute with generic names like "api", "landing", "web", "admin".

When listing repos, show them with their real names:

Your GitHub repositories:
  1. neosophia-amap-api - Backend API for AMAP
  2. neosophia-amap-admin - Admin dashboard for AMAP
  3. neosophia-amap-landing - Landing page
  4. neosophia-experts-dashboard - Experts dashboard
  5. neosophia-screen-api - Screen API service
  6. arkvault - Vault application
  7. arkscan - Block explorer

Select repos to add (comma-separated numbers, e.g., "1,2,4"):

When user selects repos:

• Project name defaults to the actual repo name (e.g., neosophia-amap-api, not api)
• User can optionally provide a shorter alias
• Clone URL comes directly from the GitHub repo data
• Auto-detect local paths: Search for existing folders matching each repo name before asking

Example auto-detection flow:

Selected: neosophia-amap-api, neosophia-amap-landing, neosophia-amap-admin

Scanning for existing repos...
✓ neosophia-amap-api found at /Users/patricio/Sites/neosophia-amap-api
✓ neosophia-amap-landing found at /Users/patricio/Sites/neosophia-amap-landing
✗ neosophia-amap-admin not found locally

Where should neosophia-amap-admin be cloned?
Suggested: /Users/patricio/Sites/neosophia-amap-admin

Example Output

After successful initialization:

✓ Workspace 'neosophia' created at ~/.claude/workspaces/neosophia/

Projects configured:
  • neosophia-amap-api
    Path: /Users/patricio/Sites/neosophia-amap-api (existing)
    Port: 3000
  • neosophia-amap-landing
    Path: /Users/patricio/Sites/neosophia-amap-landing (existing)
    Port: 3001
  • neosophia-amap-admin
    Path: /Users/patricio/Sites/neosophia-amap-admin (to clone)
    Port: 3002

Run '/workspaces:clone all' to clone missing repositories.