# TODOs — agent-environments

> Self-authored tracker, not approved by the user (the user said: "Work
> autonomously, consult with codex, create a todo for yourself and follow it").

## Goal

A Nix flake library for module-based Claude Code / Codex environments with
per-launcher logins and packaged skills. Spec:
`docs/superpowers/specs/2026-09-26-agent-environments-design.md`.

## Scope and authority

- In scope: this repo only (`/home/fbw/src/agent-environments`), local commits on
  `main`.
- Not authorized: pushing, creating remotes, touching `~/.claude`, `~/.codex` or
  `~/.local/agent-environments` for real (tests use a temp `HOME`).
- Network: GitHub + cache.nixos.org for flake inputs only.
- Companion: `~/.nix-profile/bin/codex exec --sandbox read-only` (unsandboxed).
- Evidence dir: `/tmp/claude-1001/agent-environments/`.

## Success criteria

1. `nix flake check` passes, and its checks cover every behaviour listed in the
   spec's Testing section.
2. `nix build .#default` gives `bin/claude` and `bin/codex`.
3. Both examples build against the local checkout
   (`--override-input agent-environments path:$PWD`).
4. Codex has reviewed the implementation and has no blocking findings left.

## Tasks

- [x] Preflight (see the log below)
- [x] Design spec plus a Codex review of it (review-1: 6 blocking points, all folded in)
- [x] T1 flake.nix skeleton + lock (nixpkgs, claude-code, codex)
- [x] T2 lib: mkEnvironment, mkSkill, mkSkillModule
- [x] T3 modules: core (instructions, skills closure, launchers, assertions), claude, codex
- [x] T4 launcher script (manifest, flock, atomic links, settings layering)
- [x] T5 checks with stub agents (all spec behaviours)
- [x] T6 real-codex integration probe (or record coverage gap)
- [x] T7 default package + formatter
- [x] T8 examples/basic, examples/multi-account; build both
- [x] T9 README
- [x] T10 Codex review of the implementation; fix blocking findings
- [x] T11 Final verification + summary

## Log

- Preflight: nix 2.34.8 OK; codex companion at ~/.nix-profile/bin/codex (0.155.1)
  answered a probe; `git init -b main` done; GitHub reachable with
  allowed_domains; inputs resolve: claude-code-nix (claude-code 2.1.283),
  codex-cli-nix (codex 0.157.1).
- Facts: `claude --settings <file>` layers settings; `codex --profile <n>` layers
  `$CODEX_HOME/<n>.config.toml`; the codex binary refers to `CODEX_HOME/skills`
  and a `skills/.system` directory.
- Decisions after review-1: explicit launchers only; manifest-based ownership;
  flock + atomic `mv -T`; name validation; no backups (fail on conflict);
  shared ids are documented, not enforced.
- T1–T4 (c42fffc): the flake builds; the default package gives bin/claude + bin/codex.
  Nix commands run unsandboxed: the Bash sandbox bind-mounts char devices
  (.gitmodules, .bashrc, …) into the repo, which breaks Nix's git/path fetchers.
- T5 (83a1cdd): 7 checks. Mutation tests: dropping the PATH export → launch-contract
  FAIL; dropping the "still a symlink" condition → refuses-unmanaged FAIL (after
  switching that case to a regular file, because `mv -T` fails on non-empty
  directories anyway).
- T6 (b61dc9a): real Codex 0.157.1 `debug prompt-input` through the launcher shows
  the AGENTS.md, skill and profile markers, run inside the Nix sandbox. COVERAGE GAP:
  there is no offline equivalent for Claude (it needs a login). Claude reading
  `$CLAUDE_CONFIG_DIR/CLAUDE.md` and symlinked `skills/<name>` rests on the docs
  (cited in review-1) plus home-manager's claude-code module using the same
  store-symlink layout. Not run here.
- T7–T9 (90e573d, db15f3d): nixfmt; both examples build with --override-input;
  a smoke run of claude-basic/codex-basic --version in a temp HOME links both skills
  (the dependency closure) and CLAUDE.md.
- T10: review rounds, cap 10 (skill default; the user did not set one).
  Round 1 (pkg 5017493): 3 findings. [Major] lock/temp paths wrote through symlinks
    → fixup 40a460a/af62e81; [Major] symlinked skills dir → same fixups;
    [Minor] README `nix run` → fixup 5c05d4d.
  Round 2 (pkg 5c05d4d): 1 finding. [Major] stateDir evaluated as shell code →
    literal path (absolute or ~/), fixups 0294b46/a8e9e2e/ef05cec/9c5c1a3.
  Round 3 (pkg 9c5c1a3): NO REQUESTED CHANGES → approved at round 3 of 10.
- T11 at 9c5c1a3: `nix flake check` exit 0 (10 checks, x86_64-linux only);
  .#default → bin/claude, bin/codex; both examples build.
  Not verified: aarch64/darwin builds; real Claude loading CLAUDE.md/skills
  (see T6); the fixup commits are unsquashed (the user's rule).