---
name: using-forge
description: "Routes dev tasks into the forge planning workflow. Checks whether brainstorm, writing-plans, executing-plans, or subagent-execution should run before any code is touched."
---

# Using forge

<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill — you already have your instructions.
</SUBAGENT-STOP>

## 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.