# Guide for Coding Agents - modules/sonamu/src/skills

Inherits rules from:

- `../../../../AGENTS.md`
- `../../AGENTS.md`

## Directory role

- Source-of-truth skill documents for Sonamu-related agent guidance.

## Skill reference rule

- Read `modules/sonamu/src/skills/sonamu/SKILL.md` before Sonamu feature work that uses skill context.
- Keep references under this directory consistent when adding/updating skill docs.

## Skill reference rule (user projects)

When working in a user Sonamu project, always read skill files directly using the Read tool:

```
.claude/skills/sonamu/{skill-name}.md
```

Examples:

- Migration → Read `.claude/skills/sonamu/migration.md`
- Entity creation → Read `.claude/skills/sonamu/entity-basic.md`
- Full workflow → Read `.claude/skills/sonamu/workflow.md`
- Scaffolding → Read `.claude/skills/sonamu/scaffolding.md`

See `.claude/skills/sonamu/SKILL.md` for the full skill list.

## Skill contribution trigger

- After resolving a troubleshooting issue, suggest the `skill-contribution.md` workflow if the resolution is reusable.
- If the user explicitly requests (e.g. "add this to skills", "record this"), read `skill-contribution.md` and proceed immediately.
- Always check existing skills for duplicates before writing. Do not create new files unconditionally.

## Cross-workspace gate

- For changes in this scope, root `pnpm check` (oxlint + oxfmt) must pass before handoff.

## TypeScript type safety policy

- `as any` and `as unknown as T` are strictly prohibited.
- Resolve type errors through correct type annotations, generic constraints, type narrowing, or interface extension.
- Do not use `as any` to work around "excessively deep" or similar TypeScript inference limits — find the correct access pattern instead (e.g. use `getPuri("r")` directly rather than casting the result).
- Chaining methods after `as any` bypasses all TypeScript signature checks and leads directly to runtime bugs.
- Non-null assertion (`!`) is prohibited. Use optional chaining (`?.`) or type guard filters instead.

## Code quality gate

After editing any `.ts` or `.tsx` file, always run both checks before considering the task done:

1. `npx tsc --noEmit --skipLibCheck` — type errors
2. `pnpm check` — lint and format (oxlint + oxfmt)

Do not skip lint/format check even when tsc passes. oxlint catches `noNonNullAssertion`, import order, and other issues that tsc does not.

## Skill read triggers

Read the listed skill file before attempting any workaround or fix in these situations:

| Situation                                                                   | Read before acting              |
| --------------------------------------------------------------------------- | ------------------------------- |
| TypeScript error in Model code (type inference, "excessively deep", etc.)   | `puri.md`, `model.md`           |
| Writing or modifying a `findMany()` / `executeSubsetQuery()` call           | `model.md`                      |
| Writing or modifying a `@upload` method                                     | `api.md`                        |
| Database query returning unexpected results                                 | `puri.md`                       |
| Migration error or schema change                                            | `migration.md`                  |
| Starting AC+Claim-based development or writing a Claim                      | `cdd.md`                        |
| Applying Auth Guards or handling session/permission logic                   | `auth.md`                       |
| Implementing polymorphic relations with `entity_type` + `entity_id` pattern | `entity-relations.md`           |
| Writing Puri SELECT / WHERE / JOIN / FTS / pgvector queries                 | `puri.md`                       |
| Implementing `@upload` file upload or deciding parameter pattern            | `api.md`, `framework-change.md` |
| Reading or writing files under `contract/rules/`                            | `cdd.md`                        |
| Implementing `BaseAgentClass` or `@tools` decorator                         | `ai-agents.md`                  |
| Implementing background jobs or cron scheduling                             | `tasks.md`                      |
| Batch-saving relation data (upsert)                                         | `upsert.md`                     |
| Adding a new entity or enum and registering i18n keys                       | `i18n.md`                       |
| Implementing pgvector embeddings or vector search                           | `vector.md`                     |