GeneralBots/botui
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update PROMPT.md with HTMX-first and new LLM workflow rules

Browse source 
New rules added:
- Two LLM work modes: Execution (fazer) vs Review (conferir)
- HTMX-first frontend: minimize JS at maximum
- Local assets only: no CDN references
- Server returns HTML fragments, not JSON
- No dead code: implement real code, never use _ prefix
- cargo audit must pass with 0 warnings
- Documentation rules: Rust code only in architecture docs
- Added HTMX patterns and examples
This commit is contained in:
Rodrigo Rodriguez (Pragmatismo) 2025-12-04 13:55:31 -03:00
parent bd5b2c9481
commit f1f4835d92
1 changed files with 191 additions and 102 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

293
PROMPT.md
View file

@ -19,27 +19,100 @@ botapp/ # Desktop wrapper (consumes botui)
botbook/ # Documentation botbook/ # Documentation
``` ```
### What BotUI Provides ---
- **Web Mode**: Axum server serving HTML/CSS/JS UI on port 3000 ## LLM Workflow Strategy
- **Desktop Mode**: Tauri native application with same UI
- **HTTP Bridge**: Proxies all requests to botserver ### Two Types of LLM Work
- **Local Assets**: All JS/CSS bundled locally (no CDN)
1. **Execution Mode (Fazer)**
- Pre-annotate phrases and send for execution
- Focus on automation freedom
- Less concerned with code details
- Primary concern: Is the LLM destroying something?
- Trust but verify output doesn't break existing functionality
2. **Review Mode (Conferir)**
- Read generated code with full attention
- Line-by-line verification
- Check for correctness, security, performance
- Validate against requirements
### LLM Fallback Strategy (After 3 attempts / 10 minutes)
1. DeepSeek-V3-0324 (good architect, reliable)
2. gpt-5-chat (slower but thorough)
3. gpt-oss-120b (final validation)
4. Claude Web (for complex debugging, unit tests, UI)
--- ---
## Quick Start ## Code Generation Rules
```bash ### CRITICAL REQUIREMENTS
# Terminal 1: Start BotServer
cd ../botserver && cargo run
# Terminal 2: Start BotUI (Web Mode) ```
cd ../botui && cargo run - BotUI = Presentation + HTTP bridge ONLY
# Visit http://localhost:3000 - All business logic goes in botserver
- No code duplication between layers
- Feature gates eliminate unused code paths
- Zero warnings - feature gating prevents dead code
- NO DEAD CODE - implement real functionality, never use _ for unused
- All JS/CSS must be local (no CDN)
```
# OR Desktop Mode ### HTMX-First Frontend
cargo tauri dev
```
- Use HTMX to minimize JavaScript at maximum
- Delegate ALL logic to Rust server
- Server returns HTML fragments, not JSON
- Use hx-get, hx-post, hx-target, hx-swap attributes
- WebSocket via htmx-ws extension for real-time
- NO custom JavaScript where HTMX can handle it
```
### Local Assets Only
All external libraries are bundled locally - NEVER use CDN:
```
ui/suite/js/vendor/
├── htmx.min.js # HTMX core
├── htmx-ws.js # WebSocket extension
├── htmx-json-enc.js # JSON encoding
├── marked.min.js # Markdown parser
├── gsap.min.js # Animation (minimal use)
├── alpinejs.min.js # Alpine.js (minimal use)
└── livekit-client.umd.min.js # LiveKit video
ui/minimal/js/vendor/
└── (same structure)
```
```html
<!-- CORRECT -->
<script src="js/vendor/htmx.min.js"></script>
<!-- WRONG - NEVER DO THIS -->
<script src="https://unpkg.com/htmx.org@1.9.10"></script>
```
### Dependency Management
```
- Use diesel for any local database needs
- After adding to Cargo.toml: cargo audit must show 0 warnings
- If audit fails, find alternative library
- Minimize redundancy - check existing libs before adding new ones
```
### Documentation Rules
```
- Rust code examples ONLY allowed in architecture/gbapp documentation
- Scan for ALL_CAPS.md files created at wrong places - delete or integrate
- Keep only README.md and PROMPT.md at project root level
``` ```
--- ---
@ -72,93 +145,80 @@ src/
ui/ ui/
├── suite/ # Main UI (HTML/CSS/JS) ├── suite/ # Main UI (HTML/CSS/JS)
│ ├── js/vendor/ # Local JS libraries (htmx, marked, etc.) │ ├── js/vendor/ # Local JS libraries
│ └── css/ # Stylesheets │ └── css/ # Stylesheets
└── minimal/ # Minimal chat UI └── minimal/ # Minimal chat UI
└── js/vendor/ # Local JS libraries └── js/vendor/ # Local JS libraries
``` ```
--- ### Feature Gating
## Feature Gating
```rust ```rust
#[cfg(feature = "desktop")] // Desktop build only #[cfg(feature = "desktop")]
pub mod desktop; pub mod desktop;
#[cfg(not(feature = "desktop"))] // Web build only #[cfg(not(feature = "desktop"))]
pub mod http_client; pub mod http_client;
``` ```
Build commands:
```bash
cargo build # Web mode (default)
cargo build --features desktop # Desktop mode
cargo tauri build # Optimized desktop build
```
--- ---
## Code Generation Rules ## HTMX Patterns
### CRITICAL REQUIREMENTS ### Server-Side Rendering
```
- BotUI = Presentation + HTTP bridge ONLY
- All business logic goes in botserver
- No code duplication between layers
- Feature gates eliminate unused code paths
- Zero warnings - feature gating prevents dead code
- All JS/CSS must be local (no CDN)
```
### Key Principles
1. **Minimize Code** - Only presentation and HTTP bridging
2. **Feature Gating** - Desktop code doesn't compile in web mode
3. **HTTP Communication** - All botserver calls through BotServerClient
4. **Local Assets** - All vendor JS in ui/*/js/vendor/
---
## Local JS/CSS Vendor Files
All external libraries are bundled locally:
```
ui/suite/js/vendor/
├── htmx.min.js # HTMX 1.9.10
├── htmx-ws.js # HTMX WebSocket extension
├── htmx-json-enc.js # HTMX JSON encoding
├── marked.min.js # Markdown parser
├── gsap.min.js # Animation library
├── alpinejs.min.js # Alpine.js reactivity
└── livekit-client.umd.min.js # LiveKit video
```
**NEVER use CDN URLs** - always reference local vendor files:
```html ```html
<!-- CORRECT --> <!-- Button triggers server request, response swaps into target -->
<script src="js/vendor/htmx.min.js"></script> <button hx-get="/api/items"
hx-target="#items-list"
hx-swap="innerHTML">
Load Items
</button>
<!-- WRONG - DO NOT USE --> <div id="items-list">
<script src="https://unpkg.com/htmx.org@1.9.10"></script> <!-- Server returns HTML fragment here -->
</div>
``` ```
--- ### Form Submission
## HTTP Client ```html
<form hx-post="/api/items"
hx-target="#items-list"
hx-swap="beforeend">
<input name="title" type="text" required>
<button type="submit">Add</button>
</form>
```
### WebSocket Real-time
```html
<div hx-ext="ws" ws-connect="/ws/chat">
<div id="messages"></div>
<form ws-send>
<input name="message" type="text">
<button type="submit">Send</button>
</form>
</div>
```
### Server Response (Rust/Askama)
```rust ```rust
pub struct BotServerClient { #[derive(Template)]
client: Arc<Client>, #[template(path = "partials/item.html")]
base_url: String, struct ItemTemplate {
item: Item,
} }
impl BotServerClient { async fn create_item(
pub async fn get<T: Deserialize>(&self, endpoint: &str) -> Result<T, String> State(state): State<Arc<AppState>>,
pub async fn post<T, R>(&self, endpoint: &str, body: &T) -> Result<R, String> Form(input): Form<CreateItem>,
pub async fn health_check(&self) -> bool ) -> Html<String> {
let item = save_item(&state, input).await;
let template = ItemTemplate { item };
Html(template.render().unwrap())
} }
``` ```
@ -169,9 +229,9 @@ impl BotServerClient {
### Process ### Process
1. Add business logic to **botserver** first 1. Add business logic to **botserver** first
2. Create REST API endpoint in botserver 2. Create REST API endpoint in botserver (returns HTML for HTMX)
3. Add HTTP wrapper in BotUI 3. Add HTTP wrapper in BotUI if needed
4. Add UI in `ui/suite/` 4. Add UI in `ui/suite/` using HTMX attributes
5. For desktop-specific: Add Tauri command in `src/desktop/` 5. For desktop-specific: Add Tauri command in `src/desktop/`
### Desktop Tauri Command ### Desktop Tauri Command
@ -179,17 +239,55 @@ impl BotServerClient {
```rust ```rust
#[tauri::command] #[tauri::command]
pub fn list_files(path: &str) -> Result<Vec<FileItem>, String> { pub fn list_files(path: &str) -> Result<Vec<FileItem>, String> {
// Implementation let entries = std::fs::read_dir(path)
.map_err(|e| e.to_string())?;
let items: Vec<FileItem> = entries
.filter_map(|e| e.ok())
.map(|e| FileItem {
name: e.file_name().to_string_lossy().to_string(),
is_dir: e.path().is_dir(),
})
.collect();
Ok(items)
} }
``` ```
--- ---
## Environment Variables ## Final Steps Before Commit
```bash ```bash
BOTSERVER_URL=http://localhost:8081 # BotServer location # Check for warnings
RUST_LOG=debug # Logging level cargo check 2>&1 | grep warning
# Audit dependencies (must be 0 warnings)
cargo audit
# Build both modes
cargo build
cargo build --features desktop
# Verify no dead code with _ prefixes
grep -r "let _" src/ --include="*.rs"
# Verify no CDN references
grep -r "unpkg.com\|cdnjs\|jsdelivr" ui/
```
---
## Key Files Reference
```
src/main.rs # Entry point, mode detection
src/lib.rs # Feature-gated exports
src/http_client.rs # BotServerClient wrapper
src/ui_server/mod.rs # Axum router, static files
ui/suite/index.html # Main UI entry
ui/suite/base.html # Base template
ui/minimal/index.html # Minimal chat UI
``` ```
--- ---
@ -201,27 +299,18 @@ RUST_LOG=debug # Logging level
| axum | 0.7.5 | Web framework | | axum | 0.7.5 | Web framework |
| reqwest | 0.12 | HTTP client | | reqwest | 0.12 | HTTP client |
| tokio | 1.41 | Async runtime | | tokio | 1.41 | Async runtime |
| askama | 0.12 | Templates | | askama | 0.12 | HTML Templates |
| diesel | 2.1 | Database (sqlite) | | diesel | 2.1 | Database (sqlite) |
--- ---
## Testing ## Remember
```bash - **Two LLM modes**: Execution (fazer) vs Review (conferir)
cargo build # Web mode - **HTMX first**: Minimize JS, delegate to server
cargo build --features desktop # Desktop mode - **Local assets**: No CDN, all vendor files local
cargo test - **Dead code**: Never use _ prefix, implement real code
cargo run # Start web server - **cargo audit**: Must pass with 0 warnings
cargo tauri dev # Start desktop app - **No business logic**: All logic in botserver
``` - **Feature gates**: Unused code never compiles
- **HTML responses**: Server returns fragments, not JSON
---
## Rules
- **No business logic** - only presentation
- **No CDN** - all assets local
- **Feature gate** - unused code never compiles
- **Zero warnings** - clean compilation
- **HTTP bridge** - all data from botserver