build-order

Plain-language prompts (alternatives to /build-order)

Any of these phrases should trigger this skill when spoken in natural language — please invoke /build-order when the user asks:

• "What feature should I build next?"
• "Show me the build order"
• "What's next in the Spec Kit queue?"
• "Which features are ready to build?"
• "What's blocked and why?"
• "What's the build status?"
• "Where are we in the roadmap?"

User Input

$ARGUMENTS

Arguments are whitespace-separated tokens in any order. Three kinds are recognised:

• Tier filter — a single digit 1, 2, 3, or 4. Passed through to the scanner as --tier=<N> (or as a bare digit — generate.ts accepts both).
• stale — show the full stale-artifacts table (normally collapsed behind a count when >5 rows). Sets STALE_FULL=1 env var for generate.ts.
• Output format — one of text, html, or both. Controls which artifacts you show the user:
  • text — run generate.ts --format=md, print its markdown, do NOT open the browser.
  • html — skip the scanner entirely, just open docs/build-order.html (trust git hooks + CI for freshness; see Step 0.5 freshness check).
  • both (default) — run generate.ts --format=md, print its markdown, AND open docs/build-order.html.

Any other token is ignored with a stderr warning. /build-order 1 text, /build-order text 1, and /build-order 1 are all valid. /build-order html skips the scanner entirely.

Workflow

Step 0 — Determine output format (before anything else)

Output format determination follows a graceful-fallback ladder. AskUserQuestion is unverified inside skill workflows — in non-interactive contexts (CI, /loop auto-pacing, parent-skill invocation) it can deadlock or silently default. The ladder below treats interactive prompting as a best-effort last resort.

1. Parse $ARGUMENTS. Tokenise on whitespace. If any token equals text, html, or both (case-insensitive), use that format — skip to Step 1. (If multiple format tokens are present, use the last one and warn about the others on stderr.)
2. Check for non-interactive signals. If the environment variable GITHUB_ACTIONS=true is set, default to both and skip to Step 1. (Other non-interactive signals are less reliable; rely primarily on this one for CI contexts.)
3. Try interactive prompt. Invoke AskUserQuestion with three options: Both (default) — text + open HTML, Text only — print markdown, no browser, HTML only — skip scanner, open the styled report. Use Both as the default selection. If the prompt succeeds, use the user's answer.
4. Fallback on prompt failure. If AskUserQuestion is unavailable, throws, or times out — default to both and continue. Never block. The markdown is always valuable output; worst case is the user sees both artifacts when they'd have chosen one.

Step 0.5 — HTML freshness check (only when format = html)

When the user picks html (either via $ARGUMENTS or the prompt), run a quick freshness check before calling open docs/build-order.html:

if [ -f docs/build-order.html ]; then
  html_mtime=$(stat -f %m docs/build-order.html 2>/dev/null || stat -c %Y docs/build-order.html 2>/dev/null)
  specs_newest=$(find specs -name tasks.md -exec stat -f %m {} \; 2>/dev/null | sort -nr | head -1)
  [ -z "$specs_newest" ] && specs_newest=$(find specs -name tasks.md -exec stat -c %Y {} \; 2>/dev/null | sort -nr | head -1)
  if [ -n "$html_mtime" ] && [ -n "$specs_newest" ] && [ "$html_mtime" -lt "$specs_newest" ]; then
    echo "WARNING: docs/build-order.html may be stale (no local regen since specs/ changed); consider running in 'both' mode to refresh." >&2
  fi
fi

Do NOT auto-regenerate — the CI + git hooks are the regen authority. Just warn and proceed to open the HTML.

Step 1 — Run the scanner (for text and both formats; skipped for html)

1. Run the scanner (canonical mode — fetches from origin/master before scanning):

   env -u BUILD_ORDER_USE_WORKING_TREE STALE_FULL=<1-if-stale-arg-else-0> npx tsx scripts/build-order/generate.ts --format=md ${tier:+--tier=$tier}
   

   Set STALE_FULL=1 when $ARGUMENTS contains stale (shows full stale table); otherwise STALE_FULL=0. The env -u BUILD_ORDER_USE_WORKING_TREE prefix unsets that env var so a dev with it in their shell profile still gets canonical mode from /build-order.

   The scanner fetches origin/master before scanning. Spec files are still read from the working tree, so unmerged local changes to specs/ are visible. In canonical mode, the scanned-at source ref is derived from origin/master, but other metadata such as timestamps or displayed commit SHA may still reflect wall-clock execution time or the current checkout. If the fetch fails and BUILD_ORDER_USE_WORKING_TREE is not set, the scanner exits non-zero with a clear error message.

   If a dev genuinely wants working-tree mode (rarely — only for debugging uncommitted local edits), set BUILD_ORDER_USE_WORKING_TREE=1 and run npx tsx scripts/build-order/generate.ts --format=md directly, NOT via /build-order. CI auto-bypasses the fetch gate via GITHUB_ACTIONS=true since CI is already on the correct ref.

2. Output the scanner's markdown verbatim to the user. Do NOT summarize, paraphrase, strip emoji, or cut sections. The scanner produces a complete report and the user wants to see all of it. Only add a brief sentence before or after the report if you're highlighting something specific (e.g., "Here's the current build order:" or "The blocked feature waiting on F17 is D3.").

   The scanner's output includes ALL of these sections (depending on what's in the repo):

   • Summary — headline counts (built / in progress / ready / blocked / logically ready / logically blocked / not planned)
   • Up Next — the single top pick across the unified ready ∪ logicallyReady queue, sorted by priority (P1>P2>P3>untagged) → tier (1>2>3>4) → spec number → tasks.md-present. Shows title, fid, tier, priority, branch, and the Next command to run (/speckit-implement if tasks.md exists, else /speckit-plan). Before running that command, run /speckit-claim {N} to claim the spec and create your branch. Replaces the legacy "Next recommended" + "Next to plan" pair.
   • Proceed (N) — full unified queue in the same sort order. Each row's "Next command" column tells you which /speckit-* skill to run to advance that spec.
   • Waiting on in-progress work — Tier 1+2 specs stuck behind currently IN PROGRESS upstream work. Informational; NOT a warning and NOT blocked by missing deps — the deps exist and are being built right now. Not fatal to CI.
   • Parallelism waves — Wave 1, Wave 2, etc. — features that can be built simultaneously because their deps are all in earlier waves (Tier 1+2 only, includes logically-ready specs)
   • In progress — specs with partial tasks.md completion, showing progress fraction and branch status
   • Ready to build — specs with all deps satisfied and tasks.md present, showing deps column and branch status
   • Blocked — specs with unsatisfied deps and tasks.md present, showing which feature IDs they're waiting on and branch status
   • Built — specs with 100% tasks.md completion
   • Logically ready — specs without a tasks.md but with all dependencies satisfied. These can be planned immediately. Table includes Priority column (P1/P2/P3 or - for untagged). Sorted by priority → tier → spec number.
   • Logically blocked — specs without a tasks.md and with unsatisfied dependencies. Shows which deps are missing.
   • Not yet categorized — specs with no dependencies declared and no tasks.md. Readiness cannot be determined from the dependency graph.
   • Superseded — specs whose frontmatter declares Status: Superseded. Collapsed bullet list with the fm note (what they were consolidated into). Excluded from dependency resolution and waves.
   • Drift warnings — specs where Status: Built in frontmatter contradicts an incomplete tasks.md. Non-fatal at scan time; CI lint (.github/workflows/build-order-lint.yml) fails the build if this section is non-empty.
   • Data integrity warnings — emitted at the top of the report when the spec corpus itself has authoring bugs: duplicate Feature IDs, unknown dep references (F## in a Depends On that has no authoring spec). CI lint fails on any such warning.
   • Migration Backlog Report — appended after the feature sections so /build-order is the single unified entry point. Same content as /migration-backlog summary: next-actionable migrations, deferred entries with triggers, externally-blocked, and the full planned list. Reads scripts/lib/migration-backlog-data.ts via scripts/migration-backlog.ts.

   Every table row includes a Branch column with one of:

   • 📍 on this branch (user is currently checked out)
   • 🌿 local (branch exists locally)
   • ☁️ remote (branch exists on origin only)
   • - (no branch anywhere)

   Pass the emoji icons through as-is. Modern terminals render them. Do not substitute ASCII.

Step 2 — Pop the HTML report in the browser (for html and both formats; skipped for text)

The committed docs/build-order.html is regenerated by CI on every push to master and by local git hooks on pull/checkout/commit; popping it after each /build-order run keeps the styled view in sync with the markdown the user just saw. Use the cross-platform helper:

bash .githooks/_open-html.sh && bash -c '. .githooks/_open-html.sh && open_build_order_html docs/build-order.html'

Or directly: open docs/build-order.html (macOS) / xdg-open docs/build-order.html (Linux) / explorer.exe docs/build-order.html (WSL). If popping fails (no display, headless SSH), don't retry — the markdown the user saw is the authoritative report.

For html format: after the Step 0.5 freshness check warns (or not), run the open command and that's it — no scanner, no markdown to the user.

4. If the user asks follow-up questions about a specific feature's dependencies, you can read the corresponding specs/NNN-*/spec.md directly — don't re-run the scanner for single-feature questions.

5. For a styled HTML view with a mermaid dependency graph: docs/build-order.html is the browser-viewable report, regenerated by local git hooks (git config core.hooksPath .githooks) on pull, checkout, and commit, and by /build-order itself. CI does NOT auto-commit it (GitHub blocks the bot from bypassing required PR review); the file lands in master through normal human PRs that touch specs/migrations/scanner. CI surfaces drift via job summary so a regen-and-commit is added to the next relevant PR. Same source data as the markdown, richer presentation.

How build status is derived

Frontmatter-first resolution ladder. The scanner checks **Status**: in each spec's header and falls back to tasks.md completion only when the frontmatter doesn't declare a terminal status:

1. Status: Superseded … → SUPERSEDED (own section, excluded from deps/waves)
2. Status: Complete … → BUILT (fm note captured)
3. Status: Built (partial — …) → IN PROGRESS (parenthetical captured as note)
4. Status: Built → BUILT
5. tasks.md missing → NOT PLANNED
6. tasks.md all [x] → BUILT
7. tasks.md some [x] → IN PROGRESS
8. tasks.md all [ ] / empty → NOT BUILT / NO TASKS

Drift warnings. If frontmatter says Status: Built AND tasks.md still has unchecked items, the spec is flagged in a dedicated ## Drift warnings section. The frontmatter signal wins (spec is classified BUILT), but the warning surfaces the inconsistency so the spec author can resolve it. CI lint fails on drift.

Depends On sentinels. Three states for the **Depends On**: line matter:

• Missing — no line at all. Unbuilt specs land in "Not yet categorized" (author must declare intent).
• None / N/A / - — explicit no-deps. Unbuilt specs land in "Logically ready" — plannable immediately.
• One or more refs — real deps. Walked against the built set; ready or blocked based on result.

This distinction makes "I haven't decided" different from "I've decided: no deps." Both are valid states but route differently.

Why frontmatter first. tasks.md-only was fragile: 14 specs shipped and had their Status updated in frontmatter but never had a tasks.md authored, and the scanner silently misclassified them as "not planned" and leaked them into Wave 1 parallelism suggestions. Frontmatter is the author's declared truth; tasks.md is the in-flight-work signal. Trust the declared truth, warn on divergence.

How dependencies are resolved

The scanner reads two lines from each spec's frontmatter and merges them into a single dependency set:

1. **Depends On**: F## Feature IDs — feature-level dependencies resolved against other specs in the specs/ directory
2. **Required Migrations**: NEW-### migration tags — schema-level dependencies resolved against the /migration-backlog registry at scripts/lib/migration-backlog-data.ts

A spec is classified as:

• Ready if it has no dependencies OR all its dependencies (features + migrations) are built
• Blocked if any dependency is not yet built. The "Waiting on" column in the blocked table lists both F## and NEW-### tags side by side.

Cross-reference to /migration-backlog: at startup, the scanner shells out to npx tsx scripts/migration-backlog-dump.ts once to get a TSV snapshot of every migration tag and its current status (via alias resolution for implemented_by entries). A migration is considered built if its status is built, built (schema), or built (reduced). Deferred, retracted, and planned tags count as not-built. If the dump helper fails (missing tsx, registry corrupt), the scanner falls back to F##-only dependency resolution with a stderr warning — the feature-level classification still works, just without the migration-dep overlay.

Example frontmatter:

**Feature ID**: F15
**Depends On**: F10 Deal Memory, F14 Calibration
**Required Migrations**: NEW-065, NEW-079

A spec with that frontmatter is ready only when F10, F14, NEW-065, and NEW-079 are all built. If NEW-065 is still planned, the scanner puts F15 in the blocked table with Waiting on: F14,NEW-065.

Why both fields instead of one: feature deps and migration deps have different granularity and different sources of truth. Feature deps live in the same spec directory tree; migration deps live in a machine-validated registry with a CI lint. Keeping them as separate frontmatter lines makes the declaration explicit and lets the scanner dispatch on the tag prefix without ambiguity.

Recommendation algorithm (Up Next + Proceed)

Up Next and the Proceed queue both draw from the unified union of ready ∪ logicallyReady and sort by a fully locked deterministic key:

1. Priority tag — P1 > P2 > P3 > untagged. Extracted from **Priority**: P1 in spec frontmatter. Priority is the primary key. A P1 Tier-2 Logically-Ready spec WINS over a P2 Tier-1 Ready spec — because priority trumps tier.
2. Tier — Tier 1 > Tier 2 > Tier 3 > Tier 4 > untiered.
3. Spec number — lowest first.
4. Tasks.md present — when all three above tie, the spec with tasks.md (Ready) wins over the one without (Logically Ready). This is the first-movers tiebreak: implement beats plan when everything else is equal.

The same key is used for the single Up Next pick and the full Proceed ordering. Same repo state → same recommendation every time.

The legacy "Next recommended" + "Next to plan" sections are removed from the rendered report, but BuildOrderModel.nextRecommended and nextToPlan are preserved in the model for downstream consumers that read the JSON output (deploy-monitor skill, external scripts).

Estimated effort per spec

Specs may declare a rough size estimate in their frontmatter:

**Estimated effort**: M

The size token is one of XS / S / M / L / XL. The scanner maps to hours via a single constant in scripts/build-order/types.ts. The mapping is tunable in one place:

Size	Hours	Rough dev time
XS	4h	half day
S	8h	1 day
M	16h	2 days
L	24h	3 days
XL	40h	1 week (scale cap)

The XL cap at one week is deliberate. Specs that exceed one week of dev time should be split into multiple smaller specs, or represented as an epic in a task tracker where child work fits the XL-and-smaller scale. The scanner does not model multi-week epics.

Specs without the field are counted in specsMissingEstimate and render as — in the HTML. The summary aggregates across only the specs that have an estimate — totals are honest about incomplete data.

The HTML surfaces effort in three places:

• Summary band: X hours built · Y hours remaining · Z hours total · N of 53 specs estimated
• Up Next card: the top pick's size + hours as a meta label
• Kanban cards: size abbreviation as a small badge on each card

Tuning the scale is one-line: edit EFFORT_SIZE_HOURS in scripts/build-order/types.ts. No per-spec edits needed.

Forward-compat format: **Estimated effort**: M (~16h) is also accepted — the parenthetical is informational only; the scanner uses the bucket. Authors who want to override the bucket value should edit EFFORT_SIZE_HOURS instead.

Remote freshness check

The scanner runs git fetch origin --quiet at startup to update remote refs. After the main report, it compares each spec's local tasks.md against origin/master:specs/NNN/tasks.md. If origin/master has a more complete tasks.md (more [x] items, or a tasks.md that doesn't exist locally), the scanner flags it in a Stale local data section with a git pull prompt.

This closes the multi-dev visibility gap: if another developer merges a completed feature to master, every dev running /build-order sees the stale warning without needing to remember to pull first.

The fetch adds ~1-2 seconds. If the machine is offline or has no remote configured, the fetch fails silently and the remote check is skipped.

Constraints

• Read only. The scanner never modifies any spec file.
• Fast. Core scan runs in under 2 seconds. Remote fetch adds ~1-2 seconds. Migration backlog (if npx available) adds ~3-5 seconds.
• Tolerant. Handles multiple frontmatter variants (Feature ID / Build Status / Implementation Status / Tier formats). Unparseable specs land in "Not yet planned" or "Unknown" buckets rather than crashing.

When to use this skill

• At the start of a session when choosing which feature to work on next
• When planning a sprint and deciding what's buildable
• When onboarding a new dev who wants to know where the project stands
• When Brad asks "where are we" or similar status questions

When NOT to use this skill

• Never use it to decide if a feature is "done" — it only shows task completion, not shipped/merged status. The canonical source of "shipped" is the merged PR history on master.
• Don't run it during active /speckit-implement work — it reads the same tasks.md the implement skill is updating, so the output will lag behind reality.
• Don't run it in a feature branch to check another feature — it scans specs/ on the current checkout, so the output is branch-relative.