# Repository Guidelines ({project_name})
{project_description}
## Non-Negotiables
- CI gate: `{ci_command}` MUST pass before claiming completion, committing, or merging.
- Source docs: every new/changed source file MUST start with a JSDoc comment that states:
- what the file is responsible for
- what it explicitly does NOT handle
- any invariants/assumptions callers must respect
- Tests: all new/changed behavior must be covered (success + failure modes). Prefer tests near the code.
- Type safety: use strict TypeScript configuration.
- Secrets: never commit or print secrets; redact sensitive output before recording in documentation.
## Repository Map
{repository_map}
## Build, Test, and CI
The Makefile is the contract; keep these targets working:
- `{ci_command}`: local CI gate (install → format → type-check → lint → build → test). Do not remove required install/verification steps from the repo contract.
- `make install`: install dependencies via `pnpm install`.
- `make test`: run all tests with `pnpm test`.
- `make lint`: `pnpm lint` or `biome check`
- `make format`: `pnpm format` or `biome format`
- `make type-check`: `pnpm type-check` or `tsc --noEmit`
- `make build`: `pnpm build`
- `make update`: update all deps to latest stable versions.
- `make clean`: remove lock files, node_modules, log files, etc.
Useful iteration commands (not a substitute for `{ci_command}`):
- `pnpm test`
- `pnpm dev`
- `pnpm build`
## TypeScript Conventions
- Use strict, safe TypeScript configuration (`strict: true`).
- Use `biome` for linting and formatting.
- Use `pnpm` package manager.
- Keep modules/files focused; split large files rather than growing grab-bags.
- Individual source files SHOULD remain under ~400 LOC.
- Files exceeding ~700 LOC REQUIRE explicit justification explaining why cohesion is still intact.
- Files exceeding ~1,000 LOC are presumed to be mis-scoped and MUST be split unless proven otherwise.
## Testing
- Unit tests: colocate with implementation or in `__tests__/` directories.
- Integration tests: use `tests/` directory when cross-module behavior is the subject.
- Use Vitest or Jest for testing.
- Temp dirs: tests should use isolated temp directories.
## Workflow Contracts
- Task tracking: use the project's task system for active work.
- Task ordering: top of queue runs first.
- Planning: write plans to designated cache directory (do not print inline).
- Completion: signal completion through proper channels for supervisor flow.
## Configuration
Config precedence (highest to lowest):
1. CLI flags
2. Project config files
3. Global config files
4. Schema defaults
## Git Hygiene
- Commit message: `{id_prefix}-####: <short summary>` (task id + summary).
- Do not commit if `{ci_command}` is failing.
- Prefer local CI over remote CI.
## Documentation Maintenance
- Schema changes: update code, regenerate schemas, and keep docs aligned.
- CLI changes: update help text/examples and keep CLI documentation aligned.
- Task field changes: update task documentation.
## Troubleshooting
- CI failing: run `{ci_command}`; common checks are type checking, linting, and tests.
- Dependency issues: try `make clean && make install` to refresh the environment.
- Build errors: check `tsconfig.json` for proper configuration.
---
*Generated by Ralph v{version} - {timestamp}*
*Template version: {template_version}*