sonamu 0.8.25 → 0.9.0

package/src/skills/commands/sonamu-skills.md

@@ -3,18 +3,18 @@ Read ~/.claude/skills/sonamu/SKILL.md and follow its instructions.
 Then greet the user with the following format (exactly):
 
 ---
+
 Sonamu 스킬 가이드가 로드됐습니다. 어떤 작업을 하실 건가요?
 
-**Workflow**  · CDD · project-init · config
+**Workflow** · CDD · project-init · config
 **Entity/DB** · entity-basic · entity-relations · subset · migration · database
-**API**       · model · api · puri · upsert
-**Testing**   · testing · devrunner · naite · cone · fixture-cli
-**Auth**      · auth · auth-migration · auth-plugins
-**Frontend**  · frontend · scaffolding · i18n
-**Advanced**  · vector · ai-agents · tasks
-**Meta**      · skill-contribution · framework-change
+**API** · model · api · puri · upsert
+**Testing** · testing · devrunner · naite · cone · fixture-cli
+**Auth** · auth · auth-migration · auth-plugins
+**Frontend** · frontend · scaffolding · i18n
+**Advanced** · vector · ai-agents · tasks
+**Meta** · skill-contribution · framework-change
 
-어떤 스킬이나 작업을 도와드릴까요? (하고 싶은 작업을 자유롭게 설명해도 됩니다.)
----
+## 어떤 스킬이나 작업을 도와드릴까요? (하고 싶은 작업을 자유롭게 설명해도 됩니다.)
 
 If the user provides $ARGUMENTS, skip the greeting and directly help with: $ARGUMENTS

package/src/skills/sonamu/SKILL.md

@@ -12,11 +12,13 @@ Claude Code skill for developing projects with the Sonamu framework.
 **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
@@ -41,16 +43,17 @@ PHASE 6: Frontend development                (proceed in batches with user confi
 
 **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 |
+| 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:**
+
 1. If `contract/**/*.contract.md` and `skills/project/architecture.md` exist, read them first.
 2. Verify prerequisites for the target PHASE.
 3. If prerequisites are not met, inform the user and begin from the required step.
@@ -85,18 +88,22 @@ Documents domain rules in a cohesive form and captures decision rationale that c
 # {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
 
@@ -113,79 +120,122 @@ Documents are persisted as files, so project context is preserved even when the
 
 ## 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 |
+| 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** |
+| 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
 

package/src/skills/sonamu/ai-agents.md

@@ -13,9 +13,9 @@ Sonamu provides a framework that wraps Vercel AI SDK's `ToolLoopAgent` to build
 
 ## Structure
 
-| File | Role |
-|------|------|
-| `agent.ts` | `BaseAgentClass`, `tools` decorator |
+| File       | Role                                                                    |
+| ---------- | ----------------------------------------------------------------------- |
+| `agent.ts` | `BaseAgentClass`, `tools` decorator                                     |
 | `types.ts` | `AgentConfig`, `ToolDecoratorOptions`, `RegisteredToolDefinition`, etc. |
 
 ---
@@ -30,7 +30,7 @@ import { z } from "zod/v4";
 
 class MyAgentClass extends BaseAgentClass<{ count: number }> {
   constructor() {
-    super("MyAgent");  // agentName (used as logger category)
+    super("MyAgent"); // agentName (used as logger category)
   }
 
   @tools({
@@ -50,12 +50,12 @@ export const MyAgent = new MyAgentClass();
 
 ### Key Features
 
-| Feature | Description |
-|------|------|
-| `this.logger` | LogTape logger (agent category) |
-| `this.store` | AsyncLocalStorage-based state access |
-| `this.tools` | Registered toolset (ToolSet) |
-| `this.use()` | Run the Agent (ALS context + ToolLoopAgent) |
+| Feature       | Description                                 |
+| ------------- | ------------------------------------------- |
+| `this.logger` | LogTape logger (agent category)             |
+| `this.store`  | AsyncLocalStorage-based state access        |
+| `this.tools`  | Registered toolset (ToolSet)                |
+| `this.use()`  | Run the Agent (ALS context + ToolLoopAgent) |
 
 ---
 
@@ -105,7 +105,7 @@ const result = await MyAgent.use(
   {
     model: anthropic("claude-sonnet-4-5-20250514"),
     instructions: "You are a math assistant.",
-    toolChoice: "auto",     // "auto" | "none" | "required"
+    toolChoice: "auto", // "auto" | "none" | "required"
     maxOutputTokens: 1000,
     temperature: 0.7,
   },
@@ -122,21 +122,21 @@ const result = await MyAgent.use(
 
 ### AgentConfig Options
 
-| Option | Type | Description |
-|------|------|------|
-| `model` | `LanguageModel` | AI SDK model (required) |
-| `instructions` | `string` | System prompt |
-| `toolChoice` | `"auto" \| "none" \| "required"` | Tool selection strategy |
-| `stopWhen` | `StopCondition` | Stop condition |
-| `activeTools` | `string[]` | List of tool names to activate |
-| `maxOutputTokens` | `number` | Maximum output tokens |
-| `temperature` | `number` | Temperature |
-| `topP` / `topK` | `number` | Sampling parameters |
-| `presencePenalty` / `frequencyPenalty` | `number` | Penalties |
-| `seed` | `number` | Seed for reproducibility |
-| `stopSequences` | `string[]` | Generation stop sequences |
-| `providerOptions` | `ProviderOptions` | Additional provider-specific options |
-| `headers` | `Record<string, string>` | Custom HTTP headers |
+| Option                                 | Type                             | Description                          |
+| -------------------------------------- | -------------------------------- | ------------------------------------ |
+| `model`                                | `LanguageModel`                  | AI SDK model (required)              |
+| `instructions`                         | `string`                         | System prompt                        |
+| `toolChoice`                           | `"auto" \| "none" \| "required"` | Tool selection strategy              |
+| `stopWhen`                             | `StopCondition`                  | Stop condition                       |
+| `activeTools`                          | `string[]`                       | List of tool names to activate       |
+| `maxOutputTokens`                      | `number`                         | Maximum output tokens                |
+| `temperature`                          | `number`                         | Temperature                          |
+| `topP` / `topK`                        | `number`                         | Sampling parameters                  |
+| `presencePenalty` / `frequencyPenalty` | `number`                         | Penalties                            |
+| `seed`                                 | `number`                         | Seed for reproducibility             |
+| `stopSequences`                        | `string[]`                       | Generation stop sequences            |
+| `providerOptions`                      | `ProviderOptions`                | Additional provider-specific options |
+| `headers`                              | `Record<string, string>`         | Custom HTTP headers                  |
 
 ---
 
@@ -182,6 +182,7 @@ class AgentB extends BaseAgentClass<void> {
 `this.logger` uses LogTape. The category is generated with `convertDomainToCategory(agentName, "agent")`.
 
 Debug logs are automatically recorded on tool execution:
+
 ```
 tools: {model}.{method} with args: {args}
 ```