Code Operations

Updated on Oct 1, 2026

frg code implements, reviews, refactors, documents, builds, and tests code for an issue, working from the implementation plan created by frg issue plan. Use it after the plan exists and before you open a pull request.

Prerequisites

A valid Telerik license. See Licensing.
A supported coding agent, installed and authenticated. Check it with frg status.
An Issue ID in the current context. Without one, Forge stops with Issue ID required for 'code' operations.

bash

frg config set-issue 123 # or: export FORGE_ISSUE_ID=123
frg config show-context

An implementation plan in .forge/work/job_<issue_id>/code/, created with frg issue plan:

Plan type	Files
Full	`README.md`, `research.md`, `tasks.md`, one or more `phase_x.md`
Lite	`README.md`, `tasks.md`, exactly one `phase_1.md`

Forge detects the lite shape automatically and does not require research.md for it.

Subcommands at a glance

Reports are written to .forge/work/job_<issue_id>/code/.

Subcommand	What it does	Typical inputs	Outputs	Default role
`create`	Implements the plan	Plan files	Code changes in the project; progress in `tasks.md`	`software_engineer`
`review`	Reviews code quality against the plan	Plan files, code changes	`review.md`	`software_architect`
`refactor`	Restructures existing code without changing behavior	Plan files, code	Code changes; `refactor_report.md` (`refactor_summary.md` with `--fix`)	`software_engineer`
`document`	Generates code documentation	Plan files, code	Documentation changes in the project	`technical_writer`
`build`	Compiles the project and diagnoses build problems	Plan files	`build_report.md`	`software_architect`
`test`	Runs the test suites and analyzes results	Plan files	`test_report.md`	`software_engineer`
`ask`	Answers a question about the code	Question, plan files	`answer.md`	`software_engineer`

Typical flow

text

issue plan ──► create ──► build ──► test ──► review ──► review --auto-fix <LEVEL> ──► test ──► pr draft
 ▲ │
 └────── create --fix ◄────────┘ (targeted fixes from your own instructions)

Implement the plan:

bash

frg config set-issue 123
frg code create

Build and test:

bash

frg code build
frg code test

Review the change:

bash

frg code review

Fix findings by severity, most severe first:

bash

frg code review --auto-fix critical
frg code review --auto-fix issues

Re-run the tests, then continue with Pull Requests (frg pr draft).

Options shared by all subcommands

Every frg code subcommand accepts these 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. Cannot be combined with `--role`.	None
`-m, --model <MODEL>`	Overrides the model configured in `agents.toml`.	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.	None
`--clear`	Clears the existing agent session and starts fresh.	Off
`--retry [<INSTRUCTIONS>]`	Continues the previous session to complete missing outputs. 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.	Off
`-q, --quiet`	Suppresses all output except errors.	Off

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

frg code create

Implements the issue plan and records task progress in tasks.md.

text

frg code create [OPTIONS]

Option	Description
`--fix [<INSTRUCTIONS>]`	Applies fix instructions during generation, given inline or in `fix.md`.

bash

frg code create
frg code create --fix "Handle the null session case in the auth middleware"

Notes:

If a plan exists but is incomplete (some required files are missing), the operation stops before code generation. Complete the plan with frg issue plan.
Commit instructions are enabled for create and create --fix by default. See Commit Behavior.

frg code review

Reviews the implementation against the plan (requirements, correctness, security, breaking changes, tests) and records findings by severity.

text

frg code review [OPTIONS]

Option	Description
`--edit [<INSTRUCTIONS>]`	Refines the existing review with your instructions, given inline or in `edit.md`.
`--lite`	Focused review of critical issues only (bugs, security, breaking changes). Reduces token usage by 30–50%. Flag only.
`--lite-edit [<INSTRUCTIONS>]`	Focused review with your instructions, given inline or in `lite-edit.md`.
`--auto-fix <LEVEL>`	Fixes findings from the existing `review.md` by severity. Values: `issues`, `critical`, `major`, `minor`, `suggestions`, `all`.

bash

frg code review
frg code review --edit "Focus on security issues"
frg code review --auto-fix major

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

Auto-fix severity levels

--auto-fix does not run a new review. It reads the findings in review.md, keeps only the severities selected by <LEVEL>, and has the agent fix those.

text

frg code review ──► review.md ──► frg code review --auto-fix <LEVEL>
 │
 ├─ Forge writes fix.md (the selected severity scope)
 └─ agent fixes only findings in scope ──► tasks.md updated ──► commit

Which findings each level fixes:

`<LEVEL>`	Critical	Major	Minor	Suggestions
`critical`	Yes
`major`	Yes	Yes
`minor`	Yes	Yes	Yes
`issues`	Yes	Yes	Yes
`suggestions`				Yes
`all`	Yes	Yes	Yes	Yes

issues and minor select the same severities. suggestions fixes only suggestions, never issues.

To reduce risk, fix in steps and test between them:

bash

frg code review --auto-fix critical
frg code test
frg code review --auto-fix issues
frg code test
frg code review --auto-fix suggestions

Notes:

Run frg code review first. Without a review, Forge stops with The --auto-fix option requires an existing code review. If review.md is empty, Forge asks you to run frg code review to generate content.
Forge generates fix.md from the selected level. You do not write it for --auto-fix.
The generated instructions tell the agent to make minimal, targeted changes, run tests, and commit using the project's commit patterns.
frg pr review has no --auto-fix option; severity-based auto-fix is available only on frg code review.

frg code refactor

Improves structure, maintainability, or performance while preserving external behavior.

text

frg code refactor [OPTIONS]

Option	Description
`--fix [<INSTRUCTIONS>]`	Applies refactoring using your instructions, given inline or in `fix.md`.

bash

frg code refactor
frg code refactor --fix "Extract the retry logic into a shared helper"

Outputs in .forge/work/job_<issue_id>/code/: refactor_report.md, or refactor_summary.md with --fix. The refactoring itself is applied to the project files.

frg code document

Creates or updates documentation for code, APIs, or technical components in the project.

text

frg code document [OPTIONS]

Option	Description
`--edit [<INSTRUCTIONS>]`	Refines the documentation with your instructions, given inline or in `edit.md`.

bash

frg code document
frg code document --edit "Add usage examples to the public functions"

For user guides and project documentation, use Documentation Workflows.

frg code build

Compiles the project and writes a diagnostic report of errors, warnings, dependency and configuration problems, and recommendations. It does not fix source code.

text

frg code build [OPTIONS]

No additional options.

bash

frg code build

Output: .forge/work/job_<issue_id>/code/build_report.md (temporary; not committed).

frg code test

Runs the project's test suites and analyzes the results.

text

frg code test [OPTIONS]

No additional options.

bash

frg code test

Output: .forge/work/job_<issue_id>/code/test_report.md. To fix failures, run frg code create --fix with instructions.

frg code ask

Answers a question about the codebase or the planned implementation. It does not change code or the plan.

text

frg code ask [OPTIONS] [QUESTION]

No additional options.

bash

frg code ask "How does the caching layer work?"
frg code ask "Where should I add logging?"

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