forge

What this skill does

# Forge: Reference-Grounded Initial-Prompt Formation

Form a ready-to-use initial prompt 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 initial prompt that bootstraps a follow-up session or tool invocation.

**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 an initial prompt the user carries into the next session or tool.

## Core Contract

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

```
ReferenceIntake
  -> ResolvedIntentIR        (core: reverse-induce under-determined coordinates)
  -> GroundedReference       (core: canonical-external snapshot + staleness guard)
  -> VendorPromptDraft       (adapter: project IR through the reference schema)
  -> InitialPrompt           (adapter: initial prompt for a follow-up session/tool)
```

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`, and `codex-goals` 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, and a `stale-guide` flag when the staleness guard did not pass. |
| `InitialPrompt` | The endpoint artifact: an initial prompt for a follow-up session or tool. 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 agains