nocal/AGENTS.md

Nocal agent instructions

These instructions apply to the entire repository.

Operating model

Use a frontier-capability model as the lead agent. The lead owns product and technical judgment: it inspects the repository, defines the architecture, creates the implementation plan, decomposes work, assigns non-overlapping file ownership, reviews every delivered change, integrates the result, and performs the final verification.

This lead/delegate/review sequence is the required default for feature work, not an optional optimization. Before writing feature implementation, the lead must identify bounded coding slices and dispatch them to cheaper coding agents (for example Luna) whenever the orchestration environment exposes those models. The frontier lead should normally restrict its own edits to shared contracts, cross-cutting or data-loss-sensitive logic, integration fixes, and work that is too tightly coupled to delegate safely.

If agent spawning is available but cheaper-model selection is not exposed, the lead must say so explicitly before implementation. It must not imply that a generic spawned agent is Luna or otherwise cheaper. In that environment the lead may use available agents for bounded parallel work, but should explain the limitation and still retain the same ownership, review, and verification duties.

Delegate bounded coding tasks to cheaper/lower-cost agents whenever the orchestration environment supports model selection. Coding agents should implement clearly specified slices; they should not independently redefine the architecture or expand product scope. Reserve the frontier model's context for planning, difficult cross-cutting decisions, code review, debugging integration failures, security/data-loss analysis, and final validation.

Delegation never transfers accountability. The lead must inspect the actual diffs and rerun relevant checks; an agent's claim that code compiles or tests pass is not sufficient evidence. Small, tightly coupled fixes may be completed directly by the lead when delegation would create more coordination cost than implementation value.

Delegation protocol

Before dispatching implementation work, the lead must:

1. Read this file and inspect the current workspace, including uncommitted work.
2. State the intended behavior, interfaces, invariants, and failure semantics.
3. Give each agent exclusive ownership of an explicit file or directory set.
4. Identify shared API contracts up front and prevent concurrent edits to the same files.
5. Keep build files, integration, roadmap decisions, and final review under the lead unless explicitly delegated.

Each coding agent must:

• stay inside its assigned scope and preserve unrelated user changes;
• use C++20 and avoid new runtime dependencies unless the lead approves them;
• use apply_patch for source edits;
• add or update deterministic tests for its behavior;
• compile with strict warnings and report the exact checks run;
• document limitations, unhandled edge cases, and any shared-contract mismatch;
• never mark a task complete based only on visual inspection.

Product and architecture constraints

• Nocal is a local-first, keyboard-driven terminal calendar for Linux and Hyprland.
• The month grid remains the primary view and appointments remain navigable inside day cells.
• Styling must use the terminal's default background and semantic ANSI palette. Do not introduce hard-coded RGB themes. NO_COLOR must remain usable.
• Keep domain, storage, synchronization, and TUI concerns separated. Provider APIs and iCalendar details must not leak into rendering code.
• Treat calendar writes as data-loss-sensitive. Mutations need validation, atomic persistence, rollback on failure, and tests for failure paths.
• Keep terminal lifecycle code exception-safe: raw mode, cursor visibility, and the alternate screen must always be restored.
• Remote synchronization is out of scope until the local mutation and durable cache boundaries are reliable.

Verification requirements

The lead's final review for a change should be proportional to its risk and normally include:

nix-shell --run 'meson compile -C build'
nix-shell --run 'meson test -C build --print-errorlogs'

Also run strict warning-as-error compilation for changed translation units. For storage, parsing, terminal lifecycle, or mutation work, run the Address and Undefined Behavior sanitizer build and exercise relevant failure paths. TUI changes require a live PTY smoke test covering interaction and terminal-state restoration.

Do not report completion while required tests fail, while delegated changes are unreviewed, or while user data can be lost on an ordinary error path.