radimsem/forge-skills/forge

Forge

Plan an issue, implement the approved fix, review it, and verify the result.

Overview

Read the issue or ticket, check the branch and relevant code, and present a plan for approval. After approval, implement and verify the fix. automode skips the approval gate.

One numbered workflow (Steps 1–12), split by a single gate:

Part 1 — Gate (Steps 1–6):   classify → fetch → branch → context → propose → [GATE] approve
Part 2 — Lifecycle (7–12):   implement → review-loop → refactor → spin-off → self-evolve → close
 
  gate held: no implementation edits until "yes, implement" (except under automode)

• Part 1: The gate. Show one proposal and wait for approval, except under automode. With docs, Step 5 writes the proposal to CONTEXT.md before approval.
• Part 2: Implementation. Run after approval and pause only at the decisions listed in the Autonomy section.

"The agent" means whatever agent runs this skill. Adapt every reference (config directory, agent guide, interview UI) to your runtime. Nothing is hardcoded to one assistant.

Parameters

Parse the invocation as /forge <ref> [automode] [docs] [tdd] [worktree] [lookup] [secure] [changelog] [ci-watch] [compress] [implement] [codex | codex challenge | codex impl [challenge]] [coderabbit] [code-review], or /forge pr <N> [...], or /forge plan <path>[#<slug>] [...]. The words can appear anywhere in the request. A <ref> resolves to a git-host issue or a Jira ticket per the grammar below, and the pr <N> form selects PR-review entry mode. Flags are orthogonal and compose freely; some modes have their own allowed or ignored flags, listed in references/modes/pr-entry.md for PR mode.

Full flag matrix (effects, composition rules, conflicts): [references/flags.md](references/flags.md).

Target grammar: <ref>

The target is the first reference-shaped token, or the token right after a ticket or pr keyword. Routing works by keyword or by key-shape:

A bare number routes to a tracker only if ticket or linear precedes it, and PR mode requires the pr keyword. A key-shaped ref is either Jira or Linear: when both trackers are configured, the agent disambiguates per the Jira/Linear disambiguation section in references/trackers/linear.md. Single-tracker setups skip the prompt.

Read [references/modes/pr-entry.md](references/modes/pr-entry.md) for the PR-entry mode step modifications, the allowed and ignored flags, and the PR-specific Step 12 closing menu.

Read [references/modes/plan-entry.md](references/modes/plan-entry.md) for the plan-entry step modifications and slice addressing.

Modifier flags

Each line says what the flag does and where it acts; the linked file owns the details.

• (none): interview the user if a required field is missing, propose, then wait at the gate. The review uses the project reviewer agents plus superpowers:requesting-code-review.
• automode, runs with no user gates and the agent decides Steps 6, 9, and 11. It never auto-commits, auto-pushes, or writes back to Jira; that is a hard floor. See references/autonomy.md.
• docs, works from documentation: the proposal goes to CONTEXT.md and the plan is sourced from it, and grilling uses /grill-with-docs instead of /grill-me.
• tdd. Step 7 writes the failing test first, observes it fail, then implements. See references/modes/tdd.md.
• worktree. Step 3 creates a sibling worktree instead of switching branch in place. See references/modes/worktree.md.
• lookup. Step 4 fetches current docs for every library the issue names. See references/modes/lookup.md.
• secure, adds a security-review pass at Step 8 once the regular review converges, before Step 9. See references/modes/secure.md.
• changelog. Step 12 drafts a changelog entry in the repo's existing format. See references/modes/changelog.md.
• ci-watch, after a Step 12 push, polls CI; a red result reopens Step 8. See references/modes/ci-watch.md.
• compress: sources a token-saving output skill for the whole session before Step 1: ponytail if installed, else caveman; if neither is installed, the flag is ignored with a one-line note. See references/modes/compress.md.
• implement, delegates Step 7 implementation to /implement, scoped to the approved Step 5 plan; its built-in /code-review closeout is skipped because forge's Step 8 owns review. Conflicts with codex impl (two engines for one step, stop and report); makes tdd redundant (accepted with a one-line note, since /implement drives /tdd itself). See references/modes/implement.md.
• codex / codex challenge, adds Codex as a Step 8 generic reviewer; challenge runs an adversarial review instead. Claude Code only. See references/reviewers/codex.md.
• codex impl. Codex (GPT-5.6, auto-tiered Sol/Terra/Luna) implements at Step 7 and handles Step 8b rework; the Step 8 generic reviewer reverts to the default for cross-model review, and challenge composes as an extra adversarial engine. Claude Code only. See references/modes/codex-impl.md.
• coderabbit, adds CodeRabbit as a Step 8 generic reviewer, with rework handled by coderabbit:autofix. Claude Code only; composes with codex (both run, rework routes per finding). See references/reviewers/coderabbit.md.
• code-review, adds /code-review (two-axis: Standards + Spec) as a Step 8 generic reviewer. A plain skill, so unlike codex and coderabbit it runs on any runtime. See references/reviewers/code-review.md.

The reviewer flags add to the generic-reviewer set; the project reviewer agents always run alongside, and codex, coderabbit, and code-review can all be set in one run. For example, forge ticket PROJ-7 automode docs codex challenge coderabbit is a valid invocation.

• automode with docs writes CONTEXT.md directly with no interview, then goes straight to Step 7.
• On a non-Claude-Code runtime, codex, codex challenge, codex impl, and coderabbit are ignored with a one-line warning, and the generic reviewer stays superpowers:requesting-code-review.

When to Use

• /forge <ref> (arg = issue or Jira-ticket ref).
• "forge issue 42", "solve issue 42", "fix #123", "look at issue 7".
• "solve ticket PROJ-123", "forge ticket 42", or a bare Jira key PROJ-123.
• Asks the agent to act on a specific issue/ticket in the repo.

Don't use when:

• No issue or ticket ref is given. Ask rather than guess.
• Asking about an issue/ticket, not to resolve it.

Step 1: Classify the ref, resolve the repo & tracker

Step 1a: Classify <ref> (see Parameters, Target grammar)

• If the ref is key-shaped ([A-Z][A-Z0-9]+-\d+) or follows a ticket keyword, treat it as Jira and go to Step 1c.
• Otherwise (a bare number, #N, or issue N), treat it as a git-host issue and go to Step 1b.
• If ticket is followed by a number with no key, ask for the project key first. Offer proposed answers when candidates can be inferred from git remote, CONTEXT.md, or branch names; otherwise use a single prompt. Under automode, infer the most likely key and record the assumption.

Always run git remote get-url origin (falling back to upstream) regardless of the ref kind, because Part 2 commits and branches against this repo even for Jira tickets.

Step 1b: git-host issue

Route by host in origin (fallback upstream):

If neither origin nor upstream resolves to a known issue host: stop, tell the user, do nothing else.

Step 1c: Jira ticket

Read [references/trackers/jira.md](references/trackers/jira.md), which covers resolving the ticket, fetching it, the absent-source fallback, the key-in-branch convention, and write-back. Load it now; the rest of Steps 1 through 3 and Step 12 defer their Jira specifics to it. Git-host issues never read it.

Step 2: Fetch the issue / ticket

git-host issue

Use the loaded tracker ref for the fetch command and the REST fallback: references/trackers/github.md Step 2 or references/trackers/gitlab.md Step 2. For a host without a dedicated ref, run its CLI's issue-view JSON command if one exists, otherwise curl the host's REST API. Either way, read the body and every comment. If the number is a pull request, not an issue, stop and ask whether they meant /forge pr <N>.

Jira ticket

Follow [references/trackers/jira.md](references/trackers/jira.md) Step 2 to pull the fields and comments, and its Jira-absent fallback section when the source is unreachable. The fallback warns the user and offers three choices (paste, authenticate, or abort), and it stops even under automode.

Step 3: Verify the branch

git branch --show-current

If the repo ships a git or contribution guide, follow it verbatim for branch naming, the base branch, and the PR target. Look in CONTRIBUTING.md, a git section in the project agent guide (AGENTS.md or your runtime's equivalent), .agents/rules/git*, docs/*git*, or the runtime equivalent. The repo's own rules win over everything below.

Only if no such guide exists, fall back to the default <prefix>/<slug>, where <prefix> is one of feat, fix, chore, docs, refactor, test, perf, ci, build, or style.

• Pick <prefix> from the issue: use fix for a bug, feat for new behavior, docs for documentation, and chore for dependencies, CI, or tooling. When it is ambiguous, ask.
• Build <slug> from the title: lowercase ASCII kebab-case, drop stop-words, and keep it to 50 characters or fewer. For example, "Parser fails on UTF-16 BOM" becomes fix/parser-fails-utf-16-bom.

For Jira, see [references/trackers/jira.md](references/trackers/jira.md) Step 3 for the key-in-branch and key-in-commit conventions. The repo guide still wins; otherwise the branch is <prefix>/<KEY>-<slug>, and the key is not forced into commit subjects.