logos-dev-boost/docs/project.md

Project Description

Project Structure

logos-dev-boost/
├── docs/                             # Documentation (this directory)
│   ├── index.md                      # Entry point
│   ├── spec.md                       # Domain spec: purpose, journeys, features
│   └── project.md                    # Implementation details (this file)
├── guidelines/                       # Always-loaded AI conventions
│   ├── core.md                       # Two component types, naming, file structure
│   ├── universal-module.md           # Pure C++ impl pattern, type mapping, codegen
│   ├── ui-app.md                     # ui_qml apps: pure QML + QML with C++ backend
│   ├── nix-build.md                  # Flake structure, build commands, overrides
│   ├── testing.md                    # logoscore, unit tests, TEST_GROUPS
│   ├── metadata-json.md              # Full metadata.json schema
│   └── codegen.md                    # logos-cpp-generator pipeline, LIDL, types
├── skills/                           # On-demand task knowledge (agentskills.io)
│   ├── create-universal-module/      # Scaffold + implement a universal C++ module
│   ├── wrap-external-lib/            # Wrap a C/C++ library as a module
│   ├── create-ui-app/                # QML UI app for Basecamp (pure QML or QML + backend)
│   ├── package-lgx/                  # Create + distribute LGX packages
│   ├── inter-module-comm/            # LogosAPI patterns, dependency declaration
│   ├── testing-modules/              # logoscore + unit testing patterns
│   ├── nix-flake-setup/              # Flake config, overrides, workspace integration
│   └── add-to-workspace/             # Register module in logos-workspace
├── templates/                        # Scaffolding templates (used by init command)
│   ├── universal-module/             # Pure C++ module
│   ├── universal-module-extlib/      # With external library wrapping
│   └── ui-app/                       # QML UI app (pure QML + QML with backend)
├── generators/                       # Context file generators (TypeScript)
│   ├── generate-agents-md.ts         # AGENTS.md with compressed docs index
│   ├── generate-claude-md.ts         # CLAUDE.md (imports AGENTS.md content)
│   ├── generate-cursor-rules.ts      # .cursor/rules/logos.mdc
│   └── generate-llms-txt.ts          # llms.txt from docs/
├── mcp-server/                       # MCP server (TypeScript, stdio transport)
│   ├── index.ts                      # Server entry point
│   └── tools/                        # MCP tool implementations
│       ├── project-info.ts           # SDK version, module type, build targets
│       ├── search-docs.ts            # Full-text search over docs/ (fuse.js)
│       ├── api-reference.ts          # Type system, LogosAPI, LogosResult
│       ├── build-help.ts             # Context-aware build commands
│       └── scaffold.ts               # Wraps init templates
├── installer/                        # One-command setup
│   ├── cli.ts                        # CLI entry point (init, install, generate)
│   └── install.ts                    # IDE detection, file generation
├── tests/                            # Tests
├── flake.nix                         # Nix package definition
├── package.json                      # Node.js package
├── tsconfig.json                     # TypeScript configuration
└── README.md

Stack, Frameworks & Dependencies

Component	Technology	Purpose
MCP server	TypeScript, @modelcontextprotocol/sdk	AI agent tool integration via stdio
Documentation search	fuse.js	Full-text search over bundled docs
Context generators	TypeScript, Node.js	Generate AGENTS.md, CLAUDE.md, .cursor/rules
Scaffolding	Nix flake templates, logos-module-builder	Project initialization
Build/packaging	Nix flakes	Self-contained offline-capable distribution

External Logos Dependencies

Dependency	Role	Source
logos-module-builder	Nix flake templates for module scaffolding	github:logos-co/logos-module-builder
logos-cpp-sdk	SDK headers, code generator (logos-cpp-generator)	github:logos-co/logos-cpp-sdk
logos-liblogos	Runtime library documentation reference	github:logos-co/logos-liblogos

Components

Guidelines

Guidelines are Markdown files loaded into the always-on context (AGENTS.md / CLAUDE.md). Each is kept under 2000 tokens to minimize context cost while providing essential conventions.

Guideline	Content
core.md	Two component types (Universal Module vs UI App), naming conventions, file structure, metadata.json as source of truth
universal-module.md	Pure C++ impl pattern, type mapping table, "interface": "universal", impl class naming (<name>_impl.h), public methods = module API
ui-app.md	ui_qml apps: pure QML (logos.callModule bridge) and QML + C++ backend (Qt Remote Objects, .rep file, SimpleSource + ViewPluginBase, logos.module() replica)
nix-build.md	Flake structure, follows declarations, preConfigure for codegen, build commands, --auto-local
testing.md	Unit tests (call impl class directly), logoscore integration tests, TEST_GROUPS, nix flake check
metadata-json.md	Full schema including "interface", "dependencies", "nix" config, "external_libraries", "cmake" settings
codegen.md	header-first cdylib pipeline, C++ to LIDL type mapping, generated file structure, LIDL format

Skills

Skills are on-demand knowledge modules following the agentskills.io specification. Each lives in its own directory with a SKILL.md file containing YAML frontmatter (name, description) and Markdown instructions.

Skill	Trigger	Content
create-universal-module	Creating a new Logos module	Full scaffold: metadata.json, flake.nix with preConfigure, CMakeLists.txt, impl header template
wrap-external-lib	Wrapping a C/C++ library	External library config, extern "C" patterns, based on logos-accounts-module
create-ui-app	Creating a Basecamp UI app	Two paths: pure QML (Main.qml + logos.callModule) or QML + C++ backend (.rep, SimpleSource, ViewPluginBase, logos.module replica)
package-lgx	Packaging for distribution	lgx create/add/verify workflow, portable builds, nix-bundle-lgx
inter-module-comm	Module-to-module calls	LogosAPI::callModule(), dependency declaration, LogosResult handling
testing-modules	Writing tests	Unit tests, logoscore integration, TEST_GROUPS, mock transport
nix-flake-setup	Nix configuration	Flake template, inputs, follows, preConfigure, override-input
add-to-workspace	Registering in logos-workspace	flake.nix inputs, scripts/ws REPOS, dep-graph.nix

Generators

TypeScript scripts that produce IDE-specific context files from the guidelines and documentation:

Generator	Output	Description
generate-agents-md.ts	AGENTS.md	Universal context file. Compressed docs index (~8-15KB), conventions, type system. Works with all AI tools.
generate-claude-md.ts	CLAUDE.md	Claude Code-specific context. Imports AGENTS.md content plus Claude-specific skill references.
generate-cursor-rules.ts	.cursor/rules/logos.mdc	Cursor-specific rules with file glob patterns for activation.
generate-llms-txt.ts	llms.txt, llms-full.txt	Machine-readable documentation index following the llms.txt specification.

Generators detect the project type from metadata.json ("interface": "universal" vs "type": "ui_qml") and include context specific to that project type.

MCP Server

TypeScript MCP server using @modelcontextprotocol/sdk with stdio transport. Provides live project introspection tools.

Tool	Input	Output
logos_project_info	(none — reads current directory)	Project type, interface type, SDK version, dependencies, build targets
logos_search_docs	{ "query": "..." }	Ranked search results from bundled documentation
logos_api_reference	{ "interface": "LogosAPI" }	Type mapping table, method signatures, usage examples
logos_build_help	{ "action": "build" }	Context-aware build commands, codegen pipeline explanation, troubleshooting
logos_scaffold	{ "name": "...", "type": "module" }	Creates project from template, returns file list and next steps

Installer

The installer (install.ts) performs interactive setup:

1. Detects project type from flake.nix inputs and metadata.json
2. Detects installed AI tools (checks for .claude/, .cursor/, presence of claude/codex/gemini in PATH)
3. Generates appropriate context files per detected tool
4. Builds MCP server locally (via Nix) to .logos-dev-boost/
5. Writes .mcp.json pointing to the built MCP server binary
6. Installs skills to tool-specific directories

CLI Reference

logos-dev-boost init

Scaffold a new Logos project.

nix run github:logos-co/logos-dev-boost -- init <name> --type <module|ui-qml|ui-qml-backend> [--external-lib]

Argument	Description
<name>	Project name (snake_case, e.g., crypto_utils)
--type module	Universal C++ module (default)
--type ui-qml	Pure QML UI app for Basecamp (no C++)
--type ui-qml-backend	QML + process-isolated C++ backend UI app
--external-lib	Add external library wrapping scaffold (modules only)

Creates the directory, generates the appropriate template (mkLogosModule for modules, mkLogosQmlModule for UI apps), adds AI context files, and initializes git.

logos-dev-boost install

Configure AI tools for an existing Logos project.

nix run github:logos-co/logos-dev-boost -- install

Interactive prompt asks which AI tools to configure. Generates context files and MCP server registration.

logos-dev-boost generate

Regenerate context files (useful after updating dependencies or documentation).

nix run github:logos-co/logos-dev-boost -- generate [--agents-md] [--claude-md] [--cursor-rules] [--llms-txt]

Without flags, regenerates all context files. With flags, regenerates only the specified files.

Operational

Building logos-dev-boost

# Install dependencies
npm install

# Build TypeScript
npm run build

# Or via Nix (produces self-contained package)
nix build

Testing

# Run tests
npm test

# Via Nix
nix flake check

Nix Package Outputs

packages.default       # Full logos-dev-boost (docs + guidelines + skills + generators + MCP server)
packages.docs          # Documentation bundle only
apps.default           # CLI entry point (init, install, generate)
apps.mcp-server        # MCP server only

Extension Points

Custom Guidelines

Add .md files to your project's .ai/guidelines/ directory. These are merged with logos-dev-boost guidelines when generating AGENTS.md / CLAUDE.md.

Custom Skills

Add SKILL.md files to your project's .ai/skills/<skill-name>/ directory. These are installed alongside logos-dev-boost skills.

Third-Party Module Skills

Module authors can ship skills in their repos at resources/boost/skills/<skill-name>/SKILL.md. When a project depends on that module and runs logos-dev-boost install, these skills are automatically discovered and installed.

Relationship to logos-module-builder

logos-dev-boost wraps logos-module-builder for scaffolding — it does not duplicate its templates. The init command calls nix flake init -t logos-module-builder (appropriate variant) and then layers on:

• Universal module impl header template (for --type module)
• Pure QML template (for --type ui-qml) or QML + C++ backend template (for --type ui-qml-backend)
• AI context files (AGENTS.md, CLAUDE.md, .mcp.json)
• Test skeleton

This means logos-dev-boost always uses the latest logos-module-builder templates for Nix/CMake scaffolding.

Consumers

• AI coding agents (Claude Code, Cursor, Copilot, Codex, Gemini) via AGENTS.md, CLAUDE.md, skills, and MCP
• Human developers via documentation, scaffolding, and generated project structure
• CI/CD pipelines via logos-dev-boost check (Phase 4)