Add reflected memory and update decompose/orchestrate skills

Adds decisions and process-lessons from recent reflections.
Updates decompose and orchestrate SKILL.md with operational improvements.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

memory/decisions.md

@@ -0,0 +1,21 @@
+# Architecture Decisions
+
+## Git worktrees for container agent task isolation
+
+Each container agent gets its own git worktree branch. This prevents file conflicts between parallel agents and makes merging results straightforward with standard git operations.
+
+## No hardcoded concurrency limit
+
+The `max_concurrent` value is set by the user during `/decompose`, not baked into the skill. Different tasks have different parallelism needs — a refactor across 10 files can run 10 agents, while a sequential pipeline needs 1-2.
+
+## Container agents launched with docker run -d (no --rm)
+
+Using `-d` without `--rm` ensures container logs survive for debugging. The orchestrator checks exit codes and retrieves logs from stopped containers. Cleanup is explicit, not automatic.
+
+## Harness design is highest-leverage for agent quality
+
+Research showed LangChain benchmark scores jumped from 52.8% to 66.5% from harness improvements alone (context injection, tool selection, prompt structure). Model choice matters less than giving the model good context and tools.
+
+## Keep harness layers to 3-5 (95% step problem)
+
+Each harness layer that must succeed is a multiplicative failure point. At 95% reliability per step, 10 steps = 60% overall success. Keep the critical path short — 3-5 layers max.

memory/log/2026-03-24.215106.md

@@ -0,0 +1,39 @@
+# 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

memory/process-lessons.md

@@ -0,0 +1,17 @@
+# Process Lessons
+
+## Container agent prompts need high detail for quality output
+
+Container agents produce substantial output (e.g., 426-line spec) when given detailed, structured prompts. Invest time in prompt crafting during `/decompose` — the agent has no conversation history to draw from.
+
+## Use 3+ parallel research agents before planning
+
+Survey different domains (competing tools, best practices, user patterns) in parallel before committing to an architecture. The breadth of input prevents tunnel vision during planning.
+
+## The decompose/orchestrate/loop pattern creates a manager session
+
+Human drives strategy via `/decompose`, agents execute via `/orchestrate`, and `/loop 2m /orchestrate` auto-polls progress. The human's role shifts from doing to reviewing and steering.
+
+## Always run validate-skill before committing skill changes
+
+The validator catches restriction violations (uncovered binaries, `$()` substitution, `${VAR}` syntax) that silently break skills at load time. Run it as a pre-commit gate, not an afterthought.