# 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
- (prefer `//!` module docs at the top of the file)
- Tests: all new/changed behavior must be covered (success + failure modes). Prefer tests near the code.
- Feature parity: when changing a user-visible workflow, maintain parity between the CLI and any supported GUI client (or document/justify the divergence explicitly).
- CLI help: user-facing commands/flags MUST have `--help` text with examples.
- Secrets: never commit or print secrets; redact runner output before copying into documentation.
## Repository Map
{repository_map}
## Build, Test, and CI
The Makefile is the contract; keep these targets working:
- `{ci_command}`: local CI gate (see the configured Makefile/validation command for exact ordering). Do not remove required install/verification steps from the repo contract.
- `make install`: install binary to `~/.local/bin/` (or a writable fallback).
- `make test`: runs cargo-nextest for workspace tests (fallback to `cargo test` if nextest is missing), then `cargo test --doc` in isolated temp dirs.
- `make lint`: `cargo clippy --workspace --all-targets -- -D warnings`
- `make format`: `cargo fmt --all`
- `make type-check`: `cargo check --workspace --all-targets`
- `make generate`: regenerates any generated artifacts (schemas, etc.).
- `make update`: upgrades direct Rust dependencies (`cargo upgrade --incompatible`) and refreshes transitive pins (`cargo update`); pair with `make macos-ci` when a bundled Swift/Xcode app is in scope because there may be no separate Swift package manifest to bump.
- `make clean`: removes build artifacts, logs, and cache entries.
Useful iteration commands (not a substitute for `{ci_command}`):
- `cargo test -p {package_name}`
- `cargo run -p {package_name} -- <command>`
- `cargo clippy -p {package_name}`
## Rust Conventions
- Formatting/linting: `cargo fmt` + Clippy with `-D warnings` (CI treats warnings as errors).
- 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 run in isolated temp directories (set `RALPH_CI_KEEP_TMP=1` to keep).
## 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: `.ralph/config.jsonc`
3. Global config: `~/.config/ralph/config.jsonc`
4. Schema defaults
## Git Hygiene
- Commit message: `{id_prefix}-####: <short summary>` (task id + summary).
- Do not commit if `{ci_command}` is failing.
- This repo is local-CI-first; avoid adding remote CI (e.g., GitHub Actions) as a substitute for `{ci_command}`.
## PR / Review Expectations
- Include a short "what changed" + "how to verify" section (expected: `{ci_command}`).
- 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, run `make generate`, and keep schemas + docs aligned.
- CLI changes: update help text/examples and keep CLI documentation aligned.
- Queue/task field changes: update task documentation.
## Troubleshooting
- CI failing: run `{ci_command}`; common checks are `cargo fmt --check`, `cargo clippy -- -D warnings`, `cargo test --workspace`.
- Queue lock: investigate `.ralph/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 Ralph v{version} - {timestamp}*
*Template version: {template_version}*