# Forge — `changelog` flag

At Step 12, drafts a changelog entry per the repo's existing convention and includes it in the proposed commit list. The entry covers what the implementation diff actually shipped — not the original issue text — so the changelog reflects the merged code.

## Manual verification recipe

```
/forge issue 42 changelog
```

Expected: Steps 1–11 run unchanged. Step 12 (after `/goal` verifies green) inspects the repo for an existing changelog file. If found, forge drafts a new entry matching the file's existing format and adds it to the proposed commit list. If no changelog file exists, forge surfaces this once with a one-line note ("No changelog file detected; skipping `changelog`.") and proceeds.

## When it fires

Step 12, after the `/goal` verification gate passes and before the closing menu is offered. The draft entry is part of the proposed commit list, not a separate commit.

## What it composes

No external skill. Internal logic only: locate the changelog file, parse its format, draft the entry. Read the file's last 3–5 entries to mirror tone, granularity, and section headers (Keep-a-Changelog, project-specific, conventional commits, etc.).

## Locating the changelog file

Check in order, stop at the first hit:

| Path / pattern | Notes |
|---|---|
| `CHANGELOG.md`, `CHANGELOG`, `HISTORY.md` | The conventional top-level locations |
| `docs/CHANGELOG.md`, `docs/changelog/` | Docs-prefixed variants |
| `.changeset/` directory | Changesets convention (one file per change) |
| `changie.yaml` + `.changes/` | Changie tool |
| Any file the repo guide names | Repo-specific config wins |

Repo guide (`CONTRIBUTING.md` / agent guide / etc.) wins over this list.

## Behavior change vs default

| Stage | Default | With `changelog` |
|---|---|---|
| Step 12 commit-list assembly | Code changes only | Code changes **+** one new changelog entry matching repo format |
| Entry placement | (n/a) | Top of the changelog file (Keep-a-Changelog convention) OR a new file in the changesets directory if applicable |
| Entry wording | (n/a) | Imperative summary of what the diff did, not what the issue asked. Length matches the file's existing entries. |
| Closing menu | Closing menu as usual | Same menu; option 2 (push + PR) includes the changelog entry in the PR body summary |

## Composition with other flags

| Combination | Effect |
|---|---|
| `changelog` + `automode` | Entry is drafted without prompt. The commit list at Step 12 emits the proposed history as a plan (per `automode` Step 12 behavior); the changelog entry is included in that plan. |
| `changelog` + `docs` | Entry is included in the `/tmp/forge-<ref>.md` Step 12 plan output. |
| `changelog` + `secure` | Security-fix entries should follow the repo's security-disclosure convention if one exists (look for SECURITY.md). If unclear, surface the security finding's nature in the entry and let the user adjust. |
| `changelog` + `ci-watch` | Entry lands in the proposed commits regardless of CI outcome. If CI goes red post-push, the user can pull the entry from the commit. |

# Forge — `ci-watch` flag

After Step 12 pushes the branch, polls the repo's CI for the pushed commit's status. On red, re-enters Step 8 with the CI failure as a finding so the loop can fix it. On green, reports the result and exits cleanly.

## Manual verification recipe

```
/forge issue 42 ci-watch
```
Then at the Step 12 closing menu, pick option 2 (push + PR) or option 3 (push + PR + Jira write-back).

Expected: after the push completes, forge polls the CI status for the pushed HEAD. On green, prints a one-line "CI green for `<sha>`" and exits. On red, re-enters Step 8 with the CI output as a must-fix finding; the loop applies the fix, pushes again, re-polls.

## When it fires

After Step 12 closing-menu actions complete the push. The polling only happens for menu options that actually push (2 and 3). Options 1, 4, 5, 6 silently skip `ci-watch` — polling without a published target is pointless.

If the push is rejected (non-fast-forward, auth), surface the error and stop. Do not force-push, and do not poll a HEAD that never landed.

## What it composes

No external skill. Uses the repo's host CLI for status checks:

| Host | Command |
|---|---|
| GitHub | `gh run list --branch <branch> --limit 5 --json status,conclusion,headSha,url` (poll until `status: completed`); then `gh run view <id>` for failure logs |
| GitLab | `glab ci status --branch <branch>` |
| Other | Host's status API or CI-provider CLI; if neither available, surface this once and skip |

If no CLI matches and no API path works, surface "ci-watch: no compatible CI surface detected" and exit cleanly (not a failure).

## Polling cadence

Initial wait: 30 seconds (give CI time to start). Then poll every 60 seconds. Cap at 30 minutes total wall-clock; past that, surface "ci-watch: timed out at <duration>, status still <pending|in_progress>" and exit. The user can re-check manually.

Confirm a run exists for the pushed SHA before reading status; "no run found" is not green. If none appears, keep polling to the cap, then surface that no run showed up for `<sha>`.

## Behavior change vs default

| Stage | Default | With `ci-watch` |
|---|---|---|
| Step 12 menu option 1, 4, 5, 6 | Execute as chosen | Same; `ci-watch` silently skips (no push to poll) |
| Step 12 menu option 2 or 3 | Push, open PR, exit | Push, open PR, poll CI; on green report and exit; on red re-enter Step 8 |
| Step 8 re-entry from CI red | (n/a) | Treat CI failure as a single must-fix finding; the regular pass cap applies to the re-loop |

## Composition with other flags

| Combination | Effect |
|---|---|
| `ci-watch` + `automode` | At Step 12, `automode` skips the closing menu and emits a plan only (no push). With no push, `ci-watch` has nothing to poll — silently skips. Combination is valid but functionally inert under `automode`. |
| `ci-watch` + `secure` | If CI fails on a security check, the failure re-enters Step 8 as a regular must-fix; `secure`'s dedicated post-pass runs again after the regular loop reconverges. |
| `ci-watch` + `changelog` | Changelog entry was drafted before the push; if CI fails, the entry is already in the pushed commits. After re-fix, decide whether to update the entry — usually yes if the fix is non-trivial. |

# Forge — `codex impl` flag

Loaded on demand by SKILL.md Step 7 **only when the `codex impl` flag is set**. Delegates implementation to Codex running the GPT-5.6 model family (Sol / Terra / Luna), auto-tiered by work class. The agent stays the orchestrator: it sets `/goal`, delegates, checks the returned diff for plan conformance, and runs the Step 8 review loop — GPT writes, the agent reviews.

**Claude Code only** — same constraint as the `codex` reviewer flag ([../reviewers/codex.md](../reviewers/codex.md)). Non-CC runtime: ignore the flag, warn once, implement inline. The rest of forge stays runtime-generic.

## Manual verification recipe

```
/forge issue 42 codex impl
```

Expected: Steps 1–6 unchanged. Step 7 opens with the standard ordering (`/goal` set, `/karpathy-guidelines` re-source), resolves the companion script, delegates the approved plan as one foreground `task --write` at the Sol tier, conformance-checks the returned diff, and enters Step 8 with the **default** generic reviewer (`superpowers:requesting-code-review`). Step 8b rework routes back to Codex at the Terra or Luna tier.

## Grammar & review split

- `codex` — reviewer only, unchanged ([../reviewers/codex.md](../reviewers/codex.md)).
- `codex impl` — Codex implements Step 7 and handles Step 8b rework. The Step 8 generic reviewer **reverts to the default** `superpowers:requesting-code-review`: the model family that wrote the diff must never be the only one reviewing it (cross-model review). Project reviewer agents always run, as everywhere.
- `codex impl challenge` — composes: implementation as above **plus** Codex `adversarial-review` added to the Step 8 reviewer set alongside the default reviewer. Self-review is acceptable here because it is an *additional* adversarial engine, never the only reviewer.

## Step 7 — delegated implementation

1. **Opener unchanged.** Set `/goal` and re-source `/karpathy-guidelines` first — delegation never skips the opener. With `tdd`, write and observe the failing test yourself *before* delegating; quote the red test in the delegation prompt as a pass criterion.
2. **Preflight once per run** via `<forge-skill-dir>/scripts/resolve-codex.py`, with the same semantics as the reviewer pass ([../reviewers/codex.md](../reviewers/codex.md) Step 8a). Output `UNAVAILABLE` → degrade gracefully: warn once, implement inline, and treat the rest of the run as if `impl` were not set. Never stall.
3. **Delegate the whole approved plan as one foreground task** with the resolved `<script>`:
   ```bash
   node <script> task --write --model gpt-5.6-sol --effort high "<prompt>"
   ```
   The prompt inlines, in order: (a) the karpathy constraints block — Codex cannot source Claude-side skills, same inlining rule as the Step 8b rescue path; (b) the Step 5 approved proposal verbatim (from `CONTEXT.md` under `docs`, stamp-checked); (c) the `/goal` pass criteria. Foreground, not `--background`: Step 8 needs the diff now.
4. **Conformance check before Step 8.** Diff the returned work against the plan: the files touched match the proposal's file list, nothing is out of scope, no unrelated rewrites. Revert or flag out-of-scope edits. A plan step Codex skipped or fumbled: finish inline if small, re-delegate once if large. Then enter the normal Step 8 loop.
5. **Task failure** (companion errors or returns nothing): implement inline, warn, continue — never stall, never retry more than once.

## Step 8b — tiered rework

When `impl` is set, Codex-delegated rework uses the same direct `task --write` mechanism as Step 7, at the tier the matrix below assigns — not the `codex:codex-rescue` subagent path, which stays the reviewer-only flag's rework route. The Step 8 re-hydrate block still runs before any rework pass, and the existing rule holds: trivial fixes stay inline with the agent and are not delegated at all.

## Tier matrix

Auto-tiered by work class; there is no user-facing tier syntax. Effort compensates the cheaper tiers.

| Work | Tier | `--model` | `--effort` |
|---|---|---|---|
| Step 7 — implement the approved plan | Sol | `gpt-5.6-sol` | `high` |
| Step 8b — substantive rework of a review finding | Terra | `gpt-5.6-terra` | `xhigh` |
| Step 8b — mechanical fix (typo, rename, lockstep edit, format) | Luna | `gpt-5.6-luna` | `xhigh` |

- The Step 8b classification is a judgment call. Luna is for mechanical work that is *voluminous* (many files, repetitive), not merely small — small fixes stay inline.
- If a future companion version adds an `ultra` effort level, Terra upgrades to `--effort ultra`; the mapping above is the ceiling of today's enum (`none…xhigh`).
- **Model-ID resilience:** if Codex rejects the model ID (older CLI, tier unavailable on the account), retry once with no `--model` flag (Codex's default) and note the downgrade. Verify accepted IDs against the live CLI, not this file.

## Degradation ladder

1. Non-Claude-Code runtime → ignore the flag, one-line warning (standard).
2. Preflight `UNAVAILABLE` → warn once; implement the whole run inline.
3. Model ID rejected → retry once without `--model`; note the downgrade.
4. Task fails or returns nothing → implement that unit inline, continue.

Each rung falls back to the agent implementing. Never stall the run on a delegation failure.

## Composition with other flags

| Combination | Effect |
|---|---|
| `codex impl` + `automode` | No special casing. Hard floors untouched: Codex writes to the working tree only; it never commits, pushes, or writes back to a tracker. |
| `codex impl` + `tdd` | The agent writes and observes the red test itself, then delegates; the failing test is a delegation pass criterion. The observe-red discipline stays agent-side and binds under `automode`. |
| `codex impl` + `docs` | The delegation prompt sources the plan from `CONTEXT.md` (stamp-checked) instead of the chat proposal. |
| `codex impl` + `worktree` | Composes transparently; the companion task runs in the worktree directory. |
| `codex impl` + `secure` | Unaffected; the security pass reviews the diff regardless of who wrote it. |
| `codex impl` + `coderabbit` | CodeRabbit joins the Step 8 reviewer set; CodeRabbit findings route to `coderabbit:autofix`, Codex-delegated rework routes to the tiered Step 8b path above. |
| `/forge pr <N>` + `codex impl` | Step 7 delegation is inert (PR mode has no Step 7) with a one-line note; the Step 8b rework tiering still applies, since PR mode enters at Step 8. See [pr-entry.md](pr-entry.md). |

# Forge — `compress` flag

Runs the whole forge session in a token-saving output mode by sourcing a compression skill
before Step 1. The point is to keep a long forge run (proposal, implementation, multi-pass
review) from burning context on verbose prose and over-built code, without changing what the
lifecycle does.

## Manual verification recipe

```
/forge 42 compress
```

Expected: before any Step 1 output, the agent sources `ponytail` (or `caveman` if ponytail is
absent) and announces it in one line. Every subsequent step runs under that mode. After each
re-hydrate `/compact`, the mode is re-sourced. If neither skill is installed, one line notes
the flag is ignored and the run proceeds normally.

## Skill selection

Check the runtime's available-skills list (for Claude Code, the skills offered to the Skill
tool) and pick the **first** match, in this order:

1. **`ponytail`** — preferred. It is the newer and more widely adopted of the two, and it
   compresses the bigger token sink: the code itself (minimal diffs, no unrequested
   abstractions), plus the prose around it. Accept either the bare `ponytail` name or a
   plugin-namespaced form such as `ponytail:ponytail`. Source it at its default intensity
   (`full`); do not pass a level unless the user asked for one.
2. **`caveman`** — fallback. Compresses prose only (~75% on explanation text), leaves code
   untouched.
3. **Neither installed** — the flag is inert. Say so in one line (mirroring how `codex` is
   ignored on non-Claude-Code runtimes) and run a normal session. Never try to install
   either skill or emulate their behavior from memory; an unsourced imitation drifts.

Source exactly one skill, never both. One compression discipline keeps the output shape
predictable; ponytail's own docs suggest pairing with caveman, but that is the user's call to
make explicitly, not this flag's.

## When it fires

At parameter-parse time, before Step 1 produces any output — the savings compound across the
whole session, so sourcing late forfeits most of them. Announce the choice in a single line
("compress: sourcing ponytail") and move on.

### Interaction with the re-hydrate block

The Steps 8/9 re-hydrate block runs `/compact`, which can shed the sourced skill's
persistence along with the stale reviewer transcript. After re-sourcing `/karpathy-guidelines`,
re-source the compression skill chosen at startup. The re-hydrate block becomes:

```
/compact  →  re-source /karpathy-guidelines  →  re-source <compression skill>
```

Keep the startup choice; do not re-run selection (the installed-skill set does not change
mid-session).

## What compression must never eat

The flag compresses style, not contract. These stay complete regardless of mode:

- The Step 5 proposal block — every field of the proposal template, in full.
- Step 4 interview question blocks and their proposed answers.
- The Step 12 `/goal` verification — exact commands and their real output, shown.
- Safety-relevant text: destructive-action confirmations, security findings, the Step 6 gate
  question. (Caveman's own auto-clarity exception already carves these out; the same rule
  binds under ponytail.)
- Code correctness: ponytail's "when NOT to be lazy" list (trust-boundary validation, error
  handling, security, accessibility, anything explicitly requested) binds — and the repo's
  own code standards and reviewer agents always outrank the compression skill. A Step 8
  reviewer finding is never waved off as "ponytail said less code".

If compression and a forge gate ever pull in opposite directions, the gate wins.

## Composition

| Combination | Effect |
|---|---|
| `compress` + `automode` | Orthogonal; both simply apply. The autonomous run's assumption notes and the Step 12 plan-only output stay complete per the list above. |
| `compress` + `docs` | `CONTEXT.md` gets the full proposal template — the file is the plan source for Part 2, so it is contract, not prose. |
| `compress` + `tdd` | Composes; ponytail's one-runnable-check instinct yields to `/tdd`'s explicit red-green discipline, which the user opted into. |
| `compress` + reviewer flags (`codex`, `coderabbit`) | Composes; reviewer subagents run in their own context and are unaffected. Rework prompts stay fully specified. |
| `/forge pr <N>` + `compress` | Applies — it shapes output, not lifecycle, so PR-entry mode honors it (review summaries and comments get terser without dropping findings). |

## Scope

The mode governs this forge session's output. It does not persist beyond the session, and
"stop ponytail" / "stop caveman" / "normal mode" from the user lifts it immediately without
touching the rest of the forge run.

# Forge — `implement` flag

Loaded on demand by SKILL.md Step 7 **only when the `implement` flag is set**. Default runs never read this file.

Delegates Step 7 implementation to **`/implement`** (from `mattpocock/skills`): it builds the work described by a spec or ticket set, driving `/tdd` at pre-agreed seams. Forge keeps everything around it — the gate, the review loop, `/goal` verification — and hands the skill only the step it owns.

## Contract

1. **After the opener.** The Step 7 opener still runs first: `/goal` is set and `/karpathy-guidelines` re-sourced before any delegation, exactly as for inline implementation.
2. **Scope is the approved plan.** Dispatch `/implement` against the Step 5 approved proposal (or the plan slice under `/forge plan`), plus the Step 2 issue/ticket body. It implements that plan — not the spec it might re-derive on its own. Out-of-scope work it proposes is declined and recorded as a Step 10 candidate.
3. **Closeout is suppressed.** `/implement` normally closes with `/code-review` before committing. Both halves of that closeout belong to forge: instruct the dispatched run to skip its own review closeout and to stage nothing — forge's Step 8 owns review, and Step 12 owns the commit proposal. If the `code-review` flag is also set, that same engine runs anyway — at Step 8, under forge's pass discipline, per [../reviewers/code-review.md](../reviewers/code-review.md).
4. **Conformance-check the result.** Before entering Step 8, diff the returned work against the approved plan, exactly as `codex impl` does for a Codex diff. Deviations are findings, not silently accepted improvements.

## Composition

| Combination | Effect |
|---|---|
| `implement` + `codex impl` | **Conflict — stop and report.** Two engines cannot own the same Step 7, and silently applying a precedence would hide which engine actually built the diff. |
| `implement` + `tdd` | Redundant, accepted with a one-line note: `/implement` already drives `/tdd` at pre-agreed seams, so the discipline is not doubled. The observed-red rule binds either way. |
| `implement` + `/forge pr <N>` | Inert — PR mode has no Step 7. One-line note, no error; same rule as `codex impl`. |
| `implement` + `automode` | The delegation runs unprompted. The conformance check is the agent's own, and deviations enter Step 8 as findings without a user prompt. |

## Degradation

If the `/implement` skill is not installed on this runtime, warn once, ignore the flag, and implement inline — the same graceful degradation every optional engine flag follows. Never stall Step 7 on a missing delegate.

## Manual verification recipe

1. In a repo with forge installed, run `/forge <ref> implement` on a small issue and approve the Step 5 proposal.
2. Confirm the Step 7 transcript shows the opener (`/goal` + `/karpathy-guidelines`) **before** the `/implement` dispatch, and that the dispatch names the approved plan as its scope.
3. Confirm no `/code-review` closeout ran inside the delegated work, and that Step 8 review started only after a conformance check against the plan.
4. Run `/forge <ref> implement codex impl` and confirm forge stops at Step 1 reporting the engine conflict instead of dispatching either.
5. Uninstall (or rename) the `implement` skill and re-run: Step 7 must warn once and implement inline.

# Forge — `lookup` flag

Composes the **context7 MCP** at Step 4 so the proposal is grounded in current, fetched library facts instead of training-data recall. When the context7 MCP is not connected, fall back to whatever context7 resources the runtime exposes (e.g. the `ctx7` CLI); if none is available, note the gap as a Risk rather than guessing.

## Manual verification recipe

```
/forge issue 42 lookup
```

Expected: Step 4 (context check) detects the flag. For any library, framework, SDK, CLI tool, or cloud service the issue mentions, forge queries context7 — resolve the library id, then fetch its docs — before writing the Step 5 proposal. Cited facts in the proposal carry "(per <library> docs, fetched <date>)" attribution.

## When it fires

Step 4, after the existing-context inventory and the issue-named-file reads. Library lookups happen before the gap interview, so the proposal can use fresh facts when answering the user's interview gaps.

## What it composes

| Source | Used for | Required? |
|---|---|---|
| context7 MCP | Resolve library names → ids, fetch API references, configuration syntax, migration notes. The canonical doc source for `lookup`. | Preferred when the MCP server is connected |
| context7 resources / `ctx7` CLI | Same coverage when the MCP is not connected | Fallback only; no error if missing — record a Risk instead |

No skill is bundled for this flag: `lookup` rides on the context7 MCP/resources the runtime already provides.

## Behavior change vs default

| Stage | Default | With `lookup` |
|---|---|---|
| Step 4 library mentions | Use training-data recall for library facts | Fetch current docs via context7 for every mentioned library/framework/SDK/CLI/cloud service |
| Step 5 proposal | API references stated from memory | Each library-specific claim attributed: "(per <library> docs, fetched <date>)" |
| Interview gaps about library behavior | Agent guesses or asks user | Agent fetches docs first, then proposes informed answers in the gap interview |

## When the lookup is the wrong tool

Not for refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts. The `lookup` flag adds value only when a proposal hinges on library-version-specific facts. If the issue is "refactor the parser to use the visitor pattern", `lookup` adds nothing — skip it.

## Composition with other flags

| Combination | Effect |
|---|---|
| `lookup` + `automode` | Fetches happen without prompts. If a fetch fails (rate limit, network, MCP absent), the agent records the failure as a Risk in the proposal and continues — does not block under `automode`. |
| `lookup` + `docs` | `CONTEXT.md` includes fetched-doc attributions. The plan in `CONTEXT.md` cites versions, not just library names. |
| `lookup` + `tdd` | Tests are written against the current API surface fetched by `lookup`, not the training-data API (which may be a release behind). |
| `lookup` + `worktree` | Compose freely. |

## Cost reminder

Doc fetches consume tokens. Use `lookup` when the proposal accuracy depends on library-version-specific behavior. Skip when the issue is about your own code. Per-fetch token cost is small; the value compounds when the lookup catches an API change that would otherwise produce a broken proposal.

# Forge — plan-entry mode

Loaded on demand when the invocation is `/forge plan <path>`.

## Manual verification recipe

```
/forge plan docs/superpowers/plans/2026-08-21-auth.md#task-3
```

Expected: Steps 1, 2, 4, 5 and 6 collapse into a single Step P validation pass; Step 3 still resolves the branch; implementation begins at Step 7 with `/goal` derived from the slice's own `Run:`/`Expected:` lines and stated deliverable.

## The not-dispatch-ready fallback

**A slice that fails any Step P check other than anchor resolution is not dispatch-ready. When that happens, fall back to normal forge Part 1 (Steps 4–6: check context, propose, gate) instead of implementing.** Implementing on a check that failed is exactly the failure each check exists to catch; falling back costs one extra interview-and-propose pass, which is cheap next to shipping the wrong thing. The individual failure cases below all resolve to this rule; none of them repeat it.

The one exception is an unresolvable slice anchor (see Slice addressing) — that case stops and asks instead, because Part 1 needs to know *which* task to propose against, and forge cannot guess that.

## Step P — plan validation

Replaces Steps 1, 2, 4, 5 and 6. In order:

1. **Resolve the plan slice and confirm its stamp matches this invocation.** The stamp is whatever ties the plan to what it was written against, checked in this order: a `Spec:` line in the plan file naming the design doc it implements; failing that, a recorded base SHA (a `Base:` line or equivalent); failing both, the plan file's own last commit compared against current `HEAD` for the paths the slice names. On mismatch, warn, name what changed (the stale field or the diverged paths), and fall back per the rule above. Implementing a stale slice — one written against a codebase state that has since moved — is precisely the failure this check exists to prevent; proceeding anyway would silently implement against assumptions that no longer hold.

   **When none of the three stamps can be determined at all** — no `Spec:` line, no `Base:` line, and the plan file itself has no commit yet — this is not a mismatch, it is the *most common* case: the natural workflow is brainstorm → write plan → `/forge plan` in a single session, before the plan file is ever committed. There is nothing to compare, so this is not treated as stale. Fall back to check 2 (path-existence) alone, state the gap in the Step 5 proposal as `freshness unverified: plan not yet committed`, and continue — blocking an uncommitted plan would break the exact workflow this entry verb exists to serve, and an uncommitted plan is almost always one just written, so the risk the stamp check guards against barely applies.
2. **Confirm every path the slice names exists.** On any missing path, warn, name the missing paths, and fall back per the rule above. Do not stop dead — a plan written before a refactor is a normal, recoverable case, and Part 1's interview can re-ground the slice against the current tree.
3. **Resolve the slice anchor and derive `/goal` from the slice's stated pass criteria.** See Slice addressing for anchor resolution. Derive `/goal` from the slice's own `Run:` / `Expected:` lines and its stated deliverable — the structural shape plan files in this repo actually use, not a paraphrase of the task title. If the slice carries neither `Run:`/`Expected:` lines nor a stated deliverable, it is not dispatch-ready: fall back per the rule above to establish pass criteria through the normal Step 4/5 interview. `/goal` itself never degrades once set — it is a hard floor, and Step 12 refuses to assemble a commit until it verifies green, so a vaguely-derived `/goal` is worse than falling back to get a precise one.
4. **Treat the slice as the approved Step 5 proposal.** Only once checks 1–3 have passed (or item 3's automode single-heading exception applied) does the slice's own approval satisfy the gate — Step 6 is not re-run.

Step 3 still runs: branch naming, base selection and the clean-tree check are not optional because a plan exists.

Where the slice links an issue and lacks pass criteria, Step 2's fetch is permitted to fill that gap before falling back — a linked issue with acceptance criteria can make the slice dispatch-ready without a full Part 1 pass.

## Slice addressing

`<path>#<task-heading-slug>` addresses one task within a multi-task plan file. Omit the fragment to address the whole file when the plan describes a single task.

If `<task-heading-slug>` matches no heading in the file, the anchor is unresolvable. This does not fall back to Part 1 — Part 1 still needs to know which task to propose against, and forge cannot guess that from an unresolvable fragment. Instead: stop, list the task headings found in the file, and ask the user which was meant. Under `automode`: if the file contains exactly one task heading, use it and record the assumption in the proposal; otherwise abort and report the mismatch, since guessing among multiple candidates risks implementing the wrong task unattended.

## Behavior change vs default

| Stage | Default forge | `/forge plan <path>` |
|---|---|---|
| Steps 1–2 | Classify `<ref>`, resolve repo/tracker, fetch issue body + comments | Skipped — Step P resolves the plan slice directly, no tracker fetch unless the slice links an issue lacking pass criteria |
| Step 3 | Branch off base, optional in-place switch | Unchanged — still runs; branch naming, base selection and the clean-tree check are not optional |
| Steps 4–6 | Check context sufficiency, propose the solution, gate on user approval | Skipped when the slice is dispatch-ready — Step P confirms stamp, paths and pass criteria and treats the slice's own approval as satisfying the gate. Otherwise Step P falls back to this range unchanged (see The not-dispatch-ready fallback) |
| Step 7 | Implement against the interviewed/proposed plan | Implements against the plan slice; `/goal` is derived from the slice's stated `Run:`/`Expected:` lines and deliverable |
| Step 12 | Closing menu per default forge | Unchanged — closing menu and `/goal` verification run as in default forge |

## Composition with other flags

| Flag | Effect under plan-entry |
|---|---|
| `docs` | Redundant — the plan slice *is* the sourced plan. Accepted with a one-line note; no separate `CONTEXT.md` sourcing occurs. |
| `tdd` | Composes normally — Step 7 still writes and observes the failing test before implementing. |
| `automode` | Unaffected — the gate is already satisfied by the plan's own approval, so `automode` changes nothing about Step P. The one place `automode` does change behavior is the anchor-resolution exception in Slice addressing. |
| `codex impl` | Delegates the plan slice to Codex at Step 7 exactly as it would delegate a chat-approved proposal. |

# Forge — `/forge pr <N>` entry mode

A new top-level entry verb. `/forge pr <N>` enters the lifecycle at Step 8 against an existing pull request's diff instead of starting from an issue. Used when the user wants to review someone else's PR (or their own pre-merge) with the full forge reviewer pipeline.

## Manual verification recipe

```
/forge pr 47
```

Expected: Step 1 resolves PR #47 via the repo's host CLI (`gh pr view`, `glab mr view`, …). Step 2 fetches the PR body, comments, and diff. Step 3 checks out the PR's head ref locally (in-place switch by default, or worktree with the `worktree` flag). Steps 4–7 are **skipped**. Step 8 runs the full review loop against the PR's diff. Steps 9–11 follow as appropriate. Step 12 closing offers PR-review-specific options (leave-comment-only, push-fixup-commits, request changes, approve).

## Grammar

```
/forge pr <N>            # the canonical form
/forge pr #N             # also accepted (the # is decorative)
forge pr 47              # without leading slash, same as above
```

The `pr` keyword between `forge` and the number distinguishes this mode from `/forge <N>` (issue mode). A trailing number without the `pr` keyword still routes to issue mode per the existing grammar.

## When it fires

Step 1 routing detects the `pr` keyword first, before the issue/Jira-key shape match. PR-entry mode replaces Steps 4–7 with PR-context steps.

## Step modifications

| Step | Default forge | `/forge pr <N>` |
|---|---|---|
| Step 1 | Resolve issue/ticket ref via tracker | Resolve PR via host CLI (`gh pr view <N>`, `glab mr view <N>`, …) |
| Step 2 | Fetch issue body + comments | Fetch PR title + body + comments + diff |
| Step 3 | Branch off base, optional in-place switch | Check out the PR's head ref; worktree if `worktree` set |
| Steps 4-7 | Interview, propose, gate, implement | **Skipped** — there is no implementation; the diff already exists |
| Step 8 | Review loop against in-progress implementation | Review loop against the PR's existing diff |
| Step 9 | Refactor opportunities | Refactor opportunities surfaced as PR comments (not direct commits without user approval) |
| Step 10 | Spinoff issues | Same; spinoff items become PR comments or new issues per user choice |
| Step 11 | Self-evolution | Same |
| Step 12 | Closing menu (commit/push/Jira-write-back/etc.) | Closing menu shifts (see below) |

## Step 12 closing menu (PR-review mode)

Different options than issue mode:

```
PR-review done — how should the findings land?
  - Leave the findings as PR comments only, no fixup commits (Recommended)
  - Push fixup commits for the must-fix findings to the PR's head ref + leave comments for the rest
  - Approve the PR (requires zero remaining must-fix from Step 8)
  - Request changes on the PR with the Step 8 finding summary
  - Write the full review (findings + suggested commits) to /tmp/forge-pr-<N>.md and stop
  - Hold — leave the working tree as-is for manual review
```

The `ci-watch` flag is meaningful here too: if the user picked option 2 (push fixup commits), `ci-watch` polls the PR's CI for the new HEAD.

If landing fixup commits requires bringing the PR's head ref up to date with its base and that merge or rebase conflicts, resolve through **`/resolving-merge-conflicts`** — hunk by hunk, by intent traced to each side's primary source, finishing the operation rather than `--abort`ing — instead of resolving ad hoc.

## Allowed and ignored flags

Flags that operate **at Step 8 or later** apply in PR-entry mode:

- `automode` — applies (no user gates)
- `codex` / `codex challenge` — applies (swaps generic reviewer)
- `secure` — applies (post-Step-8 security pass)
- `changelog` — applies (drafts entry for the fixup commits if option 2)
- `ci-watch` — applies (polls CI after option 2 push)
- `coderabbit` — applies
- `code-review` — applies (adds the two-axis skill reviewer; see [../reviewers/code-review.md](../reviewers/code-review.md))
- `codex impl` — partially applies: Step 7 delegation is inert (no Step 7), the Step 8b rework tiering applies; see [codex-impl.md](codex-impl.md)
- `implement` — inert: PR mode has no Step 7. One-line note, no error; see [implement.md](implement.md)
- `compress` — applies (session-wide output mode, sourced before Step 1; see [compress.md](compress.md))

Flags that operate **before Step 8** are ignored with a one-line warning:

- `docs` — no plan to source from
- `tdd` — no implementation step
- `worktree` — actually composes: use worktree for the PR head checkout. Not ignored — see composition table below.
- `lookup` — no proposal to ground

## Composition with other flags

| Combination | Effect |
|---|---|
| `/forge pr <N>` + `automode` | Skip closing menu; emit review summary to `/tmp/forge-pr-<N>.md`; no auto-push of fixup commits. |
| `/forge pr <N>` + `codex challenge` | Codex `adversarial-review` runs against the PR diff; arguably the highest-leverage combination for design critique on a peer PR. |
| `/forge pr <N>` + `secure` | Security pass runs after the regular reviewer loop converges. Must-fix → can be addressed via option 2 fixup commits. |
| `/forge pr <N>` + `worktree` | The PR head checkout happens in a sibling worktree, not in-place. Useful when the user has uncommitted work in the original tree. |
| `/forge pr <N>` + `ci-watch` + option 2 | Push fixup commits, poll the PR's CI; on red, re-enter Step 8 against the now-failing state. |

# Forge — `secure` flag

Composes the `security-review` skill after Step 8 converges (zero actionable findings from the regular reviewers). Security findings re-enter Step 8 as must-fix; the loop reopens until they're addressed.

## Manual verification recipe

```
/forge issue 42 secure
```

Expected: Step 8 runs to convergence as usual. On zero actionable findings, forge composes `security-review` against the same diff. Each finding is classified must-fix or should-fix. Must-fix → loop reopens with the security finding as the new pass-1 input. Zero security findings → proceed to Step 9.

## When it fires

Step 8, after the standard reviewer loop terminates at zero actionable findings, before Step 9 (refactor). The security pass is a separate, post-convergence gate — not a parallel engine within the regular pass.

## What it composes

`security-review` skill. Read that skill's contract for the categories it surfaces (injection, secrets handling, authn/authz, etc.) — the `secure` flag routes one Step 8 post-pass through it.

## Behavior change vs default

| Stage | Default | With `secure` |
|---|---|---|
| Step 8 termination | Zero actionable findings → Step 9 | Zero actionable findings → `security-review` pass → re-evaluate |
| Security must-fix found | (security-review never runs) | Pass cap resets by one (security gets a dedicated pass budget of 1); apply the fix, re-run security-review, advance only on green |
| Security should-fix found | (n/a) | Treated as a should-fix in the regular Step 8 sense: apply if cheap, else surface in the Step 12 proposal Risks section |
| Step 9 entry | After Step 8 zero actionable | After both Step 8 zero actionable AND security-review zero must-fix |

## Where the pass-budget comes from

The Step 8 pass cap (see [review-loop.md](../review-loop.md)) covers regular reviewers. `secure` adds **one dedicated security pass** on top — security findings do not exhaust the regular cap, but a single security pass also does not become a free re-litigation budget. If the security pass surfaces must-fix and the fix in turn triggers regular reviewer findings, those count against the regular cap.

## Composition with other flags

| Combination | Effect |
|---|---|
| `secure` + `automode` | Security pass runs without prompts. Must-fix findings are applied automatically per the regular `automode` Step 8 path (pick safest finding, continue). The pass-budget rule still binds. |
| `secure` + `codex` / `codex challenge` | Codex runs in the regular Step 8 passes; `security-review` runs after Codex converges. The two reviewers have different angles (Codex: correctness/design; security-review: vulnerability classes). Both must converge before Step 9. |
| `secure` + `tdd` | Compose freely. Security findings may require new tests; if so, those tests follow TDD discipline (red first). |
| `secure` + `coderabbit` | Same composition pattern as with `codex`. CodeRabbit handles regular Step 8; security-review handles the security pass. |

# Forge — `tdd` flag

Composes the `/tdd` skill at Step 7. Implementation must follow an observed-red test, not precede it.

## Manual verification recipe

```
/forge issue 42 tdd
```

Expected: Step 6 gate opens normally. Step 7 (implement) opens with the standard ordering (`/goal` set, `/karpathy-guidelines` re-source), then composes the TDD skill, writes the failing test, runs it, surfaces red output, and only then writes implementation code. Step 8 review loop runs as usual against the implementation diff.

## When it fires

Step 7, after `/goal` is set and `/karpathy-guidelines` is sourced, before any implementation edit.

## What it composes

`/tdd`. Read that skill's contract before using `tdd` — this flag does not duplicate the discipline, it routes Step 7 through it.

## Behavior change vs default

| Stage | Default | With `tdd` |
|---|---|---|
| Step 7 first edit | Implementation code per the approved plan | Failing test for the new behavior |
| Pre-implementation observation | None required | Run the test; confirm red output before any implementation edit |
| Implementation | Edit until plan is delivered | Edit until the test passes; stop |
| Step 8 entry | Triggered by completed implementation | Triggered by green test plus implementation |

## Composition with other flags

| Combination | Effect |
|---|---|
| `tdd` + `automode` | Discipline still binds. The agent writes the test, runs it, and confirms red itself before writing implementation. No user prompt; the failing-test observation is the agent's own. |
| `tdd` + `docs` | TDD discipline applies to the `CONTEXT.md`-sourced plan. Tests for each plan section are written first. |
| `tdd` + `codex` / `codex challenge` | Step 8 reviewer engines unchanged. Codex reviews the implementation diff plus the test diff; adversarial review may challenge the test design as well as the implementation. |
| `tdd` + `worktree` | Compose freely. Tests run inside the worktree. |
| `tdd` + `lookup` | Compose freely. Library lookups inform the test, not just the implementation. |

# Forge — `worktree` flag

Composes the `superpowers:using-git-worktrees` skill at Step 3. The branch is created in a sibling worktree directory rather than switched in-place, so your editor can keep the original working tree open while forge works.

## Manual verification recipe

```
/forge issue 42 worktree
```

Expected: Step 3 detects the flag, creates a sibling worktree (e.g. `../<repo>-<slug>/`) on the chosen branch instead of switching in-place. Subsequent edits and commits target that worktree path. Step 12 closing reminds the user to remove the worktree once the changes land or are discarded.

## When it fires

Step 3, after the branch name is resolved (per repo guide or the default `<prefix>/<slug>` fallback) and before the `git switch -c` decision.

## What it composes

`superpowers:using-git-worktrees`. Read that skill for the worktree creation, layout, and cleanup conventions — this flag routes Step 3 through it.

## Behavior change vs default

| Stage | Default | With `worktree` |
|---|---|---|
| Step 3 branch creation | `git switch -c <prefix>/<slug> <base>` in the current tree | `git worktree add <path> -b <prefix>/<slug> <base>` (path per the worktree skill's convention) |
| Edits | Apply to the current working tree | Apply to the worktree directory; the original tree is untouched |
| Step 12 | Commit and (optionally) push from the current branch | Commit and (optionally) push from the worktree; closing menu adds a cleanup reminder |
| Cleanup | Switch back to base branch when done | Run `git worktree remove <path>` (or accept the closing-menu reminder to do so) |

## Composition with other flags

| Combination | Effect |
|---|---|
| `worktree` + `automode` | Worktree is created without prompting. Cleanup at Step 12 stays opt-in even under `automode` — the worktree lives until the user removes it (`automode` never deletes user state). |
| `worktree` + `tdd` | Compose freely. Tests run inside the worktree; the original tree is unaffected by red/green output. |
| `worktree` + `docs` | `CONTEXT.md` is written inside the worktree, not the original tree. |

## Step 12 closing addendum

When `worktree` was set, the Step 12 closing message appends one line:

> Worktree at `<path>` — run `git worktree remove <path>` (or `git worktree prune` if the branch was deleted) when you're done.

This addendum is informational. It does NOT auto-remove the worktree, even under `automode` — losing in-progress state because a flag inferred you were "done" is the wrong default.

# Forge — `/code-review` reviewer reference

Loaded on demand by SKILL.md Step 8 **only when the `code-review` flag is set**. Default (no flag) runs never read this file.

**Any runtime** — unlike `codex` and `coderabbit`, this engine is a plain skill (`code-review` from `mattpocock/skills`), so it carries no Claude-Code-only degradation rule. If the skill is not installed, warn once, fall back to `superpowers:requesting-code-review` for this run, and continue the loop. Never stall.

## Step 8a — Two-axis generic reviewer

`/code-review` reviews the diff since a fixed point along two independent axes, each run as a parallel sub-agent where the runtime has them, sequentially where it does not:

- **Standards** — does the diff follow the repo's coding standards, plus a Fowler smell baseline?
- **Spec** — does the diff faithfully implement the originating issue, ticket, or spec?

Drive it with forge's own context so it does not re-derive what forge already holds:

1. **Fixed point**: the Step 3 base branch (or the worktree's fork point under `worktree`). Pass it explicitly; the skill's "diff since a fixed point" must match the diff Step 8 is reviewing, not the whole branch history.
2. **Originating spec**: the Step 5 approved proposal plus the Step 2 issue/ticket body. The Spec axis is only as good as the spec it is handed — hand it the same artifacts the gate approved.
3. Run the review; treat its findings verbatim as this pass's generic-reviewer findings. Merge with the project reviewer agents' findings; same must-fix/should-fix termination as Step 8.

## Step 8b — Rework

There is no dedicated rework skill for this engine. Findings are fixed in-pass: run the re-hydrate block (`/compact` → re-source `/karpathy-guidelines`), fix, then re-review. If `codex` or `coderabbit` is also set, their findings still route to their own rework paths; only `code-review`-raised findings stay inline.

## Composition and `automode`

| Combination | Effect |
|---|---|
| `code-review` + `codex` / `coderabbit` | All set engines run in the same Step 8 pass; each finding's rework routes to the engine that raised it (in-pass for this one). |
| `code-review` + `codex impl` | Valid — and useful: a non-Codex reviewer over a Codex-written diff satisfies the cross-model-review rule with a second independent axis pair. |
| `automode` | The review runs unprompted; non-convergence follows the regular `automode` Step 8 pick-safest path. The pass cap binds unchanged. |

# Forge — `coderabbit` flag (and `coderabbit:autofix` rework path)

Composes the `coderabbit:code-review` skill as a Step 8 generic reviewer, replacing the default `superpowers:requesting-code-review`. Composes with the `codex` flag — set both and both engines run in the same pass.

The companion `coderabbit:autofix` skill is invoked from Step 8b as the rework delegation path when `coderabbit` is the active reviewer — symmetric to how the `codex` flag uses `codex:codex-rescue` in Step 8b.

## Manual verification recipe

```
/forge issue 42 coderabbit
```

Expected: Step 8 dispatches project reviewer subagents in parallel with `coderabbit:code-review`. Project subagents still run; `coderabbit` adds to the generic-reviewer set. On findings, Step 8 fix-and-rerun cycle applies as usual. If the rework needed is too large for inline application, Step 8b delegates to `coderabbit:autofix` foreground.

## Claude Code only

The CodeRabbit plugin is Claude Code-exclusive. Non-Claude-Code runtimes: forge ignores `coderabbit` with a one-line warning and stays on the default `superpowers:requesting-code-review`. Same degradation pattern as the `codex` flag.

## Composing with `codex`

Both flags add an engine to the Step 8 generic-reviewer set. Set both and both run in the same pass, each contributing findings to the shared pass budget. Step 8b rework routes per finding: codex findings to `codex:codex-rescue`, coderabbit findings to `coderabbit:autofix`. Inline or ambiguous fixes stay agent-discretion.

## Step 8a — Generic CodeRabbit reviewer

Engine selection at Step 8 (when `coderabbit` is set):

| Slot | Engine |
|---|---|
| Project reviewer subagents (`.agents/agents/` matched to diff) | Always run (unchanged by `coderabbit`) |
| Generic reviewer | `coderabbit:code-review` |
| Sub-pass (suspected bug / perf regression) | `/diagnosing-bugs` (unchanged) |
| Fallback (no project reviewers, PR exists) | `/greploop` (unchanged) |

Dispatch the CodeRabbit reviewer in parallel with the project subagents where possible. Collect findings; apply Step 8 termination (zero actionable) and pass-cap rules unchanged.

## Step 8b — Rework delegation (`coderabbit:autofix`)

When Step 8 surfaces findings that require non-trivial implementation work — multiple files, cross-cutting refactors, or a category of fix the regular pass cannot complete inline — delegate the rework to `coderabbit:autofix`, mirroring the existing `codex:codex-rescue` path.

Before delegating, run the re-hydrate block (per the standard pass discipline) and inline the karpathy constraints in the rework prompt. `coderabbit:autofix` runs as a foreground subagent dispatch with `--wait` semantics so the next Step 8 re-review has the rework diff available.

After delegation returns: re-enter Step 8 with the rework diff as a new pass input. Apply the pass cap to subsequent passes. If `coderabbit:autofix` itself fails or returns no usable diff, surface the failure and pause (or pick safest finding under `automode`).

## Behavior change vs default

| Stage | Default | With `coderabbit` |
|---|---|---|
| Step 8 generic reviewer | `superpowers:requesting-code-review` | `coderabbit:code-review` |
| Step 8b rework delegation | (n/a or codex-rescue if `codex` set) | `coderabbit:autofix` |
| Findings format | Per the reviewer's contract | Per CodeRabbit's contract; map severity → must-fix/should-fix/nit per the file in coderabbit:code-review |

## Composition with other flags

| Combination | Effect |
|---|---|
| `coderabbit` + `automode` | Reviewer runs unprompted. Step 8b rework delegates without user confirmation; failures pick safest path. |
| `coderabbit` + `secure` | After CodeRabbit converges, `security-review` runs as the post-Step-8 gate (per the `secure` contract). Both must clear before Step 9. |
| `coderabbit` + project subagents | Project subagents always run; `coderabbit` is the generic-reviewer companion. Both engines contribute findings to the same pass budget. |
| `coderabbit` + `/forge pr <N>` | PR-review mode uses CodeRabbit as the engine for the existing PR's diff. The reviewer's PR-specific features (line comments, summaries) compose naturally. |
| `coderabbit` + `codex` | Both engines run in the same Step 8 pass; rework routes per finding (codex → `codex:codex-rescue`, coderabbit → `coderabbit:autofix`). |

# Forge — Codex reviewer reference

Loaded on demand by SKILL.md Step 8 **only when the `codex` or `codex challenge` flag is set**. Default (no flag) runs never read this file.

**Claude Code only** — the `codex` plugin is CC-exclusive. Non-CC runtime: ignore the flag, warn once, use `superpowers:requesting-code-review`, do not read further. The rest of forge stays runtime-generic.

This file is reviewer-only. Implementation delegation (the `codex impl` flag) is owned by [../modes/codex-impl.md](../modes/codex-impl.md); when `impl` is set, Step 8b rework routes through that file's tiered `task` path instead of the subagent path below.

## Step 8a — Codex generic reviewer

`/codex:review` / `/codex:adversarial-review` are `disable-model-invocation: true` — unreachable via the Skill/command tool inside an autonomous loop. Drive the companion script over Bash:

1. **Resolve + pre-flight** (once/run) via the bundled helper. Run it by its absolute path — `<forge-skill-dir>/scripts/resolve-codex.py`, where `<forge-skill-dir>` is the base directory announced when this skill loaded (the dir containing `SKILL.md`):
   ```bash
   python3 <forge-skill-dir>/scripts/resolve-codex.py
   ```
   It `JSON.parse`s `codex-companion.mjs setup --json` and prints the newest companion's absolute path **iff** `ready && codex.available && auth.loggedIn`; otherwise prints `UNAVAILABLE` and exits non-zero (covers: plugin/node/Codex missing or not authenticated). Capture stdout as `<script>`.
2. Output `UNAVAILABLE` (plugin absent, Codex missing, or unauthenticated) → **degrade gracefully**: warn the Codex reviewer is unavailable, fall back to `superpowers:requesting-code-review` this run, continue the loop. Never stall.
3. **Run foreground/synchronous** (the loop needs findings now) with the resolved `<script>`:
   - `codex` → `node <script> review --wait`
   - `codex challenge` → `node <script> adversarial-review --wait` (challenges approach/design/assumptions). Implies `codex`; **never both passes**.
4. Verbatim Codex output = this pass's generic-reviewer findings; merge with the project reviewer agents' findings; same must-fix/should-fix termination as Step 8.

## Step 8b — Optional: delegate rework to Codex (agent discretion)

Codex-suited findings (mechanical refactors, a self-contained fix Codex itself proposed) → forge **may** hand rework to the `codex:codex-rescue` subagent instead of fixing inline. Judgment call; small fixes stay inline. `automode`: auto-decide — delegate only if net-positive + clearly Codex-suited. If `coderabbit` is also set, this path handles only codex-raised findings; coderabbit findings route to `coderabbit:autofix`.

Delegation **follows the re-hydration**:

1. **Re-hydrate** (`/compact` → re-source `/karpathy-guidelines`) Claude-side first — forge still reviews Codex's returned diff with fresh discipline.
2. Dispatch via the **Agent tool**, `subagent_type: "codex:codex-rescue"` (subagent, *not* a skill — never `Skill(codex:rescue)`; re-enters the command, hangs). Codex is a different runtime, **cannot source the `/karpathy-guidelines` skill** — inline its substance as task-prompt constraints:
   ```
   Constraints (follow strictly before touching code):
   <karpathy-guidelines principles — surgical/minimal changes,
    no overcomplication, surface assumptions, verifiable success criteria>

   Task: <specific rework, scoped to the finding>
   ```
3. **Foreground (`--wait`)** — loop blocks until rework returns, then re-enter Step 8 on the new diff. Background + lifecycle polling (`node <script> status|result|cancel`, or `/codex:status|result|cancel` for the user) only for a rare long rescue.
4. The subagent only *forwards* to Codex; doesn't poll/cancel itself. Returns nothing (Codex failed) → fix inline, continue — never stall the loop on a failed delegation.

# Forge — GitHub issue reference

Loaded on demand by SKILL.md **only when `git remote get-url origin` (fallback `upstream`) host is `github.com` or a GitHub Enterprise hostname**. Other git hosts and Atlassian Jira / Linear never touch this file.

## Step 1b — Fetch source (resolve)

`gh` is the primary CLI.

## Step 2 — Pull the issue

```bash
gh issue view <N> --json number,title,body,state,labels,comments,author,url
```

Read **body + every comment** — latest comments often carry the missing repro / decision.

If `<N>` is a pull request, `gh issue view` says so — stop and ask whether they meant `/forge pr <N>`.

### GitHub-absent fallback

`gh` missing or unauthenticated → host REST API:

```bash
curl -sH "Accept: application/vnd.github+json" \
     ${GITHUB_TOKEN:+-H "Authorization: Bearer $GITHUB_TOKEN"} \
     "https://api.github.com/repos/owner/repo/issues/<N>"   # comments: same URL + "/comments"
```

Unauth REST is rate-limited — say so if you fall back.

# Forge — GitLab issue reference

Loaded on demand by SKILL.md **only when `git remote get-url origin` (fallback `upstream`) host matches `gitlab.*` (including self-hosted)**. Other git hosts and Atlassian Jira / Linear never touch this file.

## Step 1b — Fetch source (resolve)

`glab` is the primary CLI.

## Step 2 — Pull the issue

```bash
glab issue view <N> -F json   # confirm flag via `glab issue view --help`
```

Read **body + every comment** — latest comments often carry the missing repro / decision.

If `<N>` is a merge request, not an issue, stop and ask whether they meant `/forge pr <N>`.

### GitLab-absent fallback

`glab` missing or unauthenticated → host REST API: `GET /projects/:id/issues/:iid` + `/notes`, token in `PRIVATE-TOKEN`. Unauth REST is rate-limited — say so if you fall back.

# Forge — Jira ticket reference

Loaded on demand by SKILL.md **only when `<ref>` resolves to a Jira ticket** (key-shape `[A-Z][A-Z0-9]+-\d+` or the `ticket` keyword — see Parameters → Target grammar). Git-host issues never touch this file.

"The runtime's Jira tool" = whatever Atlassian/Jira MCP read/write tools the runtime advertises. Never hardcode a tool name.

## Step 1c — Fetch source (resolve)

Fetch via the **connected Atlassian/Jira MCP tools** the runtime exposes (issue-fetch + comments; usually a Jira "get issue" tool, often needs a cloud-id from an "accessible resources" tool first). No Jira MCP connected, or auth/permission error → **Jira-absent fallback** below.

## Step 2 — Pull the ticket

Pull via the runtime's Jira read tool: summary, description, issue type, status, priority, labels/components, acceptance-criteria field if present, **and every comment**. Issue type = bug-vs-feature signal for Step 4 table + Step 3 prefix.

Read **body + every comment**. Latest comments often carry the missing repro / decision.

### Jira-absent fallback

No Jira MCP connected, or auth/permission error: **warn explicitly that Jira sourcing is unavailable**, then offer exactly three choices (proposed-answer; `automode` still stops here — it suppresses *gates*, not a missing data source):

```
Warning: Atlassian/Jira MCP not connected (or unauthorized) — can't fetch <ref>.
  - Paste the ticket title + description (+ acceptance criteria) here (Recommended)
  - I'll authenticate the Atlassian MCP, then retry the fetch
  - Abort
```

*Paste* → treat text as issue body, → Step 3. *Authenticate* → run the runtime's Atlassian auth/connect tool, retry Step 1c once. *Abort* → stop, do nothing.

## Step 3 — Key in branch & commits

Repo guide still wins (documented Jira convention / smart-commit / subject-line rule overrides everything). Guide silent → branch `<prefix>/<KEY>-<slug>` (e.g. `fix/PROJ-123-parser-utf16-bom`); commit subjects keep repo style — do **not** force `PROJ-123` into the subject unless the guide asks (breaks e.g. subject-only repos capped at 72 chars). Key always in the Step 5 proposal text regardless.

## Step 12 — Write-back

The Step 12 closing menu shows a Jira write-back option **only when the target was a Jira ticket**:

```
  - Lay down that history, push, open the PR, and comment + transition <KEY> on Jira
```

Jira write-back — **opt-in, never automatic**. On selection: comment on `<KEY>` (branch/PR link + one-line summary), then transition — but first read the ticket's *available* transitions via the runtime's Jira tool and confirm the target state (names are project-specific; ambiguous → ask, proposed-answer). Never invent a transition id. **Never** Jira-write-back on any other menu option, without an explicit pick here, or under `automode`.

# Forge — Linear ticket reference

Loaded on demand by SKILL.md **only when `<ref>` resolves to a Linear issue** (key-shape `[A-Z]+-\d+` after Jira disambiguation, or the `linear` keyword — see Parameters → Target grammar). Git-host issues and Jira tickets never touch this file.

"The runtime's Linear tool" = whatever Linear MCP read/write tools the runtime advertises. Never hardcode a tool name; common surfaces are the Linear MCP server, the `linear` CLI, and the Linear REST/GraphQL API. The skill picks whichever is connected.

## Jira / Linear disambiguation

Both trackers use the same key shape (`[A-Z]+-\d+`). When the user invokes `/forge ENG-42` with both trackers configured, ask which:

```
Warning: Both Jira and Linear are connected, and `ENG-42` matches both key shapes.
  - Linear (issue ENG-42 in <team-name>) (Recommended if Linear is the primary tracker)
  - Jira (project ENG, issue 42)
  - Abort
```

Single-tracker setups skip this prompt — only one match is possible. `automode` cannot answer this question (it interviews the user); under `automode`, attempt Linear first if both are connected, record the assumption in the proposal, abort if Linear lookup 404s.

The `linear` keyword (e.g. `/forge linear ENG-42`) forces Linear routing without the disambiguation prompt. Symmetric to the `ticket` keyword that exists for Jira.

## Step 1 — Fetch source (resolve)

Fetch via the connected Linear MCP tools the runtime exposes (issue-fetch + comments; usually a Linear "get issue" tool, often needs a team-id or workspace-id prefix). No Linear MCP connected, or auth/permission error → **Linear-absent fallback** below.

## Step 2 — Pull the issue

Pull via the runtime's Linear read tool: title, description, state (Triage / Backlog / Todo / In Progress / In Review / Done / Canceled / Duplicate), priority (Urgent / High / Medium / Low / No priority), labels, assignee, estimate, parent issue (if sub-issue), **and every comment**. State + labels = bug-vs-feature signal for Step 4 table + Step 3 prefix.

Read **body + every comment**. Linear's comment surface is heavily used for inline implementation discussion; comments often carry the actual spec.

### Linear-absent fallback

No Linear MCP connected, or auth/permission error: warn explicitly that Linear sourcing is unavailable, then offer the three-choice fallback (proposed-answer; `automode` still stops here — missing data source, not a gate):

```
Warning: Linear MCP not connected (or unauthorized) — can't fetch <ref>.
  - Paste the issue title + description (+ acceptance criteria) here (Recommended)
  - I'll authenticate the Linear MCP, then retry the fetch
  - Abort
```

*Paste* → treat text as issue body, → Step 3. *Authenticate* → run the runtime's Linear auth/connect tool, retry once. *Abort* → stop, do nothing.

## Step 3 — Key in branch & commits

Repo guide still wins (documented Linear convention overrides everything). Guide silent → branch `<prefix>/<KEY>-<slug>` (e.g. `fix/ENG-123-parser-utf16-bom`). Linear has no smart-commit syntax like Jira; the key in the branch name is enough for Linear's GitHub/GitLab integration to auto-link.

Key always in the Step 5 proposal text regardless.

## Step 12 — Write-back

The Step 12 closing menu shows a Linear write-back option **only when the target was a Linear issue**:

```
  - Lay down that history, push, open the PR, and comment + transition <KEY> on Linear
```

Linear write-back — **opt-in, never automatic**. On selection: comment on `<KEY>` (branch/PR link + one-line summary), then transition — but first read the issue's *available* states via the runtime's Linear tool and confirm the target state (workflow states are workspace-specific; ambiguous → ask, proposed-answer). Never invent a state id. **Never** Linear-write-back on any other menu option, without an explicit pick here, or under `automode`.

The closing menu in `references/proposal-template.md` Step 12 keeps a single "comment + transition <KEY>" line; the trailing tracker name (`Jira` or `Linear`) is filled in based on which tracker resolved `<ref>`.