System Deep Loop
One skill has two active workflow families and one nested runtime layer.
system-deep-loop is the public, advisor-routable home for active deep-loop personas.
runtime/ is the frozen, MCP-free infrastructure layer it consumes.
This hub holds NO per-mode convergence, state or synthesis logic.
Each active mode keeps its own contract in its packet. The hub only routes by workflowMode through mode-registry.json.
Version authority. This file's version frontmatter is the hub's release version and matches the newest entry under changelog/; description.json, mode-registry.json and hub-router.json carry the same value, so every hub-root JSON routing file states the same release; ROUTER.md keeps its own document version.
Use @context for one-shot retrieval, /deep:research for iterative investigation with a bounded context snapshot, /deep:review for iterative audit with a bounded review snapshot, or /speckit:plan for implementation planning.
1. WHEN TO USE
Use this skill (through the hub) for any active deep-loop workflow. Invoke it as Skill(system-deep-loop) (optionally with a mode hint such as research: <request>); the hub classifies the request, resolves a workflowMode, and loads the matching nested mode packet. Active /deep:* commands and native agent types remain as complementary surfaces over the same packets.
| Mode |
Use it for |
Packet |
Command |
Agent |
| research |
Outward, web + code iterative investigation → research/research.md |
system-deep-loop/deep-research/ |
/deep:research |
deep-research |
| review |
Iterative review loop → P0/P1/P2 findings + verdict |
system-deep-loop/deep-review/ |
/deep:review |
deep-review |
A planning council is not a mode of this hub. It runs as the standalone @ai-council agent, reached through /speckit:ai-council.
When NOT to Use
- A single quick read/edit (no loop) — use the relevant code or doc skill directly.
- Backend/runtime support (executor, coverage-graph, scoring, fan-out) — that is
runtime/, consumed here, not invoked as a user workflow (formerly the separate deep-loop-runtime skill).
2. SMART ROUTING
Routing is registry-driven at runtime and authored in hub-router.json in two stages.
Stage 1 (hub → mode) selects a mode: hub-router.json vocabularyClasses is the one authored vocabulary, and its routerSignals keys are research and review.
The mode-registry.json aliases, each packet's Keyword triggers: line where one exists and the root ROUTER.md intents are checked against it.
Stage 2 (mode → leaves) lives in the root ROUTER.md, which maps the request's deep-loop intent to the packet-local leaf resources that mode loads.
The advisor routes every deep-loop query to the single identity system-deep-loop.
Resolve the mode with node .skilled/bin/compiled-route.cjs --hub system-deep-loop --prompt "<task>".
Compiled routing is the default. route loads its targets, clarify and defer ask, reject refuses.
An unclear deep-loop intent asks for disambiguation, because routerPolicy.defaultMode is null.
The routerPolicy.defaultResource list is only a defer-time suggestion, never a silent default.
Run the compiled-routing directive in ROUTER.md before selecting hub resources.
3. HOW IT WORKS
Terms
workflowMode: the public active mode key, research or review.
runtimeLoopType: the graph-backed convergence key that runtime/scripts/convergence.cjs consumes, validated against research|review, explicitly null for a custom backend and never inferred from workflowMode.
backendKind: runtime-loop-type for both modes, which run on the runtime/ convergence backend.
- mode packet: one of the two nested folders that owns its mode's convergence, state and artifact contract.
runtime/: the frozen, MCP-free layer every mode consumes, holding the executor config, atomic state, coverage graph, Bayesian scoring, fan-out and the seat-dispatch file the divergent pivot uses.
mode-registry.json: the registry that owns each mode's discriminator and its authoritative packet path.
hub-router.json: stage one's signals, vocabulary classes and tie-break order.
vocabularyClasses: the authored deep-loop vocabulary that stage one scores.
UNKNOWN_FALLBACK: the load level the router returns, with its disambiguation checklist, when no mode resolves or the registry has no entry for the mode.
- leaf: a canonical
(workflowMode, leafResourceId) pair from leaf-manifest.json.
defer: the outcome that asks for disambiguation, which this hub reaches because routerPolicy.defaultMode is null.
- advisor projection map: one of the hardcoded advisor maps that a drift-guard test keeps equal to the registry projection.
Layout
system-deep-loop/
SKILL.md # this routing hub (no per-mode logic)
ROUTER.md # stage-two surface router (deep-loop intent -> leaf sets)
mode-registry.json # the three-tier discriminator + advisorRouting (single source of truth)
graph-metadata.json # the ONE advisor identity for the whole skill
deep-research/ deep-review/ # active mode packets
shared/synthesis/ # workflows-shared synthesis (e.g. emitResourceMap)
Always resolve a packet path through mode-registry.json instead of hardcoding it.
Each active mode packet keeps its own SKILL.md, references/, scripts/, assets/, feature-catalog/ or manual-testing-playbook/, as applicable, with internal paths repointed.
Mode packets have no per-packet graph-metadata.json. Only this hub carries one, so the advisor discovers exactly one skill.
Backend
All modes consume runtime/, a frozen, MCP-free layer.
It provides executor config, prompt-pack, validation, atomic state, coverage-graph, Bayesian scoring, fan-out and the seat-dispatch file the divergent pivot uses.
- The offline fan-out pair replay at
runtime/scripts/score-fanout-pairs.cjs reads the merge's own decisions on near-line and cross-body pairs.
- It compares a backend's judgment with the operator's labels and makes no model call by default.
- Until the operator has labeled 40 pairs, 10 of them cross-body, it prints
stop: fewer than 40 labeled pairs.
- It runs its
--jev arm only with --out <dir> and past that backend's own gate.
- It leaves the merge unchanged.
4. RULES
✅ ALWAYS
- ALWAYS resolve a mode through
mode-registry.json (read the packet key; never hardcode a router mapping or packet path in the hub).
- ALWAYS keep advisor projection maps hardcoded and drift-guarded against the registry; command mode routing is still hardcoded in the command files and does not resolve through
mode-registry.json.
- ALWAYS keep each mode's convergence/state/artifact contract in its packet — the hub stays logic-free.
- ALWAYS keep exactly one
graph-metadata.json (this hub's) so the advisor sees one skill identity, whether a mode is reached via Skill(system-deep-loop), a /deep:* command, or an agent.
- ALWAYS keep the root
ROUTER.md RESOURCE_MAP in sync with leaf-manifest.json — the leaf sets dual-read to canonical typed pairs at the one contract boundary.
- ALWAYS keep
Skill(system-deep-loop) hub routing, the /deep:* commands, and the agent types as complementary surfaces over the same packets — never let one surface fork per-mode logic out of its packet.
⛔ NEVER
- NEVER infer
runtimeLoopType from workflowMode — read it from the registry (explicit null is load-bearing).
- NEVER add a
graph-metadata.json or a discoverable skill marker inside a mode packet or shared/.
- NEVER let a CLI lineage dispatch a nested executor for its own iteration, and prefer not to edit tracked files in a checkout with a live lineage (write containment reports them against that lineage; it no longer reverts them, and a lane that produced its artifacts still completes). Both rules live in
deep-research/references/protocol/loop-protocol.md under "Executor Resolution".
⚠️ ESCALATE IF
- A new mode is needed beyond the two registered — extend
mode-registry.json and open a packet, do not bolt logic onto the hub.
- A change would require the runtime to gain MCP tools — that contradicts the architecture; escalate.
5. REFERENCES
- Backend:
.skilled/skills/system-deep-loop/runtime/ (frozen, consumed by every mode; nested infrastructure, not a separate skill).
- Mode packets:
deep-research/SKILL.md, deep-review/SKILL.md (per-mode detail).
- Commands: the active
/deep:* commands under .skilled/commands/deep/ (complementary surface).
- Registry:
mode-registry.json (the routing contract — the authoritative packet paths).
- Surface router:
ROUTER.md (deep-loop intent to packet-local leaf sets).
6. SUCCESS CRITERIA
- The hub resolves one primary active
workflowMode for the request through mode-registry.json (never by array order).
- The selected mode packet owns the detailed convergence/state/artifact workflow; the hub stayed routing-only.
Skill(system-deep-loop[, hint]) reaches a mode, and the /deep:* commands and agent types still reach the same packets.
- Exactly one
graph-metadata.json exists for the whole skill; no packet carries its own.
7. INTEGRATION POINTS
Modes
research — outward web + code iterative investigation (research/research.md).
review — iterative review loop, P0/P1/P2 findings + verdict.
Surfaces and Consumers
Skill(system-deep-loop) is the invokable hub; active /deep:* commands and the agent types (deep-research, deep-review) are complementary surfaces over the same packets.
runtime/ is the frozen, MCP-free backend every mode consumes (nested infrastructure, not a separate skill).
/speckit:plan consumes @context packages plus research/review outputs; spec-folder docs consume research/review output.
8. RELATED RESOURCES
- Pattern:
.skilled/skills/sk-doc/sk-create-skill/references/parent-skill/parent-skills-nested-packets.md (parent-skill hub + nested packets, the one-graph-metadata invariant).
- Sibling example:
.skilled/skills/sk-prompt/ (the same invokable-hub + mode-registry.json Option E pattern).
- Registry:
mode-registry.json (this hub's routing contract).
1---2name: system-deep-loop3version: 2.0.2.04description: "Routes research and review modes through registry-selected packets."5allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task, WebFetch]6metadata:7 source: https://skillmd.com/skills/michelkerkmeester/system-deep-loop8---910<!-- Keywords: system-deep-loop, deep-loop, deep-research, deep-review, autoresearch, iterative-research, review-loop, deep-review-wave, release-readiness, severity-findings, P0-P1-P2, benchmark-harness, convergence-detection, externalized-state, iteration-files, coverage-graph, mode-registry, workflowmode, runtimeloop-type, backendkind -->1112# System Deep Loop1314One skill has two active workflow families and one nested runtime layer.15`system-deep-loop` is the public, advisor-routable home for active deep-loop personas.16`runtime/` is the frozen, MCP-free infrastructure layer it consumes.17This hub holds NO per-mode convergence, state or synthesis logic.18Each active mode keeps its own contract in its packet. The hub only routes by `workflowMode` through `mode-registry.json`.1920**Version authority.** This file's `version` frontmatter is the hub's release version and matches the newest entry under `changelog/`; `description.json`, `mode-registry.json` and `hub-router.json` carry the same value, so every hub-root JSON routing file states the same release; `ROUTER.md` keeps its own document version.2122Use `@context` for one-shot retrieval, `/deep:research` for iterative investigation with a bounded context snapshot, `/deep:review` for iterative audit with a bounded review snapshot, or `/speckit:plan` for implementation planning.2324---2526## 1. WHEN TO USE2728Use this skill (through the hub) for any active deep-loop workflow. Invoke it as `Skill(system-deep-loop)` (optionally with a mode hint such as `research: <request>`); the hub classifies the request, resolves a `workflowMode`, and loads the matching nested mode packet. Active `/deep:*` commands and native agent types remain as complementary surfaces over the same packets.2930| Mode | Use it for | Packet | Command | Agent |31|------|-----------|--------|---------|-------|32| **research** | Outward, web + code iterative investigation → `research/research.md` | `system-deep-loop/deep-research/` | `/deep:research` | `deep-research` |33| **review** | Iterative review loop → P0/P1/P2 findings + verdict | `system-deep-loop/deep-review/` | `/deep:review` | `deep-review` |3435A planning council is not a mode of this hub. It runs as the standalone `@ai-council` agent, reached through `/speckit:ai-council`.3637### When NOT to Use38- A single quick read/edit (no loop) — use the relevant code or doc skill directly.39- Backend/runtime support (executor, coverage-graph, scoring, fan-out) — that is `runtime/`, consumed here, not invoked as a user workflow (formerly the separate deep-loop-runtime skill).4041---4243## 2. SMART ROUTING4445Routing is **registry-driven at runtime and authored in `hub-router.json`** in two stages.46Stage 1 (hub → mode) selects a mode: `hub-router.json` `vocabularyClasses` is the one authored vocabulary, and its `routerSignals` keys are `research` and `review`.47The `mode-registry.json` aliases, each packet's `Keyword triggers:` line where one exists and the root `ROUTER.md` intents are checked against it.48Stage 2 (mode → leaves) lives in the root [`ROUTER.md`](./ROUTER.md), which maps the request's deep-loop intent to the packet-local leaf resources that mode loads.49The advisor routes every deep-loop query to the single identity `system-deep-loop`.50Resolve the mode with `node .skilled/bin/compiled-route.cjs --hub system-deep-loop --prompt "<task>"`.51Compiled routing is the default. `route` loads its `targets`, `clarify` and `defer` ask, `reject` refuses.52An unclear deep-loop intent asks for disambiguation, because `routerPolicy.defaultMode` is `null`.53The `routerPolicy.defaultResource` list is only a defer-time suggestion, never a silent default.54Run the compiled-routing directive in [`ROUTER.md`](./ROUTER.md) before selecting hub resources.5556---5758## 3. HOW IT WORKS5960### Terms6162- **`workflowMode`**: the public active mode key, `research` or `review`.63- **`runtimeLoopType`**: the graph-backed convergence key that `runtime/scripts/convergence.cjs` consumes, validated against `research|review`, explicitly `null` for a custom backend and never inferred from `workflowMode`.64- **`backendKind`**: `runtime-loop-type` for both modes, which run on the `runtime/` convergence backend.65- **mode packet**: one of the two nested folders that owns its mode's convergence, state and artifact contract.66- **`runtime/`**: the frozen, MCP-free layer every mode consumes, holding the executor config, atomic state, coverage graph, Bayesian scoring, fan-out and the seat-dispatch file the divergent pivot uses.67- **`mode-registry.json`**: the registry that owns each mode's discriminator and its authoritative `packet` path.68- **`hub-router.json`**: stage one's signals, vocabulary classes and tie-break order.69- **`vocabularyClasses`**: the authored deep-loop vocabulary that stage one scores.70- **`UNKNOWN_FALLBACK`**: the load level the router returns, with its disambiguation checklist, when no mode resolves or the registry has no entry for the mode.71- **leaf**: a canonical `(workflowMode, leafResourceId)` pair from `leaf-manifest.json`.72- **`defer`**: the outcome that asks for disambiguation, which this hub reaches because `routerPolicy.defaultMode` is `null`.73- **advisor projection map**: one of the hardcoded advisor maps that a drift-guard test keeps equal to the registry projection.7475### Layout76```77system-deep-loop/78 SKILL.md # this routing hub (no per-mode logic)79 ROUTER.md # stage-two surface router (deep-loop intent -> leaf sets)80 mode-registry.json # the three-tier discriminator + advisorRouting (single source of truth)81 graph-metadata.json # the ONE advisor identity for the whole skill82 deep-research/ deep-review/ # active mode packets83 shared/synthesis/ # workflows-shared synthesis (e.g. emitResourceMap)84```8586Always resolve a packet path through `mode-registry.json` instead of hardcoding it.87Each active mode packet keeps its own `SKILL.md`, `references/`, `scripts/`, `assets/`, `feature-catalog/` or `manual-testing-playbook/`, as applicable, with internal paths repointed.88Mode packets have **no per-packet `graph-metadata.json`**. Only this hub carries one, so the advisor discovers exactly one skill.8990### Backend91All modes consume `runtime/`, a frozen, MCP-free layer.92It provides executor config, prompt-pack, validation, atomic state, coverage-graph, Bayesian scoring, fan-out and the seat-dispatch file the divergent pivot uses.9394- The offline fan-out pair replay at `runtime/scripts/score-fanout-pairs.cjs` reads the merge's own decisions on near-line and cross-body pairs.95- It compares a backend's judgment with the operator's labels and makes no model call by default.96- Until the operator has labeled 40 pairs, 10 of them cross-body, it prints `stop: fewer than 40 labeled pairs`.97- It runs its `--jev` arm only with `--out <dir>` and past that backend's own gate.98- It leaves the merge unchanged.99100---101102## 4. RULES103104### ✅ ALWAYS105- **ALWAYS** resolve a mode through `mode-registry.json` (read the `packet` key; never hardcode a router mapping or packet path in the hub).106- **ALWAYS** keep advisor projection maps hardcoded and drift-guarded against the registry; command mode routing is still hardcoded in the command files and does not resolve through `mode-registry.json`.107- **ALWAYS** keep each mode's convergence/state/artifact contract in its packet — the hub stays logic-free.108- **ALWAYS** keep exactly one `graph-metadata.json` (this hub's) so the advisor sees one skill identity, whether a mode is reached via `Skill(system-deep-loop)`, a `/deep:*` command, or an agent.109- **ALWAYS** keep the root `ROUTER.md` `RESOURCE_MAP` in sync with `leaf-manifest.json` — the leaf sets dual-read to canonical typed pairs at the one contract boundary.110- **ALWAYS** keep `Skill(system-deep-loop)` hub routing, the `/deep:*` commands, and the agent types as complementary surfaces over the same packets — never let one surface fork per-mode logic out of its packet.111112### ⛔ NEVER113- **NEVER** infer `runtimeLoopType` from `workflowMode` — read it from the registry (explicit `null` is load-bearing).114- **NEVER** add a `graph-metadata.json` or a discoverable skill marker inside a mode packet or `shared/`.115- **NEVER** let a CLI lineage dispatch a nested executor for its own iteration, and prefer not to edit tracked files in a checkout with a live lineage (write containment reports them against that lineage; it no longer reverts them, and a lane that produced its artifacts still completes). Both rules live in `deep-research/references/protocol/loop-protocol.md` under "Executor Resolution".116117### ⚠️ ESCALATE IF118- A new mode is needed beyond the two registered — extend `mode-registry.json` and open a packet, do not bolt logic onto the hub.119- A change would require the runtime to gain MCP tools — that contradicts the architecture; escalate.120121---122123## 5. REFERENCES124125- Backend: `.skilled/skills/system-deep-loop/runtime/` (frozen, consumed by every mode; nested infrastructure, not a separate skill).126- Mode packets: `deep-research/SKILL.md`, `deep-review/SKILL.md` (per-mode detail).127- Commands: the active `/deep:*` commands under `.skilled/commands/deep/` (complementary surface).128- Registry: `mode-registry.json` (the routing contract — the authoritative `packet` paths).129- Surface router: `ROUTER.md` (deep-loop intent to packet-local leaf sets).130131---132133## 6. SUCCESS CRITERIA134135- The hub resolves one primary active `workflowMode` for the request through `mode-registry.json` (never by array order).136- The selected mode packet owns the detailed convergence/state/artifact workflow; the hub stayed routing-only.137- `Skill(system-deep-loop[, hint])` reaches a mode, and the `/deep:*` commands and agent types still reach the same packets.138- Exactly one `graph-metadata.json` exists for the whole skill; no packet carries its own.139140---141142## 7. INTEGRATION POINTS143144### Modes145- `research` — outward web + code iterative investigation (`research/research.md`).146- `review` — iterative review loop, P0/P1/P2 findings + verdict.147148### Surfaces and Consumers149- `Skill(system-deep-loop)` is the invokable hub; active `/deep:*` commands and the agent types (`deep-research`, `deep-review`) are complementary surfaces over the same packets.150- `runtime/` is the frozen, MCP-free backend every mode consumes (nested infrastructure, not a separate skill).151- `/speckit:plan` consumes `@context` packages plus research/review outputs; spec-folder docs consume research/review output.152153---154155## 8. RELATED RESOURCES156157- Pattern: `.skilled/skills/sk-doc/sk-create-skill/references/parent-skill/parent-skills-nested-packets.md` (parent-skill hub + nested packets, the one-graph-metadata invariant).158- Sibling example: `.skilled/skills/sk-prompt/` (the same invokable-hub + `mode-registry.json` Option E pattern).159- Registry: `mode-registry.json` (this hub's routing contract).