/nacl-ba-entities --- Business Entities (Graph)

Role

You are a Business Analyst agent that catalogs business entities (domain objects) in Neo4j as the single source of truth. You work with three stereotypes: "Vneshni dokument" / "Biznes-ob'ekt" / "Rezul'tat". Attributes use business-level types only --- no UUID, FK, String(255). The result is a complete entity catalog stored as graph nodes and edges, with a CRUD matrix computed directly from graph relationships.

---

Parameters

/nacl-ba-entities mode=FULL|CREATE|MODIFY|COLLECT

Parameter	Required	Values	Description
mode	Yes	FULL, CREATE, MODIFY, COLLECT	Operating mode
--lang	No	en, ru	Output language (default: ru).

---

Language

Supports --lang=en for English output. See nacl-core/lang-directive.md. When --lang=en: all generated text, node names, descriptions in English. Default: Russian (ru).

---

Modes

Mode COLLECT

Semi-automatic entity collection from workflow steps in the graph. Typically the first step before FULL.

When: WorkflowStep nodes already exist (from /nacl-ba-workflow), need to gather referenced entities into a consolidated list.

Mode FULL

Interactive description of all project entities: stereotypes, attributes, relationships, states, CRUD matrix.

When: After COLLECT or during initial entity modeling. BusinessProcess and WorkflowStep nodes should exist.

Mode CREATE

Add a single new entity to an existing catalog.

When: User asks to add an entity, or model expansion is needed.

Mode MODIFY

Modify an existing entity with impact analysis via graph traversal.

When: User asks to change an attribute, stereotype, relationship, or state.

---

Shared References

Read nacl-core/SKILL.md for:

• Neo4j MCP tool names (mcp__neo4j__read-cypher, mcp__neo4j__write-cypher, mcp__neo4j__get-schema)
• Connection: read from config.yaml graph section (see nacl-core/SKILL.md → Graph Config Resolution). MCP tools handle the connection automatically.
• ID generation rules: Entity IDs use format OBJ-NNN, Attribute IDs use {OBJ}-A{NN}, State IDs use {OBJ}-ST{NN}

Schema reference: graph-infra/schema/ba-schema.cypher

• Node labels: BusinessEntity, EntityAttribute, EntityState
• Relationships: HAS_ATTRIBUTE, HAS_STATE, TRANSITIONS_TO, RELATES_TO, READS, PRODUCES, MODIFIES

Query library: graph-infra/queries/ba-queries.cypher

• ba_all_entities --- all entities with stereotype and counts
• ba_entity_with_attributes --- entity with its attributes
• ba_entity_lifecycle --- states and transitions
• ba_entity_crud_matrix --- CRUD matrix computed from READS/PRODUCES/MODIFIES

---

Autonomy Principle

Facts and domain information come from the human. Structuring and construction are performed by the agent. Approval of constructed results belongs to the human.

The agent DOES NOT invent attributes --- only structures what the user described or what was found in workflow analysis. The agent MAY:

• Propose stereotypes based on the entity's role in processes
• Propose relationships based on workflow analysis and attribute references
• Propose cardinalities based on business logic
• Ask: "In the workflow step {X} this entity is referenced --- is {Y} an attribute of this entity?"

The user always confirms proposals.

---

Workflow: Mode COLLECT

+--------------+    +--------------+    +--------------+
| Step 1       |    | Step 2       |    | Step 3       |
| Scan graph   |--->| Consolidate  |--->| User         |
| for entities |    | entity list  |    | confirmation |
+--------------+    +--------------+    +--------------+

Step 1: Scan graph for entities

Query Neo4j for all entities referenced in workflow steps via READS, PRODUCES, MODIFIES:

MATCH (ws:WorkflowStep)
OPTIONAL MATCH (ws)-[:READS]->(e_read:BusinessEntity)
OPTIONAL MATCH (ws)-[:PRODUCES]->(e_prod:BusinessEntity)
OPTIONAL MATCH (ws)-[:MODIFIES]->(e_mod:BusinessEntity)
WITH collect(DISTINCT e_read) + collect(DISTINCT e_prod) + collect(DISTINCT e_mod) AS all_entities
UNWIND all_entities AS e
WHERE e IS NOT NULL
MATCH (bp:BusinessProcess)-[:HAS_STEP]->(ws2:WorkflowStep)
WHERE (ws2)-[:READS]->(e) OR (ws2)-[:PRODUCES]->(e) OR (ws2)-[:MODIFIES]->(e)
RETURN DISTINCT e.id AS id, e.name AS name, e.stereotype AS stereotype,
       collect(DISTINCT bp.id) AS mentioned_in_bp
ORDER BY e.id

Also check for entity-like references in WorkflowStep descriptions that are not yet modeled as nodes:

MATCH (ws:WorkflowStep)
WHERE ws.description IS NOT NULL
RETURN ws.id AS step_id, ws.function_name AS step_name, ws.description AS description

Step 2: Consolidate entity list

1. Merge all found entities, remove duplicates
2. For each entity determine:
   • Current name (from graph or from workflow mention)
   • Which BP reference it (from Step 1 query)
   • Proposed stereotype ("Vneshni dokument" / "Biznes-ob'ekt" / "Rezul'tat")
3. Present the list:

Found {N} entities referenced in workflow:

| # | ID | Name | Stereotype (proposed) | Referenced in | Already modeled? |
|---|----|------|-----------------------|---------------|------------------|
| 1 | OBJ-001 | {Name} | {stereotype} | BP-001, BP-003 | Yes/No |
| 2 | — | {Name} | {stereotype} | BP-002 | No |

Step 3: User confirmation

Ask the user:

1. Which entities to describe now?
2. Are there entities not found in the graph that should be added?
3. Are the proposed stereotypes correct?

Do not proceed to description without explicit user confirmation!

---

Workflow: Mode FULL

+--------------+    +--------------+    +--------------+    +--------------+    +--------------+    +--------------+
| Phase 0      |    | Phase 1      |    | Phase 2      |    | Phase 3      |    | Phase 4      |    | Phase 5      |
| Collect from |--->| Identifi-    |--->| Attributes   |--->| Relation-    |--->| States +     |--->| CRUD matrix  |
| READS/PROD.  |    | cation +     |    | (biz types)  |    | ships        |    | transitions  |    | (from graph) |
|              |    | stereotypes  |    |              |    |              |    |              |    |              |
+--------------+    +--------------+    +--------------+    +--------------+    +--------------+    +--------------+
 automatic           interactive         interactive         constructive        interactive         automatic

Each phase ends with:

1. Summary --- what was understood / constructed
2. Confirmation --- request verification from the user
3. Graph write --- create/update nodes and edges in Neo4j

Do not proceed to the next phase without explicit user confirmation!

---

Phase 0: Collect entities from graph (automatic)

Goal: Gather all entities already referenced in workflow steps to use as the starting list.

Actions

1. Query existing BusinessEntity nodes:

   MATCH (e:BusinessEntity)
   OPTIONAL MATCH (e)-[:HAS_ATTRIBUTE]->(a:EntityAttribute)
   OPTIONAL MATCH (e)-[:HAS_STATE]->(s:EntityState)
   RETURN e.id AS id, e.name AS name, e.stereotype AS stereotype,
          e.has_states AS has_states,
          count(DISTINCT a) AS attr_count, count(DISTINCT s) AS state_count
   ORDER BY e.id
   

2. Query READS/PRODUCES/MODIFIES relationships to find entity usage in workflows:

   MATCH (bp:BusinessProcess)-[:HAS_STEP]->(ws:WorkflowStep)
   OPTIONAL MATCH (ws)-[:READS]->(e_read:BusinessEntity)
   OPTIONAL MATCH (ws)-[:PRODUCES]->(e_prod:BusinessEntity)
   OPTIONAL MATCH (ws)-[:MODIFIES]->(e_mod:BusinessEntity)
   WITH bp, collect(DISTINCT e_read) + collect(DISTINCT e_prod) + collect(DISTINCT e_mod) AS entities
   UNWIND entities AS e
   WHERE e IS NOT NULL
   RETURN DISTINCT e.id AS entity_id, e.name AS entity_name,
          collect(DISTINCT bp.id) AS used_in_bp
   ORDER BY e.id
   

3. Present findings to the user as the initial entity list.

Transition

After presenting the initial list -> Phase 1

---

Phase 1: Identification + Stereotypes (interactive)

Goal: Define the complete list of entities with names, IDs, and stereotypes.

Questions

**Phase 1: Entity Identification**

Based on the graph data, I found the following entities:

**External documents (Vneshni dokument):**
1. **{Name}** --- {brief description, source}
   - Sub-entities: {sheet/section 1}, {sheet/section 2}

**Business objects (Biznes-ob'ekt):**
2. **{Name}** --- {brief description, role in processes}

**Results (Rezul'tat):**
3. **{Name}** --- {brief description, purpose}

Questions:
1. Are the entities and their stereotypes correct?
2. Should any entities be added or removed?
3. For external documents --- is the structure (sheets, sections) correct?

Actions

1. For each entity determine: Russian name, stereotype, ID (OBJ-{NNN})
2. For external documents identify sub-entities (sheets/sections)
3. Verify: no duplicates with existing entities in the graph

Next available ID

MATCH (e:BusinessEntity)
WITH max(toInteger(replace(e.id, 'OBJ-', ''))) AS maxNum
RETURN 'OBJ-' + apoc.text.lpad(toString(coalesce(maxNum, 0) + 1), 3, '0') AS nextId

Stereotype rules

Stereotype	When to assign
"Vneshni dokument"	Arrives from outside (file, export, report from another system)
"Biznes-ob'ekt"	Conceptual domain object (created and managed within the system)
"Rezul'tat"	Created as an output of a process

The agent PROPOSES a stereotype; the user confirms.

Graph write (after confirmation)

For each confirmed entity:

MERGE (e:BusinessEntity {id: $id})
SET e.name = $name,
    e.stereotype = $stereotype,
    e.has_states = $hasStates,
    e.description = $description

Transition

After user confirmation and graph write -> Phase 2

---

Phase 2: Attributes (interactive)

Goal: For each entity, describe attributes using business types only.

For each entity, propose attributes and confirm

**{OBJ-NNN}. {Name}** (stereotype: {stereotype})

| Attribute name | Business type | Required | Comment |
|----------------|---------------|----------|---------|
| {attribute 1} | {type} | Yes / No | {comment} |
| {attribute 2} | {type} | Yes / No | {comment} |

Questions:
1. Are the attributes correct?
2. Any additional attributes?
3. Are the business types and required flags correct?

Allowed business types

Business type	Description	Example values
Chislo	Numeric value	Order number, Quantity
Tekst	Free text	Comment, Description
Data	Date	Creation date
Perechislenie	Fixed set of values	Status, Type
Da/Net	Boolean value	Active, Approved
Fail	Attachment/file	Instruction, Appendix
Ssylka	Reference to another entity	Links to OBJ-NNN

Forbidden:

• Technical types: UUID, FK, String(255), Int, DateTime, JSON, Boolean, Decimal
• System fields: id, created_at, updated_at, created_by

Attribute ID generation

MATCH (e:BusinessEntity {id: $entityId})-[:HAS_ATTRIBUTE]->(a:EntityAttribute)
WITH max(toInteger(replace(a.id, $entityId + '-A', ''))) AS maxNum
RETURN $entityId + '-A' + apoc.text.lpad(toString(coalesce(maxNum, 0) + 1), 2, '0') AS nextAttrId

Graph write (after confirmation per entity)

For each confirmed attribute:

MERGE (a:EntityAttribute {id: $attrId})
SET a.name = $name,
    a.business_type = $businessType,
    a.required = $required,
    a.comment = $comment
WITH a
MATCH (e:BusinessEntity {id: $entityId})
MERGE (e)-[:HAS_ATTRIBUTE]->(a)

Properties on EntityAttribute:

Property	Type	Description
id	String	{OBJ}-A{NN} (e.g. OBJ-001-A01)
name	String	Attribute name (Russian)
business_type	String	One of the allowed business types
required	Boolean	Whether the attribute is mandatory
comment	String	Description or clarification

Transition

After all entities have attributes confirmed and written -> Phase 3

---

Phase 3: Relationships (constructive)

Goal: Define relationships between entities and generate a classDiagram.

Actions

1. For each pair of related entities the agent PROPOSES:

   • Relationship type: association, aggregation, composition
   • Cardinality: 1:1, 1:N, N:N
   • Role name for the relationship

2. Present a relationship table:

**Phase 3: Entity Relationships**

| Entity 1 | Entity 2 | Rel. type | Cardinality | Description |
|----------|----------|-----------|-------------|-------------|
| OBJ-001 | OBJ-002 | association | 1:N | {description} |
| OBJ-003 | OBJ-004 | composition | 1:1 | includes |

Questions:
1. Are the relationships correct?
2. Any missing relationships?
3. Are the cardinalities correct?

3. After confirmation, generate a Mermaid classDiagram from graph data:

classDiagram
    direction LR
    Entity_A "1" --> "*" Entity_B : contains
    Entity_C "1" *-- "1" Sub_Entity : includes

classDiagram rules

• Show ONLY entity names and relationships
• DO NOT show attributes inside classes
• Relationship types in Mermaid:
  • Association: -->
  • Aggregation: o--
  • Composition: *--
• Cardinality in quotes: "1", "*", "1" .. "*"

Graph write (after confirmation)

For each confirmed relationship:

MATCH (e1:BusinessEntity {id: $entity1Id})
MATCH (e2:BusinessEntity {id: $entity2Id})
MERGE (e1)-[r:RELATES_TO]->(e2)
SET r.rel_type = $relType,
    r.cardinality = $cardinality,
    r.description = $description

Relationship properties on RELATES_TO:

Property	Type	Description
rel_type	String	"association", "aggregation", or "composition"
cardinality	String	"1:1", "1:N", or "N:N"
description	String	Role name / description of the relationship

Transition

After user confirmation and graph write -> Phase 4

---

Phase 4: States + Transitions (interactive)

Goal: For entities with a lifecycle (has_states: true), describe states and transitions.

Determine which entities have states

Typically business objects with a "Perechislenie" attribute named "Status" or similar. The agent proposes which entities should have has_states: true based on:

• Attributes of type "Perechislenie" found in Phase 2
• Workflow steps that MODIFY the entity (state changes)

For each entity with states

**{OBJ-NNN}. {Name} --- States**

| State | Description | Who transitions |
|-------|-------------|-----------------|
| New | {description} | {role/system} |
| In progress | {description} | {role} |
| Completed | {description} | {role} |

**Transitions:**

| From | To | Condition |
|------|----|-----------|
| New | In progress | {condition} |
| In progress | Completed | {condition} |

Questions:
1. Are the states correct?
2. Are the transitions and conditions correct?
3. Any missing states or transitions?

State ID generation

MATCH (e:BusinessEntity {id: $entityId})-[:HAS_STATE]->(s:EntityState)
WITH max(toInteger(replace(s.id, $entityId + '-ST', ''))) AS maxNum
RETURN $entityId + '-ST' + apoc.text.lpad(toString(coalesce(maxNum, 0) + 1), 2, '0') AS nextStateId

Graph write (after confirmation per entity)

For each confirmed state:

MERGE (s:EntityState {id: $stateId})
SET s.name = $stateName,
    s.description = $description,
    s.transitioned_by = $transitionedBy
WITH s
MATCH (e:BusinessEntity {id: $entityId})
MERGE (e)-[:HAS_STATE]->(s)

For each confirmed transition:

MATCH (s1:EntityState {id: $fromStateId})
MATCH (s2:EntityState {id: $toStateId})
MERGE (s1)-[t:TRANSITIONS_TO]->(s2)
SET t.condition = $condition

Update the entity's has_states flag:

MATCH (e:BusinessEntity {id: $entityId})
SET e.has_states = true

Properties on EntityState:

Property	Type	Description
id	String	{OBJ}-ST{NN} (e.g. OBJ-001-ST01)
name	String	State name (Russian)
description	String	What does this state mean
transitioned_by	String	Role or system that causes this transition

Properties on TRANSITIONS_TO:

Property	Type	Description
condition	String	Condition / event that triggers the transition

Transition

After all states confirmed and written -> Phase 5

---

Phase 5: CRUD Matrix (automatic)

Goal: Compute and display the entity-process CRUD matrix directly from graph relationships.

Query: ba_entity_crud_matrix

Run the named query from graph-infra/queries/ba-queries.cypher:

MATCH (bp:BusinessProcess)-[:HAS_STEP]->(ws:WorkflowStep)
OPTIONAL MATCH (ws)-[:READS]->(e_read:BusinessEntity)
OPTIONAL MATCH (ws)-[:PRODUCES]->(e_prod:BusinessEntity)
OPTIONAL MATCH (ws)-[:MODIFIES]->(e_mod:BusinessEntity)
WITH bp,
     collect(DISTINCT e_read.id) AS reads,
     collect(DISTINCT e_prod.id) AS creates,
     collect(DISTINCT e_mod.id) AS updates
UNWIND (reads + creates + updates) AS entity_id
WITH bp.id AS bp_id, bp.name AS bp_name, entity_id,
     entity_id IN creates AS is_create,
     entity_id IN reads AS is_read,
     entity_id IN updates AS is_update
MATCH (e:BusinessEntity {id: entity_id})
RETURN e.id AS entity_id, e.name AS entity_name,
       bp_id, bp_name,
       CASE WHEN is_create THEN 'C' ELSE '' END +
       CASE WHEN is_read THEN 'R' ELSE '' END +
       CASE WHEN is_update THEN 'U' ELSE '' END AS crud
ORDER BY e.id, bp_id

Format as matrix

Pivot the query results into a matrix:

**Phase 5: CRUD Matrix (computed from graph)**

| Entity | BP-001 | BP-002 | BP-003 |
|--------|--------|--------|--------|
| OBJ-001. {Name} | R | C,R | --- |
| OBJ-002. {Name} | C | R | R,U |

Legend: C = Create, R = Read, U = Update, D = Delete, --- = not used.

Validation checks

1. Orphan entities --- entities with no READS/PRODUCES/MODIFIES relationships:

   MATCH (e:BusinessEntity)
   WHERE NOT EXISTS { (e)<-[:READS|PRODUCES|MODIFIES]-(:WorkflowStep) }
   RETURN e.id AS id, e.name AS name
   

2. Processes without entities --- processes whose steps reference no entities:

   MATCH (bp:BusinessProcess)-[:HAS_STEP]->(ws:WorkflowStep)
   WHERE NOT EXISTS { (ws)-[:READS|PRODUCES|MODIFIES]->(:BusinessEntity) }
   WITH bp, count(ws) AS total_steps
   RETURN bp.id AS id, bp.name AS name, total_steps
   

3. Report orphans and unlinked processes to the user for review.

Presentation

**Phase 5: CRUD Matrix**

{Matrix table}

Validation:
- Orphan entities (not used in any process): {list or "none"}
- Processes without entity references: {list or "none"}

Everything correct? I can make adjustments before finalizing.

---

Workflow: Mode CREATE

Add a single new entity to the existing catalog in Neo4j.

Step 1: Gather information

Questions:

1. What is the entity name?
2. Stereotype: "Vneshni dokument", "Biznes-ob'ekt", or "Rezul'tat"?
3. If external document --- what is the structure (sheets, sections)?
4. What attributes does it have?
5. Which existing entities is it related to?
6. In which processes is it used?
7. Does it have states (lifecycle)?

Actions:

1. Get next available ID:

   MATCH (e:BusinessEntity)
   WITH max(toInteger(replace(e.id, 'OBJ-', ''))) AS maxNum
   RETURN 'OBJ-' + apoc.text.lpad(toString(coalesce(maxNum, 0) + 1), 3, '0') AS nextId
   

2. Verify the entity does not duplicate existing ones:

   MATCH (e:BusinessEntity)
   WHERE toLower(e.name) CONTAINS toLower($namePart)
   RETURN e.id, e.name, e.stereotype
   

Step 2: Write to graph

1. Entity node:

   MERGE (e:BusinessEntity {id: $id})
   SET e.name = $name,
       e.stereotype = $stereotype,
       e.has_states = $hasStates,
       e.description = $description
   

2. Attribute nodes (for each attribute):

   MERGE (a:EntityAttribute {id: $attrId})
   SET a.name = $name,
       a.business_type = $businessType,
       a.required = $required,
       a.comment = $comment
   WITH a
   MATCH (e:BusinessEntity {id: $entityId})
   MERGE (e)-[:HAS_ATTRIBUTE]->(a)
   

3. Relationship edges (for each relationship to existing entities):

   MATCH (e1:BusinessEntity {id: $entity1Id})
   MATCH (e2:BusinessEntity {id: $entity2Id})
   MERGE (e1)-[r:RELATES_TO]->(e2)
   SET r.rel_type = $relType,
       r.cardinality = $cardinality,
       r.description = $description
   

4. State nodes (if has_states = true):

   MERGE (s:EntityState {id: $stateId})
   SET s.name = $stateName,
       s.description = $description,
       s.transitioned_by = $transitionedBy
   WITH s
   MATCH (e:BusinessEntity {id: $entityId})
   MERGE (e)-[:HAS_STATE]->(s)
   

5. Transition edges (for each state transition):

   MATCH (s1:EntityState {id: $fromStateId})
   MATCH (s2:EntityState {id: $toStateId})
   MERGE (s1)-[t:TRANSITIONS_TO]->(s2)
   SET t.condition = $condition
   

Step 3: Verify and report

MATCH (e:BusinessEntity {id: $newId})
OPTIONAL MATCH (e)-[:HAS_ATTRIBUTE]->(a:EntityAttribute)
OPTIONAL MATCH (e)-[:HAS_STATE]->(s:EntityState)
OPTIONAL MATCH (e)-[r:RELATES_TO]-(other:BusinessEntity)
RETURN e, collect(DISTINCT a) AS attributes,
       collect(DISTINCT s) AS states,
       collect(DISTINCT {entity: other.id, rel: type(r), props: properties(r)}) AS relationships

---

Workflow: Mode MODIFY

Modify an existing entity with impact analysis via graph traversal.

Step 1: Impact Check

Goal: Determine which workflows and related entities are affected by the change.

Change types:

Type	Description	Potential impact
ADD_ATTR	Add attribute	Workflow steps, CRUD matrix
MODIFY_ATTR	Change attribute (type, required)	Workflow steps, related entities
REMOVE_ATTR	Remove attribute	Workflow steps, CRUD matrix
CHANGE_STEREOTYPE	Change stereotype	Entity properties
ADD_STATE	Add state	State graph
REMOVE_STATE	Remove state	Transition edges, workflow steps
ADD_RELATION	Add relationship	RELATES_TO edges
REMOVE_RELATION	Remove relationship	RELATES_TO edges

Impact analysis query:

MATCH (e:BusinessEntity {id: $entityId})
OPTIONAL MATCH (ws:WorkflowStep)-[rel:READS|PRODUCES|MODIFIES]->(e)
OPTIONAL MATCH (bp:BusinessProcess)-[:HAS_STEP]->(ws)
OPTIONAL MATCH (e)-[:HAS_ATTRIBUTE]->(a:EntityAttribute)
OPTIONAL MATCH (e)-[:HAS_STATE]->(s:EntityState)
OPTIONAL MATCH (e)-[r:RELATES_TO]-(other:BusinessEntity)
OPTIONAL MATCH (brq:BusinessRule)-[:CONSTRAINS]->(e)
RETURN e,
       collect(DISTINCT {bp: bp.id, bp_name: bp.name, step: ws.id, step_name: ws.function_name, rel_type: type(rel)}) AS workflow_refs,
       collect(DISTINCT a) AS attributes,
       collect(DISTINCT s) AS states,
       collect(DISTINCT {entity: other.id, entity_name: other.name}) AS related_entities,
       collect(DISTINCT {rule: brq.id, rule_name: brq.name}) AS business_rules

Present impact report:

## Impact Report

### Change
- **Entity:** {OBJ-NNN. Name}
- **Change type:** {type}
- **Description:** {what changes}

### Affected artifacts (from graph)

| Artifact | Node/Relationship | What to change |
|----------|-------------------|----------------|
| Workflow BP-{NNN}, step {S-NN} | WorkflowStep READS/PRODUCES/MODIFIES | {description} |
| Related entity OBJ-{NNN} | RELATES_TO edge | {description} |
| Business rule BRQ-{NNN} | CONSTRAINS edge | {description} |

Proceed with changes? (yes/no)

Do not apply changes without user confirmation!

Step 2: Apply changes

Based on the change type, execute the appropriate Cypher mutations: