# 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 module doc 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.
- 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 (format → type-check → lint → build → test).
- `{build_command}`: build the project.
- `{test_command}`: run all tests.
- `{lint_command}`: run linting.
- `{format_command}`: format code.
## Testing
- Unit tests: colocate with implementation where possible.
- Integration tests: use dedicated test directories for cross-module behavior.
- 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}`; check formatting, linting, and tests.
- Task system issues: check lock files and use `--force` only when you understand why locks are stale.
---
*Generated by Ralph v{version} - {timestamp}*
*Template version: {template_version}*