@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,224 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: caveman-setup
|
|
3
|
-
description: >
|
|
4
|
-
Wire the current repository through the Caveman Cloud gateway so every LLM
|
|
5
|
-
request is measured — cost, tokens, latency — with zero behavior change.
|
|
6
|
-
Use when the user pastes the Caveman setup prompt, says "set up caveman",
|
|
7
|
-
or wants LLM spend observability added to an app. Requires the gateway URL
|
|
8
|
-
and a Cave API key (the setup prompt carries both).
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
You are wiring this repository through the Caveman gateway. Caveman is a
|
|
12
|
-
byte-preserving LLM proxy: in record mode it measures what your app sends and
|
|
13
|
-
what it costs, and changes nothing else. Your job is a minimal, verified
|
|
14
|
-
integration — not a refactor.
|
|
15
|
-
|
|
16
|
-
The prompt that sent you here provides four values. Refer to them as:
|
|
17
|
-
|
|
18
|
-
- `GATEWAY` — the gateway base URL (e.g. `https://gateway.caveman.so` or `http://127.0.0.1:8787`)
|
|
19
|
-
- `CAVE_API_KEY` — the gateway auth secret (treat like any API key: env var only, never committed, never printed in full)
|
|
20
|
-
- `PROVIDER_KEYS` — `stored` (provider keys live encrypted in Caveman Cloud) or `byok` (this app sends its own provider key per request)
|
|
21
|
-
- `DASHBOARD` — the dashboard base URL (e.g. `https://app.caveman.so`)
|
|
22
|
-
|
|
23
|
-
If any value is missing, stop and ask for it. Do not guess a URL or mint a key.
|
|
24
|
-
|
|
25
|
-
## Rules (non-negotiable)
|
|
26
|
-
|
|
27
|
-
1. **Coherent integration.** Wire every live LLM callsite through existing
|
|
28
|
-
configuration and responsible seams. Touch each layer correctness requires.
|
|
29
|
-
No drive-by refactors or formatting sweeps; add an abstraction only when it
|
|
30
|
-
clarifies ownership or lowers lifecycle cost.
|
|
31
|
-
2. **Secrets stay in env vars.** `CAVE_API_KEY` goes into the env file the repo
|
|
32
|
-
already uses (`.env`, `.env.local`, …). If that file isn't gitignored, add it
|
|
33
|
-
to `.gitignore` and say so. Never hardcode the key in source.
|
|
34
|
-
3. **Report only what you observed.** The final report states the HTTP status
|
|
35
|
-
and usage numbers from the real verification response — never assumed
|
|
36
|
-
success. If verification fails, report the failure template instead.
|
|
37
|
-
4. **Record mode only.** You are adding measurement. You do not enable any
|
|
38
|
-
optimization, and you do not claim any savings — verified savings are $0
|
|
39
|
-
until an optimizer is explicitly turned on and passes its eval gate.
|
|
40
|
-
5. **Provider keys are not your business.** With `PROVIDER_KEYS: stored` you
|
|
41
|
-
never see one. With `byok`, the app's existing provider key stays exactly
|
|
42
|
-
where it already is.
|
|
43
|
-
|
|
44
|
-
## Step 1 — Find every live LLM callsite
|
|
45
|
-
|
|
46
|
-
Read dependency files (`package.json`, `requirements.txt`, `pyproject.toml`,
|
|
47
|
-
`go.mod`, lockfiles) and search the source for LLM clients:
|
|
48
|
-
|
|
49
|
-
- SDK imports: `openai`, `@anthropic-ai/sdk`, `anthropic`, `ai` +
|
|
50
|
-
`@ai-sdk/*` (Vercel), `langchain*`, `litellm`, `google-genai` /
|
|
51
|
-
`@google/genai`, `crewai`, `pydantic_ai`, `openai-agents` / `agents`
|
|
52
|
-
- Raw HTTP to `api.openai.com`, `api.anthropic.com`, `generativelanguage.googleapis.com`
|
|
53
|
-
- Existing base-URL env vars: `OPENAI_BASE_URL`, `OPENAI_API_BASE`,
|
|
54
|
-
`ANTHROPIC_BASE_URL`, `GEMINI_BASE_URL`, `GOOGLE_GEMINI_BASE_URL`
|
|
55
|
-
|
|
56
|
-
List what you found (file:line per callsite) before changing anything. If you
|
|
57
|
-
find **no** LLM callsites, stop and report the "nothing to wire" template at
|
|
58
|
-
the end of this file — do not invent an integration.
|
|
59
|
-
|
|
60
|
-
## Step 2 — Pick the app slug
|
|
61
|
-
|
|
62
|
-
One slug names this app in the gateway path: `GATEWAY/w/<app>`. Derive it from
|
|
63
|
-
the package/module name (e.g. `support-bot`, `acme-api`). Grammar:
|
|
64
|
-
lowercase `[a-z0-9]` first, then `[a-z0-9._-]`, max 64 chars. Spend for this
|
|
65
|
-
whole app groups under that slug on the dashboard.
|
|
66
|
-
|
|
67
|
-
## Step 3 — Wire each callsite
|
|
68
|
-
|
|
69
|
-
The pattern is always the same: **base URL → the gateway with `/w/<app>`,
|
|
70
|
-
plus one auth header.** Gateway auth is `x-cave-api-key: CAVE_API_KEY`
|
|
71
|
-
(`Authorization: Bearer CAVE_API_KEY` also works where a header is awkward).
|
|
72
|
-
With `PROVIDER_KEYS: byok`, also send `x-cave-upstream-key: <the provider key
|
|
73
|
-
the app already uses>`.
|
|
74
|
-
|
|
75
|
-
Two facts that make the wiring safe (both are gateway-enforced, not hopes):
|
|
76
|
-
the gateway rebuilds upstream auth headers from scratch, so a client's
|
|
77
|
-
`Authorization`/`x-api-key` value is never forwarded to the provider; and with
|
|
78
|
-
`stored`, upstream auth comes from the encrypted connection server-side. So in
|
|
79
|
-
`stored` mode, where an SDK insists on an api-key parameter, set it to the
|
|
80
|
-
Cave key — it authenticates the gateway and goes no further.
|
|
81
|
-
|
|
82
|
-
Exact shapes (use the one matching each callsite — these are the product's
|
|
83
|
-
published recipes, not suggestions):
|
|
84
|
-
|
|
85
|
-
**OpenAI SDK (TS)** — Chat Completions and Responses both route through:
|
|
86
|
-
```ts
|
|
87
|
-
const client = new OpenAI({
|
|
88
|
-
baseURL: `${process.env.CAVE_GATEWAY_URL}/w/<app>/openai/v1`,
|
|
89
|
-
apiKey: process.env.OPENAI_API_KEY, // byok: unchanged · stored: use CAVE_API_KEY
|
|
90
|
-
defaultHeaders: {
|
|
91
|
-
"x-cave-api-key": process.env.CAVE_API_KEY!,
|
|
92
|
-
// byok only:
|
|
93
|
-
"x-cave-upstream-key": process.env.OPENAI_API_KEY!,
|
|
94
|
-
},
|
|
95
|
-
});
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
**OpenAI SDK (Python)** — same shape: `base_url=f"{gw}/w/<app>/openai/v1"`,
|
|
99
|
-
`default_headers={"x-cave-api-key": ..., "x-cave-upstream-key": ...}`.
|
|
100
|
-
|
|
101
|
-
**Anthropic SDK (TS/Python)** — the SDK appends `/v1/messages` itself. The
|
|
102
|
-
`x-cave-api-key` header is required here in both modes (this SDK's own key
|
|
103
|
-
param rides `x-api-key`, which is not a gateway-auth header):
|
|
104
|
-
```python
|
|
105
|
-
client = anthropic.Anthropic(
|
|
106
|
-
base_url=f"{os.environ['CAVE_GATEWAY_URL']}/w/<app>",
|
|
107
|
-
api_key=os.environ["ANTHROPIC_API_KEY"], # byok: unchanged · stored: use CAVE_API_KEY
|
|
108
|
-
default_headers={
|
|
109
|
-
"x-cave-api-key": os.environ["CAVE_API_KEY"],
|
|
110
|
-
# byok only:
|
|
111
|
-
"x-cave-upstream-key": os.environ["ANTHROPIC_API_KEY"],
|
|
112
|
-
},
|
|
113
|
-
)
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
**Vercel AI SDK** — `createOpenAICompatible({ baseURL: `${gw}/w/<app>/openai/v1`,
|
|
117
|
-
headers: { "x-cave-api-key": ... } })`; Anthropic models via
|
|
118
|
-
`createAnthropic({ baseURL: `${gw}/w/<app>/v1`, headers: { ... } })`.
|
|
119
|
-
|
|
120
|
-
**LangChain / LangGraph** — `ChatOpenAI(base_url=f"{gw}/w/<app>/openai/v1",
|
|
121
|
-
default_headers={...})`; `ChatAnthropic(base_url=f"{gw}/w/<app>",
|
|
122
|
-
default_headers={...})`. LangGraph inherits whatever model you pass it.
|
|
123
|
-
|
|
124
|
-
**LiteLLM** — per call `api_base=f"{gw}/w/<app>/openai/v1"` +
|
|
125
|
-
`extra_headers={...}`, or fleet-wide in the LiteLLM proxy `config.yaml`.
|
|
126
|
-
|
|
127
|
-
**Raw HTTP / anything else** — swap the host, keep the provider's native path:
|
|
128
|
-
`GATEWAY/w/<app>/v1/chat/completions` (OpenAI protocol) or
|
|
129
|
-
`GATEWAY/w/<app>/v1/messages` (Anthropic protocol), add the header(s).
|
|
130
|
-
|
|
131
|
-
Concretely, with slug `support-bot` and the hosted gateway, an OpenAI-SDK base
|
|
132
|
-
URL reads `https://gateway.caveman.so/w/support-bot/openai/v1`. And in `stored`
|
|
133
|
-
mode, drop every `x-cave-upstream-key` line entirely — it is byok-only.
|
|
134
|
-
|
|
135
|
-
For frameworks not listed (google-genai, crewai, pydantic-ai, openai-agents),
|
|
136
|
-
fetch the matching page under `<docs origin>/docs/integrations/` — same origin
|
|
137
|
-
this skill came from — and follow it.
|
|
138
|
-
|
|
139
|
-
Add to the repo's env file (and reference from code — no literals):
|
|
140
|
-
|
|
141
|
-
```
|
|
142
|
-
CAVE_GATEWAY_URL=<GATEWAY>
|
|
143
|
-
CAVE_API_KEY=<CAVE_API_KEY>
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
## Step 4 — Verify with one real request
|
|
147
|
-
|
|
148
|
-
The user pasted the setup prompt to authorize exactly this: one small
|
|
149
|
-
verification request. Send it now — do not pause to ask permission for it.
|
|
150
|
-
An integration that ends unverified because you hesitated is a worse outcome
|
|
151
|
-
than one tiny request; finishing the verification and the report autonomously
|
|
152
|
-
is the point of this skill.
|
|
153
|
-
|
|
154
|
-
Send one minimal request through the wiring you just built — the app's own
|
|
155
|
-
cheapest path if it has a script for it, otherwise curl **on the path matching
|
|
156
|
-
the protocol you just wired** with the app's own model and a small cap
|
|
157
|
-
(`max_tokens` ≤ 32):
|
|
158
|
-
|
|
159
|
-
```bash
|
|
160
|
-
# OpenAI-protocol wiring:
|
|
161
|
-
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/chat/completions" \
|
|
162
|
-
-H "x-cave-api-key: $CAVE_API_KEY" \
|
|
163
|
-
-H "content-type: application/json" \
|
|
164
|
-
-d '{"model":"<model the repo already uses>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
|
|
165
|
-
|
|
166
|
-
# Anthropic-protocol wiring:
|
|
167
|
-
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/messages" \
|
|
168
|
-
-H "x-cave-api-key: $CAVE_API_KEY" \
|
|
169
|
-
-H "anthropic-version: 2023-06-01" \
|
|
170
|
-
-H "content-type: application/json" \
|
|
171
|
-
-d '{"model":"<model the repo already uses>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
(byok: add `-H "x-cave-upstream-key: $PROVIDER_KEY"`.) This is one real,
|
|
175
|
-
billable provider request — that is the point: real traffic, real measurement.
|
|
176
|
-
|
|
177
|
-
Read the response. Success = HTTP 200 with a `usage` block. Anything else =
|
|
178
|
-
the matching failure template below.
|
|
179
|
-
|
|
180
|
-
## Step 5 — Report
|
|
181
|
-
|
|
182
|
-
End with exactly this shape, values filled from what you actually did and saw:
|
|
183
|
-
|
|
184
|
-
```
|
|
185
|
-
## Caveman is live in this repo
|
|
186
|
-
|
|
187
|
-
Wired: <n> callsite(s) in <n> file(s)
|
|
188
|
-
- <file> — <one-line what changed>
|
|
189
|
-
App slug: <app> — spend for this app groups under it
|
|
190
|
-
Verified: HTTP 200 · model <model> · <in> in / <out> out tokens (one real request)
|
|
191
|
-
Mode: record — measured only. No model-visible bytes changed, no optimization
|
|
192
|
-
enabled. Verified savings are $0 until you turn an optimizer on and it passes
|
|
193
|
-
its eval gate. That honesty is the product.
|
|
194
|
-
|
|
195
|
-
See the dollars: <DASHBOARD>/traces — your request is the top row, priced from
|
|
196
|
-
the public catalog. <DASHBOARD>/getting-started flips to "First request received."
|
|
197
|
-
|
|
198
|
-
Want spend split by workflow (e.g. support-reply vs nightly-digest), not just
|
|
199
|
-
by app? Say "discover workflows" — I'll fetch <docs origin>/docs/discover-workflows.md
|
|
200
|
-
and label every callsite by the job it does.
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
## Failure templates (use verbatim, filled in — never soften)
|
|
204
|
-
|
|
205
|
-
- **Nothing to wire**: "I found no LLM callsites in this repo (searched SDKs,
|
|
206
|
-
raw provider HTTP, base-URL env vars). If this repo runs a coding agent
|
|
207
|
-
rather than shipping LLM code, use `caveman wrap <agent>` instead — see
|
|
208
|
-
<DASHBOARD>/getting-started."
|
|
209
|
-
- **Gateway unreachable**: "The verification request could not reach GATEWAY
|
|
210
|
-
(<error>). Wiring is in place but unverified — nothing will be measured
|
|
211
|
-
until the gateway is reachable. Check the URL and network, then re-run the
|
|
212
|
-
verification curl above."
|
|
213
|
-
- **401 cave_invalid_api_key**: "The gateway rejected CAVE_API_KEY. Mint a new
|
|
214
|
-
key at <DASHBOARD>/getting-started and update the env file; the wiring
|
|
215
|
-
itself is unchanged."
|
|
216
|
-
- **404 cave_route_not_found**: "The gateway matched no route — usually a
|
|
217
|
-
malformed /w/<app> slug (lowercase [a-z0-9] first, then [a-z0-9._-], max 64)
|
|
218
|
-
or a path that doesn't match the SDK's protocol. Fix the URL and re-verify."
|
|
219
|
-
- **Provider error (4xx/5xx via gateway)**: report status + body verbatim; the
|
|
220
|
-
gateway is reachable and auth passed, the upstream call failed — usually a
|
|
221
|
-
provider key or model-name issue in the app itself.
|
|
222
|
-
|
|
223
|
-
Never report success on any of these. An unverified integration is reported as
|
|
224
|
-
unverified.
|
|
@@ -1,36 +0,0 @@
|
|
|
1
|
-
# caveman-stats
|
|
2
|
-
|
|
3
|
-
Real session token receipts. No AI estimation.
|
|
4
|
-
|
|
5
|
-
## What it does
|
|
6
|
-
|
|
7
|
-
Reads the current Claude Code session log directly and reports actual input/output token usage plus estimated savings versus a non-caveman baseline. Numbers come from the JSONL session log on disk — the model itself does not compute or estimate them. Output is injected by the `caveman-mode-tracker` hook, which intercepts `/caveman-stats` and returns the formatted stats as a blocked-decision reason.
|
|
8
|
-
|
|
9
|
-
Output also includes an `Est. rule overhead` and `Est. net` line whenever the savings figure above them is unambiguous (a single benchmarked mode with a known turn count — no guessing across mixed or unattributed spans). Overhead estimates the per-turn INPUT-token cost of the rules the skill injects every turn — default 1,250 tokens/turn, override with `CAVEMAN_RULE_OVERHEAD_TOKENS` if you've measured your own setup. Net is savings minus that overhead. On short, terse replies this can go negative — caveman's OUTPUT savings don't clear its INPUT cost — and the line says so directly instead of hiding it behind a gross-savings number. Background: `docs/HONEST-NUMBERS.md`.
|
|
10
|
-
|
|
11
|
-
Each run also writes a lifetime-savings suffix file used by the statusline badge (`⛏ 12.4k`). That badge stays a gross-savings figure on purpose — it is a glanceable summary, not a full accounting; run `/caveman-stats` for the net picture.
|
|
12
|
-
|
|
13
|
-
## How to invoke
|
|
14
|
-
|
|
15
|
-
```
|
|
16
|
-
/caveman-stats
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## Example output
|
|
20
|
-
|
|
21
|
-
```
|
|
22
|
-
Session: 47 turns
|
|
23
|
-
Input: 12,304 tokens
|
|
24
|
-
Output: 3,891 tokens (caveman)
|
|
25
|
-
Baseline: 11,247 tokens (estimated without caveman)
|
|
26
|
-
Saved: 7,356 tokens (~65%)
|
|
27
|
-
Est. rule overhead: 58,750 (input, ~1,250/turn over 47 turns)
|
|
28
|
-
Est. net: -51,394 (caveman cost more than it saved for this workload — consider turning it off)
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
(Numbers above are illustrative — see `docs/HONEST-NUMBERS.md` for why short, terse-reply sessions tend to land net-negative even at a healthy output-savings percentage.)
|
|
32
|
-
|
|
33
|
-
## See also
|
|
34
|
-
|
|
35
|
-
- [`SKILL.md`](./SKILL.md) — hook contract and mechanics
|
|
36
|
-
- [Caveman README](../../README.md) — repo overview
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: caveman-stats
|
|
3
|
-
description: >
|
|
4
|
-
Show real token usage and estimated savings for the current session.
|
|
5
|
-
Reads directly from the Claude Code session log — no AI estimation.
|
|
6
|
-
Triggers on /caveman-stats. Output is injected by the mode-tracker hook;
|
|
7
|
-
the model itself does not compute the numbers.
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
This skill is delivered by `hooks/caveman-stats.js` (read by `hooks/caveman-mode-tracker.js` on `/caveman-stats`). The model does not need to do anything when this skill fires — the hook returns `decision: "block"` with the formatted stats as the reason. The user sees the numbers immediately.
|
|
11
|
-
|
|
12
|
-
Output also includes `Est. rule overhead` and `Est. net` lines wherever a savings estimate exists with a known turn count. Rule overhead is the estimated per-turn INPUT-token cost of the injected caveman rules (default 1,250 tokens/turn, override with `CAVEMAN_RULE_OVERHEAD_TOKENS`) times the turn count. Net is savings minus that overhead — when negative, the output says so plainly and suggests turning caveman off for that workload, rather than hiding the net-negative regime behind a gross-savings number (see `docs/HONEST-NUMBERS.md`).
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: investigate-first
|
|
3
|
-
description: Diagnose ambiguous failures before editing. Use for unknown causes, intermittent behavior, performance regressions, or investigations needing evidence-ranked hypotheses.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Investigate first
|
|
7
|
-
|
|
8
|
-
Gather evidence before changing product code.
|
|
9
|
-
|
|
10
|
-
- Separate observed symptom from inferred cause.
|
|
11
|
-
- Trace inputs, state transitions, ownership boundaries, and failure output.
|
|
12
|
-
- Rank hypotheses by evidence and cheap falsification value.
|
|
13
|
-
- Do not edit until one credible mechanism explains evidence.
|
|
14
|
-
- Stop exploration when evidence is sufficient to name cause or exact blocker.
|
|
15
|
-
|
|
16
|
-
Report cause and proof. Make no fix unless task authorizes implementation.
|
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: lean-build
|
|
3
|
-
description: Build feature work with high overbuilding risk. Use for new behavior, product slices, or integrations where repository reuse, strict scope, and an explicit stop condition matter.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Lean build
|
|
7
|
-
|
|
8
|
-
Native Core's architecture-first simplicity remains mandatory. Turn feature into complete narrow outcome fitting system.
|
|
9
|
-
|
|
10
|
-
- Derive observable acceptance and explicit non-goals from request and repository.
|
|
11
|
-
- Trace entry point through layers owning invariants.
|
|
12
|
-
- Deliver coherent end-to-end path across responsible layers; never force work into one file, direct expression, or local patch.
|
|
13
|
-
- Reuse fitting seam. Refactor when patching duplicates behavior, weakens ownership, or hides root cause.
|
|
14
|
-
- Omit modes, providers, config, extensibility, and polish unless acceptance needs them.
|
|
15
|
-
- Add surface, dependency, service, config, or migration only for lifecycle design or acceptance; state material tradeoff.
|
|
16
|
-
- Keep work runnable; preserve Core safety.
|
|
17
|
-
|
|
18
|
-
Exercise path. Run focused proof. Stop when acceptance passes. Report only material omissions and trigger.
|
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: migration
|
|
3
|
-
description: Implement reversible compatibility-safe transitions. Use for schema, data, API, protocol, configuration, or dependency migrations requiring rollback and preservation proof.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Migration
|
|
7
|
-
|
|
8
|
-
Map current readers, writers, data shape, compatibility window, and ownership before editing.
|
|
9
|
-
|
|
10
|
-
- Define forward path and rollback path.
|
|
11
|
-
- Preserve existing data; make destructive steps explicit and separately authorized.
|
|
12
|
-
- Keep mixed-version operation safe where rollout can overlap.
|
|
13
|
-
- Sequence expand, migrate, verify, then contract when applicable.
|
|
14
|
-
- Make retries idempotent and partial failure observable.
|
|
15
|
-
- Verify old and new paths at required transition stages.
|
|
16
|
-
|
|
17
|
-
Stop after requested stage passes; do not perform later destructive contraction implicitly.
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: safe-refactor
|
|
3
|
-
description: Restructure code while preserving behavior. Use for extraction, consolidation, ownership moves, or cleanup where verification must bracket structural edits.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Safe refactor
|
|
7
|
-
|
|
8
|
-
Define behavior-preservation boundary and establish verification before structural edits.
|
|
9
|
-
|
|
10
|
-
- Keep feature changes outside refactor.
|
|
11
|
-
- Move one ownership boundary at a time.
|
|
12
|
-
- Preserve public interfaces, failure behavior, ordering, and compatibility unless explicitly scoped.
|
|
13
|
-
- Keep intermediate states buildable and testable.
|
|
14
|
-
- Avoid dependency or configuration growth without correctness need.
|
|
15
|
-
|
|
16
|
-
Run same proof after change. Stop when behavior matches and requested structure is achieved.
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: surgical-patch
|
|
3
|
-
description: Fix bugs and small behavior changes at the narrowest responsible layer. Use when regression proof, preserved surrounding behavior, and task-relevant tests matter.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Surgical patch
|
|
7
|
-
|
|
8
|
-
Reproduce failure first when economical; otherwise capture strongest available evidence.
|
|
9
|
-
|
|
10
|
-
- Trace symptom to responsible mechanism.
|
|
11
|
-
- Change narrowest layer that owns incorrect behavior.
|
|
12
|
-
- Preserve unrelated behavior and user changes.
|
|
13
|
-
- Avoid cleanup, renaming, and abstraction outside fix.
|
|
14
|
-
- Add only regression proof relevant to task.
|
|
15
|
-
|
|
16
|
-
Run focused proof plus nearest affected gate. Stop when failure is fixed and regression proof passes.
|
|
@@ -1,16 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: verify-and-stop
|
|
3
|
-
description: Prove existing work meets acceptance conditions without expanding scope. Use for validation-only tasks, completion checks, focused gate runs, and last-mile proof.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Verify and stop
|
|
7
|
-
|
|
8
|
-
Translate acceptance conditions into smallest sufficient proof set.
|
|
9
|
-
|
|
10
|
-
- Reuse still-current results with matching repository state.
|
|
11
|
-
- Run focused checks before wider gates.
|
|
12
|
-
- Distinguish pass, fail, unavailable, and blocked exactly.
|
|
13
|
-
- Do not edit product code unless verification request includes fixes.
|
|
14
|
-
- Do not add polish, cleanup, or unrelated tests after criteria pass.
|
|
15
|
-
|
|
16
|
-
Stop immediately when acceptance proof is complete. Report commands, results, and unresolved risk only.
|