Coding Agent workflow

Flowman's primary workflow starts a coding session, optionally plans and waits for human approval, then runs implementation and follow-up chat. One workflow implementation (src/workflows/coding-agent.ts) serves every Coding Agent run. Projects create child workflows (derived templates) to preconfigure fields and give each use case its own slug, card, and run history — without duplicating workflow code.

How a run flows

Whether a run starts from the UI, an email trigger, or another connector, the path is the same. The HTTP route is always /api/workflows/coding-agent. The optional workflowSlug in the request body selects which workflow record owns the run.

UI / trigger dispatch
  → POST /api/workflows/coding-agent  (body may include workflowSlug)
  → beforeOpenRun hooks (prompt template merge, conflict guard)
  → Convex openRun (records run under child slug, merges promptTemplate)
  → Workflow SDK start(codingAgent)
  → plan session OR direct implementation
  → local runtime polls Convex  OR  provider cloud node action

Workflow code path

• Route handler — src/app/api/workflows/coding-agent/route.ts uses createWorkflowRoute to open a Convex run, snapshot project env vars, and call start() from the Workflow SDK.
• Orchestrator — codingAgent() in src/workflows/coding-agent.ts validates input, resolves the repository, then either opens a planning session (default) or jumps straight to implementation when planMode is false.
• Step actions — shared steps in src/workflows/shared/actions/coding-agent.ts create Convex coding sessions, bind approval webhooks, and wait for plan decisions before queuing implementation.
• Execution — local runs are polled and executed by a self-hosted coding-agent runtime (pnpm runtime:coding). Provider cloud runs are driven directly from Convex via convex/cursorCloudNode.ts or convex/openAiCloudNode.ts and never touch a runtime environment.

Plan mode vs direct start

When planMode is true (the default), the workflow opens a planning session, pauses for clarification questions or plan approval on the Approvals page, then queues implementation after approval. When planMode is false, the workflow skips planning and opens a single implementation turn immediately.

Before a local planning session starts, the runtime refreshes the repository's base branch so the plan is written against current code rather than a checkout left behind by an earlier run. Uncommitted changes fail the session before the agent starts, unless the session already carries an approved dirty worktree — those only refresh origin/<base> and leave the checkout untouched. See Branch management for the isolated versus current-branch rules.

After implementation completes, the workflow run closes. Follow-up chat turns reuse the same coding session thread but do not reopen the workflow run.

Child workflows (derived templates)

A child workflow is a project-scoped workflow record derived from the base coding-agent workflow. It shares the same route (/api/workflows/coding-agent) and the same orchestrator code, but has its own slug, name, description, category, visibility, parameter defaults, and field visibility.

Creating a child workflow

1. Open Workflows in the project and click New Workflow.
2. Choose a name and optional slug. Flowman copies all Coding Agent parameters from the base workflow via createCodingAgentTemplate in Convex.
3. For each parameter, choose whether it stays visible in the run modal or is hidden with a saved default. Hidden fields are still submitted when the run starts.
4. Required fields cannot be hidden unless they have a valid default. Attachments cannot be saved as defaults because uploads are per-run.

Examples: a Plan New Feature template might expose only repository and prompt while defaulting runtime environment, provider, plan mode, and branch mode. A Cursor Cloud Fix template might hide agentProvider=cursor and location=cloud so users only pick a repository and describe the bug. Flowman also insert-only seeds a Cursor Local child (cursor-local) with agentProvider=cursor and location=local hidden. Existing workflows with that slug are left unchanged.

Slug vs route: how runs are recorded

The route handler's factory slug is always coding-agent, but callers pass the child slug in the request body. Convex openRun looks up the workflow by that slug, verifies it belongs to the project and that its route matches the request path, then stores the run under the child workflow's workflowId. Trigger dispatch preserves the matched workflow slug automatically (triggers docs).

POST /api/workflows/coding-agent
Content-Type: application/json

{
  "projectSlug": "my-project",
  "workflowSlug": "debug-issue",
  "input": {
    "repositoryId": "codingRepositories_...",
    "runtimeEnvironmentId": "runtimeEnvironments_...",
    "agentProvider": "codex",
    "location": "local",
    "prompt": "Fix the flaky test in auth.test.ts"
  }
}

Editing child workflows

Use the pencil action on a child workflow card to edit name, description, category, public/private visibility, exposed fields, and saved defaults. The slug stays fixed. Only child workflows can be edited this way — the base coding-agent workflow is seeded and not editable through the template editor. See Organize workflows for categories, visibility, and prompt-template distinctions.

Design mode PRDs

Child workflows can save hidden designMode as true with planMode still true. Flowman then uses the normal clarification loop but asks the agent for a Markdown PRD/design document. The ready state opens Review Design, and Finalize PRD completes the run without queuing implementation.

Prompt template wrapping

Every Coding Agent workflow (base and child) carries a hidden promptTemplate parameter. At run start, Flowman replaces {prompt} with the user's submitted prompt before the orchestrator and stored run input see it. The template default is {prompt} (pass-through). promptTemplate is stripped from persisted input after merging.

Hidden promptTemplate default:
  "Debug the following issue: {prompt}"

User submits prompt:
  "Fix the flaky test in auth.test.ts"

Stored run input.prompt (what the agent receives):
  "Debug the following issue: Fix the flaky test in auth.test.ts"

This is separate from project prompt templates under Build → Prompts, which help users compose the prompt field in the run modal. Child workflow prompt templates wrap that text automatically at runtime.

Coding providers

Workflow input agentProvider selects the coding backend. Flowman supports two providers today:

Each provider and location pair is a Coding Agent Integration. Its capability contract drives model choices, supported tuning, repository and runtime requirements, attachments, project environment delivery, and git behavior. Workflow callers do not forward those capabilities individually.

Codex

• Runtime: local or OpenAI cloud, selected with location.
• Executor: self-hosted coding-agent runtime running the Codex app-server against a local repository checkout (or an ephemeral temp directory when no repository is configured).
• Requirements: runtimeEnvironmentId, runtime host with CODING_AGENT_RUNTIME_TOKEN, FLOWMAN_ENVIRONMENT, and Convex URL. Optional CODEX_BIN / CODEX_MODEL overrides on the runtime host.
• Tuning: supports model, reasoningEffort, and speed (Codex service tier). New runs default to GPT-5.6 Sol with High reasoning. Sol, Terra, and Luna support Low through Max locally; GPT-5.5 and GPT-5.3-Codex-Spark keep Low through Extra high.
• Env vars: repository commands start from an isolated OS and tooling baseline, then receive the immutable run-start project environment snapshot. Flowman runtime credentials and deployment selectors are not inherited. The same snapshot is reapplied when Flowman resumes the thread, while local skills remain available through the retained home, path, Codex home, and SSH agent settings. Skills that depend on environment-only credentials must receive them through project environment variables.
• Previews: preview commands use the same isolated baseline and run-start project environment snapshot as repository commands.
• Branch / PR: full local git branch management, dirty-worktree protection, Commit to PR via gh, and preview sessions through zrok.

Codex — OpenAI cloud

• Uses background Responses with resumable event streams, one durable OpenAI conversation, and reusable Hosted Shell containers. Planning receives a separate read-only container; approval starts a fresh implementation container that follow-ups reuse while it remains active.
• New runs default to gpt-5.6-sol with High reasoning. Terra and Luna are also available. GPT-5.6 supports None, Low, Medium, High, Extra high, and Max in OpenAI cloud; gpt-5.5 keeps Low through Extra high.
• Existing gpt-5.6selections remain valid and continue to use OpenAI's Sol alias, but the alias is hidden when choosing a new model. Flowman does not expose GPT-5.6 Pro mode.
• Requires a canonical GitHub repository URL, project env var OPENAI_API_KEY, and a connected Flowman GitHub App with contents and pull-request write access. It never uses ChatGPT or Codex subscription credentials.
• GitHub, the npm registry, and the Convex management/version APIs are included in every outbound allowlist. Optional comma-separated domains may be added with OPENAI_CLOUD_ALLOWED_DOMAINS and must also be approved in the OpenAI organization allowlist. OpenAI Hosted Shell does not expose unrestricted or wildcard outbound access: an organization admin must enable container networking and approve every requested domain. The complete project environment snapshot is uploaded into each Hosted Shell container for agent commands; sensitive values are redacted from persisted output.
• Project variables named CONVEX_DEPLOYMENT or ending in _CONVEX_DEPLOYMENT automatically add the corresponding <deployment>.convex.cloud domain for values such as dev:chatty-ibex-315.
• Images are forwarded by public URL; non-image attachments remain stored in Flowman. Implementations use a deterministic codex/... branch and must commit and push before Flowman creates or updates a PR.

Cursor

Cursor supports both local and cloud execution via the location field (defaults to local). Codex uses the same location field for OpenAI Hosted Shell.

Cursor — local

• Executor: self-hosted coding-agent runtime using @cursor/sdk against the registered repository path on the runtime host.
• Requirements: runtimeEnvironmentId and CURSOR_API_KEY on the runtime host. Optional CURSOR_DEFAULT_MODEL when workflow input omits a model.
• Models: shared Cursor catalog with Composer 2.5 (default), Cursor Grok 4.6, Cursor Grok 4.5, Auto, and the expanded Claude / GPT / Gemini / Kimi / GLM IDs listed in the Cursor model matrix below. Selected IDs are submitted unchanged.
• Behavior: same branch management, conflict guards, Commit to PR, and preview flows as Codex local runs. Reasoning effort is available for supported Cursor models and is sent as Cursor effort or reasoning params. Speed / service-tier controls remain unavailable.
• Env vars: the run-start project environment snapshot is applied to the coding-agent runtime process while a Cursor Local thread starts or a turn runs, so local tools and skills can read those keys. Keys prefixed with CURSOR_ are excluded. Cursor Local calls that apply process env run one at a time so concurrent turns cannot inherit another project's secrets. Flowman restores the previous process values when the call ends.

Cursor — cloud

• Executor:Cursor's cloud infrastructure. Convex schedules node actions that drive the Cursor SDK directly — no self-hosted runtime polls or executes the session.
• Input: set agentProvider: "cursor" and location: "cloud". runtimeEnvironmentId and branchMode are ignored.
• Repository: requires a configured GitHub URL on the repository record. Cursor clones that URL into an isolated VM and may auto-create a pull request.
• Env vars: the run-start snapshot of project environment variables (record.env) is injected into the cloud VM. Keys prefixed with CURSOR_ are excluded.
• Concurrency: cloud runs skip the local repository conflict guard — multiple cloud sessions on the same repository can run in parallel because each gets its own VM.
• Attachments: images are sent as public Convex file URLs. PDF and text attachments are stored in Flowman but not forwarded to Cursor Cloud.
• Models: same shared Cursor catalog as local Cursor — Composer 2.5 remains the default when no model is specified; Composer 2.5, Cursor Grok 4.6, Cursor Grok 4.5, and Auto stay available; newly added Claude / GPT / Gemini / Kimi / GLM IDs appear with the ticket display names. Supported models expose Reasoning effort (including Max where Cursor provides it); Composer/Auto do not. Service-tier / Speed controls remain unavailable.
• PR completion:cloud runs do not queue the local "complete PR" skill; they finalize from GitHub webhooks like local runs. Cursor Cloud polyrepo runs reconcile structured branch data, final-summary PR URLs, and—when a GitHub App is connected—a bounded workspace branch lookup. While an implementation is active, Check agent status offers a one-shot, idempotent recovery if the provider finished after the stream drain stopped; it does not poll in the background.

Provider × location matrix

| Provider | location | Executor              | Runtime env required | Repository checkout        |
|----------|----------|-----------------------|----------------------|----------------------------|
| codex    | local    | Self-hosted runtime       | Yes                  | Local path on runtime host       |
| codex    | cloud    | OpenAI Hosted Shell       | No                   | OpenAI container clones GitHub   |
| cursor   | local    | Self-hosted runtime       | Yes                  | Local path on runtime host       |
| cursor   | cloud    | Cursor Cloud (Convex)     | No                   | Cursor VM clones workspace GitHub URLs (standalone or full polyrepo set) |

Codex model matrix

| Integration  | Models offered for new runs                         | Reasoning efforts                         |
|--------------|-----------------------------------------------------|-------------------------------------------|
| Codex local  | gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna          | low, medium, high, xhigh, max             |
| OpenAI cloud | gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna          | none, low, medium, high, xhigh, max       |
| Both         | gpt-5.5 (plus gpt-5.3-codex locally)               | low, medium, high, xhigh                  |

Cursor model matrix

| Integration   | Default       | Models offered for new runs                                                                 |
|---------------|---------------|---------------------------------------------------------------------------------------------|
| Cursor local  | composer-2.5  | composer-2.5, grok-4.6, grok-4.5, auto, plus the expanded Cursor catalog below              |
| Cursor cloud  | composer-2.5  | Same shared Cursor catalog: existing choices retained, plus Claude/GPT/Gemini/Kimi/GLM IDs  |

Expanded Cursor catalog (exact IDs; shared by local and cloud):
  composer-2.5, grok-4.6, grok-4.5, auto,
  claude-opus-5, claude-opus-4-8, gpt-5.6-sol, gpt-5.5, claude-fable-5, claude-sonnet-5,
  gpt-5.6-terra, claude-sonnet-4-6, composer-2, gpt-5.3-codex, claude-opus-4-7, gpt-5.4,
  claude-opus-4-6, claude-opus-4-5, gpt-5.2, gpt-5.6-luna, gemini-3.6-flash, gemini-3.1-pro,
  gpt-5.4-mini, gpt-5.4-nano, claude-haiku-4-5, claude-sonnet-4-5, gpt-5.1, gemini-3-flash,
  gemini-3.5-flash, claude-sonnet-4, gpt-5-mini, gemini-2.5-flash, kimi-k3, kimi-k2.7-code,
  glm-5.2

Cursor reasoning effort is model-specific (for example Opus/Fable/Sonnet Max,
GPT Extra high / Max, Grok 4.6 low/medium/high/xhigh, Grok 4.5 low/medium/high).
Composer and Auto have no effort control. Cursor Cloud requires a complete
id+params variant (context/fast/thinking companions included); Flowman fills
those from Cursor's default variant when sending a selected effort.
Cursor still does not expose service-tier / Speed controls in Flowman.
Codex-only catalogs are unchanged.

For both providers, location: "cloud" removes the local runtime requirement. Cloud runs require a registered repository with a canonical GitHub URL; Codex cloud additionally enforces the OpenAI key, GitHub App, and Hosted Shell model prerequisites above.

Project defaults

Under Project settings → Coding agent, admins can set default provider, model, reasoning effort, and speed. These apply when a run or child workflow does not override them. Legacy codexDefaults project fields still resolve as implicit Codex defaults.

Runtime environments

A runtime environment is a named, project-scoped target for local execution. Each environment maps repository records to filesystem paths on a specific host. One coding-agent runtime process should run per environment/VPS pair in production; the runtime heartbeats to Convex and polls for queued turns scoped to its FLOWMAN_ENVIRONMENT value.

Runtime metadata can advertise which providers the host supports (codingAgentProviders: ["codex", "cursor"]). Cloud sessions never select a runtime environment.

Diagnosing a runtime host

Run pnpm runtime:coding:doctor before starting Codex Local on a new machine. The command is read-only: it checks Node, pnpm, Git, workspace dependencies, .env.local, the environment slug/token against Convex, the Codex app-server and login, and the complete Flowman skills checkout. Failures produce a non-zero exit code; GitHub CLI, zrok, and SSH-agent gaps remain warnings because they affect optional PR, preview, or SSH-remote capabilities.

The skills checkout defaults to $HOME/git/skills/skills. Set FLOWMAN_SKILLS_REPO to the Git repository root when it lives elsewhere. Every immediate child containing SKILL.md must be enabled in Codex and resolve through its symlink back to that checkout.

Intake and Refined columns (Jira queue)

Creating Jira requests in Flowman

Members and customers can use New Ticket in the top bar to raise a Jira Service Management request without leaving Flowman. Customer View raises the request as the impersonated customer. Jira projects come from the project-qualified queues in JIRA_QUEUE_ID; customers see only projects represented by their assigned queues. Flowman shows only request types mapped by Jira work profiles and loads their visible fields from Jira when selected. Stable service-desk and request-type IDs win; a unique request-type name is used as a fallback. Missing or ambiguous mappings are reported as configuration errors.

Supported fields are text, multiline text, Markdown description, number, date, boolean, single- and multi-choice, and Jira-backed user pickers. Optional unsupported fields are omitted; an unsupported field required by Jira blocks submission. Description Markdown is converted to Jira ADF. Up to five images, PDFs, or text files may be attached, with a 20 MB limit per file. Files are uploaded to Jira as public request attachments and Flowman deletes the forwarded draft blobs.

Jira automation must apply exactly one recognized repo: label and route the issue into one of the configured queues. After Jira creates the request, Flowman performs a bounded Intake refresh and verifies the queue, repository, and customer visibility. A fully verified request returns to Coding with a success message. If the Jira issue exists but an attachment or visibility check fails, Flowman still returns with the issue key and a partial-success warning. An ambiguous Jira timeout is marked indeterminate and is never retried automatically, preventing duplicate requests.

The board opens with two Jira columns before Planning: Intake (tickets that are not yet refined) and Refined (tickets carrying the Refined label). Both pull from the configured Jira Service Management queues and have not become coding sessions yet. Sync is pull on demand: nothing polls in the background. Press the refresh control in the Intake column header and Flowman resolves each project-qualified entry in JIRA_QUEUE_ID, reads that queue's own JQL filter, and searches Jira with it. The same refresh can be triggered from a Jira org-level Automation rule on issue create via POST /api/webhooks/jira/intake-refresh with Authorization: Bearer <secret>. Set JIRA_INTAKE_WEBHOOK_SECRET on the app (or reuse FLOWMAN_INTERNAL_DISPATCH_TOKEN). The request body must include the Jira issue (at least issue.key or issue.fields.project.key); Flowman refreshes every project whose JIRA_QUEUE_ID watches that Jira project key.

Tickets appear in both views. On the Board they sit in Intake or Refined; the refresh control lives on Intake only. On the List, grouping by Status puts them in leading Intake and Refined groups (each omitted when empty), and grouping by Repositoryfiles each ticket with that repository's sessions — so a repository with nothing but intake tickets still gets its own group. Click a ticket to open a right-hand detail drawer with description, people, labels, and the latest comment (fetched live from Jira). From that drawer, Edit switches the title and description into an editable form. Description editing uses Markdown for headings, emphasis, links, lists, block quotes, inline code, code blocks, and horizontal rules. Save writes both fields to the same Jira issue, keeps the drawer open, and replaces the form with values confirmed by a fresh Jira read. Cancelexits edit mode without writing. If Jira's title or description changed after editing began, Flowman does not overwrite those fields — it refreshes the drawer and asks you to review the newer values. When the existing Jira description contains formatting Markdown cannot represent (for example panels, tables, media, or mentions), Flowman warns that unsupported formatting may be lost and requires explicit confirmation before saving. Empty titles are blocked; empty descriptions are allowed. While a save is pending, duplicate submissions are prevented and failures leave your draft in place with an actionable error. From a Refined ticket you can start a Cloud or Local coding run directly from that drawer. From an Intake ticket, Exclude from intake asks for confirmation, then adds the exact flowman:exclude label in Jira without removing other labels, and removes the ticket from Intake only after that label is verified. The action is not offered for Refined tickets. Restoration is done in Jira by removing the label; the ticket returns on a later successful Intake refresh when it still matches a configured queue and is not refined. From either Intake or Refined, Rejectasks for confirmation, then uses Jira's exact Reject transition to Canceled and removes the ticket from the Flowman board only after that status is verified. Rejection stays disabled while refinement or investigation is still active, leaves Jira labels and other fields unchanged, and keeps the ticket visible with a retryable error when the required transition is missing, ambiguous, or fails. Use Open in Jira when you need the full issue page or fields outside title and description.

A refresh both adds new tickets and updates ones already pulled, so labels, status, assignee, and priority stay current. Tickets that have left the queue are hidden from the board but their rows are kept, so a ticket that returns to the queue reappears without losing anything Flowman recorded against it. Tickets rejected from Flowman keep their dismissal and do not reappear merely because Jira still returns them. Each refresh pulls at most JIRA_INTAKE_MAX_ISSUES tickets (200 by default); when that cap is hit, nothing is hidden, because a capped pull has an incomplete view of the queue.

Jira label conventions drive the card, and none are stored — each is re-read from the ticket's labels on every render, so editing a label in Jira takes effect on the next refresh:

• Refined — moves the ticket from the Intake column into Refined. Matched case-insensitively.
• flowman:exclude — hides a non-refined ticket from Intake. If the ticket also carries Refined, Refined takes precedence and the ticket stays in the Refined column. Matched case-insensitively; hidden from the chip row.
• repo:<name> — maps the ticket to a registered repository, for example repo:qualip-web. The name is compared as a repository slug, so casing and separators do not matter. A ticket with no repo: label still appears on the board with no repository; one pointing at an unregistered name, or carrying more than one, is flagged on the card instead of being dropped. Matched tickets count toward the repository filter chips just like coding sessions.
• workflow:cloud, workflow:local, workflow:local:codex, or workflow:local:cursor — seeds the Start as choice when you start a coding run from the Refined drawer. workflow:cloud is Cursor Cloud. workflow:local and workflow:local:codex are Codex Local. workflow:local:cursor is Cursor Local. Default is Cloud when absent. Like Refined and repo:, these labels are hidden from the chip row.

Jira work profiles

Project owners configure Jira work profiles under Settings → Jira. Each profile maps one or more JSM request types or Jira issue types to either Refine or Investigate, with profile-specific agent instructions. Flowman resolves a JSM request type first, then an issue type, and finally compares normalized Jira names when stable IDs are unavailable. A Jira identity can belong to only one profile. Unmapped tickets remain visible but cannot start work until an owner adds a mapping.

A ticket explicitly converted from a completed investigation has one higher-precedence exception: Flowman resolves it to the existing Suggest improvementrefinement profile even when its Jira request or issue type still maps to investigation. If that profile is removed or changed away from Refine, the ticket stays blocked until an owner restores it. The override is cleared only after a later refinement is successfully posted and verified.

The built-in profiles classify Report a bug as an investigation, with Bug as its issue-type fallback. Suggest a new feature and Suggest improvement are separate refinement profiles. There is intentionally no New Featureissue-type fallback because it cannot distinguish a feature from an improvement. Profile instructions are always enclosed by Flowman's immutable safety, transport, and output rules.

Refining an Intake ticket

Open an unrefined Intake ticket to link a registered repository and start Refine ticket. Choose Codex Local or Cursor Local in the drawer (Jira workflow:local:cursor defaults to Cursor Local). Linking is an explicit Jira write: Flowman removes every existing repo: label, adds exactly one repo:<registered-slug>, and preserves all unrelated labels. Refinement is enabled only when an online runtime for the selected provider has a configured filesystem path for that repository. A single eligible runtime is selected automatically; otherwise you must choose one.

The hidden refine-ticket workflow resumes one Codex thread and requires the installed skill with that exact name. Repository inspection is read-only. If the selected runtime does not expose the skill, the run fails with an installation message instead of substituting a generic refinement. Only one active refinement is allowed for an Intake ticket.

• Questions use the coding-session dialog. Choice questions have bounded options; nuanced questions use free-form answers. Optional questions can be skipped, and Done—draft now sends partial answers while recording the remainder as unresolved.
• The completed Markdown draft opens in the same dialog with View Run, Revise, Post, and Cancel. Closing the dialog only dismisses it; clicking the Intake card reopens the pending session.
• Posting sends the exact postresponse to the same agent thread. The agent must write the approved Markdown to a local file and pass that path to the skill's bundled posting command; stdin and - are unreliable in coding-agent shells. The command converts the file, posts and verifies the Jira changes as one non-interactive operation, and avoids ad hoc shell pipelines. It posts an internal Jira comment containing @agent-ticket-refined and adds the exact Refined label while preserving current labels. No Jira write is permitted before this approval.
• The skill verifies the exact rendered body, internal visibility, comment identity, Refined, and all prior labels, then returns structured proof to Flowman. The ticket moves to Refined only after every proof passes. A partial or uncertain result keeps the approved draft and shows Retry missing Jira update; retries reuse a matching comment, repair an earlier raw-Markdown comment in place, and perform only missing mutations.

While the workflow is active, the ticket remains in Intake with Refining, Questions, Draft ready, Posting, or Posting failed state. Cancelling retains the run and session audit history, clears the active link, makes no Jira changes, and permits a fresh refinement.

Local development stores Workflow SDK state in .workflow-data so a Next.js build does not erase active question or posting webhooks. If an older local run loses its webhook, Flowman will not bypass Jira posting verification. Use Cancel to clear the orphaned active link without a Jira write, then start a fresh refinement.

Investigating a test or production ticket

Tickets resolved to an investigation profile show Investigate ticket. The hidden investigate-jira-ticket workflow starts immediately on the selected registered repository and online Codex Local runtime. The ticket leaves Intake as soon as the run is linked. The session snapshots the resolved profile and compiled instructions, so later settings edits apply only to future runs.

• The workflow requires the installed investigate-ticket skill with that exact name and never invokes refine-ticket. Before approval, investigation is read-only: Codex cannot edit repository files, post to Jira, change labels, or mutate another external system. Diagnostic questions are allowed; feature-design and implementation-planning questions are not.
• An explicit test or production stage in the ticket or a later reviewer answer selects that environment. A later answer wins; conflicting or unrecognized environment names require a diagnostic clarification. When no stage is stated, the skill defaults to production and records the selection basis under Target Environment. Stage-specific checks run against only the selected environment.
• Owners may add repository-specific investigation instructions in Jira settings, including exact installed skill names. These overrides are used only by investigation sessions. If a required skill is missing, the run reports the blocker instead of imitating the skill.
• The report separates evidence from hypotheses and records impact, checks, findings, root-cause confidence, mitigations, next actions, and open questions. Reviewers can Revise, Post findings & mark done, or Cancel.
• On approval, Flowman sends exact post to the same skill session without repository write access. The skill deterministically converts the reviewed Markdown to Jira wiki markup so headings, lists, links, and code render correctly; posts it as an internal JSM comment; adds Investigatedincrementally; and performs the available transition into Jira's Done status category. It re-reads Jira to verify content, rendered structure, privacy, final status, and preservation of every prior label. It does not add Refined.
• Flowman validates the skill's structured result and expected Jira key; it does not perform a second Jira mutation or verification call. A partial result preserves the report and returns to review for an explicit retry. The skill finds an existing matching internal comment and retries only missing work so it does not duplicate the report or repeat an already-completed transition.

Cancelling returns the ticket to Intake and keeps the run for audit history. A failed or cancelled run exposes the same restore control on run detail. Successfully posted investigations remain linked to their completed run and outside Intake.

When the findings identify code work, open the completed investigation's run menu and choose Convert to refinement. Flowman resumes the same Codex thread with an exact Jira-only command. The skill removes only Investigated, requires a transition named exactly Reopen issue unless Jira is already Open or Reopened in its open status category, preserves the report and every other label, and verifies the issue is returned by at least one configured Intake queue. Flowman does not clear the active run link until all checks succeed.

A successful conversion keeps the original completed run and report for audit, but returns the ticket to Intake as Suggest improvement. It does not start refinement or add Refined; select the ticket and begin refinement normally. Partial Jira updates remain linked to the investigation and expose an explicit retry. Retries accept an already-Open or already-Reopened issue, repeat only missing mutations, and never edit or duplicate the findings comment.

From a Refinedticket's drawer, choose Cloud (Cursor Cloud), Codex Local, or Cursor Local and press Start. Jira workflow: labels still pick the default (workflow:local and workflow:local:codex select Codex Local; workflow:local:cursor selects Cursor Local). The latest Jira comment becomes the implementation prompt (planMode: false), and the matched repo: repository is required. Local runs need an online runtime environment. After start, the ticket is linked to the new run and leaves Intake / Refined until you restore it: delete the run, or use Return to Refined on a failed or cancelled run detail page (the run itself is kept for history).

When a linked local implementation is marked done—or all of its pull requests become terminal—Flowman queues the required flowman-pull-request-completed skill. The skill completes branch synchronization and verification, then transitions the linked Jira issue through the unique Done-category transition. It re-reads Jira, verifies the final status and preservation of existing labels, and only then marks the Flowman run done. Retrying is idempotent when Jira succeeded but Flowman completion did not. Cloud implementations retain their provider-native completion path because they do not have the project's locally installed skill.

Credentials come from project environment variables, never from the host process. Set JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN, and JIRA_QUEUE_ID. Use strict project-qualified entries such as FS:53,CA:13; Flowman trims entries, ignores blanks, uppercases project keys, deduplicates exact queue references, and combines tickets by Jira issue identity. Bare values such as 53 are rejected. JIRA_INTAKE_MAX_ISSUES is a shared cap across the combined refresh. If a queue fails or the cap prevents a complete evaluation, successful results are applied, uncertain existing tickets are preserved, and the refresh feedback identifies the project-qualified partial failure or truncation. The account behind the token needs agent access to every configured service desk — a customer or collaborator account is rejected even though it can see the same issues in the portal. Any project member can refresh; only admins can set the variables.

Further reading

• codingAgent action reference — full input schema, branch management, email triggers, failure behavior, and plan revision details.
• Organize workflows — categories, child template field rules, and public template copying.
• Getting started — register repositories, start the runtime, and launch your first run.
• Environment variables — how record.env reaches workflows and provider cloud execution.