--- name: forge description: "Forge an issue, ticket, or PR into a shipped fix: propose a plan, get it approved, then implement, review, and refactor. Use when the user runs /forge or asks to investigate, fix, resolve, triage, or solve one. See Parameters for modifier flags." ---

# Forge

> Forge an issue into a shipped fix: heat it (implement), hammer it (review loop), then temper it (refactor).

## Overview

Turn an issue or ticket reference into a verified, branch-correct, user-approved plan. Then, only after the user confirms (or immediately under `automode`), run the implementation lifecycle.

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: nothing touches the codebase until "yes, implement" (automode = only sanctioned bypass) ```

- **Part 1 — The gate.** The contract; do not weaken it. - **Part 2 — Lifecycle.** Runs autonomously after approval, stopping only at substantive gates (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](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:

| Form | Routes to | Examples | |---|---|---| | bare number, `#N`, `issue N` | **git-host issue** (Step 1b) | `forge 42`, `fix #123`, `issue 7` | | matches `[A-Z]+-\d+` | **Jira ticket** OR **Linear issue** (disambiguate if both configured — see [references/trackers/linear.md](references/trackers/linear.md)) | `forge PROJ-123`, `solve ENG-42`, `forge AB12-9` | | after `ticket` keyword | **Jira ticket**; number-only → ask project key | `forge ticket PROJ-123`, `solve ticket 42` | | after `linear` keyword | **Linear issue** (forces Linear routing, skips disambiguation) | `forge linear ENG-42` | | after `pr` keyword | **PR-review entry mode** (skips Steps 4–7; enters at Step 8 against the PR diff) | `forge pr 47`, `forge pr #123` | | after `plan` keyword | **plan-entry mode** (replaces Steps 1, 2, 4–6 with a single Step P validation pass; Step 3 still runs; enters at Step 7 against the plan slice) | `forge plan docs/superpowers/plans/x.md#task-3` |

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](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](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](references/modes/tdd.md). - `worktree` — Step 3 creates a sibling worktree instead of switching branch in place. See [references/modes/worktree.md](references/modes/worktree.md). - `lookup` — Step 4 fetches current docs for every library the issue names. See [references/modes/lookup.md](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](references/modes/secure.md). - `changelog` — Step 12 drafts a changelog entry in the repo's existing format. See [references/modes/changelog.md](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](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](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](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](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](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](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](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`):

| Host in remote URL | Reference | |---|---| | `github.com` / GH Enterprise | [references/trackers/github.md](references/trackers/github.md) | | `gitlab.*` (incl. self-hosted) | [references/trackers/gitlab.md](references/trackers/gitlab.md) | | other (Gitea, Bitbucket, …) | that host's CLI's issue-view JSON command if present; else host REST API | | any, no CLI / auth error | host REST API per the loaded tracker ref (else generic curl) |

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](references/trackers/github.md) Step 2 or [references/trackers/gitlab.md](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

```bash 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>/<