@izhimu/pi-caveman 0.2.0 → 0.4.0

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 (55) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/README.md +60 -74
  3. package/extensions/caveman.ts +452 -346
  4. package/package.json +37 -6
  5. package/skills/caveman/README.md +68 -48
  6. package/skills/caveman/SKILL.md +57 -56
  7. package/skills/megacave/README.md +11 -0
  8. package/skills/megacave/SKILL.md +65 -0
  9. package/skills/ultracave/README.md +13 -0
  10. package/skills/ultracave/SKILL.md +63 -0
  11. package/skills/cavecrew/README.md +0 -61
  12. package/skills/cavecrew/SKILL.md +0 -82
  13. package/skills/caveman-commit/README.md +0 -44
  14. package/skills/caveman-commit/SKILL.md +0 -65
  15. package/skills/caveman-compress/README.md +0 -163
  16. package/skills/caveman-compress/SECURITY.md +0 -31
  17. package/skills/caveman-compress/SKILL.md +0 -111
  18. package/skills/caveman-compress/scripts/__init__.py +0 -9
  19. package/skills/caveman-compress/scripts/__main__.py +0 -3
  20. package/skills/caveman-compress/scripts/benchmark.py +0 -80
  21. package/skills/caveman-compress/scripts/cli.py +0 -85
  22. package/skills/caveman-compress/scripts/compress.py +0 -414
  23. package/skills/caveman-compress/scripts/detect.py +0 -139
  24. package/skills/caveman-compress/scripts/validate.py +0 -221
  25. package/skills/caveman-discover/SKILL.md +0 -118
  26. package/skills/caveman-evidence-review/SKILL.md +0 -144
  27. package/skills/caveman-explore/SKILL.md +0 -42
  28. package/skills/caveman-explore/package.json +0 -12
  29. package/skills/caveman-explore/tests/skill-file.test.mjs +0 -44
  30. package/skills/caveman-help/README.md +0 -38
  31. package/skills/caveman-help/SKILL.md +0 -63
  32. package/skills/caveman-learn/CLAUDE.md +0 -32
  33. package/skills/caveman-learn/README.md +0 -29
  34. package/skills/caveman-learn/SKILL.md +0 -69
  35. package/skills/caveman-learn/package.json +0 -12
  36. package/skills/caveman-learn/tests/skill-file.test.mjs +0 -44
  37. package/skills/caveman-manage/SKILL.md +0 -114
  38. package/skills/caveman-optimize/SKILL.md +0 -114
  39. package/skills/caveman-review/README.md +0 -33
  40. package/skills/caveman-review/SKILL.md +0 -55
  41. package/skills/caveman-setup/SKILL.md +0 -224
  42. package/skills/caveman-stats/README.md +0 -36
  43. package/skills/caveman-stats/SKILL.md +0 -12
  44. package/skills/investigate-first/SKILL.md +0 -16
  45. package/skills/investigate-first/agents/openai.yaml +0 -4
  46. package/skills/lean-build/SKILL.md +0 -18
  47. package/skills/lean-build/agents/openai.yaml +0 -4
  48. package/skills/migration/SKILL.md +0 -17
  49. package/skills/migration/agents/openai.yaml +0 -4
  50. package/skills/safe-refactor/SKILL.md +0 -16
  51. package/skills/safe-refactor/agents/openai.yaml +0 -4
  52. package/skills/surgical-patch/SKILL.md +0 -16
  53. package/skills/surgical-patch/agents/openai.yaml +0 -4
  54. package/skills/verify-and-stop/SKILL.md +0 -16
  55. package/skills/verify-and-stop/agents/openai.yaml +0 -4
@@ -1,221 +0,0 @@
1
- #!/usr/bin/env python3
2
- import re
3
- from collections import Counter
4
- from pathlib import Path
5
-
6
- URL_REGEX = re.compile(r"https?://[^\s)]+")
7
- FENCE_OPEN_REGEX = re.compile(r"^(\s{0,3})(`{3,}|~{3,})(.*)$")
8
- HEADING_REGEX = re.compile(r"^(#{1,6})\s+(.*)", re.MULTILINE)
9
- BULLET_REGEX = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
10
-
11
- # crude but effective path detection
12
- # Requires either a path prefix (./ ../ / or drive letter) or a slash/backslash within the match
13
- PATH_REGEX = re.compile(r"(?:\./|\.\./|/|[A-Za-z]:\\)[\w\-/\\\.]+|[\w\-\.]+[/\\][\w\-/\\\.]+")
14
-
15
-
16
- class ValidationResult:
17
- def __init__(self):
18
- self.is_valid = True
19
- self.errors = []
20
- self.warnings = []
21
-
22
- def add_error(self, msg):
23
- self.is_valid = False
24
- self.errors.append(msg)
25
-
26
- def add_warning(self, msg):
27
- self.warnings.append(msg)
28
-
29
-
30
- def read_file(path: Path) -> str:
31
- return path.read_text(encoding="utf-8")
32
-
33
-
34
- # ---------- Extractors ----------
35
-
36
-
37
- def extract_headings(text):
38
- return [(level, title.strip()) for level, title in HEADING_REGEX.findall(text)]
39
-
40
-
41
- def extract_code_blocks(text):
42
- """Line-based fenced code block extractor.
43
-
44
- Handles ``` and ~~~ fences with variable length (CommonMark: closing
45
- fence must use same char and be at least as long as opening). Supports
46
- nested fences (e.g. an outer 4-backtick block wrapping inner 3-backtick
47
- content).
48
- """
49
- blocks = []
50
- lines = text.split("\n")
51
- i = 0
52
- n = len(lines)
53
- while i < n:
54
- m = FENCE_OPEN_REGEX.match(lines[i])
55
- if not m:
56
- i += 1
57
- continue
58
- fence_char = m.group(2)[0]
59
- fence_len = len(m.group(2))
60
- open_line = lines[i]
61
- block_lines = [open_line]
62
- i += 1
63
- closed = False
64
- while i < n:
65
- close_m = FENCE_OPEN_REGEX.match(lines[i])
66
- if (
67
- close_m
68
- and close_m.group(2)[0] == fence_char
69
- and len(close_m.group(2)) >= fence_len
70
- and close_m.group(3).strip() == ""
71
- ):
72
- block_lines.append(lines[i])
73
- closed = True
74
- i += 1
75
- break
76
- block_lines.append(lines[i])
77
- i += 1
78
- if closed:
79
- blocks.append("\n".join(block_lines))
80
- # Unclosed fences are silently skipped — they indicate malformed markdown
81
- # and including them would cause false-positive validation failures.
82
- return blocks
83
-
84
-
85
- def extract_urls(text):
86
- return set(URL_REGEX.findall(text))
87
-
88
-
89
- def extract_paths(text):
90
- return set(PATH_REGEX.findall(text))
91
-
92
-
93
- def count_bullets(text):
94
- return len(BULLET_REGEX.findall(text))
95
-
96
-
97
- def extract_inline_codes(text):
98
- """Backtick-delimited inline spans, with fenced code blocks stripped first.
99
-
100
- Previously used a column-0-anchored regex to strip fences, which misses
101
- fences indented 1-3 spaces (valid CommonMark). Reuse extract_code_blocks
102
- (FENCE_OPEN_REGEX-based, indentation-aware) instead so an indented fence's
103
- body backticks don't leak into inline-code pairing.
104
- """
105
- text_without_fences = text
106
- for block in extract_code_blocks(text):
107
- text_without_fences = text_without_fences.replace(block, "", 1)
108
- return re.findall(r"`([^`]+)`", text_without_fences)
109
-
110
-
111
- # ---------- Validators ----------
112
-
113
-
114
- def validate_headings(orig, comp, result):
115
- h1 = extract_headings(orig)
116
- h2 = extract_headings(comp)
117
-
118
- if len(h1) != len(h2):
119
- result.add_error(f"Heading count mismatch: {len(h1)} vs {len(h2)}")
120
-
121
- if h1 != h2:
122
- result.add_warning("Heading text/order changed")
123
-
124
-
125
- def validate_code_blocks(orig, comp, result):
126
- c1 = extract_code_blocks(orig)
127
- c2 = extract_code_blocks(comp)
128
-
129
- if c1 != c2:
130
- result.add_error("Code blocks not preserved exactly")
131
-
132
-
133
- def validate_urls(orig, comp, result):
134
- u1 = extract_urls(orig)
135
- u2 = extract_urls(comp)
136
-
137
- if u1 != u2:
138
- result.add_error(f"URL mismatch: lost={u1 - u2}, added={u2 - u1}")
139
-
140
-
141
- def validate_paths(orig, comp, result):
142
- p1 = extract_paths(orig)
143
- p2 = extract_paths(comp)
144
-
145
- if p1 != p2:
146
- result.add_warning(f"Path mismatch: lost={p1 - p2}, added={p2 - p1}")
147
-
148
-
149
- def validate_bullets(orig, comp, result):
150
- b1 = count_bullets(orig)
151
- b2 = count_bullets(comp)
152
-
153
- if b1 == 0:
154
- return
155
-
156
- diff = abs(b1 - b2) / b1
157
-
158
- if diff > 0.15:
159
- result.add_warning(f"Bullet count changed too much: {b1} -> {b2}")
160
-
161
-
162
- def validate_inline_codes(orig, comp, result):
163
- c1 = Counter(extract_inline_codes(orig))
164
- c2 = Counter(extract_inline_codes(comp))
165
-
166
- if c1 != c2:
167
- lost = set(c1.keys()) - set(c2.keys())
168
- added = set(c2.keys()) - set(c1.keys())
169
- for code, count in c1.items():
170
- if code in c2 and c2[code] < count:
171
- lost.add(f"{code} (lost {count - c2[code]} of {count} occurrences)")
172
- if lost:
173
- result.add_error(f"Inline code lost: {lost}")
174
- if added:
175
- result.add_warning(f"Inline code added: {added}")
176
-
177
-
178
- # ---------- Main ----------
179
-
180
-
181
- def validate(original_path: Path, compressed_path: Path) -> ValidationResult:
182
- result = ValidationResult()
183
-
184
- orig = read_file(original_path)
185
- comp = read_file(compressed_path)
186
-
187
- validate_headings(orig, comp, result)
188
- validate_code_blocks(orig, comp, result)
189
- validate_urls(orig, comp, result)
190
- validate_paths(orig, comp, result)
191
- validate_bullets(orig, comp, result)
192
- validate_inline_codes(orig, comp, result)
193
-
194
- return result
195
-
196
-
197
- # ---------- CLI ----------
198
-
199
- if __name__ == "__main__":
200
- import sys
201
-
202
- if len(sys.argv) != 3:
203
- print("Usage: python validate.py <original> <compressed>")
204
- sys.exit(1)
205
-
206
- orig = Path(sys.argv[1]).resolve()
207
- comp = Path(sys.argv[2]).resolve()
208
-
209
- res = validate(orig, comp)
210
-
211
- print(f"\nValid: {res.is_valid}")
212
-
213
- if res.errors:
214
- print("\nErrors:")
215
- for e in res.errors:
216
- print(f" - {e}")
217
-
218
- if res.warnings:
219
- print("\nWarnings:")
220
- for w in res.warnings:
221
- print(f" - {w}")
@@ -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
@@ -1,63 +0,0 @@
1
- ---
2
- name: caveman-help
3
- description: >
4
- Quick-reference card for all caveman modes, skills, and commands.
5
- One-shot display, not a persistent mode. Trigger: /caveman-help,
6
- "caveman help", "what caveman commands", "how do I use caveman".
7
- ---
8
-
9
- # Caveman Help
10
-
11
- Display this reference card when invoked. One-shot — do NOT change mode, write flag files, or persist anything. Output in caveman style.
12
-
13
- ## Modes
14
-
15
- | Mode | Trigger | What change |
16
- |------|---------|-------------|
17
- | **Lite** | `/caveman lite` | Drop filler. Keep sentence structure. |
18
- | **Full** | `/caveman` | Drop articles, filler, pleasantries, hedging. Fragments OK. Default. |
19
- | **Ultra** | `/caveman ultra` | Extreme compression. Bare fragments. Tables over prose. |
20
- | **Wenyan-Lite** | `/caveman wenyan-lite` | Classical Chinese style, light compression. |
21
- | **Wenyan-Full** | `/caveman wenyan` | Full 文言文. Maximum classical terseness. |
22
- | **Wenyan-Ultra** | `/caveman wenyan-ultra` | Extreme. Ancient scholar on a budget. |
23
-
24
- Mode stick until changed or session end.
25
-
26
- ## Skills
27
-
28
- | Skill | Trigger | What it do |
29
- |-------|---------|-----------|
30
- | **caveman-commit** | `/caveman-commit` | Terse commit messages. Conventional Commits. ≤50 char subject. |
31
- | **caveman-review** | `/caveman-review` | One-line PR comments: `L42: bug: user null. Add guard.` |
32
- | **caveman-compress** | `/caveman-compress <file>` | Compress .md files to caveman prose. Saves ~46% input tokens. |
33
- | **caveman-help** | `/caveman-help` | This card. |
34
-
35
- ## Deactivate
36
-
37
- Say "stop caveman" or "normal mode". Resume anytime with `/caveman`.
38
-
39
- ## Language
40
-
41
- Keep user's language by default. User write Portuguese → reply Portuguese caveman. Compress the style, not the language. Technical terms, code, commands, commit types, and exact error strings stay verbatim unless user ask for translation.
42
-
43
- ## Configure Default Mode
44
-
45
- Default mode = `full`. Change it:
46
-
47
- **Environment variable** (highest priority):
48
- ```bash
49
- export CAVEMAN_DEFAULT_MODE=ultra
50
- ```
51
-
52
- **Config file** (`~/.config/caveman/config.json`):
53
- ```json
54
- { "defaultMode": "lite" }
55
- ```
56
-
57
- Set `"off"` to disable auto-activation on session start. User can still activate manually with `/caveman`.
58
-
59
- Resolution: env var > config file > `full`.
60
-
61
- ## More
62
-
63
- Full docs: https://github.com/JuliusBrussee/caveman