Yonexus/PLAN.md

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)

{
  "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:

{
  "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.