GEMINI.md

1# bigpowers — Gemini CLI
2 
3> **Auto-generated** by `sync-skills.sh` from `CLAUDE.md`. Edit CLAUDE.md, not this file.
4 
5Read CONVENTIONS.md before any GitHub or git operation.
6 
7## Project
8 
9bigpowers — 58 agent skills for spec-driven, test-first software development by solo developers.
10Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code, Cursor, Gemini CLI)
11 
12## Commands
13 
14| Action  | Command |
15|---------|---------|
16| Install | `npm install -g bigpowers && bigpowers setup` |
17| Run     | `bash scripts/sync-skills.sh` |
18| Test    | N/A (documentation project) |
19| Build   | `bash scripts/install.sh` (from source) |
20| Lint    | `bash scripts/sync-skills.sh` (validates SKILL.md syntax) |
21 
22## Architecture
23 
24Collection of 58 verb-noun skills, each with a SKILL.md source file and supporting documentation. Includes Verify phase and profiles/. The sync-skills.sh script auto-generates artifacts for Cursor (.cursor/rules) and Gemini CLI (.gemini/extensions/bigpowers/) from SKILL.md sources. All planning and spec output goes to specs/ at the project root.
25 
26## Conventions
27 
28- Skill directories use verb-noun naming (two words, kebab-case)
29- Every skill has a single SKILL.md file as its source of truth
30- All planning/spec output goes to specs/ at project root
31- Artifacts in .cursor/rules and .gemini/ are auto-generated; edit SKILL.md, not artifacts
32- Run sync-skills.sh after any SKILL.md changes to regenerate artifacts
33 
34## Never
35 
36- Never edit .cursor/rules or .gemini/extensions/ directly — these are generated files
37- Never create a skill without a SKILL.md file and proper verb-noun naming
38- Never push changes without running sync-skills.sh first
39 
40## Token Management
41 
42- **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.
43- **Context Compaction**: Every 10 turns, summarize the current session state and implementation decisions into a short, high-density note.
44- **Minimal Output**: Prefer text-only output for simple status; use `web_fetch` or `run_shell_command` only for evidence.
45 
46## Agent Rules
47 
48- **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".
49- Read specs/ and CONVENTIONS.md before writing code.
50- Write the minimum code that solves the stated problem. Nothing extra.
51- Never refactor, rename, or reorganize code outside the task scope.
52- Run tests after every change. Show evidence before declaring done.
53- One clarifying question beats a wrong assumption baked into 200 lines.
54- All written output (plans, specs, investigations) goes in specs/.
55 
56## bts toolchain
57 
58`bts` is installed. Prefer its verbs over ad-hoc shell commands.
59 
60| Task | Command | Avoid |
61|------|---------|-------|
62| Search code | `bts find --print <pattern>` | grep / find / cat |
63| Interactive search | `bts find <pattern>` | manual grep pipes |
64| Compress for context | `bts compress <file>` or `cmd \| bts compress` | summarising by hand |
65| Repo map | `bts map` | listing files by hand |
66| Library docs | `bts docs <lib>` | guessing from training data |
67| Package source | `bts src <pkg>` | git clone |
68| Toolchain health | `bts doctor` | which / command -v |
69 
70**Rules**
71- Search with `bts find` before opening files to locate a symbol or pattern.
72- Pipe anything > 200 lines through `bts compress` before adding to context.
73- Run `bts map` when asked for a repo overview.
74- Use `bts docs <lib>` before answering questions about library APIs.
75- If a tool is missing, say so and run `bts doctor` — do not silently substitute.
76