Skip to content
SYNNET DevHub

CLAUDE.md refresh + migrator module doc

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/superpowers/specs/2026-04-28-claude-md-refresh-design.md. Edit at the source, not here.

CLAUDE.md refresh + migrator module doc

Section titled “CLAUDE.md refresh + migrator module doc”

Date: 2026-04-28
Status: approved (auto-mode session)

Problem

Section titled “Problem”

CLAUDE.md is at version 0.8.x in a repo currently shipping 0.12.1. 850 lines, 100 commits of drift since the last edit (2026-04-24). Three concerns are tangled in one file:

  1. Canonical onboarding (atemporal: product overview, conventions, host roles, working style).
  2. Per-release archeology (already canonically tracked in CHANGELOG.md).
  3. Per-module deep-dives (already in docs/modules/<name>/ for the v0.10+ modules).

The user’s workflow target: lee CLAUDE.md y docs/modules/<X>/README.md → arranca con contexto correcto. That fails today because (1) is contaminated by stale (2), and (3) is missing for several modules — including migrator, the next target.

Solution

Section titled “Solution”

Two surgical commits, no new top-level files.

Commit 1 — docs(claude-md): refresh canonical guide

Section titled “Commit 1 — docs(claude-md): refresh canonical guide”

Strip §3 (current state archeology), §8 (master prompts), §9 (deferred work lists). Those are patch-notes territory and live in CHANGELOG.md already.

Result: ~400 lines (vs 850), structured as:

  • §1 Product overview (refresh)
  • §2 Repository layout (20 active crates today; drop never-built storage-zfs / ovs)
  • §3 Current state — 4 paragraphs only: shipping = 0.12.1, master = X, ISO at sha Y, full history → CHANGELOG.md
  • §4 Engineering conventions (canonical, intact)
  • §5 Architecture highlights — only modules alive today
  • §6 Host roles (canonical)
  • §7 Infrastructure (refresh tooling references)
  • §8 Working style rules (canonical)
  • §9 File paths cheat sheet (refresh)
  • §10 End-of-doc + “Last updated” + index of docs/modules/ (which exist, which are gaps)

Commit 2 — docs(modules): migrator module documentation

Section titled “Commit 2 — docs(modules): migrator module documentation”

New docs/modules/migrator/ tree mirroring the iso-detection / vm-profiles pattern:

  • README.md — overview, scope, module tree, public API, REST surface.
  • ARCHITECTURE.md — JobManager + SourceRegistry + UploadStore + Orchestrator + StateStore relationships, ASCII data-flow diagram for both live-pull and offline-import paths.
  • ADAPTERS.md — six source adapters (vim_api, wmi_api, pve_api, prism_api, xen_api, libvirt_remote) with the technical surface each speaks.
  • IMPORTERS.md — ten offline-import formats (ova, ovf-folder, vmx-folder, vhdx, qcow2, vmdk, vmcx-export, vbox-folder, xva).
  • ROADMAP.md — open items (sub-minute cutover, agent-injected for Linux, …).

CLAUDE.md naming convention preserved: technical descriptions only, no third-party product names (per existing CLAUDE.md §1).

Validation

Section titled “Validation”
  • wc -l CLAUDE.md ≤ 450 after refresh.
  • Every removed CLAUDE.md fact still findable in CHANGELOG.md or per-module docs.
  • docs/modules/migrator/README.md references real symbols from crates/migrator/src/lib.rs.

Rejected alternatives

Section titled “Rejected alternatives”
  • New docs/CLAUDE-history.md — duplicates CHANGELOG.md (which already carries 0.3.0 → 0.12.1 entries).
  • Full rewrite from scratch — drops institutional memory of canonical conventions / host-role design / English-only policy that’s still right.
  • Keep §3/§8/§9 in CLAUDE.md — recreates the drift problem within the next 4 minor bumps.

Out of scope

Section titled “Out of scope”

Filling the other module-doc gaps (daemon submodules outside vm_profiles / iso_detection / libvirt_renderer, synvirt-libvirt, console, boot-splash, web-ux legacy, console-gateway, synvirt-guest-*, synvirt-core, synvirt-cli, synvirt-node-agent, console-ticket). The CLAUDE.md §10 index lists the gaps so a future session knows what to fill on demand.