using-forge

Using forge

If you were dispatched as a subagent to execute a specific task, skip this skill — you already have your instructions.

The rule

For any task that will touch code, check the forge skills BEFORE responding or editing. The default instinct is to read files and start typing. That's the mistake this skill exists to prevent.

If there's even a 1% chance that one of these applies, invoke it:

• brainstorm — user explicitly asks to brainstorm, grill, challenge, stress-test, compare approaches, or clarify domain language before planning. Do not infer this from vague tasks.
• writing-plans — user describes a feature, bugfix, refactor, or multi-step change. Before any code. Triggers on phrases like "add", "build", "fix", "refactor", "implement", a Linear reference (ENG-123), or any task that isn't a pure one-liner question. Excludes explicit brainstorm requests.
• executing-plans — a plan file already exists (.forge/plan/*.md) and the user wants it executed in this session.
• subagent-execution — same as above but the user picked the subagent-driven mode, or wants the main chat kept light.

brainstorm is available on demand when the user explicitly asks for it. Do not auto-route vague tasks to it; keep the default flow light.

If none apply, proceed normally.

Chain

The skills chain themselves — you don't orchestrate:

writing-plans ─┬─▶ executing-plans         (user picks [1] in-session)
               └─▶ subagent-execution      (user picks [2] subagent-driven)

writing-plans ends by asking the user which mode. executing-plans and subagent-execution end by offering to run the test-runner agent. That's the whole default flow.

Platform tool glossary

Forge skills use canonical Claude-style tool names. Translate those names to the current agent platform at runtime.

Forge canonical term	Claude Code	OpenCode	Codex
Agent	Agent	Task	multi_agent_v1.spawn_agent
Skill	Skill	skill	read/apply the listed SKILL.md from available skills
TodoWrite	TodoWrite	todowrite	functions.update_plan
Read	Read	read	shell read commands (sed, rg)
Write	Write	write	apply_patch for files
Edit	Edit	edit or apply_patch	apply_patch
Bash	Bash	bash	functions.exec_command
Glob	Glob	glob	rg --files / find
Grep	Grep	grep	rg
WebFetch	WebFetch	webfetch	web.run only when browsing is allowed/required
AskUserQuestion	AskUserQuestion	question	plain-text user question

Downstream Forge skills should use the Forge canonical term. Do not repeat per-platform tool mappings unless a platform has materially different behavior that changes the instruction.

Red flags — STOP if you think any of these

Thought	Reality
"This is a small change, I'll skip planning"	Small changes become big. Invoke writing-plans — a 3-step plan is cheap and the user can say "skip it, just do X" after seeing it.
"Let me read the files first to see what's needed"	That's what codebase-explorer does inside writing-plans. Check the skill first.
"I'll just fix the typo / rename / one-liner"	Truly trivial edits (typo, comment fix, single-line rename) can skip. Anything with logic or > 1 file: invoke writing-plans.
"The user already has a plan in context, I'll just implement"	Exactly — that's why executing-plans or subagent-execution exists. Pick one.
"I can do this faster manually than by dispatching"	Maybe, but you lose the on-disk plan + todo discipline. Use the skill.

User instructions override

If the user explicitly says "skip planning, just do X" or "don't use subagents" or similar, obey. Skills are the default; user intent wins.

Announce before acting

When you invoke another Forge skill, use that skill's own Announce at start line. No preamble, no explanation. One line, then run.