| name | sonamu |
| description | Sonamu TypeScript full-stack framework development guide. Entity, Model, API, testing, and frontend integration. Use when developing with Sonamu framework. |
Sonamu Framework Skills
Claude Code skill for developing projects with the Sonamu framework.
CRITICAL: Ask one question at a time
MUST ask questions one at a time. NEVER overwhelm users with multiple questions.
MUST DO
- One question → wait for user response → next question
- Keep questions concise
- Present choices clearly when options are available
NEVER DO
- List multiple questions at once
- Ask questions alongside long explanations
- Output a checklist of confirmation items all at once
Development Flow
PHASE 0: Project creation and initial setup (create project → identify domains → auth generate → Users sequence setup)
PHASE 1: Domain logic documentation (write contract/{domain}/*.contract.md per domain → user confirmation)
PHASE 2: Entity design (design with user confirmation)
PHASE 3: Entity creation and migration (entity.json + migration + cone + scaffolding)
PHASE 4: Testing and API implementation (contract → Claim → AC → implement, repeat)
PHASE 5: Fixture generation (generate with LLM after user approval)
PHASE 6: Frontend development (proceed in batches with user confirmation)
Full details: see .claude/workflow/project_init.md
Starting Point Determination
Begin from the PHASE that matches the user's instruction. Do not always start from PHASE 0.
| User instruction | Starting PHASE | Prerequisites to verify |
|---|
| "Create a new project" | PHASE 0 | — |
| "Write contract" / "Analyze domain" | PHASE 1 | Domain list identified |
| "Add entity" / "Create entity" | PHASE 2 | Project exists, dev server running, read contract/*/.contract.md, PHASE 1 complete |
| "Write tests" / "Implement API" | PHASE 4 | entity.json exists, migration complete, scaffolding complete |
| "Generate fixtures" | PHASE 5 | Tests passing, cone.note exists |
| "Develop frontend" | PHASE 6 | API implementation complete, contract/*/.contract.md reviewed |
Mid-entry rules:
- If
contract/**/*.contract.md and skills/project/architecture.md exist, read them first.
- Verify prerequisites for the target PHASE.
- If prerequisites are not met, inform the user and begin from the required step.
- Within a PHASE, follow the numbered steps in
.claude/workflow/project_init.md in order. Do not skip any step or merge steps on your own judgment.
Project Document System
CRITICAL: Read these before starting any task
Before starting any project task, always read the following documents.
contract/
└── {domain}/
└── {domain}.contract.md # PHASE 1: domain rules + decision rationale (permanent; update alongside code changes)
.claude/skills/project/
└── architecture.md # entity design + system architecture
tmp/claims/ # in-progress Claim YAML (discard after completion)
Code is the ground truth. *.contract.md records the rationale behind code decisions — it is not a spec that precedes the code. When code and *.contract.md conflict, the code takes precedence.
Domain *.contract.md
Documents domain rules in a cohesive form and captures decision rationale that cannot be inferred from code alone.
# {Domain} Business Logic
## Rules
- Refunds allowed only within 7 days of payment [Rationale: PG provider policy]
- Order status transitions: pending → confirmed → shipped → completed
## Workflow
1. ...
Two development paths:
- New: write
*.contract.md → Claim → AC (test name) → implement (TDD)
- Change: modify code → register Claim → verify/update
*.contract.md (record change rationale)
Update rules:
- When code changes, check affected domain rules and update
*.contract.md together
- Record the reason and decision rationale — this keeps
*.contract.md alive
architecture.md
When: designing entities or discussing system architecture
Content: entity structure and relationships, database schema, system component structure
Safe after compacting
Documents are persisted as files, so project context is preserved even when the conversation is compacted.
Skills List
| Skill | File | Purpose |
|---|
| CDD (AC+Claim-based development) | cdd.md | *.contract.md (domain rules), AC (test names), Claim (work instructions) — 3-artifact system |
| Project creation | create-sonamu.md | create-sonamu CLI options |
| Project initialization | project-init.md | Project creation flow and conversation guide |
| Project configuration | config.md | .env, sonamu.config.ts settings |
| Database | database.md | DB setup, port conflict resolution, 3-Tier structure |
| Entity validation | entity-validation-checklist.md | Step-by-step entity creation checklist |
| Entity basics | entity-basic.md | Entity JSON structure, field types |
| Entity relations | entity-relations.md | BelongsToOne, HasMany, ManyToMany, FK code patterns |
| Subset | subset.md | Response field scope definition |
| Model | model.md | BaseModelClass, CRUD patterns |
| API | api.md | @api decorator |
| Puri | puri.md | SQL query builder |
| i18n | i18n.md | Internationalization, SD functions |
| Upsert | upsert.md | Batch saving of relation data |
| Testing | testing.md | Vitest tests (test/testAs), fixture generation tips |
| DevRunner | testing-devrunner.md | sonamu test execution, HMR integration, parallel tests, sonamu.config.ts test settings |
| Naite | naite.md | Naite.t()/get() tracing system, chaining filters, trace CLI output |
| Cone | cone.md | Cone metadata generation and management (LLM/template) |
| Fixture CLI | fixture-cli.md | fixture gen/fetch/explore commands, 3-Tier DB usage |
| Migration | migration.md | DB schema migration, PK type changes |
| Auth | auth.md | better-auth system (auto entity generation, Guards, Context) |
| Auth Migration | auth-migration.md | User.id type changes for external auth (e.g., better-auth) |
| Auth Plugins | auth-plugins.md | better-auth plugin wrappers (admin, organization, 2fa, passkey, etc. — 10 types), snake_case mapping |
| Vector search | vector.md | pgvector embeddings (Voyage AI/OpenAI), chunking, hybrid search |
| Puri query builder | puri.md | SELECT, WHERE, JOIN, FTS, pg_trgm fuzzy search, pgvector |
| AI Agents | ai-agents.md | BaseAgentClass, @tools decorator, ToolLoopAgent, AsyncLocalStorage state |
| Tasks | tasks.md | Background workflows, cron scheduling, durable steps, retry policies |
| Skill contribution | skill-contribution.md | Troubleshooting → skill contribution workflow (matching, decision, format, approval) |
| Framework change | framework-change.md | Criteria for framework fix vs. project workaround. @upload parameter pattern |
| Frontend | frontend.md | Service, TanStack Query |
| Scaffolding | scaffolding.md | Resolving UI scaffolding errors |
Task-to-Skill Reference
CRITICAL: When building a new system from scratch, start with .claude/workflow/project_init.md!
| Task | Reference Skill |
|---|
| Build an entire system from scratch | .claude/workflow/project_init.md (7-phase master guide) |
| Domain logic documentation / AC+Claim-based development | cdd.md |
| Project creation | create-sonamu, project-init |
| Project configuration | config |
| Sonamu local dev setup | config |
| DB setup / port conflict | database, config |
| 3-Tier DB structure | database, fixture-cli |
| Cone metadata generation/management | cone |
| Entity / field definition | entity-basic |
| Relationship setup | entity-relations |
| BelongsToOne FK code usage | entity-relations |
| API response field composition | subset |
| Data query / save logic | model, puri |
| API endpoints | api |
| Batch saving of relation data | upsert |
| Writing tests | testing |
| Running tests (sonamu test) | testing-devrunner |
| Naite tracing / debugging | naite |
| Fixture data generation/management | fixture-cli |
| Test data generation tips | testing (Fixture data generation tips), fixture-cli (practical tips) |
| DB schema changes | migration |
| Auth setup (auth generate, Guards, Context) | auth |
| PK type changes (better-auth, etc.) | auth-migration |
| Adding auth plugins | auth-plugins |
| Frontend development | frontend |
| Internationalization / translation | i18n |
| Scaffolding errors | scaffolding |
| Vector search / embeddings | vector |
| pg_trgm Fuzzy Search | puri, entity-basic |
| AI Agent development | ai-agents |
| Background jobs / scheduling | tasks |
| Troubleshooting → skill contribution | skill-contribution |
| Framework bug / constraint response | framework-change |
Skill Selection by CDD Claim Type
For Planners: Use this table to populate required_skills in each Claim blueprint.
surface — Entity / Schema / Shared Type Work
| Case | Required Skills |
|---|
| Add new entity | entity-basic, entity-relations, migration, cone, fixture-cli, i18n |
| Define subset | entity-basic, subset |
| Add auth entity | auth, auth-migration |
| Add auth plugin | auth-plugins |
| Add batch save structure | upsert |
| Add vector search structure | vector, entity-basic |
| Resolve scaffolding errors | scaffolding |
test — Test Writing
| Case | Required Skills |
|---|
| Business logic tests | testing, testing-devrunner |
| Tests requiring fixtures | testing, fixture-cli |
| Debugging / tracing | naite |
implement — Business Logic Implementation
| Case | Required Skills |
|---|
| Model CRUD implementation | model, puri |
| API endpoint implementation | api, model |
| File upload implementation | api, framework-change |
| SQL query writing | puri |
| Internationalization | i18n |
| Auth guard / session handling | auth |
| Auth plugin implementation | auth-plugins |
| Batch save implementation | upsert, model |
| AI Agent implementation | ai-agents |
| Background job / scheduling | tasks |
| Vector search implementation | vector, puri |
| Frontend integration | frontend, scaffolding |
Command Execution Path
All pnpm commands are run from the packages/api directory.
cd packages/api
pnpm build
pnpm dev
pnpm sonamu migrate run
Source Code References
- Sonamu framework:
sonamu/modules/sonamu/
- Example project:
sonamu/examples/miomock/
- Official docs:
sonamu/modules/docs/
- create-sonamu:
sonamu/modules/create-sonamu/
