workspace

What this skill does

# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```markdown
## 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**
```bash
# 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**
```bash
# 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**
```bash
# 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) - consumer contracts
4. Inferred from code - last resort

### Phase 4: Key File Identification (~30 seconds)

Identify files Claude MUST know about for each context:

| Category | Detection Pattern | Token Priority |
|----------|-------------------|----------------|
| **Route definitions** | `**/routes/**`, `**/api/**`, `@app.get`, `@router` | HIGH |
| **Type definitions** | `**/types/**`, `*.d.ts`, `schemas/`, `models/` | HIGH |
| **Config** | `.env.example`, `config/`, `settings.py` | MEDIUM |
| **Entry points** | `main.ts`, `index.ts`, `app.py`, `server.py` | MEDIUM |
| **API clients** | `**/api/client*`, `**/lib/api*` | HIGH |
| **Database schema** | `schema/`, `migrations/`, `prisma/schema.prisma` | MEDIUM |
| **Tests** | `__tests__/`, `*_test.py`, `*.spec.ts` | LOW (on-demand) |

---

## Generated Artifacts

All artifacts go in `_project_specs/workspace/`:

```
_project_specs/workspace/
├── TOPOLOGY.md           # What modules exist, their roles
├── CONTRACTS.md          # API specs, shared types (summarized)
├── DEPENDENCY_GRAPH.md   # Who calls whom (visual + list)
├── KEY_FILES.md          # What to load for each context
├── CROSS_REPO_INDEX.md   # Capabilities across all modules
└── .contract-sources     # Files to monitor for changes
```

### TOPOLOGY.md Format

```markdown
# Workspace Topology

Generated: 2026-01-20T14:32:00Z
Analyzer: maggy/workspace-analysis
Workspace Type: Monorepo (Turborepo)

## Overview

```
┌─────────────────────────────────────────────────┐
│ apps/web (Next.js) ←→ apps/api (FastAPI)        │
│      ↓                      ↓                   │
│ packages/shared-types ← packages/db             │
└─────────────────────────────────────────────────┘
```

## Modules

### apps/web
- **Path**: /apps/web
- **Tech**: Next.js 14, TypeScript, TailwindCSS
- **Role**: Customer-facing dashboard
- **Consumes**: apps/api (REST), packages/shared-types
- **Entry**: src/app/layout.tsx
- **Key files**:
  - `src/lib/api/client.ts` - API client (187 lines)
  - `src/types/` - Frontend-specific types (12 files)
- **Token estimate**: ~15K (full), ~4K (summarized)

### apps/api
- **Path**: /apps/api
- **Tech**: FastAPI, Python 3.12, SQLAlchemy
- **Role**: REST API, business logic
- **Exposes**: OpenAPI at /docs (47 endpoints)
- **Consumes**: packages/db
- **E