Lab Specification — Module 0.2: The Ecosystem

# In a Codespace or local shell
sudo apt-get update && sudo apt-get install -y cloc   # or: brew install cloc (macOS)
mkdir ecosystem-lab && cd ecosystem-lab

# Terminal — Pi (minimal baseline) OR Aider if Pi URL is unavailable
git clone --depth 1 https://github.com/Aider-AI/aider
# Terminal — OpenCode (large client/server)
git clone --depth 1 https://github.com/sst/opencode
# Meta-harness — oh-my-opencode (if public) OR use Aider + OpenCode as your 2 terminals

cloc <repo-dir> --exclude-dir=node_modules,.git,vendor,dist,build
git -C <repo-dir> log --oneline | wc -l    # commit count (remove --depth 1 above for full history)

[Child] exists because [parent] [specific deficiency], so [child] adds
[specific architectural contribution] to fix it. The tradeoff [child]
accepts is [cost of the fix].

# Lab Specification — Module 0.2: The Ecosystem

**Course**: Master Course — Harness Engineering
**Module / Section**: 0 / 0.2
**Duration**: 45–60 minutes
**Environment**: GitHub Codespace (recommended) or local Git + `cloc`. No API keys required.

---

## Learning objectives

By the end of this lab you will have:

1. **Measured** the actual scale (LOC, commit count) of three harnesses across categories — making the Module 0.1 thickness spectrum concrete as data.
2. **Annotated** the lineage map with real numbers — so the parent→child diffs become visible as scale, not just as prose.
3. **Classified** five real harnesses into the seven categories and predicted where each one's interesting engineering lives.
4. **Read** one fork's README against its parent's and stated the design disagreement in one sentence.

---

## Phase 0 — Environment setup (5 min)

```bash
# In a Codespace or local shell
sudo apt-get update && sudo apt-get install -y cloc   # or: brew install cloc (macOS)
mkdir ecosystem-lab && cd ecosystem-lab
```

**Expected output**: `cloc --version` prints a version number.

---

## Phase 1 — Measure three harnesses (15 min)

Clone one harness from each of three categories and measure them side by side.

```bash
# Terminal — Pi (minimal baseline) OR Aider if Pi URL is unavailable
git clone --depth 1 https://github.com/Aider-AI/aider
# Terminal — OpenCode (large client/server)
git clone --depth 1 https://github.com/sst/opencode
# Meta-harness — oh-my-opencode (if public) OR use Aider + OpenCode as your 2 terminals
```

> **Repo note**: the course ecosystem map is the source of truth for current URLs. If a named repo has moved, substitute the closest equivalent in the same category — the lab's point is the *scale comparison*, not a specific URL.

For each:

```bash
cloc <repo-dir> --exclude-dir=node_modules,.git,vendor,dist,build
git -C <repo-dir> log --oneline | wc -l    # commit count (remove --depth 1 above for full history)
```

### Fill in this table

| Harness | Category | Primary language | Total LOC | Commit count | LOC ratio vs smallest |
| --- | --- | --- | --- | --- | --- |
| (smallest) | terminal | | | | 1× |
| | | | | | |
| | | | | | |

**Expected output**: a three-row table. The LOC ratio column should show a dramatic spread (typically 20×–50× from thinnest to thickest in the terminal category alone).

---

## Phase 2 — Annotate the lineage map (10 min)

Take the lineage map from `02-diagrams.md` (Diagram 2) and write each harness's LOC next to its node. Then answer:

1. Do the forks (NemoClaw, Scout) have *more* code than their parent (OpenClaw), or less? What does that tell you about where their contribution lives?
2. oh-my-opencode vs OpenCode — what is the LOC delta? That delta is the meta-harness contribution (routing + subagent hierarchy). Is it large or small relative to the base?
3. Does the scale ordering match the Module 0.1 thickness-spectrum ordering? Where does it diverge, and what does the divergence tell you? (A harness can be large in LOC but thin in *conceptual* thickness — e.g. verbose but few tools.)

---

## Phase 3 — Classify and predict (10 min)

For each of the following, state: (a) the category, (b) where the interesting engineering lives, (c) which rubric module to read first.

| Harness | (a) Category | (b) Interesting in | (c) Read rubric module first |
| --- | --- | --- | --- |
| Aider | | | |
| OpenClaw | | | |
| Hermes | | | |
| NemoClaw | | | |
| LangGraph | | | |
| OpenAI Agents SDK | | | |

**Self-check** against the teaching document §2 and §6. The point is not memorization — it is that the category *predicts* (b) and (c). If you cannot predict, re-read the seven-category table.

---

## Phase 4 — Read one fork against its parent (10 min)

Pick either NemoClaw (vs OpenClaw) or oh-my-opencode (vs OpenCode). For your chosen fork:

1. Read both READMEs (parent and child) in full.
2. Find the section where the child explains *why it exists* or *what it adds*.
3. State the design disagreement in **one sentence**, using this template:

```
[Child] exists because [parent] [specific deficiency], so [child] adds
[specific architectural contribution] to fix it. The tradeoff [child]
accepts is [cost of the fix].
```

**Example (NemoClaw)**: *NemoClaw exists because OpenClaw's trust architecture lets untrusted channel content reach the model without a clean boundary, so NemoClaw adds a NeMo Guardrails layer outside the agent's reach to evaluate every model call. The tradeoff NemoClaw accepts is additional latency on every call and reduced agent autonomy.*

**Expected output**: one filled-in template sentence. If your sentence does not name a *specific deficiency* and a *specific architectural contribution*, re-read — you have produced a feature description, not a design disagreement.

---

## Deliverables

Submit `lab-0.2-report.md` containing:

- [ ] Phase 1: the LOC/commit table (3 rows)
- [ ] Phase 2: the three answered questions + the annotated lineage map (LOC per node)
- [ ] Phase 3: the 6-row classification table
- [ ] Phase 4: the one-sentence design-disagreement statement

---

## Solution key (instructor / self-grader)

Key checks:

- **Phase 1**: LOC ratios should span at least an order of magnitude across the terminal category. Aider (~25k LOC Python) vs OpenCode (much larger, TypeScript client/server) is a clean comparison. If all three are within 2× of each other, the learner picked harnesses from the wrong end of the spectrum — re-pick.
- **Phase 2 Q1**: hardened forks are typically *smaller* in net new code than parents — because their contribution is a layer, not a reimplementation. If a learner reports NemoClaw as larger, they counted inherited OpenClaw code.
- **Phase 2 Q2**: oh-my-opencode's delta over OpenCode should be modest relative to the base — confirming "meta-harness extends, does not replace."
- **Phase 3**:
  - Aider → Terminal → loop+tools → Module 1
  - OpenClaw → Platform → cross-channel trust → Module 6
  - Hermes → Platform → memory architecture → Module 4
  - NemoClaw → Hardened fork → governance layer only → Module 6/11
  - LangGraph → Orchestration framework → state-machine semantics → Module 8
  - OpenAI Agents SDK → SDK/runtime → loop/tool/sandbox abstraction → Module 5
- **Phase 4**: a correct statement names a *specific* deficiency (not "it was missing features") and a *specific* contribution (an architectural layer/decision, not a feature list).

---

## Stretch goals

1. **Add a 4th harness from a different category** (e.g. Mastra for SDK, OpenHarness for academic). Does the category-to-LOC pattern hold across categories, or do different categories have different scale profiles?
2. **Compute "conceptual thickness" vs "LOC thickness"**: count the tools in each harness's tool registry (search for `input_schema` or tool definition patterns). Plot tools vs LOC. The harnesses that are high-LOC but low-tool are doing something other than capability expansion — what? (Bridge to Module 3 context management.)
3. **Read the `hermes claw migrate` tool's source** if available. What does the migration actually rewrite? The answer tells you exactly which OpenClaw assumptions Hermes rejected.