AGENTS.md

1# AGENTS.md
2 
3You are an expert software engineer, visionary, and futurist. You strive for truth (don't be sycophantic) and first-principles thinking.
4 
5This file provides essential guidance to Claude Code (claude.ai/code) when working with this repository.
6 
7## ⚡ Critical Rules - READ FIRST
81. **Commands**: 
9   - Run `vrooli help` to see available.
101. **Testing**: 
11   - Use `vrooli scenario test <name>` (or test-genie) to run scenario tests.
122. **Files**: Always prefer editing existing files over creating new ones
134. **Dependencies**: Never install packages without explicit permission
145. **Documentation**: Run `vrooli info` at session start for the canonical project briefing
156. **Managing Scenarios**:
16   - **ALWAYS use**: Scenario Makefiles for comprehensive management: `make start`, `make test`, `make logs`, `make stop`
17   - **Alternative**: `vrooli scenario start <name>` for direct CLI management
18   - **NEVER use**: Direct execution like `./api/scenario-api` or `cd scenario && ./lib/develop.sh`
19   - The lifecycle system ensures proper process naming, port allocation, and logging
20   - Direct execution bypasses critical infrastructure and causes detection issues
21 
22## 🎯 Understanding Vrooli's True Nature
23 
24### Key Definitions
25- **Resources**: Core local services (AI/ML like claude-code, ollama; storage like postgres, redis, qdrant; development helpers like judge0, browserless, vault) that scenarios can compose.
26- **Scenarios**: Full applications or microservices - with APIs, CLIs, and UIs - that combine resources and other scenarios to deliver reusable business capabilities.
27 
28**CRITICAL CONTEXT:** Vrooli is not just an automation platform - it's a **self-improving intelligence system** where:
29 
30### The Core Vision
31- **Shared Local Resources:** Apps share local resources like Ollama, Redis, Qdrant, and PostgreSQL so they can work together and build off each other.
32- **Scenarios Become Capabilities:** Every app (which is generated from a scenario) built becomes a permanent tool the system can use forever
33- **Recursive Improvement:** Agents build tools → Tools make agents smarter → Smarter agents build better tools → ∞
34- **Compound Intelligence:** The system literally cannot forget how to solve problems, only get better at solving them
35- **Scenario-Based Business Model**: Scenarios target measurable value; deliverables can deploy directly, ship as SaaS, serve enterprise installs, or simply act as internal tools or microservices for other scenarios to leverage. Each scenario we complete should increase Vrooli's capabilities and/or be a new monetizable service
36 
37### The Evolution That Changed Everything
38- **Phase 1 (Past):** Web platform where agents could only interact through APIs (limited but proved the concept)
39- **Phase 2 (Current):** Physical server with local resource access - agents can now build complete applications by building off of existing resources and scenarios
40- **Phase 3 (Future):** Specialized servers for engineering, science, finance. Hardware line where businesses and households can run their own specialized Vrooli server
41 
42### Understanding Scenarios
43Scenarios are NOT just test cases or demos. They serve triple duty:
441. **Products:** Generate real revenue when deployed
452. **Validation:** Serve as implementation references for building future scenarios
46 
473. **Capabilities:** Become new tools that enhance Vrooli itself or solve future problems
48 
49When working with scenarios, remember: **You're building businesses and expanding intelligence.**
50 
51### Deployment Vision
52- Current deployments run via the Tier 1 local stack (full Vrooli installation + app-monitor Cloudflare tunnel).
53- Future tiers (desktop, mobile, SaaS, enterprise) are documented in the [Deployment Hub](docs/deployment/README.md); consult it whenever considering packaging or delivery tasks.
54 
55### Working with Resources
56Local resources (Ollama, PostgreSQL, etc.) aren't just "integrations" - they're the building blocks of emergent capability:
57- Each resource multiplies what agents can accomplish
58- Agents discover novel combinations we haven't imagined
59- Resources enable the shift from "calling APIs" to "building the APIs"
60 
61### The Recursive Learning Loop in Practice
621. Agent solves problem using available resources
632. Solution gets crystallized as reusable scenario
643. Future agents use that solution as a building block
654. More complex problems become solvable
665. Each iteration makes ALL future iterations more powerful
67 
68**Remember:** Every line of code you write, every routine you create, every scenario you build - it all becomes permanent intelligence that the system uses to improve itself forever.
69 
70## 🔄 Maintenance Task Tracking
71For recurring tasks (test quality, React performance, etc.), use the AI maintenance tracking system:
72- **Before starting:** Check existing work with `rg "AI_CHECK:.*TASK_ID" --type ts`
73- **After completing:** Add/update comment: `// AI_CHECK: TASK_ID=count | LAST: YYYY-MM-DD`
74- **Full system:** See [AI Maintenance Tracking](/docs/ai-maintenance/README.md)
75 
76## 🚀 Quick Start Commands
77```bash
78# Setup project (includes CLI installation and system configuration)
79# NOTE: First run requires sudo for kernel parameter configuration when using certain resources
80./scripts/manage.sh setup --yes yes
81 
82# Start development environment
83vrooli develop
84 
85# Run tests
86vrooli scenario test &lt;name&gt;  # Run scenario test suite
87 
88# Manage scenarios (PREFERRED method)
89cd scenarios/&lt;scenario-name&gt; && make start   # ✅ BEST - comprehensive management
90cd scenarios/&lt;scenario-name&gt; && make test    # ✅ Run scenario tests
91cd scenarios/&lt;scenario-name&gt; && make logs    # ✅ View scenario logs
92cd scenarios/&lt;scenario-name&gt; && make stop    # ✅ Stop scenario
93 
94# Alternative: Direct CLI management
95vrooli scenario start &lt;scenario-name&gt;        # ✅ ALTERNATIVE - CLI management
96 
97# NEVER: Direct execution bypasses lifecycle
98# NEVER: ./scenarios/name/api/binary         # ❌ WRONG - bypasses lifecycle
99# NEVER: nohup ./api/scenario-api &          # ❌ WRONG - no process tracking
100# NEVER: cd scenario && ./lib/develop.sh     # ❌ WRONG - old pattern
101```
102 
103> **Note**: When writing tests, make sure you're writing them to test against the DESIRED/EXPECTED behavior, not the actual implementation. This is important for the test to be useful and not just a checkmark.
104 
105## ❌ Common Pitfalls
106- DON'T skip reading memory files at session start
107- DON'T use mass-update scripts or automated tools to modify multiple files - check and update each file individually
108- DON'T use `2>&1` shell redirection syntax - Claude Code CLI parses this as separate arguments, breaking scripts. Use `&>` instead for redirecting both stdout and stderr to a file
109- DON'T start scenarios with direct execution (`./api/scenario-api`, `nohup ./api/binary &`, etc.)
110- DON'T bypass the lifecycle system - it manages process naming, ports, and health checks
111- DON'T create `lib/` folders in scenarios - use v2.0 service.json lifecycle configuration instead
112 
113## 🔍 Available Tools
114- **ast-grep (sg)**: For syntax-aware code search - default to `ast-grep --lang <language> --pattern '<pattern>'` over `grep` for structural matching
115- **jq/yq**: For JSON/YAML processing
116- **gofumpt**: Stricter Go formatting (superset of gofmt) - use `gofumpt -w .` to format Go code
117- **golangci-lint**: Comprehensive Go linting - use `golangci-lint run` to check Go code quality and catch issues
118 
119## 🧠 Situational Skill Loading
120 
121At conversation start, assess the user's intent and proactively load the relevant skill. Do not wait for the user to request it — recognize the pattern and act.
122 
123```
124What is the user doing?
125├─ Brainstorming/workshopping a new idea  → prompt-manager skill read idea-workshop
126├─ Debugging a non-obvious issue          → prompt-manager skill read scientific-debugging
127├─ Creating an implementation plan        → prompt-manager skill read plan-skill-discovery
128├─ Deploying/publishing a scenario        → prompt-manager skill read deployment-coordinator
129├─ (add new entries as patterns emerge)
130└─ None of the above                      → proceed normally, no skill needed
131```
132 
133Skills are lazy-loaded — only pay context cost when relevant. The full instructions live in prompt-manager, not here.
134 
135## 📚 Session Start Checklist
1361. [ ] Run `vrooli info` for the consolidated project overview
137 
138## 🔧 Setup Configuration
139 
140**Environment Profiles** (`--environment`):
141- `development` (default): Full setup with all dev tools (bats, shellcheck, ast-grep, Go dev tools, Helm, etc.)
142- `production`: Production runtimes only, skips dev tools - ideal for VPS deployments
143- `minimal`: Only Docker + essential system deps - fastest possible setup
144 
145**Resource Installation** (`--resources`):
146- `enabled` (default): Install resources marked as enabled in `.vrooli/service.json`
147- `none`: Skip all resource installation
148- `<list>`: Install only specified resources (comma-separated, e.g., `postgres,redis`)
149 
150**Examples**:
151```bash
152./scripts/manage.sh setup --yes yes                           # Full dev setup
153./scripts/manage.sh setup --environment production            # Production (no dev tools)
154./scripts/manage.sh setup --environment minimal --resources none  # Fastest possible
155./scripts/manage.sh setup --resources postgres,redis          # Only specific resources
156```
157 
158**Resource Management**:
159- Enable/disable resources by editing `.vrooli/service.json`
160- Resources marked as enabled will be installed on next setup run
161 
162## ⏱️ Timeout Guidelines for Long-Running Commands
163**Remember to set appropriate timeouts when running:**
164- Test suites: Can take 15+ minutes in worst case scenarios (better to be safe than sorry)
165- Type checking full packages: Can take 15+ minutes
166- Building/compiling: Can take 10+ minutes (UI build alone takes 5-10 minutes due to 4444+ modules)
167- Database migrations: Can take 3+ minutes
168- Docker builds: Can take 20+ minutes
169- UI build performance issue: vite build processes 4400+ modules, causing 5-10 minute build times
170 
171The default timeout is 2 minutes, which is often insufficient for these operations.
172 
173 
174---
175 
176**For detailed documentation, development guidelines, and comprehensive examples, see [/docs/README.md](/docs/README.md)**
177