orient-status
Answers "How far along am I, and when will it be done?" on any subject (repo, folder, plan, task) — current position, what's left, and a banded ETA, computed fresh via a bounded read-only subagent. `--resume` rebuilds context after a gap (one next move + counter-case). Trigger ph
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/orient-status
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-status
How far along am I, and when will it be done? Answers with — position · what is left · a banded ETA · (
--resume) the one next move. Does not answer — what changed (/orient-map) · what is stuck (/orient-gaps) · what comes next (/orient-roadmap). Owns for the family — nothing topological; it reuses the shared topology contract in its existing bounded worker.
Computes a fresh, honest read of where the current work stands — position, remaining work, and a banded ETA — and returns it as one ephemeral bundle (a structured YON record + a human markdown read + a small visual). --resume re-frames it for the "I just came back and lost the thread" case. Part of the orient- family; emits a 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.
Reuse the shared topology-detection contract within the same single bounded worker, or consume supplied topology fields with their stated provenance and limits. Do not invoke another self-orchestrating orientation skill or start a second sweep; supplied and detected interpretations must agree or remain an explicit gap.
When to use
- "Where are we / what's the status / how far along / what's the ETA" on a project, repo, plan, or task.
- After a context fill or at the start of a session, before deciding the next move.
--resume: you've been away (a gap, a context-switch) and lost the thread — you need what changed + exactly where to put your hands next.
How it works (self-sufficient — works without protocol.yon)
orient-status 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.
Take intent as input, never prompt for it. Intent (the goal / what "done" means) is the denominator every read leans on, and it is the least recoverable thing from evidence. Accept an
intentargument if given. If intent can't be grounded (no stated goal, no plan, no README), gate every intent-dependent field — render it— (needs goal)and cap its confidence toguessed. Never fabricate a goal and hang a confident read off it. On an evidence-poor surface the highest-value output is the nudge: "name the goal in one line and I get sharper."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 →
branch,dirtycount,ahead/behind, recent commit subjects (phase signal),merge-base(branch detection). - plan/doc tier → from a
PLAN.md/TODO.md/checklist:open_count, theopen_setitems,done_count, the current phase/frontier, thenext_openunchecked item. - conversation/folder tier → recent turns, the folder name, file mtimes for the live frontier.
Every attested field comes back with a re-runnable
source:line/git-ref proof.
- git tier →
Compute three things:
- Position — the one-line headline state (phase /
frontier/on_branch). Consume family topology as supplied: an absenton_branchmeans unknown, never false/trunk; do not recompute it or infer a topology-dependent ETA from its absence. - Remaining + distance — the
open_countagainst its denominator (flag when the real remainder may be larger than the visible one —denominator_trust). - ETA — the one non-observed output. A band, never a point estimate (
~1–3 days), taggedestimate, not observed. With no plan →ETA: unknown. A fabricated percentage or confident phase is banned.
- Position — the one-line headline state (phase /
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 plausibleready/blockedand never a bare0/false— on barren evidence. The empty-folder read is a success state, not a failure.--resumemode: lead with the resume-pointer — the exact spot you stopped + the half-finished thought — then exactly one next move + its counter-case + the single dropped alternative (never a menu). Suppress the full snapshot.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 structure in the worked examples; the visual face is rendered per the render-face contract §2 (Claude Code only): for a human on Claude Code with the visualize tool present on an explicit invocation, build the status widget from the kit — call
mcp__visualize__read_meonce, then emit viamcp__visualize__show_widgetan identity nameplate + a position track (the phase spine, hand-SVG, fixedviewBox="0 0 680 …") + a remaining load-bar + ledger (open-ended▰▰▰▒╌╌?when the denominator is unknown) + an ETA fading uncertainty band (a point-marker is BANNED — the uncertainty is the datum), with the cursor/now the dominant element and◆◐◌tier glyphs as redundant non-color encoding; an agent consumer gets the YON record only; any other runtime / no tool / indeterminatehandler_typegets the ASCII twin (fail-closed). The information-complete ASCII status twin is emitted when the selected face includes a visual — it is the only render in a no-SVG channel and carries every datum the widget does. The widget is sparse — a learn-once legend + tier glyphs, never per-node sentences. Below a grounding threshold (mostly◌) draw aNO SUBSTRATEcard instead of a structural visual. 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/plan-createotherwise). The footer's four faces, the staleness short-circuit (an unchanged last-look anchor → "no change in checked Git inputs"; uncovered inputs stay 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 a slice of references/orient-spec/orient-record.yon (schema_version = orient-record/1). Reserved tags only — custom tags like @SNAPSHOT are parser-rejected. List fields go in a sidecar @MAP, never an in-set bracket-list (an in-set bracket-list corrupts the record silently and still validates). Never run yon format on an emitted instance — CANON mode is destructive on set-internal lists and the corruption still validates clean; hand-emit the @MAP sidecars and leave them. Validate with --profile exec. Minimal skeleton:
@CFG id=orient | set=[schema_version=orient-record/1,computed_at:ts=…,ephemeral:bool=true,tool=orient-status,tier=orient,scope=…,evidence_mode=git-only,gate_status=degraded,gate_confidence_floor=inferred,family_used=orient-status,family_suggested_next=plan-create,overall_trust=med,degraded:bool=true,degrade_reason="inferred advisory status; no attested blocking field"]
@CFG id=subject | set=[name=…,kind=monorepo,purpose=…,purpose_source=readme,intent_status=stated]
@CFG id=snapshot | set=[status=in-progress,stage=…,stage_idx:int=1,frontier=…,on_branch:bool=true,branch=…,dirty:int=0,ahead:int=0,behind:int=0]
@CFG id=remaining | set=[open_count:int=4,done_count:int=1,fraction_done:flt=0.2,denominator_trust=inferred,next_open=…]
@MAP name=open_set | pairs=["o1"->"…","o2"->"…"]
@CFG id=forecast | set=[kind=prediction,provenance=extrapolated,eta_low=1d,eta_high=3d,eta_unit=calendar-days,confidence=low,unschedulable:bool=false]
@CFG id=resume | set=[next_action=…,counter_case=…,dropped_alt=…,resume_confidence=high] # --resume mode only
@MAP name=provenance | pairs=["snapshot.on_branch"->"git-attested:high:git-rev-parse"]
A full worked instance ships at references/orient-spec/examples/orient-record.example.yon.
Output — worked examples (markdown face)
Rich tier (a git repo with a plan):
🧭 open-skills — public skills repo. [identity: ◆ git]
**Now:** P1 — building orient-status on `feat/orient`. ◆ git `rev-parse`
**Left:** 4 open · ~20% done (visible-only). ◐ inferred (checkboxes)
**ETA:** ~1–3 days *(estimate, not observed)*. ◌ 2 data points
**→ Next:** finish protocol.yon, then count-wiring.
Trust: ◆◐◌ · ⚠️ lean here: the ~1–3 day ETA (2 points, not observed) · next → /plan-create
Git-rich but intent-absent (the case intent-gating exists for — confident position, gated distance):
🧭 some-repo — a git repo on `wip`. [identity: ◆ git]
**Now:** on `wip`, 3 dirty, 12 commits. ◆ git `rev-parse`
**Left:** — (needs goal) · **ETA:** — (needs goal) ◌ no goal on record
**→ Next:** name the goal in one line and I get sharper. ← position is real; distance can't be
Trust: ◆◌◌ · ⚠️ lean here: there is no goal — every distance/ETA field is gated, not guessed. [limited evidence]
Barren tier (a non-git folder, no plan — honest degradation is the success case):
🧭 ToDo — a folder (no manifest, no git, no README). [identity: ◌ guessed]
**Now:** can't tell — barely-started / mid / near-done. [◌ no durable state]
**ETA:** unknown — nothing to measure against.
**→ Next:** name the goal in one line and I get sharper. ← the cheapest win
Trust: ◌◌◌ · ⚠️ lean here: every line — no durable state exists. [cannot determine from available evidence]
The ASCII trust trailer with the ⚠️ lean your scrutiny here line (naming the single load-bearing guess) is mandatory on the selected full human face.
Boundaries
- Not
/investigate— that gathers arbitrary deep facts read-only; orient-status computes a fixed position + distance + forecast about ongoing work. - Not
/plan-deep-dive— that walks an existing plan phase-by-phase for quality; orient-status reads the current position against whatever evidence exists (often no plan) and forecasts. - Not a private arc-state status skill — that kind pulls declared agent and arc state from a private system; orient-status orients on any subject (repo, folder, plan, task) from universal evidence.
- Not
/reflect, notinsight-*— those THINK / DECIDE; orient-status only SEES and reports NOW. After it, reach for/plan-createto act, or a sibling lens (orient-mapfor the shape,orient-gapsfor what's stuck) once they ship — until then the footer routes only to installed skills. - Read-only. It never mutates state; the one sanctioned reference point (an intent line / last-look anchor) is caller-supplied or harness-held, never written to disk by default.
Rules
- MUST take
intentas input and gate intent-dependent fields when it's absent — never fabricate a goal. - MUST express ETA as a band, never a point estimate; MUST NOT emit a fabricated percentage or confident phase on an unknown denominator.
- MUST tag every field with a provenance tier and fail closed —
gate_status=degraded/indeterminatewith a sentinel, never a plausibleready— 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; list fields as sidecar@MAP; 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 trust trailer with the
⚠️ lean hereload-bearing-guess line; the ASCII status twin is mandatory for that selected visual face — it is the only render in a no-SVG channel. - 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 → status widget + ASCII twin; other runtime / no tool / indeterminatehandler_type→ ASCII twin (fail-closed). The status widget is an identity nameplate + position track + remaining load-bar + ETA fading-band, the cursor/now the dominant element; ETA renders as a band, never a point-marker. - MUST keep the widget and ASCII twin projections of one node-structure (same labels +
◆◐◌tier glyphs as redundant non-color encoding), chrome-compliant (colors only via CSS vars /c-*classes — no hardcoded hex; noposition:fixed;role="img"+ non-empty<title>/<desc>; fixedviewBox="0 0 680 …"), checked by the repository-onlytools/orient-roundtrip.mjsrelease guard when running from a clone; installed copies retain this as an emitter obligation. The widget MUST be sparse — a learn-once legend + tier glyphs only, NEVER per-node sentences or interpretive prose glued to elements (its whole purpose is to lower cognitive load). - 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.
--resumeMUST end in exactly ONE next move + counter-case + the single dropped alternative (no menu).
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
-
-
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 10.3 KB · in bundle
-
SKILL.md 17.7 KB
--- name: orient-status description: > Answers "How far along am I, and when will it be done?" on any subject (repo, folder, plan, task) — current position, what's left, and a banded ETA, computed fresh via a bounded read-only subagent. `--resume` rebuilds context after a gap (one next move + counter-case). Trigger phrases: "/orient-status", "where are we on this", "how far along", "what's the ETA". Not /orient-map (what changed since I last looked), /orient-gaps (what is stuck or missing), /orient-roadmap (what comes next and what gates it), /investigate (deep facts), /reflect (thinking), or a private arc-state status skill — orient-status SEES and reports NOW. 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: plan-create phrase: "/plan-create" why: "Turn the bearings into a phased plan for the next move" triggers: - "/orient-status" - "where are we on this" - "status quo and eta" - "how far along" - "what's the ETA" - "status of this repo or folder or plan" --- # /orient-status > **How far along am I, and when will it be done?** > **Answers with —** position · what is left · a banded ETA · (`--resume`) the one next move. > **Does not answer —** what changed (`/orient-map`) · what is stuck (`/orient-gaps`) · what comes next (`/orient-roadmap`). > **Owns for the family —** nothing topological; it reuses the shared topology contract in its existing bounded worker. Computes a fresh, honest read of **where the current work stands** — position, remaining work, and a banded ETA — and returns it as one ephemeral bundle (a structured YON record + a human markdown read + a small visual). `--resume` re-frames it for the "I just came back and lost the thread" case. Part of the `orient-` family; emits a 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. Reuse the shared topology-detection contract within the same single bounded worker, or consume supplied topology fields with their stated provenance and limits. Do not invoke another self-orchestrating orientation skill or start a second sweep; supplied and detected interpretations must agree or remain an explicit gap. ## When to use - "Where are we / what's the status / how far along / what's the ETA" on a project, repo, plan, or task. - After a context fill or at the start of a session, before deciding the next move. - **`--resume`**: you've been away (a gap, a context-switch) and lost the thread — you need *what changed + exactly where to put your hands next*. ## How it works (self-sufficient — works without `protocol.yon`) `orient-status` **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. 1. **Take intent as input, never prompt for it.** Intent (the goal / what "done" means) is the denominator every read leans on, and it is the *least* recoverable thing from evidence. Accept an `intent` argument if given. If intent can't be grounded (no stated goal, no plan, no README), **gate every intent-dependent field** — render it `— (needs goal)` and cap its confidence to `guessed`. **Never fabricate a goal** and hang a confident read off it. On an evidence-poor surface the highest-value output is the nudge: *"name the goal in one line and I get sharper."* 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** → `branch`, `dirty` count, `ahead`/`behind`, recent commit subjects (phase signal), `merge-base` (branch detection). - **plan/doc tier** → from a `PLAN.md`/`TODO.md`/checklist: `open_count`, the `open_set` items, `done_count`, the current phase/`frontier`, the `next_open` unchecked item. - **conversation/folder tier** → recent turns, the folder name, file mtimes for the live frontier. Every attested field comes back with a re-runnable `source:line`/git-ref **proof**. 3. **Compute three things:** - **Position** — the one-line headline state (phase / `frontier` / `on_branch`). Consume family topology as supplied: an absent `on_branch` means unknown, never false/trunk; do not recompute it or infer a topology-dependent ETA from its absence. - **Remaining + distance** — the `open_count` against its denominator (flag when the real remainder may be larger than the visible one — `denominator_trust`). - **ETA** — the one *non-observed* output. A **band, never a point estimate** (`~1–3 days`), tagged `estimate, not observed`. With no plan → `ETA: unknown`. A fabricated percentage or confident phase is **banned**. 4. **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 `ready`/`blocked` and never a bare `0`/`false` — on barren evidence. The empty-folder read is a success state, not a failure. 5. **`--resume` mode**: lead with the **resume-pointer** — the exact spot you stopped + the half-finished thought — then **exactly one next move + its counter-case + the single dropped alternative** (never a menu). Suppress the full snapshot. 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 structure in the worked examples; the **visual face is rendered per the [render-face contract](references/orient-spec/orient-contract.md) §2 (Claude Code only)**: for a human on Claude Code with the visualize tool present on an explicit invocation, build the **status widget** from the kit — call `mcp__visualize__read_me` once, then emit via `mcp__visualize__show_widget` an **identity nameplate + a position track (the phase spine, hand-SVG, fixed `viewBox="0 0 680 …"`) + a remaining load-bar + ledger (open-ended `▰▰▰▒╌╌?` when the denominator is unknown) + an ETA fading uncertainty band** (a point-marker is BANNED — the uncertainty *is* the datum), with the cursor/now the dominant element and `◆◐◌` tier glyphs as redundant **non-color** encoding; 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 status twin is emitted when the selected face includes a visual** — it is the only render in a no-SVG channel and carries every datum the widget does. The widget is **sparse** — a learn-once legend + tier glyphs, **never per-node sentences**. Below a grounding threshold (mostly `◌`) draw a **`NO SUBSTRATE`** card instead of a structural visual. 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 `/plan-create` otherwise). The footer's four faces, the **staleness short-circuit** (an unchanged last-look anchor → "no change in checked Git inputs"; uncovered inputs stay 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 a 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 `@SNAPSHOT` are parser-rejected. **List fields go in a sidecar `@MAP`, never an in-set bracket-list** (an in-set bracket-list corrupts the record *silently and still validates*). **Never run `yon format` on an emitted instance** — `CANON` mode is destructive on set-internal lists and the corruption still validates clean; hand-emit the `@MAP` sidecars and leave them. Validate with `--profile exec`. Minimal skeleton: ``` @CFG id=orient | set=[schema_version=orient-record/1,computed_at:ts=…,ephemeral:bool=true,tool=orient-status,tier=orient,scope=…,evidence_mode=git-only,gate_status=degraded,gate_confidence_floor=inferred,family_used=orient-status,family_suggested_next=plan-create,overall_trust=med,degraded:bool=true,degrade_reason="inferred advisory status; no attested blocking field"] @CFG id=subject | set=[name=…,kind=monorepo,purpose=…,purpose_source=readme,intent_status=stated] @CFG id=snapshot | set=[status=in-progress,stage=…,stage_idx:int=1,frontier=…,on_branch:bool=true,branch=…,dirty:int=0,ahead:int=0,behind:int=0] @CFG id=remaining | set=[open_count:int=4,done_count:int=1,fraction_done:flt=0.2,denominator_trust=inferred,next_open=…] @MAP name=open_set | pairs=["o1"->"…","o2"->"…"] @CFG id=forecast | set=[kind=prediction,provenance=extrapolated,eta_low=1d,eta_high=3d,eta_unit=calendar-days,confidence=low,unschedulable:bool=false] @CFG id=resume | set=[next_action=…,counter_case=…,dropped_alt=…,resume_confidence=high] # --resume mode only @MAP name=provenance | pairs=["snapshot.on_branch"->"git-attested:high:git-rev-parse"] ``` A full worked instance ships at [`references/orient-spec/examples/orient-record.example.yon`](references/orient-spec/examples/orient-record.example.yon). ## Output — worked examples (markdown face) **Rich tier (a git repo with a plan):** ``` 🧭 open-skills — public skills repo. [identity: ◆ git] **Now:** P1 — building orient-status on `feat/orient`. ◆ git `rev-parse` **Left:** 4 open · ~20% done (visible-only). ◐ inferred (checkboxes) **ETA:** ~1–3 days *(estimate, not observed)*. ◌ 2 data points **→ Next:** finish protocol.yon, then count-wiring. Trust: ◆◐◌ · ⚠️ lean here: the ~1–3 day ETA (2 points, not observed) · next → /plan-create ``` **Git-rich but intent-absent (the case `intent`-gating exists for — confident position, gated distance):** ``` 🧭 some-repo — a git repo on `wip`. [identity: ◆ git] **Now:** on `wip`, 3 dirty, 12 commits. ◆ git `rev-parse` **Left:** — (needs goal) · **ETA:** — (needs goal) ◌ no goal on record **→ Next:** name the goal in one line and I get sharper. ← position is real; distance can't be Trust: ◆◌◌ · ⚠️ lean here: there is no goal — every distance/ETA field is gated, not guessed. [limited evidence] ``` **Barren tier (a non-git folder, no plan — honest degradation is the success case):** ``` 🧭 ToDo — a folder (no manifest, no git, no README). [identity: ◌ guessed] **Now:** can't tell — barely-started / mid / near-done. [◌ no durable state] **ETA:** unknown — nothing to measure against. **→ Next:** name the goal in one line and I get sharper. ← the cheapest win Trust: ◌◌◌ · ⚠️ lean here: every line — no durable state exists. [cannot determine from available evidence] ``` The ASCII trust trailer with the `⚠️ lean your scrutiny here` line (naming the single load-bearing guess) is **mandatory** on the selected full human face. ## Boundaries - **Not `/investigate`** — that gathers arbitrary deep facts read-only; orient-status computes a fixed *position + distance + forecast* about ongoing work. - **Not `/plan-deep-dive`** — that walks an existing plan phase-by-phase for quality; orient-status reads the *current position* against whatever evidence exists (often no plan) and forecasts. - **Not a private arc-state status skill** — that kind pulls declared agent and arc state from a private system; orient-status orients on *any* subject (repo, folder, plan, task) from universal evidence. - **Not `/reflect`, not `insight-*`** — those THINK / DECIDE; orient-status only SEES and reports NOW. After it, reach for `/plan-create` to act, or a sibling lens (`orient-map` for the shape, `orient-gaps` for what's stuck) **once they ship** — until then the footer routes only to installed skills. - **Read-only.** It never mutates state; the one sanctioned reference point (an intent line / last-look anchor) is caller-supplied or harness-held, never written to disk by default. ## Rules - MUST take `intent` as input and **gate intent-dependent fields** when it's absent — never fabricate a goal. - MUST express ETA as a **band**, never a point estimate; MUST NOT emit a fabricated percentage or confident phase on an unknown denominator. - MUST tag every field with a provenance tier and **fail closed** — `gate_status` = `degraded`/`indeterminate` with a sentinel, never a plausible `ready` — 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; list fields as sidecar `@MAP`; 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 trust trailer with the `⚠️ lean here` load-bearing-guess line; **the ASCII status twin is mandatory for that selected visual face** — it is the only render in a no-SVG channel. - 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 → status widget + ASCII twin**; **other runtime / no tool / indeterminate `handler_type` → ASCII twin (fail-closed)**. The status widget is an **identity nameplate + position track + remaining load-bar + ETA fading-band**, the cursor/now the dominant element; **ETA renders as a band, never a point-marker**. - MUST keep the widget and ASCII twin projections of **one node-structure** (same labels + `◆◐◌` tier glyphs as redundant **non-color** encoding), chrome-compliant (colors only via CSS vars / `c-*` classes — no hardcoded hex; no `position:fixed`; `role="img"` + non-empty `<title>`/`<desc>`; fixed `viewBox="0 0 680 …"`), **checked by the repository-only `tools/orient-roundtrip.mjs` release guard when running from a clone; installed copies retain this as an emitter obligation**. The widget MUST be **sparse — a learn-once legend + tier glyphs only, NEVER per-node sentences or interpretive prose glued to elements** (its whole purpose is to *lower* cognitive load). - 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. - `--resume` MUST end in exactly ONE next move + counter-case + the single dropped alternative (no menu). > **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.