IOTA SDK - Claude Code Orchestrator Configuration

Design Philosophy

iota-sdk is a general purpose ERP building engine/solution. When designing anything inside iota-sdk:

• Make it extensible, generalizable, and customizable
• Prefer interfaces over concrete structs at boundaries
• Apply dependency inversion and inject interfaces
• Keep domain and services decoupled from infrastructure details

Quick Decision Tree

Task Classification: choose the smallest useful workflow.

• Bounded fix with a clear owner: work directly and run focused checks.
• Uncertain diagnosis or substantial independent parts: delegate scoped investigation or implementation, with one owner for each dependent change.
• Review: use auditor for material API, data, migration, release, or other high-risk changes when an independent pass adds value.

Choose debugger for investigation, editor for implementation, and auditor for independent review as needed. A change spanning a repository and template still has one owner.

Build/Test Commands

# After Go changes
go vet ./...

# After template/css changes
templ generate && just css

# Testing
just test -v                       # All tests (verbose)
go test -v ./path -run TestName    # Single test

# Other
just check tr                      # Validate translations
just db migrate up                 # Apply migrations

Never run go build - use go vet instead.

NPM @iota-uz/sdk is built and released from this repository together with the matching Go tag. Public JavaScript APIs are limited to the bounded exports documented in docs/client-host-release-train.md.

Module Architecture (DDD)

modules/{module}/
├── domain/aggregates/{entity}/    # Entity + events + repository interface
├── infrastructure/persistence/    # DB models, mappers, repository impl
├── services/                      # Business logic orchestration
├── presentation/
│   ├── controllers/               # HTTP handlers + DTOs
│   ├── templates/pages/{entity}/  # list.templ, edit.templ, new.templ
│   ├── viewmodels/                # Presentation models
│   └── locales/                   # en.json, ru.json, uz.json
├── component.go                   # Component registration
├── links.go                       # Navigation
└── permissions/constants.go       # RBAC

Creating New Entities

1. Domain: modules/{m}/domain/aggregates/{entity}/ - entity, impl, events, repository interface
2. Infrastructure: infrastructure/persistence/{entity}_repository.go + models + mappers
3. Service: services/{entity}_service.go with NewEntityService(repo, eventPublisher) constructor
4. Presentation: controller + DTOs + viewmodel + mapper
5. Templates: templates/pages/{entity}/ - list.templ, edit.templ, new.templ
6. Localization: Add keys to en/ru/uz.json
7. Registration: Add to component.go, links.go
8. Verify: go vet ./... and templ generate && just css

Multi-Agent Orchestration

Workflow Rules:

• Identify the affected symbols, callers, and boundaries before choosing checks or delegating; a full go vet ./... is not a prerequisite to scope analysis.
• Divide work along seams, not evenly — an even split that cuts through a dependency costs more than it saves, because neither half can see the other
• Pass every agent the paths and symbols you already have, and keep the ones it returns. An agent starts with an empty context and re-derives the rest.
• Keep the number of agents proportional to independent work.

Critical coordination rule:

• Before agent completes: Agent must create tasks for ANY unfinished work (stubs, TODOs, partial implementations)
• After agents complete: Orchestrator must call TaskList and either implement remaining tasks or create new agents
• Never assume: Agents completed everything unless explicitly verified via TaskList

E2E Testing

For manual local browser sign-in, follow the Local browser sign-in for agents section in AGENTS.md.

Use the /e2e-testing skill for setup, running, and debugging E2E tests locally. Always reproduce and fix locally before pushing to CI.

just e2e dev      # Start E2E server (hot-reload)
just e2e run      # Interactive Playwright UI
just e2e ci       # Headless CI mode
cd e2e && npx playwright test tests/module/specific.spec.ts:LINE  # Single test by line

Technology Stack

• Backend: Go 1.24.10, IOTA SDK framework, GraphQL
• Database: PostgreSQL 13+ (multi-tenant with tenant_id)
• Frontend: HTMX + Alpine.js + Templ + Tailwind CSS
• Auth: Cookie-based sessions with RBAC

Core Rules

Task Management (NEVER leave unfinished work unmarked)

CRITICAL: Do NOT leave stubs, partial implementations, or TODO comments without creating tasks.

Prohibited patterns:

• // TODO: implement validation
• // FIXME: handle error case
• // This will be implemented later
• Function stubs with return nil, nil or panic("not implemented")
• Commented-out code awaiting completion
• Partial feature implementations without tracking

When you identify unfinished work, immediately use TaskCreate:

• subject: "Implement validation for user input"
• description: Full context, affected files (e.g., user_service.go:123), acceptance criteria
• activeForm: "Implementing validation for user input"

Common scenarios requiring TaskCreate:

• Feature partially implemented (stub functions, incomplete logic)
• Missing validation or error handling
• Tests not yet written
• Refactoring needed after POC
• Documentation updates required
• Edge cases not handled

Agent workflow: Before completing, agents MUST:

1. Search their changes for stubs/incomplete code
2. Create tasks for ALL unfinished work with file:line references
3. Return task IDs in completion message

Orchestrator workflow: After agents complete:

1. Call TaskList to verify all unfinished work is tracked
2. Implement tasks or assign to new agents
3. Show user final task list

Exception: Preserve existing TODO comments when editing legacy code (but never add new ones).

Other Rules

• Multi-tenant isolation: Always include tenant_id in WHERE clauses
• Error handling: Use pkg/serrors - serrors.Wrap(op, err)
• HTMX: Check htmx.IsHxRequest(r), use htmx.SetTrigger(w, "event", payload)
• Templ: Edit .templ sources, not generated *_templ.go files. Inspect generated diffs or compiler errors when validating a change, and exclude unrelated generator churn.

Child Module CLAUDE.md Files

• modules/bichat/CLAUDE.md - BiChat module specifics
• modules/bichat/agents/CLAUDE.md - Agent implementations
• pkg/bichat/CLAUDE.md - BiChat foundation framework
• pkg/lens/CLAUDE.md - Dashboard framework