The library & tools

Everything an agent reads lives in one git repository. Words are code: diffed, reverted, hot-reloaded, merged from upstream — and audited by hash on every run.

Four kinds, one namespace

Kind	What it is
`directives/`	The verbs. A markdown file with a tiny frontmatter contract (`mode:` required; persona, model, description optional). A routine triggers one on a schedule; a workflow chains them; an agent can read one as a skill or invoke one as a tool.
`personas/`	The voices — role identities composed under a directive at materialization time.
`fragments/`	Shared prose included by reference (`{{> name}}`): engineering standards, escalation rules, verification discipline.
`scripts/`	Utilities in any language. JavaScript runs in an in-process sandbox (no filesystem, no network); anything with a shebang runs as a daemon subprocess, JSON in, JSON out. Metadata rides a comment header; `tool: true` plus a schema makes a script agent-callable.

A broken edit never bricks the system: the daemon validates the whole tree on every load and keeps serving the last good one until the tree parses again. Composition happens once, at work creation — the assembled prompt is frozen onto the work with a manifest of every fragment and its hash.

Distribution is a git merge

A fresh install forks a shared base library — standard roles, the flow pipeline, starter workflows. forge directives update merges upstream improvements into your fork like any other code; your local edits and the base evolve independently and reconcile with ordinary git machinery.

The tool bridge

Five small, static tools connect agents back into the system, with all the interesting decisions made at call time:

forge_library — search and read the library: the skills path.
forge_script_run — run a tool-flagged script synchronously.
forge_directive_run — spawn a sub-task from a directive. Guardrails at the call: spawn depth capped, fan-out capped, backlog class by default, autonomy inherited, full provenance stamped.
forge_workflow_run — fire a workflow, get a run id back.
forge_scratch — the organic layer, below.

Tools that earn tenure

Agents constantly write small scripts to answer small questions. Instead of dying in worktrees, they go through forge_scratch: save-and-run into an LRU cache, reusable by name, discoverable by search. A script that crosses a usage threshold — enough runs, from enough distinct attempts — triggers a curation task against the library repository itself. The curator's standing orders:

If the library already covers the functionality, don't add a twin — fix the existing script's discoverability (its description and schema) and stop.
If an existing script is close, extend it to cover the missing path.
Otherwise promote: rename if a clearer name exists, apply a straightforward optimization pass — promoted scripts are hot paths — and write the proper metadata header.

The change lands through the ordinary merge pipeline, journaled, with the usage stats in the commit message. The library grows the way good internal tooling always has: bottom-up, by demonstrated demand, with an editor.

The library is a repository Forge works on. It registers itself at bootstrap, which is what lets promotion — and a standing reflection routine that sharpens the worst-performing directive, evidence-first — run through the same plan/build/verify/merge machinery as any feature.

Next: The learning loop — the return path that makes decomposition recursive.