toph/claudebox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claudebox/.planning/RETROSPECTIVE.md
Christopher Mühl ee686a36eb chore: complete v1.0 MVP milestone 
Archive milestone artifacts, evolve PROJECT.md, reorganize ROADMAP.md,
write retrospective. Requirements archived to milestones/v1.0-REQUIREMENTS.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-10 08:05:53 +00:00

2.3 KiB
Raw Blame History

Project Retrospective

A living document updated after each milestone. Lessons feed forward into future planning.

Milestone: v1.0 — MVP

Shipped: 2026-04-10 Phases: 3 | Plans: 5

What Was Built

  • Nix flake producing claudebox wrapper: bwrap sandbox with clearenv, env allowlist, tmpfs root, secret path hiding, git identity forwarding, comma/nix tool access
  • CLI diagnostic modes: --check (environment validation), --dry-run (print bwrap command), --shell (debug shell)
  • Pre-launch env audit with grouped sections, sensitive value masking, Y/n confirmation prompt
  • SANDBOX.md generation and CLAUDE.md import management so Claude knows its sandbox constraints

What Worked

  • writeShellApplication with builtins.readFile pattern — shellcheck at build time, shell syntax highlighting in editors
  • Rapid phase execution: Phase 1 in ~2 min, Phase 2 in ~4 min, Phase 3 in ~76 sec
  • clearenv + allowlist approach caught all secret leakage by default
  • readlink -f fix for NixOS symlinks was discovered and fixed in-phase without blocking

What Was Inefficient

  • REQUIREMENTS.md traceability table not updated during execution — 7 requirements showed "Pending" despite being complete
  • Phase 3 context was gathered but not executed in the same session, requiring session continuity overhead

Patterns Established

  • readlink -f for all host-resolved binaries passed into bwrap (NixOS symlink chains)
  • SANDBOX.md as separate file with @import in CLAUDE.md (keeps user content clean, sandbox instructions always fresh)
  • export trick for shellcheck SC2034 when a variable is used in a later plan but not yet

Key Lessons

  1. On NixOS, every host binary path is a symlink chain through /etc/profiles/per-user/ — must resolve to real store paths before passing to bwrap
  2. Conditional mounts needed for cross-distro support (/etc/static exists only on NixOS)

Cost Observations

  • Model mix: predominantly opus for execution
  • Sessions: ~3 sessions across 2 days
  • Notable: entire v1.0 MVP shipped in under 2 days of wall clock time

Cross-Milestone Trends

Process Evolution

Milestone Phases Plans Key Change
v1.0 3 5 Initial project — established sandbox patterns

Top Lessons (Verified Across Milestones)

  1. (Will populate as more milestones complete)