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>

.reflection-state.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "last_run": "2026-03-24T10:36:46Z",
+  "processed": {
+    "memory/log/2026-03-17.110845.md": "5ac7f82c96613876a4ecf7f2b5506edf",
+    "memory/log/2026-03-24.215106.md": "3e039830da10338af26d31fc0959dff1"
+  }
+}

MEMORY.md

@@ -11,6 +11,11 @@
 - **Broad `Bash(git *)` is acceptable when justified:** orchestrate skill needs worktree/branch/merge/checkout — listing 6+ specific subcommands is worse than the broad pattern with a validator warning
 - **Skills that launch containers need careful entrypoint handling:** Use `--entrypoint uid-wrapper.sh` when running `claude --print` in agent containers — the default entrypoint expects AGENT_PAYLOAD
 
+## Topic Files
+
+- [Process Lessons](memory/process-lessons.md) — Container agent workflow patterns, skill development rules
+- [Decisions](memory/decisions.md) — Task orchestration architecture decisions, harness design rationale
+
 ## Task Orchestration Skills (2026-03-24)
 
 Added `/decompose` and `/orchestrate` for parallel container agent work:

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.

skills/decompose/SKILL.md

@@ -63,6 +63,8 @@ For each subtask, determine:
 - **End every prompt with:** "Run `pytest tests/ -v --tb=short` and fix any failures before finishing. Write a session log to memory/log/ when done."
 - **State import conventions explicitly** in prompts — e.g., "Use `from module import X`, not `from .module import X`" when source dirs aren't packages
 - **Before writing .agent-tasks.json, warn the user to commit WIP** if there are untracked/uncommitted files that agents will need. Worktrees only see committed content.
+- **Set the `model` field** for each task. Use `claude-opus-4-20250514` for research, architecture, and complex reasoning tasks. Use `claude-sonnet-4-20250514` (or omit for default) for code generation, testing, and mechanical tasks. Ask the user if unsure.
+- **Do NOT include "use web search" in prompts.** Container agents cannot web search. If a task requires current data verification, note this in the task description so the user can validate from their main session after the agent completes.
 
 ### Step 3: Present the task graph
 
@@ -102,6 +104,7 @@ Once approved, write `.agent-tasks.json` in the project root:
     "<task-id>": {
       "name": "<human readable name>",
       "prompt": "<full prompt for container agent>",
+      "model": "<optional model override, e.g. claude-opus-4-20250514>",
       "depends_on": ["<task-id>", ...],
       "reads": ["<file paths the agent should read>"],
       "writes": ["<file paths the agent will create/modify>"],

skills/orchestrate/SKILL.md

@@ -98,6 +98,11 @@ This step is critical — worktrees only contain committed content. Without it,
 
 #### 3c. Launch the container
 
+Determine the model to use:
+- Read the task's `model` field from `.agent-tasks.json`
+- If `model` is set, use that value (e.g., `claude-opus-4-20250514`, `claude-sonnet-4-20250514`)
+- If `model` is not set or null, default to `claude-sonnet-4-20250514`
+
 ```bash
 docker run -d \
   -e CLAUDE_CODE_OAUTH_TOKEN="<token>" \
@@ -106,7 +111,7 @@ docker run -d \
   -w /project \
   --entrypoint uid-wrapper.sh \
   agent-claude:latest \
-  claude --print --dangerously-skip-permissions --model claude-sonnet-4-20250514 "<task prompt>"
+  claude --print --dangerously-skip-permissions --model <model> "<task prompt>"
 ```
 
 **Important:**
@@ -115,6 +120,7 @@ docker run -d \
 - Capture the container ID from docker run output
 - The CLAUDE_CODE_OAUTH_TOKEN must be available in the current environment. If not set, read it from `~/dev/claude/secrets/claude/long_lived_oauth_token` (extract the value after `value: `)
 - If the task's `reads` list references paths outside the project (e.g., `/foundations` for best practices), mount those as additional read-only volumes
+- Container agents do NOT have web search capability. Do not include "use web search" in task prompts unless web search support has been explicitly configured for the container.
 
 After launching, update the task in `.agent-tasks.json`:
 - Set `status` to `running`