/workspace

name: workspace
description: Dynamic multi-repo and monorepo awareness for Claude Code. Analyze workspace topology, track API contracts, and maintain cross-repo context.
when-to-use: When working across multiple repos or in a monorepo with shared dependencies
user-invocable: true
effort: high

Workspace Analysis Skill

> Dynamic multi-repo and monorepo awareness for Claude Code. Analyze workspace topology, track API contracts, and maintain cross-repo context.

The Problem

When you have separate frontend/backend repos (or monorepo with multiple apps), Claude Code operates in isolation. It doesn't know:

• API contracts between modules/repos
• Shared types and interfaces
• Full system architecture
• Cross-repo dependencies
• What changed in other parts of the system

This leads to:

• Duplicate type definitions
• API contract mismatches
• Breaking changes not caught until runtime
• Claude reimplementing things that exist elsewhere

---

Solution: Dynamic Workspace Analysis

Instead of static manifests that get stale, Claude dynamically analyzes the workspace and generates context artifacts that stay fresh through hooks.

┌─────────────────────────────────────────────────────────────────┐
│  WORKSPACE ANALYSIS SYSTEM                                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  /analyze-workspace (Full Analysis - ~2 min)                     │
│  ├── Topology discovery (monorepo vs multi-repo)                │
│  ├── Dependency graph (who calls whom)                          │
│  ├── Contract extraction (OpenAPI, GraphQL, types)              │
│  └── Key file identification (what to load when)                │
│                                                                  │
│  /sync-contracts (Incremental - ~15 sec)                         │
│  ├── Check contract source files for changes                    │
│  ├── Update CONTRACTS.md with diffs                             │
│  └── Validate consistency                                       │
│                                                                  │
│  Hooks (Automatic)                                               │
│  ├── Session start: Staleness advisory (~5 sec)                 │
│  ├── Post-commit: Auto-sync if contracts changed (~15 sec)      │
│  └── Pre-push: Validation gate (~10 sec)                        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

Workspace Classification

Detection Patterns

| Type | Indicators | File Access | |------|------------|-------------| | **Monorepo** | pnpm-workspace.yaml, nx.json, turbo.json, lerna.json | Direct (same tree) | | **Multi-repo** | Sibling directories with separate .git | Via symlinks or paths | | **Hybrid** | Monorepo + external repo dependencies | Mixed | | **Single** | One app, no workspace config | N/A (use existing-repo) |

Monorepo Detection

# Check for monorepo indicators
ls package.json pnpm-workspace.yaml lerna.json nx.json turbo.json 2>/dev/null
ls apps/ packages/ services/ libs/ modules/ 2>/dev/null

Multi-Repo Detection

# Check sibling directories for related repos
ls -la ../*.git 2>/dev/null
cat ../*/.git/config 2>/dev/null | grep "url"

# Look for naming patterns
ls .. | grep -E "(frontend|backend|api|web|shared|common)"

Polyglot Detection

# Find all package manifests
find . -maxdepth 4 -name "package.json" -o -name "pyproject.toml" \
  -o -name "go.mod" -o -name "Cargo.toml" -o -name "pom.xml" \
  -o -name "build.gradle" -o -name "Gemfile"

---

Analysis Protocol

Phase 1: Topology Discovery (~30 seconds)

Determine workspace structure:

## Discovery Checklist

1. [ ] Identify workspace root
2. [ ] Classify workspace type (monorepo/multi-repo/hybrid/single)
3. [ ] List all modules/apps/packages
4. [ ] Detect tech stack per module
5. [ ] Identify entry points per module

**Module Detection Pattern:**

workspace-root/
├── apps/           → Application modules
│   ├── web/        → Frontend app
│   └── api/        → Backend app
├── packages/       → Shared packages
│   ├── ui/         → Component library
│   ├── types/      → Shared types
│   └── db/         → Database layer
├── services/       → Microservices
└── libs/           → Internal libraries

Phase 2: Dependency Graph (~60 seconds)

For each module, map:

**1. Internal Dependencies**

# TypeScript/JavaScript
grep -r "from ['\"]@" --include="*.ts" --include="*.tsx" | head -50
grep -r "workspace:" package.json

# Python
grep -r "from \." --include="*.py" | head -50

**2. API Relationships**

# Find API calls
grep -rE "fetch|axios|httpx|requests\." --include="*.ts" --include="*.py" | \
  grep -E "/api|localhost|127\.0\.0\.1" | head -30

**3. Database Connections**

# Find DB access patterns
grep -rE "prisma|drizzle|sqlalchemy|sequelize|typeorm" --include="*.ts" --include="*.py"

Phase 3: Contract Extraction (~45 seconds)

Identify and parse API contracts:

| Contract Type | Detection | Extraction | |---------------|-----------|------------| | **OpenAPI** | openapi.json, swagger.yaml, /docs endpoint | Parse paths, schemas | | **GraphQL** | schema.graphql, *.gql, /graphql endpoint | Parse types, queries, mutations | | **tRPC** | trpc router files, @trpc/* imports | Parse router definitions | | **Protobuf** | *.proto files | Parse services, messages | | **TypeScript** | Shared .d.ts, exported interfaces | Parse exported types | | **Pydantic** | schemas/, models/ with BaseModel | Parse model definitions | | **Zod** | schemas/ with z.object | Parse schema definitions |

**Contract Source Priority:**

1. Generated specs (openapi.json) - most accurate 2. Schema definitions (Pydantic, Zod) - source of truth 3. Type exports (TypeScript .d.ts) - consu