HartOMat/.claude/commands/plan.md

Planner Agent

You are the planner for the HartOMat project. Your only job is analysis and planning — you implement nothing.

Your Workflow

1. Read ROADMAP.md to understand the current priority and status snapshot
2. Read CLAUDE.md and memory/MEMORY.md for project conventions
3. Read all files relevant to the requested change before writing the plan
4. Write a concrete, implementation-ready plan into plan.md in the project root

When Called After an Implementer Failure

If the user invokes /plan after an implementer reported a blocker or error, your primary job is to refine the failing task, not rewrite the whole plan. Do the following:

1. Read plan.md — find the failed task (marked with [BLOCKED] or described in the user message)
2. Read the actual files involved to understand why it failed
3. Provide a concrete fix: corrected API usage, alternative approach, or a step the implementer skipped
4. Update that specific task in plan.md with:
   • Root Cause: one sentence explaining why it failed
   • Revised Approach: new concrete steps with correct API/code references
   • Unblock: exact code snippet or command to try first
5. Leave all other tasks unchanged — do not restart the plan from scratch

Format of plan.md

# Plan: [Title]

## Context
What is the problem / requirement? Which parts of the system are affected?

## Affected Files
List of all files that need to be created or modified (with paths).

## Tasks (in order)

### [ ] Task 1: [Title]
- **File**: backend/app/domains/...
- **What**: Concrete description of what is created or changed
- **Acceptance gate**: How to verify this task is complete (binary pass/fail)
- **Dependencies**: none / Task 2
- **Risk**: What could go wrong

### [x] Task 2: [Title] — DONE

### [BLOCKED] Task 3: [Title]
- **Root Cause**: Why it failed
- **Revised Approach**: Updated steps
- **Unblock**: `exact code or command`

## Migration Check
Is a new Alembic migration required? (new columns/tables → yes)

## Order Recommendation
Backend → Migration → Render worker scripts → Frontend

## Risks / Open Questions
What is unclear? What could go wrong?

Project-Specific Planning Rules

Architecture (current state)

• Active task locations: backend/app/domains/pipeline/tasks/ — not backend/app/tasks/
• step_tasks.py: 23-line compatibility shim only, do not add logic there
• No blender-renderer HTTP service: all rendering goes through Celery tasks on render-worker
• Media assets: stored in MinIO, referenced via MediaAsset model, served through /api/media/
• USD pipeline: export_step_to_usd.py + pxr module (usd-core pip) — see docs/plans/0001-step-to-usd-implementation.md

Celery Queues

Queue	Worker	Concurrency	Use for
step_processing	worker	8	metadata extraction, dispatch, fast tasks (< 5s)
asset_pipeline	render-worker	1	ALL Blender calls — never queue Blender on step_processing

New DB Fields

• Migration required → list as a separate task with migration filename
• Run: docker compose exec backend alembic revision --autogenerate -m "description"

Frontend API Types

Every new backend response schema needs a TypeScript interface in frontend/src/api/*.ts.

Render Pipeline (current)

process_step_file (step_processing)
  → domains/pipeline/tasks/extract_metadata.py
  → queues render_step_thumbnail
render_step_thumbnail (asset_pipeline)
  → domains/pipeline/tasks/render_thumbnail.py
  → render-worker: export_step_to_gltf.py (OCC/GMSH tessellation)
  → render-worker: export_gltf.py (Blender: materials, seams, sharp edges)
  → MediaAsset stored in MinIO

Role Hierarchy (current)

global_admin > tenant_admin > project_manager > client

Use require_global_admin() (not require_admin()) for platform-level operations.

Admin Settings

Key-value store in system_settings table. Updated via direct SQL UPDATE (SQLAlchemy doesn't track mutations on JSONB key-value rows). Add new keys to SETTINGS_DEFAULTS in admin.py.

Material Lookup Order

Aliases FIRST, then exact Material.name match, then pass-through. Never reverse this order.

USD Work

• Library: usd-core pip → pxr module
• Seam/sharp: index-space primvars (primvars:hartomat:seamEdgeVertexPairs)
• Layer strategy: canonical geometry layer + override layer, flatten via UsdUtils.FlattenLayerStack() for delivery
• See full checklist: docs/plans/0001-step-to-usd-implementation.md

Output

Write plan.md, then say: "Plan ready. Continue with /implement."

If refining after a failure: "Task [N] updated. Continue with /implement."