# runoq

This repository implements the deterministic runtime layer for GitHub-backed agentic development orchestration.

## Core principles

- Keep durable behavior in code and machine-readable contracts, not in prompts.
- Prefer structured outputs over prose at script and tool boundaries.
- Treat GitHub as the audit and control surface.
- Treat `.runoq/state/*.json` as local recovery breadcrumbs, not the system of record.
- Preserve the target repository's main checkout; do execution work in sibling worktrees or explicit sandboxes.

## Development guidelines

- ALWAYS USE TDD SKILL WHEN WRITING CODE
- Keep the CLI thin and push stable logic into reusable runtime components.
- Prefer small, composable commands with explicit inputs, outputs, and side effects.
- Preserve existing contracts unless there is an intentional, documented versioned change.
- Favor deterministic behavior over cleverness.
- Reuse existing helpers, fixtures, and workflows before adding new ones.
- Keep prompts and agents thin; they should call stable repository logic rather than reimplement it.
- Focus on modularity and testability. Avoid monolithic scripts or agents that do everything.
- If current code architecture manifests as an implementation concern, prefer refactoring into a cleaner architecture over hacking solution in place; follow Kent Beck's principle of "First make the change easy, then make the easy change"

## Testing and validation

- Add or update deterministic tests whenever behavior changes.
- Use fake `gh` fixtures for integration-style coverage where possible.
- Use live smoke lanes for real GitHub and real LLM validation, but keep them opt-in and credential-gated.
- Validate both happy paths and recovery or failure paths.
- Smoke test environment variables are in `.env.smoke-sandbox`. Source it before running live smoke tests. See `docs/live-smoke.md` for full setup.

## Go code

When editing or creating Go code, load and follow these skills from `.agents/skills/`:

- `use-modern-go`
- `golang-linter`
- `golang-data-structures`

Rules:
- Always load `use-modern-go` and `golang-linter` before making Go changes.
- Load `golang-data-structures` whenever changing data structures, collection types, pointer usage, or performance-sensitive paths.

# runoq runtime notes

- Agents and skills in this repo are loaded into target projects via `--add-dir`.
- Utility scripts are the source of truth for queue state, PR lifecycle, state management, and reporting.
- Do not duplicate deterministic rules from the scripts into prompts.

## Documentation

- Update docs when changing operator-visible behavior, contracts, or architecture.
- Read `docs/development-guidelines.md` for the more detailed contributor guidance.