sc-compose
Compose once. Render deterministically. Ship everywhere.
A standalone CLI and composable library for teams whose templates have outgrown copy-paste. Compose agent profiles, config files, test fixtures, and reports from shared fragments — with declared inputs that fail loudly when missing.
Why sc-compose?
🔗 Compose from Shared Fragments
Place your house style, review checklist, and error conventions in one
includable file. Reference it from every template with @<_includes/house-style.md>.
Edit once — every downstream template picks up the change.
✅ Declared Inputs, Loud Failures
Declare required variables in YAML frontmatter. Missing a
task_id? sc-compose fails with an actionable diagnostic
that names the variable, the file that declared it, and the include
chain. No silent guessing.
🔀 One Profile, Four Runtimes
Author an agent profile once under .agents/agents/. It
resolves correctly for Claude Code, Codex, Gemini, and OpenCode through
each runtime's native search chain. Override only the runtimes that
genuinely need specialization.
🔄 Multi-Pass Nested Templates
Define deploy-time, install-time, and invocation-time variables in one file. Stacked YAML headers with progressive brace counts. Render all passes in one command. Verify deployed output hasn't drifted from the template source.
🐍 Python Bindings
pip install sc-compose. Native extension module built with
PyO3 and maturin. Pre-built wheels for macOS, Linux, and Windows
(Python 3.11+). Full multi-pass rendering from Python.
📊 Built-in Reporting
Produce compliance evidence from declarative semantic specs. Scaffold a report catalog, render HTML reports, materialize metadata, and generate CI handoff manifests — all from the CLI.
Quickstart
# Render your first template
echo 'Hello {{ name }}!' > hello.txt.j2
sc-compose render --file hello.txt.j2 --var name=World
# → Hello World!
# Compose a profile for Claude Code
sc-compose render --mode profile --kind agent \
--agent rust-developer --runtime claude
# Generate pytest stubs from a bundled example
sc-compose examples pytest-fixture \
--var-file tests.json --output tests/test_auth.py
Install Everywhere
| Platform | Method | Command |
|---|---|---|
| macOS | Homebrew | brew install randlee/tap/sc-compose |
| Windows | Winget | winget install randlee.sc-compose |
| Any (Rust) | crates.io | cargo install sc-compose |
| Any (Python) | PyPI | pip install sc-compose |
| Any (source) | cargo | cargo build --release -p sc-compose |
| Rust lib | Cargo.toml | sc-composer = "1.4.1" |
Bundled examples are guaranteed in Homebrew, Winget, and GitHub Release
installs. cargo install ships the binary only — set
SC_COMPOSE_DATA_DIR for examples.
What People Use It For
AI Agent Profiles
Author once, resolve across Claude, Codex, Gemini, and OpenCode.
Task Templates
Generate structured XML/JSON task assignments with declared inputs.
pytest Fixtures
Generate test stubs from a list of test names with bundled examples.
Service Configs
Compose YAML configs from shared fragments with env-var inputs.
Sprint Reports
Generate HTML compliance reports from declarative semantic specs.
.NET Benchmarks
Compose benchmark harnesses from shared setup and teardown fragments.
Documentation
- Requirements — normative behavior, JSON schemas, exit codes
- Architecture — library module layout and crate boundaries
- Error Codes — stable
ERR_*diagnostic codes - Releasing — step-by-step release checklist
- Publishing — distribution channels and secrets
- Examples — bundled starter templates
Status
| Version | 1.4.1 |
| MSRV | Rust 1.94.1 |
| Edition | 2024 |
| Platforms | macOS, Linux, Windows |
| Stability | stable 1.x release line |