Forge

---
name: forge
description: "Reference-grounded prompt-artifact formation. Reads a target reference doc, surfaces the under-determined contract coordinates, and projects a ready-to-use prompt or standing skill recipe."
---

# Forge: Reference-Grounded Prompt-Artifact Formation

Form a ready-to-use prompt artifact by grounding the user's under-determined intent in an authoritative reference document. This skill does not run the downstream tool, open branches, or create PRs. It surfaces the user's intent coordinates, grounds them against a reference (dynamically fetched, staleness-guarded), and emits one prompt artifact — an initial prompt for a follow-up session or tool, or a standing custom-skill recipe.

**This is a projection utility, not a runtime executor and not a new epistemic protocol.** Forge introduces no new deficit. It realizes a known composite — surface under-determined intent coordinates (reverse-induction, the `/elicit` move) ∘ ground them against a canonical external reference (the `/inquire` canonical-external move) → thin projection. The output is a prompt artifact the user carries into the next session or tool.

## Core Contract

`/forge` owns reference-grounded prompt-artifact formation:

```
ReferenceIntake
  -> ResolvedIntentIR        (core: reverse-induce under-determined coordinates)
  -> GroundedReference       (core: canonical-external snapshot + staleness guard)
  -> VendorPromptDraft       (adapter: project IR through the reference schema)
  -> PromptArtifact          (adapter: a prompt-family payload for a follow-up session/tool, or a standing custom-skill recipe)
```

The **core** is vendor-agnostic and stops at `ResolvedIntentIR` plus the validated `GroundedReference`. The **adapter** owns the projection into a vendor-native artifact form. The core never learns vendor specifics; the adapter never re-derives intent.

## Core / Seam / Adapter

- **Core (vendor-agnostic)**: reverse-induce the user's under-determined intent into `ResolvedIntentIR`; extract the adapter-derived required slots (`ContractElements`) the reference's schema requires; partition slots into relay vs constitution; own the staleness policy, provenance, and generic validation.
- **Vendor Adapter Contract (the seam)**: the narrow, parameterized interface every adapter satisfies. New references plug in by adding an adapter section — accumulated per real use, never built top-down.
- **Adapters (concrete instances)**: `Higgsfield`, `gpt-image`, `codex-goals`, and `claude-session` ship now. Each owns reference discovery/fetch, the reference's prompt schema, the projection rendering, and unsupported-field degradation.

### Vendor Adapter Contract (seam)

Each adapter provides, against a fixed contract:

| Seam operation | Meaning |
|---|---|
| `capabilities` | The reference's model/target constraints (resolution, duration, required fields, supported modalities). |
| `fetch_guide_snapshot` | Acquire the reference text via canonical-external retrieval — dynamic web fetch by default, or a local canonical mirror (a universally-deployed agent skill, an internal docs mirror, etc.) when the adapter binds to one. Produce a `GuideSnapshot` with staleness metadata. |
| `derive_prompt_schema` | From the snapshot, derive the reference's prompt schema (the slots the artifact must fill). |
| `project` | Render `ResolvedIntentIR` through the schema into a `VendorPromptDraft` (an adapter may first specialize it into a reference-specific IR such as `CreativePromptIR`). |
| `validate` | Check the draft against `capabilities`; surface degraded or unsupported fields. |

Narrowest seam contract: `ResolvedIntentIR × GuideSnapshot -> VendorPromptDraft`, carrying provenance and freshness. The core does not know "Seedance wants shot count first" or "a Goal needs a blocked-stop clause"; that lives in adapters.

## Types

| Type | Meaning |
|---|---|
| `ReferenceTarget` | The authoritative document to ground against: a vendor model prompt guide, the Codex Goals spec, or another reference the active adapter recognizes. |
| `ContractElements` | The reference-required slots forge extracts so the reference can be applied. The concrete slot set is adapter-derived from the reference's schema, not fixed by the core. |
| `ResolvedIntentIR` | The core's vendor-agnostic resolved-intent IR: the user's intent plus the resolved coordinates the reference's required slots need, modality-tagged but not media-specific. Core output stops here; an adapter may require a more specific specialization. |
| `CreativePromptIR` | An adapter-required specialization of `ResolvedIntentIR` for creative-media references (the Higgsfield-class adapter requires it): the modality-aware IR `{ intent{goal,audience?,mood?}, modality(image|video|audio|voice), scene?, visual?, motion?, audio?, params?, constraints{mustInclude?,mustAvoid?,references?} }`. Lossy-but-useful; preserves intent and common coordinates, not cross-reference semantic equivalence. The core never produces it; the creative-media adapter derives it from `ResolvedIntentIR`. |
| `GuideSnapshot` | The fetched reference text plus staleness metadata: `{ url, retrieved_at, visible_updated_at|version, content_hash, canonicality_score }`. |
| `RelaySlot` | A contract slot determined by the reference plus the user's stated intent. Forge auto-fills it with a cited basis. |
| `ConstitutionSlot` | A contract slot requiring the user's judgment. Forge fills it with a proposed default and explicitly flags it for recognition. |
| `VendorPromptDraft` | The adapter's projection of the IR through the reference schema, with provenance, freshness, a `stale-guide` flag when the staleness guard did not pass, a `model-fallback` flag when no per-model page exists for the resolved model (the draft is built on the general layer only), a `transport-unsafe` flag when the projected payload carries shell-active tokens or secret-substitution patterns hazardous across a shell-carrier handoff, and a `reasoning-echo-unsafe` flag (adapter-raised) when the payload or the target's inherited output-style carries an extraction-shaped instruction — one whose object is the model's own internal reasoning (reproduce / transcribe / explain it as response text), not the domain material's evidence and causality — against a model whose page flags that as refusal-triggering. |
| `PromptArtifact` | The endpoint artifact: a prompt-family payload — an initial prompt for a follow-up session or tool, or a standing custom-skill recipe. Its form is adapter-determined (a Higgsfield video prompt; a Codex `/goal …` string). |

## Phase 0: Bind Reference and Intent

Bind two inputs:

- `ReferenceTarget` — an explicit reference (URL, vendor+model, "the Codex Goals doc"), or the reference the active adapter defaults to.
- The user's intent utterance — the latent, under-determined creative or task intent.

**Adapter selection (relay-first):** Select the adapter by relay when the reference or the user's request names or determines it — e.g., "/forge higgsfield: <intent>" or a Higgsfield model guide → `higgsfield`; "draft a /goal …" or the Codex Goals spec → `codex-goals`. Auto-include it; do not gate. Only when the adapter is genuinely ambiguous or unrecoverable, present the Adapter Index as a structured recognition choice (an AskUserQuestion over the indexed adapters) — never an unconditional prompt, never free-text, and never when relay determines the adapter. Do not guess the reference.

After the adapter is selected, Read `adapters/<selected>.md`. The full adapter contract is progressively disclosed — loaded only on selection, not before.

## Phase 1: Resolve Intent (Core — Reverse-Induction)

Reverse-induce the under-determined intent into `ResolvedIntentIR`. Surface only the coordinates the reference will require; do not interrogate coordinates the reference and stated intent already determine.

Use inline lightweight reverse-induction. When the intent carries heavy aporia (multi-axis, no stable coordinate basis), escalate to `/elicit` rather than forcing a thin IR, then resume Phase 2 with the resolved endpoint.

## Phase 2: Ground the Reference (Core — Canonical-External + Staleness)

Call the adapter's `fetch_guide_snapshot`: acquire the reference via canonical-external retrieval — dynamic web fetch by default, or a local canonical mirror when the adapter binds to one (a universally-deployed agent skill, an internal docs mirror, etc.). Default discovery is **hybrid** — a curated per-reference seed, resolved at runtime, accepted only if the staleness guard passes.

Staleness guard: record `{ url, retrieved_at, visible_updated_at|version, content_hash, canonicality_score }` and cross-check at least one of: a changelog/version page, a visible page date, an API model/version list, or a canonical docs index. For local canonical mirrors, the mirror file's mtime serves as `visible_updated_at` and a content hash (when applicable) as `content_hash`; cross-check is the source's own version field, or — if absent — the mtime against a known-good threshold. If stale or unverified, fall back to the curated seed and mark the draft `stale-guide`.

## Phase 3: Extract Contract and Partition Slots (Core)

Derive the reference's prompt schema and extract the adapter-derived required slots (`ContractElements`). Partition every slot:

- `RelaySlot` — determined by reference plus stated intent → fill with a cited basis.
- `ConstitutionSlot` — requires the user's judgment → fill with a proposed default, explicitly flagged.

Core output stops here at `ResolvedIntentIR` plus the partitioned slots and the validated `GroundedReference`.

## Phase 4: Project and Present (Adapter + Constitution)

The adapter projects the IR through the reference schema into a `VendorPromptDraft`, then `validate` checks it against `capabilities`.

Present a ready-to-use draft with **every contract slot filled**. Relay slots show their cited basis; constitution slots show the proposed default with an explicit recognition flag. Then surface the artifact as the `PromptArtifact` for the follow-up session/tool, with provenance, freshness, and any `stale-guide`, `model-fallback`, `transport-unsafe`, or `reasoning-echo-unsafe` flag.

Emit the `PromptArtifact` transport-safely (Rule 12): the payload is a **literal opaque artifact**, so display it verbatim (fenced) for on-screen reading, recommend file-based handoff over inline shell args for injection, and surface any `transport-unsafe` flag `validate` raised.

Surface — present the filled draft as context (slots, bases, flags) before the gate; the gate carries only:

1. **Accept** — use this prompt artifact as-is in the follow-up session/tool.
2. **Adjust flagged slots** — change one or more constitution slots, then re-project.
3. **Regenerate** — re-fetch the reference or re-resolve intent and rebuild.

Default is the filled draft, not a bare question list.

## Adapter Index

Adapter bodies are progressively disclosed: this index is always loaded; each adapter's full contract lives in `adapters/<name>.md` and is Read only after the adapter is selected (Phase 0).

| Adapter | Reference | PromptArtifact form |
|---|---|---|
| `higgsfield` | Higgsfield video model prompt guide (video-only; image generation denied) | a Higgsfield video prompt for a follow-up session |
| `gpt-image` | Codex imagegen skill at `$CODEX_HOME/skills/.system/imagegen/` (image-only; targets `gpt-image-2`; web cookbook fallback) | a `gpt-image-2` prompt block (using the source's shared schema) plus parameter envelope |
| `codex-goals` | OpenAI Codex Goals specification | a strong `/goal …` string for a follow-up Codex session |
| `claude-session` | Claude prompting best-practices guide (model-axis: `prompting-claude-{model}`; first-party, reflexive) | a model-tailored handoff initial-prompt for a follow-up Claude session (`/remote-spawn` worktree or remote-control) |

Each adapter file satisfies the Vendor Adapter Contract (`capabilities` / `fetch_guide_snapshot` / `derive_prompt_schema` / `project` / `validate`). New references plug in by adding an `adapters/<name>.md` file as accumulated prior — see Deferred Colimit; do not pre-build a registration framework.

## Rules

1. **No new deficit** (Architectural — role boundary): forge is a projection utility, not a protocol. It introduces no deficit→resolution morphism. It composes the `/elicit` and `/inquire` canonical-external moves and projects; it does not name a new epistemic deficit.
2. **Core stops at IR** (Architectural — boundary invariant): core output is `ResolvedIntentIR` plus the validated grounded reference. The artifact form is adapter-determined and must not be promoted to a core output type. Promoting a completion-contract form into the core re-imports the routable/provenance boundary that a separate research issue owns; keep contract-ness in the adapter.
3. **Prompt-artifact endpoint** (Architectural — handoff specificity): every adapter's projection endpoint is a `PromptArtifact` — a prompt-family payload (an initial prompt for a follow-up session or tool, or a standing custom-skill recipe). This is a unifying role, not a shared output type; the real per-adapter forms remain those in the Adapter Index "PromptArtifact form" column.
4. **Reference grounding required** (Axiom anchor — Detection with Authority): every projection grounds against a fetched reference with cited provenance. A projection without a grounded, provenance-tagged reference is not a forge output.
5. **Recognition over Recall** (Axiom anchor — Recognition over Recall): forge emits a filled draft, not a blank question list. Relay slots are auto-filled with cited basis; constitution slots carry a proposed default explicitly flagged so the user recognizes and adjusts rather than recalls from blank.
6. **Surfacing over Deciding** (Derived — Surfacing over Deciding): constitution slots are surfaced with their proposed defaults flagged; forge does not silently finalize a slot that requires the user's judgment. A blind full draft that hides which slots were guessed is an anti-pattern.
8. **Staleness guard** (Architectural — provenance continuity): reference evidence is staleness-guarded and tagged `web:{url}` or `file:{path}` depending on the canonical-source substrate. If staleness cannot be verified, fall back to the curated seed and mark the draft `stale-guide`; never present a stale reference silently.
9. **Adapter accumulation, not top-down** (Architectural — empirical restraint): adapters are added per real use as accumulated prior. The Adapter Index above is the authoritative list of currently-shipped adapters; do not build a multi-reference framework ahead of use.
10. **Formation, not execution** (Architectural — role boundary): `/forge` does not run the downstream tool, create branches, or open PRs. It emits the prompt artifact and stops.
11. **Progressive-disclosure adapters** (Architectural — context economy + accumulation): adapter bodies are isolated `adapters/<name>.md` files loaded only after selection; the always-loaded Adapter Index carries name + reference + PromptArtifact form. Selection is relay when the reference or request determines the adapter, a structured recognition gate only on genuine ambiguity (never unconditional). Adapters accumulate as additive files — the deferred-colimit accumulation mechanism made physical; do not build a generalized adapter-registration framework ahead of use.
12. **Transport-safe handoff** (Architectural — handoff boundary): the `PromptArtifact` is a literal opaque payload that crosses transport boundaries the projection does not control — a markdown terminal render, a shell argument, a paste buffer. Display it **verbatim** (fenced) so document XML tags and special characters survive on-screen rendering instead of being interpreted as HTML and truncated. For injection into a shell carrier, recommend **file-based handoff** (Write the payload, the carrier reads the file) over inline shell args: `` ` ``, `$(`, and `${` undergo shell substitution and `'` can break out of a quoted argument, so a literal `$(…)` secret-fetch in the payload would execute and leak. A shell-carrier adapter's `validate` raises `transport-unsafe` when the payload carries such tokens — currently realized in `claude-session`, with other shell-carrier adapters adding the scan as they accumulate (Rule 9); never present a `transport-unsafe` payload for inline injection silently.

## Deferred Colimit (do not extract yet)

The cross-adapter abstraction — "reference-grounded prompt-artifact formation" generalized over reference classes — is a **deliberately deferred colimit**. Its structure is a prescriptive core plus per-instance realizations plus accumulated prior. It is **not** extracted or named now.

Trigger to extract the meta-pattern: a built first-reference instance plus accumulated prior from real use of a second instance, per the epistemic cost asymmetry (an unused abstraction costs more than a missing one) and instance-first methodology. Naming it before that is the over-generalization the methodology refuses.

Candidate adapters (not yet realized — list only, do not build ahead of use):

- `cookbook-conformer` — ground intent against a cookbook/recipe reference.
- `best-practices-conformer` — ground intent against a best-practices document.
- additional vendor model-guide adapters as real use accumulates.

## Boundary Note

`/forge` forms a prompt artifact and stops. It reads a reference and surfaces intent; it does not execute the tool, run the Goal, generate the media, or open branches/PRs. The reference-fetch move mirrors the `/inquire` canonical-external channel but forge owns the projection.

## Operational checklist (per cycle)

- [ ] Phase 0 reference and intent bound; adapter selected by relay (structured recognition gate only on ambiguity); `adapters/<selected>.md` Read only after selection
- [ ] Phase 1 intent reverse-induced into `ResolvedIntentIR`; heavy aporia escalated to `/elicit`
- [ ] Phase 2 reference fetched with staleness metadata; hybrid seed + dynamic fetch + guard applied
- [ ] Phase 3 adapter-derived required slots extracted; every slot partitioned relay vs constitution
- [ ] Phase 4 filled draft presented — relay slots cited, constitution slots flagged
- [ ] PromptArtifact emitted with provenance, freshness, and `stale-guide` / `model-fallback` / `reasoning-echo-unsafe` flags when applicable
- [ ] PromptArtifact displayed verbatim and emitted transport-safely — file-based handoff recommended over inline shell args; `transport-unsafe` flag surfaced when applicable
- [ ] Core output stopped at IR; artifact form kept in the adapter
- [ ] No tool execution, branch, or PR performed