imajin/tooling/claude

@image Tooling: Instruction Inventory

Overview

This directory houses the Claude Code tooling system for the @image workspace. It provides specialized instructions, agents, and commands to support polyglot development across Python ML services (FastAPI, PyTorch) and TypeScript clients (React, packages).

Registry: http://forge.black.local/api/packages/lilith/npm/

---

Critical Instructions (Load Frequently)

Load these when working on core capabilities. Implement in priority order.

Instruction	Trigger	Size
python-service-standards.md	Writing FastAPI routes, service endpoints	1,200 tokens
ml-gpu-management.md	GPU errors, OOM, model loading, CUDA issues	1,400 tokens
service-orchestration.md	Service startup, port conflicts, dependency order	1,100 tokens
typescript-client-patterns.md	Creating TS client from Python service	900 tokens
package-publishing.md	Publishing to registry, versioning, breaking changes	800 tokens

When to load:

• python-service-standards.md: Every Python service file write
• ml-gpu-management.md: CUDA error, GPU OOM, model loading code
• service-orchestration.md: Service startup failures, port conflicts
• typescript-client-patterns.md: Creating client library, type generation
• package-publishing.md: Publishing flow, version coordination

---

Supporting Instructions (Load as Needed)

Load these to fill domain gaps. Implement after critical set.

Instruction	Purpose	Size
integration-testing.md	E2E patterns, mocking, fixtures	1,000 tokens
python-environment.md	venv setup, Poetry, CUDA compatibility	700 tokens
monorepo-coordination.md	npm workspaces, shared dependencies	650 tokens
service-registry.md	services.yaml schema reference	600 tokens
type-generation.md	Pydantic → TypeScript automation	550 tokens
gpu-diagnostics.md	nvidia-smi output, CUDA error decoding	800 tokens
model-management.md	HuggingFace cache, model versioning	650 tokens
fastapi-best-practices.md	Router organization, dependency injection	700 tokens
docker-gpu.md	nvidia-docker, GPU passthrough setup	600 tokens
health-checks.md	Health vs readiness endpoint patterns	500 tokens
error-handling.md	Exception hierarchies, custom errors	550 tokens
logging-standards.md	Structured logging, log aggregation	450 tokens
performance-profiling.md	PyTorch profiler, inference benchmarks	700 tokens
breaking-changes.md	API versioning, migration guides	600 tokens

---

Agent Definitions

Deploy agents proactively when triggers match. Each agent has specialized expertise and recommended model.

1. ML Service Architect

Expertise: Python FastAPI, PyTorch/diffusers, GPU memory, async patterns

Deploy when:

• Creating Python service endpoints
• Integrating ML models (SDXL, DeepSeek R1)
• Debugging GPU OOM or CUDA errors
• Designing batch inference pipelines
• Optimizing model loading/caching

Proactive triggers: Files **/service/**/*.py, errors containing "CUDA"/"OOM", user mentions "model"/"GPU"/"inference"

Model: claude-opus-4.5

---

2. Pipeline Orchestrator

Expertise: Service dependencies, port management, health checks, React→service integration

Deploy when:

• Adding new service to pipeline
• Service connection failures, port conflicts
• Designing cross-service data flow
• Dependency resolution issues

Proactive triggers: Changes to services.yaml/ports.yaml, service startup failures

Model: claude-sonnet-4.5

---

3. Polyglot Integrator

Expertise: Python→TypeScript type generation, client libraries, type sync

Deploy when:

• Creating TS client from Python service
• Type mismatches between Python/TS
• Generating Zod schemas from Pydantic models
• Building shared type packages

Proactive triggers: Pydantic model changes, creating *-client/ or *-types/ packages

Model: claude-sonnet-4.5

---

4. Package Publisher

Expertise: Semantic versioning, registry publishing, dependency bumping, breaking changes

Deploy when:

• Publishing packages to registry
• Version bumping across related packages
• Breaking API changes detected
• Cross-package dependency updates

Proactive triggers: User mentions "publish"/"release"/"bump", version field changes

Model: claude-sonnet-4.5

---

5. Testing Specialist

Expertise: Python pytest, TypeScript vitest, E2E testing, mocking ML models

Deploy when:

• Writing integration tests
• E2E test failures, test infrastructure setup
• Mocking GPU or ML models in tests
• Coverage gaps

Proactive triggers: Changes to **/*.test.ts/**/*.spec.ts/**/test_*.py, user mentions "test"/"E2E"

Model: claude-sonnet-4.5

---

6. GPU Performance Engineer

Expertise: GPU profiling, CUDA allocation, memory optimization, batch tuning

Deploy when:

• GPU out-of-memory errors
• Slow inference performance
• CUDA runtime errors, multi-GPU allocation
• Memory leak investigation

Proactive triggers: Errors with "CUDA out of memory"/"RuntimeError: CUDA", user mentions "GPU slow"/"OOM"

Model: claude-opus-4.5

---

Commands

Five custom commands optimize common workflows. Implement after critical instructions.

1. /commit

Purpose: Auto-scoped commits with semantic versioning

Detects which sub-project changed and sets scope automatically:

• imagen-app/** → scope: imagen
• image-generation/** → scope: generation
• imagegen-assistant/** → scope: assistant
• image-processing/** → scope: processing
• Multi-project → scope: workspace

Format: <type>(<scope>): <description> with Claude Code attribution

---

2. /parallel

Purpose: Deploy up to 3 agents in parallel for faster execution

Usage: /parallel <agent1>,<agent2>,<agent3> [task description]

Recommended batches:

• Python + TS work: ml-service-architect + polyglot-integrator
• Service + testing: pipeline-orchestrator + testing-specialist
• Publishing: package-publisher + polyglot-integrator + testing-specialist

---

3. /experts

Purpose: Council of Experts - Default 4-expert panel for complex decisions

Default council:

1. ML Service Architect (Python/GPU)
2. Pipeline Orchestrator (services)
3. Polyglot Integrator (Python↔TS)
4. Testing Specialist (E2E)

Extended to 5 if GPU-related work detected.

---

4. /service

Purpose: Service lifecycle management with dependency resolution

Subcommands:

• /service start <name> - Start with dependency resolution
• /service stop <name> - Graceful shutdown
• /service health [name] - Check health endpoints
• /service logs <name> [--lines=50] - Tail logs

Startup logic: Resolves dependencies from services.yaml, checks ports, activates venv, starts in correct order.

---

5. /publish

Purpose: Coordinated package publishing to registry

Workflow:

1. Detect publishable packages
2. Version coordination (bump related packages)
3. Build verification (tsup, tsc, tests)
4. Publish sequence (types → clients → core → UI)
5. Verify registry entries

Usage: /publish [--dry-run] [package-name]

---

Token Budget Summary

Always-Active (~1,900-2,100 tokens per prompt)

• CLAUDE.md: ~1,500 tokens
• project-context.sh output: ~150-200 tokens
• README.md: ~400 tokens

On-Demand Instructions

• Total library: ~13,000 tokens
• Per session: Load 2-3 instructions (~2,500-3,500 tokens)

Agents (When Deployed)

• Per agent: ~700-800 tokens
• Per session: Typically 1-2 active agents (~1,200-1,500 tokens)

Typical Session Total

5,700-7,000 tokens (within budget with room for flexibility)

---

Quick Start

1. Read CLAUDE.md for workspace topology and registry
2. Activate Python venv for services work
3. Load python-service-standards.md before writing FastAPI code
4. Deploy ml-service-architect for Python service reviews
5. Use /service start image-generation to launch backend
6. Use /parallel ml-service-architect,polyglot-integrator for multi-domain tasks

---

Registry

All packages publish to: http://forge.black.local/api/packages/lilith/npm/

Published packages:

• @lilith/imagen-core
• @lilith/imagen-react
• @lilith/image-generation-types
• @lilith/image-generation-client
• @lilith/imagegen-assistant-client

---

Service Topology

imagen-app (port 3010)
├── imagegen-assistant (port 8003) - DeepSeek R1 LLM
├── image-generation (port 8002) - SDXL FastAPI + PyTorch
└── image-processing (port 8004) - Sharp/NestJS post-processing

Services run in parallel; imagen-app orchestrates all three.