sad-mcp 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sad-mcp",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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,16 @@ 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
+- Omitting a participant entirely — if the process description mentions a customer/patient/citizen, they MUST appear in the diagram as a pool with their own flow
+
+### Element Placement — CRITICAL
+
+**Every BPMN element (task, gateway, event) must be fully contained within a single lane or pool.** No element may overlap a lane divider line or sit on the boundary between two lanes. If an element belongs to a lane, it must be clearly centered vertically within that lane's area, with visible spacing from the lane borders above and below.
+
 ### Color Scheme by Participant Type
 
 | Element | Fill | Stroke |
@@ -78,13 +114,28 @@ Example: If a Resident interacts with both a Delivery Company and a Development
 
 ### Gateways — CRITICAL RULE
 
-**Every gateway — both split AND merge/join — MUST display the X marker (for XOR) or + marker (for AND/parallel).** Merge gateways are never left as blank diamonds. This is a non-negotiable requirement.
+**Gateway diamonds must contain ONLY the marker symbol — NEVER text.** No labels, descriptions, or questions inside the diamond shape. Gateway labels go ABOVE or BESIDE the diamond, never inside it.
+
+- XOR (exclusive): **X** marker inside the diamond
+- AND (parallel): **+** marker inside the diamond
+- OR (inclusive): **O** marker inside the diamond
+
+**Every gateway — both split AND merge/join — MUST display its marker symbol.** Merge gateways are never left as blank diamonds. This is a non-negotiable requirement.
+
+**Anti-pattern — NEVER do this:**
+```svg
+<!-- WRONG: text inside gateway diamond -->
+<polygon points="..." fill="..." stroke="..."/>
+<text x="CX" y="CY">כמה ימים?</text>  <!-- FORBIDDEN -->
+```
 
+**Correct pattern:**
 ```svg
-<!-- XOR Gateway template (both split and merge) -->
+<!-- RIGHT: X marker inside, label outside -->
 <rect x="X" y="Y" width="34" height="34" class="gateway" transform="rotate(45, CX, CY)"/>
 <line x1="CX-7" y1="CY-10" x2="CX+7" y2="CY+10" class="gateway-x"/>
 <line x1="CX+7" y1="CY-10" x2="CX-7" y2="CY+10" class="gateway-x"/>
+<text x="CX" y="CY-25" text-anchor="middle">כמה ימים?</text>  <!-- label ABOVE -->
 ```
 
 ### Intermediate Events (Waiting/Catching)
@@ -190,20 +241,23 @@ 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
+- [ ] Every gateway (split AND merge) has ONLY an X/+/O marker inside — no text inside the diamond
+- [ ] Gateway labels (questions, conditions) are positioned ABOVE or BESIDE the diamond, never inside
+- [ ] Every element (task, gateway, event) is fully inside a single lane — nothing sits on a lane boundary
 - [ ] No arrow paths overlap or cross ambiguously
 - [ ] Data objects (📄) and data stores (🗄️) use different icons
+- [ ] Every participant mentioned in the process description appears in the diagram — none are omitted
 - [ ] External participants are in separate pools with message flows
 - [ ] Passive waiting uses intermediate events, not regular tasks
 - [ ] Flow labels (כן/לא) are clearly positioned near their gateway
 - [ ] 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