# Repository Guidelines ({project_name})
{project_description}
## Non-Negotiables
- {ci_gate_rule}
- {documentation_style_rule}
- Tests: all new/changed behavior must be covered (success + failure modes). Prefer tests near the code.
- Type safety: preserve or strengthen the repo's existing typing expectations.
- Secrets: never commit or print secrets; redact sensitive output before recording in documentation.
## Agent Execution Style
- Start from the requested outcome, success criteria, constraints, and validation evidence.
- Keep plans and status updates concise; add detail only when it changes behavior or reduces risk.
- Ask for clarification only when missing information would materially change the work or create meaningful risk.
- Use available tools to verify facts instead of carrying stale assumptions forward.
- Stop only when the outcome is complete, validation is run or explicitly blocked, and remaining risks are documented.
## Repository Map
{repository_map}
## Build, Test, and CI
BLUF: use detected or explicitly configured repo commands when listed below. If a line is marked as a default or TODO, verify it before treating it as the repo contract.
Command source: {command_source_note}
- CI gate: {ci_command_line}
- Build: {build_command_line}
- Test: {test_command_line}
- Lint: {lint_command_line}
- Format: {format_command_line}
## Python Conventions
- Use the repo's existing environment and dependency workflow; many repos standardize on `uv`, but that is not assumed here unless the repo documents it.
- Prefer explicit type hints where the repo already uses them or where they materially improve safety.
- 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/`.
- Integration tests: use `tests/` when cross-module behavior is the subject.
- Temp dirs: tests should use isolated temp directories.
- Prefer fixtures and helper utilities over copy-pasted setup.
## 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).
- {git_ci_rule}
- 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.
## PR / Review Expectations
- Include a short "what changed" + "how to verify" section (expected local verification: {ci_review_expectation}).
- Call out any breaking behavior explicitly and update docs/help accordingly.
## Troubleshooting
- {ci_troubleshooting}
- Dependency issues: refresh the repo's environment using its documented workflow before changing package managers.
- Type errors: align with the repo's existing type-checking expectations before adding new tooling.
---
*Generated by CueLoop v{version} - {timestamp}*
*Template version: {template_version}*