small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo AGENTS.md
8.4 kB · 171 lines
Markdown
at main

Repository agent instructions #

Albedo is a coding agent daemon written in Gleam, with a Go terminal client, a Svelte web client, and a Python execution kernel. Start with the robot documentation index for implementation ownership and interfaces.

Use the documentation #

Read the relevant subsystem page before changing its behavior. Read Change Albedo for shared ownership, lifecycle, storage, provider, and testing rules. Name the owning module before choosing where a change belongs.

Use the source links to verify current behavior. A contributor rule is project policy, not necessarily a runtime check. If code and a rule disagree, investigate the conflict rather than deleting the rule or silently changing behavior.

Use the design-preflight skill before substantial implementation changes. Reuse an existing owner or pattern instead of adding a parallel implementation.

Write and maintain the documentation #

Follow robot-docs/AGENTS.md when creating or editing wiki pages. It contains the writing and verification rules.

Keep contributor instructions self-contained. State project rules directly, and link repository files for supporting procedures. Do not depend on personal tool installations, private paths, temporary audit reports, or conversation history.

Update the canonical page in the same change as the behavior it describes. Preserve relevant guidance as well as facts, including what callers and contributors should not do. Keep shared guidance in Change Albedo, and link from feature pages instead of copying it.

Keep one owner for each contract. Add new pages to the index and link related pages in both directions. Check incoming links before renaming a page or changing its headings. Do not keep unsupported claims just to preserve old prose.

Use the project tools #

Write code in Gleam. Keep Erlang only as a thin binding for what Gleam cannot express, and move what Gleam can express when you change an Erlang module. See Change Albedo.

Do not add dependencies unless asked. Use gleam add or gleam add --dev for Gleam packages. Do not edit the generated manifest.toml by hand.

Use the tools supplied by nix develop. In particular, keep Go and gopls from the same pinned toolchain. The declared versions and settings live in gleam.toml, pyproject.toml, and the Nix development shell.

Run nix fmt before committing any change, including prose-only changes. It runs every formatter configured in nix/treefmt.nix, and CI fails when it would change a file. Prettier rewraps Markdown at 80 columns, so edited wiki and instruction pages usually need it too.

Run the checks relevant to the changed language:

  • Gleam: gleam check, gleam format src test, and test/gleam-lint.sh.
  • Python: ruff format priv/python test, ruff check, and ty check.
  • Go: go -C cli vet ./..., go -C cli test ./..., and python3 test/gopls_all.py inside nix develop.
  • Renderer: cargo test --release --locked --manifest-path native/render/Cargo.toml.

test/quick.sh runs the static checks. test.sh is the gate before a commit. Its default selects affected end-to-end tests. Use that default locally unless the task needs a full run. ./test.sh --full runs the full selection used by CI. The lint script's optional --review and --all profiles are described in Gleam lint.

Keep generated lint, audit, and benchmark reports under /tmp. Do not commit retrospective cleanup inventories. A prose-only change needs formatting, link, heading, and whitespace checks, not new tests that assert documentation wording.

Choose and run tests #

Follow the writing-tests skill. Prefer a scenario through the real daemon and shared harness in test/e2e. Unit tests need a cross-cutting invariant or bug-prone logic that an end-to-end scenario cannot exercise reliably.

Keep reusable Python fixtures in _support.py modules. Keep test state on the test instance. Use the harness's exclusive modes for global settings or daemon restarts, and its peer-daemon support for additional test daemons. Do not reproduce that startup plumbing in individual tests.

The gate creates a daemon snapshot before concurrent suites start. Do not start an end-to-end suite from inside gleam test, which holds the build lock needed to create that snapshot. Use the prebuilt daemon and CLI expected by the harness. Use -count=1 when running the Go end-to-end suite directly so it does not reuse cached results. See test execution.

Keep live-provider, PTY, and benchmark experiments under test/manual. Set ALBEDO_NO_BROWSER=1 when a command could open a browser automatically.

Reproduce intermittent failures under load and measure the slow or racy operation before changing a deadline. python3 test/manual/stress.py <command> supports this work. Do not hide a race with retries. When the deadline itself is the behavior under test, keep its inner and outer waits consistent.

Own private daemons #

For an experiment outside the test harness, use a private ALBEDO_HOME and a launcher from test/snapshot-daemon.sh. Set ALBEDO_PARENT_PID to the process that owns the experiment, rather than the short-lived CLI. Use a private ALBEDO_STANDBY_DIR or set ALBEDO_STANDBY=0.

Stop the private daemon with albedo daemon --stop under the same environment and check for remaining processes before reporting completion. The CLI launches detached work, so finishing the CLI command does not prove the daemon stopped.

Inspect UI changes #

Render UI changes and inspect the result before calling them done. Code review and text output do not replace a visual check.

For TUI changes, use the shot gallery. Cover the relevant normal, empty, error, pending, and confirmation states at wide and narrow sizes. Set ALBEDO_SHOT_DIR, run the matching TestShotGallery selection, and render its output with python3 test/manual/tui_shot.py /tmp/shots.

For web changes, use a private daemon, build with npm --prefix web run build, and run albedo web --no-open against that private home. Inspect desktop and phone layouts in light and dark themes. Close resources created for the review when finished. See web client and terminal client.

Commit and publish #

Other agents may share this checkout. Stage only the paths you changed. Do not stash or overwrite someone else's work.

Run the commit gate before committing. jj does not run Git hooks, so run test/quick.sh explicitly when using it. Push only when the user has authorized the destination. Do not push to main on your own. Monitor CI after an authorized push and investigate failures.

If asked to create a pull request, tell the user that the maintainers require the human contributor to write its body in their own words and explain their reasoning. Do not write that body for them.

Find the implementation #

  • src/albedo/daemon: session coordination, durable storage, HTTP adapters, settings, migrations, and observation.
  • src/albedo/harness: the model loop, plugin contracts, composition, runtime, and provider integration. extensions.gleam owns the installed and default extension lists.
  • cli/internal: command wiring, application workflows, daemon transport, ACP, the web server, and the TUI.
  • web/src: the browser client.
  • priv/python: kernel execution, job handling, bindings, and supporting processes.
  • native/render: the renderer.
  • release, test, and nix: packaging, validation, and development tools.

Use the wiki index for detailed subsystem pages. Repo-local design, TUI, test, and Tangled skills live under .agents/skills. Shipped model skills live under priv/skills. Preserve the patch notes under vendored dependencies when changing them.