orient-roadmap
Answers "What comes next, and what gates it?" on any subject — the increment arc (built → current → next), what shipped now, the gates, the next increment's clusters (paramount starred), and the runway of stage boxes (now → gated-next → future) plus the deferred lanes, computed f
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/orient-roadmap
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
git clone https://github.com/allemaar/open-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
/orient-roadmap
What comes next, and what gates it? Answers with — the increment arc (built → current → next) · what ships now · the gates · the next clusters · the runway. Does not answer — how far along (
/orient-status) · what changed (/orient-map) · what is stuck (/orient-gaps). Owns for the family — the horizon fields:arc_current,arc_idx/arc_count,paramount_ref,runway_span,deferred_count.
Computes a fresh, honest read of where the work is going — the increment arc (built → current → next), what is shipping now, the gates, the next increment's clusters (the paramount one starred), and the runway of stage boxes (now → gated-next → future) plus the deferred lanes — and returns it as one ephemeral bundle (a structured YON record + a human markdown read + a small visual). It is the orient- family's forward-horizon lens: where /orient-map looks back (delta + topology) and /orient-status reports the node you stand on, orient-roadmap looks ahead across multiple horizons. Emits the roadmap slice of the shared record at references/orient-spec/orient-record.yon.
Structured execution spec:
protocol.yon. Read it for the canonical steps, rules, and gates; this file is the human-readable, self-sufficient explanation. The two must stay in sync — if you edit one, update the other and refresh the@STAMPdate.
The shared record, render contract, worked fixtures, and value validator travel
inside references/. The repository-only round-trip guard is
release evidence; its absence from an installed copy does not block execution.
When to use
- "Show me the roadmap / the runway / what's next" on a project, repo, plan, or task — you want the forward horizons, not the node you're on.
- "What are the increments and the lanes" — you want the built → current → next arc, the next increment's clusters, and the runway of gated stages laid out as one board.
- "What's the plan from here" — the prospective board (increments not yet reached, the runway of gated stages, the deferred lanes), not the retrospective delta.
How it works (self-sufficient — works without protocol.yon)
orient-roadmap delegates the gathering to a bounded, read-only subagent so the calling session (a human's, or an agent orienting itself) never sees the search/inference noise — only the result bundle comes back. Nothing is stored; every call recomputes from current reality. If its worker is unavailable, refuses or times out, report unavailable/partial evidence; do not infer NO SUBSTRATE, gather inline, retry or extend the bound. Limit unchanged/clean claims to checked inputs and disclose unexamined tiers. It is horizon-first: the forward increments and the runway lead; the retrospective delta is /orient-map's job, not this one's.
Take the north-star / intent and the last-look anchor as inputs, never prompt for them. Intent (the goal / what the arc is aiming at) gates the whole board: if intent can't be grounded, render what exists but cap every intent-dependent horizon to
guessedand never emit a confident runway from the void. The anchor (a git ref, aPLAN.md, a HEAD@time) is caller-supplied or git-inferred, never written to disk. Never fabricate a north-star or an anchor.Spawn one bounded subagent (read-only, depth-1, single wave; budget ≤ ~8–12 tool calls, hard timeout ~60–90s, stop at the first evidence tier that gives a confident answer). It runs the cheap-first evidence ladder and returns this signal (not raw logs):
- git tier → the commit subjects / merged work = the built items (
✅now-shipping chips), the current branch/frontier = the current increment. - plan/doc tier → from a
PLAN.md/roadmap/checklist: the increment arc (built → current → next), the gates, the next increment's clusters (which is the paramount one), the runway stages (now → gated-next → future), and the deferred lanes. - conversation/folder tier → an un-plan'd next step; file mtimes for the live frontier; the folder name.
Every attested item/increment comes back with a re-runnable
source:line/git-ref proof.
- git tier → the commit subjects / merged work = the built items (
Build the roadmap slice — this skill is the forward-horizon authority (siblings read
arc_current/paramount_ref, none recompute the horizons). The increment arc is a 3-node spine (@CFG id=node.<x>,kind=increment, oneistatus=current— the hero). Hold it to ≤ 3 arc nodes and ≤ 3 runway stages (the ≤5-node budget per sub-graph,orient-contract.md§2 (Visual-render contract)): if a live emission exceeds that, decompose into an overview arc + a drill-down runway rather than cramming. Setarc_current,arc_idx/arc_count,now_count,next_count,runway_span,paramount_ref,cleanup_now_count,deferred_count.Encode the two orthogonal axes without conflating them. The tier axis (provenance confidence) is
◆ attested · ◐ inferred · ◌ guessed— the a11y non-color glyphs on every field. The state/role axis (roadmap semantics) is the handler emoji in the markdown/ASCII face —✅ built · ◉ current · 🔄 running · ★ paramount · ▢ next-gated · ◌ deferred · ⚠ promoted-cleanup.★is a paramount role marker on a next-item chip, never a tier glyph (the handler-ratified★tier lives only in the trust trailer, a different render zone). The SVG widget face translates the emoji column to shape-glyphs + shape encoding (filled/hollow/dashed) — no emoji in the widget.Tag every field with a provenance tier —
◆ git-attested·◐ inferred·◌ guessed— and fail closed: setgate_status(enum:ready | blocked | stalled | degraded | indeterminate) todegradedorindeterminatewith a sentinel value — never a plausible verdict and never a bare0/false— on barren evidence. A no-substrate subject draws aNO SUBSTRATEcard, not a structural roadmap.Emit the bundle to the consumer that asked — one record, three faces, never all three at one reader. The YON record is the AGENT face and goes to an agent consumer only; a human gets the plain-language read plus the visual (widget when available, ASCII twin otherwise) and never sees the record, a raw record field, a node-id, or a gate enum. See Record emission below for the YON face (agent-only); the markdown read follows the worked example; the visual face is rendered per the render-face contract (Claude Code only): for a human on Claude Code with the visualize tool present on an explicit invocation, build the roadmap widget from the kit — call
mcp__visualize__read_meonce, then emit viamcp__visualize__show_widgeta hand-SVG 8-band board (viewBox="0 0 780 …", each band an independent<g transform>so coordinate math stays local), the current increment the dominant node,◆◐◌tier glyphs as redundant (non-color) encoding, deferred chips dashed + faded, no emoji in the widget face; an agent consumer gets the YON record only; any other runtime / no tool / indeterminatehandler_typegets the ASCII twin (fail-closed). The information-complete ASCII roadmap twin is emitted when the selected face includes a visual — it is the only render in a no-SVG channel and carries every increment, item, gate, stage, and lane the widget does (worked trio atreferences/orient-spec/examples/orient-roadmap.{ascii.txt,widget.svg}). The footer is one evidence-derived line — and only ever suggests a skill that is actually installed (fall back to a plain prose hint or/orient-status//plan-createotherwise). The footer's four faces, the staleness short-circuit (anchor unchanged → "no change in checked Git inputs"; other inputs remain unexamined unless read within the bound), the neutral re-look signal, and handoff-feeder routing follow the sharedreferences/orient-spec/family-behaviors.md.
Record emission (the YON face — AGENT consumers only; never printed to a human)
Before emission, pipe the actual current record in memory to
node <skill-dir>/references/tools/orient-validate.mjs -. Do not save a derived
record or substitute an example/self-test pass. The helper covers mapped enums,
core/schema-version fields, parsing/duplicates, provenance syntax and barren
status, with an ETA point warning; all other emitter obligations still apply.
Select the consumer face before applying visual/trailer requirements: agent
record-only, automator no visual, nominal human auto-loop one line, explicit
human full face, unknown consumer ASCII fallback; preserve the widget escape.
The structured face is the roadmap slice of references/orient-spec/orient-record.yon (schema_version = orient-record/1). Reserved tags only — custom tags like @ROADMAP/@RUNWAY are parser-rejected. Increment nodes are @CFG id=node.<x> (kind=increment); every list field (built_items, gates, next_items, runway_stages, cleanup_now, deferred, edges) goes in a sidecar @MAP, never an in-set bracket-list (an in-set bracket-list corrupts the record silently and still validates). ★ (paramount) and ◌ (deferred) ride inside the item label as render hints, never as new tier glyphs. Never run yon format on an emitted instance — CANON mode is destructive on set-internal lists. Validate with --profile exec then the value gate references/tools/orient-validate.mjs. Minimal skeleton:
@CFG id=orient | set=[schema_version=orient-record/1,computed_at:ts=…,ephemeral:bool=true,tool=orient-roadmap,tier=orient,scope=…,evidence_mode=git-only,gate_status=degraded,gate_confidence_floor=inferred,family_used=orient-roadmap,family_suggested_next=orient-status,family_reason_code=lost_thread,overall_trust=med,degraded:bool=true,degrade_reason="advisory skeleton; no attested gating field"]
@CFG id=subject | set=[name=…,kind=monorepo,purpose=…,purpose_source=readme,intent_status=stated,parent_subject=…]
@CFG id=roadmap | set=[north_star=…,arc_current=…,arc_idx:int=2,arc_count:int=3,now_count:int=4,next_count:int=3,runway_span=…,paramount_ref=…,cleanup_now_count:int=1,deferred_count:int=2]
@CFG id=node.a1 | set=[kind=increment,label=…,istatus=built,lane=arc]
@CFG id=node.a2 | set=[kind=increment,label=…,istatus=current,lane=arc]
@CFG id=node.a3 | set=[kind=increment,label=…,istatus=next,lane=arc]
@MAP name=edges | pairs=["a1"->"a2","a2"->"a3"]
@MAP name=built_items | pairs=["b1"->"…","b2"->"…"]
@MAP name=gates | pairs=["g1"->"…","g2"->"…"]
@MAP name=next_items | pairs=["x1"->"★ …","x2"->"…"]
@MAP name=runway_stages | pairs=["r1"->"now: …","r2"->"gated-next: …","r3"->"future: …"]
@MAP name=cleanup_now | pairs=["u1"->"⚠ …"]
@MAP name=deferred | pairs=["d1"->"◌ …(deferred)"]
@MAP name=provenance | pairs=["roadmap.arc_current"->"artifact-stated:med:plan-md","roadmap.built_items"->"git-attested:high:git-log"]
On barren evidence the envelope degrades honestly and carries the reason: gate_status=indeterminate, degraded:bool=true, degrade_reason="no git, no plan" — and the visual is the NO SUBSTRATE card, never a structural roadmap. A full worked instance ships at references/orient-spec/examples/orient-roadmap.example.yon.
Output — worked examples (markdown face)
The horizon board (the case orient-roadmap exists for):
🧭 open-skills — public skills pack, the roadmap. ↳ in: open-source push [identity: ◆ git]
North star: one orient- family, three faces, machine-checked.
THE ARC: ✅ status ──▶ ◉ map+gaps (current) ──▶ ▢ roadmap (next) ◆ plan spine
NOW SHIPPING:
✅ orient-status ✅ orient-map ✅ orient-gaps ✅ value-gate ◆ git log
GATES: [ full validate green ] [ cold-review pass ] ◆ CI
NEXT INCREMENT:
★ roadmap slice widget parity ascii floor ◐ plan
THE RUNWAY: now:author ──▶ gated-next:cold-review ──▶ future:publish ◐ plan
CLEANUP-NOW: ⚠ stale STAMP dates
DEFERRED: ◌ deterministic renderer(deferred) ◌ ci wiring(deferred) ◌ unchanged
**→ Next:** map+gaps is the current increment; the roadmap slice is paramount.
Trust: ◆◐◌ · ⚠️ lean here: the runway "future: publish" stage (inferred from the plan, not a gate) · next → /orient-status
legend: ◆ attested · ◐ inferred · ◌ guessed · ✅ built · ◉ current · 🔄 running · ★ paramount · ▢ next/gated · ◌ deferred · ⚠ promoted-cleanup
Barren / no-substrate (honest degradation is the success case):
🧭 ToDo — a folder (no git, no plan). [identity: ◌ guessed]
┌───────────────────────────────┐
│ NO SUBSTRATE │ no commits, no plan — no horizons to draw.
│ can't draw a roadmap. │
└───────────────────────────────┘
**→ Next:** init git or name the north-star, and the horizons become visible.
Trust: ◌◌◌ · ⚠️ lean here: every line — no durable roadmap exists. [cannot determine: no git or plan evidence]
The ASCII roadmap + the trust trailer with the ⚠️ lean your scrutiny here line (naming the single load-bearing guess) and the one-line legend is mandatory on the selected full human face; deferred items keep the (deferred) word so the widget's dashed chips have a text twin.
Boundaries
- Not
/orient-status— that reports position + remaining + a banded ETA on the ONE node you stand on; orient-roadmap reports the forward horizons and the runway (the increment arc, the next clusters, the stage lanes). They share one sweep; orient-roadmap owns the horizon board, orient-status owns position + ETA on the current increment. - Not
/orient-map— that reports topology + the delta since your last look (done → here → next, a tree on a branch, capped at ≤5 nodes); orient-roadmap reports where the work is GOING (increments not yet reached, the runway of gated stages, the deferred lanes). orient-map is retrospective/delta; orient-roadmap is prospective/multi-horizon. - Not
/plan-createor/plan-deep-dive— those DESIGN or WALK a plan; orient-roadmap only SEES and reports the current roadmap NOW against whatever evidence exists (often no formal plan). - Not
/reflect, notinsight-*— those THINK / DECIDE; orient-roadmap only SEES and reports the horizons NOW. After it, reach for/orient-statusfor the ETA on the current increment, or/plan-createto act on the next horizon. - Read-only. It never mutates state; the north-star/intent and the anchor are caller-supplied or inferred, never written to disk by default.
Rules
- MUST be horizon-first — lead with the forward increments and the runway; the retrospective delta belongs to
/orient-map, not here. - MUST render the increment arc as a ≤3-node spine (one
current, the hero) and the runway as ≤3 stage boxes (now → gated-next → future); if a live emission exceeds that, decompose into an overview arc + a drill-down runway rather than cram (the ≤5-node-per-sub-graph budget). - MUST own and emit the horizon fields (
arc_current,arc_idx/arc_count,paramount_ref,now_count,next_count,runway_span,cleanup_now_count,deferred_count) so sibling slices don't recompute the horizons. - MUST keep the tier axis (
◆◐◌, provenance) and the state/role axis (the handler emoji✅◉🔄★▢◌⚠) separate —★is a paramount role marker on a next-item chip, NEVER a tier glyph; the handler-ratified★tier rides only the trust trailer. - MUST take
intent/ the north-star as input and gate intent-dependent horizons when it's absent — never fabricate a north-star; below a grounding threshold draw aNO SUBSTRATEcard, not a structural roadmap. - MUST tag every field with a provenance tier and fail closed —
gate_status=degraded/indeterminatewith a sentinel, never a plausible verdict — on zero evidence. - MUST, when the consumer is an agent (
handler_type = agent), emit a record conformant toreferences/orient-spec/orient-record.yon(reserved tags; increment nodes as@CFG id=node.<x>kind=increment; list fields as sidecar@MAP;★/◌as in-label render hints only; neveryon formatan instance). A human consumer gets its selected plain-language face (one line when nominal, otherwise the read plus visual) — never the record, a raw record field, a node-id, or a gate enum. - MUST, when the selected face includes a visual, emit the ASCII roadmap + the trust trailer with the
⚠️ lean hereload-bearing-guess line + the one-line legend; deferred items keep the(deferred)word so the widget's dashed chips have a text twin; the visual's ASCII twin is mandatory. - MUST NOT print the YON record — or any raw record field, node-id, gate enum,
@CFGline, or@MAPline — into a human-facing reply. The record is the agent face (handler_type = agent); the human face is the plain-language read plus the visual (widget when available, ASCII twin otherwise). Perreferences/orient-spec/orient-contract.md§1 (token discipline) andfamily-behaviors.md§6. - MUST render the visual face per the render-face contract (Claude Code only, via
mcp__visualize__show_widget): agent → YON record only; human + Claude + tool + explicit invocation → widget + ASCII twin; other runtime / no tool / indeterminatehandler_type→ ASCII twin (fail-closed). The widget is the 8-band roadmap board (viewBox="0 0 780 …", per-band<g transform>groups), the current increment the dominant node, carrying the◆◐◌tier glyphs (non-color) and no emoji in the widget face, chrome-compliant, checked by the repository-onlytools/orient-roundtrip.mjsrelease guard when running from a clone; installed copies retain this as an emitter obligation. - MUST delegate gathering to a bounded, read-only, depth-1 subagent and return only the bundle (no raw search noise), with a re-runnable proof on every attested field.
- The family footer MUST only suggest an installed skill.
Next skills. On completion, run the Next Skills protocol (
next-skills/SKILL.md): surface thenext-skillsrecommendations from front-matter for the caller to pick. Offer only — never auto-invoke.
Self-improvement. On completion, run the Self-Improvement Protocol (
self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Files (open-skills)
-
references
-
orient-spec
-
examples
-
bad
-
enum-banana.yon 2 KB · in bundle
-
fail-open.yon 1.6 KB · in bundle
-
-
orient-record.example.yon 7.1 KB · in bundle
-
orient-roadmap.ascii.txt 1.3 KB
Loading… -
orient-roadmap.example.yon 5.6 KB · in bundle
-
orient-roadmap.widget.svg 6.3 KB · in bundle
-
-
family-behaviors.md 10.9 KB
Loading… -
family-manifest.yon 7.3 KB · in bundle
-
orient-contract.md 13.8 KB
Loading… -
orient-record.yon 15.3 KB · in bundle
-
-
tools
-
orient-validate.mjs 14.6 KB · in bundle
-
-
-
protocol.yon 12.7 KB · in bundle
-
SKILL.md 20.4 KB
--- name: orient-roadmap description: > Answers "What comes next, and what gates it?" on any subject — the increment arc (built → current → next), what shipped now, the gates, the next increment's clusters (paramount starred), and the runway of stage boxes (now → gated-next → future) plus the deferred lanes, computed fresh via a bounded read-only subagent. Trigger phrases: "/orient-roadmap", "show me the roadmap", "show me the runway", "what's next". Not /orient-status (how far along am I and when will it be done), /orient-map (what changed since I last looked), or /orient-gaps (what is stuck or missing) — orient-roadmap shows the FORWARD HORIZONS and the runway. visibility: public self-improvable: true companions: - path: references/orient-spec optional: false why: "The required record, render contract, and worked fixtures; bundled inside this skill." - path: references/tools/orient-validate.mjs optional: false why: "The required value and fail-closed gate; bundled inside this skill." - path: ../../tools/orient-roundtrip.mjs optional: true why: "Repository-only release evidence; installed execution retains the emitter obligation." next-skills: - skill: orient-status phrase: "/orient-status" why: "Once the horizons are clear, get position + remaining + banded ETA on the current increment" triggers: - "/orient-roadmap" - "show me the roadmap" - "show me the runway" - "what's next" - "the increments and lanes" - "the plan" --- # /orient-roadmap > **What comes next, and what gates it?** > **Answers with —** the increment arc (built → current → next) · what ships now · the gates · the next clusters · the runway. > **Does not answer —** how far along (`/orient-status`) · what changed (`/orient-map`) · what is stuck (`/orient-gaps`). > **Owns for the family —** the horizon fields: `arc_current`, `arc_idx`/`arc_count`, `paramount_ref`, `runway_span`, `deferred_count`. Computes a fresh, honest read of **where the work is going** — the increment arc (**built → current → next**), what is shipping **now**, the **gates**, the next increment's **clusters** (the paramount one starred), and the **runway** of stage boxes (**now → gated-next → future**) plus the **deferred lanes** — and returns it as one ephemeral bundle (a structured YON record + a human markdown read + a small visual). It is the `orient-` family's *forward-horizon* lens: where `/orient-map` looks back (delta + topology) and `/orient-status` reports the node you stand on, `orient-roadmap` looks **ahead** across multiple horizons. Emits the `roadmap` slice of the shared record at [`references/orient-spec/orient-record.yon`](references/orient-spec/orient-record.yon). > **Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical steps, rules, and gates; this file is the human-readable, self-sufficient explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date. The shared record, render contract, worked fixtures, and value validator travel inside [`references/`](references/). The repository-only round-trip guard is release evidence; its absence from an installed copy does not block execution. ## When to use - "Show me the roadmap / the runway / what's next" on a project, repo, plan, or task — you want the **forward horizons**, not the node you're on. - "What are the increments and the lanes" — you want the built → current → next arc, the next increment's clusters, and the runway of gated stages laid out as one board. - "What's the plan from here" — the prospective board (increments not yet reached, the runway of gated stages, the deferred lanes), not the retrospective delta. ## How it works (self-sufficient — works without `protocol.yon`) `orient-roadmap` **delegates the gathering to a bounded, read-only subagent** so the calling session (a human's, or an agent orienting itself) never sees the search/inference noise — only the result bundle comes back. Nothing is stored; every call recomputes from current reality. If its worker is unavailable, refuses or times out, report unavailable/partial evidence; do not infer NO SUBSTRATE, gather inline, retry or extend the bound. Limit unchanged/clean claims to checked inputs and disclose unexamined tiers. It is **horizon-first**: the forward increments and the runway lead; the retrospective delta is `/orient-map`'s job, not this one's. 1. **Take the north-star / intent and the last-look anchor as inputs, never prompt for them.** **Intent** (the goal / what the arc is aiming at) gates the whole board: if intent can't be grounded, render what exists but **cap every intent-dependent horizon to `guessed`** and **never emit a confident runway from the void**. The **anchor** (a git ref, a `PLAN.md`, a HEAD@time) is caller-supplied or git-inferred, **never written to disk**. Never fabricate a north-star or an anchor. 2. **Spawn one bounded subagent** (read-only, depth-1, single wave; budget ≤ ~8–12 tool calls, hard timeout ~60–90s, stop at the first evidence tier that gives a confident answer). It runs the cheap-first evidence ladder and **returns this signal** (not raw logs): - **git tier** → the commit subjects / merged work = the **built** items (`✅` now-shipping chips), the current branch/frontier = the **current** increment. - **plan/doc tier** → from a `PLAN.md`/roadmap/checklist: the increment arc (built → current → next), the **gates**, the **next increment's clusters** (which is the paramount one), the **runway stages** (now → gated-next → future), and the **deferred** lanes. - **conversation/folder tier** → an un-plan'd next step; file mtimes for the live frontier; the folder name. Every attested item/increment comes back with a re-runnable `source:line`/git-ref **proof**. 3. **Build the roadmap slice — this skill is the forward-horizon authority** (siblings read `arc_current` / `paramount_ref`, none recompute the horizons). The **increment arc is a 3-node spine** (`@CFG id=node.<x>`, `kind=increment`, one `istatus=current` — the hero). Hold it to **≤ 3 arc nodes and ≤ 3 runway stages** (the ≤5-node budget *per sub-graph*, [`orient-contract.md`](references/orient-spec/orient-contract.md) §2 (Visual-render contract)): if a live emission exceeds that, **decompose** into an overview arc + a drill-down runway rather than cramming. Set `arc_current`, `arc_idx`/`arc_count`, `now_count`, `next_count`, `runway_span`, `paramount_ref`, `cleanup_now_count`, `deferred_count`. 4. **Encode the two orthogonal axes without conflating them.** The **tier axis** (provenance confidence) is `◆ attested · ◐ inferred · ◌ guessed` — the a11y non-color glyphs on every field. The **state/role axis** (roadmap semantics) is the handler emoji in the markdown/ASCII face — `✅ built · ◉ current · 🔄 running · ★ paramount · ▢ next-gated · ◌ deferred · ⚠ promoted-cleanup`. **`★` is a paramount *role* marker on a next-item chip, never a tier glyph** (the handler-ratified `★` tier lives only in the trust trailer, a different render zone). The SVG widget face translates the emoji column to shape-glyphs + shape encoding (filled/hollow/dashed) — no emoji in the widget. 5. **Tag every field with a provenance tier** — `◆ git-attested` · `◐ inferred` · `◌ guessed` — and **fail closed**: set **`gate_status`** (enum: `ready | blocked | stalled | degraded | indeterminate`) to `degraded` or `indeterminate` with a **sentinel** value — *never* a plausible verdict and never a bare `0`/`false` — on barren evidence. A no-substrate subject draws a **`NO SUBSTRATE`** card, not a structural roadmap. 6. **Emit the bundle to the consumer that asked — one record, three faces, never all three at one reader.** The **YON record is the AGENT face and goes to an agent consumer only**; a **human gets the plain-language read plus the visual (widget when available, ASCII twin otherwise) and never sees the record, a raw record field, a node-id, or a gate enum**. See *Record emission* below for the YON face (agent-only); the markdown read follows the worked example; the **visual face is rendered per the [render-face contract](references/orient-spec/family-behaviors.md) (Claude Code only)**: for a human on Claude Code with the visualize tool present on an explicit invocation, build the **roadmap widget** from the kit — call `mcp__visualize__read_me` once, then emit via `mcp__visualize__show_widget` a hand-SVG **8-band board** (`viewBox="0 0 780 …"`, each band an independent `<g transform>` so coordinate math stays local), the current increment the dominant node, `◆◐◌` tier glyphs as redundant (non-color) encoding, deferred chips dashed + faded, **no emoji in the widget face**; an **agent** consumer gets the YON record only; any **other runtime / no tool / indeterminate `handler_type`** gets the ASCII twin (fail-closed). The **information-complete ASCII roadmap twin is emitted when the selected face includes a visual** — it is the only render in a no-SVG channel and carries every increment, item, gate, stage, and lane the widget does (worked trio at [`references/orient-spec/examples/orient-roadmap.{ascii.txt,widget.svg}`](references/orient-spec/examples/)). The footer is one evidence-derived line — and **only ever suggests a skill that is actually installed** (fall back to a plain prose hint or `/orient-status`/`/plan-create` otherwise). The footer's four faces, the **staleness short-circuit** (anchor unchanged → "no change in checked Git inputs"; other inputs remain unexamined unless read within the bound), the neutral re-look signal, and handoff-feeder routing follow the shared [`references/orient-spec/family-behaviors.md`](references/orient-spec/family-behaviors.md). ## Record emission (the YON face — AGENT consumers only; never printed to a human) Before emission, pipe the actual current record in memory to `node <skill-dir>/references/tools/orient-validate.mjs -`. Do not save a derived record or substitute an example/self-test pass. The helper covers mapped enums, core/schema-version fields, parsing/duplicates, provenance syntax and barren status, with an ETA point warning; all other emitter obligations still apply. Select the consumer face before applying visual/trailer requirements: agent record-only, automator no visual, nominal human auto-loop one line, explicit human full face, unknown consumer ASCII fallback; preserve the widget escape. The structured face is the `roadmap` slice of [`references/orient-spec/orient-record.yon`](references/orient-spec/orient-record.yon) (`schema_version = orient-record/1`). **Reserved tags only** — custom tags like `@ROADMAP`/`@RUNWAY` are parser-rejected. **Increment nodes are `@CFG id=node.<x>` (`kind=increment`); every list field (`built_items`, `gates`, `next_items`, `runway_stages`, `cleanup_now`, `deferred`, `edges`) goes in a sidecar `@MAP`, never an in-set bracket-list** (an in-set bracket-list corrupts the record *silently and still validates*). `★` (paramount) and `◌` (deferred) ride **inside the item label** as render hints, never as new tier glyphs. **Never run `yon format` on an emitted instance** — `CANON` mode is destructive on set-internal lists. Validate with `--profile exec` then the value gate `references/tools/orient-validate.mjs`. Minimal skeleton: ``` @CFG id=orient | set=[schema_version=orient-record/1,computed_at:ts=…,ephemeral:bool=true,tool=orient-roadmap,tier=orient,scope=…,evidence_mode=git-only,gate_status=degraded,gate_confidence_floor=inferred,family_used=orient-roadmap,family_suggested_next=orient-status,family_reason_code=lost_thread,overall_trust=med,degraded:bool=true,degrade_reason="advisory skeleton; no attested gating field"] @CFG id=subject | set=[name=…,kind=monorepo,purpose=…,purpose_source=readme,intent_status=stated,parent_subject=…] @CFG id=roadmap | set=[north_star=…,arc_current=…,arc_idx:int=2,arc_count:int=3,now_count:int=4,next_count:int=3,runway_span=…,paramount_ref=…,cleanup_now_count:int=1,deferred_count:int=2] @CFG id=node.a1 | set=[kind=increment,label=…,istatus=built,lane=arc] @CFG id=node.a2 | set=[kind=increment,label=…,istatus=current,lane=arc] @CFG id=node.a3 | set=[kind=increment,label=…,istatus=next,lane=arc] @MAP name=edges | pairs=["a1"->"a2","a2"->"a3"] @MAP name=built_items | pairs=["b1"->"…","b2"->"…"] @MAP name=gates | pairs=["g1"->"…","g2"->"…"] @MAP name=next_items | pairs=["x1"->"★ …","x2"->"…"] @MAP name=runway_stages | pairs=["r1"->"now: …","r2"->"gated-next: …","r3"->"future: …"] @MAP name=cleanup_now | pairs=["u1"->"⚠ …"] @MAP name=deferred | pairs=["d1"->"◌ …(deferred)"] @MAP name=provenance | pairs=["roadmap.arc_current"->"artifact-stated:med:plan-md","roadmap.built_items"->"git-attested:high:git-log"] ``` On **barren** evidence the envelope degrades honestly and carries the *reason*: `gate_status=indeterminate, degraded:bool=true, degrade_reason="no git, no plan"` — and the visual is the `NO SUBSTRATE` card, never a structural roadmap. A full worked instance ships at [`references/orient-spec/examples/orient-roadmap.example.yon`](references/orient-spec/examples/orient-roadmap.example.yon). ## Output — worked examples (markdown face) **The horizon board (the case orient-roadmap exists for):** ``` 🧭 open-skills — public skills pack, the roadmap. ↳ in: open-source push [identity: ◆ git] North star: one orient- family, three faces, machine-checked. THE ARC: ✅ status ──▶ ◉ map+gaps (current) ──▶ ▢ roadmap (next) ◆ plan spine NOW SHIPPING: ✅ orient-status ✅ orient-map ✅ orient-gaps ✅ value-gate ◆ git log GATES: [ full validate green ] [ cold-review pass ] ◆ CI NEXT INCREMENT: ★ roadmap slice widget parity ascii floor ◐ plan THE RUNWAY: now:author ──▶ gated-next:cold-review ──▶ future:publish ◐ plan CLEANUP-NOW: ⚠ stale STAMP dates DEFERRED: ◌ deterministic renderer(deferred) ◌ ci wiring(deferred) ◌ unchanged **→ Next:** map+gaps is the current increment; the roadmap slice is paramount. Trust: ◆◐◌ · ⚠️ lean here: the runway "future: publish" stage (inferred from the plan, not a gate) · next → /orient-status legend: ◆ attested · ◐ inferred · ◌ guessed · ✅ built · ◉ current · 🔄 running · ★ paramount · ▢ next/gated · ◌ deferred · ⚠ promoted-cleanup ``` **Barren / no-substrate (honest degradation is the success case):** ``` 🧭 ToDo — a folder (no git, no plan). [identity: ◌ guessed] ┌───────────────────────────────┐ │ NO SUBSTRATE │ no commits, no plan — no horizons to draw. │ can't draw a roadmap. │ └───────────────────────────────┘ **→ Next:** init git or name the north-star, and the horizons become visible. Trust: ◌◌◌ · ⚠️ lean here: every line — no durable roadmap exists. [cannot determine: no git or plan evidence] ``` The ASCII roadmap + the trust trailer with the `⚠️ lean your scrutiny here` line (naming the single load-bearing guess) and the one-line legend is **mandatory** on the selected full human face; deferred items keep the `(deferred)` word so the widget's dashed chips have a text twin. ## Boundaries - **Not `/orient-status`** — that reports *position + remaining + a banded ETA* on the ONE node you stand on; orient-roadmap reports the **forward horizons and the runway** (the increment arc, the next clusters, the stage lanes). They share one sweep; orient-roadmap owns the horizon board, orient-status owns position + ETA on the current increment. - **Not `/orient-map`** — that reports **topology + the delta since your last look** (done → here → next, a tree on a branch, capped at ≤5 nodes); orient-roadmap reports **where the work is GOING** (increments not yet reached, the runway of gated stages, the deferred lanes). orient-map is retrospective/delta; orient-roadmap is prospective/multi-horizon. - **Not `/plan-create` or `/plan-deep-dive`** — those DESIGN or WALK a plan; orient-roadmap only SEES and reports the current roadmap NOW against whatever evidence exists (often no formal plan). - **Not `/reflect`, not `insight-*`** — those THINK / DECIDE; orient-roadmap only SEES and reports the horizons NOW. After it, reach for `/orient-status` for the ETA on the current increment, or `/plan-create` to act on the next horizon. - **Read-only.** It never mutates state; the north-star/intent and the anchor are caller-supplied or inferred, never written to disk by default. ## Rules - MUST be **horizon-first** — lead with the forward increments and the runway; the retrospective delta belongs to `/orient-map`, not here. - MUST render the **increment arc as a ≤3-node spine** (one `current`, the hero) and the **runway as ≤3 stage boxes** (now → gated-next → future); if a live emission exceeds that, **decompose** into an overview arc + a drill-down runway rather than cram (the ≤5-node-per-sub-graph budget). - MUST own and emit the horizon fields (`arc_current`, `arc_idx`/`arc_count`, `paramount_ref`, `now_count`, `next_count`, `runway_span`, `cleanup_now_count`, `deferred_count`) so sibling slices don't recompute the horizons. - MUST keep the **tier axis** (`◆◐◌`, provenance) and the **state/role axis** (the handler emoji `✅◉🔄★▢◌⚠`) separate — `★` is a *paramount role* marker on a next-item chip, NEVER a tier glyph; the handler-ratified `★` tier rides only the trust trailer. - MUST take `intent` / the north-star as input and gate intent-dependent horizons when it's absent — never fabricate a north-star; below a grounding threshold draw a `NO SUBSTRATE` card, not a structural roadmap. - MUST tag every field with a provenance tier and **fail closed** — `gate_status` = `degraded`/`indeterminate` with a sentinel, never a plausible verdict — on zero evidence. - MUST, **when the consumer is an agent (`handler_type = agent`)**, emit a record conformant to `references/orient-spec/orient-record.yon` (reserved tags; increment nodes as `@CFG id=node.<x>` `kind=increment`; list fields as sidecar `@MAP`; `★`/`◌` as in-label render hints only; never `yon format` an instance). **A human consumer gets its selected plain-language face (one line when nominal, otherwise the read plus visual) — never the record, a raw record field, a node-id, or a gate enum.** - MUST, when the selected face includes a visual, emit the ASCII roadmap + the trust trailer with the `⚠️ lean here` load-bearing-guess line + the one-line legend; deferred items keep the `(deferred)` word so the widget's dashed chips have a text twin; the visual's ASCII twin is mandatory. - MUST NOT print the YON record — or any raw record field, node-id, gate enum, `@CFG` line, or `@MAP` line — into a human-facing reply. The record is the **agent** face (`handler_type = agent`); the human face is the plain-language read plus the visual (widget when available, ASCII twin otherwise). Per `references/orient-spec/orient-contract.md` §1 (token discipline) and `family-behaviors.md` §6. - MUST render the visual face per the render-face contract (Claude Code only, via `mcp__visualize__show_widget`): agent → YON record only; human + Claude + tool + explicit invocation → widget + ASCII twin; other runtime / no tool / indeterminate `handler_type` → ASCII twin (fail-closed). The widget is the **8-band roadmap board** (`viewBox="0 0 780 …"`, per-band `<g transform>` groups), the current increment the dominant node, carrying the `◆◐◌` tier glyphs (non-color) and **no emoji in the widget face**, chrome-compliant, checked by the repository-only `tools/orient-roundtrip.mjs` release guard when running from a clone; installed copies retain this as an emitter obligation. - MUST delegate gathering to a bounded, read-only, depth-1 subagent and return **only** the bundle (no raw search noise), with a re-runnable proof on every attested field. - The family footer MUST only suggest an **installed** skill. > **Next skills.** On completion, run the Next Skills protocol (`next-skills/SKILL.md`): surface the `next-skills` recommendations from front-matter for the caller to pick. Offer only — never auto-invoke. > **Self-improvement.** On completion, run the Self-Improvement Protocol (`self-improve/SKILL.md`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.