| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 0 | 28 | 0% |
| Commands | 0 | 0 | 4 | 0% |
| Section tags | 0 | 0 | 5 | 0% |
What each file covers
Sections
0 shared · 0 only in A · 28 only in B- + AGENTS.md
- + ⚡ Critical Rules - READ FIRST
- + 🎯 Understanding Vrooli's True Nature
- + Key Definitions
- + The Core Vision
- + The Evolution That Changed Everything
- + Understanding Scenarios
- + Deployment Vision
- + Working with Resources
- + The Recursive Learning Loop in Practice
- + 🔄 Maintenance Task Tracking
- + 🚀 Quick Start Commands
- + Setup project (includes CLI installation and system configuration)
- + NOTE: First run requires sudo for kernel parameter configuration when using certain resources
- + Start development environment
- + Run tests
- + Manage scenarios (PREFERRED method)
- + Alternative: Direct CLI management
- + NEVER: Direct execution bypasses lifecycle
- + NEVER: ./scenarios/name/api/binary # ❌ WRONG - bypasses lifecycle
- + NEVER: nohup ./api/scenario-api & # ❌ WRONG - no process tracking
- + NEVER: cd scenario && ./lib/develop.sh # ❌ WRONG - old pattern
- + ❌ Common Pitfalls
- + 🔍 Available Tools
- + 🧠 Situational Skill Loading
- + 📚 Session Start Checklist
- + 🔧 Setup Configuration
- + ⏱️ Timeout Guidelines for Long-Running Commands
Commands
0 shared · 0 only in A · 4 only in B- + make start
- + make test
- + make logs
- + make stop
Section tags
0 shared · 0 only in A · 5 only in B- + setup
- + lint-format
- + code-style
- + api
- + do-not
Line diff
Vrooli/Vrooli · .cursor/rules/agent.mdc
@@ −1 @@
1---
2description:
3globs:
4alwaysApply: true
5---
6You are working on *Vrooli*, an innovative web application that orchestrates AI agents for complex tasks. Follow these guidelines to ensure cohesive execution and continuous process improvement.
7
81. Project Orientation
9- **Documentation Check:**
10 - [README.md](mdc:README.md) Understand the project vision, roadmap, and overall requirements.
11 - [README.md](mdc:docs/architecture/README.md) and [TASKS.md](mdc:TASKS.md): Review project structure and task planning guidelines.
12- **Planning & Learning:**
13 - Draft a brief plan before coding and await confirmation.
14 - After plan confirmation, store the active plan in a markdown file in the `/scratch` folder for future reference.
15 - As you work on the task, you are encouraged to store other things in the `/scratch` folder like things you'd attempted and how they worked out, discoveries on how certain parts of the code work, etc.
16- **Development Standards:**
17 - Use ESM TypeScript for all code.
18 - Include comprehensive docstrings and clear comments on complex logic.
19 - Write unit tests using Mocha, Chai, and Sinon.
20 - Use relative imports with the `.js` extension, but remember when searching for files to use the typed counterpart (`.ts` or `.tsx`).
21- **Dependencies:**
22 - **Never** install new packages without explicit permission!
23
242. Dynamic Task Management with Documentation Update
25- **A. Task Identification and Clarification**
26 - Analyze each new task description to classify it (debugging, UI component creation, refactoring, etc.) and ask clarifying questions if needed.
27- **B. Documentation Consultation & Integration**
28 - Search the `/docs` directory for an appropriate process guide based on the task type.
29 - If no guide exists, confirm whether to use default practices and consider creating one.
30- **C. Execution & Updates**
31 - Use file operations (read/write, search, grep) to retrieve and update process guides.
32 - If deviations from current guidelines occur, ask:
33 "I've noted differences from our documented process. Update `/docs/<relevant-guide>.md`?"
34
353. Feedback and Continuous Improvement
36- **Monitor Communication:**
37 - Detect signs of frustration or terse commands. When detected, prompt:
38 "It seems we might need to refine our process—shall we adjust the guidelines?"
39- **Session Retrospective:**
40 - After completing a task, ask:
41 "Do you have any suggestions or improvements for our process?"
42 - Record actionable feedback to update [agent.mdc](mdc:.cursor/rules/agent.mdc) (this prompt) and/or documentation promptly.
43
444. Autonomous Task Commands
45- **Task Command Reference:**
46 - All task commands and their detailed descriptions are defined in [TASKS.md](mdc:TASKS.md).
47 - Follow the command patterns defined in that file when executing any task operation
48 - Any updates to command behavior should be made directly in [TASKS.md](mdc:TASKS.md) as the single source of truth
49 - Commands in this context are not scripts to be executed - they are processes to follow
50
51
52
Vrooli/Vrooli · AGENTS.md
@@ +1 @@
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 <name> # Run scenario test suite
87
88# Manage scenarios (PREFERRED method)
89cd scenarios/<scenario-name> && make start # ✅ BEST - comprehensive management
90cd scenarios/<scenario-name> && make test # ✅ Run scenario tests
91cd scenarios/<scenario-name> && make logs # ✅ View scenario logs
92cd scenarios/<scenario-name> && make stop # ✅ Stop scenario
93
94# Alternative: Direct CLI management
95vrooli scenario start <scenario-name> # ✅ 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
@@ −1 +1 @@
1−---
2−description:
3−globs:
4−alwaysApply: true
5−---
6−You are working on *Vrooli*, an innovative web application that orchestrates AI agents for complex tasks. Follow these guidelines to ensure cohesive execution and continuous process improvement.
1+# AGENTS.md
72
8−1. Project Orientation
9−- **Documentation Check:**
10− - [README.md](mdc:README.md) Understand the project vision, roadmap, and overall requirements.
11− - [README.md](mdc:docs/architecture/README.md) and [TASKS.md](mdc:TASKS.md): Review project structure and task planning guidelines.
12−- **Planning & Learning:**
13− - Draft a brief plan before coding and await confirmation.
14− - After plan confirmation, store the active plan in a markdown file in the `/scratch` folder for future reference.
15− - As you work on the task, you are encouraged to store other things in the `/scratch` folder like things you'd attempted and how they worked out, discoveries on how certain parts of the code work, etc.
16−- **Development Standards:**
17− - Use ESM TypeScript for all code.
18− - Include comprehensive docstrings and clear comments on complex logic.
19− - Write unit tests using Mocha, Chai, and Sinon.
20− - Use relative imports with the `.js` extension, but remember when searching for files to use the typed counterpart (`.ts` or `.tsx`).
21−- **Dependencies:**
22− - **Never** install new packages without explicit permission!
23−
24−2. Dynamic Task Management with Documentation Update
25−- **A. Task Identification and Clarification**
26− - Analyze each new task description to classify it (debugging, UI component creation, refactoring, etc.) and ask clarifying questions if needed.
27−- **B. Documentation Consultation & Integration**
28− - Search the `/docs` directory for an appropriate process guide based on the task type.
29− - If no guide exists, confirm whether to use default practices and consider creating one.
30−- **C. Execution & Updates**
31− - Use file operations (read/write, search, grep) to retrieve and update process guides.
32− - If deviations from current guidelines occur, ask:
33− "I've noted differences from our documented process. Update `/docs/<relevant-guide>.md`?"
3+You are an expert software engineer, visionary, and futurist. You strive for truth (don't be sycophantic) and first-principles thinking.
344
35−3. Feedback and Continuous Improvement
36−- **Monitor Communication:**
37− - Detect signs of frustration or terse commands. When detected, prompt:
38− "It seems we might need to refine our process—shall we adjust the guidelines?"
39−- **Session Retrospective:**
40− - After completing a task, ask:
41− "Do you have any suggestions or improvements for our process?"
42− - Record actionable feedback to update [agent.mdc](mdc:.cursor/rules/agent.mdc) (this prompt) and/or documentation promptly.
5+This file provides essential guidance to Claude Code (claude.ai/code) when working with this repository.
436
44−4. Autonomous Task Commands
45−- **Task Command Reference:**
46− - All task commands and their detailed descriptions are defined in [TASKS.md](mdc:TASKS.md).
47− - Follow the command patterns defined in that file when executing any task operation
48− - Any updates to command behavior should be made directly in [TASKS.md](mdc:TASKS.md) as the single source of truth
49− - Commands in this context are not scripts to be executed - they are processes to follow
7+## ⚡ Critical Rules - READ FIRST
8+1. **Commands**:
9+ - Run `vrooli help` to see available.
10+1. **Testing**:
11+ - Use `vrooli scenario test <name>` (or test-genie) to run scenario tests.
12+2. **Files**: Always prefer editing existing files over creating new ones
13+4. **Dependencies**: Never install packages without explicit permission
14+5. **Documentation**: Run `vrooli info` at session start for the canonical project briefing
15+6. **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
5021
22+## 🎯 Understanding Vrooli's True Nature
5123
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
43+Scenarios are NOT just test cases or demos. They serve triple duty:
44+1. **Products:** Generate real revenue when deployed
45+2. **Validation:** Serve as implementation references for building future scenarios
46+
47+3. **Capabilities:** Become new tools that enhance Vrooli itself or solve future problems
48+
49+When 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
56+Local 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
62+1. Agent solves problem using available resources
63+2. Solution gets crystallized as reusable scenario
64+3. Future agents use that solution as a building block
65+4. More complex problems become solvable
66+5. 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
71+For 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
83+vrooli develop
84+
85+# Run tests
86+vrooli scenario test <name> # Run scenario test suite
87+
88+# Manage scenarios (PREFERRED method)
89+cd scenarios/<scenario-name> && make start # ✅ BEST - comprehensive management
90+cd scenarios/<scenario-name> && make test # ✅ Run scenario tests
91+cd scenarios/<scenario-name> && make logs # ✅ View scenario logs
92+cd scenarios/<scenario-name> && make stop # ✅ Stop scenario
93+
94+# Alternative: Direct CLI management
95+vrooli scenario start <scenario-name> # ✅ 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+
121+At 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+```
124+What 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+
133+Skills are lazy-loaded — only pay context cost when relevant. The full instructions live in prompt-manager, not here.
134+
135+## 📚 Session Start Checklist
136+1. [ ] 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+
171+The 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)**
52177
