GitHub Workflow Steps

The GitHub plugin exposes public reusable workflow steps through GitHubPlugin.get_steps(). The reference groups them by user-facing functionality so workflow authors can find related building blocks quickly.

For full contract details for every public step, including documented inputs, outputs, and return behavior, see the detailed step reference.

Functional groups

• Pull Requests
• Prompt and Selection
• Issue Creation
• Pull Request Review
• Code Review
• Worktree Support
• Releases

Summary

Step	Group	Used by built-in workflows
create_pr	Pull Requests	create-pr-ai
get_pull_request	Pull Requests	-
merge_pull_request	Pull Requests	-
verify_pull_request_state	Pull Requests	-
ai_suggest_pr_description	Pull Requests	create-pr-ai
prompt_for_pr_title	Prompt and Selection	-
prompt_for_pr_body	Prompt and Selection	-
prompt_for_pr_draft	Prompt and Selection	create-pr-ai
prompt_for_issue_body_step	Prompt and Selection	create-issue-ai
prompt_for_self_assign	Prompt and Selection	create-issue-ai
prompt_for_labels	Prompt and Selection	create-pr-ai
ai_suggest_issue_title_and_body	Issue Creation	create-issue-ai
preview_and_confirm_issue	Issue Creation	-
create_issue	Issue Creation	create-issue-ai
select_pr_for_review	Pull Request Review	respond-pr-comments
fetch_pending_comments	Pull Request Review	respond-pr-comments
check_clean_state	Pull Request Review	respond-pr-comments
checkout_pr_branch	Pull Request Review	respond-pr-comments
review_comments	Pull Request Review	respond-pr-comments
push_commits	Pull Request Review	respond-pr-comments
send_comment_replies	Pull Request Review	respond-pr-comments
request_review	Pull Request Review	respond-pr-comments
checkout_original_branch	Pull Request Review	respond-pr-comments
select_pr_for_code_review	Code Review	-
fetch_pr_review_bundle	Code Review	-
build_change_manifest	Code Review	-
build_existing_comments_index	Code Review	-
write_review_material	Code Review	-
ai_review_findings	Code Review	-
normalize_findings	Code Review	-
dedupe_findings	Code Review	-
build_new_comment_actions	Code Review	-
validate_review_actions	Code Review	-
submit_review_actions	Code Review	-
build_thread_review_candidates	Code Review	-
build_thread_review_contexts	Code Review	-
ai_thread_resolution	Code Review	-
normalize_thread_decisions	Code Review	-
build_thread_actions	Code Review	-
create_worktree	Worktree Support	-
cleanup_worktree	Worktree Support	-
select_release	Releases	-

Pull Requests

Use these steps to generate PR content, inspect PR state, and create or merge pull requests.

• create_pr: create a pull request from workflow context data
• get_pull_request: fetch a pull request and expose it to later steps
• merge_pull_request: merge a pull request with workflow-selected merge options
• verify_pull_request_state: validate that a pull request is in the expected state
• ai_suggest_pr_description: generate PR title and body from branch changes using AI

Prompt and Selection

Use these steps when a workflow needs interactive user input before creation or review work starts.

• prompt_for_pr_title: capture a PR title interactively when one is not already available
• prompt_for_pr_body: capture a PR body interactively when one is not already available
• prompt_for_pr_draft: ask whether the PR should be created as draft
• prompt_for_issue_body_step: capture the raw issue request before AI expansion
• prompt_for_self_assign: ask whether the current user should be assigned to the issue
• prompt_for_labels: prompt for repository labels and save the selection to a configurable context key

Issue Creation

Use these steps to build and submit GitHub issues.

• ai_suggest_issue_title_and_body: generate issue content and suggested labels from user input
• preview_and_confirm_issue: show generated issue content and ask for explicit confirmation
• create_issue: create the final GitHub issue from workflow context data

Pull Request Review

Use these steps for the contributor flow of responding to PR comments and restoring local branch state afterward.

• select_pr_for_review: select a pull request that needs comment response work
• fetch_pending_comments: load unresolved PR comments into workflow context
• check_clean_state: ensure the current branch is safe to leave before checkout
• checkout_pr_branch: switch to the PR branch while preserving original branch context
• review_comments: guide the user through resolving comments and making local changes
• push_commits: push local follow-up commits back to the PR branch
• send_comment_replies: submit replies for the reviewed comments
• request_review: request another review after follow-up work is pushed
• checkout_original_branch: restore the original branch after review work completes

Code Review

These are advanced review-pipeline steps for structured AI-assisted code review. They are public and reusable, but many are intended to be composed together rather than used in isolation.

• select_pr_for_code_review: choose a PR for the advanced code-review pipeline
• fetch_pr_review_bundle: collect PR, diff, file, and discussion context for review
• build_change_manifest: build a structured manifest of changed files and targets
• build_existing_comments_index: index existing review comments to avoid duplicate findings
• write_review_material: write the review material into the worktree (.titan-review/: pr.md with the description and every review comment, pr.diff, per-file diffs, base versions); the review needs the worktree and stops with an error without one
• ai_review_findings: the review — one free-form session of the configured CLI in the worktree, prompted as a user would ask for a review. It may use subagents and read-only git (log, show, diff, blame, grep), does not run tests (CI does), and returns a plain list of findings that the later steps dedupe, anchor and put to you for approval. Ceilings: 30 minutes, and $6 where the CLI enforces a budget (Claude)
• normalize_findings: normalize raw findings into workflow-friendly structures
• dedupe_findings: remove duplicate or overlapping findings before submission
• build_new_comment_actions: translate findings into GitHub review actions
• validate_review_actions: validate those review actions before posting
• submit_review_actions: submit review comments or review actions to GitHub
• build_thread_review_candidates: collect review threads that may need follow-up decisions
• build_thread_review_contexts: expand context needed to evaluate thread resolution
• ai_thread_resolution: ask AI whether open threads should be resolved or reopened
• normalize_thread_decisions: normalize thread resolution decisions for execution
• build_thread_actions: build GitHub actions from normalized thread decisions

Worktree Support

Use these steps when a GitHub workflow should operate in a dedicated worktree.

• create_worktree: create an isolated worktree for GitHub-focused workflow tasks
• cleanup_worktree: remove a worktree created during workflow execution

Releases

Use this step to let a workflow pick a published GitHub release and read its notes.

• select_release: list published GitHub releases and select one to use as a notes source

Detailed Step Contracts

The summaries above show what each github step is for. The sections below show the documented contract for each public step: what it expects from ctx.data, what it saves back, and what result types it may return.

Expand a step to see its workflow usage, required context, inputs, outputs, and result behavior.

How to read these contracts:

• Inputs (from ctx.data) = values the step expects before it runs.
• Outputs (saved to ctx.data) = metadata keys saved for later steps when the step returns Success or Skip.
• Returns = the workflow result type (Success, Skip, Error, Exit), not a separate payload.

Pull Requests

create_pr

Creates a GitHub pull request using data from the workflow context.

Workflow usage

- plugin: github
  step: create_pr

Used by built-in workflows: create-pr-ai

Available to later steps: pr_number, pr_url

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.
ctx.git	-	An initialized GitClient.

Inputs (from ctx.data)

Name	Type	Description
pr_title	str	The title of the pull request.
pr_body	str, optional	The body/description of the pull request.
pr_head_branch	str	The branch with the new changes.
pr_base_branch	str, optional	The branch to merge into. Defaults to the git plugin's configured main branch.
pr_is_draft	bool, optional	Whether to create the PR as a draft. Defaults to False.
pr_reviewers	list, optional	List of GitHub usernames or team slugs to request review from.
pr_excluded_reviewers	list, optional	List of GitHub usernames to exclude from team expansion.
pr_labels	list, optional	List of label names to add to the PR.
auto_assign_prs	bool	If True, automatically assigns the PR to the current GitHub user.

Outputs (saved to ctx.data)

Name	Type	Description
pr_number	int	The number of the created pull request.
pr_url	str	The URL of the created pull request.

Returns

Result	Saved for later steps	Description
Success	pr_number, pr_url	If the PR is created successfully.
Error	-	If any required context arguments are missing or if the API call fails.

get_pull_request

Fetch a pull request and store it in workflow context.

Workflow usage

- plugin: github
  step: get_pull_request

Available to later steps: pr_info

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to fetch.

Outputs (saved to ctx.data)

Name	Type	Description
pr_info	-	The fetched pull request object.

Returns

Result	Saved for later steps	Description
Success	pr_info	If the pull request is fetched successfully.
Error	-	If required context is missing or the GitHub call fails.

check_merge_queue

Check whether the pull request's base branch requires a merge queue.

Workflow usage

- plugin: github
  step: check_merge_queue

Available to later steps: merge_queue_enabled, merge_queue_state

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to inspect.

Outputs (saved to ctx.data)

Name	Type	Description
merge_queue_enabled	bool | None	Whether the base branch requires a merge queue, or None when the lookup failed.
merge_queue_state	-	The merge queue state object, when the lookup succeeded.

Returns

Result	Saved for later steps	Description
Success	merge_queue_enabled, merge_queue_state	When the PR number is available. A failed lookup is not fatal: it reports merge_queue_enabled=None, so the merge falls back to a direct merge and says the queue was never checked.
Error	-	If required context is missing.

merge_pull_request

Merge a pull request, or add it to the base branch's merge queue.

Workflow usage

- plugin: github
  step: merge_pull_request

Available to later steps: merge_result, merge_queued, expected_pr_state

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to merge.
merge_method	str, optional	Merge strategy. Ignored with a merge queue.
commit_title	str, optional	Override commit title. Ignored with a merge queue.
commit_message	str, optional	Override commit message. Ignored with a merge queue.
merge_queue_enabled	bool, optional	Result of a previous check_merge_queue, reused to avoid looking the queue up twice. None means unknown, and the queue is looked up again here.

Outputs (saved to ctx.data)

Name	Type	Description
merge_result	-	The GitHub merge result object.
merge_queued	bool	True when the PR was added to the merge queue.
expected_pr_state	str	"MERGED" after a regular merge, "OPEN" once queued.

Returns

Result	Saved for later steps	Description
Success	merge_result, merge_queued, expected_pr_state	If the pull request is merged or added to the merge queue.
Error	-	If required context is missing or the GitHub call fails.

verify_pull_request_state

Verify a pull request is currently in the expected state.

Workflow usage

- plugin: github
  step: verify_pull_request_state

Available to later steps: verified_pr_info

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to inspect.
expected_state	str	Expected pull request state.

Outputs (saved to ctx.data)

Name	Type	Description
verified_pr_info	-	The pull request object when verification succeeds.

Returns

Result	Saved for later steps	Description
Success	verified_pr_info	If the pull request is in the expected state.
Error	-	If required context is missing, verification fails, or the GitHub call fails.

verify_merge_outcome

Verify the outcome of a merge that may have gone through a merge queue.

Workflow usage

- plugin: github
  step: verify_merge_outcome

Available to later steps: verified_pr_info, merge_queue_state

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
pr_number	int	Pull request number to inspect.
merge_queued	bool	Set by merge_pull_request; True when the PR was added to the merge queue. Required - a missing value is treated as a workflow configuration error.

Outputs (saved to ctx.data)

Name	Type	Description
verified_pr_info	-	The pull request object; saved only on the regular merge path (merge_queued falsy).
merge_queue_state	-	The merge queue state; saved only on the queued merge path (merge_queued truthy).

Returns

Result	Saved for later steps	Description
Success	verified_pr_info, merge_queue_state	If the PR is merged, or still queued when it was enqueued. Exactly one output key is saved - verified_pr_info on the regular merge path, merge_queue_state on the queued merge path - never both.
Error	-	If required context is missing, the PR is in neither state, or the GitHub call fails.

ai_suggest_pr_description

Generate PR title and description using PRAgent.

Workflow usage

- plugin: github
  step: ai_suggest_pr_description

Used by built-in workflows: create-pr-ai

Available to later steps: pr_title, pr_body, pr_size, ai_generated

Requires

Name	Type	Description
ctx.ai_router	-	The AI execution façade (falls back to ctx.ai)
ctx.git	-	An initialized GitClient
ctx.github	-	An initialized GitHubClient

Inputs (from ctx.data)

Name	Type	Description
pr_head_branch	str	The head branch for the PR

Outputs (saved to ctx.data)

Name	Type	Description
pr_title	str	AI-generated PR title
pr_body	str	AI-generated PR description
pr_size	str	Size classification (small/medium/large/very large)
ai_generated	bool	True if AI generated the content

Returns

Result	Saved for later steps	Description
Success	pr_title, pr_body, pr_size, ai_generated	PR description generated
Skip	pr_title, pr_body, pr_size, ai_generated	AI not configured or user declined
Error	-	Failed to generate PR description

Prompt and Selection

prompt_for_pr_title

Interactively prompts the user for a Pull Request title.

Workflow usage

- plugin: github
  step: prompt_for_pr_title

Available to later steps: pr_title

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
pr_title	str	The title entered by the user.

Returns

Result	Saved for later steps	Description
Success	pr_title	If the title was captured successfully.
Error	-	If the user cancels or the title is empty.
Skip	pr_title	If pr_title already exists.

prompt_for_pr_body

Interactively prompts the user for a Pull Request body.

Workflow usage

- plugin: github
  step: prompt_for_pr_body

Available to later steps: pr_body

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
pr_body	str	The body/description entered by the user.

Returns

Result	Saved for later steps	Description
Success	pr_body	If the body was captured successfully.
Error	-	If the user cancels.
Skip	pr_body	If pr_body already exists.

prompt_for_pr_draft

Ask whether the pull request should be created as a draft.

Workflow usage

- plugin: github
  step: prompt_for_pr_draft

Used by built-in workflows: create-pr-ai

Available to later steps: pr_is_draft

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Inputs (from ctx.data)

Name	Type	Description
draft	bool | None, optional	Draft mode from workflow params. Use True/False to skip the prompt, or None to ask interactively.

Outputs (saved to ctx.data)

Name	Type	Description
pr_is_draft	bool	Whether the PR should be created as a draft.

Returns

Result	Saved for later steps	Description
Success	pr_is_draft	If the draft preference was resolved successfully.
Error	-	If the user cancels or the prompt fails.

prompt_for_issue_body_step

Interactively prompts the user for a GitHub issue body.

Workflow usage

- plugin: github
  step: prompt_for_issue_body_step

Used by built-in workflows: create-issue-ai

Available to later steps: issue_body

Requires

Name	Type	Description
ctx.textual	-	Textual UI components.

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
issue_body	str	The body/description entered by the user.

Returns

Result	Saved for later steps	Description
Success	issue_body	If the body was captured successfully.
Error	-	If the user cancels.
Skip	issue_body	If issue_body already exists.

prompt_for_self_assign

Asks the user if they want to assign the issue to themselves.

Workflow usage

- plugin: github
  step: prompt_for_self_assign

Used by built-in workflows: create-issue-ai

Available to later steps: assignees

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
assignees	list[str]	Updated assignees list when the user chooses self-assignment.

Returns

Result	Saved for later steps	Description
Success	assignees	If the assignment preference is captured successfully.
Error	-	If the GitHub client is unavailable or the prompt fails.

prompt_for_labels

Prompt the user to select repository labels and save them to context.

Workflow usage

- plugin: github
  step: prompt_for_labels

Used by built-in workflows: create-pr-ai

Available to later steps: <output_key>

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
output_key	str, optional	Context key where selected labels should be stored. Defaults to "labels".
prompt	str, optional	Prompt text shown to the user. Defaults to "Select labels:".
default_selected_key	str, optional	Context key used to preselect labels. Defaults to output_key.

Outputs (saved to ctx.data)

Name	Type	Description
<output_key>	list[str]	Labels selected by the user.

Returns

Result	Saved for later steps	Description
Success	<output_key>	If label selection completes successfully.
Skip	<output_key>	If the repository has no labels.
Error	-	If the GitHub client is unavailable or the prompt fails.

Issue Creation

ai_suggest_issue_title_and_body

Use AI to suggest a title and description for a GitHub issue.

Workflow usage

- plugin: github
  step: ai_suggest_issue_title_and_body

Used by built-in workflows: create-issue-ai

Available to later steps: issue_title, issue_body, issue_category, labels

Inputs (from ctx.data)

Name	Type	Description
issue_body	str	Raw issue request entered by the user.

Outputs (saved to ctx.data)

Name	Type	Description
issue_title	str	AI-generated or user-edited title.
issue_body	str	AI-generated or user-edited body.
issue_category	str	Detected issue category.
labels	list[str]	Suggested labels for the issue.

Returns

Result	Saved for later steps	Description
Success	issue_title, issue_body, issue_category, labels	If issue content is generated and accepted.
Skip	issue_title, issue_body, issue_category, labels	If AI is unavailable or the user rejects the generated issue.
Error	-	If required context is missing or generation fails.

preview_and_confirm_issue

Show a preview of the AI-generated issue and ask for confirmation.

Workflow usage

- plugin: github
  step: preview_and_confirm_issue

Inputs (from ctx.data)

Name	Type	Description
issue_title	str	Generated issue title.
issue_body	str	Generated issue body.

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	If the user confirms the issue preview.
Error	-	If required context is missing, the user rejects, or the prompt is cancelled.

create_issue

Create a new GitHub issue.

Workflow usage

- plugin: github
  step: create_issue

Used by built-in workflows: create-issue-ai

Available to later steps: issue

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
issue_title	str	Issue title.
issue_body	str	Issue body.
assignees	list, optional	Usernames to assign.
labels	list, optional	Labels to apply.

Outputs (saved to ctx.data)

Name	Type	Description
issue	GitHubIssue	The created issue object.

Returns

Result	Saved for later steps	Description
Success	issue	If the issue is created successfully.
Error	-	If required context is missing or the GitHub call fails.

Pull Request Review

select_pr_for_review

Select a PR from the user's open PRs to review comments.

Workflow usage

- plugin: github
  step: select_pr_for_review

Used by built-in workflows: respond-pr-comments

Available to later steps: selected_pr_number, selected_pr_title

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
selected_pr_number	int	The selected PR number
selected_pr_title	str	The selected PR title

Returns

Result	Saved for later steps	Description
Success	selected_pr_number, selected_pr_title	PR selected successfully
Exit	-	No PRs available or user cancelled
Error	-	Failed to fetch PRs

fetch_pending_comments

Fetch unresolved review threads for the selected PR using GraphQL.

Workflow usage

- plugin: github
  step: fetch_pending_comments

Used by built-in workflows: respond-pr-comments

Available to later steps: review_threads

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
review_threads	List[UICommentThread]	Unresolved review threads

Returns

Result	Saved for later steps	Description
Success	review_threads	Threads fetched
Exit	-	No unresolved threads
Error	-	Failed to fetch threads

check_clean_state

Check that the working tree is clean before checking out the PR branch.

Workflow usage

- plugin: github
  step: check_clean_state

Used by built-in workflows: respond-pr-comments

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	Working tree is clean
Exit	-	Uncommitted changes detected — user must stash manually
Error	-	Failed to check status

checkout_pr_branch

Save the current branch and checkout the PR branch.

Workflow usage

- plugin: github
  step: checkout_pr_branch

Used by built-in workflows: respond-pr-comments

Available to later steps: original_branch

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
original_branch	str	Branch to restore after review

Returns

Result	Saved for later steps	Description
Success	original_branch	PR branch checked out
Error	-	Failed to fetch or checkout

review_comments

Review all unresolved comment threads one by one and take action.

Workflow usage

- plugin: github
  step: review_comments

Used by built-in workflows: respond-pr-comments

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	All threads processed
Error	-	Failed to process threads

push_commits

Push commits to PR branch.

Workflow usage

- plugin: github
  step: push_commits

Used by built-in workflows: respond-pr-comments

Available to later steps: push_successful

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
push_successful	bool	Whether push succeeded

Returns

Result	Saved for later steps	Description
Success	push_successful	Commits pushed
Skip	push_successful	No commits to push or user cancelled
Error	-	Failed to push

send_comment_replies

Send comment replies (both text responses and commit hashes).

Workflow usage

- plugin: github
  step: send_comment_replies

Used by built-in workflows: respond-pr-comments

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	Replies sent
Skip	-	No replies to send or user cancelled
Error	-	Failed to send replies

request_review

Re-request review from existing reviewers.

Workflow usage

- plugin: github
  step: request_review

Used by built-in workflows: respond-pr-comments

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	Review re-requested
Skip	-	Push didn't succeed or user cancelled
Error	-	Failed to request review

checkout_original_branch

Restore the original branch after PR review.

Workflow usage

- plugin: github
  step: checkout_original_branch

Used by built-in workflows: respond-pr-comments

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	Restored to original branch
Exit	-	No original branch saved or checkout failed

Code Review

select_pr_for_code_review

List all open PRs and ask user to select one.

Workflow usage

- plugin: github
  step: select_pr_for_code_review

Used by built-in workflows: review-pr, review-pr-thread-resolution

Available to later steps: review_pr_number, review_pr_title, review_pr_head, review_pr_base

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
review_pr_number	int	Selected PR number
review_pr_title	str	PR title
review_pr_head	str	Head branch
review_pr_base	str	Base branch

Returns

Result	Saved for later steps	Description
Success	review_pr_number, review_pr_title, review_pr_head, review_pr_base	A PR was selected.
Exit	-	No PRs, or the user cancelled.
Error	-	If listing PRs fails.

fetch_pr_review_bundle

Fetch all data needed for a full PR review cycle.

Workflow usage

- plugin: github
  step: fetch_pr_review_bundle

Used by built-in workflows: review-pr, review-pr-thread-resolution

Available to later steps: review_pr, review_diff, review_changed_files, review_changed_files_with_stats, review_commit_sha, review_threads, review_general_comments, pr_template

Inputs (from ctx.data)

Name	Type	Description
review_pr_number	int	PR number

Outputs (saved to ctx.data)

Name	Type	Description
review_pr	UIPullRequest	Pull request details
review_diff	str	Full unified diff
review_changed_files	List[str]	Changed file paths (may be subset for large PRs)
review_changed_files_with_stats	List[UIFileChange]	All files with add/del stats
review_commit_sha	str	Head commit SHA
review_threads	List[UICommentThread]	Inline review threads (unresolved)
review_general_comments	List[UICommentThread]	General PR-level comments
pr_template	str | None	PR template content if available

Returns

Result	Saved for later steps	Description
Success	review_pr, review_diff, review_changed_files, review_changed_files_with_stats, review_commit_sha, review_threads, review_general_comments, pr_template	The step completed.
Skip	review_pr, review_diff, review_changed_files, review_changed_files_with_stats, review_commit_sha, review_threads, review_general_comments, pr_template	Nothing to do (empty diff).
Error	-	The step failed.

build_change_manifest

Build a structured manifest of the PR changes (no AI involved).

Workflow usage

- plugin: github
  step: build_change_manifest

Used by built-in workflows: review-pr

Available to later steps: change_manifest

Inputs (from ctx.data)

Name	Type	Description
review_pr	UIPullRequest	Pull request details
review_changed_files_with_stats	List[UIFileChange]	Files with add/del stats

Outputs (saved to ctx.data)

Name	Type	Description
change_manifest	ChangeManifest	Structured PR context

Returns

Result	Saved for later steps	Description
Success	change_manifest	The step completed.
Error	-	The step failed.

build_existing_comments_index

Build a compact index of existing PR comments for deduplication.

Workflow usage

- plugin: github
  step: build_existing_comments_index

Used by built-in workflows: review-pr

Available to later steps: existing_comments_index

Inputs (from ctx.data)

Name	Type	Description
review_threads	List[UICommentThread]	Inline review threads
review_general_comments	List[UICommentThread]	General PR-level comments

Outputs (saved to ctx.data)

Name	Type	Description
existing_comments_index	List[ExistingCommentIndexEntry]	-

Returns

Result	Saved for later steps	Description
Success	existing_comments_index	The step completed.

write_review_material

Put what the review would otherwise fetch into the PR worktree, as files.

Workflow usage

- plugin: github
  step: write_review_material

Used by built-in workflows: review-pr

Available to later steps: review_material

Inputs (from ctx.data)

Name	Type	Description
change_manifest	ChangeManifest	-
review_diff_manager	DiffContextManager	-
review_threads, review_general_comments	List[UICommentThread]	-
worktree_path	str	-

Outputs (saved to ctx.data)

Name	Type	Description
review_material	dict[str, bool]	each changed path -> whether it has a base version

Returns

Result	Saved for later steps	Description
Success	review_material	The step completed.
Error	-	The step failed.

ai_review_findings

Run the review session, and report its cost even if it is abandoned.

Workflow usage

- plugin: github
  step: ai_review_findings

Used by built-in workflows: review-pr

Available to later steps: raw_findings, ai_findings_failed

Inputs (from ctx.data)

Name	Type	Description
change_manifest	ChangeManifest	-
worktree_path	str	with the material write_review_material left in it

Outputs (saved to ctx.data)

Name	Type	Description
raw_findings	list	the session's findings, mapped onto Finding's fields
ai_findings_failed	bool	True when no review happened

Returns

Result	Saved for later steps	Description
Success	raw_findings, ai_findings_failed	With the raw findings, or with none when AI is off for the task.
Error	-	If the session could not run or produced nothing readable.

normalize_findings

Parse and validate raw AI output into Finding models.

Workflow usage

- plugin: github
  step: normalize_findings

Used by built-in workflows: review-pr

Available to later steps: normalized_findings

Inputs (from ctx.data)

Name	Type	Description
raw_findings	list | str	Raw AI output from ai_review_findings

Outputs (saved to ctx.data)

Name	Type	Description
normalized_findings	List[Finding]	Validated Finding objects

Returns

Result	Saved for later steps	Description
Success	normalized_findings	The step completed.
Error	-	The step failed.

dedupe_findings

Remove findings that duplicate existing PR comments.

Workflow usage

- plugin: github
  step: dedupe_findings

Used by built-in workflows: review-pr

Available to later steps: deduped_findings

Inputs (from ctx.data)

Name	Type	Description
normalized_findings	List[Finding]	-
existing_comments_index	List[ExistingCommentIndexEntry]	-

Outputs (saved to ctx.data)

Name	Type	Description
deduped_findings	List[Finding]	Findings after duplicate removal

Returns

Result	Saved for later steps	Description
Success	deduped_findings	The step completed.
Error	-	The step failed.

build_new_comment_actions

Convert deduplicated findings into ReviewActionProposal objects.

Workflow usage

- plugin: github
  step: build_new_comment_actions

Used by built-in workflows: review-pr

Available to later steps: review_action_proposals

Inputs (from ctx.data)

Name	Type	Description
deduped_findings	List[Finding]	-

Outputs (saved to ctx.data)

Name	Type	Description
review_action_proposals	List[ReviewActionProposal]	-

Returns

Result	Saved for later steps	Description
Success	review_action_proposals	The step completed.
Skip	review_action_proposals	Nothing to do (no findings).

validate_review_actions

Present each ReviewActionProposal to the user for approval, editing, or skipping.

Workflow usage

- plugin: github
  step: validate_review_actions

Used by built-in workflows: review-pr, review-pr-thread-resolution

Available to later steps: approved_action_proposals

Inputs (from ctx.data)

Name	Type	Description
review_action_proposals	List[ReviewActionProposal]	-
review_diff	str	Full PR diff for extracting diff context per comment

Outputs (saved to ctx.data)

Name	Type	Description
approved_action_proposals	List[ReviewActionProposal]	-

Returns

Result	Saved for later steps	Description
Success	approved_action_proposals	The step completed.
Skip	approved_action_proposals	Nothing to do (none approved).
Error	-	The step failed.

submit_review_actions

Submit approved ReviewActionProposal objects to GitHub.

Workflow usage

- plugin: github
  step: submit_review_actions

Used by built-in workflows: review-pr, review-pr-thread-resolution

Inputs (from ctx.data)

Name	Type	Description
approved_action_proposals	List[ReviewActionProposal]	-
review_pr_number	int	-
review_commit_sha	str	Head commit SHA (fetched if missing)
review_diff	str	Full PR diff for inline comment validation

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	The step completed.
Skip	-	Nothing to do (no approved actions).
Error	-	The step failed.

build_thread_review_candidates

Select open inline threads worth AI analysis.

Workflow usage

- plugin: github
  step: build_thread_review_candidates

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: thread_review_candidates

Inputs (from ctx.data)

Name	Type	Description
review_threads	List[UICommentThread]	Unresolved inline review threads
review_pr	UIPullRequest	PR object with author info
review_current_user	str	GitHub login running Titan

Outputs (saved to ctx.data)

Name	Type	Description
thread_review_candidates	List[ThreadReviewCandidate]	-

Returns

Result	Saved for later steps	Description
Success	thread_review_candidates	The step completed.
Skip	thread_review_candidates	Nothing to do (no candidates).
Error	-	The step failed.

build_thread_review_contexts

Enrich thread candidates with diff hunk context and full reply history.

Workflow usage

- plugin: github
  step: build_thread_review_contexts

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: thread_review_contexts

Requires

Name	Type	Description
ctx.github	-	Optional GitHub client used to inspect referenced commits.

Inputs (from ctx.data)

Name	Type	Description
thread_review_candidates	List[ThreadReviewCandidate]	-
review_threads	List[UICommentThread]	For extracting reply history
review_diff	str	Full PR unified diff

Outputs (saved to ctx.data)

Name	Type	Description
thread_review_contexts	List[ThreadReviewContext]	-

Returns

Result	Saved for later steps	Description
Success	thread_review_contexts	The step completed.
Skip	thread_review_contexts	Nothing to do (no candidates).
Error	-	The step failed.

ai_thread_resolution

AI call: decide what to do with each open thread.

Workflow usage

- plugin: github
  step: ai_thread_resolution

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: raw_thread_decisions

Inputs (from ctx.data)

Name	Type	Description
thread_review_contexts	List[ThreadReviewContext]	-

Outputs (saved to ctx.data)

Name	Type	Description
raw_thread_decisions	list	Raw AI output aggregated across batches, before normalization

Returns

Result	Saved for later steps	Description
Success	raw_thread_decisions	The step completed.
Error	-	The step failed.

normalize_thread_decisions

Parse and validate raw AI output into ThreadDecision models.

Workflow usage

- plugin: github
  step: normalize_thread_decisions

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: thread_decisions

Inputs (from ctx.data)

Name	Type	Description
raw_thread_decisions	list | str	Raw AI output from ai_thread_resolution

Outputs (saved to ctx.data)

Name	Type	Description
thread_decisions	List[ThreadDecision]	Validated ThreadDecision objects

Returns

Result	Saved for later steps	Description
Success	thread_decisions	The step completed.
Error	-	The step failed.

build_thread_actions

Transform ThreadDecision objects into ReviewActionProposal objects.

Workflow usage

- plugin: github
  step: build_thread_actions

Used by built-in workflows: review-pr-thread-resolution

Available to later steps: review_action_proposals

Inputs (from ctx.data)

Name	Type	Description
thread_decisions	List[ThreadDecision]	-
thread_review_contexts	List[ThreadReviewContext]	-

Outputs (saved to ctx.data)

Name	Type	Description
review_action_proposals	List[ReviewActionProposal]	-

Returns

Result	Saved for later steps	Description
Success	review_action_proposals	The step completed.
Skip	review_action_proposals	Nothing to do (no actionable decisions).
Error	-	The step failed.

Worktree Support

create_worktree

Create a worktree for PR review.

Workflow usage

- plugin: github
  step: create_worktree

Used by built-in workflows: review-pr

Available to later steps: worktree_path, worktree_created

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

Name	Type	Description
worktree_path	str	Absolute path to worktree
worktree_created	bool	Whether worktree was created

Returns

Result	Saved for later steps	Description
Success	worktree_path, worktree_created	Worktree created
Error	-	Failed to create worktree

cleanup_worktree

Cleanup a worktree created for PR review.

Workflow usage

- plugin: github
  step: cleanup_worktree

Used by built-in workflows: review-pr

Inputs (from ctx.data)

None documented.

Outputs (saved to ctx.data)

None documented.

Returns

Result	Saved for later steps	Description
Success	-	Worktree cleaned up
Skip	-	Nothing to clean up, no git client, or removal failed
Never returns Exit	-	that would stop the whole workflow, and this step may run
before others (nothing was created is a normal case when worktree setup was	-	-
allowed to fail). Skip keeps the workflow going.	-	-

Releases

select_release

List published GitHub releases and select one to use as a notes source.

Workflow usage

- plugin: github
  step: select_release

Available to later steps: selected_release, selected_release_tag, selected_release_notes, selected_release_url

Requires

Name	Type	Description
ctx.github	-	An initialized GitHubClient.

Inputs (from ctx.data)

Name	Type	Description
github_release_limit	int, optional	Maximum number of releases to list. Defaults to 15.

Outputs (saved to ctx.data)

Name	Type	Description
selected_release	UIRelease	Selected GitHub release, including its notes body.
selected_release_tag	str	Tag name of the selected release.
selected_release_notes	str	Release notes body of the selected release.
selected_release_url	str	URL of the selected release.

Returns

Result	Saved for later steps	Description
Success	selected_release, selected_release_tag, selected_release_notes, selected_release_url	If a release is selected successfully.
Skip	selected_release, selected_release_tag, selected_release_notes, selected_release_url	If no published releases exist.
Error	-	If the GitHub client is not available or the request fails.

Docstring-based reference

The semiautomated step inventory reads public step docstrings from code and validates that each exposed step documents:

• Requires
• Inputs (from ctx.data) when applicable
• Outputs (saved to ctx.data) when applicable
• Returns

The generated machine-readable inventory lives under docs/plugins/_generated/.

For this project, the inventory is maintained through:

• .titan/workflows/sync-plugin-docs.yaml
• .titan/workflows/validate-plugin-docs.yaml
• .titan/steps/sync_plugin_docs.py
• .titan/steps/validate_plugin_docs.py