custom-claude-skills/memory/log/2026-03-24.215106.md

Session Log — 2026-03-24

Summary

Designed the M3 composable agent harness architecture for agent-runtimes, wrote the full plan and had a container agent write the harness spec. Created two new skills (/decompose and /orchestrate) for task decomposition and container agent dispatch with git worktree isolation.

Decisions

• Decision: Harnesses live in a separate agent-harnesses repo under skynet org — Rationale: Versioned independently from agent-runtimes, allows different teams/projects to share harness definitions
• Decision: Three harness kinds (capability, context, composite) — Rationale: Separation of concerns between container overlays (tools) and session config (identity, context, skills)
• Decision: Context files mount at unique paths per layer, use --append-system-prompt-file — Rationale: Claude Code's native mechanism, no lossy merging, preserves all context layers distinctly
• Decision: Heavy capability layers use OCI mod images (LinuxServer.io pattern) — Rationale: Runtime install too slow for JDK/Rust; single-layer OCI images with modcache provide fast cached extraction
• Decision: Harness-injected actions with payload suppress — Rationale: Cross-cutting concerns (session logging) belong in harness, but payload must be able to override
• Decision: Git worktrees for container agent task isolation — Rationale: No file conflicts between concurrent agents, clean per-task branches, dependency chains branch from parent output
• Decision: No hardcoded concurrency limit — user approves max_concurrent during /decompose — Rationale: Token usage happens regardless of parallelism; more agents = faster, not more expensive
• Decision: Container agents launched with docker run -d (no --rm) — Rationale: Logs must survive for inspection after container exit

Gotchas Discovered

• [docker] Symptom: Container agent failed with "No payload" error when launched with docker run ... agent-claude:latest claude --print ... — Fix: Must use --entrypoint uid-wrapper.sh to override the default entrypoint (which expects AGENT_PAYLOAD env var). The claude-container.sh script handles this correctly.
• [skills] Symptom: validate-skill failed on decompose skill with "Command binary 'ls' not covered" — Fix: Bang-command !ls spec/`` requires Bash(ls *) in allowed-tools. Every binary in bang-commands must be explicitly covered.
• [skills] Symptom: validate-skill warned about Bash(git *) being too broad in orchestrate skill — Fix: Acceptable warning — orchestrate needs worktree add/remove, branch, merge, and checkout. Specific subcommand patterns would need 6+ entries.

Key Context

• LangChain research showed 52.8% → 66.5% improvement on Terminal Bench by modifying only the harness, not the model — validates harness design as highest-leverage work
• Claude Code's --append-system-prompt-file is the native context injection mechanism (one flag per file, preserves built-in prompt)
• Skills auto-discovered from .claude/skills/ — just mount them into containers
• Anthropic's reference devcontainer uses iptables firewall allowlisting (adopted into our harness design)
• OpenCode reads CLAUDE.md and ~/.claude/skills/ by default — cross-tool compatibility is free
• K8s Agent Sandbox CRD (SIG Apps, March 2026) worth evaluating for M9
• 95% step problem: 20 steps at 95% each = 36% success — keep harness layers to 3-5

Process Notes

• Container agent successfully wrote a 426-line spec from a detailed prompt — validates the pattern of using container agents for substantial spec/code work
• Research phase used 3 parallel agents effectively: LinuxServer.io patterns, broader container composition, and existing codebase analysis
• Second research round (Claude devcontainers, OpenCode, 2026 best practices) surfaced important design refinements that improved the plan
• The /decompose + /orchestrate + /loop workflow creates a "manager session" pattern where the human drives strategy while agents execute in parallel