UNRELEASED DEVELOPMENT SNAPSHOT · READ-ONLY EXCERPT

skills/brief-forge/SKILL.md

This is the cited technical source at local revision 275a354, inspected on 22 September 2026. It differs from the public release. This reference publishes only the cited sections, not an installable release or the development branch.

Line numbers refer to the complete recorded file. Uncited lines are omitted. Full-file SHA-256: 01de57b18a32e044f5fa6b650935c6c55ce70b6cb0712d46a7ac48d5ffb9347f.

1---
2name: brief-forge
3layer: foundation
4description: Use when a workflow explicitly hands work across a boundary — spawning a subagent, transitioning a phase, passing to a cold executor, or taking operator input — to build a structured envelope and run the active pack's evaluators on it.
5color: cyan
6tools: Read, Write, Bash
7voice: internal
8cli_support: [claude-code, codex]
9---
10
11You are the BRIEF-FORGE — the explicit hand-off gate for workflow boundaries that invoke it.
12
13## What this skill does
14
15When a workflow invokes Brief Forge before control passes to another component, it:
161. **Constructs an envelope** per `lib/envelope-schema.yaml` (HEAD + BODY + TAIL)
… omitted uncited lines …
181  write_bypass_audit "$kind" "$from" "$to"
182  exit 0
183fi
184
185# Validate every configured name before constructing or dispatching an envelope.
186# The default pack reaches this call with security/stale for subagent_spawn;
187# a merely declared but unloaded pack evaluator blocks here.
188validate_brief_forge_evaluators "$evaluators_csv" || exit 1
189```
190
191### Step 3 — Construct envelope (HEAD + BODY + TAIL)
192
193```bash
194envelope_path=$(mktemp)
195trap 'rm -f "$envelope_path"' EXIT
196
197forge_envelope_head "$kind" "$from" "$to" > "$envelope_path"
198forge_envelope_body "$content_type" "$content_file" >> "$envelope_path"
199```
200
201`forge_envelope_head` generates:
202```yaml
203head:
204  envelope_id: <ULID>
205  envelope_schema_version: "1"
206  kind: <kind>
207  from: <from>
208  to: <to>
… omitted uncited lines …
253
254### Step 5 — Compose tail + finalize
255
256```bash
257# Aggregate completeness score (min of all evaluator scores, weighted by importance)
258completeness_score=$(aggregate_evaluator_scores "${evaluator_results[@]}")
259
260# Compose escape hatches (per content_type)
261escape_hatches=$(build_escape_hatches "$content_type" "$from")
262
263# Audit pointer. _audit_out_dir applies: explicit LINTEL_AUDIT_DIR, then a
264# v5-layout repo's .claude/runtime/audit/, then the operator-global fallback.
265audit_dir="$(_audit_out_dir brief-forge)"
266audit_path="$audit_dir/envelopes-$(date -u +%Y-%m-%d).jsonl"
267mkdir -p "$audit_dir"
268
269forge_envelope_tail "$completeness_score" "${evaluator_results[@]}" "$escape_hatches" "$audit_path" >> "$envelope_path"
270```
271
272### Step 6 — Write audit + emit envelope
273
274```bash
275# Write the envelope as a single JSON line to audit
276envelope_json=$(yaml_to_json "$envelope_path")
277echo "$envelope_json" >> "$audit_path"
278
279# Emit envelope to stdout (for the receiver to consume)
280cat "$envelope_path"
281
282# Scope-routed stats use the same destination policy as the envelope pointer.
283audit_log "brief-forge" "brief_forge_emitted" \
284  "event=$kind" "from=$from" "to=$to" \
285  "completeness=$completeness_score" "budget_used=$budget_used" \
286  "evaluators_run=${#evaluator_results[@]}"
… omitted uncited lines …
323**Reads:**
324- `lib/envelope-schema.yaml` (envelope shape)
325- `lib/pack-resolver.sh` (active-pack discovery, inheritance cache and two-level pack policy)
326- the skill-local block-scoped reader (three-level event and cold-path fields under
327  `brief_forge_handoffs`)
328- `lib/brief-forge.sh` (envelope helpers)
329- `lib/brief-forge-evaluators.sh` (security, completeness and stale built-ins)
330- any trusted active-pack evaluator library explicitly sourced before dispatch
331- Content file passed in (varies by content_type)
332
333**Writes:**
334- the scope-routed `envelopes-<date>.jsonl` (per-envelope audit)
335- the scope-routed `brief-forge.jsonl` (per-forge emitted, bypassed or blocked events)
336- stdout (the envelope, for receiver consumption)
337
338For v5-layout repository work, the routed directory is `.claude/runtime/audit/`. An explicitly set
339`LINTEL_AUDIT_DIR` overrides that destination; work without a migrated repository falls back to
340`~/.lintel/audit/`. The runnable sequence above and these write declarations use the same unified
341router from `bin/_audit.sh`.
342
343**Invoked by:**
344- Source workflows that explicitly call `/li:brief-forge` at a documented boundary
345- Direct operator or test invocations
346
347No `brief-forge-pre-spawn` or `brief-forge-pre-phase` hook is registered in the shipped hook