---

name: architect description: Project overview and architecture guide for bombyx -- crate layout, responsibilities, quality gates, and how to add a feature.

bombyx Architecture

Project Identity

| Field | Value | |-------|-------| | Language | Rust (edition 2024, stable toolchain) | | Shape | CLI only -- no services, no frontend | | License | MIT | | Version | crates/bombyx/Cargo.toml (single source) | | Versioning | SemVer 2.0.0 | | Platforms | Windows (workstation), Linux | | Template | derived from breki/rustbase |

What bombyx Does

Drives isolated AI-agent VMs on a libvirt host, usually a second machine reached over SSH. The control plane is deliberately thin: bombyx generates a Vagrantfile and a bootstrap script, writes them onto the VM host and runs vagrant there, streaming output back. When host names the machine bombyx is running on, the same script goes through sh -c instead.

The key architectural constraint: neither the workstation nor the VM host reads the project's files. Both generated files come out of the operator's own config.toml and are rewritten on every boot, so the host cannot drift, and the guest clones the project itself once it is running. See docs/trust-boundary.md.

Repository Layout

bombyx/
  .cargo/
    config.toml         # cargo xtask alias
  .claude/
    hooks/              # Claude Code hook scripts
    commands/           # slash commands
    skills/             # domain knowledge skills
    settings.json       # hook configuration
  crates/
    bombyx/
      src/
        lib.rs          # crate root, re-exports
        plan.rs         # which commands run, in what order
        config.rs       # config.toml parsing (submodules)
        remote.rs       # command building, either route
        vagrantfile.rs  # renders the two generated files
        doctor.rs       # preflight checks (submodules)
        update.rs       # self-update (submodules)
        name.rs term.rs tool.rs
        bin/bombyx/
          main.rs       # CLI entry point (thin)
      tests/
        integration_test.rs
  xtask/
    src/
      main.rs           # build automation
  scripts/              # bash wrappers
  docs/
    developer/
      DIARY.md          # development diary
      redteam-log.md    # security review findings
      artisan-log.md    # quality review findings

Module Responsibilities

config -- project configuration

Parses the operator's config.toml: a file-wide host, and one [projects.<name>] table per project carrying remote_root, an optional host, [vm] and [source]. Config::load_project(name, registry) is the one loader, and config::host::rank picks between the two host keys, the project's own winning. Every host in the file is checked as the file is read, so holding a Registry proves they all passed. Typed errors via thiserror. Computes remote paths (remote_project_dir, remote_scratch_dir).

remote -- command construction

Pure functions returning a RemoteCommand { program, args, dir }. Nothing here spawns a process. That separation is what makes quoting, path joining and command composition unit-testable with no VM host in the loop.

Includes shell_quote for POSIX single-quote escaping -- every value interpolated into a remote script goes through it.

bin/bombyx/main.rs -- entry point

Clap parsing, then plan() maps a subcommand to a sequence of Commands, which are either printed (--dry-run) or executed. Kept thin because coverage excludes src/bin/.

xtask -- build automation

Not published. validate, test, clippy, fmt, coverage, dupes, audit, dep-age*.

Quality Gates

| Gate | Threshold | |------|-----------| | Clippy | Zero warnings (-D warnings) | | Formatting | cargo fmt --check | | Coverage | 90% overall, 85% per module | | Duplication | <= 6% (production code) | | Unsafe code | Forbidden (#[forbid(unsafe_code)]) | | Advisories | RUSTSEC clean |

cargo xtask validate runs every gate; the six above are the ones worth memorising, and CLAUDE.md under Definition of Done lists them all in execution order.

The Claude Code Stop hook runs a subset: fmt-check, clippy, doc and test. It skips coverage and duplication deliberately, because both are slow -- see .claude/hooks/stop-check.sh. A coverage regression is caught by validate, not by the hook.

Adding a New Subcommand

1. Write tests first (TDD).
2. Add the command-building function in remote.rs with unit tests asserting the exact argv. There are two argv shapes, one per route, so assert both -- see Config::for_tests_local.
3. Add the VmCmd variant and its action_of arm in main.rs -- the CLI surface, and nothing else.
4. Add the Action variant and its plan() arm in plan.rs, with the unit test asserting the ordered commands. This is where the logic goes: main.rs is excluded from coverage.
5. Add an integration test driving the real binary with --dry-run.
6. Run cargo xtask validate.
7. Commit with /commit.

Keep logic out of main.rs: it is excluded from coverage, so anything non-trivial there ships untested.