Add a configuration option
Configuration is the operator's API: everything that varies between deploys while the
code stays the same. A new option must be declared once, parsed and validated at
startup, defaulted to today's behaviour, and documented from the same place it is
defined. Half the incidents that start with "we set the env var" end with "in the wrong
process" or "in seconds, not milliseconds".
Steps
- Confirm it should be an option at all. Twelve-factor's test: config is what varies
per deploy (hosts, credentials, limits, feature switches). A value that never differs
between environments is a constant — keep it in code (the
minimalism skill). A
credential is not an ordinary option: follow the security-secret-handling skill.
- Find the config spine. Where options are declared (a schema, a settings module, a
config.sh, a typed Config object), how precedence works (commonly: CLI flag, then
env var, then config file, then default), and whether docs are generated from it. Call search_lore
for the convention, and search for existing env reads with the Grep tool (a Bash
command mentioning process.env is hook-blocked). Add the option THERE; never read
process.env.X or os.environ from a random module.
- Name it by the repo's rules. Prefix, casing, scope and unit
(
APP_UPLOAD_TIMEOUT_MS, not timeout). The unit in the name prevents the classic
seconds-vs-milliseconds outage. Never reuse a retired option's name for new meaning.
- Parse once, validate at load, fail fast. Convert to a typed value (integer with a
range, enum, URL, duration, path) at startup and exit with a message naming the option
and the bad value. Treat an empty string explicitly (unset or invalid — decide and
test). Booleans accept a documented set (
true/false/1/0), not "anything non-empty".
A silently ignored malformed setting is worse than a crash.
- Choose the default deliberately. It is what every operator who does not know the
option exists will run: it must be safe and preserve current behaviour unless the
ticket says otherwise. State why in one comment at the declaration.
- Thread it to every consumer. If a child process, worker, container or dashboard
needs the value, pass it explicitly (spawn env, compose file, chart values) with the
same precedence. Prove the value arrives at the consumer, not just that it parses.
- Document from the source. Regenerate the reference doc if the repo generates one;
otherwise add a row to the config table in README/docs: name, type, default, unit,
effect, since-version. If the dashboard or an admin UI lists settings, add it through
that existing settings definition, not a parallel form. If the repo keeps a COMMITTED
.env.example (or .sample / .template), add the new key there with a placeholder
value; the safety hook allows a tracked template and blocks every other .env* file.
Do not create a new template — say in your evidence that a human needs to add one.
- Test it: default applied when unset; override honoured; each invalid form rejected
with the named message; precedence (flag beats env) when the repo has layers; the child
process sees it when step 6 applies. Evidence via the
record-evidence skill (on a
resume that call is refused: do not retry; put this, the AC → test map and the
smallest-change note in your final message).
Done when
One declaration exists; the default equals today's behaviour (or the ticket's stated
value); invalid values fail at startup with a clear message; tests cover default,
override and invalid; docs name the option, type, default and unit.
Stop and escalate when
- The right default is a product or operational judgement the ticket does not settle:
request_decision with the options and their effect.
- The repo has two competing config systems: use the one the surrounding code uses and
request_decision rather than adding a third.
Rules
- One declaration point; no scattered ad-hoc environment reads.
- Name with prefix, scope and unit; validate and fail fast.
- Safe default that preserves current behaviour unless the ticket changes it.
- Same precedence in every process; prove the value arrives.
- Never log a config value that might be a secret; log the option name.
- Work on the delivery branch (verify with
git branch --show-current); commit, never push.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While threading the option to every process you learn the repo's real config precedence and which processes read which values. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: add-config-option3description: Use when a ticket adds or changes a configuration option — an environment variable, a settings key, a CLI flag, a YAML field — that operators set, and it must have one source of truth, a validated default, precedence rules, and documentation that cannot drift. Invoke for "make X configurable", "add an env var for Y", "expose a setting", or "the default should be Z".4stack: []5area: workflow6metadata:7 source: https://skillmd.com/skills/tmj-90/add-config-option8---910# Add a configuration option1112Configuration is the operator's API: everything that varies between deploys while the13code stays the same. A new option must be declared once, parsed and validated at14startup, defaulted to today's behaviour, and documented from the same place it is15defined. Half the incidents that start with "we set the env var" end with "in the wrong16process" or "in seconds, not milliseconds".1718## Steps19201. **Confirm it should be an option at all.** Twelve-factor's test: config is what varies21 per deploy (hosts, credentials, limits, feature switches). A value that never differs22 between environments is a constant — keep it in code (the `minimalism` skill). A23 credential is not an ordinary option: follow the `security-secret-handling` skill.242. **Find the config spine.** Where options are declared (a schema, a settings module, a25 `config.sh`, a typed `Config` object), how precedence works (commonly: CLI flag, then26 env var, then config file, then default), and whether docs are generated from it. Call `search_lore`27 for the convention, and search for existing env reads with the Grep tool (a Bash28 command mentioning `process.env` is hook-blocked). Add the option THERE; never read29 `process.env.X` or `os.environ` from a random module.303. **Name it by the repo's rules.** Prefix, casing, scope and unit31 (`APP_UPLOAD_TIMEOUT_MS`, not `timeout`). The unit in the name prevents the classic32 seconds-vs-milliseconds outage. Never reuse a retired option's name for new meaning.334. **Parse once, validate at load, fail fast.** Convert to a typed value (integer with a34 range, enum, URL, duration, path) at startup and exit with a message naming the option35 and the bad value. Treat an empty string explicitly (unset or invalid — decide and36 test). Booleans accept a documented set (`true/false/1/0`), not "anything non-empty".37 A silently ignored malformed setting is worse than a crash.385. **Choose the default deliberately.** It is what every operator who does not know the39 option exists will run: it must be safe and preserve current behaviour unless the40 ticket says otherwise. State why in one comment at the declaration.416. **Thread it to every consumer.** If a child process, worker, container or dashboard42 needs the value, pass it explicitly (spawn env, compose file, chart values) with the43 same precedence. Prove the value arrives at the consumer, not just that it parses.447. **Document from the source.** Regenerate the reference doc if the repo generates one;45 otherwise add a row to the config table in README/docs: name, type, default, unit,46 effect, since-version. If the dashboard or an admin UI lists settings, add it through47 that existing settings definition, not a parallel form. If the repo keeps a COMMITTED48 `.env.example` (or `.sample` / `.template`), add the new key there with a placeholder49 value; the safety hook allows a tracked template and blocks every other `.env*` file.50 Do not create a new template — say in your evidence that a human needs to add one.518. **Test it:** default applied when unset; override honoured; each invalid form rejected52 with the named message; precedence (flag beats env) when the repo has layers; the child53 process sees it when step 6 applies. Evidence via the `record-evidence` skill (on a54 resume that call is refused: do not retry; put this, the AC → test map and the55 smallest-change note in your final message).5657## Done when5859One declaration exists; the default equals today's behaviour (or the ticket's stated60value); invalid values fail at startup with a clear message; tests cover default,61override and invalid; docs name the option, type, default and unit.6263## Stop and escalate when6465- The right default is a product or operational judgement the ticket does not settle:66 `request_decision` with the options and their effect.67- The repo has two competing config systems: use the one the surrounding code uses and68 `request_decision` rather than adding a third.6970## Rules7172- One declaration point; no scattered ad-hoc environment reads.73- Name with prefix, scope and unit; validate and fail fast.74- Safe default that preserves current behaviour unless the ticket changes it.75- Same precedence in every process; prove the value arrives.76- Never log a config value that might be a secret; log the option name.77- Work on the delivery branch (verify with `git branch --show-current`); commit, never push.7879## Capture lore8081This skill is one of the places durable, reusable knowledge naturally surfaces:82**While threading the option to every process you learn the repo's real config precedence and which processes read which values.** That kind of fact is _lore_. Capture it via the **lore-capture83protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):84call the Memory MCP `suggest_lore` once at the close of your work — reusable85conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.