83 lines
3.7 KiB
Markdown
83 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
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:
|
|
|
|
```sh
|
|
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.
|