@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.
Files changed (44) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +36 -44
  3. package/extensions/caveman.ts +101 -149
  4. package/package.json +5 -1
  5. package/skills/caveman/README.md +52 -48
  6. package/skills/caveman/SKILL.md +3 -1
  7. package/skills/caveman-compress/README.md +42 -29
  8. package/skills/caveman-compress/scripts/compress.py +113 -22
  9. package/skills/caveman-compress/scripts/validate.py +193 -6
  10. package/skills/cavecrew/README.md +0 -61
  11. package/skills/cavecrew/SKILL.md +0 -82
  12. package/skills/caveman-commit/README.md +0 -44
  13. package/skills/caveman-commit/SKILL.md +0 -65
  14. package/skills/caveman-discover/SKILL.md +0 -118
  15. package/skills/caveman-evidence-review/SKILL.md +0 -144
  16. package/skills/caveman-explore/SKILL.md +0 -42
  17. package/skills/caveman-explore/package.json +0 -12
  18. package/skills/caveman-explore/tests/skill-file.test.mjs +0 -44
  19. package/skills/caveman-help/README.md +0 -38
  20. package/skills/caveman-help/SKILL.md +0 -63
  21. package/skills/caveman-learn/CLAUDE.md +0 -32
  22. package/skills/caveman-learn/README.md +0 -29
  23. package/skills/caveman-learn/SKILL.md +0 -69
  24. package/skills/caveman-learn/package.json +0 -12
  25. package/skills/caveman-learn/tests/skill-file.test.mjs +0 -44
  26. package/skills/caveman-manage/SKILL.md +0 -114
  27. package/skills/caveman-optimize/SKILL.md +0 -114
  28. package/skills/caveman-review/README.md +0 -33
  29. package/skills/caveman-review/SKILL.md +0 -55
  30. package/skills/caveman-setup/SKILL.md +0 -224
  31. package/skills/caveman-stats/README.md +0 -36
  32. package/skills/caveman-stats/SKILL.md +0 -12
  33. package/skills/investigate-first/SKILL.md +0 -16
  34. package/skills/investigate-first/agents/openai.yaml +0 -4
  35. package/skills/lean-build/SKILL.md +0 -18
  36. package/skills/lean-build/agents/openai.yaml +0 -4
  37. package/skills/migration/SKILL.md +0 -17
  38. package/skills/migration/agents/openai.yaml +0 -4
  39. package/skills/safe-refactor/SKILL.md +0 -16
  40. package/skills/safe-refactor/agents/openai.yaml +0 -4
  41. package/skills/surgical-patch/SKILL.md +0 -16
  42. package/skills/surgical-patch/agents/openai.yaml +0 -4
  43. package/skills/verify-and-stop/SKILL.md +0 -16
  44. 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
@@ -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