Enterprise Code Standard

---
name: enterprise-code-standard
description: "Enforces enterprise TypeScript and full-stack implementation standards for AigcForge. Use when adding or changing production code, tests, Effect services, Schema, database, HTTP, LLM, tool, UI, TUI, desktop, or generated-boundary code. Aligns new code with Coding mode, the build agent, existing owners, and repository protocols."
allowed-tools: Read Edit Write Bash Glob Grep
---

# Enterprise Code Standard

Apply this skill to every new or materially changed production code path. It defines the
repository's implementation bar and makes Coding-mode `build` the compatibility source for new code.

## When to Use

- Add or change TypeScript, Effect, Schema, database, HTTP, LLM, tool, TUI, desktop, or SolidJS code.
- Create a helper, service, component, route, adapter, schema, migration, or test fixture.
- Review code generated by an agent or ported from another Product Mode.
- Decide whether a new abstraction is justified.

## When NOT to Use

- Pure product requirements or architecture decisions: read the relevant PRD or ADR first.
- Database-only details: also load `skills/database/SKILL.md`.
- Theme-only details: also load `skills/frontend-theming/SKILL.md`.
- Protocol navigation: load `skills/protocols/SKILL.md` first.

## Non-Negotiable Rules

1. **Reuse before creation.** Search the owning module, Coding mode, and `build` agent patterns before writing a new implementation. A new helper or abstraction requires evidence that an existing owner cannot serve the need.
2. **Align with local contracts.** Preserve package boundaries, self-export modules, Effect services, Schema codecs, generated clients, v2 UI tokens, and existing test helpers. Do not invent a parallel API.
3. **Keep the happy path small.** Prefer early returns, inference, functional collection methods, one clear owner, and few variables. Extract only reusable or genuinely complex concepts.
4. **Write English comments only when needed.** Comments explain non-obvious constraints, compatibility reasons, security boundaries, or surprising behavior. Do not narrate obvious code. Existing non-English comments may remain unless the change touches them; new comments must be English.
5. **Make boundaries explicit.** Validate untrusted input at boundaries, use typed errors, preserve interruption and defects, and never expose secrets or full prompts in logs.
6. **Test behavior, not duplicated implementation.** Extend the nearest real test pattern. Prefer `testEffect`, `Layer.mock`, live fixtures, contract tests, and Playwright for user workflows over hand-written runtimes or copied production logic.

## Coding-Mode Source Order

Use this order for every implementation decision:

1. Read the applicable `AGENTS.md` and protocol route.
2. Find the same behavior in Coding mode (`packages/app`, `packages/core`, `packages/aigcfroge/src/agent/build`, or the relevant shared package).
3. Read `packages/aigcfroge/src/agent/build/protocol.md`.
4. Find an existing owner symbol and its callers and tests before creating anything.
5. Extend or parameterize the existing owner when the behavior is genuinely shared.
6. Add a new symbol only when reuse is impossible or would violate an existing boundary; record rejected reuse candidates in the plan or review note.

"No hand-written code" means **no unverified duplicate implementation**. Necessary new code is allowed after the repository proves that no suitable implementation exists.

## Required Implementation Shape

| Area         | Required default                                                                                     |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| Effect       | `Effect.gen`, named `Effect.fn`, direct typed errors, `Effect.forkIn(scope)`                         |
| Schema       | `Schema.Class` for multi-field domain records, brands for single values, tagged errors               |
| Imports      | self-export namespaces; no new star imports or aliases; dynamic import for heavy branch-only modules |
| Control flow | early returns; no `else` after a guard; `const` and inferred types                                   |
| Database     | snake_case Drizzle fields, TypeScript migrations, generated artifacts regenerated by script          |
| HTTP         | thin handlers, service-owned business rules, declared `HttpApiBuilder` groups                        |
| LLM          | preserve Session/LLM adapter boundary and Protocol/Endpoint/Auth/Framing route axes                  |
| Tools        | canonical `Tool.make`, owner-scoped registration, typed permission and settlement semantics          |
| UI           | reuse shared components, v2 tokens, i18n, accessible labels, stable layout, light/dark verification  |
| Tests        | nearest fixture and helper; no `Effect.sleep` or arbitrary timeout for readiness                     |

## Comment Policy

- New code comments must be English and short.
- Prefer naming a concept over explaining a line: use names such as `requireConfig`, `reconcileContext`, or `assertContainedPath`.
- Keep comments for constraints such as provider quirks, migration compatibility, security checks, or intentionally deferred behavior.
- Remove stale comments when behavior changes.
- User-facing strings belong to i18n, not code comments or ad hoc constants.

## Review Gate

- [ ] Reuse search covered the owner module, Coding mode, `build` agent, callers, and tests.
- [ ] New abstractions have a named owner and a reason reuse was insufficient.
- [ ] The diff has no unnecessary generated edits, duplicate constants, dead branches, or speculative compatibility code.
- [ ] New comments are English, necessary, and current.
- [ ] Affected package typecheck, tests, lint, and UI/e2e checks pass.
- [ ] `git diff` contains only task-related changes and no secrets or sensitive logs.

## Reference

Read [coding-mode-source-map.md](references/coding-mode-source-map.md) when the correct Coding-mode owner or verification command is unclear.