Spike: Support an out-of-the-box migration workflow with rgctl

Context

@sraghunathan experimented with migIQ and
its discovery engine, rgctl, and found the
results promising. This issue originally scoped a full migIQ-vs-ours
comparison; it's narrowed here to the piece actually worth adopting:
whether rgctl can power plan-stage discovery in our opinionated migration
workflow, out of the box.

migIQ's orchestration layer — workspace setup, resume prompts, stop-and-report
failure handling, spawning a background agent for long work — overlaps the
controller, AgentWorkflow, and the harness. Those are ADR'd and shipped. That
layer stays out of scope and this spike should not reopen it.

rgctl itself is a standalone code knowledge graph CLI: tree-sitter based,
14+ languages, built to answer agent queries (callers/callees, blast-radius,
CFG/taint slices, communities, semantic search) from a graph it builds once
via discover and caches to .rgctl/ in the repo.

Packaging question — resolved

The original spike gated everything on one question: can rgctl ship without
a daemon, given skills reach the agent as read-only OCI image volumes at
/opt/skills (ADR 0014, ADR 0015) and it all has to work disconnected (#155)?

Confirmed from the rgctl repo: yes. It's a standalone CLI (prebuilt
binaries per OS/arch, or cargo build --release --bin rgctl), no background
daemon for core usage. The optional serve command is an on-demand HTTP
dashboard, not a persistent process. discover output is a cached artifact
in .rgctl/, not a live index. That clears the blocker — rgctl is
packageable into a stage image the same way other skill tooling is.

What's still open is binary size/arch matrix and whether --no-default-features
(needed if ONNX linking fails) costs us the semantic search command.

What it would take to ship this out of the box

Shipping "a seeded migration workflow with rgctl" is more than swapping a
discovery backend — it means the controller ecosystem ships a default
AgentWorkflow + SkillCollection a user can run without authoring their
own CRs. Concretely:

1. rgctl skill packaging. Build an OCI image per ADR 0014/0015 bundling
   the rgctl binary plus a SkillCard wrapping discover/find/callers/
   blast-radius/etc as agent-callable tools. Needs a multi-arch build (the
   stage image runs wherever the Agent Sandbox pod runs) and a disconnected
   mirroring plan (#155).
2. A discovery skill, not just a binary. Content — when/how the agent
   calls rgctl, how it interprets the JSON output — has to be authored into
   catalog/skills/plan/, the same slot Graphify discovery would occupy
   (#159). Whichever wins the measurement gate, or both as swappable
   SkillCollection entries.
3. A seeded SkillCollection + AgentWorkflow. The actual "out of the
   box" part: a pre-built AgentWorkflow chaining prompt-builder/
   questionnaire → plan (rgctl discovery) → execute → verify → report,
   shipped as a default catalog manifest rather than something a user
   writes by hand. Stays consistent with design principle #1 (controller is
   domain-agnostic) — migration-specific wiring lives in catalog content and
   parameter values, not controller code.
4. Parameter/questionnaire surface. The controller treats parameters as
   opaque, so the seeded workflow needs its parameter schema (repo URL,
   target stack, etc.) exposed somewhere fillable — this makes "promote the
   questionnaire out of harness/experiments/" a hard dependency rather
   than a nice-to-have.
5. Cache lifecycle across stages. rgctl's .rgctl/ index is a cached
   artifact tied to a checkout. The harness owns git/workspace lifecycle
   across stages and resumes — need to decide whether .rgctl/ is
   regenerated per AgentRun, persisted across the workflow's stages, or
   rebuilt at each stage boundary, since that drives how expensive
   discover is to repeat.
6. Report stage dependency. An end-to-end seeded workflow mirroring
   migIQ's full phase set needs catalog/skills/report/ (#60), which
   doesn't exist yet. Until then the seeded workflow stops at
   plan → execute → verify.
7. CI/eval coverage. The rgctl skill image needs the same build/test
   treatment as other skill images, plus eval harness coverage so the
   measurement gate stays re-checkable as either side changes.
8. Docs. docs/getting-started.md has no out-of-the-box workflow entry
   point today — this would need a "try the seeded migration workflow"
   path once one exists.

Phase-by-phase mapping against catalog/skills/

The rows below the first are migIQ-orchestration-shaped, not rgctl-shaped —
kept here for traceability but not this spike's focus.

Open questions

• rgctl vs Graphify (#159) — the central question. Both graph-index the
  repo and answer architecture/dependency/impact queries; rgctl adds
  PageRank/communities, CFG, taint, and vuln/deps checks. Compare output
  quality and token cost of query-first discovery against what Graphify
  gives us today.
• CI/PR integration. rgctl ships check / pr-check / diff commands
  aimed at CI gating — is there a workflow-stage fit beyond plan-stage
  discovery (e.g. a verify-stage consistency check)?
• Report and prompt-builder. Still open from the original spike, but now
  secondary to the rgctl discovery question — see #60 and the
  questionnaire note above.

Measurement gate

"rgctl beats Graphify for plan-stage discovery" is a did this make results
better, and at what token cost question — exactly what @shawn-hurley's
evaluation work is being built to answer. This spike should produce a
recommendation on discovery with its reasoning and token observations; the
adoption decision waits for the evaluation harness.

Timeboxed tasks

• Answer the rgctl packaging question — resolved above: standalone CLI,
  no daemon, packageable as stage-image tooling.
• Verify rgctl's binary size/arch matrix against the stage-image
  constraints and disconnected mirroring (#155).
• Run rgctl and Graphify discovery over the same application; capture
  output quality and token cost.
• Note where rgctl's CI-facing commands (check, pr-check, diff)
  might fit a workflow stage, without committing to one.
• Scope the seeded AgentWorkflow/SkillCollection shape needed to ship
  rgctl discovery out of the box (see "What it would take" section).

Deliverables

• A findings write-up with a recommendation on rgctl for plan-stage
  discovery: adopt, adapt, or decline.
• A proposed shape for the seeded AgentWorkflow/SkillCollection (design
  only, not implementation) if rgctl is recommended.
• A follow-up issue for rgctl packaging/integration if adopted.
• A comment recording the outcome on #159.

Out of scope

• Adopting migIQ's orchestration layer.
• Implementing any of it.
• Deciding the discovery backend — see the measurement gate.
• Report stage (#60) and prompt-builder — tracked separately, not blocked
  on this spike.
• Building or shipping the seeded workflow itself — this spike scopes what
  it would take, it does not implement it.

Related

• #159 — Use Graphify queries for plan-stage discovery (the competing slot)
• #60 — Report stage skill
• #260 — Path to convergence with Lightspeed Agentic Operator
• #261 — Application execution, browser verification, and visual evidence
• #155 — Disconnected mirroring for skill images