Two files, one repository

danielvm-git/bigpowers ships 4 formats across 40 indexed files. The question worth asking is whether the second one says anything the first does not.

CompareCLAUDE.md ↔ GEMINI.md CLAUDE.md ↔ AGENTS.md CLAUDE.md ↔ Cursor rules GEMINI.md ↔ AGENTS.md GEMINI.md ↔ Cursor rules AGENTS.md ↔ Cursor rules

A · website/AGENTS.md · 79 words B · CLAUDE.md · 2837 words

What each file covers, counted
Dimension	Only in A	Only in B	Overlap
Sections	2	40	0%
Commands	0	10	0%
Section tags	1	11	0%

What each file covers

Sections

0 shared · 2 only in A · 40 only in B

− Development
− Documentation
+ story: e38s08
+ story: e51s05
+ story: e45s22
+ story: e45s23
+ story: e55s03
+ bigpowers — Claude Code
+ Context Routing
+ Learned User Preferences
+ Workspace Facts
+ Project
+ Commands
+ Pre-Merge Checklist
+ Architecture
+ Conventions
+ Never
+ Token Management
+ Session Start
+ Agent Rules
+ bts toolchain
+ sqz — Context Compression (READ FIRST)
+ Preferred tools (MCP)
+ Bash commands (hooked automatically)
+ Escape hatch — when you see a `§ref:HASH§` token
+ When NOT to use sqz tools
+ RTK (Rust Token Killer) - Token-Optimized Commands
+ Golden Rule
+ ❌ Wrong
+ ✅ Correct
+ RTK Commands by Workflow
+ Build & Compile (80-90% savings)
+ Test (60-99% savings)
+ Git (59-80% savings)
+ GitHub (26-87% savings)
+ JavaScript/TypeScript Tooling (70-90% savings)
+ Files & Search (60-75% savings)
+ Analysis & Debug (70-90% savings)
+ Infrastructure (85% savings)
+ Network (65-70% savings)
+ Meta Commands
+ Token Savings Overview

Commands

0 shared · 0 only in A · 10 only in B

+ npm run compliance && bash scripts/run-verification-gates.sh
+ git status
+ cargo test
+ docker ps
+ kubectl get pods
+ git add . && git commit -m "msg" && git push
+ npm install -g bigpowers && bigpowers setup
+ npm run compliance
+ gh pr checks
+ python

Section tags

0 shared · 1 only in A · 11 only in B

− docs
+ setup
+ build
+ test
+ lint-format
+ code-style
+ architecture
+ types
+ git-pr
+ monorepo
+ do-not
+ agent-behaviour

Line diff

+390 added−13 removed10 unchanged2.5% identical

danielvm-git/bigpowers · website/AGENTS.md

@@ −1 @@

1## Development

3When starting the dev server, use background mode:

5```

6astro dev --background

7```

9Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.

11## Documentation

13Full documentation: https://docs.astro.build

15Consult these guides before working on related tasks:

17- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)

18- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)

19- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)

20- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)

21- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)

22- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)

danielvm-git/bigpowers · CLAUDE.md

@@ +1 @@

1# story: e38s08

2# story: e51s05

3# story: e45s22

4# story: e45s23

5# story: e55s03

7# bigpowers — Claude Code

9Read CONVENTIONS.md before any GitHub or git operation.

11[`constitution.md`](constitution.md) is a consolidated entry point synthesizing

12this project's doctrine (this file, CONVENTIONS.md, docs/PRINCIPLES.md,

13docs/references/*.md) into bigspec's B0-B10 + Capstone blocks, with citations

14back to the fuller text. It's a starting point for a reader, not a

15replacement — this file remains fully authoritative for its own content today.

17

18## Context Routing

20Load subdirectory context **by file glob** — do not read the full doc tree up front.

22| Glob / trigger | Load first | Fallback |

23|----------------|------------|----------|

24| `skills/**` | Active skill's `SKILL.md` + sibling `REFERENCE.md` if linked | `SKILL-INDEX.md` |

25| `specs/epics/**` | Capsule `epic.yaml` + active story `-tasks.yaml` | `specs/release-plan.yaml` |

26| `specs/product/**` | `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml` | `specs/README.md` |

27| `specs/tech-architecture/**` | `tech-stack.md` + epic `eNN-TEST_PLAN_LATEST.md` if present | `CONVENTIONS.md` |

28| `scripts/**` | `CONVENTIONS.md` § Generated artifact targets | This file § Commands |

29| `website/**` | `website/README.md` if present | Never edit `website/src/content/docs/` (generated) |

30| `docs/**` | Matching doc under `docs/` | `docs/references/` |

31| Default / session start | This file → `CONVENTIONS.md` → `specs/state.yaml` | `survey-context` |

33Sub-AGENTS.md files (when present in consumer projects) override this table for their directory only.

34

36

37## Learned User Preferences

39_Durable preferences discovered across sessions. Update via `session-state` — do not infer from chat alone._

41- Prefer `rtk`-prefixed shell commands for git, test, and build output (token savings).

42- Run Preflight before forward work; never dismiss red gates as pre-existing.

43- Edit `skills/*/SKILL.md` sources only — never `.cursor/rules/` or `.gemini/` artifacts.

45## Workspace Facts

47_Stable repo facts — prefer these over re-discovery._

49- Stack: Markdown / Bash documentation project; skills sync via `bash scripts/sync-skills.sh`.

50- Planning SoT: `specs/state.yaml`, `specs/release-plan.yaml`, `specs/execution-status.yaml`.

51- Story traceability: `# story: eNNsNN` tags in implementing files; `bash scripts/trace-stories.sh --strict` in CI.

52- Rule matrix: `bash scripts/compile-rule-matrix.sh` → `specs/rule-matrix.json` (P0–P3 tiers from CONVENTIONS.md).

53

55## Project

57bigpowers — agent skills for spec-driven, test-first software development by solo developers (skill count and catalog are auto-generated in `SKILL-INDEX.md`; never hardcode the count in docs).

58Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)

60## Commands

62| Action | Command |

63|---------|---------|

64| Install | `npm install -g bigpowers && bigpowers setup` |

65| Run | `bash scripts/sync-skills.sh` |

66| Test | N/A (documentation project) |

67| Build | `bash scripts/install.sh` (from source) |

68| Lint | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |

69| Validate specs YAML | `bash scripts/validate-specs-yaml.sh` |

70| Typecheck | N/A (Markdown / Bash project) |

71| CI platform | GitHub Actions (`.github/workflows/publish.yml`, `sync-skills.yml`, `golden-suite.yml`) |

72| Compliance | `npm run compliance` |

73| Verification Gates | `bash scripts/run-verification-gates.sh` |

74| Traceability | `bash scripts/trace-stories.sh --strict` | grep for story tags (traceability check) |

75| Preflight | `npm run compliance && bash scripts/run-verification-gates.sh && bash scripts/sync-skills.sh && bash scripts/trace-stories.sh --strict` | Full local green stack before forward work. Chain ends on `--strict` traceability — no trailing always-exit-0 step. |

76| Catalog drift (advisory) | `bash scripts/check-catalog-drift.sh` | e54s02 Confirm gate during catalog freeze — always exits 0; run manually when changing skills, not part of Preflight. |

77| CI | `gh pr checks` | Remote CI green when a PR is open |

79### Pre-Merge Checklist

81Before opening a PR or landing a branch, run:

83```bash

84npm run compliance && bash scripts/run-verification-gates.sh

85```

87If any gate fails, fix before merging. Run `--baseline` after any intentional increase in skill count or structure.

89**BCP Plus:** For stories sized with the 13-dimension BCP Plus methodology, confirm the `bcp_plus_breakdown` is present in the epic YAML and carried into `state.yaml` as `epic_cycle.bcp_plus`. See `docs/references/bcp-plus.md` for the NFR Gate pattern.

91## Architecture

93Collection of verb-noun skills under `skills/`, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.

95## Conventions

97- Skill directories under `skills/` use verb-noun naming (two words, kebab-case)

98- Every skill has a single SKILL.md file as its source of truth

99- All planning/spec output goes to specs/ at project root

100- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts

101- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts

102- Website content in website/src/content/docs/ is auto-generated by prebuild; edit repo sources, not site files

103

104## Never

105

106- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files

107- Never edit website/src/content/docs/ directly — these are generated files; website/ is the fourth generated artifact target (alongside .cursor/, .gemini/, .pi/)

108- Never create a skill without a SKILL.md file and proper verb-noun naming

109- Never push changes without running sync-skills.sh first

110

111## Token Management

112

113**Mechanical backstop (e45s03):** `scripts/hooks/token-mgmt-pre-tool-use.sh` blocks oversized tool calls when prose rules are ignored. Wire as a `PreToolUse` hook for `Read`, `Grep`, and `Bash` (alongside `hooks/pre-tool-use.sh` for git safety). Thresholds: Read >100KB, Grep >200 matches without `head_limit`, Bash commands likely to exceed 500 output lines without `rtk`/`sqz compress`. Install snippet:

114

115```json

116{

117 "hooks": {

118 "PreToolUse": [

119 { "matcher": "Read|Grep|Bash", "hooks": [{ "type": "command", "command": "bash scripts/hooks/token-mgmt-pre-tool-use.sh" }] }

120 ]

121 }

122}

123```

124

125Context engineering (write/select/compress/isolate — see `docs/references/context-engineering.md`):

126

127- **Write (token-efficient content):** Short functions (4-20 lines), unique symbol names, headless tests. Don't restate code in comments.

128- **Select (include only what's relevant):** Use `bts_map` for ranked file lists, `survey-context` for phase bootstrap. Don't read files you don't need.

129- **Compress (reduce without losing structure):** Use `bts_compress` or pipe through `sqz compress`. Use `rtk` for build/test/git output (60-99% savings). Prefer `terse-mode` when context is heavy.

130- **Isolate (partition work):** Use `kickoff-branch` for isolated worktrees, `dispatch-agents` for parallel tasks with disjoint scopes, `session-state` for cold-start handoff.

131

132**Effort classification:** Skills carry an `effort:` frontmatter field (`light` | `standard` | `heavy`). Prefer `light` skills for bootstrap/status checks; reserve `heavy` for epic builds and multi-phase planning.

133

134- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.

135- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.

136- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.

137- **Stream Stability**: When writing large files or long documents, output continuously in chunks of ~200 lines. Do not pause. If you need time to process, emit a placeholder comment rather than going silent.

138

139## Session Start

140

141Before any task, run this sequence — not optional:

142

1431. Read `CLAUDE.md` (this file)

1442. Read `CONVENTIONS.md`

1453. Read `specs/state.yaml` if it exists — current session and active epic

1464. Read `specs/release-plan.yaml` if it exists — active release context

147

148## Agent Rules

149

150- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".

151- **Always Green / fix-or-log:** Preflight and CI must be green before forward work. Any reproducible gate failure during unrelated work requires **quick-fix** or **fix-bug** — see CONVENTIONS § Discovered Defects. Never dismiss failures as pre-existing or out of scope.

152- Read specs/ and CONVENTIONS.md before writing code.

153- Write the minimum code that solves the stated problem. Nothing extra.

154- Run tests after every change. Show evidence before declaring done.

155- One clarifying question beats a wrong assumption baked into 200 lines.

156- All written output (plans, specs, investigations) goes in specs/.

157

158## bts toolchain

159

160`bts` is installed. Prefer its verbs over ad-hoc shell commands.

161

162| Task | Command | Avoid |

163|------|---------|-------|

164| Search code | `bts find --print <pattern>` | grep / find / cat |

165| Interactive search | `bts find <pattern>` | manual grep pipes |

167| Repo map | `bts map` | listing files by hand |

168| Library docs | `bts docs <lib>` | guessing from training data |

169| Package source | `bts src <pkg>` | git clone |

170| Toolchain health | `bts doctor` | which / command -v |

171

172**Rules**

173- Search with `bts find` before opening files to locate a symbol or pattern.

174- Pipe anything > 200 lines through `bts compress` before adding to context.

175- Run `bts map` when asked for a repo overview.

176- Use `bts docs <lib>` before answering questions about library APIs. Doc fetches use `scripts/lib/doc-fetch-cache.sh` (ETag-revalidated, 300s TTL — see `context7-mcp` skill, e45s20).

177- If a tool is missing, say so and run `bts doctor` — do not silently substitute.

178

179

180

181**RTK hook (installed):** `scripts/hooks/rtk-rewrite.sh` is symlinked into `~/.claude/hooks/` by `bash scripts/install.sh` and registered as a Bash `PreToolUse` hook. It delegates to `rtk hook claude` — prose rules below are a fallback only when the hook is absent.

182

183

184

185

186

187## sqz — Context Compression (READ FIRST)

188

189sqz is installed in this project. It compresses tool output so large

190files, long logs, and verbose command output cost far fewer tokens.

191There are **two ways** sqz is wired in, and you should prefer each

192one in the situations below.

193

194### Preferred tools (MCP)

195

196The `sqz-mcp` server is registered in this project's MCP config. It

197exposes three read-only tools that compress their output through the

198sqz pipeline:

199

200- **`sqz_read_file`** — read a file from disk and return a compressed

201 view. **PREFER this over the built-in `Read` tool** for any file

202 larger than ~2KB or any file you might read more than once in the

203 same session. Repeat reads return a 13-token `§ref:HASH§` reference

204 instead of the full content.

205

206- **`sqz_grep`** — search files for a literal string or regex.

207 **PREFER this over the built-in `Grep`** for anything that might

208 match more than a handful of lines. Caps at 200 matches by default;

209 raise with `max_matches` if needed.

210

211- **`sqz_list_dir`** — list a directory. Skips `.git`, `node_modules`,

212 `target`, `dist`, `build`, `vendor`, `__pycache__` so the output

213 stays focused. **PREFER this over `ls -la` via Bash** when you want

214 to see a project layout.

215

216The built-in `Read`, `Grep`, `Glob` tools remain available. Use them for:

217- Tiny config files (<1KB) where compression can't help.

218- Byte-exact reads you'll hash or diff (lockfiles, signatures).

219- Globbing (sqz has no glob tool; `Glob` is still the right choice).

220

221### Bash commands (hooked automatically)

222

223When you run a shell command through the `Bash` tool, a PreToolUse hook

224rewrites it to pipe output through `sqz compress`. This is transparent:

225you don't need to remember to add anything, but it's useful to know

226that these commands get compressed automatically:

227

228```bash

229git status # → git status 2>&1 | sqz compress --cmd git

230cargo test # → cargo test 2>&1 | sqz compress --cmd cargo

231docker ps # → docker ps 2>&1 | sqz compress --cmd docker

232kubectl get pods # → kubectl get pods 2>&1 | sqz compress --cmd kubectl

233```

234

235The rewrite is skipped for interactive commands (`vim`, `ssh`,

236`python`), compound commands (`a && b`, `a > file.txt`), and anything

237already going through sqz.

238

239### Escape hatch — when you see a `§ref:HASH§` token

240

241If tool output contains a `§ref:a1b2c3d4§` token and you need the full

242content it points at, resolve it. Three equivalent ways:

243

244- Shell: `/Users/danielvm/.local/bin/sqz expand a1b2c3d4` (or paste the whole token

245 `/Users/danielvm/.local/bin/sqz expand §ref:a1b2c3d4§`).

246- MCP tool: call `expand` with `{ "prefix": "a1b2c3d4" }`.

247- To get uncompressed output for one command: prefix it with

248 `SQZ_NO_DEDUP=1` (e.g. `SQZ_NO_DEDUP=1 git log | sqz compress`).

249

250If the compressed output is actively making the task harder (looping

251on refs, small retries replacing one big read), call the `passthrough`

252MCP tool to get raw text.

253

254### When NOT to use sqz tools

255

256- Writing or editing files — use the built-in `Write`/`Edit` tools.

257 sqz has no write tools (by design; see issue #5 follow-up).

258- Running commands interactively or in watch mode.

259- Reading very small files (<1KB) where compression can't help.

260

261

262

263

264# RTK (Rust Token Killer) - Token-Optimized Commands

265

266## Golden Rule

267

268**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.

269

270**Important**: Even in command chains with `&&`, use `rtk`:

271```bash

272# ❌ Wrong

273git add . && git commit -m "msg" && git push

274

275# ✅ Correct

276rtk git add . && rtk git commit -m "msg" && rtk git push

277```

278

279## RTK Commands by Workflow

280

281### Build & Compile (80-90% savings)

282```bash

283rtk cargo build # Cargo build output

284rtk cargo check # Cargo check output

285rtk cargo clippy # Clippy warnings grouped by file (80%)

286rtk tsc # TypeScript errors grouped by file/code (83%)

287rtk lint # ESLint/Biome violations grouped (84%)

288rtk prettier --check # Files needing format only (70%)

289rtk next build # Next.js build with route metrics (87%)

290```

291

292### Test (60-99% savings)

293```bash

294rtk cargo test # Cargo test failures only (90%)

295rtk go test # Go test failures only (90%)

296rtk jest # Jest failures only (99.5%)

297rtk vitest # Vitest failures only (99.5%)

298rtk playwright test # Playwright failures only (94%)

299rtk pytest # Python test failures only (90%)

300rtk rake test # Ruby test failures only (90%)

301rtk rspec # RSpec test failures only (60%)

302rtk test <cmd> # Generic test wrapper - failures only

303```

304

305### Git (59-80% savings)

306```bash

307rtk git status # Compact status

308rtk git log # Compact log (works with all git flags)

309rtk git diff # Compact diff (80%)

310rtk git show # Compact show (80%)

311rtk git add # Ultra-compact confirmations (59%)

312rtk git commit # Ultra-compact confirmations (59%)

313rtk git push # Ultra-compact confirmations

314rtk git pull # Ultra-compact confirmations

315rtk git branch # Compact branch list

316rtk git fetch # Compact fetch

317rtk git stash # Compact stash

318rtk git worktree # Compact worktree

319```

320

321Note: Git passthrough works for ALL subcommands, even those not explicitly listed.

322

323### GitHub (26-87% savings)

324```bash

325rtk gh pr view <num> # Compact PR view (87%)

326rtk gh pr checks # Compact PR checks (79%)

327rtk gh run list # Compact workflow runs (82%)

328rtk gh issue list # Compact issue list (80%)

329rtk gh api # Compact API responses (26%)

330```

331

332### JavaScript/TypeScript Tooling (70-90% savings)

333```bash

334rtk pnpm list # Compact dependency tree (70%)

335rtk pnpm outdated # Compact outdated packages (80%)

336rtk pnpm install # Compact install output (90%)

337rtk npm run <script> # Compact npm script output

338rtk npx <cmd> # Compact npx command output

339rtk prisma # Prisma without ASCII art (88%)

340```

341

342### Files & Search (60-75% savings)

343```bash

344rtk ls <path> # Tree format, compact (65%)

345rtk read <file> # Code reading with filtering (60%)

346rtk grep <pattern> # Search grouped by file (75%). Format flags (-c, -l, -L, -o, -Z) run raw.

347rtk find <pattern> # Find grouped by directory (70%)

348```

349

350### Analysis & Debug (70-90% savings)

351```bash

352rtk err <cmd> # Filter errors only from any command

353rtk log <file> # Deduplicated logs with counts

354rtk json <file> # JSON structure without values

355rtk deps # Dependency overview

356rtk env # Environment variables compact

357rtk summary <cmd> # Smart summary of command output

358rtk diff # Ultra-compact diffs

359```

360

361### Infrastructure (85% savings)

362```bash

363rtk docker ps # Compact container list

364rtk docker images # Compact image list

365rtk docker logs <c> # Deduplicated logs

366rtk kubectl get # Compact resource list

367rtk kubectl logs # Deduplicated pod logs

368```

369

370### Network (65-70% savings)

371```bash

372rtk curl <url> # Compact HTTP responses (70%)

373rtk wget <url> # Compact download output (65%)

374```

375

376### Meta Commands

377```bash

378rtk gain # View token savings statistics

379rtk gain --history # View command history with savings

380rtk discover # Analyze Claude Code sessions for missed RTK usage

381rtk proxy <cmd> # Run command without filtering (for debugging)

382rtk init # Add RTK instructions to CLAUDE.md

383rtk init --global # Add RTK to ~/.claude/CLAUDE.md

384```

385

386## Token Savings Overview

387

388| Category | Commands | Typical Savings |

389|----------|----------|-----------------|

390| Tests | vitest, playwright, cargo test | 90-99% |

391| Build | next, tsc, lint, prettier | 70-87% |

392| Git | status, log, diff, add, commit | 59-80% |

393| GitHub | gh pr, gh run, gh issue | 26-87% |

394| Package Managers | pnpm, npm, npx | 70-90% |

395| Files | ls, read, grep, find | 60-75% |

396| Infrastructure | docker, kubectl | 85% |

397| Network | curl, wget | 65-70% |

398

399Overall average: **60-90% token reduction** on common development operations.

400

@@ −1 +1 @@

1−## Development

1+# story: e38s08

2+# story: e51s05

3+# story: e45s22

4+# story: e45s23

5+# story: e55s03

3−When starting the dev server, use background mode:

7+# bigpowers — Claude Code

9+Read CONVENTIONS.md before any GitHub or git operation.

10+

11+[`constitution.md`](constitution.md) is a consolidated entry point synthesizing

12+this project's doctrine (this file, CONVENTIONS.md, docs/PRINCIPLES.md,

13+docs/references/*.md) into bigspec's B0-B10 + Capstone blocks, with citations

14+back to the fuller text. It's a starting point for a reader, not a

15+replacement — this file remains fully authoritative for its own content today.

16+

17+

18+## Context Routing

19+

20+Load subdirectory context **by file glob** — do not read the full doc tree up front.

21+

22+| Glob / trigger | Load first | Fallback |

23+|----------------|------------|----------|

24+| `skills/**` | Active skill's `SKILL.md` + sibling `REFERENCE.md` if linked | `SKILL-INDEX.md` |

25+| `specs/epics/**` | Capsule `epic.yaml` + active story `-tasks.yaml` | `specs/release-plan.yaml` |

26+| `specs/product/**` | `SCOPE_LATEST.yaml`, `VISION_LATEST.yaml` | `specs/README.md` |

27+| `specs/tech-architecture/**` | `tech-stack.md` + epic `eNN-TEST_PLAN_LATEST.md` if present | `CONVENTIONS.md` |

28+| `scripts/**` | `CONVENTIONS.md` § Generated artifact targets | This file § Commands |

29+| `website/**` | `website/README.md` if present | Never edit `website/src/content/docs/` (generated) |

30+| `docs/**` | Matching doc under `docs/` | `docs/references/` |

31+| Default / session start | This file → `CONVENTIONS.md` → `specs/state.yaml` | `survey-context` |

32+

33+Sub-AGENTS.md files (when present in consumer projects) override this table for their directory only.

34+

35+

36+

37+## Learned User Preferences

38+

39+_Durable preferences discovered across sessions. Update via `session-state` — do not infer from chat alone._

40+

41+- Prefer `rtk`-prefixed shell commands for git, test, and build output (token savings).

42+- Run Preflight before forward work; never dismiss red gates as pre-existing.

43+- Edit `skills/*/SKILL.md` sources only — never `.cursor/rules/` or `.gemini/` artifacts.

44+

45+## Workspace Facts

46+

47+_Stable repo facts — prefer these over re-discovery._

48+

49+- Stack: Markdown / Bash documentation project; skills sync via `bash scripts/sync-skills.sh`.

50+- Planning SoT: `specs/state.yaml`, `specs/release-plan.yaml`, `specs/execution-status.yaml`.

51+- Story traceability: `# story: eNNsNN` tags in implementing files; `bash scripts/trace-stories.sh --strict` in CI.

52+- Rule matrix: `bash scripts/compile-rule-matrix.sh` → `specs/rule-matrix.json` (P0–P3 tiers from CONVENTIONS.md).

53+

54+

55+## Project

56+

57+bigpowers — agent skills for spec-driven, test-first software development by solo developers (skill count and catalog are auto-generated in `SKILL-INDEX.md`; never hardcode the count in docs).

58+Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)

59+

60+## Commands

61+

62+| Action | Command |

63+|---------|---------|

64+| Install | `npm install -g bigpowers && bigpowers setup` |

65+| Run | `bash scripts/sync-skills.sh` |

66+| Test | N/A (documentation project) |

67+| Build | `bash scripts/install.sh` (from source) |

68+| Lint | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |

69+| Validate specs YAML | `bash scripts/validate-specs-yaml.sh` |

70+| Typecheck | N/A (Markdown / Bash project) |

71+| CI platform | GitHub Actions (`.github/workflows/publish.yml`, `sync-skills.yml`, `golden-suite.yml`) |

72+| Compliance | `npm run compliance` |

73+| Verification Gates | `bash scripts/run-verification-gates.sh` |

74+| Traceability | `bash scripts/trace-stories.sh --strict` | grep for story tags (traceability check) |

75+| Preflight | `npm run compliance && bash scripts/run-verification-gates.sh && bash scripts/sync-skills.sh && bash scripts/trace-stories.sh --strict` | Full local green stack before forward work. Chain ends on `--strict` traceability — no trailing always-exit-0 step. |

76+| Catalog drift (advisory) | `bash scripts/check-catalog-drift.sh` | e54s02 Confirm gate during catalog freeze — always exits 0; run manually when changing skills, not part of Preflight. |

77+| CI | `gh pr checks` | Remote CI green when a PR is open |

78+

79+### Pre-Merge Checklist

80+

81+Before opening a PR or landing a branch, run:

82+

83+```bash

84+npm run compliance && bash scripts/run-verification-gates.sh

585 ```

6−astro dev --background

86+

87+If any gate fails, fix before merging. Run `--baseline` after any intentional increase in skill count or structure.

88+

89+**BCP Plus:** For stories sized with the 13-dimension BCP Plus methodology, confirm the `bcp_plus_breakdown` is present in the epic YAML and carried into `state.yaml` as `epic_cycle.bcp_plus`. See `docs/references/bcp-plus.md` for the NFR Gate pattern.

90+

91+## Architecture

92+

93+Collection of verb-noun skills under `skills/`, each with a SKILL.md source file and supporting documentation. Runtime specs live in `specs/state.yaml`, `specs/release-plan.yaml`, and `specs/execution-status.yaml`; intent in `specs/product/`; epic shards in `specs/epics/`. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning output goes to specs/ at the project root.

94+

95+## Conventions

96+

97+- Skill directories under `skills/` use verb-noun naming (two words, kebab-case)

98+- Every skill has a single SKILL.md file as its source of truth

99+- All planning/spec output goes to specs/ at project root

100+- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts

101+- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts

102+- Website content in website/src/content/docs/ is auto-generated by prebuild; edit repo sources, not site files

103+

104+## Never

105+

106+- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files

107+- Never edit website/src/content/docs/ directly — these are generated files; website/ is the fourth generated artifact target (alongside .cursor/, .gemini/, .pi/)

108+- Never create a skill without a SKILL.md file and proper verb-noun naming

109+- Never push changes without running sync-skills.sh first

110+

111+## Token Management

112+

113+**Mechanical backstop (e45s03):** `scripts/hooks/token-mgmt-pre-tool-use.sh` blocks oversized tool calls when prose rules are ignored. Wire as a `PreToolUse` hook for `Read`, `Grep`, and `Bash` (alongside `hooks/pre-tool-use.sh` for git safety). Thresholds: Read >100KB, Grep >200 matches without `head_limit`, Bash commands likely to exceed 500 output lines without `rtk`/`sqz compress`. Install snippet:

114+

115+```json

116+{

117+ "hooks": {

118+ "PreToolUse": [

119+ { "matcher": "Read|Grep|Bash", "hooks": [{ "type": "command", "command": "bash scripts/hooks/token-mgmt-pre-tool-use.sh" }] }

120+ ]

121+ }

122+}

7123 ```

8124

9−Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.

125+Context engineering (write/select/compress/isolate — see `docs/references/context-engineering.md`):

10126

11−## Documentation

127+- **Write (token-efficient content):** Short functions (4-20 lines), unique symbol names, headless tests. Don't restate code in comments.

128+- **Select (include only what's relevant):** Use `bts_map` for ranked file lists, `survey-context` for phase bootstrap. Don't read files you don't need.

129+- **Compress (reduce without losing structure):** Use `bts_compress` or pipe through `sqz compress`. Use `rtk` for build/test/git output (60-99% savings). Prefer `terse-mode` when context is heavy.

130+- **Isolate (partition work):** Use `kickoff-branch` for isolated worktrees, `dispatch-agents` for parallel tasks with disjoint scopes, `session-state` for cold-start handoff.

12131

13−Full documentation: https://docs.astro.build

132+**Effort classification:** Skills carry an `effort:` frontmatter field (`light` | `standard` | `heavy`). Prefer `light` skills for bootstrap/status checks; reserve `heavy` for epic builds and multi-phase planning.

14133

15−Consult these guides before working on related tasks:

134+- **Auto-Terse**: When a session exceeds 20 turns or the context window feels "heavy" (latency increasing), you MUST switch to `terse-mode` to save tokens.

135+- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.

136+- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.

137+- **Stream Stability**: When writing large files or long documents, output continuously in chunks of ~200 lines. Do not pause. If you need time to process, emit a placeholder comment rather than going silent.

16138

17−- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)

18−- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)

19−- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)

20−- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)

21−- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)

22−- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)

139+## Session Start

23140

141+Before any task, run this sequence — not optional:

142+

143+1. Read `CLAUDE.md` (this file)

144+2. Read `CONVENTIONS.md`

145+3. Read `specs/state.yaml` if it exists — current session and active epic

146+4. Read `specs/release-plan.yaml` if it exists — active release context

147+

148+## Agent Rules

149+

150+- **Workflow Mandate:** You MUST use the bigpowers skills (e.g., `plan-work`, `develop-tdd`, `craft-skill`) to perform tasks. DO NOT write code directly in response to a user prompt like "build this feature".

151+- **Always Green / fix-or-log:** Preflight and CI must be green before forward work. Any reproducible gate failure during unrelated work requires **quick-fix** or **fix-bug** — see CONVENTIONS § Discovered Defects. Never dismiss failures as pre-existing or out of scope.

152+- Read specs/ and CONVENTIONS.md before writing code.

153+- Write the minimum code that solves the stated problem. Nothing extra.

154+- Run tests after every change. Show evidence before declaring done.

155+- One clarifying question beats a wrong assumption baked into 200 lines.

156+- All written output (plans, specs, investigations) goes in specs/.

157+

158+## bts toolchain

159+

160+`bts` is installed. Prefer its verbs over ad-hoc shell commands.

161+

162+| Task | Command | Avoid |

163+|------|---------|-------|

164+| Search code | `bts find --print <pattern>` | grep / find / cat |

165+| Interactive search | `bts find <pattern>` | manual grep pipes |

167+| Repo map | `bts map` | listing files by hand |

168+| Library docs | `bts docs <lib>` | guessing from training data |

169+| Package source | `bts src <pkg>` | git clone |

170+| Toolchain health | `bts doctor` | which / command -v |

171+

172+**Rules**

173+- Search with `bts find` before opening files to locate a symbol or pattern.

174+- Pipe anything > 200 lines through `bts compress` before adding to context.

175+- Run `bts map` when asked for a repo overview.

176+- Use `bts docs <lib>` before answering questions about library APIs. Doc fetches use `scripts/lib/doc-fetch-cache.sh` (ETag-revalidated, 300s TTL — see `context7-mcp` skill, e45s20).

177+- If a tool is missing, say so and run `bts doctor` — do not silently substitute.

178+

179+

180+

181+**RTK hook (installed):** `scripts/hooks/rtk-rewrite.sh` is symlinked into `~/.claude/hooks/` by `bash scripts/install.sh` and registered as a Bash `PreToolUse` hook. It delegates to `rtk hook claude` — prose rules below are a fallback only when the hook is absent.

182+

183+

184+

185+

186+

187+## sqz — Context Compression (READ FIRST)

188+

189+sqz is installed in this project. It compresses tool output so large

190+files, long logs, and verbose command output cost far fewer tokens.

191+There are **two ways** sqz is wired in, and you should prefer each

192+one in the situations below.

193+

194+### Preferred tools (MCP)

195+

196+The `sqz-mcp` server is registered in this project's MCP config. It

197+exposes three read-only tools that compress their output through the

198+sqz pipeline:

199+

200+- **`sqz_read_file`** — read a file from disk and return a compressed

201+ view. **PREFER this over the built-in `Read` tool** for any file

202+ larger than ~2KB or any file you might read more than once in the

203+ same session. Repeat reads return a 13-token `§ref:HASH§` reference

204+ instead of the full content.

205+

206+- **`sqz_grep`** — search files for a literal string or regex.

207+ **PREFER this over the built-in `Grep`** for anything that might

208+ match more than a handful of lines. Caps at 200 matches by default;

209+ raise with `max_matches` if needed.

210+

211+- **`sqz_list_dir`** — list a directory. Skips `.git`, `node_modules`,

212+ `target`, `dist`, `build`, `vendor`, `__pycache__` so the output

213+ stays focused. **PREFER this over `ls -la` via Bash** when you want

214+ to see a project layout.

215+

216+The built-in `Read`, `Grep`, `Glob` tools remain available. Use them for:

217+- Tiny config files (<1KB) where compression can't help.

218+- Byte-exact reads you'll hash or diff (lockfiles, signatures).

219+- Globbing (sqz has no glob tool; `Glob` is still the right choice).

220+

221+### Bash commands (hooked automatically)

222+

223+When you run a shell command through the `Bash` tool, a PreToolUse hook

224+rewrites it to pipe output through `sqz compress`. This is transparent:

225+you don't need to remember to add anything, but it's useful to know

226+that these commands get compressed automatically:

227+

228+```bash

229+git status # → git status 2>&1 | sqz compress --cmd git

230+cargo test # → cargo test 2>&1 | sqz compress --cmd cargo

231+docker ps # → docker ps 2>&1 | sqz compress --cmd docker

232+kubectl get pods # → kubectl get pods 2>&1 | sqz compress --cmd kubectl

233+```

234+

235+The rewrite is skipped for interactive commands (`vim`, `ssh`,

236+`python`), compound commands (`a && b`, `a > file.txt`), and anything

237+already going through sqz.

238+

239+### Escape hatch — when you see a `§ref:HASH§` token

240+

241+If tool output contains a `§ref:a1b2c3d4§` token and you need the full

242+content it points at, resolve it. Three equivalent ways:

243+

244+- Shell: `/Users/danielvm/.local/bin/sqz expand a1b2c3d4` (or paste the whole token

245+ `/Users/danielvm/.local/bin/sqz expand §ref:a1b2c3d4§`).

246+- MCP tool: call `expand` with `{ "prefix": "a1b2c3d4" }`.

247+- To get uncompressed output for one command: prefix it with

248+ `SQZ_NO_DEDUP=1` (e.g. `SQZ_NO_DEDUP=1 git log | sqz compress`).

249+

250+If the compressed output is actively making the task harder (looping

251+on refs, small retries replacing one big read), call the `passthrough`

252+MCP tool to get raw text.

253+

254+### When NOT to use sqz tools

255+

256+- Writing or editing files — use the built-in `Write`/`Edit` tools.

257+ sqz has no write tools (by design; see issue #5 follow-up).

258+- Running commands interactively or in watch mode.

259+- Reading very small files (<1KB) where compression can't help.

260+

261+

262+

263+

264+# RTK (Rust Token Killer) - Token-Optimized Commands

265+

266+## Golden Rule

267+

268+**Always prefix commands with `rtk`**. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.

269+

270+**Important**: Even in command chains with `&&`, use `rtk`:

271+```bash

272+# ❌ Wrong

273+git add . && git commit -m "msg" && git push

274+

275+# ✅ Correct

276+rtk git add . && rtk git commit -m "msg" && rtk git push

277+```

278+

279+## RTK Commands by Workflow

280+

281+### Build & Compile (80-90% savings)

282+```bash

283+rtk cargo build # Cargo build output

284+rtk cargo check # Cargo check output

285+rtk cargo clippy # Clippy warnings grouped by file (80%)

286+rtk tsc # TypeScript errors grouped by file/code (83%)

287+rtk lint # ESLint/Biome violations grouped (84%)

288+rtk prettier --check # Files needing format only (70%)

289+rtk next build # Next.js build with route metrics (87%)

290+```

291+

292+### Test (60-99% savings)

293+```bash

294+rtk cargo test # Cargo test failures only (90%)

295+rtk go test # Go test failures only (90%)

296+rtk jest # Jest failures only (99.5%)

297+rtk vitest # Vitest failures only (99.5%)

298+rtk playwright test # Playwright failures only (94%)

299+rtk pytest # Python test failures only (90%)

300+rtk rake test # Ruby test failures only (90%)

301+rtk rspec # RSpec test failures only (60%)

302+rtk test <cmd> # Generic test wrapper - failures only

303+```

304+

305+### Git (59-80% savings)

306+```bash

307+rtk git status # Compact status

308+rtk git log # Compact log (works with all git flags)

309+rtk git diff # Compact diff (80%)

310+rtk git show # Compact show (80%)

311+rtk git add # Ultra-compact confirmations (59%)

312+rtk git commit # Ultra-compact confirmations (59%)

313+rtk git push # Ultra-compact confirmations

314+rtk git pull # Ultra-compact confirmations

315+rtk git branch # Compact branch list

316+rtk git fetch # Compact fetch

317+rtk git stash # Compact stash

318+rtk git worktree # Compact worktree

319+```

320+

321+Note: Git passthrough works for ALL subcommands, even those not explicitly listed.

322+

323+### GitHub (26-87% savings)

324+```bash

325+rtk gh pr view <num> # Compact PR view (87%)

326+rtk gh pr checks # Compact PR checks (79%)

327+rtk gh run list # Compact workflow runs (82%)

328+rtk gh issue list # Compact issue list (80%)

329+rtk gh api # Compact API responses (26%)

330+```

331+

332+### JavaScript/TypeScript Tooling (70-90% savings)

333+```bash

334+rtk pnpm list # Compact dependency tree (70%)

335+rtk pnpm outdated # Compact outdated packages (80%)

336+rtk pnpm install # Compact install output (90%)

337+rtk npm run <script> # Compact npm script output

338+rtk npx <cmd> # Compact npx command output

339+rtk prisma # Prisma without ASCII art (88%)

340+```

341+

342+### Files & Search (60-75% savings)

343+```bash

344+rtk ls <path> # Tree format, compact (65%)

345+rtk read <file> # Code reading with filtering (60%)

346+rtk grep <pattern> # Search grouped by file (75%). Format flags (-c, -l, -L, -o, -Z) run raw.

347+rtk find <pattern> # Find grouped by directory (70%)

348+```

349+

350+### Analysis & Debug (70-90% savings)

351+```bash

352+rtk err <cmd> # Filter errors only from any command

353+rtk log <file> # Deduplicated logs with counts

354+rtk json <file> # JSON structure without values

355+rtk deps # Dependency overview

356+rtk env # Environment variables compact

357+rtk summary <cmd> # Smart summary of command output

358+rtk diff # Ultra-compact diffs

359+```

360+

361+### Infrastructure (85% savings)

362+```bash

363+rtk docker ps # Compact container list

364+rtk docker images # Compact image list

365+rtk docker logs <c> # Deduplicated logs

366+rtk kubectl get # Compact resource list

367+rtk kubectl logs # Deduplicated pod logs

368+```

369+

370+### Network (65-70% savings)

371+```bash

372+rtk curl <url> # Compact HTTP responses (70%)

373+rtk wget <url> # Compact download output (65%)

374+```

375+

376+### Meta Commands

377+```bash

378+rtk gain # View token savings statistics

379+rtk gain --history # View command history with savings

380+rtk discover # Analyze Claude Code sessions for missed RTK usage

381+rtk proxy <cmd> # Run command without filtering (for debugging)

382+rtk init # Add RTK instructions to CLAUDE.md

383+rtk init --global # Add RTK to ~/.claude/CLAUDE.md

384+```

385+

386+## Token Savings Overview

387+

388+| Category | Commands | Typical Savings |

389+|----------|----------|-----------------|

390+| Tests | vitest, playwright, cargo test | 90-99% |

391+| Build | next, tsc, lint, prettier | 70-87% |

392+| Git | status, log, diff, add, commit | 59-80% |

393+| GitHub | gh pr, gh run, gh issue | 26-87% |

394+| Package Managers | pnpm, npm, npx | 70-90% |

395+| Files | ls, read, grep, find | 60-75% |

396+| Infrastructure | docker, kubectl | 85% |

397+| Network | curl, wget | 65-70% |

398+

399+Overall average: **60-90% token reduction** on common development operations.

400+