Issue Management

Updated on Oct 5, 2026

frg issue drafts, reviews, triages, splits, and publishes a work item in your configured issue tracker, and generates the implementation plan that frg code works from. Use it at the start of a piece of work, before any code is written.

Prerequisites

A valid Telerik license. See Licensing.
A supported coding agent (claude_code, github_copilot, or opencode), installed and authenticated. Check it with frg status.
An issue tracker configured in .forge/config/toolchain.toml. See Toolchain Configuration.
An Issue ID in the current context. Every frg issue subcommand requires one:

bash

export FORGE_ISSUE_ID=123 # current shell only
frg config set-issue 123 # saved in the project context
frg config show-context # verify

Without an Issue ID, Forge stops with Issue ID required for 'issue' operations.

Subcommands at a glance

All local files are written to .forge/work/job_<issue_id>/.

Subcommand	What it does	Typical inputs	Outputs	Default role
`draft`	Creates a local issue draft	The issue in the tracker, optional instructions	`issue/issue.md`	`product_manager`
`review`	Reviews the issue for completeness and quality	`issue/issue.md`	`issue/review.md`	`product_manager`
`publish`	Publishes the local draft to the issue tracker	`issue/issue.md`	Updated issue description in the tracker (no local file)	`product_manager`
`plan`	Generates an implementation plan	`issue/issue.md`	`code/README.md`, `code/research.md`, `code/tasks.md`, `code/phase_x.md` (lite: `README.md`, `tasks.md`, `phase_1.md`)	`software_architect`
`triage`	Evaluates and prioritizes the issue	`issue/issue.md`	`issue/triage.md`	`product_manager`
`split`	Splits a large issue into smaller work items	`issue/issue.md`	`issue/issue_*.md` (for example `issue_a.md`, `issue_b.md`)	`product_manager`
`ask`	Answers a question about the current issue	Question, `issue/issue.md`	`issue/answer.md`	`product_manager`

Typical flow

text

set-issue ──► draft ──► review ──► draft --edit ──► publish ──► plan ──► frg code create
 ▲ │
 └──────────────┘ repeat until the review is clean

Set the issue you are working on:

bash

frg config set-issue 123

Create a local draft, then review it:

bash

frg issue draft
frg issue review

Refine the draft with the findings from review.md:

bash

frg issue draft --edit "Address the gaps listed in review.md"

Publish the description to the issue tracker:

bash

frg issue publish

Generate the implementation plan:

bash

frg issue plan # full plan
frg issue plan --lite # single-phase plan for a small change

Continue with Code Operations (frg code create).

Options shared by all subcommands

Every frg issue subcommand accepts these options. Subcommand sections list only the additional options.

Option	Description	Default
`-a, --agent <NAME>`	Coding agent for this run: `claude_code`, `github_copilot`, or `opencode`.	Agent in `agents.toml`
`-r, --role <ROLE>`	Overrides the default role: `product_manager`, `software_engineer`, `software_architect`, `technical_writer`, `security_analyst`, `sre`. Cannot be combined with `--custom-agent`.	Subcommand default role
`--custom-agent <NAME>`	Selects a custom agent configuration inside your coding agent (for example `python-expert`). Cannot be combined with `--role`.	None
`-m, --model <MODEL>`	Overrides the model configured in `agents.toml`. Valid values depend on the agent.	Model in `agents.toml`
`-c, --context-file <FILE>`	Adds a file path as context. Repeatable.	None
`--context-dir <DIR>`	Adds a directory as context. Repeatable. Up to 100 files per directory and 1 MB per file; binary files and hidden directories are skipped.	None
`--clear`	Clears the existing agent session and starts fresh.	Off
`--retry [<INSTRUCTIONS>]`	Continues the previous session to complete missing outputs, with optional extra instructions. Requires an existing session; cannot be combined with `--clear`.	Off
`--auto-retry`	Retries once automatically when expected outputs are missing. Cannot be combined with `--clear`.	Off
`--print-prompt`	Prints the compiled prompt without running the agent.	Off
`--bypass-safety-checks`	Skips prompt-injection validation. Bypasses are logged. See Prompt Safety.	Off
`-q, --quiet`	Suppresses all output except errors.	Off

To follow agent progress from another terminal, run FORGE_ISSUE_ID=123 frg --tail.

frg issue draft

Creates or refines the local issue description.

text

frg issue draft [OPTIONS]

Option	Description
`--edit [<INSTRUCTIONS>]`	Refines the draft with your instructions, given inline or in `edit.md`.
`--lite`	Writes a lightweight draft with essential details only. Flag only.
`--lite-edit [<INSTRUCTIONS>]`	Lightweight draft with your instructions, given inline or in `lite-edit.md`.

bash

frg issue draft
frg issue draft --lite-edit "Emphasize the security implications"

Output: .forge/work/job_<issue_id>/issue/issue.md. For how instruction files are resolved, see Modifiers.

frg issue review

Reviews the issue for completeness and quality and lists actionable recommendations.

text

frg issue review [OPTIONS]

Option	Description
`--edit [<INSTRUCTIONS>]`	Refines the review with your instructions, given inline or in `edit.md`.
`--lite`	Focused review with actionable items only (gaps, risks, recommendations); excludes positive observations. Flag only.
`--lite-edit [<INSTRUCTIONS>]`	Focused review with your instructions, given inline or in `lite-edit.md`.

bash

frg issue review
frg issue review --lite

Output: .forge/work/job_<issue_id>/issue/review.md.

frg issue publish

Publishes the local draft to the issue tracker. Only the description field is updated; state, labels, and other metadata are left unchanged.

text

frg issue publish [OPTIONS]

No additional options.

bash

frg issue publish

Notes:

publish requires .forge/work/job_<issue_id>/issue/issue.md. If the file does not exist, the agent stops and reports that it cannot find the draft to publish. Run frg issue draft first.
No local output file is written.

issue publish and pr publish transfer the draft body to the tracker by file reference instead of inline text, so the published description matches the local file as authored. This is internal behavior, not a command option.

frg issue plan

Generates an implementation plan that frg code and frg docs operations read.

text

frg issue plan [OPTIONS]

Option	Description
`--edit [<INSTRUCTIONS>]`	Refines the plan with your instructions, given inline or in `edit.md`.
`--lite`	Lightweight plan with core essentials only: single phase, no diagrams. Flag only.
`--lite-edit [<INSTRUCTIONS>]`	Lightweight plan with your instructions, given inline or in `lite-edit.md`.

bash

frg issue plan
frg issue plan --lite-edit "Include database migration steps"

Output in .forge/work/job_<issue_id>/code/:

Plan type	Files
Full	`README.md` (approach), `research.md` (research and decisions), `tasks.md` (task checklist), `phase_x.md` (one file per phase)
Lite	`README.md`, `tasks.md`, `phase_1.md`

Forge detects a lite plan automatically when README.md, tasks.md, and exactly one phase file (phase_1.md) exist.

frg issue triage

Evaluates and prioritizes the issue: severity, urgency, effort, and priority, with justifications.

text

frg issue triage [OPTIONS]

No additional options.

bash

frg issue triage

Output: .forge/work/job_<issue_id>/issue/triage.md.

frg issue split

Splits a large issue into smaller work items.

text

frg issue split [OPTIONS]

No additional options.

bash

frg issue split

Output: one issue_*.md file per work item in .forge/work/job_<issue_id>/issue/, for example issue_a.md and issue_b.md.

frg issue ask

Answers a question about the current issue context.

text

frg issue ask [OPTIONS] [QUESTION]

No additional options.

bash

frg issue ask "What are the acceptance criteria?"
frg issue ask "What dependencies does this have?"

Output: .forge/work/job_<issue_id>/issue/answer.md.

If issue.md is missing, the reading operations can retrieve the issue from the tracker instead. publish never does this.