# Weave Template (Claude)

A spec-driven FABRIC experiment template designed and autonomously managed by Claude Code.

## What It Does

The default experiment:

1. **Deploys** a single Ubuntu 22.04 VM on a randomly-selected FABRIC site (verified available)
2. **Measures** CPU, memory, and network utilization for 60 seconds
3. **Collects** results as JSON to the local `data/` directory
4. **Analyzes** data and writes summary statistics
5. **Monitors** the slice until you click Stop (which deletes it)

## File Structure

```
Weave_Template__Claude_/
├── weave.json              # Weave manifest: args, topology, metadata
├── weave.sh                # Thin orchestrator (SIGTERM handling, monitor loop)
├── experiment.py           # Python lifecycle: start/stop/monitor/collect/analyze
├── tools/
│   └── setup-node.sh       # VM boot script: installs sysstat, jq
├── notebooks/
│   ├── progress.ipynb      # Experiment setup description + live status cell
│   └── results.ipynb       # Full report: motivation, methodology, graphs, conclusion
├── docs/
│   ├── spec-template.md    # Interactive spec walkthrough template
│   ├── roadmap-template.md # Project roadmap template
│   └── testing-template.md # Testing plan template
├── data/                   # Experiment results (created at runtime)
│   ├── vmstat.json         # CPU data (1-second intervals)
│   ├── memory.json         # Memory data (1-second intervals)
│   ├── network.json        # Network throughput data (1-second intervals)
│   ├── metadata.json       # Run metadata (site, times, config)
│   └── summary.json        # Aggregated statistics
└── README.md               # This file
```

## How to Use

### Run the Default Experiment

1. Open **Artifacts** in the WebUI
2. Find "Weave Template (Claude)" and click **Run**
3. Optionally adjust the Slice Name and Duration
4. Watch progress in the Build Log
5. When complete, open `notebooks/results.ipynb` for graphs and analysis
6. Click **Stop** to tear down the slice

### Design Your Own Experiment

Use the `/design-experiment` skill to walk through creating a custom spec:

```
/design-experiment
```

This interactive walkthrough asks targeted questions about your research goals,
infrastructure needs, and measurement strategy — then generates:
- `docs/spec.md` — Complete experiment specification
- `docs/roadmap.md` — Phased implementation plan
- `docs/testing.md` — Testing procedures

### Available Skills

| Skill | Description |
|-------|-------------|
| `/design-experiment` | Interactive walkthrough to create spec + roadmap + testing docs |
| `/run-experiment` | Autonomously run an experiment from a completed spec |
| `/collect-data` | Collect data from running experiment nodes |
| `/analyze-data` | Analyze collected data and create visualizations |

### Available Agents

| Agent | Description |
|-------|-------------|
| `@spec-architect` | Expert at facilitating experiment design walkthroughs |
| `@experiment-runner` | Autonomous experiment execution and monitoring |
| `@data-engineer` | Data collection, analysis, and visualization |

## Customizing the Template

The default experiment is intentionally simple. To build more complex experiments:

1. **More nodes:** Add entries to the `nodes` array in `weave.json`
2. **Networks:** Add L2Bridge, FABNetv4, or other network types
3. **Special hardware:** Add GPU, FPGA, or SmartNIC components
4. **Custom metrics:** Extend `experiment.py` with your measurement logic
5. **Parameter sweeps:** See the IPERF3 benchmark weave for patterns

## Slice Lifecycle

```
weave.sh start → experiment.py start → [deploy VM, measure, collect, analyze]
                                         ↓
                  experiment.py monitor → [health checks every 30s]
                                         ↓
weave.sh Stop  → experiment.py stop   → [delete slice]
```
