# Yonexus — Project Plan

## 1) Goal
Build an OpenClaw plugin that models organization hierarchy and agent identities, supports supervisor relationships, provides query tools for agents, and uses shared memory per scope (org/department/team).

## 2) Core Concepts
- **Hierarchy**: Organization → Department → Team → Agent
- **Supervisor**: each agent may have exactly one supervisor
- **Identity**: an agent can hold multiple identities across teams/departments
- **Schema-driven metadata**: configurable fields with per-field queryability
- **Scope memory**: shared memory for org/department/team (using `memory_store`, compatible with memory-lancedb-pro)

## 3) Storage Strategy
- **Structure & identity data**: in-memory + JSON persistence (no memory_store)
- **Shared memory**: memory_store keyed by scope (`org:{id}`, `dept:{id}`, `team:{id}`)

## 4) Permissions Model (B)
Roles:
- Org Admin
- Dept Admin
- Team Lead
- Agent

Rules:
- Supervisor is **not** a role (no inherent permissions)
- Registration **not** self-service
  - only configured agent list or human via slash command

Permission matrix (recommended):
- create_department → Org Admin
- create_team → Org Admin, Dept Admin (same dept)
- assign_identity → Org Admin, Dept Admin (same dept), Team Lead (same team)
- register_agent → Org Admin, Dept Admin, Team Lead (scope-limited)
- set_supervisor → Org Admin, Dept Admin (same dept)
- query → all roles, but only schema fields with `queryable: true`

## 5) Schema Configuration (example)
```json
{
  "position": { "type": "string", "queryable": true },
  "discord_user_id": { "type": "string", "queryable": true },
  "git_user_name": { "type": "string", "queryable": true },
  "department": { "type": "string", "queryable": false },
  "team": { "type": "string", "queryable": false }
}
```

## 6) Tool/API Surface (MVP)
- `create_department(name, orgId)`
- `create_team(name, deptId)`
- `register_agent(agentId, name)`
- `assign_identity(agentId, deptId, teamId, meta)`
- `set_supervisor(agentId, supervisorId)`
- `whoami(agentId)` → identities + supervisor + roles
- `query_agents(filters, options)` → list; supports `eq | contains | regex`

Query example:
```json
{
  "filters": [
    {"field":"discord_user_id","op":"eq","value":"123"},
    {"field":"git_user_name","op":"regex","value":"^hang"}
  ],
  "options": {"limit": 20, "offset": 0}
}
```

## 7) Data Model (MVP)
- Organization { id, name }
- Department { id, name, orgId }
- Team { id, name, deptId }
- Agent { id, name, roles[] }
- Identity { id, agentId, deptId, teamId, meta }
- Supervisor { agentId, supervisorId }

## 8) Milestones
**Phase 0 (Design)**
- finalize schema
- confirm permission rules

**Phase 1 (MVP)**
- storage + JSON persistence
- core models + tools
- query DSL
- scope memory adapter

**Phase 2 (v1)**
- policy refinements
- better query pagination & filtering
- management commands & validation

## 9) Notes & Decisions
- Structure data is not stored in memory_store.
- Shared memory uses memory_store (compatible with memory-lancedb-pro).
- Queryable fields are whitelisted via schema.