/orient

name: orient
description: >-
  Orient a spec-driven jig/servo/shaper repository with a read-only, project-wide
  briefing: start from the `workflow.py orient` headline, survey open pull requests,
  unmerged work, Proposed ADRs, DEFERRED triggers, refinement items, release scope,
  the inbox, and the bug board, then recommend where to start. Use when the user
  invokes `/jig:orient` or explicitly asks for a whole-project session pickup, a
  return-after-time-away briefing, the overall project status or big picture, or
  what to pick up across the repository. Do not use for a bare "what's next?"
  ("next step?", "what should I pick up next?"): answer it directly with the next
  step from the current plan or session context, then ask whether the user wants
  the full project orientation, and run this skill only if they say yes. Do not
  use for work questions like "what's blocking this test?", or for non-code
  projects (use `studio:project-desk`). Never write files or lifecycle state;
  scheduled jobs and dashboards may capture stdout.

Orient

**One job: tell the user where the project stands and what to do next, in a shape they can actually read.**

The user runs `/jig:orient` (or asks to be oriented) — the calm manager's question, *"where do things stand, and what should I pick up?"* Orient answers it by reading the project's own truth (not guessing), and presenting it in **one fixed, scannable layout**: a headline that tells the honest state, then a short stack of **titled sections**, each a list of **titled bullets** — never a wall of inline prose with items buried mid-sentence.

The substance is grounded; the **format is the point**. If the answer reads like a paragraph with five things crammed into it, the skill has failed even if every fact is right.

---

Scope check — before running anything

This is a **project-level rescan**. Look at how you got here:

• **The user invoked `/jig:orient`, or explicitly asked for the whole-project

picture** (a session pickup, a return after time away, "where does the project stand overall") → run the full orientation below. Don't ask first.

• **The user asked "what's next?"** (or any bare next-step question: "next step?",

"next task?", "what should I pick up next?") → give the short answer first, in a line or two: the next step in the plan or task list in progress, else the SessionStart `jig hint:` focus, else say you have no current plan in view. Then ask one question: do they want the full project orientation?

• **No** → stop there: no headline command, no survey, no briefing.
• **Yes** → run the full orientation below, collaboration survey included. That is

the project-level "what's next" spec 101 fixed.

If you're unsure which case a question fits, treat it as a "what's next?".

---

Start from the deterministic headline

Do not re-derive the project's lifecycle state by hand — jig already computes it. Run the read-only command spec 088 added and use its line as your factual base:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/spec-workflow/workflow.py" orient --project-dir . --fetch
# → jig hint: <scaffold state> · active specs: <rollup> · focus: <slice needing attention>
#   …and, only when the checkout is ahead of its default branch:
#   · in flight: <n> commit(s) ahead of <base> on <branch>
#   …and, only when the --fetch check finds a problem:
#   · freshness: <n> commit(s) behind <base>   |   could not reach origin

Pass **`--fetch`**. Orient reads *local* boards, ADRs, and slice `STATUS` — all only as current as your last fetch — so an interactive orientation must refresh against origin first, or it will confidently narrate a stale picture (work already shipped on trunk reported as still open). `--fetch` runs one bounded, fail-soft `git fetch` and adds a `freshness:` segment when the checkout is **behind** origin, or when origin **could not be reached** (offline: the local view is unverified, not confirmed fresh). This flag is for the interactive path only — the SessionStart hook never passes it (spec 103's git-freshness hook already fetches at time-zero), so the hot-path headline is unchanged.

That single `jig hint:` line — scaffold classification, active-spec rollup, and the slice currently requiring lifecycle attention — is the **deterministic headline**. Reusing it (rather than re-implementing a second lifecycle-focus algorithm) keeps Orient's headline from drifting away from jig's own computed state. Orient's job is to **layer judgment on top**: the ADRs, deferrals, release plans, refinement-todo, inbox, and standalone bugs that the one-line command does not weigh, then recommend one thing.

**If the headline shows `freshness: … behind …`, treat every local artifact below as possibly stale** — say so in the headline, and recommend integrating origin (or re-running after a pull) before trusting the boards. A `could not reach origin` reading means you could not verify freshness at all; report that honestly rather than implying the state is current.

---

The prime directive — formatting

These rules are non-negotiable. They are the reason this skill exists.

• **Every distinct item is its own bullet, led by a short bold title.**

`- **Recents (002-07)** — the last fork of the quick-add split; needs a Home-row mockup first.` Never `favourites are done and recipes are done but recents still needs a design and also backup restore is parked and…`

• **Group bullets under `##` / `###` section headers.** The reader should be able to

jump to "the deferred stuff" or "the one decision" by scanning headers alone.

• **No inline lists.** If you catch yourself writing "X, plus Y, and also Z" where X/Y/Z

are separate pieces of work, stop and turn them into three bullets.

• **One line per item where possible.** Title — what it is — the blocker or trigger.

Keep each bullet to roughly one sentence; detail goes in a sub-bullet only if it earns it.

• **Lead with the answer.** The headline and the obv