substrate-ai 0.2.34 → 0.2.35
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -1,22 +1,63 @@
|
|
|
1
1
|
<!-- substrate:start -->
|
|
2
2
|
## Substrate Pipeline
|
|
3
3
|
|
|
4
|
-
This project uses Substrate for automated implementation pipelines.
|
|
5
|
-
|
|
6
|
-
###
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
4
|
+
This project uses Substrate for automated implementation pipelines. Substrate runs are long-running (5–40 minutes). Plan accordingly.
|
|
5
|
+
|
|
6
|
+
### Running the Pipeline
|
|
7
|
+
|
|
8
|
+
**Preferred — Supervisor mode** (handles stalls, auto-restarts, post-run analysis):
|
|
9
|
+
```
|
|
10
|
+
substrate supervisor --output-format json --stories 7-1,7-2
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
**Direct mode** (simpler, no auto-recovery):
|
|
14
|
+
```
|
|
15
|
+
substrate run --events --stories 7-1,7-2
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
**CRITICAL execution rules:**
|
|
19
|
+
- Pipeline runs take **5–40 minutes**. You MUST use `run_in_background: true` or `timeout: 600000` (10 min) when invoking via Bash tool. Default 2-minute timeout WILL kill the pipeline.
|
|
20
|
+
- **NEVER pipe substrate output** to `head`, `tail`, `grep`, or any command that may close the pipe early — this causes EPIPE stalls that hang the process.
|
|
21
|
+
- **DO NOT use `Task Output`** to monitor substrate — Claude Code task IDs do not map to substrate's internal processes.
|
|
22
|
+
- For full event protocol and command reference: `substrate run --help-agent`
|
|
23
|
+
|
|
24
|
+
### Monitoring (while pipeline is running)
|
|
25
|
+
|
|
26
|
+
Poll status periodically (every 60–90s):
|
|
27
|
+
```
|
|
28
|
+
substrate status --output-format json
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Check process health if pipeline seems quiet:
|
|
32
|
+
```
|
|
33
|
+
substrate health --output-format json
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**Interpreting silence:** No output for 5 minutes = normal (agent is working). No output for 15+ minutes = likely stalled. Use `substrate health` to confirm, then consider killing and resuming.
|
|
37
|
+
|
|
38
|
+
### After Pipeline Completes
|
|
39
|
+
|
|
40
|
+
1. **Summarize results** conversationally: X succeeded, Y failed, Z escalated
|
|
41
|
+
2. **Check metrics**: `substrate metrics --output-format json`
|
|
42
|
+
3. **Read analysis** (if supervisor mode): `substrate metrics --analysis <run_id> --output-format json`
|
|
43
|
+
|
|
44
|
+
### Handling Escalations and Failures
|
|
45
|
+
|
|
46
|
+
- **On story escalation**: read the flagged files and issues listed in the escalation event, propose a fix, ask the user before applying
|
|
47
|
+
- **On minor fix verdict** (`NEEDS_MINOR_FIXES`): offer to fix automatically
|
|
48
|
+
- **On build verification failure**: read the build output, diagnose the compiler error, propose a fix
|
|
49
|
+
- **On contract mismatch** (`pipeline:contract-mismatch`): cross-story interface conflict — read both stories' files, reconcile types manually
|
|
50
|
+
- **Never re-run a failed story** without explicit user confirmation
|
|
51
|
+
|
|
52
|
+
### Key Commands Reference
|
|
53
|
+
|
|
54
|
+
| Command | Purpose |
|
|
55
|
+
|---|---|
|
|
56
|
+
| `substrate run --events` | Run pipeline with NDJSON event stream |
|
|
57
|
+
| `substrate supervisor --output-format json` | Run with auto-recovery and analysis |
|
|
58
|
+
| `substrate status --output-format json` | Poll current pipeline state |
|
|
59
|
+
| `substrate health --output-format json` | Check process health and stall detection |
|
|
60
|
+
| `substrate metrics --output-format json` | View historical run metrics |
|
|
61
|
+
| `substrate resume` | Resume an interrupted pipeline run |
|
|
62
|
+
| `substrate run --help-agent` | Full agent instruction reference (487 lines) |
|
|
22
63
|
<!-- substrate:end -->
|