Skip to content
Solutioneer

How A Run Works

Every Solutioneer skill follows the same five-step flow. Knowing the flow makes it easier to pick the right skill, understand where grounding came from, and decide whether to ask for save or writeback.

The canonical flow

Section titled “The canonical flow”
  1. Route. Codex picks one of the eight skills (or asks a single routing question if intent is ambiguous).
  2. Intake. Codex asks only the next highest-value missing field, one question at a time.
  3. Normalize. Codex converts the conversation into the internal SkillRunInput shape — account, objective, notes, artifactRefs, destinations, providerMode.
  4. Execute. Codex runs the skill, calling the repo-local Firecrawl or Composio wrappers when needed.
  5. Return. Codex delivers the artifact in chat with a summary, the main artifact, citations when available, and assumptions when grounding is incomplete.

Default disposition is chat-only. Nothing is saved to disk and nothing is pushed to an external system unless you explicitly ask.

Providers in the loop

Section titled “Providers in the loop”

Two optional providers shape what happens during execution:

  • Firecrawl is used for grounded research — search, scrape, map, crawl, and interact. If FIRECRAWL_API_KEY is present, Codex can cite sources. If it is missing, unsupported claims must be labelled as assumptions or unknown.
  • Composio is used for external writeback to Google Docs, Confluence, Linear, and GitHub. If COMPOSIO_API_KEY is present and the matching toolkit is connected, Codex can push artifacts to those systems. If not, the artifact still comes back in chat and the block is explained.

See Firecrawl API Key and Composio API Key for how to provision each provider.

What the output looks like

Section titled “What the output looks like”

Every skill returns the same response shape:

  1. A short summary.
  2. The main artifact in markdown, sectioned per the skill.
  3. Citations, when available.
  4. Assumptions or unknowns, when grounding was incomplete.
  5. Pending save or writeback actions, only if relevant.

The section list inside the artifact is skill-specific and documented on each skill’s page.

Saving and writeback

Section titled “Saving and writeback”

Both are explicit and confirmation-based.

Save

Section titled “Save”
  • Default output is chat-only.
  • Before saving generated markdown to a user-requested .md path, Codex asks for confirmation.
  • Codex only saves after confirmation, even if you mentioned a path in the initial message.

Writeback

Section titled “Writeback”
  • Codex confirms that you want the external write.
  • Codex confirms the target destination.
  • Codex verifies that COMPOSIO_API_KEY is present.
  • Codex verifies that the required toolkit is already connected.

If the toolkit is not connected, Codex presents a Connect now / Skip decision point. Connect now opens the Composio hosted login page in a browser tab when available; Codex then waits for the connection to become active before executing the write.

See Save & Writeback for the full rules.

Section titled “What to read next”