GEMINI.md

1# GEMINI.md - System Instructions for Gemini CLI
2 
3You are working in a **SAFe multi-agent development environment** using the {{PROJECT_SHORT}} (Words to Film By) Agentic Workflow methodology.
4 
5## Key Principles
6 
7### Pattern-First Development
8"Search First, Reuse Always, Create Only When Necessary"
9 
10Before implementing any feature:
111. Search existing patterns in `patterns_library/`
122. Check existing specs in `specs/`
133. Review documentation in `docs/`
144. Only create new patterns when necessary
15 
16### Evidence-Based Delivery
17All work requires verifiable evidence attached to Linear tickets:
18- **Dev Phase**: Test results, command output, PR link
19- **Staging Phase**: UAT validation or N/A with reason
20- **Done Phase**: QA report, merge confirmation
21 
22### Round Table Philosophy
23- Equal voice: AI and human input have equal weight
24- Mutual respect: All perspectives respected
25- Stop-the-line authority: Flag architectural or security concerns
26 
27## Available Skills
28 
29Skills auto-load when context matches. All 19 skills:
30 
31| Skill | Trigger When |
32|-------|--------------|
33| `safe-workflow` | Starting work, commits, branches, PRs |
34| `safe-ai-dlc` | Planning or running a multi-issue program |
35| `vault-sync` | Knowledge vault drift or staleness |
36| `pattern-discovery` | Before implementing features |
37| `rls-patterns` | Database operations, RLS policies |
38| `api-patterns` | Creating API endpoints |
39| `frontend-patterns` | UI components, pages |
40| `testing-patterns` | Writing tests |
41| `security-audit` | Security validation |
42| `linear-sop` | Ticket management |
43| `deployment-sop` | Deploying code |
44| `orchestration-patterns` | Multi-step workflows, pipelines |
45| `agent-coordination` | Multi-agent collaboration |
46| `spec-creation` | Writing SAFe specs (Epic/Feature/Story) |
47| `release-patterns` | Release management, versioning |
48| `git-advanced` | Rebasing, cherry-pick, conflict resolution |
49| `stripe-patterns` | Payment integration, webhooks |
50| `confluence-docs` | Confluence documentation, templates |
51| `migration-patterns` | Database migrations, schema changes |
52 
53## Available Commands
54 
55Commands are invoked with `/namespace:command` or `/command`:
56 
57### Workflow Commands
58- `/workflow:start-work [ticket]` - Start work on Linear ticket
59- `/workflow:pre-pr` - Pre-PR validation checklist
60- `/workflow:end-work` - Complete work session
61- `/workflow:check-workflow` - Quick workflow health check
62- `/workflow:sync-linear` - Sync work with Linear ticket
63- `/workflow:quick-fix [ticket]` - Fast-track bug fix workflow
64- `/workflow:update-docs` - Update relevant documentation
65- `/workflow:retro` - Conduct retrospective
66 
67### Local Commands
68- `/local:sync` - Sync local dev environment after git pull
69- `/local:deploy` - Deploy Docker image locally
70 
71### Remote Commands
72- `/remote:status` - Check if remote needs updating
73- `/remote:deploy` - Deploy to remote staging
74- `/remote:health` - Health dashboard
75- `/remote:logs` - View container logs
76- `/remote:rollback [sha]` - Rollback to previous version
77 
78### Other Commands
79- `/test-pr-docker [PR]` - Test PR Docker workflow
80- `/audit-deps` - Comprehensive dependency audit
81- `/search-pattern <pattern>` - Search codebase for patterns
82 
83### Media Commands
84- `/media:analyze-images <dir>` - Analyze images using vision
85- `/media:extract-pdf <file>` - Extract structured data from PDFs
86- `/media:sketch-to-code <image>` - Generate code from UI sketches
87- `/media:organize-files <dir>` - Organize files based on content
88- `/media:transcribe-audio <file>` - Transcribe audio to text/SRT/VTT
89- `/media:analyze-audio <file>` - Analyze audio content and mood
90- `/media:extract-dialogue <file>` - Extract dialogue with speaker diarization
91- `/media:analyze-video <file>` - Analyze video scene by scene
92- `/media:extract-frames <file>` - Extract key frames with descriptions
93- `/media:video-to-script <file>` - Generate screenplay from video
94- `/media:scene-detect <file>` - Detect scene transitions with timestamps
95 
96### Built-in Commands (Gemini CLI v0.32+)
97- `/plan` - Enter plan mode for complex tasks
98- `/rewind` - Navigate to a previous point in the session
99- `/introspect` - Debug session state and context
100- `/prompt-suggest` - Generate prompt suggestions
101- `/hooks` - Manage lifecycle hooks (panel, enable, disable)
102- `/skills` - Manage agent skills (list, link, enable, disable)
103- `/settings` - View and edit settings interactively
104- `/restore` - Restore from a checkpoint
105 
106## SAFe Workflow
107 
108### Branch Naming
109```
110{{TICKET_PREFIX}}-{number}-{short-description}
111```
112Example: `{{TICKET_PREFIX}}-123-add-user-profile`
113 
114### Commit Format
115```
116type(scope): description [{{TICKET_PREFIX}}-XXX]
117```
118Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
119 
120Example: `feat(user): add profile editing [{{TICKET_PREFIX}}-123]`
121 
122### PR Workflow
1231. Create feature branch from main
1242. Implement with pattern discovery
1253. Run `/workflow:pre-pr` validation
1264. Create PR with template
1275. QA review before merge
1286. Rebase and merge (linear history)
129 
130## RLS (Row Level Security) Requirements
131 
132**CRITICAL**: All database operations MUST use RLS context helpers:
133 
134```typescript
135// CORRECT - Always use context helpers
136const user = await withUserContext(prisma, userId, async (client) => {
137  return client.user.findUnique({ where: { user_id: userId } });
138});
139 
140// FORBIDDEN - Direct Prisma calls bypass RLS
141const user = await prisma.user.findUnique({ where: { user_id } }); // NEVER DO THIS
142```
143 
144Context helpers:
145- `withUserContext` - User-facing operations
146- `withAdminContext` - Admin operations
147- `withSystemContext` - Webhooks and background jobs
148 
149## Linear Integration
150 
151Since Gemini CLI doesn't have native Linear MCP integration, use:
152- **Linear Web UI**: https://linear.app
153- **Linear CLI**: `linear` command (if installed)
154- **Evidence Templates**: See `linear-sop` skill
155 
156> **Tip**: If your team uses GitHub-Linear auto-sync, tickets referenced in commit messages (e.g., `[WOR-123]`) auto-move to Done when the PR merges. Manually close child stories not referenced in commits.
157 
158## Agent Roles (Reference)
159 
160While Gemini doesn't have discrete agents, embody these roles as needed:
161 
162| Role | Responsibility |
163|------|----------------|
164| **BSA** | Requirements, specs, acceptance criteria |
165| **System Architect** | Pattern validation, architectural decisions |
166| **FE Developer** | Frontend components, UI |
167| **BE Developer** | Backend APIs, server logic |
168| **Data Engineer** | Database, migrations, RLS |
169| **QAS** | Testing, validation |
170| **Security Engineer** | Security audits, RLS validation |
171| **Tech Writer** | Documentation |
172| **RTE** | PR creation, releases |
173| **TDM** | Coordination, blockers |
174 
175## Stop-the-Line Conditions
176 
177**Immediately stop and escalate if you encounter:**
178 
1791. **Direct Prisma calls** - Must use RLS context helpers
1802. **Missing AC/DoD** - Route to BSA before implementation
1813. **Security vulnerabilities** - Hardcoded secrets, SQL injection
1824. **Architecture changes without approval** - Get ARCHitect sign-off
1835. **CI failures before merge** - Fix before proceeding
184 
185## Plan Mode (v0.29.0+)
186 
187Use `/plan` to enter plan mode before implementing complex changes. Gemini CLI will:
1881. Analyze the task and break it into steps
1892. Present the plan for your approval
1903. Execute the plan with tracking
191 
192Settings in `settings.json`:
193```json
194{
195  "general": {
196    "plan": { "directory": ".gemini/plans", "modelRouting": true }
197  }
198}
199```
200 
201## Policy Engine (v0.30.0+)
202 
203The policy engine provides fine-grained control over tool execution. Configure policies via:
204- `settings.json` → `policyPaths: ["path/to/policy.yaml"]`
205- CLI flag: `gemini --policy strict.yaml`
206 
207Policies can restrict tools, MCP servers (with wildcards), and match tool annotations.
208Replaces the deprecated `--allowed-tools` flag.
209 
210## Browser Agent (Experimental, v0.31.0+)
211 
212An experimental subagent that interacts with web pages via accessibility tree.
213- Navigate, fill forms, click elements, extract content
214- Configure in `settings.json` under `agents.browser`
215- Requires explicit opt-in via experimental flags
216 
217## Hooks System (v0.26.0+)
218 
219Hooks intercept Gemini CLI lifecycle events. Configure in `settings.json`:
220 
221| Event | When | Use Case |
222|-------|------|----------|
223| `SessionStart` | Session begins | Load context |
224| `BeforeAgent` | Before planning | Validate input |
225| `AfterAgent` | Loop completes | Review output |
226| `BeforeTool` | Before tool exec | Block operations |
227| `AfterTool` | After tool exec | Run tests |
228| `PreCompress` | Context compression | Save state |
229 
230Manage via `/hooks panel`, `/hooks enable-all`, `/hooks disable-all`.
231 
232## Extensions (v0.26.0+)
233 
234Extensions bundle skills, MCP servers, commands, and tool restrictions into shareable packages.
235- Install: `gemini extensions install <source>`
236- Skills are individual capabilities; extensions are the distribution format
237- Extension skills load at the Extension tier (lowest precedence after workspace and user)
238 
239## Checkpointing (v0.30.0+)
240 
241Session recovery via automatic checkpoints before file modifications.
242- Enable: `settings.json` → `general.checkpointing.enabled: true`
243- Restore: `/restore` command
244- Stored in `~/.gemini/tmp/<project_hash>/checkpoints`
245 
246## Model Configuration
247 
248| Model | Default Since | Notes |
249|-------|--------------|-------|
250| Gemini 3 Flash | v0.29.0 | Default for all users |
251| Gemini 3.1 Pro Preview | v0.31.0 | Higher capability |
252 
253Configure in `settings.json` → `model.name` or use `{{GEMINI_MODEL}}` placeholder.
254Plan mode can auto-switch between Flash (planning) and Pro (execution) via `plan.modelRouting`.
255 
256## Documentation Structure
257 
258```
259docs/
260├── onboarding/          # New user guides
261├── database/            # Schema, RLS, migrations
262├── security/            # Security architecture
263├── ci-cd/               # CI/CD pipeline
264├── sop/                 # Standard Operating Procedures
265├── workflow/            # Workflow templates
266└── adr/                 # Architecture Decision Records
267```
268 
269## Quick References
270 
271- **CONTRIBUTING.md**: Git workflow, commit standards
272- **AGENTS.md**: Agent team structure
273- **CLAUDE.md**: AI assistant context (compatible)
274- **docs/database/RLS_IMPLEMENTATION_GUIDE.md**: RLS patterns
275- **docs/database/DATA_DICTIONARY.md**: Database schema
276