# 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](robot-docs/README.md) for implementation ownership and interfaces. ## Use the documentation Read the relevant subsystem page before changing its behavior. Read [Change Albedo](robot-docs/contributing.md) 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](priv/skills/design-preflight/SKILL.md) 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](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](robot-docs/contributing.md), 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](robot-docs/contributing.md#write-gleam-and-keep-values-typed). 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](gleam.toml), [pyproject.toml](pyproject.toml), and the [Nix development shell](nix/devShells.nix). Run `nix fmt` before committing any change, including prose-only changes. It runs every formatter configured in [nix/treefmt.nix](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](test/quick.sh) runs the static checks. [test.sh](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](robot-docs/gleam-lint.md). 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](.agents/skills/writing-tests/SKILL.md). 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](robot-docs/testing.md). 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 ` 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](cli/internal/tui/shot_test.go). 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](robot-docs/web.md) and [terminal client](robot-docs/tui.md). ## 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](src/albedo/daemon): session coordination, durable storage, HTTP adapters, settings, migrations, and observation. - [src/albedo/harness](src/albedo/harness): the model loop, plugin contracts, composition, runtime, and provider integration. [extensions.gleam](src/albedo/harness/extensions.gleam) owns the installed and default extension lists. - [cli/internal](cli/internal): command wiring, application workflows, daemon transport, ACP, the web server, and the TUI. - [web/src](web/src): the browser client. - [priv/python](priv/python): kernel execution, job handling, bindings, and supporting processes. - [native/render](native/render): the renderer. - [release](release), [test](test), and [nix](nix): packaging, validation, and development tools. Use the [wiki index](robot-docs/README.md) for detailed subsystem pages. Repo-local design, TUI, test, and Tangled skills live under [.agents/skills](.agents/skills). Shipped model skills live under [priv/skills](priv/skills). Preserve the patch notes under vendored dependencies when changing them.