chore: add AGENTS.md with project docs, versioning, and auto-push workflow
This commit is contained in:
root
parent
573765d51e
commit
687ac6aef6
1 changed files with 194 additions and 0 deletions
194
AGENTS.md
Normal file
194
AGENTS.md
Normal file
|
|
@ -0,0 +1,194 @@
|
||||||
|
# Service Factory — ERPNext Custom App Project
|
||||||
|
|
||||||
|
> **Current Version: V0.1.0001** — Each completed prompt/step increments the patch number by 1 (V0.1.0000 → V0.1.0001 → V0.1.0002…). The agent automatically commits and pushes after every step.
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
|
||||||
|
**Service Factory** is a custom Frappe/ERPNext application that productizes professional services by treating human teams as structured "Resource Centers" and engagements as "Production Orders." Built for Frappe v16/ERPNext.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### ERPNext Deployment (Production)
|
||||||
|
|
||||||
|
| Attribute | Value |
|
||||||
|
|-----------|-------|
|
||||||
|
| **Location** | `/opt/erpnext/frappe-bench/` |
|
||||||
|
| **System user** | `erpnext` |
|
||||||
|
| **Frappe version** | v16 (via `bench`) |
|
||||||
|
| **Database** | MariaDB |
|
||||||
|
| **Domain** | `erp.lohmar.co.uk` |
|
||||||
|
| **Port** | 8000 (web) |
|
||||||
|
| **Process manager** | systemd (5 services managed via `frappe-bench.target`) |
|
||||||
|
| **Reverse proxy** | Zoraxy (unifies web + SocketIO on port 8080) |
|
||||||
|
|
||||||
|
### Sites
|
||||||
|
|
||||||
|
| Site | URL | Purpose |
|
||||||
|
|------|-----|---------|
|
||||||
|
| `erp.lohmar.co.uk` | http://erp.lohmar.co.uk:8000 | **Production** — ERPNext with all default apps + service_factory |
|
||||||
|
| `test_sf.lohmar.co.uk` | (site created) | **Testing** — isolated site for Service Factory development |
|
||||||
|
|
||||||
|
### Installed Apps (on production site)
|
||||||
|
|
||||||
|
```
|
||||||
|
frappe, erpnext, service_factory
|
||||||
|
```
|
||||||
|
|
||||||
|
Default ERPNext apps active: Framework, Organization, Accounting, Assets, Buying, Manufacturing, Projects, Quality, Selling, Stock, Subcontracting, ERPNext Settings.
|
||||||
|
|
||||||
|
### Bench Services (systemd)
|
||||||
|
|
||||||
|
| Service | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| `frappe-bench-web.service` | Gunicorn web server (port 8000) |
|
||||||
|
| `frappe-bench-worker.service` | Background async worker |
|
||||||
|
| `frappe-bench-schedule.service` | Scheduled job runner |
|
||||||
|
| `frappe-bench-socketio.service` | Realtime WebSocket (port 9000) |
|
||||||
|
| `frappe-bench-watch.service` | File watcher for dev/assets |
|
||||||
|
|
||||||
|
All services managed via `frappe-bench.target` (start/stop/status as a unit).
|
||||||
|
|
||||||
|
### Credentials
|
||||||
|
|
||||||
|
```
|
||||||
|
Location: /root/erpnext-admin-credentials.txt
|
||||||
|
Site: http://erp.lohmar.co.uk:8000
|
||||||
|
Username: Administrator
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Repository Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
~/development/
|
||||||
|
├── erp-next/ # Git repository (Forgejo: cclohmar/erp-next.git)
|
||||||
|
│ ├── service_factory/ # Frappe app source (DEV COPY — may be behind bench)
|
||||||
|
│ ├── pyproject.toml
|
||||||
|
│ ├── README.md
|
||||||
|
│ └── .pre-commit-config.yaml
|
||||||
|
└── sow.md # Statement of Work — the authoritative blueprint
|
||||||
|
```
|
||||||
|
|
||||||
|
The **actual live app** lives at:
|
||||||
|
```
|
||||||
|
/opt/erpnext/frappe-bench/apps/service_factory/
|
||||||
|
```
|
||||||
|
|
||||||
|
**IMPORTANT**: The bench app and the dev repo are two separate git clones. The bench app contains the latest development work (all milestones complete). The dev repo at `~/development/erp-next/` may be behind and needs syncing after changes are made in the bench.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Milestone Status (ALL COMPLETE in bench)
|
||||||
|
|
||||||
|
| # | Milestone | Status |
|
||||||
|
|---|-----------|--------|
|
||||||
|
| **M1** | Custom App Scaffold & DB Schema (5 DocTypes) | ✅ Done |
|
||||||
|
| **M2** | Backend Python Controllers (cost rollup, card generation, capacity warnings) | ✅ Done |
|
||||||
|
| **M3+4** | Frontend JS Components + Role-Based Workspaces | ✅ Done |
|
||||||
|
| **M5** | Test Suite (4 integration tests) | ✅ Done |
|
||||||
|
| — | Deployment config with systemd, nginx, Zoraxy proxy | ✅ Done |
|
||||||
|
| — | App icon + fixtures (seed data) | ✅ Done |
|
||||||
|
|
||||||
|
### DocTypes Created (5 + 3 child tables)
|
||||||
|
|
||||||
|
**Master / Submittable: No**
|
||||||
|
- `Resource Center` — Team/unit with cost/billing rates
|
||||||
|
- Child: `Resource Center Member` — Employee allocation
|
||||||
|
- `Engagement Recipe` — Service template (like BOM)
|
||||||
|
- Child: `Engagement Recipe Step` — Ordered steps with dependencies
|
||||||
|
|
||||||
|
**Transaction / Submittable: Yes**
|
||||||
|
- `Engagement Order` — Active project run
|
||||||
|
- Child: `Engagement Order Run Step` — Per-step tracking
|
||||||
|
- `Execution Card` — Atomic work tracking
|
||||||
|
- Child: `Execution Card Log` — Time entries
|
||||||
|
|
||||||
|
### Business Logic (server-side)
|
||||||
|
|
||||||
|
- `EngagementOrder.validate()` — Recipe step auto-population, capacity warnings, cost totals
|
||||||
|
- `EngagementOrder.on_submit()` — Auto-generates Execution Cards for assigned steps
|
||||||
|
- `ExecutionCard.on_update()` — Rollup of actual hours → parent order costs/billing
|
||||||
|
|
||||||
|
### Dashboards (3 role-based workspaces)
|
||||||
|
|
||||||
|
- **Engineer Workspace** — My Execution Cards, Timer, Hours chart, Quick actions
|
||||||
|
- **Manager Workspace** — Schedule Gantt, Capacity Alerts, Active/Stalled KPIs
|
||||||
|
- **Director Workspace** — Margin Ledger, Delivery Efficiency, Resource Burn-Down
|
||||||
|
|
||||||
|
### Tests (bench app)
|
||||||
|
|
||||||
|
```
|
||||||
|
test_engagement_order.py — 4 integration tests:
|
||||||
|
1. Execution Cards generated on Order submit
|
||||||
|
2. Cost/billing rollup from Card hours
|
||||||
|
3. Recipe steps auto-populate from template
|
||||||
|
4. Capacity warning fires on overallocation
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Git Operations
|
||||||
|
|
||||||
|
Git server: `git.lohmar.co.uk` (self-hosted Forgejo)
|
||||||
|
|
||||||
|
Two `.gitenv` files exist:
|
||||||
|
- `/root/.gitenv` — template (placeholder, ignore)
|
||||||
|
- `/root/bin/.gitenv` — **actual credentials**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source /root/bin/.gitenv
|
||||||
|
```
|
||||||
|
|
||||||
|
| Setting | Value |
|
||||||
|
|---------|-------|
|
||||||
|
| Remote | `https://cclohmar:${TOKEN}@git.lohmar.co.uk/cclohmar/erp-next.git` |
|
||||||
|
| Default branch | `main` |
|
||||||
|
| Commit prefix | `chore:` |
|
||||||
|
| Auto-stash | enabled |
|
||||||
|
|
||||||
|
### Two Git Repos — Keep in Sync
|
||||||
|
|
||||||
|
```
|
||||||
|
DEV REPO: ~/development/erp-next/ (1 commit — scaffold only)
|
||||||
|
BENCH APP: /opt/erpnext/frappe-bench/apps/service_factory/ (10 commits — all milestones)
|
||||||
|
```
|
||||||
|
|
||||||
|
The bench app has all the development work. When making changes:
|
||||||
|
1. Develop in the bench's app directory (or sync bench → dev repo first)
|
||||||
|
2. Commit from the bench app OR the dev repo
|
||||||
|
3. Push to Forgejo
|
||||||
|
|
||||||
|
### Auto-Push Workflow
|
||||||
|
|
||||||
|
After **every completed prompt/step**, the agent MUST:
|
||||||
|
1. Stage all changes (`git add -A`)
|
||||||
|
2. Commit with prefix `chore:` and a concise description
|
||||||
|
3. Increment the version in this file's header (V0.1.xxxx → V0.1.xxxx+1)
|
||||||
|
4. Push to `origin/main`
|
||||||
|
5. If the dev repo is behind the bench app, sync first before committing
|
||||||
|
|
||||||
|
This ensures every interaction is checkpointed and version-tracked.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Environment
|
||||||
|
|
||||||
|
| Tool | Location |
|
||||||
|
|------|----------|
|
||||||
|
| OpenAgentsControl | `/root/.opencode/` |
|
||||||
|
| Context files | `/root/.opencode/context/` |
|
||||||
|
| Tmux manager | `/root/bin/workspace` (`tmux-project new\|return\|list\|kill`) |
|
||||||
|
| Linting | ruff (Python), eslint (JS), prettier |
|
||||||
|
| Python | ≥3.14 |
|
||||||
|
| Runtime | Node.js/Bun, `@opencode-ai/plugin` |
|
||||||
|
|
||||||
|
### Agent Rules
|
||||||
|
|
||||||
|
- **OpenAgent** — General purpose, workflow orchestration
|
||||||
|
- **OpenCoder** — Production development
|
||||||
|
- Load context via ContextScout before any code/doc/test work
|
||||||
|
- Approval gates required before file writes and bash execution
|
||||||
|
- STOP on test failure — never auto-fix
|
||||||
Loading…
Reference in a new issue