mirror of
https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git
synced 2026-06-18 15:29:36 +00:00
a319feb6d7
Governance layer (14 docs): - MASTER_OPERATING_PROMPT.md — operating constitution (five planes, six tracks, policy classes) - docs/ai-operating-model.md — five-plane architecture (Decision/Execution/Trust/Data/Operating) - docs/dealix-six-tracks.md — six strategic tracks (Revenue/Intelligence/Compliance/Expansion/Operations/Trust) - docs/governance/execution-fabric.md — OpenClaw execution plane deep dive - docs/governance/trust-fabric.md — trust plane with contradiction engine + evidence packs - docs/governance/saudi-compliance-and-ai-governance.md — PDPL/ZATCA/SDAIA/NCA live controls - docs/governance/technology-radar-tier1.md — Core/Strong/Pilot/Watch/Hold classification - docs/governance/partnership-os.md — alliance lifecycle management - docs/governance/ma-os.md — M&A corporate development lifecycle - docs/governance/expansion-os.md — geographic and vertical growth - docs/governance/pmi-os.md — post-merger integration framework - docs/governance/executive-board-os.md — executive decision surfaces - docs/execution-matrix-90d-tier1.md — 90-day sprint execution plan - docs/adr/0001-tier1-execution-policy-spikes.md — 8 architectural decisions Backend (3 models, 6 services, 8 API routes): - Contradiction Engine — detect/track system conflicts - Evidence Pack System — tamper-evident audit proof with SHA256 - Saudi Compliance Matrix — live PDPL/ZATCA/SDAIA/NCA controls - Executive Room — unified executive decision surface - Connector Governance — integration health monitoring - Model Routing Dashboard — LLM provider metrics - Forecast Control Center — actual vs forecast across tracks - Approval Center — enhanced approval queue with SLA Frontend (9 components): - Executive Room, Evidence Pack Viewer, Approval Center - Connector Governance Board, Saudi Compliance Dashboard - Actual vs Forecast Dashboard, Risk Heatmap - Policy Violations Board, Partner Pipeline Board Tooling: - scripts/architecture_brief.py — preflight validation (40/40 checks pass) - Updated CLAUDE.md and AGENTS.md with governance references https://claude.ai/code/session_01W1rJthWDkasijTdXCfxVHs
147 lines
4.8 KiB
Markdown
147 lines
4.8 KiB
Markdown
# AGENTS.md — Dealix AI Revenue OS
|
|
|
|
## Project Identity
|
|
- **Name**: Dealix (ديلكس)
|
|
- **Type**: AI-Powered CRM SaaS for Saudi Arabia
|
|
- **Stack**: FastAPI + Next.js 15 + PostgreSQL + Redis + Celery
|
|
- **Market**: Saudi SMBs (real estate, healthcare, retail, contracting, education)
|
|
- **Language**: Arabic-first, bilingual (AR/EN)
|
|
|
|
## Architecture Boundaries
|
|
|
|
### Backend (`salesflow-saas/backend/`)
|
|
- FastAPI 0.115.6 on Python 3.12
|
|
- SQLAlchemy 2.0 async with PostgreSQL 16
|
|
- Celery 5.x with Redis broker
|
|
- JWT authentication (PyJWT)
|
|
- Multi-tenant data isolation via `tenant_id`
|
|
|
|
### Frontend (`salesflow-saas/frontend/`)
|
|
- Next.js 15 with App Router
|
|
- TypeScript 5.7, Tailwind CSS 3.4
|
|
- RTL-first layout (dir="rtl")
|
|
- Fonts: IBM Plex Sans Arabic (primary), Tajawal (secondary)
|
|
|
|
### AI Layer (`backend/app/services/ai/`)
|
|
- LLM Provider: Groq (primary) → OpenAI (fallback)
|
|
- Arabic NLP with Saudi dialect support
|
|
- Model routing via `services/model_router.py`
|
|
|
|
### Agent System (`backend/app/services/agents/`)
|
|
- Manus-style orchestrator with 8 specialized roles
|
|
- Event-to-agent routing via `router.py`
|
|
- Executor with retry logic and escalation
|
|
|
|
## Coding Conventions
|
|
- Python: async/await, type hints, Pydantic models, 4-space indent
|
|
- TypeScript: strict mode, functional components, Tailwind classes
|
|
- Database: all queries through SQLAlchemy ORM, never raw SQL
|
|
- API: RESTful, versioned (/api/v1/), proper HTTP status codes
|
|
- Naming: snake_case (Python), camelCase (TypeScript)
|
|
- Arabic: all user-facing strings must have Arabic versions
|
|
- Currency: SAR default, Numeric type for money fields
|
|
- Timezone: Asia/Riyadh (UTC+3)
|
|
|
|
## Forbidden Actions
|
|
- Never hardcode API keys or secrets
|
|
- Never bypass tenant isolation
|
|
- Never send messages without PDPL consent check
|
|
- Never delete data without soft-delete first
|
|
- Never push directly to main branch
|
|
- Never skip security review for auth/payment changes
|
|
- Never use synchronous DB calls in async endpoints
|
|
- Never store PII in logs
|
|
|
|
## Policy Classes
|
|
|
|
### Class A — Auto-allowed
|
|
- Code reading and inspection
|
|
- Test generation and execution
|
|
- Documentation updates
|
|
- Memory/knowledge base updates
|
|
- Linting and formatting
|
|
- Architecture analysis
|
|
|
|
### Class B — Approval Required
|
|
- Database migrations
|
|
- Customer-facing message sends
|
|
- Payment/billing changes
|
|
- Permission model changes
|
|
- External API integrations
|
|
- Production deployments
|
|
- PDPL consent configuration changes
|
|
|
|
### Class C — Forbidden
|
|
- Secret exfiltration
|
|
- Bypassing branch protections
|
|
- Silent destructive changes
|
|
- Disabling security gates
|
|
- Cross-tenant data access
|
|
- Ungoverned bulk messaging
|
|
|
|
## How to Install
|
|
```bash
|
|
cd salesflow-saas
|
|
cp .env.example .env # Configure your environment
|
|
docker-compose up -d
|
|
make migrate
|
|
make seed
|
|
```
|
|
|
|
## How to Test
|
|
```bash
|
|
cd salesflow-saas/backend
|
|
pytest -v
|
|
# Or with coverage
|
|
pytest --cov=app --cov-report=html
|
|
```
|
|
|
|
## How to Run
|
|
```bash
|
|
docker-compose up # All services
|
|
# Or individually:
|
|
cd backend && uvicorn app.main:app --reload --port 8000
|
|
cd frontend && npm run dev
|
|
```
|
|
|
|
## Provider Preferences
|
|
1. **Fast classification**: Groq (llama-3.1-70b)
|
|
2. **Arabic NLP**: Groq with Arabic context prompts
|
|
3. **Sales copy/proposals**: Claude (via model_router)
|
|
4. **Research/analysis**: Gemini (via model_router)
|
|
5. **Coding tasks**: DeepSeek (via model_router)
|
|
6. **Fallback**: OpenAI GPT-4o-mini
|
|
|
|
## Release Process
|
|
1. Feature branch → PR → Code review
|
|
2. Run tests + security scan
|
|
3. Deploy to staging
|
|
4. Smoke test (Arabic + English)
|
|
5. Deploy to production with canary (10%)
|
|
6. Monitor 30 min → full rollout
|
|
7. Rollback plan documented per release
|
|
|
|
## Governance Integration (Tier-1)
|
|
|
|
All agents operate under the governance framework defined in `MASTER_OPERATING_PROMPT.md`:
|
|
|
|
- **Trust Plane**: Every agent action is classified as A/B/C via `openclaw/policy.py`. Class B actions (messaging, payments, CRM sync) require approval tokens.
|
|
- **Evidence Packs**: Agent outputs logged to `ai_conversations` contribute to evidence pack assembly.
|
|
- **Contradiction Detection**: Agent-generated content is subject to contradiction checks against governance docs.
|
|
- **Structured Outputs**: All critical agent outputs use defined schemas (LeadScoreCard, QualificationMemo, ProposalPack, etc.).
|
|
|
|
### New Tier-1 API Surfaces
|
|
- `GET /api/v1/executive-room/snapshot` — Executive Room
|
|
- `GET /api/v1/contradictions/` — Contradiction Engine
|
|
- `GET /api/v1/evidence-packs/` — Evidence Pack Viewer
|
|
- `GET /api/v1/approval-center/` — Approval Center
|
|
- `GET /api/v1/connectors/governance` — Connector Governance
|
|
- `GET /api/v1/model-routing/dashboard` — Model Routing
|
|
- `GET /api/v1/compliance/matrix/` — Saudi Compliance Matrix
|
|
- `GET /api/v1/forecast-control/unified` — Actual vs Forecast
|
|
|
|
### Architecture Preflight
|
|
```bash
|
|
python scripts/architecture_brief.py # Run from salesflow-saas/ root
|
|
```
|