# 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.
- Cross-surface parity: if the repo ships multiple user-facing surfaces for the same workflow, keep them aligned or document the intended divergence.
- User-facing interfaces: update help text, docs, or UX copy when changing commands, flags, prompts, or visible behavior.
- Secrets: never commit or print secrets; redact runner output before copying into 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}
Useful iteration commands (not a substitute for the recorded CI gate):
- `cargo test -p {package_name}`
- `cargo run -p {package_name} -- <command>`
- `cargo clippy -p {package_name}`
## Rust Conventions
- Formatting/linting: prefer the repo's existing Rust verification flow; common defaults are `cargo fmt` and Clippy with `-D warnings`.
- Visibility: keep APIs small; default to private, prefer `pub(crate)` over `pub`.
- Errors: prefer descriptive error types (`thiserror`) and `Result<T, E>` over panics.
- Cohesion: 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 via `#[cfg(test)]`.
- Integration tests: use `tests/` directory when cross-module behavior is the subject.
- Temp dirs: CI tests should run in isolated temp directories.
## Workflow Contracts
- Queue is the source of truth: active tasks and archived tasks.
- Task ordering: queue file order is execution order (top runs first).
- Draft tasks are skipped unless explicitly included.
- Planning cache: Phase 1 plans are written to cache directory (do not print inline).
- Supervision-aware completion: signal completion properly for the supervisor flow.
## Configuration
Config precedence (highest to lowest):
1. CLI flags
2. Project config: `.cueloop/config.jsonc`
3. Global config: `~/.config/cueloop/config.jsonc`
4. Schema defaults
## Git Hygiene
- Commit message: `{id_prefix}-####: <short summary>` (task id + summary).
- {git_ci_rule}
- This repo is local-CI-first; avoid adding remote CI (for example GitHub Actions) as a substitute for the recorded local gate.
## 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.
- When working from an issue/PR, prefer `gh` for context (`gh issue view ...`, `gh pr view ...`).
## Documentation Maintenance
- Schema changes: update code, regenerate schemas, and keep docs aligned.
- CLI changes: update help text/examples and keep CLI documentation aligned.
- Queue/task field changes: update task documentation.
## Troubleshooting
- {ci_troubleshooting}
- Queue lock: investigate `.cueloop/lock`; use `--force` only when you understand why the lock is stale.
- Runner issues: verify the runner binary is on `PATH` and check runner/model settings in config.
---
*Generated by CueLoop v{version} - {timestamp}*
*Template version: {template_version}*