Source Command Implement Roadmap

source-command-implement-roadmap

Use this skill when the user asks to run the migrated source command implement-roadmap.

Command Template

Workflow: Implement the Roadmap — OrderBook-rs (unattended)

Drive every open issue in the roadmap to a merged, green state without stopping for confirmation between steps. The single source of truth for what to do next is .internalDoc/ROADMAP.md.

Unattended mode — read this first

• This command runs autonomously. The per-issue STOP / "confirm with the user" points in /implement-issue, /create-pr, and /respond-review are converted into autonomous decision points here — do not pause for approval at them. Plan, implement, test, and proceed on your own judgment, staying strictly within rules/global_rules.md and AGENTS.md.
• You stop only at an Escalation condition (see the dedicated section). When you escalate, leave the work in a safe state (PR open, CI status reported, roadmap untouched for that issue) and surface a concise summary.
• Never weaken a check to make progress: no --no-verify, no disabling a CI job, no #[allow] to silence a real warning, no skipped test, and never remove #![deny(unsafe_code)] to make code compile.
• One issue per PR. One merged PR per loop iteration.

Context

• Repository: joaquinbejar/OrderBook-rs — high-performance, lock-free limit order book. The core matching engine is synchronous (crossbeam-skiplist + dashmap + atomics); tokio is opt-in (only BookManagerTokio and the NATS publishers). Never .await in the matching hot path. #![deny(unsafe_code)] is on lib.rs and must stay. Feature flags are gated (see policy).
• Binding rules: rules/global_rules.md and AGENTS.md. Read both before writing code. Follow the 10-step Agent Workflow in AGENTS.md (model+errors → core engine → snapshot/stats → eventing → sequencer/journal → NATS → manager → public surface → tests/examples/benches → docs).
• Module boundaries (must not be violated):
  • error.rs is a leaf (std + thiserror + upstream errors only).
  • book.rs is the core engine — consumes matching, modifications, operations, stp, fees, cache, pool, iterators, snapshot, statistics, market_impact, trade, book_change_event, order_state. It must not depend on manager, nats*, or sequencer.
  • matching.rs owns the algorithm — depends on pricelevel, trade, stp, fees, pool. No tokio, no I/O.
  • sequencer/ depends on book.rs + serialization; not on nats* or manager. Journal-format changes require an ORDERBOOK_SNAPSHOT_FORMAT_VERSION bump + migration note.
  • nats*.rs and manager.rs depend on the core engine; the core never depends on them. Keep BookManagerStd / BookManagerTokio parity for any new book-level surface.
  • prelude.rs / lib.rs own the public re-exports; nothing inside src/ imports back from prelude.rs.
• Specialized agents (delegate by territory):
  • book-expert — core engine: matching, operations, modifications, mass cancel, STP, fees, repricing, cache, pool, iterators, snapshots, statistics, market-impact, the multi-book manager, the IV solver.
  • eventing-expert — sequencer/, journal, replay, nats.rs, nats_book_change.rs, serialization.rs, trade.rs, book_change_event.rs, order_state.rs.
  • devops — Docker, .github/workflows/, Makefile, crates.io packaging, coverage tooling, Criterion benches, examples.
  • architect — module boundaries, coding standards, public surface, and keeping doc/ + README in sync.
  • Review-only (pull in before opening the PR, by territory): determinism-auditor (after any change to matching.rs, operations.rs, modifications.rs, book.rs, sequencer/, or the serialization / NATS paths — and always before sequencer replay tests), hotpath-reviewer (perf-relevant hot-path changes), microstructure-critic (matching semantics, STP policy, fee asymmetry, README microstructure claims).
• GitHub account (must be active for every gh call): joaquinbejar. Verify with gh auth status before any gh operation. The gh wrapper selects the account by directory — always run gh from the repo root, never via a bare bash -c that bypasses the wrapper.

Preconditions (run once at the start)

gh auth status                       # active account must be joaquinbejar
git switch main && git pull --ff-only
git status --porcelain               # must be clean before starting a new issue

If the tree is dirty or main is behind in a way that won't fast-forward, escalate. Read .internalDoc/ROADMAP.md fully to load the order and the gated/in-progress notes.

Bootstrap (no roadmap yet). .internalDoc/ROADMAP.md does not exist in this repo yet (.internalDoc/ is gitignored). If it is missing, build the work order from live GitHub state instead and create the file so the loop can persist progress:

gh issue list --repo joaquinbejar/OrderBook-rs --state open --limit 100 \
  --json number,title,labels,createdAt

Order by dependency notes in the issue bodies, then by issue number ascending. Write a minimal .internalDoc/ROADMAP.md with a Status ledger (phase tables with [ ] checkboxes + depends on notes), a Remaining list, a Changelog table, and a final recommended execution order line. Keep it local — never stage it.

Outer loop — pick the next issue

Repeat until there is no eligible issue left:

1. Parse .internalDoc/ROADMAP.md. The recommended execution order line at the bottom of the Status ledger is authoritative; within it, respect the depends on notes in the phase tables (never start an issue whose dependency is not yet merged).
2. Cross-check against live state:

   gh issue list --repo joaquinbejar/OrderBook-rs --state open --limit 100
   gh pr list   --repo joaquinbejar/OrderBook-rs --state open

3. Select the first roadmap issue that is: open, not already merged, has all dependencies merged, and is not gated (see Gated issues policy). If the user passed a starting issue number or continue, honor it as the entry point but still respect dependency order.
4. If the only remaining issues are gated → escalate with the list and stop.
5. If no issues remain → finish: report the full changelog and stop.

Log the chosen issue: ▶ Implementing #<n> — <title> (phase <p>).

Per-issue pipeline

Step 1 — Implement and open the PR (/implement-issue + /create-pr)

Run the /implement-issue workflow for the selected issue, autonomously (no STOPs): Understand → Plan (internally; do not enter plan-mode approval) → Branch → Implement → Test → Pre-submission → Push → open PR via /create-pr.

• Branch from fresh main: git switch main && git pull --ff-only && git switch -c issue-<n>-<slug>.
• Follow the 10-step Agent Workflow in AGENTS.md. Delegate the body of the work to the owning agent per the issue's territory (book-expert for the core engine, eventing-expert for sequencer/journal/NATS/serialization, devops for CI/Makefile/benches/examples, architect for boundaries + public surface). Pull in the matching review-only agent before opening the PR: determinism-auditor after matching/sequencer/serialization/NATS changes, hotpath-reviewer for perf-relevant changes, microstructure-critic for matching-semantics or README-claim changes.
• Ship the full vertical slice: /// docs on every new pub item, unit tests co-located, integration tests under tests/unit/, a runnable examples/ demo and a Criterion benches/ case when perf-relevant, round-trip tests for new event shapes, and snapshots_match verification after replay for sequencer changes. Bump the What's New sections in lib.rs + README.md and add a CHANGELOG.md entry.
• Gate before pushing: make pre-push must be clean (zero warnings). It runs fix fmt lint-fix test readme doc and may stage README.md — verify git status after it. For feature-touching work, also build the relevant flags, e.g. cargo build --features special_orders,nats,bincode,journal.
• The PR body must end with Closes #<n> and carry the same labels as the issue.

Capture the PR number: PR=$(gh pr view --json number -q .number).

Step 2 — Request Copilot review and wait for it

Request the GitHub Copilot code review:

# Primary
gh pr edit "$PR" --repo joaquinbejar/OrderBook-rs --add-reviewer Copilot

If that errors (Copilot not addable by name), use the GraphQL fallback — find the Copilot reviewer actor, then request it:

# Find the bot id
gh api graphql -f query='
  query($owner:String!,$name:String!){
    repository(owner:$owner,name:$name){
      id
      suggestedActors(capabilities:[CAN_BE_ASSIGNED], first:50){
        nodes { login __typename ... on Bot { id } ... on User { id } }
      }
    }
  }' -f owner=joaquinbejar -f name=OrderBook-rs
# then requestReviews(pullRequestId, userIds:[<copilot id>], union:true)

If Copilot still cannot be requested programmatically → escalate (ask the user to add the Copilot reviewer in the UI, then resume with continue).

Wait for the review to land. Copilot posts a review (state COMMENTED / CHANGES_REQUESTED / APPROVED) and/or inline comments when finished. Poll without a foreground sleep (use a background watcher or gh pr checks --watch for CI in parallel):

# Poll until a Copilot review exists
gh api repos/joaquinbejar/OrderBook-rs/pulls/$PR/reviews \
  --jq '.[] | select(.user.login|test("[Cc]opilot")) | {state,id}'

Treat the review as finished once a Copilot review object appears (or Copilot posts inline comments and no longer shows "is reviewing"). If nothing arrives after a long wait, retry the request once, then escalate.

Step 3 — Respond to the review (/respond-review) and fix

Run the /respond-review workflow for $PR, autonomously:

• Classify every Copilot comment (code change / question / suggestion / disagree / deferred refactor).
• For valid points: fix in the same PR, respecting rules/global_rules.md and the module boundaries. Run make pre-push, commit (address review: …), push before replying.
• For points that conflict with the rules or are wrong: reply with a one-sentence reason citing the rule/reference; do not change code.
• For out-of-scope suggestions: open a follow-up issue via /create-issue (add > Created from PR #$PR review comment.), reply with the link, and — if it's a genuinely new improvement — append it to the roadmap Remaining list.
• Reply to every comment and resolve each conversation.
• If a Copilot comment requires a design decision, a new dependency, a new feature flag, or a breaking change → escalate instead of guessing.

Re-trigger Copilot only if you made substantive changes and want a second pass (optional); otherwise proceed.