Imported from zubbyik/openagile_parent (
AGENTS.md). Install upstream withnpx skills add zubbyik/openagile_parent. Copyright stays with the author.
AGENTS.md — Essential Guidance for OpenCode Sessions
Critical Rules (Never Miss These)
0. First-Contact Context Discovery
- Start at the workspace root
AGENTS.mdfor global OpenAgile rules. - Then identify the target subproject before editing files.
- Target project triggers, in priority order:
- Explicit project name in the user prompt.
- File paths mentioned in the user prompt.
- Active/open IDE file path supplied in context.
- A handover, acceptance test, or context file that names a project.
- If no target project can be identified, ask the user to name the project.
- Project-local context engines live under each subproject's
docs/context/directory when available. - For Estate Portfolio Manager, read:
egbuna_estate_account_streamlight/estate-portfolio/docs/context/MASTER_CONTEXT.mdegbuna_estate_account_streamlight/estate-portfolio/docs/context/WORKFLOW.mdegbuna_estate_account_streamlight/estate-portfolio/docs/context/DELEGATION_REGISTRY.mdegbuna_estate_account_streamlight/estate-portfolio/docs/context/AGENT_STATE.yaml
- Once a target project is resolved, edits are limited to that project path and explicitly authorized root coordination docs. Do not edit another subproject unless the user explicitly expands the scope.
- If project-local context conflicts with this file, this root
AGENTS.mdcontrols global infrastructure rules, while the subproject context controls local file ownership, current handovers, and implementation sequencing. - Documentation structure must follow
docs/DOCUMENTATION_STRUCTURE.mdat the root and the matching structure inside each subprojectdocs/directory.
1. Branch Discipline
- Always work on
testbranch — never commit directly tomain - Create/switch to
testbefore starting work:git checkout testorgit switch -c test - Only approved maintainers merge
test→main
2. Docker Usage (GitHub Actions Only)
- NEVER run Docker commands locally (on Fedora laptop)
- All deployment must go through GitHub Actions:
- Push changes to GitHub → Actions deploys to Netcup VPS
- Local machine: Git ops, code editing, local testing only
3. Frappe Development Conventions (Applies only to frappe_docker* folders)
- Use bench venv Python:
/home/frappe/frappe-bench/env/bin/pip - Install custom apps:
docker compose exec backend /home/frappe/frappe-bench/env/bin/pip install -e apps/<app> - After pip install: Run
bench buildto generate assets - Assets use named volumes (NOT bind mounts) to avoid symlink issues
- Important: These conventions ONLY apply to frappe_docker* directories. Do not use them in other project folders.
4. Testing Requirements
- Single test:
pytest tests/test_frappe_docker.py::test_endpoints -s - Follow BDD/TDD pipeline: Write pytest from Gherkin, see Red, then write production code to pass (Green)
- Trace assertions back to spec:
# Spec: feature_name.feature | SC-001 | Then... - Verification format: ALL solutions must include:
## Verification Steps 1. **Test Command**: [exact command to test] 2. **Expected Output**: [what success looks like] 3. **If It Fails**: [diagnostic steps] 4. **Rollback**: [how to undo if broken]
5. Service-Specific Commands
Root Infrastructure
docker compose up -d # Start stack (via GitHub Actions only)
docker compose ps # Check status
docker compose logs -f [svc] # View logs
frappe_docker (Main Frappe Setup)
./scripts/deploy.sh # Deploy multi-tenant
docker compose exec backend bench new-site [name] --admin-password=admin
edu_theme Frontend (Vue.js + Vite)
cd frappe_docker/apps/edu_theme/frontend
npm run dev # Development server
npm run build # Build for production (outputs to ../edu_theme/public/frontend/)
Estate Portfolio (Streamlit)
cd egbuna_estate_account_streamlight/estate-portfolio
pip install -r requirements.txt
streamlit run app.py # Or: docker compose up -d via GitHub Actions
6. Key Constraints to Remember
- Shared PostgreSQL 15 — never create new container, reuse existing
- All services on
openagile_networkwith Traefik labels for routing - Low-resource server (<4GB RAM per service) — avoid memory-heavy tools
- Documentation must use standard YAML headers in
docs/directory - Pre-commit hooks: Install in
apps/edu_themefor Python/JS formatting - Traefik labels: When adding services, use the standard label convention
- Volume strategy: Use named volumes for Frappe assets (bind mounts cause symlink issues)
