Skip to content

Commit 493a401

Browse files
claudeclaude
committed
feat(vision): VISION.md-driven meta-loop above the conductor
A meta-orchestration layer one level above a single goal. A VISION.md (north-star mission + guardrails + ordered objectives + hard limits) drives a bounded loop that draws work from BOTH the objectives and a monitored signal inbox, delegates one item per tick to the conductor, and records the outcome to the shared brain so thinking compounds. - vision-file: parse/scaffold VISION.md, toggle objective checkboxes - signals: JSONL inbox for the monitored source (bugs, CI, issues) - vision-loop: select (signals outrank objectives) -> guardrail-gate -> brain-dedupe (no repeats) -> delegate (injected) -> record -> mark done - guardrails: maxIterations, maxIterationsPerDay, consecutive-failure circuit breaker, requireApproval, daily-resetting persisted state - stackmemory conductor vision init|status|signal|plan|run - run is plan-only unless --delegate-cmd is given (anti-haywire default) - 13 tests; docs/guides/VISION.md https://claude.ai/code/session_01Gk8DiqCeG9uMaWT9RprwP1
1 parent e31551e commit 493a401

9 files changed

Lines changed: 1436 additions & 0 deletions

File tree

‎docs/guides/VISION.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# StackMemory Vision — the 24/7 meta-loop
2+
3+
> Your agents run 24/7. A single goal isn't enough to keep them on track — and
4+
> too loose a goal makes them go haywire. **VISION.md** is the guardrail: a
5+
> north-star mission, hard limits, and an ordered objective list. The vision
6+
> loop runs one level above any single task, drawing work from both the
7+
> objectives *and* a monitored signal source, delegating to the conductor, and
8+
> recording every conclusion to the shared brain so thinking compounds.
9+
10+
```
11+
VISION.md (mission + guardrails + objectives + limits)
12+
│
13+
signals ──► vision loop ──► consult brain ──► conductor ──► PR
14+
(bugs, CI, │ guardrails │ (no repeats) (executor)
15+
issues) │ checked ▼
16+
└──────────────► record outcome ──► brain (compounds)
17+
```
18+
19+
This is the layer that turns "build a feature" into "build the app" and "fix a
20+
bug" into "watch the bug stream and fix them as they arrive."
21+
22+
## Quick start
23+
24+
```bash
25+
stackmemory conductor vision init # scaffold VISION.md
26+
$EDITOR VISION.md # set the mission, scope, objectives
27+
stackmemory conductor vision plan # dry-run: what's the next action?
28+
stackmemory conductor vision run --once --dry-run
29+
30+
# Act for real — provide how to delegate one objective:
31+
stackmemory conductor vision run --delegate-cmd 'claude -p "{{OBJECTIVE}}"'
32+
```
33+
34+
> **Safety:** `run` is **plan-only** unless you pass `--delegate-cmd`. The loop
35+
> never spawns autonomous agents by accident.
36+
37+
## VISION.md format
38+
39+
Plain markdown, so it stays human-editable and reviewable:
40+
41+
```markdown
42+
# Vision
43+
44+
Ship a reliable, self-healing sync layer that any agent can depend on.
45+
46+
## Guardrails
47+
- Stay within the scope below; never touch secrets or deploy/publish.
48+
- Open a PR for review; never merge to the default branch autonomously.
49+
- If an objective is ambiguous or risky, stop and ask a human.
50+
51+
## Scope
52+
- src/**
53+
- docs/**
54+
55+
## Objectives
56+
- [ ] add retry with jitter to the sync client
57+
- [x] write the protocol types
58+
- [ ] add a `sync status` command
59+
60+
## Limits
61+
maxIterations: 10
62+
maxIterationsPerDay: 50
63+
maxConsecutiveFailures: 3
64+
tickIntervalSec: 60
65+
requireApproval: false
66+
stopWhenComplete: true
67+
```
68+
69+
The loop reloads VISION.md **every tick**, so editing the file (or checking a
70+
box) changes its behavior live.
71+
72+
## Two sources of work
73+
74+
Per the design, the loop draws objectives from **both**:
75+
76+
1. **VISION.md objectives** — the planned, ordered backlog (the "build the app"
77+
direction). Completed objectives get their checkbox ticked automatically.
78+
2. **A monitored signal inbox** — reactive work that arrives over time (the "fix
79+
bugs as they show up" direction):
80+
81+
```bash
82+
stackmemory conductor vision signal "500s on /sync after deploy" --severity high
83+
```
84+
85+
Anything can feed it — a CI hook, a GitHub-issue poller, a bug-report
86+
webhook — by appending to `.stackmemory/vision/signals.jsonl` or calling the
87+
`signal` command. **Pending signals outrank objectives**, so urgent issues
88+
preempt planned work, bounded by the same guardrails.
89+
90+
## Guardrails (the anti-haywire layer)
91+
92+
Every tick is gated by `## Limits`:
93+
94+
| Limit | Effect |
95+
|-------|--------|
96+
| `maxIterations` | objectives handled per `run` |
97+
| `maxIterationsPerDay` | objectives handled per calendar day (persisted) |
98+
| `maxConsecutiveFailures` | circuit breaker — stop after N failures in a row |
99+
| `tickIntervalSec` | delay between ticks |
100+
| `requireApproval` | when true, the loop only plans + queues, never delegates |
101+
| `stopWhenComplete` | stop once objectives are done and no signals remain |
102+
103+
Loop state (today's count, consecutive failures) lives in
104+
`.stackmemory/vision/state.json` and resets daily.
105+
106+
## Brain integration (compounding)
107+
108+
Before delegating, the loop asks the [brain](./BRAIN.md) whether this exact work
109+
was already concluded — if so it **skips it** (and ticks the objective), so the
110+
loop never repeats itself across machines or agents. After delegating, the
111+
outcome is recorded as a brain `experiment` (agent `vision`) with the
112+
conclusion, tags, and refs — feeding the same compounding memory every other
113+
agent reads.
114+
115+
## Running it on the portal (24/7)
116+
117+
On your Hetzner + Tailscale [portal](./PORTAL.md) box, run the loop inside the
118+
tmux session so it survives disconnects:
119+
120+
```bash
121+
# inside the tmux 'claude' session
122+
stackmemory conductor vision run \
123+
--delegate-cmd 'claude -p "{{OBJECTIVE}}. Stay within VISION.md scope. Open a PR."'
124+
```
125+
126+
Check in from any device via the portal; the loop keeps working the vision and
127+
the signal stream while you experience life.
128+
129+
## CLI
130+
131+
```bash
132+
stackmemory conductor vision init [--force]
133+
stackmemory conductor vision status [--json]
134+
stackmemory conductor vision signal <text> [--severity] [--source] [--refs]
135+
stackmemory conductor vision plan [--max <n>]
136+
stackmemory conductor vision run [--once] [--max <n>] [--dry-run] \
137+
[--delegate-cmd <tpl>] [--timeout <sec>]
138+
```
139+
140+
`--delegate-cmd` substitutes `{{OBJECTIVE}}`, `{{KIND}}`, and `{{REFS}}`.
141+
142+
## Files
143+
144+
| Path | Purpose |
145+
|------|---------|
146+
| `src/core/vision/vision-file.ts` | VISION.md parse / scaffold / objective toggle |
147+
| `src/core/vision/signals.ts` | monitored signal inbox (JSONL) |
148+
| `src/core/vision/vision-loop.ts` | the guardrailed loop (select → gate → dedupe → delegate → record) |
149+
| `src/cli/commands/vision.ts` | `stackmemory conductor vision` command |

‎src/cli/commands/orchestrate.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ import Database from 'better-sqlite3';
2525
import { logger } from '../../core/monitoring/logger.js';
2626
import { isProcessAlive } from '../../utils/process-cleanup.js';
2727
import { Conductor } from './orchestrator.js';
28+
import { createVisionCommand } from './vision.js';
2829
import {
2930
getAgentStatusDir,
3031
getOutcomesLogPath,
@@ -903,6 +904,9 @@ export function createConductorCommands(): Command {
903904
cmd.help();
904905
});
905906

907+
// --- vision (meta-loop above the conductor) ---
908+
cmd.addCommand(createVisionCommand());
909+
906910
// --- capture ---
907911
cmd
908912
.command('capture')

0 commit comments

Comments
 (0)