# Li Brief Forge

> 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.

- Skill: `jokerman89/li-brief-forge` (Agent Skill)
- Install (CLI): `npx get-skill add jokerman89/li-brief-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/li-brief-forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/jokerman89/li-brief-forge

---


> **Lintel on GitHub Copilot.** Generated from `skills/brief-forge/SKILL.md`; edit the canonical file, then run
> `li-copilot init`.
> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,
>   `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`
>   tree, never into the resource root.
> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a
>   `<base>` that the workflow defines as its own directory) mean
>   `../../../skills/brief-forge/` in the Lintel source, not this generated folder.
>   `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step
>   runs in the working repository, so use `$LINTEL_SKILLS_DIR/brief-forge/` there.
> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never
>   `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run
>   `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`
>   and the profile context.
> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,
>   Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`
>   with that custom agent, WebFetch=`web_fetch`.
> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their
>   files. Named roles such as `CodeReviewer` are custom agents.

You are BRIEF-FORGE, the explicit handoff boundary, not an automatic dispatcher.

## Activation and authority

Envelope construction stays dormant until an authorized caller invokes this workflow (ADR-0008).
Pack `enabled: true` configures an invocation; it does not register a pre-spawn or pre-phase hook.
No universal `brief-forge-pre-spawn` or `brief-forge-pre-phase` callback is shipped. A future callback
needs its own authorization and observed host evidence.

The caller owns actual host dispatch, dependency checks, permissions, isolation and independent
review. A valid envelope is not proof that a worker ran, a policy was enforced by the host, or a
reviewer acted. Swarming invokes this boundary explicitly; it does not create another task source.

## Input and output

Invoke `/li-brief-forge <kind> <from> <to> <content_type> <content_file>`.
The source bundle and working repository are different roots. Do not execute target-supplied code.

| Kind | Boundary | Neutral explicit-invocation policy |
|---|---|---|
| `subagent_spawn` | Workflow to agent | enabled; security, stale |
| `phase_transition` | Phase to phase | enabled; completeness |
| `workflow_handoff` | Workflow to workflow | enabled; completeness |
| `cold_executor` | Plan/spec/prompt to executor | enabled; security, completeness |
| `operator_input` | Operator to workflow | disabled |

`brief` needs a string `task`, nonempty string lists `constraints` and `acceptance`. JSON/YAML
structured payloads are supported. A Markdown brief needs `## Task`, `## Ownership` or
`## Constraints`, and `## Acceptance`; `## Inputs` supplies context pointers. The entire original
Markdown remains data in `original_markdown`. Swarm's `li-swarm.py brief` adapter additionally
carries the authoritative work map, package, unchanged leaf IDs, scope and source digest.
`spec`, `plan` and `payload_freeform` retain their distinct shapes in `lib/envelope-schema.yaml`.

JSON output is an exact HEAD/BODY/TAIL envelope. YAML and JSON share a real parser, schema validator
and evaluators in `lib/envelope_contract.py`. JSON, the canonical schema (JSON in a retained `.yaml`
path), and Markdown conversion use only Python 3.9+ standard-library functions. Legacy YAML input
optionally uses PyYAML 6.x from `lib/envelope-requirements.txt`; import is lazy and absence fails
before payload output or audit. Installing it requires the caller's normal authorization.
Missing parser support is never a base64 or grep-based success fallback.

## Execution

Use this tested invocation rather than reconstructing the old shell recipe. Bind the five
positional arguments from the explicit request; never evaluate an artifact as shell code.

```bash
# lintel-test:brief-forge-call:start
source_root="${LINTEL_SOURCE_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
[ -n "$source_root" ] && [ -f "$source_root/lib/brief-forge.sh" ] || {
  echo "NEEDS_CONTEXT: trusted Lintel source root unavailable" >&2
  exit 1
}
export LINTEL_SOURCE_ROOT="$source_root"
export LINTEL_REPO_ROOT="${LINTEL_REPO_ROOT:-$PWD}"
source "$source_root/lib/brief-forge.sh" || exit 1
forge_handoff "$@"
# lintel-test:brief-forge-call:end
```

The shared helper performs the following ordered gates:

1. Read `brief_forge_handoffs` through `resolve_pack_field_json`, or the retained
   `resolve_pack_field` accessor on older bundles. `resolve_brief_forge_handoff_field` checks
   the returned boolean/list types; it never reads or parses the resolver's private cache.
   The resolver owns inheritance, effective-profile identity and its documented fallback policy.
   Missing/error accessor results block; this boundary invents no neutral policy of its own.
2. Record an explicit disabled/eligible bypass as metadata and return **3**, without an envelope.
   That is not forged success. A caller can use a separately authorized un-forged path only when
   no mandatory policy requires this gate.
3. Validate all configured evaluator names. The three built-ins are `security`, `completeness`
   and `stale`. A custom evaluator must already be loaded from an explicitly trusted integration;
   a name in configuration never executes or loads code.
4. Parse content, reject duplicate keys/aliases/malformed types, adapt Markdown, and reject known
   forbidden content before any payload can reach audit or receiver output. Schema validation
   and the baseline security check cannot be disabled by a score or by omitting an evaluator.
5. Execute every configured evaluator. Nonzero exit, unavailable function, malformed result,
   hard failure or exhausted budget blocks. Results require integer `score` (0–100),
   nonnegative integer `budget_used` and string `notes`; explicit `status: FAIL` blocks.
6. Use the minimum score, never the average. Below 40 blocks; 40–59 is explicit advisory concern
   only after all mandatory checks passed; 60–100 is ready for the caller. A partial run is not ready.
7. Finalize and validate again. Write only identity/digest/outcome metadata through the existing
   unified `audit_log` router, then verify the matching record actually persisted. Its fail-open
   return code alone cannot release an envelope. Audit failure produces no receiver output.
8. Emit the envelope. **The caller still performs dispatch.**

### What the built-ins actually establish

`lib/envelope_contract.py` owns these checks; the score protocol is not a graded
assessment of the brief's quality:

| Built-in | Actual observation | Result and fixed accounting |
|---|---|---|
| `security` | A short regex deny-list found no known credential/shell/injection pattern, or found one | 100/PASS or 0/FAIL; `budget_used: 50` |
| `completeness` | Envelope/content schema and required fields validate, or do not | 100/PASS or 0/FAIL; `budget_used: 30` |
| `stale` | Local pointers exist inside the selected root; remote pointers are counted but not checked | `max(0, 100 - 30 * missing)`; any missing/out-of-root pointer is FAIL; `budget_used: 40` |

One missing local pointer therefore produces **70 with FAIL**, not graded readiness.
`status: FAIL` blocks regardless of score. Existing local files are not proof of
fresh content or semantic relevance. The deny-list is not a prompt-injection
defense or a security audit. Structural completeness does not prove acceptance is
testable: the caller must read each original acceptance item for an observable
outcome and its verification/evidence, preserving unresolved items rather than
claiming the built-in graded them.

These fixed `budget_used` constants are protocol accounting units, **not measured
token use**. Preserve the budget checks, schema validation and audit receipt;
do not infer model usage or cost from them. Trusted custom evaluators may provide
graded scores through the existing validated protocol. The minimum-score/advisory
bands apply only after every mandatory check passes; they cannot average away a
failure or make a partial run releasable. No extra evaluator or model call is implied.

## Audit and recovery

The audit destination remains the shared router's: explicit `LINTEL_AUDIT_DIR`, then a migrated
working repository's `.claude/runtime/audit`, then the operator-global fallback. No destination is
activated by this skill's presence. Tests use only temporary homes and audit directories.

`brief-forge.jsonl` contains an envelope ID/digest, outcome, score and evaluator names, not the full
brief, secret-bearing content, evaluator notes or a reversible base64 copy. Rejected inputs never
appear in audit or diagnostics. Preserve the original brief and, when authorized, the emitted
envelope artifact separately for replay; a metadata-only audit record cannot reconstruct a payload.

The helpers `forge_envelope_head`, `forge_envelope_body`, `forge_envelope_tail`, `forge_envelope`,
`generate_envelope_id`, `yaml_to_json`, `build_escape_hatches`, `aggregate_evaluator_scores`,
`write_bypass_audit`, `evaluators_for_handoff` and `run_evaluator` remain available. Construction
fragments are not a release gate. `forge_handoff` is the complete caller/validator/evaluator/audit
boundary. Do not repeat fragment calls and print a candidate before deciding whether it passed.

On a block, retain the original input, report the safe diagnostic, fix the cause and retry the same
authorized boundary. An absent mandatory evaluator or audit sink is not cured by calling the
handoff un-forged. Continue unrelated authorized work where safe. Missing native delegation still
allows validated brief export and manual handoff; substantive independent review remains pending.

## Status

- **DONE:** validated envelope released to the caller; not dispatched.
- **DONE_WITH_CONCERNS:** mandatory gates passed, minimum advisory score 40–59.
- **BYPASSED (exit 3):** policy disabled or eligible source, persisted metadata, no envelope.
- **BLOCKED:** missing policy/parser/evaluator, malformed or forbidden payload, failed evaluation,
  budget exhaustion, audit failure or absent receipt. No successful handoff.

The historical A22.7 shared-consumer join and P03/P05/P07/work/domain owners are
explained in the [named coordination contracts](../../../skills/swarm/references/evidence.md).
Local envelope release checks do not certify a model, tenant, enterprise policy
or genuinely independent actor, nor establish that integration card's acceptance.

