sad-mcp 0.1.20 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sad-mcp",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "MCP server for Software Analysis and Design course materials at BGU",
   "type": "module",
   "bin": {

package/skills/bpmn-diagram/SKILL.md

@@ -18,22 +18,48 @@ This skill creates professional, standards-compliant BPMN diagrams rendered as i
 
 Before writing any SVG code, analyze the process description to identify:
 
-1. **Participants**: Who are the actors? Determine if they are internal (lanes in the same pool) or external (separate pools)
-   - External participants (customers, patients, citizens) → **separate pool** with message flows
+1. **Participants — CRITICAL (Pool vs Lane)**: Who are the actors? Classify each based on **process control**, not just organizational membership:
+   - If the participant acts **independently** and communicates with the organization from outside (e.g., a customer calling to cancel a subscription, a patient arriving at a clinic, a citizen filing a complaint, an external company like a credit card company or supplier) → **separate pool** with message flows
+   - If the organization **dictates and controls** how the participant performs their activities within its own system (e.g., a customer using the bank's app to make a transaction, a user following a guided online workflow) → **lane** within the organization pool with sequence flows
    - Internal roles within the same organization → **lanes** within one pool
+   - **The test**: "Does the organization orchestrate this participant's actions, or do they act on their own initiative?" If they act independently → separate pool
 2. **Activities/Tasks**: List every action/task mentioned
 3. **Decision Points**: Identify every conditional branch (if/else, exists/doesn't exist)
 4. **Data**: What information is created, read, updated, or stored?
 5. **Handoffs**: Where does work pass between participants? These become message flows between pools or sequence flows between lanes
 6. **Waiting Points**: Is any participant passively waiting? Use intermediate events, not regular tasks
-7. **Data Persistence**: If the process description mentions a "system" or implies that data is stored, read, or updated across multiple steps or participants — model a Data Store (DB). Connect it with data associations to every task that reads from or writes to it. Do NOT substitute a lightweight Data Object when persistent shared storage is implied. A system = a data store.
+7. **Data Persistence — CRITICAL**: Model a Data Store whenever the process involves persistent storage. **Trigger words** that require a data store: "system", "database", "account", "record", "registry". **Action verbs** that imply a data store: "block account", "update record", "generate invoice", "credit account", "register", "log", "store", "look up", "check status". If a task reads from or writes to shared persistent state, it MUST have a data association to a data store. Do NOT substitute a lightweight Data Object when persistent shared storage is implied. A system = a data store. An account = a data store.
 8. **Complete Each Participant's Flow**: Every pool must have its own complete internal sequence flow (start → tasks → end), even for external parties. If the description says "Company X will handle the complaint," model the full handling sequence inside that pool (receive → process → respond → close), not just the first step. Never collapse an external participant's process into a single task or annotation.
 9. **Bidirectional Communication**: When one participant sends something to another, check: does the receiver send something back? Every message flow that triggers a response must have a corresponding return message flow. Model both directions explicitly. Common pairs: request→acknowledgment, notification→confirmation, complaint→response.
 10. **Implied Activities**: Read the description for activities that are described but not explicitly named as "tasks." Phrases like "she can and is expected to be in phone contact" or "will coordinate directly" describe real activities that should be modeled as tasks, NOT as text annotations. Annotations are only for meta-information that clarifies context but isn't an executable step.
 
+## Mandatory Structural Analysis Output — CRITICAL
+
+**Before writing ANY SVG code, you MUST output the following structured analysis as text.** This is non-negotiable — skipping this step is the primary cause of structural modeling errors (wrong pool/lane assignments, missing data stores).
+
+### Required Output Format:
+
+```
+STRUCTURAL ANALYSIS:
+
+1. PARTICIPANTS:
+   - [Name] → POOL (acts independently: [reason]) / LANE (org controls: [reason])
+   - ...
+
+2. DATA STORES:
+   - [Store name] — triggered by: [task X writes/reads/updates ...]
+   - ...
+
+3. MESSAGE FLOWS (between pools):
+   - [Pool A] ↔ [Pool B]: [what is communicated]
+   - ...
+```
+
+**The SVG diagram MUST match this analysis exactly.** If the analysis says "separate pool," the SVG must have a separate pool. If the analysis identifies a data store, the SVG must include it with data associations.
+
 ## Architecture & Layout Rules
 
-### Pools and Lanes
+### Pools and Lanes — CRITICAL
 
 - **External participants** (e.g., patient, customer, citizen) get their own **pool** at the top of the diagram
   - Use a distinct color scheme for the external pool header (e.g., brown) to differentiate from the organization pool (dark gray)
@@ -43,6 +69,11 @@ Before writing any SVG code, analyze the process description to identify:
   - Separate lanes with dashed divider lines
 - Pool headers are vertical text bars on the left side of the pool
 
+**Common Mistakes to Avoid:**
+- Putting a customer/patient/citizen as a lane when they act independently — they need a separate pool with message flows, not sequence flows
+- Using sequence flows between independent participants instead of message flows between separate pools
+- Forgetting that external companies (e.g., חברת אשראי, ספק, קבלן) also need their own pool — they are not part of the organization
+
 ### Color Scheme by Participant Type
 
 | Element | Fill | Stroke |
@@ -190,9 +221,9 @@ Output a single self-contained HTML file with:
 - Height: Scale based on number of pools and lanes (~130px per external pool, ~250px per lane, plus spacing for data artifacts)
 - Use `viewBox` matching width/height for proper scaling
 
-## Iterative Refinement Checklist
+## Verification Gate — MANDATORY
 
-After generating the initial diagram, verify:
+**STOP before delivering the diagram. Verify EVERY item below. If any item fails, you MUST fix it before delivering. Do NOT skip this step.**
 
 - [ ] Every gateway (split AND merge) has an X or + symbol
 - [ ] No arrow paths overlap or cross ambiguously
@@ -203,7 +234,7 @@ After generating the initial diagram, verify:
 - [ ] The legend includes every symbol type used in the diagram
 - [ ] Data artifacts don't overlap with sequence flow paths
 - [ ] Every pool has a complete internal flow (start → ... → end), not just a single task
-- [ ] A Data Store is modeled if the process mentions a "system" or database
+- [ ] A Data Store is modeled for every persistent system (accounts, invoices, records, registrations — see trigger words in Process Analysis step 7)
 - [ ] Every message flow that expects a response has a return message flow
 - [ ] Phone calls, emails, and direct contacts mentioned in the description are modeled as tasks, not annotations
 - [ ] After a rejection/refusal gateway, the rejecting participant's subsequent state (waiting/action) is explicitly modeled