forge

/forge

Interview the user with structured multiple-choice questions, then forge a prompt that another agent session can execute with minimal ambiguity. Targets Claude Opus 4.7 or GPT-5.5 (Codex CLI). Use this skill for coding and agentic prompt design, anywhere from a single bug-fix prompt to a long-horizon repo migration.

The skill has three phases: interview, draft, deliver.

Read references/anthropic-claude-prompting.md when targeting Opus 4.7 and the task is long-horizon, tool-heavy, or expensive enough that prompt quality materially matters. Read references/openai-gpt-5-5-prompting.md when targeting GPT-5.5 or Codex.

Activation

Two ways to invoke:

• Bare: /forge. Open with "What do you need a prompt for?" and treat the user's reply as the seed.
• Seeded: /forge <topic>. Use the topic as the interview seed, skip the opening question, and dive into clarifications.

The skill also activates conversationally when the user says things like "help me write a prompt", "I need an Opus 4.7 prompt", "scope this for me", or asks for prompt design. When activated conversationally, treat the user's most recent message as the seed.

Run /forge in the main session, never in a forked subagent. Subagents cannot relay user replies in either Claude Code or Codex, so the interview will hang.

Phase 1: Interview

Run an adaptive interview. Pick the transport based on the harness, then start with up to 5 base questions. Add deeper questions only when answers flag complexity (long-horizon, tool-heavy, subagent-orchestrated, validation-heavy, multi-system).

Interview transport

The skill ships in two harnesses with different interaction primitives. Detect which is available and pick the matching transport. Never invent a tool that is not in your toolset.

• Claude Code (any mode, including outside plan mode): use the AskUserQuestion tool. Up to 4 questions per call, 2 to 4 options each, header max 12 chars. An "Other" free-text choice is available by setting the per-question option that displays an additional free-text choice after the listed options.
• Codex CLI / Codex app, and any harness without AskUserQuestion: use the text fallback below. Codex does not expose a multi-choice modal to skills or custom prompts. The selection modals you see in the Codex Mac app are wired to built-in slash commands (/plan, /model, /agent etc.), not to user code, so the skill cannot trigger them. It renders questions as plain text and waits for the user's reply.

Decision rule: if AskUserQuestion is in your tool list, use it. Otherwise use the text fallback. Both transports use the same base questions and the same adaptive deep-dive triggers below; only the rendering changes.

Text fallback format (Codex)

Render exactly one question per turn, then stop and wait for the user's reply before continuing. Use this template:

**Q{n} of {est_total}: {Header}**

{Question text}

  1. {Option label}{ (Recommended) if applicable}
     {one-line description of what this option means}
  2. {Option label}
     {one-line description}
  3. ...

Reply with a number, or write your own answer.

Rules for the text fallback:

• One question per turn. Do not batch. The user replies, you acknowledge in one short line, then send the next question.
• 2 to 4 numbered options per question. The "Other (free text)" path is implicit: any non-numeric reply is treated as the user's free answer.
• Recommend by suffixing the option label with " (Recommended)", same convention as AskUserQuestion.
• Use the same headers and option text as the AskUserQuestion variant. Content stays identical; only rendering changes.
• Free-text questions (Objective, Tech stack, Done criteria) skip the numbered list and just ask the question with a one-line prompt for the user's answer.
• Stop the interview the moment you have enough to fill every required Prompt Shape section.

Base questions

Ask these in order using the chosen transport. 2 to 4 mutually exclusive options per multiple-choice question. Recommend an option (first in the list, "(Recommended)" suffix) when one is the clear default for coding work.

1. Objective. What concrete outcome must the executing model achieve? Use a free-text follow-up if multiple-choice does not fit.
2. Execution environment.
   • Codex CLI (terminal-based agent)
   • Claude Code (CLI / IDE)
   • Anthropic API directly (programmatic harness)
   • Other harness (free-text)
3. Effort and persistence profile.
   • Long-horizon, validation-heavy: xhigh effort, persistence required (Recommended for full implementations)
   • Intelligence-sensitive but bounded: high effort
   • Quick scoped change: low effort
4. Tech stack and tooling in play. Free-text. Let the user name their own stack rather than assuming Docker, Supabase, Playwright, or any other specific tools. Capture languages, frameworks, services, runtime, infra, and any custom tools.
5. Done criteria. Free-text or multiple-choice depending on context. Extract concrete checks the executing model must run before finishing: tests, build, lint, integration suites, manual verification, smoke checks. Names of commands matter; "test thoroughly" does not.

Adaptive deep-dive triggers

Ask additional questions only when an earlier answer signals depth:

• Long-horizon: ask about persistence, context compaction, memory files, what to do when token budget runs low.
• Tool-heavy: ask which tools, when to use them, parallelism rules, what NOT to delegate to tools.
• Subagent-orchestrated: ask what to delegate to subagents and what stays in the main agent.
• User mentions risk or fragility: ask about edge cases, failure modes, rollback rules.
• Migration or refactor: ask about scope boundaries (files or systems that are off-limits, style rules, approval limits).
• User has examples or prior work: gather them as few-shot anchors or required references.
• Multi-system or multi-service: ask which services must be running, in which order, with which credentials.

Cap deep-dives at 3 follow-up questions per branch. Stop interviewing as soon as you have enough to fill every required section of the Prompt Shape (Phase 2).

Interview rules

• In Claude Code, use AskUserQuestion for every multiple-choice question. In Codex, use the text fallback above. Either way, the "Other" free-text path is available to the user.
• Phrase options as fundamentally different approaches, not gradations of the same choice.
• Skip obvious questions. Dig into the hard stuff.
• Do not re-ask anything you can infer from earlier answers.
• After each answer, decide whether the next planned question is still high-yield. If not, stop.
• Header max 12 characters. 2 to 4 options per question. AskUserQuestion supports up to 4 questions per call; the text fallback is one question per turn.

Phase 2: Draft

Once interviewing is complete, pick the target path from the execution environment named in Q2, then draft the prompt using XML blocks.

Pick the target path

Q2 answer	Target	Path
Codex CLI	GPT-5.5	GPT-5.5 / Codex path
Claude Code	Claude Opus 4.7	Opus 4.7 path
Anthropic API directly	Claude Opus 4.7	Opus 4.7 path
Other harness	Ask user which model, then route	per answer

If "Other harness" is selected and the model is not obvious from earlier answers, ask one short follow-up: "Which model will execute this prompt? (Claude Opus 4.7, GPT-5.5, other)". Default to the closer of the two paths if the user names a different OpenAI or Anthropic model in the same family.

Opus 4.7 path

Use Anthropic-style XML sections. Fill each section from interview answers. Drop sections that do not apply.

<role>
You are Claude Opus 4.7 acting as {{role}} in this {{environment}}.
</role>

<mission>
{{concrete outcome the model must deliver}}
</mission>

<context>
- Location: {{repo path / project / system}}
- Branch or revision: {{branch_or_commit}}
- Tech stack: {{stack_named_by_user}}
- Required work items: {{items}}
- Relevant files or docs: {{files_and_docs}}
- Prior findings or spec: {{prior_context}}
</context>

<requirements>
- {{hard constraint 1}}
- {{hard constraint 2}}
- Negative constraints: {{what must not happen}}
</requirements>

<workflow>
1. Read the relevant docs, specs, and code paths first.
2. Confirm the real implementation gaps from the code, not assumptions.
3. {{task-specific steps}}
4. Run the required validations.
5. If a check fails, fix the cause and rerun.
6. Only finish once the done criteria are satisfied or a real external blocker remains.
</workflow>

<tooling>
- {{when to use tools, when not to}}
- After each tool result, reflect on what changed and choose the best next action.
- Run independent checks in parallel when possible.
- Do not stay in reasoning-only mode if action is required.
</tooling>

<validation>
- Required commands: {{exact commands the user named}}
- Required services or environments: {{what must be running, named by user}}
- Rerun the relevant checks after material fixes.
</validation>

<done>
{{stop condition}}: do not finish until the named work items are implemented and the named validations have run successfully. If something cannot be completed, state the exact blocker, the evidence, and what remains.
</done>

<output>
Report:
- what changed
- what validations ran and their outcomes
- any remaining blockers or risks
</output>

Include <tooling> only when tools are part of the task. Include <validation> for every coding prompt. Drop <context> lines that have no answer.

Opus 4.7 rules

Apply these patterns when drafting:

• Be explicit. Opus 4.7 follows instructions more literally than 4.6, especially at lower effort. Do not rely on implied behavior. Say exactly what to do, exactly what not to do, and exactly what counts as done.
• Use high-level reasoning guidance, not brittle algorithms. Prefer "reason carefully, then act" and "reflect on failures and choose the best next action" over hand-written hidden algorithms.
• Push tool use directly when it matters. Opus 4.7 uses fewer tools and fewer subagents by default than 4.6. When execution matters, say "do not stay in reasoning-only mode; take action."
• Recommend the right effort. Use claude-opus-4-7 with thinking: {type: "adaptive"} and output_config.effort: "xhigh" when quality matters. Use "high" for intelligence-sensitive work. Reserve "low" for short, scoped, latency-sensitive tasks.
• Do not recommend thinking: {"type": "enabled", "budget_tokens": N} (removed for Opus 4.7, returns an error). Do not recommend non-default temperature, top_p, or top_k. Do not recommend assistant-message prefill: prefer prompt instructions and structured output configuration.
• Persistence language for long tasks. "Do not stop early due to token budget. If the harness compacts context or supports memory or state files, persist state and continue."
• Require self-checking. Tell the model to verify against the named criteria and rerun checks after material fixes.
• No assumed tech stack. Use what the user named in the interview. If the user did not mention Docker, do not write "Start local Docker services". If the user did not mention Playwright, do not write "Run Playwright". The validation section must reflect their stack, not a default one.

GPT-5.5 / Codex path

Use Codex-style XML blocks (named contracts). Compose only the blocks the task actually needs. Reference: references/openai-gpt-5-5-prompting.md.

Available blocks (pick what the task needs, in roughly this order):

• <task> — concrete job, repo or failure context, expected end state. Always include.
• <default_follow_through_policy> — when to act vs ask. Include when the task expects autonomous progress.
• <completeness_contract> — finish the job, do not stop at first plausible answer. Include for any execution work.
• <tool_persistence_rules> — keep using tools until enough evidence to finish. Include for tool-heavy work.
• <verification_loop> — verify before finalizing, fix and rerun. Include whenever correctness matters.
• <missing_context_gating> — do not guess; retrieve or state unknown. Include when guesses would be costly.
• <grounding_rules> — anchor claims to context or tool output, label inferences. Include for review and research.
• <citation_rules> — back claims with primary sources. Include for research with external sources.
• <action_safety> — keep changes tightly scoped, flag risky actions. Include for any write-capable run.
• <structured_output_contract> — exact response shape. Include when the user specified a report shape.
• <compact_output_contract> — concise prose contract. Include when verbosity matters but no schema applies.
• <dig_deeper_nudge> — second-order checks before finalizing. Include for adversarial review.
• <research_mode> — separate facts, inferences, open questions. Include for exploration tasks.
• <progress_updates> — brief, outcome-based progress for long runs.

Fill each block from interview answers. Use short imperative bullets. Skeleton template:

<task>
You are an autonomous senior engineer working in {{repo_path}} on branch {{branch}}.
Implement the required work items end-to-end and validate them.

Required work items:
- {{item_1}}
- {{item_2}}

Relevant files and docs:
- {{file_or_doc_1}}
- {{file_or_doc_2}}

Tech stack: {{stack_named_by_user}}.
</task>

<default_follow_through_policy>
Default to the most reasonable low-risk interpretation and keep going.
Only stop to ask when a missing detail changes correctness, safety, or an irreversible action.
</default_follow_through_policy>

<completeness_contract>
Persist until the task is fully handled end-to-end within the current turn whenever feasible.
Do not stop at analysis or partial fixes.
Treat the task as incomplete until every required item is covered or explicitly marked [blocked] with evidence.
Before finishing, reconcile every plan item: Done, Blocked, or Cancelled. Never leave items in-progress.
</completeness_contract>

<tool_persistence_rules>
Prefer dedicated tools over raw shell (apply_patch, rg, read_file, list_dir, update_plan).
Parallelize independent reads; sequence dependent ones.
After parallel retrieval, synthesize before the next batch.
Keep using tools until you have enough evidence to finish confidently.
</tool_persistence_rules>

<verification_loop>
Required validations:
- {{command_1}}
- {{command_2}}
- {{service_or_environment_named_by_user}}
Before finalizing, run the required validations.
If a check fails, fix the cause and rerun until green or a real external blocker remains.
</verification_loop>

<missing_context_gating>
Do not guess missing repository facts.
Retrieve with tools, or state exactly what remains unknown.
</missing_context_gating>

<action_safety>
Keep changes tightly scoped to the stated task.
Avoid unrelated refactors, renames, or cleanup unless required for correctness.
Do not run destructive git commands (reset --hard, checkout --) without explicit approval.
No broad try/catch; propagate errors explicitly. No `as any` or type assertions in place of real types.
</action_safety>

<structured_output_contract>
Final report:
1. what changed (per file, one line each)
2. what validations ran and their outcomes
3. residual risks or follow-ups
Keep it compact. Highest-value findings first.
</structured_output_contract>

GPT-5.5 / Codex rules

Apply these patterns when drafting:

• Outcome-first. Describe the destination, not every step. GPT-5.5 picks better paths than micromanaged hidden algorithms.
• Literal instruction following. Replace absolute commands ("ALWAYS X", "NEVER Y") with decision rules ("If X, do Y; otherwise Z") for anything that is a judgment call.
• Recommend reasoning.effort deliberately. Default "medium" for interactive coding. "low" for latency-sensitive work where some thinking still helps. Reserve "high" or "xhigh" for complex agentic tasks where evals show measurable gains. "none" only for fast, no-reasoning paths. Tighten the prompt before raising effort — overthinking is real on GPT-5.5.
• Recommend text.verbosity deliberately. Default "low" for code agents and concise responses. Specify word budgets, section counts, or JSON-only when strictness matters.
• Bias to action. Drop in verbatim where appropriate: "Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes."
• Tool preference (Codex). Prefer dedicated tools (apply_patch, rg, read_file, list_dir, update_plan) over shell. Parallelize independent reads.
• Planning (Codex). For medium-or-larger tasks, instruct the model to maintain a plan via update_plan. Skip planning for trivial tasks. Reconcile every plan item before finishing — Done, Blocked, or Cancelled. Never leave items in-progress.
• Structured outputs. Do not describe schemas in prose. Use the Structured Outputs API for validation. In the prompt, tell the model to "return exactly the requested output shape and nothing else."
• Prompt caching. Place static content first, dynamic content last. Use prompt_cache_key consistently for repeated traffic.
• No assumed tech stack. Use what the user named. If they did not mention Docker, do not write "Start local Docker services". The verification block must reflect their stack, not a default one.

Suggested API or CLI configuration to mention in the deliver phase when targeting GPT-5.5:

• model: "gpt-5.5"
• reasoning.effort: "medium" (use "high" only if evals show measurable gains)
• text.verbosity: "low"
• Use the Responses API for reasoning, tool-calling, and multi-turn workflows.
• For Codex CLI: run with codex exec for non-interactive automated runs (or just codex for an interactive TUI session) and let the harness manage tools and planning.

Phase 3: Deliver

Ask the user how they want the artifact:

• Polished prompt text (paste into a fresh session)
• SPEC.md handoff (write .forge/SPEC.md, then /clear and implement @.forge/SPEC.md)
• Both

Ask using the chosen transport: AskUserQuestion in Claude Code, the numbered text fallback in Codex. Recommend "Both" when the task is non-trivial.

Polished prompt text

Print the XML-tagged prompt as a single fenced code block. Prepend a one-line preamble:

Paste this into a fresh Claude or Codex session. Run /clear first to avoid context drift.

SPEC.md handoff

Write the prompt to .forge/SPEC.md (create the directory if missing). Use a markdown header preamble plus the XML body drafted in Phase 2 — use the Opus 4.7 tag set or the GPT-5.5 / Codex block set, matching the chosen path.

For Opus 4.7:

# SPEC: {{one-line title}}

Generated by /forge on {{ISO date}}. Target: Claude Opus 4.7. Run `implement @.forge/SPEC.md` in a fresh session.

<role>...</role>
<mission>...</mission>
<context>...</context>
<requirements>...</requirements>
<workflow>...</workflow>
<tooling>...</tooling>
<validation>...</validation>
<done>...</done>
<output>...</output>

For GPT-5.5 / Codex:

# SPEC: {{one-line title}}

Generated by /forge on {{ISO date}}. Target: GPT-5.5 (Codex CLI). Run `implement @.forge/SPEC.md` in a fresh session.

<task>...</task>
<default_follow_through_policy>...</default_follow_through_policy>
<completeness_contract>...</completeness_contract>
<tool_persistence_rules>...</tool_persistence_rules>
<verification_loop>...</verification_loop>
<missing_context_gating>...</missing_context_gating>
<action_safety>...</action_safety>
<structured_output_contract>...</structured_output_contract>

After writing the file, tell the user the exact next command:

Run /clear, then in a new prompt: implement @.forge/SPEC.md

Both

Print the polished prompt in chat AND write .forge/SPEC.md. Tell the user both options are available.

Anti-patterns

Avoid these when forging the prompt, regardless of target:

• Vague goals with no acceptance criteria.
• Asking for persistence without naming the validation loop.
• Asking for tool use only indirectly when tool use is actually required.
• Overstuffing the prompt with background that does not change execution.
• Mixing contradictory instructions (e.g., "be extremely proactive" + "only use tools when absolutely necessary") without task-specific guidance.
• Letting the model decide whether validation matters.
• Baking in tech-stack assumptions the user did not name.
• Continuing the interview after you have enough to fill every prompt section.
• Re-asking what the user already answered or what is obvious from the seed.

Target-specific anti-patterns:

• Opus 4.7: recommending thinking: {"type": "enabled", "budget_tokens": N}, non-default temperature/top_p/top_k, or assistant-message prefill.
• GPT-5.5 / Codex: step-by-step micromanagement when the path does not matter, absolute "ALWAYS"/"NEVER" commands for judgment calls, raising reasoning.effort to compensate for a weak prompt, describing schemas in prose instead of using Structured Outputs.

Final check

Before returning a prompt or writing the SPEC, verify:

• Names the exact implementation scope.
• Names the exact validation commands the user provided.
• States whether each named tool or service must be used.
• Tells the model not to stop at analysis.
• Tells the model what counts as done.
• Has no contradictory instructions.
• Uses no tech-stack names the user did not mention.
• Recommends a concrete effort level appropriate to the task and target model.

Target-specific final checks:

• Opus 4.7: uses <role>/<mission>/<context>/<requirements>/<workflow>/<validation>/<done>/<output> structure; recommends claude-opus-4-7 with thinking: {type: "adaptive"} and an explicit output_config.effort ("xhigh", "high", or "low" matched to the task).
• GPT-5.5 / Codex: uses Codex-style XML blocks (<task> plus the contracts the task needs); recommends model: "gpt-5.5" with reasoning.effort and text.verbosity chosen deliberately; replaces absolute commands with decision rules; for Codex runs, mentions update_plan reconciliation before finishing.