caveman-discover

You are labeling this repository's LLM workflows for Caveman Cloud. A workflow is a job the code performs — "answer a support ticket", "build the nightly digest", "run the eval suite" — not a technology. Every gateway request can carry a workflow label; unlabeled traffic all lands in one

unlabeled-workflow

bucket. Your job: find the workflows, name them well, wire the labels, and verify nothing broke.

This changes code, so it goes through the user's normal review: propose the table first, apply after the user agrees. Re-running on an already-labeled repo must change nothing (idempotent).

This skill is operator-invoked. An

unlabeled-traffic

Cave Plan observation is review-only and does not create an advisory file, proposal, or Draft PR. Do not infer that telemetry selected a callsite or authorized an edit. Independently inventory the repository, present the labeling table, and wait for the user's approval before changing code.

Step 1 — Inventory the workflows

Walk the repo from its entry points, not from its imports:

HTTP/RPC handlers that call an LLM (directly or through layers)
Scheduled jobs: cron definitions, queue consumers, workers, GitHub Actions that invoke LLM code
CLI commands and scripts (
```
scripts/
```
,
```
bin/
```
, package.json scripts)
Eval / test harnesses that burn real tokens
Distinct agents or chains inside a framework (each LangGraph graph, each crew, each agent definition is usually its own workflow)

One workflow = one job a human would name. Ten callsites inside the same request handler are one workflow; one shared

llm.ts

helper used by three jobs is three workflows (label at the callers, never the shared helper).

Step 2 — Name them

Slug grammar (the gateway enforces this): lowercase

[a-z0-9_-]

, 1–96 chars. Name the job, not the tech:

Good:

support-reply

nightly-digest

pr-review

eval-suite

onboarding-email

Bad:
```
openai-calls
```
(tech),
```
main
```
(says nothing),
```
SupportReply
```
(invalid),
```
johns-test-3
```
(won't age)

Names are forever-ish — renaming later splits the spend history. When a job's purpose isn't clear from the code, derive the slug from the file name and mark it

review

in the table rather than inventing a purpose.

Step 3 — Propose, then apply

Present this table and ask to proceed:

| workflow | job | where | how it gets labeled |
|---|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 | defaultHeaders on the reply client |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 | header on the digest client |
| eval-suite (review) | scripts/eval.ts:8 — purpose inferred from filename | scripts/eval.ts:8 | env override at invocation |

Then wire each label with the lightest mechanism available at that callsite:

@caveman-ai/sdk / caveman_cloud SDK: per-trace
```
workflow
```
option, or
```
defaultWorkflow
```
on the client a single-job service constructs.
Raw provider SDKs (OpenAI/Anthropic/LangChain/LiteLLM/Vercel): add
```
"x-cave-workflow": "<slug>"
```
to the same
```
defaultHeaders
```
/
```
default_headers
```
/
```
extra_headers
```
block that already carries
```
x-cave-api-key
```
. Shared client used by several jobs → pass the header per call (every SDK above accepts per-request header overrides), or give each job its own thin client.
Wrapped coding agents (
```
caveman wrap
```
):
```
--workflow <slug>
```
flag or
```
CAVE_WORKFLOW=<slug>
```
env at the invocation site (cron line, CI step).
Raw HTTP: add the
```
x-cave-workflow
```
header to the request.

Label the callers, keep the diff minimal, match the repo's style. If a callsite is not routed through the Caveman gateway at all, don't label it — list it under "not wired" in the report (labels only travel on gateway traffic; wiring is the caveman-setup skill's job).

Step 4 — Verify

Run whatever the repo already uses to exercise one labeled path (a test, a dev script, one curl). Then confirm: the request still succeeds (the gateway rejects an invalid label with 400

cave_invalid_request_header

— fix the slug if so). Labeled spend appears on the dashboard at

/activity?tab=workflows

as each workflow next runs; jobs on a schedule show up when the schedule fires, and that's worth saying in the report rather than pretending they're live.

Step 5 — Report

## Workflows labeled

| workflow | job | where |
|---|---|---|
| support-reply | answers inbound tickets | src/bot/reply.ts:41 |
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 |

Verified: <the labeled path you actually exercised, and what you observed>
Lands at: <DASHBOARD>/activity?tab=workflows — each row appears as that workflow
next runs. Anything still unlabeled shows as `unlabeled-workflow`.
Not wired (no gateway routing, so no label): <list or "none">
Marked review: <slugs whose purpose was inferred from filenames, or "none">

If you found no LLM entry points at all: say exactly that, and point at the setup skill (

<docs origin>/docs/agent-setup.md

) instead of manufacturing a table.

caveman-discover

NPX Install

Tags

SKILL.md Content

Step 1 — Inventory the workflows

Step 2 — Name them

Step 3 — Propose, then apply

Step 4 — Verify

Step 5 — Report