Solutioneer

Solutioneer is a Codex-native skill pack for solution engineering workflows. The primary experience is conversational: start Codex in this repo, invoke a skill, answer the next missing question, and receive the result in chat.

What Solutioneer Does

Solutioneer currently ships eight workflows for pre-sales and solution engineering:

• account-intel-brief
• discovery-context-ingester
• discovery-question-generator
• demo-scenario-builder
• architecture-fit-mapper
• integration-fit-gap-analyzer
• poc-handoff-orchestrator
• security-review-prep

These skills are designed to run inside Codex in this repository. The user-facing workflow is not npm run ....

Start Codex In This Repo

git clone <https://github.com/sushii2/solutioneer.git>
cd sun-valley
npm install
codex

Once Codex is running here, use Solutioneer directly in chat.

Install The Skills Into Codex

Repo-local skills/ folders do not automatically appear in Codex's skill picker. Install the shipped skills into ~/.codex/skills first:

npm run install-codex-skills -- --force

This copies the eight Solutioneer skills into your Codex environment.

If you prefer symlinks while developing locally:

npm run install-codex-skills -- --link --force

After installation, restart Codex so the picker reloads the installed skills.

How To Invoke A Skill

Two entrypoints are supported.

Explicit skill syntax:

$account-intel-brief Outtake.ai

Natural language:

Prepare an account brief for Outtake.ai
Normalize messy discovery notes for Outtake.ai
Build discovery questions for a RevOps lead at Outtake.ai
Build a demo scenario for Outtake.ai selling Solutioneer to a RevOps lead
Map the architecture for Outtake.ai's pilot
Can we integrate Solutioneer with Segment and HubSpot?
Turn this discovery and fit-gap into a POC handoff package
Prep a security review response for Outtake.ai

Invocation rules:

• explicit $skill ... wins over inferred routing
• the token after $skill is treated as accountSeed
• accountSeed may be a company domain, company name, or product name
• if the user request is ambiguous, Codex should ask one routing question before continuing

What Happens In A Run

The canonical flow is:

1. Codex routes the request to one of the eight shipped skills.
2. Codex asks only the next missing question.
3. Codex normalizes the conversation into the shared internal runtime shape.
4. Codex uses repo-local Firecrawl or Composio helpers when needed.
5. Codex returns the artifact in chat.

Default behavior:

• output is chat-only
• nothing is saved by default
• nothing is pushed externally by default

Shipped Skills

account-intel-brief

Use for pre-call account research.

Expected output:

• summary
• company snapshot
• stack signals
• likely initiatives
• discovery questions
• citations or assumptions

discovery-context-ingester

Use for messy discovery notes, transcripts, and connected private-source ingestion.

Expected output:

• summary
• discovery fact sheet
• source index
• unknowns
• citations or assumptions

discovery-question-generator

Use for next-call discovery prep from a fact sheet.

Expected output:

• summary
• discovery plan
• stakeholder questions
• signal scorecard
• red flags
• citations or assumptions

demo-scenario-builder

Use for tailored demo prep.

Expected output:

• summary
• demo narrative
• talk track
• likely objections
• deterministic seed data
• fallback plan
• citations or assumptions

architecture-fit-mapper

Use for solution architecture mapping and validation planning.

Expected output:

• summary
• architecture map
• diagram
• fit analysis
• blockers
• required validations
• citations or assumptions

integration-fit-gap-analyzer

Use for cited integration assessment.

Expected output:

• fit-gap summary
• support/workaround/gap/unknown matrix
• open questions
• risks
• citations or unknowns

poc-handoff-orchestrator

Use for pre-sales to delivery handoff.

Expected output:

• summary
• POC plan
• architecture note
• milestones
• risks
• dependencies
• citations or assumptions

security-review-prep

Use for security questionnaires, control mapping, and follow-up prep.

Expected output:

• summary
• security response brief
• control matrix
• customer follow-ups
• escalation gaps
• citations or assumptions

One-Question Intake

Solutioneer skills are intentionally narrow in how they collect inputs.

Rules:

• ask one question at a time
• ask only the next highest-value missing question
• do not ask the user to provide raw JSON
• do not ask for every field up front if the next step can proceed with less

This keeps the Codex workflow conversational instead of turning the user into a form filler.

Provider Configuration

Optional provider keys are loaded in this order:

1. .env
2. .env.local
3. process.env overrides file values

Example:

cp .env.example .env

FIRECRAWL_API_KEY=fc-...
COMPOSIO_API_KEY=cmp-...

What Happens When Keys Are Missing

If FIRECRAWL_API_KEY is missing:

• research stays local-only
• unsupported external claims must be marked as assumptions or unknown
• Solutioneer must not freehand account or vendor facts

If COMPOSIO_API_KEY is missing:

• external writeback is disabled
• Google Docs, Confluence, Linear, and GitHub writes should not be attempted
• discovery ingest from HubSpot, Slack, Gmail, and Google Drive stays pending
• the artifact can still be returned in chat

External Writeback And Composio Connections

External writes are explicit and confirmation-based.

Supported toolkit families:

• googlesuper for Google Docs / Sheets
• confluence
• linear
• github

Read-side discovery ingest in v1:

• hubspot
• slack
• gmail
• googledrive
• granola_mcp only when auth is already preconfigured

If writeback is requested, Solutioneer should:

1. confirm that the user wants the external write
2. confirm the target destination
3. check whether COMPOSIO_API_KEY is available
4. check whether the required toolkit is already connected

If the toolkit is not connected, Codex should present:

• Connect now
• Skip external writeback

Behavior:

• Connect now opens the Composio hosted login page in a browser tab when available
• Codex waits for the user to complete login
• Codex polls the connected account until it becomes active
• Codex does not execute the external write before the connection is active
• if browser tooling is unavailable, Codex can provide the link in chat and wait there instead
• Skip external writeback keeps the workflow chat-only

Save Confirmation

Local save is also explicit.

Rules:

• default output is chat-only
• before saving markdown to a user-requested .md path, ask for confirmation
• save only after confirmation

This applies even when the artifact already exists in chat.

Grounding Rules

Every external-facing factual claim must either:

• cite a Firecrawl-derived source
• cite a private-source provenance URL such as local://... or composio://...
• or be labeled as an assumption / unknown

Never freehand:

• account facts
• vendor claims
• integration support claims
• product or security assertions

Repo Layout

Key directories:

skills/             Skill definitions and templates
tools/core/         Shared runtime, env, and conversational helpers
tools/firecrawl/    Firecrawl wrappers
tools/composio/     Composio wrappers and connection helpers
tools/skills/       Skill execution logic
tests/              Verification for runtime and docs behavior

Developer-Only Commands

These commands are for validating the helper layer, not for normal end-user skill invocation:

npm test
npm run typecheck
npm run build

Documentation Site

An Astro + Starlight documentation site lives in docs/.

Run locally:

cd docs
npm install
npm run dev

Build static output:

cd docs
npm run build

Deploying to Vercel

The repo ships a root-level vercel.json that tells Vercel to build the docs site from the docs/ subdirectory. After importing this repo into Vercel, no additional configuration is required — the build command, install command, and output directory are already wired up.