Skip to content
Back to skills

Subtrees

ASecurity

Subtree configs — one typed config several commands of a binary load (every command at or below a path), without every process loading it; registration, the loader's path check, the collision rules and the KCL projection.

  • 10 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 13, 2026
ai-agentsgoapidatabase

Works with

  • cli
  • api

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill subtrees --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Subtrees?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Subtrees
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-subtrees/badge)](https://www.skillsdirectory.com/skills/reliant-labs-subtrees)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: subtrees
description: Subtree configs — one typed config several commands of a binary load (every command at or below a path), without every process loading it; registration, the loader's path check, the collision rules and the KCL projection.
---

# Subtree configs

A setting many commands read but the server roles must not carry — the CLI's server URL and token, a guard policy `daemon start` and `open` both run — is a SUBTREE config: loaded by every command at or below each path, and by no other process.

```protobuf
message CLIConfig {
  option (forge.v1.binary_config) = {
    binary: "app"
    subtrees: [{path: ["auth"]}, {path: ["daemon"]}, {path: ["open"]}]
  };
  string server_url = 1 [(forge.v1.config) = {env_var: "APP_SERVER_URL", flag: "server"}];
  string token = 2 [(forge.v1.config) = {env_var: "APP_TOKEN", sensitive: true}];
}
```

```go
config.RegisterCLIConfigFlags(authCmd)     // persistent on EACH subtree's command
config.RegisterCLIConfigFlags(daemonCmd)
config.RegisterCLIConfigFlags(openCmd)
// in any RunE at or below them:
cli, err := config.LoadCLIConfig(cmd)      // refuses a command under none of them
```

- `subtrees` and `command` are exclusive; no path may lie below another of the same message.
- Any two configs one process can load together — root and anything, a subtree config and a command or subtree config at or below it — may not declare the same env var, flag or top-level field; `generate` refuses the pair, naming a process that loads both. Siblings no process loads together may compose the same block: one definition, two values.
- KCL: `<bin>ProcessEnvMap` adds every subtree config whose path prefixes the workload's argv path, so `app server api`'s Deployment carries none of `CLIConfig`. Add the instance to `<bin>_process` in each env's config.k.
- Composition graph: each subtree and command config of the primary binary is a graph input (`g.<Message>`). A root's process loads the ones over its command path, and its reach is the fields its closure reads of them (`architecture`, "Roots and commands"). `roots_gen.go` registers a subtree config's flags on its path's command.

## Roots: each command's settings, and its migrations

Each root's command loads its own configs beside the root config, and
`rootSpec.Configs` (a generated `rootConfigs`, `nil` per config its command
does not load) hands them to `runRoot` before the policy runs. The scaffolded
`serverkitConfig(cfg, root.Configs)` reads the listen port, drain budget,
logging, TLS and database settings from whichever loaded config declares
them — a command config over a subtree config over the root config — so a
role whose port and drain live in its own command config listens and drains
on them. A setting under another name (a `health_port`, a `drain` block) is
yours to read in the same function: serve.go is owned.

What `runRoot` reads is every root's reach, the way what compose.go reads is
one root's: `generate` reads serve.go itself — `cfg` from `config.LoadReach`,
`root.Configs.<Msg>`, and each value it hands a function of the command
tree — so an `observability` block or a `PROMETHEUS_ENABLED` of your own is
in `ROOTS`, `Roots()` and `LoadReach` with nothing declared. A database field
counts only for a root that opens the database. A config handed whole to
another package is the whole of it: pass the fields instead.

A group command (`server` above `server api`) takes its help from a comment
of its own in `internal/app`, by the root doc's rule — first paragraph the
Short, the rest the Long — ending `//forge:group server` (a path:
`//forge:group server,jobs`). Undeclared, it is "The server roots".

`//forge:root worker command=server,worker migrate=wait` leaves the schema to
another process: `apply` migrates before building the root (the default for a
root that reaches the database), `wait` blocks until the schema is current
(`/readyz` names `schema`; `migratekit.AwaitSchema`), and `none` leaves it
alone. `runRoot` reads `root.Migrate` / `root.AwaitMigrations`.

## Each root's env schema, importable

The generated `roots_gen.go` in a graph project's `pkg/config` is `ROOTS` as Go: `config.Roots()`, `config.RootNamed(name)` and `config.ValidateRootEnv(name, env)`. Each `forgeconfig.Root` carries its args, every env var it reaches (config, path, type, required, sensitive), its env families and the configs its process loads. `Root.Validate(env)` runs the boot load over a rendered env (no flags, every problem rather than the first) and adds a `*forgeconfig.UnreachedVarError` for each var the root never reads. The repo that keeps a deployment's values imports this package at its pinned version and checks each workload's env against the root it runs.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.