Add Yonexus project plan

PLAN.md

@@ -0,0 +1,95 @@
+# 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.