logos-core-module-builder

name	logos-core-module-builder
description	Use when the user wants to create, extend, or debug a Logos core module and needs concrete guidance for metadata.json, flake.nix, CMakeLists.txt, mkLogosModule, code generation, external-library wrapping, inter-module calls, and logoscore-friendly validation.

Logos Core Module Builder

Use this skill after the builder has already chosen a core module shape and needs exact implementation guidance.

Quick start

• Read references/core-module-skeleton.md for the standard file set.
• Read references/build-and-validation.md before suggesting nix, logoscore, or lm commands.
• Read references/external-library-wrapping.md when the module wraps a C, C++, or Go-backed library.
• Read references/inter-module-communication.md when the module must call other Logos modules.

When the target project has its own CLAUDE.md, prefer it for build commands and CLI usage. The logos-workspace/CLAUDE.md has the most comprehensive module development reference.

Workflow

1. Confirm the work is a core module and not ui or ui_qml.
2. Start from the standard layout:
   • metadata.json
   • flake.nix
   • CMakeLists.txt
   • src/*
   • optional generated_code/*
   • optional tests/*
3. Keep the default builder path concrete:
   • mkLogosModule
   • codegen in preConfigure when universal/provider flows are actually in play
   • explicit main, dependencies, and build outputs
   • lm and logoscore validation after build
4. Surface compatibility boundaries before runtime testing:
   • PluginInterface versus LogosProviderBase (these are NOT interchangeable -- see runtime warnings below)
   • local runtime versus public release behavior
   • tutorial path versus runtime-specific workaround path
5. Route packaging, installation, and Basecamp/runtime debug loops to logos-module-build-loop.

Runtime warnings (from validated testing)

These findings come from ground-truth runtime testing of the Logos tooling:

• Interface mismatch is real. Some codegen/tooling targets LogosProviderBase while local runtimes use PluginInterface. A module that builds successfully may crash at runtime due to this mismatch.
• Public Basecamp releases may not discover user-installed modules. Tested GitHub releases #80-#111 did not load file-dropped or lgpm-installed modules.
• The code generator works correctly. logos-cpp-generator parses C++ headers, produces valid Qt glue, and integrates into the Nix build via preConfigure.
• The Nix builder (mkLogosModule) is solid. Resolves Qt 6, SDK, and module headers correctly. LGX packaging is integrated.
• Variant naming bug. The builder produces linux-amd64-dev but some runtimes expect linux-amd64.

Always confirm the target runtime's expected interface before treating a build success as proof of runtime compatibility.

Reference map

• references/core-module-skeleton.md -> standard file and metadata layout
• references/build-and-validation.md -> build, inspect, and logoscore validation flow
• references/external-library-wrapping.md -> external library and wrapper-specific guidance
• references/inter-module-communication.md -> C++ call patterns and dependency declarations

Quality rules

• Prefer the target project's own CLAUDE.md and current runtime behavior over bundled snapshots.
• Keep core module guidance separate from ui and ui_qml guidance.
• Mention mkLogosModule, metadata.json, flake.nix, CMakeLists.txt, and code generation explicitly when they matter.
• Treat external-library wrapping as a first-class path.
• Warn about PluginInterface versus LogosProviderBase compatibility before telling the user to rely on runtime validation.
• Do not treat a successful build as proof of runtime compatibility.