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
GuideSnapshot	The fetched reference text plus staleness metadata: `{ url, retrieved_at, visible_updated_at
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: " 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.
7. 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.
8. 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.
9. 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.
10. 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.
11. 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