Workflow Commands
Workflow commands use an AI coding agent to do software delivery tasks, such as drafting issues, writing code, and reviewing pull requests. This page explains how they run, the options they share, and the context they need. For every option of every command, see the Command Reference.
Prerequisites
- A configured AI coding agent:
claude_code,github_copilot, oropencode. Check it withfrg status. - For most targets, a job context such as an Issue ID. See Context requirements.
How workflow commands work
Each workflow operation is defined in TOML: the built-in command definitions, plus any customizations in .forge/config/commands.toml. When you run a command such as frg issue draft --edit, Forge:
- Resolves the target (
issue) and operation (draft) in the command registry. - Checks the required context, such as
FORGE_ISSUE_ID. - Validates the required input files for the operation.
- Composes the prompt from the operation's role prompt, its task prompt (or the modifier's task override, such as
issue_draft_edit), project context, any context files, and your modifier instructions. - Runs the agent and writes a trace to the job's
traces/directory. - Checks the expected outputs, then prints a summary and next-step hints.
To see the composed prompt without running the agent, add --print-prompt.
For what Forge displays during steps 3 to 6, see Progress Tracking.
Commands
| Target | Purpose | Operations |
|---|---|---|
issue | Work item planning and management | draft, publish, review, plan, triage, split, ask |
backlog | Strategic planning and backlog management | create, review, rank, ask |
code | Code and build operations | create, review, refactor, document, build, test, ask |
pr | Pull request operations | draft, publish, review, merge, ask |
docs | Project documentation and guides | create, build, ask |
ticket | Customer support ticket investigation and response | triage, respond, ask, correlate |
sec | Security scanning and vulnerability remediation | audit, patch, ask |
ask | Context-free Q&A about the codebase | (none) |
run | Execute arbitrary tasks in the codebase | (none) |
To run the same operations across several repositories, use frg app <target> <operation>. See App commands.
Shared options
All workflow operations accept these options:
| Option | Description |
|---|---|
-a, --agent <NAME> | AI coding agent for this run: claude_code, github_copilot, or opencode |
-r, --role <ROLE> | Override the default AI role: product_manager, software_engineer, software_architect, technical_writer, security_analyst, sre. Can't be used with --custom-agent. |
--custom-agent <NAME> | Custom agent configuration within your AI coding agent, for example python-expert. Can't be used with --role. |
-m, --model <MODEL> | Override the model configured in agents.toml. Run frg status to see available models. |
-c, --context-file <FILE> | Include a file path as context. Repeatable. Relative and absolute paths are supported. |
--context-dir <DIR> | Include a directory as a context source. Repeatable. Max 100 files per directory and 1 MB per file; binary files and hidden directories are skipped. |
--clear | Clear the existing agent session and start fresh |
--retry [<INSTRUCTIONS>] | Continue the previous session with a prompt to complete missing outputs |
--auto-retry | Retry once automatically if output validation fails |
--print-prompt | Display the compiled prompt without executing the agent |
--bypass-safety-checks | Bypass prompt injection safety validation. Use only for input you've verified. |
-q, --quiet | Suppress all output except errors |
Command-specific options
| Option | Available on |
|---|---|
--edit [<INSTRUCTIONS>] | issue draft, issue review, issue plan, backlog create, backlog review, backlog rank, code review, code document, pr draft, pr review, docs create, ticket triage, ticket respond, sec patch |
--lite | issue draft, issue review, issue plan, code review, pr draft, pr review |
--lite-edit [<INSTRUCTIONS>] | issue draft, issue review, issue plan, code review, pr draft, pr review |
--fix [<INSTRUCTIONS>] | code create, code refactor, pr merge |
--auto-fix <LEVEL> | code review. Levels: issues, critical, major, minor, suggestions, all |
--dev | docs build: focus on developer/API audience |
--tail | ask, run: follow agent execution output in real time |
--task-file <FILE> | run: read task instructions from a file |
frg ask takes an optional [QUESTION] argument, and frg run takes an optional [TASK] argument.
For modifier behavior, see Modifiers and Lite Mode Commands.
Examples
# Select the AI coding agent
frg issue draft --agent github_copilot
# Override the AI role
frg code review -r software_engineer
# Include several context files
frg code create -c docs/design.md -c docs/api.md
# Include a directory as context
frg issue plan --context-dir docs/patterns
# Combine options
frg issue plan -a claude_code -r software_architect -c docs/requirements.md
# Ask or run without issue context
frg ask "How does the authentication system work?"
frg run --task-file improvements.mdContext requirements
Most targets act on a specific work item. Set the context with an environment variable or with frg config:
| Target | Required context | Set with |
|---|---|---|
issue, code, docs | Issue ID | export FORGE_ISSUE_ID=<number> or frg config set-issue <number> |
pr | Issue ID; PR ID for operations on an existing pull request | export FORGE_PR_ID=<number> or frg config set-pr <number> |
ticket | Ticket ID | export FORGE_TICKET_ID=<id> or frg config set-ticket <id> |
backlog | None | |
sec | Issue ID | export FORGE_ISSUE_ID=<number> or frg config set-issue <number> |
ask, run | None |
To see the current context and where it comes from, run frg config show-context.
frg ask stores question.md and answer.md in .forge/work/job_<id>/ask/ when an Issue ID is set, in .forge/work/ticket_<id>/ask/ when a Ticket ID is set, and in .forge/work/ask/ otherwise. frg run always uses .forge/work/run/.
Modifiers
Modifiers change how an operation runs without changing what it does. For example, --edit switches frg issue draft to the issue_draft_edit task prompt and adds your instructions. You can use only one modifier per run. For details, see Modifiers.
App commands
frg app <target> <operation> runs an operation across the repositories in application.toml:
- Direct execution (most operations): One agent run with application context. These accept the shared options above.
--liteisn't supported. - Workflow execution (
app issue plan,app code create,app pr draft,app pr publish,app pr review,app pr merge): Runs a workflow in each child repository. These accept--start-from,--bypass-approvals,--dry-run, and, where listed,--edit,--lite-edit, or--fix, but not--clear.
See App Command Validation and Multi-Repository Application Commands.
Troubleshooting
error: unrecognized subcommand 'issues'
Cause: The target or operation name is misspelled. Forge shows a tip: with the closest match.
Solution:
- Use the singular target name, for example
frg issue draft, notfrg issues draft. - List the targets with
frg --help, and the operations for a target withfrg issue --help.
Issue ID required for 'issue' operations
Cause: The command needs a job context that isn't set. The same message appears for code, docs, and pr, and Ticket ID required for 'ticket' operations for ticket.
Solution:
- Set the context:
export FORGE_ISSUE_ID=123
# or
frg config set-issue 123- Run the command again.
Verify: frg config show-context shows the Issue ID.
Workflow commands are blocked after a configuration change
Cause: The repository has a configuration lockfile, .forge/.config_lock, and a configuration file changed after locking.
Solution:
- Validate your configuration:
frg config validate- Fix any reported errors.
- Relock the configuration:
frg config lockThe agent finishes but some outputs are missing
Cause: AI agents are non-deterministic and don't always create every expected file.
Solution:
- Run the same command with
--retryto continue the session and ask for the missing files. - For unattended runs, add
--auto-retry.
See Progress Tracking and Common Issues.