Cline rules

1# AI Agent Guidelines
2 
3> Guidelines for AI agents working with Project Shisha.
4 
5## Agent Context
6 
7This is a **Bun workspaces monorepo** with 2 applications:
8 
9- `apps/fuel-advisor-bot` — Telegram fuel price bot
10- `apps/tablo-crawler` — Web crawler
11 
12The architecture prioritizes **predictability** and **agent-friendliness**.
13 
14---
15 
16## Quick Reference
17 
18### Required Files Per App
19 
20Every app in `apps/` MUST have:
21 
22- `Dockerfile` — Safe strategy (Bun runtime)
23- `Dockerfile.optimized` — Optimized (compiled binary)
24- `compose.yml` — Container config
25- `.env.example` — Environment template
26- `deploy.vars.yml` — Deployment metadata
27 
28### Key Paths
29 
30| Path                        | Purpose                |
31| --------------------------- | ---------------------- |
32| `apps/<app>/`               | Application source     |
33| `infra/compose/`            | Shared Docker services |
34| `ansible/roles/app_deploy/` | Deployment role        |
35| `.github/workflows/`        | CI/CD pipelines        |
36 
37---
38 
39## Agent Workflow
40 
41### Before Making Changes
42 
431. **Read the architecture** — Check ARCHITECTURE.md first
442. **Check existing patterns** — Look at similar files in other apps
453. **Identify the scope** — Which app? Which files?
46 
47### Common Tasks
48 
49#### Run an app locally
50 
51```bash
52bun run dev:fuel-advisor-bot
53bun run dev:tablo-crawler
54```
55 
56#### Build an app
57 
58```bash
59bun run build:fuel-advisor-bot
60bun run build:tablo-crawler
61```
62 
63#### Deploy an app
64 
65```bash
66ansible-playbook -i ansible/inventories/production/hosts.ini \
67  ansible/playbooks/deploy-app.yml \
68  -e &quot;app_path=apps/fuel-advisor-bot&quot;
69```
70 
71#### Add a new app
72 
731. Create `apps/new-app/` with required files
742. Add scripts to root `package.json`
753. Create CI workflow in `.github/workflows/`
764. Add entry to README.md
77 
78---
79 
80## Important Conventions
81 
82### File Naming
83 
84- Files: `lowercase-with-dashes.ts`
85- Classes: `PascalCase`
86- Functions: `camelCase`
87 
88### Docker Strategy
89 
90- Default: `Dockerfile` (safe strategy)
91- Set via `deploy.vars.yml`: `dockerfile_strategy: safe`
92 
93### Watchtower
94 
95- Runs globally in `infra/compose/watchtower.yml`
96- Apps opt-in with label: `com.centurylinklabs.watchtower.enable: "true"`
97 
98### Environment Variables
99 
100- Templates in `.env.example` (committed)
101- Actual values in `.env` (gitignored)
102- Production on server only
103 
104---
105 
106## What NOT To Do
107 
108- Don't create separate Watchtower instances per app
109- Don't hardcode deployment values — use `deploy.vars.yml`
110- Don't duplicate configs — reference shared ones in `infra/`
111- Don't commit secrets to `.env` files
112 
113---
114 
115## Available Documentation
116 
117| File                                  | Description      |
118| ------------------------------------- | ---------------- |
119| [README.md](../README.md)             | Project overview |
120| [CONTRIBUTING.md](../CONTRIBUTING.md) | Dev guidelines   |
121| [ARCHITECTURE.md](../ARCHITECTURE.md) | Design decisions |
122| [CLAUDE.md](../CLAUDE.md)             | AI context       |
123 
124---
125 
126_For agents: Always prefer explicit conventions over implicit knowledge._
127