sge

Reference template and convention guide for custom orchestrators that dispatch SGE implementation lanes. Use when building a bespoke fan-out orchestrator (not /sge:team-pipeline or /sge:issue-swarm) and you need to know the correct way to batch-classify issues, inject SGE_GOVTRACE_VERDICT, and wire the governance gate into dispatched lanes.

Use when assessing how far a repo — or a whole portfolio of repos — has adopted atomic design; when design-token, primitive-layer, catalog, or enforcement maturity needs an evidence-backed score; when /sge:sge-align needs its L2 Design System signal (check C10); or before planning a design-system investment, extraction, or migration roadmap. Advisory and read-only — not for making changes.

Use when you need a conflict-safe set of open GitHub issues that multiple agents or pipelines can work in parallel without colliding — when /sge:team-pipeline asks for a work pool, when the user wants to "find issues safe to parallelise", "what can we work on at once", or "pick the next non-conflicting issue", or to surface what is blocked vs ready. With --fleet, aggregates the same conflict-safe, dependency-annotated worklist across every repo in a fleet (a GitHub org or an explicit repo list) for org-wide dispatch. Read-only discovery and analysis; it does not implement issues.

Use when a GitHub issue (or a batch of them) must be gated as build-ready before any agent picks it up — clear acceptance criteria, bounded scope, no unresolved open questions or decisions, dependencies resolved, AND classified against the repo's SGE governance artefacts — so a swarm or pipeline only burns implementation effort on well-defined, governed work. This audit folds in the /sge:governance-trace classification (opt-out via --skip-governance) so callers make one skill hop, not two. Invoke when asked to "check build-readiness of these issues", "gate the backlog before swarming", or when /sge:available-issues / /sge:issue-swarm dispatches its per-issue go/no-go. Writes routing verdict labels to issues (Step 3R); does not implement issues. For the deep per-spec entry check use /sge:sge-preflight.

Use when committing work in a WTP/SGE repo — at the end of an implementation slice, before opening a PR, or whenever changes are ready to be recorded with quality gates and SGE traceability trailers. Also use when another skill says "commit via /sge:commit". Not for amending history or interactive rebase.

Use when you need to check the current session's token consumption against the active spec's BudgetPolicy — mid-session budget spot-checks ("are we within token budget?"), before starting another expensive slice on a metered spec, or whenever SGE_SPEC_ID is set and budget pressure is suspected. Advisory soft gate — reports an ok/alert/deny verdict but never stops the session itself. For cost attribution reporting use /sge:roi-report.

Use when a single GitHub issue is too large to implement in one session and should be split into ordered, parallel-safe child sub-tasks — an enabler plus independent vertical slices that can be worked concurrently without touching the same files. Use whenever the user asks to decompose, break down, split, or fan out a large issue, or when /sge:sge-implement Phase 2 sizes an issue as Large (> 30). Not for building — it creates the child issues and the orchestration plan, then hands off to the implementation pipeline.

Use when a GitHub issue needs in-depth investigation and a recorded decision rather than immediate implementation — an unclear bug root cause, a feature whose blast radius and alternatives need weighing, a suspected duplicate or stale issue, or a drift issue raised by /sge:sge-align that needs triage. Not for building; for SGE spec issues use /sge:sge-preflight then /sge:sge-implement.

New-org rollout runbook — stand up an Upptime status repo, GitHub Pages site, custom domain, optional brand skin, and SGE DORA feed from scratch. Generic; no org-specific assumptions.

Use when a repo's SGE Audit Score (the `/sge:sge-align` per-check governance-coherence rollup — an operational fleet-audit signal, distinct from and NOT the platform's canonical SM-2 `coherence_score`) or a specific drift metric needs to be actively raised, not just measured — closing the loop the SGE platform's daily drift snapshot and `/sge:sge-align` only open. Picks the highest-leverage drift gap, opens ONE bounded PR to close it, re-measures with an independent sweep, and repeats until the target is hit or a bound stops it. Comparative-goal, metric-hill-climb loop. Advisory, PR-first, bounded.

Use when an unattended SGE session's throughput collapses or could — orphaned dev/test-server processes burning CPU, a relocated checkout with broken pnpm symlinks, more concurrent sessions than the box has cores, or a hung install. Run it hourly as a background monitor and as a preflight gate before any fan-out (team-pipeline / issue-swarm) so saturation and broken environments are caught and self-healed before work starts, not hand-diagnosed hours later.

Canonical exit-report contract for orchestrated SGE skills — one machine-readable JSON shape (schema.json beside this file) that orchestrators consume to decide the next move. Fields — skill, runId, duration, itemsProcessed, outcomes[], stopReason, followUps[]. Emitting skills link here instead of inventing bespoke report blocks; this file is not a user command.

Use when fixing a GitHub issue that reports a production bug or regression — routes to /sge:sge-implement, with Sentry context (stacktrace, breadcrumbs, environment) gathered as pre-context when a Sentry issue ID is referenced.

Canonical reference for targeting the right GitHub repo when an SGE skill is invoked outside the target repo's checkout — the GH_REPO / cd convention for cross-repo and hub (control-session) dispatch, the startup echo check, and the raw-git pitfall. gh-heavy skills link here instead of restating the boilerplate; this file is not a user command.

Use to classify a GitHub issue against a repo's SGE governance artefacts — Vision, Capability Model, Feature Specs — before any code is written. Determines whether the work matches an existing spec unchanged, would modify an existing spec's stated requirement, needs a new spec (capability gap), needs no spec (chore/infra), or falls outside SGE scope entirely (Vision non-goal conflict / ungoverned work). Use whenever `/sge:sge-implement` Phase 0.5 dispatches its mandatory pre-implementation gate, whenever `/sge:deep-dive` Phase 4 needs the shared classifier instead of ad-hoc judgment, or when a human wants to check "does this need a spec, and would it change one?" before starting work by hand.

Use when implementing a GitHub issue that does not reference an SGE spec (no `SPEC-NNN` / legacy `SGD-NNN` in the title or body) — plain feature, bug-fix, or chore issues.

Use when you want an unattended, weekly cadence that keeps a repo's SGE efficacy climbing on its own — the scheduled sweep that reads the three drift trend surfaces (Audit Score coherence, token-economy, skill-quality), picks the single highest-leverage gap across those dials, runs the matching drift-hillclimb dimension for exactly ONE bounded PR, re-measures, and appends the measured delta. This is the cadence layer that makes F-EFFICACY (SGD-044) real. Invoke on a weekly cron/`/loop`, or by hand to run one sweep cycle now. It never opens more than one PR per cycle and every cycle — acted, skipped, or failed — appends a visible delta row.

Use when you want to point an agent at a repo's backlog and drain it one issue at a time — each build-ready issue worked through the full SGE pipeline (implement → review gate → merge) until /sge:available-issues --mode autonomous-next returns no next issue. Invoke when the user says "work the backlog one issue at a time until it's done", "keep implementing the next issue until none are left", or wants a queue-empty-bounded (not duration-bounded) unattended serial run. For parallel or time-boxed runs use /sge:issue-swarm or /sge:team-pipeline instead.

Use when you want an autonomous, time-boxed run that continuously works build-ready SGE issues to reviewed, green PRs and stops cleanly when a wall-clock budget expires or the queue drains. Invoke when the user says "swarm the issues for the next 2 hours", "burn down the backlog until lunch", "run an unattended SGE session with a hard stop", or wants duration-bounded parallel issue progress that never overruns.

Canonical reference for the four loop patterns used across SGE skills — the inner Red/Green/Refactor loop, the wait-for-condition loop, the bounded refinement loop, and the recurring cross-session loop. Other skills link here instead of re-describing a loop; this file is not a user command.

Interactive onboarding skill — guided first-week path for a new developer (--dev) or ceremony-overlay adoption for an existing agile team (--team)

Use when a single pull request's CI is red and needs driving to green — failing required checks blocking a merge, a PR stuck on lint/test/build failures, or when /sge:pr-monitor classifies a lane PR as CI-failing and dispatches a fix. Also handles a dirty (conflicting) PR and, with --all-prs, a whole backlog of red PRs in one pass.

Use when several open PRs need shepherding to merge without babysitting — after a batch of PRs lands, when the user asks to monitor/babysit/drive open PRs, when a backlog of red or review-blocked PRs has built up, or for unattended merge-queue duty on a repo.

Use when a pull request needs the SGE merge-gate review — before merging any PR, when a PR is review-blocked (`mergeStateStatus: BLOCKED` or the `pr-reviewed` label is missing), when /sge:pr-monitor routes a lane PR here, or when new commits have landed on an already-reviewed PR and a delta re-review is needed.

Use when a pull request needs runtime/behavioural QA — when the merge decision needs evidence that the change actually works in the running app (not just that the diff looks right), when a linked issue's acceptance criteria or an SGE spec's Gherkin scenarios must be exercised against a live build, when /sge:pr-review Phase 4 wants a QA report comment for a high-risk PR, or when a UI/API change needs captured behavioural evidence before sign-off. This skill starts the app, exercises the feature, and posts evidence; it applies no merge-gate labels. For reviewing the diff itself and owning the pr-reviewed gate label, use /sge:pr-review instead.

Pre-flight filter for dispatch skills — drop issues/files already merged, closed, or present on main before any agent fan-out. Call before spawning implementation agents to prevent re-doing completed work.

Use when the user asks to refactor, restructure, or clean up existing code, or mentions code smells, duplication, a god class or god function, tangled dependencies, dead code, cleanup, or tech debt. Behaviour-preserving restructuring only — not for new features or bug fixes.

Use when a regulated WTP repo must map its feature specs and capabilities to named FCA / UK-regulatory obligations and frameworks (ISO 27001, ISO 42001, ISO 27701) and export that mapping as audit evidence — preparing for a client's third-party due-diligence pack, an FG26/4 material-arrangement registration, an ISO surveillance audit, or a tripartite (firm + auditor + regulator) evidence request. Also use when a spec in a 'regulated' capability lacks an obligation mapping, or when /sge:sge-align's C12 regulatory-traceability check raises drift. Complements /sge:sge-ai-inventory (which governs AI *use cases*) — this skill governs *spec-level SDLC traceability* across ALL specs, AI or not.

Operational reference for the SGE review daemon (SPEC-090 Layer 1). Read before operating, configuring, or extending the daemon or its claim-mutex protocol.

Use when you want a token cost attribution report for AI-assisted development — "where did our tokens go?", per-spec and per-PR cost breakdowns, the governed-vs-unattributed spend gap, or a sprint-end/CI cost snapshot (optionally pushed to the SGE platform with --push). Pure reporting, no budget enforcement — for live budget checks use /sge:cost-guard.

Use when a team wants to assess their readiness for SGE adoption before committing — produces a scored readiness assessment and a sequenced rollout plan. Run this before /sge:sge-init for new prospects or teams. Not for teams already running SGE — that is /sge:sge-align.

Use when a financial-services organisation needs to register, document, or review its AI/LLM use cases — adopting Claude or any model with full controls, preparing for FCA/PRA or EU AI Act scrutiny, completing a DORA third-party register entry, drafting model-risk documentation, running vendor due diligence on an AI provider, or when someone asks "what AI are we running and is it governed?". Also use when a new AI feature is proposed in a regulated repo and no inventory entry exists yet.

Use when checking a repo — or a whole fleet of repos — for SGE governance drift; when a built feature has no spec, a spec has no Gherkin, or code has no governing artefact; when open GitHub issues may no longer match current scope after a Vision, capability, or spec change; when a repo-level or org-wide Audit Score (governance-coherence) scorecard is needed; or before a governance review or client audit. Also use for Zero-Trust agent-security scoring via --dimension agent-security, FCA/UK regulatory-traceability scoring via --dimension regulatory, or skill-quality scoring via --dimension skill-quality (delegates to /sge:sge-skill-audit).

Use when a repo should publish the SGE coherence dashboard — the brand-neutral single-page site (Vision → Capabilities → Features → Specs → Test Pyramid → Decisions → Live Coherence) generated from docs/sge-dag.json + the SGE markdown + the repo's own code. Invoke to adopt the sge-dashboard kit in a repo for the first time, to refresh/rebuild it, or to wire it into CI. Not for authoring specs (that is /sge:sge-init / /sge:sge-implement). Not for applying WTP's own brand — that is a separate, WTP-only step (see "Applying a brand" below); this skill's default output carries no customer's branding.

Use when implementing a GitHub issue end-to-end — both issues that reference an SGE feature spec (`SPEC-NNN`, or legacy `SGD-NNN`) and plain feature/bug/chore issues with no spec. Use whenever the user asks to build, implement, or ship an issue through to a merged PR.

Use when onboarding a new product or a greenfield repo onto SGE — when a repo has no Vision, capability model, or feature specs yet; when the user asks to set up SGE, seed governance artefacts, or run product intake; or when an intake/brief document needs turning into SGE seed artefacts. Not for auditing an already-seeded repo — that is /sge:sge-align.

Use when preparing to implement an SGE feature spec — before any branch, plan, or code exists — when asked to preflight or check build-readiness of a SPEC-NNN, or when /sge:sge-implement Phase 1 delegates its entry-criteria checks.

Use when a finished implementation needs an independent review against its SGE spec — after coding completes and before a PR is opened, when /sge:sge-implement Phase 5 delegates its pre-PR review, or when asked to verify that work satisfies a SPEC-NNN.

Use when you want to score the quality of one or more SGE skills against the SQ-0–SQ-5 skill-quality dimensions (Frontmatter Integrity, Executability, Cost-Awareness, Scope Clarity, UNTRUSTED DATA annotation, Tool Sequencing). Run against a single skill before merging a SKILL.md change, or sweep all skills for a fleet quality report. Also the delegation target for /sge:sge-align's skill-quality dimension (that wiring lives in sge-align; this skill works identically standalone).

Use when a spec doc's `## Validation` section (docs/specs/README.md convention) needs to be run against a demo fixture — checking that a spec's stated business-rule invariants (e.g. "C1 must be ≤ Addressable − Exclusions", "Total = Exclusions + C1 + C2 + C3") actually hold, not just that a test exists for the scenario. Invoke after adding or editing a `## Validation` section, at spec-graduation time (draft → approved → implemented), or when /sge:sge-align's C4 sub-check flags an implemented spec with a missing or unverified Validation section.

Use when writing the next increment of implementation code — the inner Red/Green/Refactor loop inside any implementation workflow. Triggers on implementing a feature slice, fixing a bug test-first, or any task where production code is about to be written.

Use when you want to run multiple SGE implementation agents in parallel, continuously implementing and reviewing issues as a pipeline. Invoke when the user asks to "run the pipeline", "work issues in parallel", "batch implement issues", or wants unattended multi-issue progress. With --duration it is also the time-boxed swarm engine ("swarm the issues for 2 hours", "burn down the backlog until lunch") — duration-bounded progress that never overruns.

Use when the user wants to clean up, tidy, prune, sweep, or remove git worktrees or stale branches — after merging a batch of PRs, before starting new work, when worktree/branch sprawl builds up, or when they ask for a fast "delete everything not tied to an open PR" sweep (that is the --force mode). Destructive in its final phase — even --force never deletes without a single user-confirmed deletion plan listing tip SHAs.

Use when installing the SGE Traceability Module (SPEC-054) into the current repo — copies the traceability data builder and interactive chart page, wires the docs Pages workflow, and opens a draft install PR. Run from inside a cloned SGE-governed repo checkout when the user asks to "install the traceability chart/module". For the web-UI install use the SGE Modules tab instead; this skill does not build or audit traceability data itself.

Verify a completed change — run the quality suite and check the diff against acceptance criteria. Accepts `--tier trivial` to use inline verification instead of spawning a review subagent.

Canonical reference for where SGE skills place git worktrees — the sibling `../<repo>-worktrees/<purpose>-<id>` layout, the in-repo `.worktrees/issue-N` team-pipeline exception, and the deprecated stray layouts. Other skills link here instead of restating placement rules; this file is not a user command.