Migrate Project 1 flat collaboration diagrams to the Project 3 hierarchical format with boundary groupings and participant-type annotations. Supports non-destructive batch or individual migration: reads collaboration-diagrams.md and collaboration-diagrams.json produced by diagram-generatecollaboration (Project 1 mode), applies boundary-detection heuristics and stereotype-classification rules from diagram-generatecollaboration, and writes an enhanced counterpart file (collaboration-diagrams-enhanced.md / collaboration-diagrams-enhanced.json) alongside the originals. All existing requirement-traceability links and message sequences are preserved. Use when a user wants to upgrade legacy flat diagrams, batch-migrate all Project 1 diagrams, preview migration changes before applying, or add participant annotations to existing diagrams.
Migrate Project 1 flat collaboration diagrams to the Project 3 hierarchical format with boundary groupings and participant-type annotations. Supports non-destructive batch or individual migration: reads collaboration-diagrams.md and collaboration-diagrams.json produced by diagram-generatecollaboration (Project 1 mode), applies boundary-detection heuristics and stereotype-classification rules from diagram-generatecollaboration, and writes an enhanced counterpart file (collaboration-diagrams-enhanced.md / collaboration-diagrams-enhanced.json) alongside the originals. All existing requirement-traceability links and message sequences are preserved. Use when a user wants to upgrade legacy flat diagrams, batch-migrate all Project 1 diagrams, preview migration changes before applying, or add participant annotations to existing diagrams.
license
MIT
Migration Tools
Convert existing flat (Project 1 style) collaboration diagrams into hierarchical, boundary-annotated (Project 3 style) collaboration diagrams, preserving 100 % of requirement traceability and message-flow content.
Intent
Non-destructively upgrade pre-Project 3 flat sequenceDiagram EDPS collaboration diagrams to hierarchical, boundary-annotated format. Applies stereotype-classification rules from diagram-generatecollaboration, adds box boundaries, and annotates participant types — without modifying the original files.
Deprecation notice (see C1): The migrate operation has been absorbed into hierarchy-management --op migrate. Prefer calling hierarchy-management directly. This skill is retained for backward compatibility during the transition period.
Core Function
: Non-destructive upgrade of flat sequenceDiagrams to hierarchical boundary-box format
: and/or produced by any pre-Project 3 invocation of
: , , and
: Downstream of ; upstream of and
Migration record: per-diagram change summary, boundary suggestions, type inferences, and any warnings
Non-destructive guarantee: Original collaboration-diagrams.md and collaboration-diagrams.json are never modified. All additions are written to the *-enhanced.* counterparts.
Migration Workflow
Step 1 — Load Source Diagrams
1a. If collaboration-diagrams.json is present, parse it as primary source (authoritative participant list, requirement refs).
1b. If only collaboration-diagrams.md is present, parse the Mermaid sequenceDiagram blocks textually:
Extract participant <Alias> as <Label> declarations.
Apply the same inference rules as diagram-generatecollaboration §Participant Stereotype Classification. Evaluate in order; use the first matching rule:
Priority
Rule
Inferred type
1
Label contains User, Developer, Operator, Client, Owner, Human, Person, or Team
actor
2
Label contains API, Gateway, Interface, Service (AND does not contain DB, Store, Repository, Cache)
Label contains Framework, Workspace, Environment, Platform, System (not classifiable above)
control
6
No rule matched
control (fallback) — flag as INFERRED_FALLBACK in migration log
Record confidence level for each:
HIGH: Rules 1–3 (distinct label keywords)
MEDIUM: Rules 4–5 (structural keywords, some ambiguity)
LOW: Rule 6 (fallback) — note in migration log; human review recommended
Step 3 — Boundary Grouping Detection
Identify participant clusters that should share a box boundary in the enhanced diagram.
3a. Actor Exclusion
Participants inferred as actor type are placed outside all boundary boxes (they interact with the system; they are never enclosed).
3b. Automatic Boundary Clustering Rules
Apply in order:
Service Boundary: Group all control and entity participants whose labels share a common prefix word (e.g., AuthService, AuthDB → Auth Boundary).
Colocation Heuristic: If ≥ 2 non-actor participants send and receive messages only among themselves (a closed subgraph), group them into a single boundary.
Single-Entity Boundary: Any entity participant that exclusively receives messages from a single control participant is co-located in the same boundary as that control.
Ungrouped Fallback: Any non-actor participant not captured by rules 1–3 gets a singleton boundary named "<Label> System".
3c. Boundary Naming Convention
Boundary name: shared prefix word + " Boundary" (e.g., "Auth Boundary") or colocation grouping label.
Maximum 8 participants per boundary. If a candidate group exceeds 8, split by rule 2 (closed subgraph) first, then alphabetically.
3d. Box Color Assignment
Use the palette from diagram-generatecollaboration §Box Syntax Generation:
Boundary index
Color
1
rgb(230,240,255) — blue tint
2
rgb(230,255,230) — green tint
3
rgb(255,240,220) — orange tint
4
rgb(245,230,255) — purple tint
5+
rgb(240,240,240) — neutral grey
Step 4 — Build Enhanced Diagram Block
For each source diagram, produce an enhanced sequenceDiagram block:
### <Original Title> — Enhanced *(Diagram <id>-E)*
**Source Requirements**: <preserved from original>
**Entities Involved**: <preserved from original>
**Migration**: Enhanced from Diagram <id> on <ISO-8601 date>
```mermaid
sequenceDiagram
%% BOUNDARY SUMMARY
%% Boundary 1: <BoundaryName> — participants: <Alias1>, <Alias2>
%% Boundary 2: <BoundaryName> — participants: ...
%% Stereotypes: <ActorAlias>=actor | <Alias1>=<type>, <Alias2>=<type>
box rgb(nnn,nnn,nnn) "<BoundaryName>"
participant <Alias1> as "<Label1>"
participant <Alias2> as "<Label2>"
end
participant <ActorAlias> as "<ActorLabel>"
%% --- messages preserved verbatim from original ---
<all original message lines, alt/loop/note blocks unchanged>
**Preservation rules**:
- Every message line from the original must appear in the enhanced version unchanged.
- `Note over`, `Note left of`, `Note right of` blocks preserved verbatim.
- `alt/else/end`, `loop/end`, `opt/end`, `par/and/end`, `critical/option/end` blocks preserved verbatim.
- Only the `participant` declarations change (reordered by boundary grouping, annotations added).
---
### Step 5 — Preserve Requirement Traceability
For every `**Source Requirements**: [R-xxx]` line found in the source, copy it verbatim into:
- The enhanced markdown block header (Step 4).
- The `source_requirements` array in the enhanced JSON (Step 6).
No requirement reference may be omitted, reworded, or reformatted. If the source uses `[R-xxx]` notation, that exact notation is preserved.
---
### Step 6 — Generate Enhanced JSON
For each diagram, create an enhanced JSON object alongside the original:
```json
{
"diagram_id": "D-001-E",
"migrated_from": "D-001",
"title": "AI Skills Invocation Flow — Enhanced",
"source_requirements": ["R-019", "R-021", "R-023"],
"entities_involved": ["DeveloperTeamMember", "VSCodeWorkspace", "AIAgentSkill"],
"participants": [
{
"alias": "Dev",
"label": "DeveloperTeamMember",
"type": "actor",
"boundary": null,
"inference_confidence": "HIGH",
"inference_rule": 1
},
{
"alias": "VSC",
"label": "VSCodeWorkspace",
"type": "control",
"boundary": "Workspace Boundary",
"inference_confidence": "MEDIUM",
"inference_rule": 5
}
],
"boundaries": [
{
"name": "Workspace Boundary",
"color": "rgb(230,240,255)",
"participants": ["VSC", "Skill"]
}
],
"migration_metadata": {
"migrated_at": "<ISO-8601>",
"migration_tool_version": "1.0.0",
"mode": "apply",
"fallback_participants": [],
"boundary_count": 1,
"actor_count": 1,
"warnings": []
},
"messages": [ "...all original message objects preserved..." ]
}
Step 7 — Generate Migration Log
Write migration-log.md with the following sections:
# Migration Log**Generated**: <ISO-8601>**Source**: collaboration-diagrams.md / collaboration-diagrams.json
**Mode**: preview | apply
**Scope**: batch | diagram=<id>## Summary
| Metric | Value |
|--------|-------|
| Diagrams processed | N |
| Participants annotated | N |
| Boundaries added | N |
| Fallback (LOW confidence) participants | N |
| Warnings | N |
## Per-Diagram Results### D-001: AI Skills Invocation Flow-**Participants** (5 total): Dev → actor (HIGH), VSC → control (MEDIUM), Skill → control (MEDIUM), Output → entity (HIGH), Report → entity (HIGH)
-**Boundaries** (1): Workspace Boundary [VSC, Skill, Output]
-**Requirement links preserved**: R-019, R-021, R-023
-**Warnings**: none
...
Append any INFERRED_FALLBACK (LOW confidence) participant notices at the end under a ## Human Review Required section, with the participant alias, label, the diagram it appears in, and a suggested type.
Preview Mode
When --mode preview (default):
Run Steps 1–7 in full.
Print the migration log to the chat window / stdout.
Do not write collaboration-diagrams-enhanced.md, collaboration-diagrams-enhanced.json, or migration-log.md to disk.
Show the user a summary: "N diagrams ready for migration. N participants require human review. Run with --mode apply to write files."
--scope batch (default): Migrate all diagrams found in the source files in a single pass.
--scope diagram=<id>: Process only the diagram with the given diagram_id (e.g., D-001). Write or preview only that diagram's enhanced block. The *-enhanced.* files are created if they do not exist; if they already exist, only the targeted diagram's entry is updated (others preserved verbatim).
Integration Points
Skill
Relationship
diagram-generatecollaboration
Authoritative source for stereotype inference rules and box syntax. Migration-tools delegates classification logic to this skill's §Participant Stereotype Classification and §Box Syntax Generation sections.
hierarchy-management
Run after migration to decompose any control-type participant in the enhanced diagram into a sub-process hierarchy.
documentation-automation
Run after hierarchy-management to generate main.md, process.md, and fully annotated collaboration.md for each decomposed level.
edps-compliance
Run after migration to validate the enhanced diagram against VR-1–VR-4 boundary rules.
hierarchy-validation
Run after hierarchy-management decomposition to validate structural integrity.
Error Handling
Error
Code
Resolution
Source file not found
ERR_NO_SOURCE
Provide path to collaboration-diagrams.md or collaboration-diagrams.json
Diagram ID not found (individual scope)
ERR_DIAGRAM_NOT_FOUND
Check diagram ID against source; use --scope batch to migrate all
All participants of a diagram are actor type
ERR_NO_BOUNDARY_CANDIDATES
Review participation list; at least one non-actor participant required for boundary generation
Enhanced file already exists and --scope diagram=<id> would overwrite other diagrams
WARN_PARTIAL_OVERWRITE
Non-blocking; only the targeted diagram section is updated
> 50 % of participants in a diagram are LOW confidence
WARN_LOW_CONFIDENCE
Preview shows warning and lists participants needing review before apply
Validation Checklist (Post-Migration)
After --mode apply completes, verify:
collaboration-diagrams.md and collaboration-diagrams.json are unchanged (bit-for-bit).
Every **Source Requirements**: [R-xxx] reference from the original appears in the corresponding enhanced block.
No message lines are missing, reordered, or altered in content.
Every non-actor participant belongs to exactly one boundary box.
The migration-log.md lists every diagram processed and shows zero omitted requirement links.
If any LOW-confidence participants were noted, they are listed in the ## Human Review Required section of the log.
Usage Examples
Batch Preview (default)
Use migration-tools to preview migration of all Project 1 diagrams.
Source: OrgDocument/projects/01 - Building Skills/artifacts/Analysis/
Batch Apply
Use migration-tools --mode apply to migrate all Project 1 diagrams.
Source: OrgDocument/projects/01 - Building Skills/artifacts/Analysis/
Individual Diagram Enhancement
Use migration-tools --mode apply --scope diagram=D-003 to enhance only diagram D-003.
Source: OrgDocument/projects/01 - Building Skills/artifacts/Analysis/
Version: 1.0.0 Last Updated: 2026-03-15 Compatibility: EDPS v1.x, Project 3 boundary-diagram format Depends On: diagram-generatecollaboration (stereotype + box syntax rules) Unblocks: hierarchy-management, documentation-automation, edps-compliance
Migration path: This skill is superseded by hierarchy-management --op migrate (see hierarchy-management SKILL.md). This skill file is retained for backward compatibility. New projects should use hierarchy-management --op migrate directly.
