@izhimu/pi-caveman 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +36 -44
- package/extensions/caveman.ts +101 -149
- package/package.json +5 -1
- package/skills/caveman/README.md +52 -48
- package/skills/caveman/SKILL.md +3 -1
- package/skills/caveman-compress/README.md +42 -29
- package/skills/caveman-compress/scripts/compress.py +113 -22
- package/skills/caveman-compress/scripts/validate.py +193 -6
- package/skills/cavecrew/README.md +0 -61
- package/skills/cavecrew/SKILL.md +0 -82
- package/skills/caveman-commit/README.md +0 -44
- package/skills/caveman-commit/SKILL.md +0 -65
- package/skills/caveman-discover/SKILL.md +0 -118
- package/skills/caveman-evidence-review/SKILL.md +0 -144
- package/skills/caveman-explore/SKILL.md +0 -42
- package/skills/caveman-explore/package.json +0 -12
- package/skills/caveman-explore/tests/skill-file.test.mjs +0 -44
- package/skills/caveman-help/README.md +0 -38
- package/skills/caveman-help/SKILL.md +0 -63
- package/skills/caveman-learn/CLAUDE.md +0 -32
- package/skills/caveman-learn/README.md +0 -29
- package/skills/caveman-learn/SKILL.md +0 -69
- package/skills/caveman-learn/package.json +0 -12
- package/skills/caveman-learn/tests/skill-file.test.mjs +0 -44
- package/skills/caveman-manage/SKILL.md +0 -114
- package/skills/caveman-optimize/SKILL.md +0 -114
- package/skills/caveman-review/README.md +0 -33
- package/skills/caveman-review/SKILL.md +0 -55
- package/skills/caveman-setup/SKILL.md +0 -224
- package/skills/caveman-stats/README.md +0 -36
- package/skills/caveman-stats/SKILL.md +0 -12
- package/skills/investigate-first/SKILL.md +0 -16
- package/skills/investigate-first/agents/openai.yaml +0 -4
- package/skills/lean-build/SKILL.md +0 -18
- package/skills/lean-build/agents/openai.yaml +0 -4
- package/skills/migration/SKILL.md +0 -17
- package/skills/migration/agents/openai.yaml +0 -4
- package/skills/safe-refactor/SKILL.md +0 -16
- package/skills/safe-refactor/agents/openai.yaml +0 -4
- package/skills/surgical-patch/SKILL.md +0 -16
- package/skills/surgical-patch/agents/openai.yaml +0 -4
- package/skills/verify-and-stop/SKILL.md +0 -16
- package/skills/verify-and-stop/agents/openai.yaml +0 -4
|
@@ -1,61 +0,0 @@
|
|
|
1
|
-
# cavecrew
|
|
2
|
-
|
|
3
|
-
Decision guide. When to delegate to caveman subagents instead of doing the work inline.
|
|
4
|
-
|
|
5
|
-
## What it does
|
|
6
|
-
|
|
7
|
-
Tells the main thread when to spawn a caveman-style subagent versus the vanilla equivalent. The win: subagent tool-results inject back into main context verbatim, and caveman output is roughly 1/3 the size of vanilla prose. Across 20 delegations in one session, that is the difference between context exhaustion and finishing the task.
|
|
8
|
-
|
|
9
|
-
Three subagents:
|
|
10
|
-
|
|
11
|
-
| Subagent | Job | Use when |
|
|
12
|
-
|----------|-----|----------|
|
|
13
|
-
| `cavecrew-investigator` | Locate code (read-only) | "Where is X defined / what calls Y / list uses of Z" |
|
|
14
|
-
| `cavecrew-builder` | Surgical edit, 1-2 files | Scope is obvious, ≤2 files. Refuses 3+ file scope. |
|
|
15
|
-
| `cavecrew-reviewer` | Diff/file review | One-line findings with severity emoji |
|
|
16
|
-
|
|
17
|
-
Use vanilla `Explore` or `Code Reviewer` when you want prose, architecture commentary, or rationale. Use main thread directly for one-line answers and 3+ file refactors.
|
|
18
|
-
|
|
19
|
-
This skill is a decision guide, not a slash command. It activates when the conversation mentions delegation.
|
|
20
|
-
|
|
21
|
-
## How to invoke
|
|
22
|
-
|
|
23
|
-
Triggers on phrases like "delegate to subagent", "use cavecrew", "spawn investigator", "save context", "compressed agent output".
|
|
24
|
-
|
|
25
|
-
## Example chaining
|
|
26
|
-
|
|
27
|
-
Locate → fix → verify (most common):
|
|
28
|
-
|
|
29
|
-
1. `cavecrew-investigator` returns site list (`path:line — symbol — note`)
|
|
30
|
-
2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`
|
|
31
|
-
3. `cavecrew-reviewer` audits the resulting diff
|
|
32
|
-
|
|
33
|
-
Parallel scout: spawn 2-3 `cavecrew-investigator` calls in one message with different angles (defs, callers, tests). Aggregate in main.
|
|
34
|
-
|
|
35
|
-
## Model overrides
|
|
36
|
-
|
|
37
|
-
By default, `cavecrew-reviewer` and `cavecrew-investigator` pin `model: haiku` in their frontmatter; `cavecrew-builder` has no `model:` line (uses the API session default). Set env vars in your shell before launching Claude Code to override per-agent:
|
|
38
|
-
|
|
39
|
-
| Env var | Agent |
|
|
40
|
-
|---|---|
|
|
41
|
-
| `CAVECREW_REVIEWER_MODEL` | `cavecrew-reviewer` |
|
|
42
|
-
| `CAVECREW_BUILDER_MODEL` | `cavecrew-builder` |
|
|
43
|
-
| `CAVECREW_INVESTIGATOR_MODEL` | `cavecrew-investigator` |
|
|
44
|
-
|
|
45
|
-
Example — run reviewer on sonnet, keep others on default:
|
|
46
|
-
|
|
47
|
-
```sh
|
|
48
|
-
export CAVECREW_REVIEWER_MODEL=sonnet
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
Use the same model name strings you'd use in any Claude Code agent frontmatter (e.g. `haiku`, `sonnet`, `opus`).
|
|
52
|
-
|
|
53
|
-
Overrides patch only the `model:` line in the installed agent's frontmatter; the prompt body is untouched and keeps receiving upstream updates. Plugin installs only — standalone hook installs have no local agent files to patch. Unset or blank = no change. The patch persists in the installed file until the plugin is updated or reinstalled.
|
|
54
|
-
|
|
55
|
-
## See also
|
|
56
|
-
|
|
57
|
-
- [`SKILL.md`](./SKILL.md) — full decision matrix and output contracts
|
|
58
|
-
- [`agents/cavecrew-investigator.md`](../../agents/cavecrew-investigator.md)
|
|
59
|
-
- [`agents/cavecrew-builder.md`](../../agents/cavecrew-builder.md)
|
|
60
|
-
- [`agents/cavecrew-reviewer.md`](../../agents/cavecrew-reviewer.md)
|
|
61
|
-
- [Caveman README](../../README.md) — repo overview
|
package/skills/cavecrew/SKILL.md
DELETED
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: cavecrew
|
|
3
|
-
description: >
|
|
4
|
-
Decision guide for delegating to caveman-style subagents. Tells the main
|
|
5
|
-
thread WHEN to spawn `cavecrew-investigator` (locate code), `cavecrew-builder`
|
|
6
|
-
(1-2 file edit), or `cavecrew-reviewer` (diff review) instead of doing the
|
|
7
|
-
work inline or using vanilla `Explore`. Subagent output is caveman-compressed
|
|
8
|
-
so the tool-result injected back into main context is ~60% smaller — main
|
|
9
|
-
context lasts longer across long sessions.
|
|
10
|
-
Trigger: "delegate to subagent", "use cavecrew", "spawn investigator/builder/reviewer",
|
|
11
|
-
"save context", "compressed agent output".
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation.
|
|
15
|
-
|
|
16
|
-
## When to use cavecrew vs alternatives
|
|
17
|
-
|
|
18
|
-
| Task | Use |
|
|
19
|
-
|---|---|
|
|
20
|
-
| "Where is X defined / what calls Y / list uses of Z" | `cavecrew-investigator` |
|
|
21
|
-
| Same but you also want suggestions/architecture commentary | `Explore` (vanilla) |
|
|
22
|
-
| Surgical edit, ≤2 files, scope obvious | `cavecrew-builder` |
|
|
23
|
-
| New feature / 3+ files / cross-cutting refactor | Main thread or `feature-dev:code-architect` |
|
|
24
|
-
| Review diff, branch, or file for bugs | `cavecrew-reviewer` |
|
|
25
|
-
| Deep code review with rationale + alternatives | `Code Reviewer` (vanilla) |
|
|
26
|
-
| One-line answer you already know | Main thread, no subagent |
|
|
27
|
-
|
|
28
|
-
Rule of thumb: **if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla.**
|
|
29
|
-
|
|
30
|
-
## Why this exists (the real win)
|
|
31
|
-
|
|
32
|
-
Subagent tool results get injected into main context verbatim. A vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from `cavecrew-investigator` returns ~700 tokens. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task.
|
|
33
|
-
|
|
34
|
-
## Output contracts
|
|
35
|
-
|
|
36
|
-
What main thread can rely on per agent:
|
|
37
|
-
|
|
38
|
-
**`cavecrew-investigator`**
|
|
39
|
-
```
|
|
40
|
-
<Header>:
|
|
41
|
-
- path:line — `symbol` — short note
|
|
42
|
-
totals: <counts>.
|
|
43
|
-
```
|
|
44
|
-
Or `No match.` Always file-path-first, line-number-attached, backticked symbols. Safe to grep with `path:\d+`.
|
|
45
|
-
|
|
46
|
-
**`cavecrew-builder`**
|
|
47
|
-
```
|
|
48
|
-
<path:line-range> — <change ≤10 words>.
|
|
49
|
-
verified: <re-read OK | mismatch @ path:line>.
|
|
50
|
-
```
|
|
51
|
-
Or one of: `too-big.` / `needs-confirm.` / `ambiguous.` / `regressed.` (terminal first token).
|
|
52
|
-
|
|
53
|
-
**`cavecrew-reviewer`**
|
|
54
|
-
```
|
|
55
|
-
path:line: <emoji> <severity>: <problem>. <fix>.
|
|
56
|
-
totals: N🔴 N🟡 N🔵 N❓
|
|
57
|
-
```
|
|
58
|
-
Or `No issues.` Findings sorted file → line ascending.
|
|
59
|
-
|
|
60
|
-
## Chaining patterns
|
|
61
|
-
|
|
62
|
-
**Locate → fix → verify** (most common):
|
|
63
|
-
1. `cavecrew-investigator` returns site list.
|
|
64
|
-
2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`.
|
|
65
|
-
3. `cavecrew-reviewer` audits the diff.
|
|
66
|
-
|
|
67
|
-
**Parallel scout** (when investigation is broad):
|
|
68
|
-
Spawn 2-3 `cavecrew-investigator` calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread.
|
|
69
|
-
|
|
70
|
-
**Single-shot edit** (when site is already known):
|
|
71
|
-
Skip investigator. Hand exact path:line to `cavecrew-builder` directly.
|
|
72
|
-
|
|
73
|
-
## What NOT to do
|
|
74
|
-
|
|
75
|
-
- Don't use `cavecrew-builder` when you don't already know the file. Spawn investigator first or main thread will eat tokens passing context.
|
|
76
|
-
- Don't chain `cavecrew-investigator → cavecrew-builder` for a 5-file refactor. Builder will return `too-big.` and you'll have wasted a turn.
|
|
77
|
-
- Don't ask `cavecrew-reviewer` for "general feedback" — it returns findings only, no architecture opinions. Use `Code Reviewer` for that.
|
|
78
|
-
- Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase.
|
|
79
|
-
|
|
80
|
-
## Auto-clarity (inherited)
|
|
81
|
-
|
|
82
|
-
Subagents drop caveman → normal English for security warnings, irreversible-action confirmations, and any output where fragment ambiguity could be misread. Resume caveman after.
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
# caveman-commit
|
|
2
|
-
|
|
3
|
-
Terse Conventional Commits. Why over what.
|
|
4
|
-
|
|
5
|
-
## What it does
|
|
6
|
-
|
|
7
|
-
Generates commit messages in Conventional Commits format. Subject ≤50 chars, hard cap 72. Imperative mood. Body only when the *why* is non-obvious or there are breaking changes. No AI attribution, no "this commit does X", no emoji unless the project uses them. Body always required for breaking changes, security fixes, data migrations, and reverts — future debuggers need the context.
|
|
8
|
-
|
|
9
|
-
Outputs only the message. Does not stage, commit, or amend.
|
|
10
|
-
|
|
11
|
-
## How to invoke
|
|
12
|
-
|
|
13
|
-
```
|
|
14
|
-
/caveman-commit
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
Also triggers on phrases like "write a commit", "commit message", "generate commit".
|
|
18
|
-
|
|
19
|
-
## Example output
|
|
20
|
-
|
|
21
|
-
Diff: new endpoint for user profile.
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
feat(api): add GET /users/:id/profile
|
|
25
|
-
|
|
26
|
-
Mobile client needs profile data without the full user payload
|
|
27
|
-
to reduce LTE bandwidth on cold-launch screens.
|
|
28
|
-
|
|
29
|
-
Closes #128
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
Diff: breaking API rename.
|
|
33
|
-
|
|
34
|
-
```
|
|
35
|
-
feat(api)!: rename /v1/orders to /v1/checkout
|
|
36
|
-
|
|
37
|
-
BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
|
|
38
|
-
before 2026-06-01. Old route returns 410 after that date.
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## See also
|
|
42
|
-
|
|
43
|
-
- [`SKILL.md`](./SKILL.md) — full LLM-facing instructions
|
|
44
|
-
- [Caveman README](../../README.md) — repo overview
|
|
@@ -1,65 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: caveman-commit
|
|
3
|
-
description: >
|
|
4
|
-
Ultra-compressed commit message generator. Cuts noise from commit messages while preserving
|
|
5
|
-
intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why"
|
|
6
|
-
isn't obvious. Use when user says "write a commit", "commit message", "generate commit",
|
|
7
|
-
"/commit", or invokes /caveman-commit. Auto-triggers when staging changes.
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
Write commit messages terse and exact. Conventional Commits format. No fluff. Why over what.
|
|
11
|
-
|
|
12
|
-
## Rules
|
|
13
|
-
|
|
14
|
-
**Subject line:**
|
|
15
|
-
- `<type>(<scope>): <imperative summary>` — `<scope>` optional
|
|
16
|
-
- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`
|
|
17
|
-
- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
|
|
18
|
-
- ≤50 chars when possible, hard cap 72
|
|
19
|
-
- No trailing period
|
|
20
|
-
- Match project convention for capitalization after the colon
|
|
21
|
-
|
|
22
|
-
**Body (only if needed):**
|
|
23
|
-
- Skip entirely when subject is self-explanatory
|
|
24
|
-
- Add body only for: non-obvious *why*, breaking changes, migration notes, linked issues
|
|
25
|
-
- Wrap at 72 chars
|
|
26
|
-
- Bullets `-` not `*`
|
|
27
|
-
- Reference issues/PRs at end: `Closes #42`, `Refs #17`
|
|
28
|
-
|
|
29
|
-
**What NEVER goes in:**
|
|
30
|
-
- "This commit does X", "I", "we", "now", "currently" — the diff says what
|
|
31
|
-
- "As requested by..." — use Co-authored-by trailer
|
|
32
|
-
- "Generated with Claude Code" or any AI attribution — unless the user's own rule requires an `Assisted-by`/AI-attribution trailer, then add it as a trailer
|
|
33
|
-
- Emoji (unless project convention requires)
|
|
34
|
-
- Restating the file name when scope already says it
|
|
35
|
-
|
|
36
|
-
## Examples
|
|
37
|
-
|
|
38
|
-
Diff: new endpoint for user profile with body explaining the why
|
|
39
|
-
- ❌ "feat: add a new endpoint to get user profile information from the database"
|
|
40
|
-
- ✅
|
|
41
|
-
```
|
|
42
|
-
feat(api): add GET /users/:id/profile
|
|
43
|
-
|
|
44
|
-
Mobile client needs profile data without the full user payload
|
|
45
|
-
to reduce LTE bandwidth on cold-launch screens.
|
|
46
|
-
|
|
47
|
-
Closes #128
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
Diff: breaking API change
|
|
51
|
-
- ✅
|
|
52
|
-
```
|
|
53
|
-
feat(api)!: rename /v1/orders to /v1/checkout
|
|
54
|
-
|
|
55
|
-
BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
|
|
56
|
-
before 2026-06-01. Old route returns 410 after that date.
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
## Auto-Clarity
|
|
60
|
-
|
|
61
|
-
Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context.
|
|
62
|
-
|
|
63
|
-
## Boundaries
|
|
64
|
-
|
|
65
|
-
Only generates the commit message. Does not run `git commit`, does not stage files, does not amend. Output the message as a code block ready to paste. "stop caveman-commit" or "normal mode": revert to verbose commit style.
|
|
@@ -1,118 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: caveman-discover
|
|
3
|
-
description: >
|
|
4
|
-
Find every LLM workflow in the current repository and label it, so Caveman
|
|
5
|
-
Cloud groups spend by what the code actually does (support-reply,
|
|
6
|
-
nightly-digest) instead of one anonymous bucket. Use when the user pastes
|
|
7
|
-
the Caveman discovery prompt, says "discover workflows", or asks to break
|
|
8
|
-
LLM spend down by workflow. The repo should already route through the
|
|
9
|
-
Caveman gateway (the caveman-setup skill does that part).
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
You are labeling this repository's LLM workflows for Caveman Cloud. A
|
|
13
|
-
*workflow* is a job the code performs — "answer a support ticket", "build the
|
|
14
|
-
nightly digest", "run the eval suite" — not a technology. Every gateway
|
|
15
|
-
request can carry a workflow label; unlabeled traffic all lands in one
|
|
16
|
-
`unlabeled-workflow` bucket. Your job: find the workflows, name them well,
|
|
17
|
-
wire the labels, and verify nothing broke.
|
|
18
|
-
|
|
19
|
-
This changes code, so it goes through the user's normal review: **propose the
|
|
20
|
-
table first, apply after the user agrees.** Re-running on an already-labeled
|
|
21
|
-
repo must change nothing (idempotent).
|
|
22
|
-
|
|
23
|
-
This skill is operator-invoked. An `unlabeled-traffic` Cave Plan observation is
|
|
24
|
-
review-only and does not create an advisory file, proposal, or Draft PR. Do not
|
|
25
|
-
infer that telemetry selected a callsite or authorized an edit. Independently
|
|
26
|
-
inventory the repository, present the labeling table, and wait for the user's
|
|
27
|
-
approval before changing code.
|
|
28
|
-
|
|
29
|
-
## Step 1 — Inventory the workflows
|
|
30
|
-
|
|
31
|
-
Walk the repo from its entry points, not from its imports:
|
|
32
|
-
|
|
33
|
-
- HTTP/RPC handlers that call an LLM (directly or through layers)
|
|
34
|
-
- Scheduled jobs: cron definitions, queue consumers, workers, GitHub Actions
|
|
35
|
-
that invoke LLM code
|
|
36
|
-
- CLI commands and scripts (`scripts/`, `bin/`, package.json scripts)
|
|
37
|
-
- Eval / test harnesses that burn real tokens
|
|
38
|
-
- Distinct agents or chains inside a framework (each LangGraph graph, each
|
|
39
|
-
crew, each agent definition is usually its own workflow)
|
|
40
|
-
|
|
41
|
-
One workflow = one job a human would name. Ten callsites inside the same
|
|
42
|
-
request handler are one workflow; one shared `llm.ts` helper used by three
|
|
43
|
-
jobs is three workflows (label at the callers, never the shared helper).
|
|
44
|
-
|
|
45
|
-
## Step 2 — Name them
|
|
46
|
-
|
|
47
|
-
Slug grammar (the gateway enforces this): lowercase `[a-z0-9_-]`, 1–96 chars.
|
|
48
|
-
Name the job, not the tech:
|
|
49
|
-
|
|
50
|
-
- Good: `support-reply`, `nightly-digest`, `pr-review`, `eval-suite`,
|
|
51
|
-
`onboarding-email`
|
|
52
|
-
- Bad: `openai-calls` (tech), `main` (says nothing), `SupportReply` (invalid),
|
|
53
|
-
`johns-test-3` (won't age)
|
|
54
|
-
|
|
55
|
-
Names are forever-ish — renaming later splits the spend history. When a job's
|
|
56
|
-
purpose isn't clear from the code, derive the slug from the file name and mark
|
|
57
|
-
it `review` in the table rather than inventing a purpose.
|
|
58
|
-
|
|
59
|
-
## Step 3 — Propose, then apply
|
|
60
|
-
|
|
61
|
-
Present this table and ask to proceed:
|
|
62
|
-
|
|
63
|
-
```
|
|
64
|
-
| workflow | job | where | how it gets labeled |
|
|
65
|
-
|---|---|---|---|
|
|
66
|
-
| support-reply | answers inbound tickets | src/bot/reply.ts:41 | defaultHeaders on the reply client |
|
|
67
|
-
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 | header on the digest client |
|
|
68
|
-
| eval-suite (review) | scripts/eval.ts:8 — purpose inferred from filename | scripts/eval.ts:8 | env override at invocation |
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
Then wire each label with the lightest mechanism available at that callsite:
|
|
72
|
-
|
|
73
|
-
- **@caveman-ai/sdk / caveman_cloud SDK**: per-trace `workflow` option, or
|
|
74
|
-
`defaultWorkflow` on the client a single-job service constructs.
|
|
75
|
-
- **Raw provider SDKs** (OpenAI/Anthropic/LangChain/LiteLLM/Vercel): add
|
|
76
|
-
`"x-cave-workflow": "<slug>"` to the same `defaultHeaders` /
|
|
77
|
-
`default_headers` / `extra_headers` block that already carries
|
|
78
|
-
`x-cave-api-key`. Shared client used by several jobs → pass the header per
|
|
79
|
-
call (every SDK above accepts per-request header overrides), or give each
|
|
80
|
-
job its own thin client.
|
|
81
|
-
- **Wrapped coding agents** (`caveman wrap`): `--workflow <slug>` flag or
|
|
82
|
-
`CAVE_WORKFLOW=<slug>` env at the invocation site (cron line, CI step).
|
|
83
|
-
- **Raw HTTP**: add the `x-cave-workflow` header to the request.
|
|
84
|
-
|
|
85
|
-
Label the callers, keep the diff minimal, match the repo's style. If a
|
|
86
|
-
callsite is not routed through the Caveman gateway at all, don't label it —
|
|
87
|
-
list it under "not wired" in the report (labels only travel on gateway
|
|
88
|
-
traffic; wiring is the caveman-setup skill's job).
|
|
89
|
-
|
|
90
|
-
## Step 4 — Verify
|
|
91
|
-
|
|
92
|
-
Run whatever the repo already uses to exercise one labeled path (a test, a
|
|
93
|
-
dev script, one curl). Then confirm: the request still succeeds (the gateway
|
|
94
|
-
rejects an invalid label with 400 `cave_invalid_request_header` — fix the slug
|
|
95
|
-
if so). Labeled spend appears on the dashboard at `/activity?tab=workflows` as
|
|
96
|
-
each workflow next runs; jobs on a schedule show up when the schedule fires,
|
|
97
|
-
and that's worth saying in the report rather than pretending they're live.
|
|
98
|
-
|
|
99
|
-
## Step 5 — Report
|
|
100
|
-
|
|
101
|
-
```
|
|
102
|
-
## Workflows labeled
|
|
103
|
-
|
|
104
|
-
| workflow | job | where |
|
|
105
|
-
|---|---|---|
|
|
106
|
-
| support-reply | answers inbound tickets | src/bot/reply.ts:41 |
|
|
107
|
-
| nightly-digest | 02:00 summary job | jobs/digest.ts:12 |
|
|
108
|
-
|
|
109
|
-
Verified: <the labeled path you actually exercised, and what you observed>
|
|
110
|
-
Lands at: <DASHBOARD>/activity?tab=workflows — each row appears as that workflow
|
|
111
|
-
next runs. Anything still unlabeled shows as `unlabeled-workflow`.
|
|
112
|
-
Not wired (no gateway routing, so no label): <list or "none">
|
|
113
|
-
Marked review: <slugs whose purpose was inferred from filenames, or "none">
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
If you found no LLM entry points at all: say exactly that, and point at the
|
|
117
|
-
setup skill (`<docs origin>/docs/agent-setup.md`) instead of manufacturing a
|
|
118
|
-
table.
|
|
@@ -1,144 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: caveman-evidence-review
|
|
3
|
-
description: >
|
|
4
|
-
Review Caveman Cloud evidence read-only: costs, Cave Score, Cave Plan,
|
|
5
|
-
workflows, traces, latency, errors, compression, routing, and verified
|
|
6
|
-
savings. Use when the user asks what Caveman found, where LLM spend goes,
|
|
7
|
-
why cost or quality changed, which workflows need attention, or asks for a
|
|
8
|
-
trace or analytics review. Prefer Caveman MCP tools; fall back to CLI JSON.
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
# Review Caveman evidence
|
|
12
|
-
|
|
13
|
-
Act as a read-only operator. Build conclusions from current Caveman data, not
|
|
14
|
-
from repository guesses. Never start, approve, cancel, or roll back an
|
|
15
|
-
experiment from this skill.
|
|
16
|
-
|
|
17
|
-
## Hard rules
|
|
18
|
-
|
|
19
|
-
1. Keep these buckets separate:
|
|
20
|
-
- measured provider-complete list-price cost;
|
|
21
|
-
- `inferred` daily headroom;
|
|
22
|
-
- `verified` ledger savings;
|
|
23
|
-
- evidence cost.
|
|
24
|
-
Never add or relabel them.
|
|
25
|
-
2. Do not fetch prompt, completion, tool, or artifact payloads unless the user
|
|
26
|
-
explicitly asks for payload review. Metadata, spans, timing, models, token
|
|
27
|
-
counts, status, and optimizer attribution are enough for the default review.
|
|
28
|
-
3. Scope every read to the project selected by Caveman context. Never supply an
|
|
29
|
-
organization id.
|
|
30
|
-
4. Empty results are evidence of no current signal, not zero cost or zero risk.
|
|
31
|
-
5. Cite trace ids and exact time windows used. Do not claim a cause from an
|
|
32
|
-
aggregate alone.
|
|
33
|
-
|
|
34
|
-
## Step 1 — Load context
|
|
35
|
-
|
|
36
|
-
Prefer MCP:
|
|
37
|
-
|
|
38
|
-
```text
|
|
39
|
-
caveman_context {}
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
CLI fallback:
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
caveman cloud whoami
|
|
46
|
-
caveman cloud projects list
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
Stop if login or project selection is missing. Ask the user to run
|
|
50
|
-
`caveman login` or select a project; never guess.
|
|
51
|
-
|
|
52
|
-
## Step 2 — Establish baseline
|
|
53
|
-
|
|
54
|
-
Use `caveman_report` for:
|
|
55
|
-
|
|
56
|
-
- `overview`
|
|
57
|
-
- `costs`
|
|
58
|
-
- `score`
|
|
59
|
-
- `workflows`
|
|
60
|
-
- `verified_savings`
|
|
61
|
-
|
|
62
|
-
Then use `caveman_plan` for ranked daily headroom. If question is narrow, skip
|
|
63
|
-
unrelated reports. Read shortest set that can answer it.
|
|
64
|
-
|
|
65
|
-
CLI fallback:
|
|
66
|
-
|
|
67
|
-
```bash
|
|
68
|
-
caveman cloud costs
|
|
69
|
-
caveman cloud score
|
|
70
|
-
caveman cloud plan --json
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
State report window and basis before interpreting direction.
|
|
74
|
-
|
|
75
|
-
## Step 3 — Test the leading explanation with traces
|
|
76
|
-
|
|
77
|
-
Use `caveman_trace_search`. Choose a bounded window and closed filters:
|
|
78
|
-
workflow, agent, model, provider, error code, runtime mode, cache status,
|
|
79
|
-
optimization id, status class, token/cost/latency bounds, compression, or
|
|
80
|
-
monitor verdict.
|
|
81
|
-
|
|
82
|
-
Useful groupings:
|
|
83
|
-
|
|
84
|
-
- `workflow` — find jobs driving cost or failures;
|
|
85
|
-
- `model` — compare model mix;
|
|
86
|
-
- `session` — isolate retry or loop behavior;
|
|
87
|
-
- ungrouped — identify exact traces.
|
|
88
|
-
|
|
89
|
-
Compare a suspect cohort with a control cohort or earlier bounded window.
|
|
90
|
-
Do not infer causality from one expensive trace.
|
|
91
|
-
|
|
92
|
-
CLI fallback:
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
caveman cloud traces search \
|
|
96
|
-
--workflow <slug> \
|
|
97
|
-
--from <RFC3339> \
|
|
98
|
-
--to <RFC3339> \
|
|
99
|
-
--sort total_cost_usd \
|
|
100
|
-
--dir desc \
|
|
101
|
-
--limit 25
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
## Step 4 — Inspect representative traces
|
|
105
|
-
|
|
106
|
-
Call `caveman_trace_get` for a small number of high-signal trace ids. Inspect
|
|
107
|
-
request and span metadata, latency, status, token counts, cache state, applied
|
|
108
|
-
optimizers, and model route. Keep payload retrieval off.
|
|
109
|
-
|
|
110
|
-
CLI fallback:
|
|
111
|
-
|
|
112
|
-
```bash
|
|
113
|
-
caveman cloud traces show <trace-id> --spans
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
## Step 5 — Report
|
|
117
|
-
|
|
118
|
-
Use this shape:
|
|
119
|
-
|
|
120
|
-
```text
|
|
121
|
-
## Caveman evidence review
|
|
122
|
-
|
|
123
|
-
Scope: <project> · <from> to <to>
|
|
124
|
-
Measured cost: <value and basis>
|
|
125
|
-
Verified savings: <ledger value, kept separate>
|
|
126
|
-
Inferred headroom: <per-day band, kept separate>
|
|
127
|
-
|
|
128
|
-
Findings:
|
|
129
|
-
1. <finding> — <aggregate evidence> — traces <ids>
|
|
130
|
-
2. <finding> — <aggregate evidence> — traces <ids>
|
|
131
|
-
|
|
132
|
-
Unproven:
|
|
133
|
-
- <plausible explanation lacking a control, trace, or eval>
|
|
134
|
-
|
|
135
|
-
Next read-only check:
|
|
136
|
-
- <one bounded query>
|
|
137
|
-
|
|
138
|
-
Possible action:
|
|
139
|
-
- <proposal only; use caveman-manage for read-only lifecycle review and safety gate>
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
If data is missing, name missing signal and stop at strongest supported
|
|
143
|
-
statement. Never turn a catalog subtotal into an invoice or an experiment result
|
|
144
|
-
into verified savings.
|
|
@@ -1,42 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: caveman-explore
|
|
3
|
-
description: Read-only repository explorer. Use PROACTIVELY for cold-start exploration, broad cross-file localization, or when a direct search has failed and you need to find where something lives. Skip it when the issue already names the exact file or symbol, or a previous turn already returned usable file:line evidence. Returns only compact path:line citations; its reads and greps never enter the main conversation.
|
|
4
|
-
tools: Read, Glob, Grep
|
|
5
|
-
model: haiku
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
You are FastContext, a fast, cheap, read-only repository explorer. Another agent
|
|
9
|
-
(the solver) delegates a localization question to you. Your only job is to find
|
|
10
|
-
WHERE the relevant code lives and report it as a compact list of file paths with
|
|
11
|
-
line ranges. You never edit files, run commands, or propose a solution.
|
|
12
|
-
|
|
13
|
-
How to work:
|
|
14
|
-
|
|
15
|
-
1. Issue several tool calls IN PARALLEL in your first turn — cast a broad net.
|
|
16
|
-
Cover complementary hypotheses at once: likely path patterns (Glob), symbol and
|
|
17
|
-
string matches (Grep), and reading the most promising files (Read). Do not probe
|
|
18
|
-
one file at a time when you can fan out.
|
|
19
|
-
2. Follow the evidence over one or two more turns only if needed. Stop as soon as
|
|
20
|
-
you can name the relevant locations. You are optimizing for the solver's token
|
|
21
|
-
budget, so finish fast.
|
|
22
|
-
3. Only cite line ranges you actually read. Never invent or estimate a range, and
|
|
23
|
-
never cite a range past the end of a file. A precise small range beats a vague
|
|
24
|
-
large one.
|
|
25
|
-
|
|
26
|
-
Your reply MUST be ONLY an evidence block: one citation per line, nothing else.
|
|
27
|
-
No preamble, no explanation, no summary, no markdown headings. Use exactly this
|
|
28
|
-
shape, one per line:
|
|
29
|
-
|
|
30
|
-
path/to/file.ext:START-END reason it is relevant
|
|
31
|
-
|
|
32
|
-
Example reply:
|
|
33
|
-
|
|
34
|
-
src/router/pick.go:42-71 route selection — where a model is chosen
|
|
35
|
-
src/router/pick_test.go:18-40 the table test covering pick()
|
|
36
|
-
|
|
37
|
-
If you genuinely cannot find anything relevant, reply with the single line:
|
|
38
|
-
|
|
39
|
-
no relevant locations found
|
|
40
|
-
|
|
41
|
-
That honest answer is better than a guess. The solver reads your citations and
|
|
42
|
-
nothing else from your work, so keep the list short, specific, and correct.
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@caveman/skill-caveman-explore",
|
|
3
|
-
"version": "1.0.0",
|
|
4
|
-
"license": "MIT",
|
|
5
|
-
"private": true,
|
|
6
|
-
"type": "module",
|
|
7
|
-
"description": "Read-only FastContext exploration skill with parallel repository search and citation-only output.",
|
|
8
|
-
"files": ["SKILL.md"],
|
|
9
|
-
"scripts": {
|
|
10
|
-
"test": "node --test tests/*.mjs"
|
|
11
|
-
}
|
|
12
|
-
}
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
import { test } from "node:test";
|
|
2
|
-
import assert from "node:assert";
|
|
3
|
-
import { readFileSync } from "node:fs";
|
|
4
|
-
import { dirname, join } from "node:path";
|
|
5
|
-
import { fileURLToPath } from "node:url";
|
|
6
|
-
|
|
7
|
-
const skillFile = join(dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md");
|
|
8
|
-
const md = readFileSync(skillFile, "utf8");
|
|
9
|
-
|
|
10
|
-
function frontmatter(text) {
|
|
11
|
-
const match = text.match(/^---\n([\s\S]*?)\n---\n/);
|
|
12
|
-
assert.ok(match, "skill file must open with a --- frontmatter block ---");
|
|
13
|
-
return match[1];
|
|
14
|
-
}
|
|
15
|
-
|
|
16
|
-
test("frontmatter name matches directory and declares read-only cheap explorer", () => {
|
|
17
|
-
const fm = frontmatter(md);
|
|
18
|
-
assert.match(fm, /^name:\s*caveman-explore\s*$/m, "name must be caveman-explore");
|
|
19
|
-
assert.match(fm, /^model:\s*haiku\s*$/m, "explorer must run on cheap model");
|
|
20
|
-
assert.match(fm, /^tools:\s*Read,\s*Glob,\s*Grep\s*$/m, "tools must be exactly three read-only tools");
|
|
21
|
-
assert.doesNotMatch(fm, /\b(Edit|Write|Bash|NotebookEdit)\b/, "explorer must not have write or execution tools");
|
|
22
|
-
assert.match(fm, /^description:\s*.+/m, "description required for auto-delegation");
|
|
23
|
-
});
|
|
24
|
-
|
|
25
|
-
test("description says when to invoke and skip", () => {
|
|
26
|
-
const fm = frontmatter(md);
|
|
27
|
-
assert.match(fm, /cold-start|cross-file|localization|search has failed/i, "must say when to invoke");
|
|
28
|
-
assert.match(fm, /skip/i, "must say when to skip");
|
|
29
|
-
});
|
|
30
|
-
|
|
31
|
-
test("body mandates parallel calls and citation-only reply", () => {
|
|
32
|
-
assert.match(md, /IN PARALLEL/i, "must mandate parallel tool calls");
|
|
33
|
-
assert.match(md, /ONLY an evidence block|only.*citation/i, "must mandate citation-only reply");
|
|
34
|
-
assert.match(md, /path\/to\/file\.ext:START-END/i, "must show compact path:line shape");
|
|
35
|
-
assert.match(md, /no relevant locations found/i, "must give honest empty fallback");
|
|
36
|
-
assert.match(md, /never edit|never.*solve|read-only/i, "must forbid editing and solving");
|
|
37
|
-
});
|
|
38
|
-
|
|
39
|
-
test("artifact carries no placeholder markers", () => {
|
|
40
|
-
const banned = ["TO" + "DO", "FIX" + "ME", "place" + "holder", "X" + "X" + "X"];
|
|
41
|
-
for (const marker of banned) {
|
|
42
|
-
assert.doesNotMatch(md, new RegExp("\\b" + marker + "\\b", "i"), `artifact must not contain ${marker}`);
|
|
43
|
-
}
|
|
44
|
-
});
|
|
@@ -1,38 +0,0 @@
|
|
|
1
|
-
# caveman-help
|
|
2
|
-
|
|
3
|
-
Quick-reference card. One shot, no mode change.
|
|
4
|
-
|
|
5
|
-
## What it does
|
|
6
|
-
|
|
7
|
-
Prints a cheat sheet of all caveman modes, sibling skills, deactivation triggers, and how to set the default mode via env var or config file. One-shot display — does not flip the active mode, write flag files, or persist anything. Use when you forget the slash commands.
|
|
8
|
-
|
|
9
|
-
## How to invoke
|
|
10
|
-
|
|
11
|
-
```
|
|
12
|
-
/caveman-help
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
Also triggers on "caveman help", "what caveman commands", "how do I use caveman".
|
|
16
|
-
|
|
17
|
-
## Example output
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
Modes:
|
|
21
|
-
/caveman full (default)
|
|
22
|
-
/caveman lite lighter
|
|
23
|
-
/caveman ultra extreme
|
|
24
|
-
/caveman wenyan classical Chinese
|
|
25
|
-
|
|
26
|
-
Skills:
|
|
27
|
-
/caveman-commit terse Conventional Commits
|
|
28
|
-
/caveman-review one-line PR comments
|
|
29
|
-
/caveman-stats session token savings
|
|
30
|
-
|
|
31
|
-
Deactivate:
|
|
32
|
-
"stop caveman" or "normal mode"
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## See also
|
|
36
|
-
|
|
37
|
-
- [`SKILL.md`](./SKILL.md) — full reference card
|
|
38
|
-
- [Caveman README](../../README.md) — repo overview
|