ba-workflow

/nacl:ba-workflow --- Activity Diagram in Neo4j

Role

You are a Business Analyst agent specialized in building activity diagrams (3-swimlane workflow decomposition) for business processes. Unlike the file-based /nacl:ba-workflow, you use the Neo4j knowledge graph as the single source of truth. You create WorkflowStep nodes, bind them to performers (BusinessRole) and artifacts (BusinessEntity), model decision points, and generate a Mermaid flowchart from graph queries.

---

Parameters

• bp_id --- identifier of the BusinessProcess node to decompose (e.g. "BP-001")

---

Shared References

Read ${CLAUDE_PLUGIN_ROOT}/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 ${CLAUDE_PLUGIN_ROOT}/nacl-core/SKILL.md → Graph Config Resolution). MCP tools handle the connection automatically.
• ID generation rules: WorkflowStep IDs use format {BP}-S{NN} (e.g. BP-001-S03)
• Excalidraw element types and customData structure (for optional board generation)

Reference query: ba_workflow_steps from graph-infra/queries/ba-queries.cypher

---

Preliminary Check

1. Load the BusinessProcess node

Query Neo4j for the target process:

MATCH (bp:BusinessProcess {id: $bpId})
OPTIONAL MATCH (bp)<-[:OWNS]-(owner:BusinessRole)
RETURN bp, owner

Extract: name, trigger, result, has_decomposition, owner role.

• If the node does not exist --- stop and report:

  BusinessProcess {bp_id} not found in the graph. Create it first with /nacl:ba-process, then run /nacl:ba-workflow.

• If has_decomposition is not true --- stop and report:

  BusinessProcess {bp_id} has has_decomposition: false. Workflow decomposition is not applicable.

2. Load existing roles

MATCH (r:BusinessRole)
OPTIONAL MATCH (r)-[:PARTICIPATES_IN]->(bp:BusinessProcess {id: $bpId})
OPTIONAL MATCH (r)-[:OWNS]->(bp2:BusinessProcess {id: $bpId})
RETURN r, bp IS NOT NULL OR bp2 IS NOT NULL AS involved
ORDER BY r.id

Identify roles already linked to the target process and all available roles for binding.

3. Load existing entities

MATCH (e:BusinessEntity)
RETURN e.id AS id, e.name AS name, e.stereotype AS stereotype
ORDER BY e.id

Identify entities available for artifact binding in Phase 4.

4. Check for existing workflow steps

MATCH (bp:BusinessProcess {id: $bpId})-[:HAS_STEP]->(ws:WorkflowStep)
OPTIONAL MATCH (ws)-[:PERFORMED_BY]->(r:BusinessRole)
RETURN ws, r
ORDER BY ws.step_number

If steps already exist, show them to the user and ask: continue editing, rebuild from scratch, or abort.

---

Workflow

General Principle

+-------------------------------------------------------------------------+
|                    PRELIMINARY CHECK                                     |
|  1. BusinessProcess node exists, has_decomposition = true               |
|  2. Extract name, trigger, result, roles from graph                     |
|  3. If node missing -> suggest /nacl:ba-process                        |
+-------------------------------------------------------------------------+
                                    |
                                    v
+--------------+   +---------------+   +---------------+
| Phase 1      |   | Phase 2       |   | Phase 3       |
| Step         |-->| Stereotyping  |-->| Performer     |
| Identification|   |               |   | Binding       |
+--------------+   +---------------+   +---------------+
                                            |
                                            v
+--------------+   +---------------+   +---------------+
| Phase 6      |   | Phase 5       |   | Phase 4       |
| Diagram      |<--| Decision      |<--| Artifact      |
| Generation   |   | Points        |   | Binding       |
+--------------+   +---------------+   +---------------+

Do not proceed to the next phase without user confirmation!

---

Critical Rules

Autonomy Principle (facts vs construction)

Only from the user (FACTS)	Agent constructs (STRUCTURES)
What steps are performed	Step numbering, ID format {BP}-S{NN}
In what order the steps occur	Stereotype: "Бизнес-функция" / "Автоматизируется"
Who performs each step	Assigning IDs to roles and documents
What documents are inputs/outputs	Mermaid diagram, canonical table
Where branching points are	change_marker assignment based on user description
Current state of the process (As-Is)	Neo4j node/relationship creation, validation

The agent NEVER adds steps that are not in the user's description. The agent MAY suggest a stereotype, performer binding, or artifact binding --- but only based on context from the user's description, and always with a confirmation request.

Canonical Representation

The Neo4j graph is the authoritative source, not the Mermaid diagram. When discrepancies arise, the graph is considered correct. Mermaid is a visual illustration for stakeholder alignment.

---

Phases

Phase 1: Step Identification (interactive)

Mode: INTERACTIVE. This is the key phase --- the user provides facts.

Goal: Obtain a complete description of the business process steps from the user and structure them.

Actions:

1. Show the user the context extracted from the graph:

   BusinessProcess {bp_id}: {name}
   - Goal: {goal from bp.description or bp.result}
   - Trigger: {trigger}
   - Result: {result}
   - Owner: {owner role}
   - Existing roles: {list of roles involved}
   

2. Ask the key question:

   Describe the steps of this business process: who does what, in what order, what documents are used.

3. Based on the user's answer, structure the description into numbered steps:

   1. {Who} {does what}
   2. {Who} {does what}
   3. {Who} {does what}
   ...
   

4. Assign change_marker values based on the user's description:
   • [inherited As-Is] --- step exists in the current process, carried over without changes
   • [changed] --- step exists but modified in To-Be
   • [new] --- step added in To-Be
5. Assign step IDs in format {BP}-S{NN} (e.g. BP-001-S01, BP-001-S02, ...):
   • Query for existing steps to determine the next available number:

     MATCH (bp:BusinessProcess {id: $bpId})-[:HAS_STEP]->(ws:WorkflowStep)
     RETURN max(ws.step_number) AS maxStep
     

   • New steps start from maxStep + 1 (or 1 if no steps exist)
6. Show the result to the user and request confirmation

Constraint: Maximum 12 steps. If more --- propose decomposition: extract some steps into a subprocess (a separate BusinessProcess with its own workflow, linked via CALLS_SUB).

Confirmation gate: User confirms the step list, change markers, and IDs.

---

Phase 2: Stereotyping (constructive)

Mode: CONSTRUCTIVE. Agent proposes, user confirms.

Goal: Assign each step a stereotype: "Бизнес-функция" or "Автоматизируется".

Actions:

1. For each step from Phase 1, the agent proposes a stereotype based on:
   • The user's step description
   • Keywords: "система", "автоматически", "импорт", "экспорт", "расчёт", "генерация" -> "Автоматизируется"
   • Keywords: "анализирует", "принимает решение", "согласует", "проверяет (вручную)" -> "Бизнес-функция"
2. Show the stereotype table:

   | ID | Step | Proposed Stereotype | Rationale |
   |---|---|---|---|
   | BP-001-S01 | Mark candidate parts in BOM | "Бизнес-функция" | Manual employee action |
   | BP-001-S02 | Import parts into catalog | "Автоматизируется" | Keyword "import" |
   

3. Request confirmation for each stereotype

Stereotypes:

Stereotype	Description	Mermaid Color
"Бизнес-функция"	Step performed by a human	Yellow (bizFunc, #ffd93d)
"Автоматизируется"	Step subject to automation in the target system	Green (autoFunc, #2ecc71)

Confirmation gate: User confirms the stereotype for each step.

---

Phase 3: Performer Binding (constructive)

Mode: CONSTRUCTIVE. Agent proposes, user confirms.

Goal: Assign each step exactly ONE performer (left swimlane) and create PERFORMED_BY relationships.

Actions:

1. Use roles loaded during Preliminary Check. Show available roles:

   MATCH (r:BusinessRole) RETURN r.id, r.full_name, r.department ORDER BY r.id
   

2. For each step, the agent proposes a performer based on:
   • Roles linked to the BusinessProcess (via PARTICIPATES_IN or OWNS)
   • Context from the user's step description in Phase 1
   • For steps with stereotype "Автоматизируется" --- the performer is usually "Система" (System) or the role that initiates the automated action
3. Show the binding table:

   | ID | Step | Proposed Performer |
   |---|---|---|
   | BP-001-S01 | Mark candidate parts in BOM | ROL-05 (УРРД) |
   | BP-001-S02 | Import parts into catalog | Система |
   

4. Request confirmation

Rules:

• Each step has exactly one performer
• If the performer is an existing BusinessRole node --- the relationship PERFORMED_BY will point to it
• If the performer is "Система" (System) --- create or reuse a BusinessRole node with id: "ROL-SYS", full_name: "Система"
• If a role is not yet in the graph --- note it for creation (the user can run /nacl:ba-roles afterward)

Confirmation gate: User confirms the performer for each step.

---

Phase 4: Artifact Binding (constructive)

Mode: CONSTRUCTIVE. Agent proposes, user confirms.

Goal: Determine input and output documents for each step (right swimlane) and create READS / PRODUCES relationships.

Actions:

1. Use entities loaded during Preliminary Check. Show available entities:

   MATCH (e:BusinessEntity) RETURN e.id, e.name, e.stereotype ORDER BY e.id
   

2. For each step, the agent proposes input and output documents based on:
   • The user's step description
   • Existing BusinessEntity nodes in the graph
   • Process context (trigger inputs, result outputs)
3. Show the binding table:

   | ID | Step | Documents (input) | Documents (output) |
   |---|---|---|---|
   | BP-001-S01 | Mark candidate parts | OBJ-001. BOM | --- |
   | BP-001-S02 | Import into catalog | --- | OBJ-005. Parts List |
   

4. If a document is mentioned but no matching BusinessEntity exists:
   • Mark it as "requires creation"
   • After workflow completion, suggest /nacl:ba-entities to create it
5. Request confirmation

Rules:

• Documents are BusinessEntity nodes (referenced by OBJ-{NNN} id) or external systems
• A step may have no documents (pure action)
• READS relationship: step reads an input document
• PRODUCES relationship: step produces an output document
• One document may be the output of one step and the input of another

Confirmation gate: User confirms the artifact bindings.

---

Phase 5: Decision Points (interactive)

Mode: INTERACTIVE. User describes branching, agent structures.

Goal: Identify decision points (forks), exceptions, and subprocess calls.

Actions:

1. Based on the description from Phase 1, identify potential branching points
2. For each fork, clarify with the user:
   • Condition: the question text (e.g. "List formed?")
   • Outgoing branches: maximum 3 variants with labels
   • Where each branch leads: to the next step, to end, or to an exception
3. Identify exception events (process interrupted without result):
   • Conditions under which the process does not achieve its goal
4. Identify subprocess references:
   • Steps that lead to other BusinessProcesses with their own decomposition
   • Format: CALLS_SUB relationship to another BusinessProcess node

Decision point modeling in Neo4j:

Decision points are modeled as special WorkflowStep nodes with additional properties:

CREATE (d:WorkflowStep {
  id: '{BP}-D{NN}',
  function_name: '{condition question}',
  step_number: {N},
  stereotype: 'Decision',
  change_marker: '{marker}'
})

Outgoing branches use NEXT_STEP relationships with a label property:

MATCH (d:WorkflowStep {id: '{BP}-D01'})
MATCH (yes_step:WorkflowStep {id: '{BP}-S05'})
MATCH (no_step:WorkflowStep {id: '{BP}-S08'})
CREATE (d)-[:NEXT_STEP {label: 'Да'}]->(yes_step)
CREATE (d)-[:NEXT_STEP {label: 'Нет'}]->(no_step)

Exception nodes:

CREATE (exc:WorkflowStep {
  id: '{BP}-EXC{N}',
  function_name: 'Результат не достигнут',
  stereotype: 'Exception'
})

Subprocess links:

MATCH (ws:WorkflowStep {id: '{BP}-S{NN}'})
MATCH (sub:BusinessProcess {id: '{SUB_BP_ID}'})
CREATE (ws)-[:CALLS_SUB]->(sub)

Rules for forks:

• Maximum 3 outgoing branches from one decision point
• Branches must converge back into the flow or terminate (End/Exception)
• Labels on arrows are brief condition formulations

Confirmation gate: User confirms forks, exceptions, and subprocess references.

---

Phase 6: Diagram Generation (automated)

Mode: AUTOMATED. Agent generates artifacts from confirmed data.

Goal: Write all confirmed data to Neo4j and generate a Mermaid flowchart from graph queries.

Actions:

6.1 Write WorkflowStep nodes to Neo4j

For each confirmed step, create a node and link it to the BusinessProcess:

CREATE (ws:WorkflowStep {
  id: $stepId,
  function_name: $functionName,
  step_number: $stepNumber,
  stereotype: $stereotype,
  change_marker: $changeMarker
})
WITH ws
MATCH (bp:BusinessProcess {id: $bpId})
CREATE (bp)-[:HAS_STEP {order: $stepNumber}]->(ws)

Where:

• $stepId --- format {BP}-S{NN} (e.g. BP-001-S03)
• $functionName --- step description (e.g. "Mark candidate parts in BOM")
• $stepNumber --- integer, sequential order
• $stereotype --- "Бизнес-функция" or "Автоматизируется"
• $changeMarker --- "[inherited As-Is]", "[changed]", or "[new]"

6.2 Write NEXT_STEP relationships (flow order)

For each consecutive pair of steps, create the flow:

MATCH (a:WorkflowStep {id: $fromId})
MATCH (b:WorkflowStep {id: $toId})
CREATE (a)-[:NEXT_STEP {label: $label}]->(b)

The label property is optional for straight-line flow and required for decision branches.

6.3 Write PERFORMED_BY relationships

MATCH (ws:WorkflowStep {id: $stepId})
MATCH (r:BusinessRole {id: $roleId})
CREATE (ws)-[:PERFORMED_BY]->(r)

6.4 Write READS / PRODUCES relationships

// Input document
MATCH (ws:WorkflowStep {id: $stepId})
MATCH (e:BusinessEntity {id: $entityId})
CREATE (ws)-[:READS]->(e)

// Output document
MATCH (ws:WorkflowStep {id: $stepId})
MATCH (e:BusinessEntity {id: $entityId})
CREATE (ws)-[:PRODUCES]->(e)

6.5 Write Decision and Exception nodes

See Phase 5 for the Cypher patterns. Create the nodes and their NEXT_STEP relationships.

6.6 Query the complete workflow from the graph

Use the reference query ba_workflow_steps (extended) to retrieve the full picture:

MATCH (bp:BusinessProcess {id: $bpId})-[:HAS_STEP]->(ws:WorkflowStep)
OPTIONAL MATCH (ws)-[:PERFORMED_BY]->(r:BusinessRole)
OPTIONAL MATCH (ws)-[:READS]->(input:BusinessEntity)
OPTIONAL MATCH (ws)-[:PRODUCES]->(output:BusinessEntity)
OPTIONAL MATCH (ws)-[:NEXT_STEP]->(next:WorkflowStep)
RETURN ws.id AS id,
       ws.step_number AS step_number,
       ws.function_name AS function_name,
       ws.stereotype AS stereotype,
       ws.change_marker AS change_marker,
       r.id AS performer_id,
       r.full_name AS performer_name,
       collect(DISTINCT {id: input.id, name: input.name}) AS inputs,
       collect(DISTINCT {id: output.id, name: output.name}) AS outputs,
       collect(DISTINCT {id: next.id, label: null}) AS next_steps
ORDER BY ws.step_number

6.7 Generate the canonical TABLE

From the query result, build the markdown table:

| # | ID | Performer | Step | Stereotype | Documents (input) | Documents (output) | Change |
|---|---|---|---|---|---|---|---|
| 1 | BP-001-S01 | ROL-05 (УРРД) | Mark candidate parts in BOM | "Бизнес-функция" | --- | --- | [inherited As-Is] |
| 2 | BP-001-S02 | Система | Import parts into catalog | "Автоматизируется" | --- | OBJ-005. Parts List | [new] |
| --- | BP-001-D01 | --- | **Decision:** List formed? | --- | --- | --- | --- |

6.8 Generate the Mermaid flowchart

Build a 3-swimlane flowchart TD from the graph query results:

• Direction: flowchart TD
• Start: Start((Начало)):::startEnd
• Business function: S01["<<Бизнес-функция>>\n1. Description\n:bust_in_silhouette: Role"]:::bizFunc
• Automated step: S02["<<Автоматизируется>>\n2. Description\n:bust_in_silhouette: Role"]:::autoFunc
• Decision: D01{{"Condition?"}}:::decision
• Exception: EXC1((Результат не достигнут)):::exception
• Subprocess: SUB1[["-> BP-{NNN}. Name"]]
• Documents: doc1[":page_facing_up: OBJ-{NNN}. Name"]:::doc connected with dashed lines -.-
• External systems: ext1[":link: Name"]:::extSys connected with dashed lines -.-
• End: End((Результат достигнут)):::startEnd

Apply color coding:

classDef bizFunc fill:#ffd93d,stroke:#f39c12,color:#000
classDef autoFunc fill:#2ecc71,stroke:#27ae60,color:#000
classDef decision fill:#fff,stroke:#2ecc71,color:#000
classDef doc fill:#fff3cd,stroke:#ffc107,color:#000
classDef extSys fill:#ffcccc,stroke:#e74c3c,color:#000
classDef startEnd fill:#333,stroke:#000,color:#fff
classDef exception fill:#ff6b6b,stroke:#c0392b,color:#fff

Flow arrows: --> for step-to-step flow, -.- for document connections (dashed).

6.9 Output to user

Present the following to the user for final confirmation:

1. The canonical table (generated from graph data)
2. The Mermaid flowchart
3. Summary of related artifacts (entities requiring creation, roles requiring creation)
4. Node/relationship counts written to the graph

Confirmation gate: User confirms the final output.

---

Important Rules

Canonical Representation

1. The Neo4j graph is the authoritative source. Validation checks the graph, not the Mermaid diagram.
2. The Mermaid diagram is a visual illustration for stakeholder alignment.
3. When discrepancies arise between graph and Mermaid, the graph is correct.

Step Rules

1. Maximum 12 steps per workflow. If more --- decompose into subprocesses via CALLS_SUB.
2. One performer per step --- each step has exactly one PERFORMED_BY relationship.
3. ID format: {BP}-S{NN} --- e.g. BP-001-S01, BP-001-S12.
4. Each step has a stereotype property: "Бизнес-функция" or "Автоматизируется".
5. Each step has a change_marker property: "[inherited As-Is]", "[changed]", or "[new]".

Document Rules (right swimlane)

1. Documents are BusinessEntity nodes (referenced by OBJ-{NNN} id) or external systems.
2. Documents MUST reference existing BusinessEntity nodes in the graph or be marked as "requires creation".
3. New entities are created via /nacl:ba-entities.
4. Document-step connections use READS (input) and PRODUCES (output) relationships.
5. In Mermaid, document connections are dashed lines (-.-), not flow arrows (-->).

Decision Rules

1. Maximum 3 outgoing branches from one decision point.
2. Branches must converge back into the flow or terminate (End/Exception).
3. Labels on NEXT_STEP edges are brief condition formulations.
4. Decision nodes use IDs in format {BP}-D{NN}.

Autonomy Principle

1. The agent NEVER adds steps that were not in the user's description.
2. The agent MAY propose stereotypes, performer bindings, artifact bindings.
3. Every agent proposal requires user confirmation.
4. If information is insufficient --- the agent asks a clarifying question, but does not invent an answer.

Flow Rules

1. The flow starts with Start and ends with at least one End (goal achieved).
2. May contain Exception nodes (interrupted without result).
3. No "dangling" steps --- every step is connected to the flow via NEXT_STEP relationships.

---

Relationships Reference

Relationship	From	To	Properties	Purpose
HAS_STEP	BusinessProcess	WorkflowStep	order: Int	Process owns step
NEXT_STEP	WorkflowStep	WorkflowStep	label: String (optional)	Flow order / branch label
PERFORMED_BY	WorkflowStep	BusinessRole	---	Left swimlane: who performs
READS	WorkflowStep	BusinessEntity	---	Right swimlane: input document
PRODUCES	WorkflowStep	BusinessEntity	---	Right swimlane: output document
CALLS_SUB	WorkflowStep	BusinessProcess	---	Subprocess decomposition

---

Reads / Writes

Reads (Neo4j via MCP)

Query	Purpose
BusinessProcess {id: $bpId}	Process card: name, trigger, result, has_decomposition
BusinessRole (all)	Available roles for performer binding
BusinessEntity (all)	Available entities for artifact binding
ba_workflow_steps (from ba-queries.cypher)	Existing steps for the process

Writes (Neo4j via MCP)

Node / Relationship	Purpose
CREATE (ws:WorkflowStep {...})	Workflow step nodes
CREATE (bp)-[:HAS_STEP]->(ws)	Link steps to process
CREATE (ws)-[:NEXT_STEP]->(ws2)	Flow order between steps
CREATE (ws)-[:PERFORMED_BY]->(r)	Performer binding
CREATE (ws)-[:READS]->(e)	Input document binding
CREATE (ws)-[:PRODUCES]->(e)	Output document binding
CREATE (ws)-[:CALLS_SUB]->(bp2)	Subprocess reference

Calls

Skill	Condition
/nacl:ba-entities	If a document in the right swimlane does not exist as a BusinessEntity node
/nacl:ba-roles	If a performer does not exist as a BusinessRole node

Called by

Skill	Context
/nacl:ba-process	After creating a BusinessProcess with has_decomposition: true
User	Manual invocation via /nacl:ba-workflow BP-{NNN}

---

Checklist

Before completing the workflow, verify:

Preliminary Conditions

• BusinessProcess node exists in the graph with has_decomposition: true
• Name, trigger, result extracted from the graph
• Existing steps checked (continue / rebuild / new)

Phase 1: Steps

• All steps received from the user and structured
• IDs assigned in format {BP}-S{NN}
• change_marker assigned: [inherited As-Is] / [changed] / [new]
• No more than 12 steps (otherwise decomposed into subprocesses)
• User confirmed step list

Phase 2: Stereotypes

• Each step has a stereotype: "Бизнес-функция" or "Автоматизируется"
• User confirmed each stereotype

Phase 3: Performers

• Each step has exactly one performer
• Performers reference existing BusinessRole nodes or are flagged for creation
• User confirmed each performer binding

Phase 4: Artifacts

• Input/output documents identified per step
• Documents reference existing BusinessEntity nodes or are flagged as "requires creation"
• User confirmed artifact bindings

Phase 5: Decisions

• Decision points identified with conditions
• Each decision has max 3 outgoing branches
• Branches converge or terminate (End/Exception)
• Subprocess references use valid BP IDs
• User confirmed decisions

Phase 6: Graph & Diagram

• All WorkflowStep nodes written to Neo4j
• HAS_STEP relationships created with correct order
• NEXT_STEP relationships create a connected flow
• PERFORMED_BY relationships link each step to one role
• READS / PRODUCES relationships link steps to entities
• Decision / Exception nodes written
• Canonical table generated from graph query
• Mermaid flowchart generated with correct color coding
• Documents use dashed lines (-.-), not flow arrows (-->)
• Flow starts with Start and ends with End
• Mermaid diagram renders correctly
• User confirmed final output

Cross-Validation

• Performers match BusinessRole nodes in the graph
• Documents match BusinessEntity nodes in the graph
• Subprocess references match BusinessProcess nodes in the graph
• No dangling steps (every step connected via NEXT_STEP)
• Agent did not add steps absent from the user's description
• Step count in graph matches confirmed step count