Manage updates to organizational model documents and folder structures. Updates orgModel hierarchy including process documentation, domain models, collaboration diagrams, and test cases based on requirements processing results and domain analysis outputs.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
orgmodel-update
description
Manage updates to organizational model documents and folder structures. Updates orgModel hierarchy including process documentation, domain models, collaboration diagrams, and test cases based on requirements processing results and domain analysis outputs.
license
MIT
OrgModel Update
Systematically manages updates to organizational model documents and folder structures based on analysis outputs from requirements processing and domain modeling.
Intent
Maintain the orgModel hierarchy with systematic updates to process documentation, domain models, collaboration diagrams, and test cases. Ensures organizational models remain current with evolving requirements while preserving existing content structure and maintaining cross-reference integrity.
Primary inputs: domain-alignment.json / domain-concepts.json from the project analysis phase.
Operates at: The orgModel process folder level (e.g., orgModel/01 - Skill Development Process/). Does not recurse into per-hierarchy-node sub-folders created by hierarchy-management.
Relative to documentation-automation
Skill
Trigger
Primary Input
Owns
documentation-automation
Hierarchy decomposition event
[folder]/collaboration.md
main.md, process.md, collaboration.md, domain-model.md at each EDPS hierarchy node
orgmodel-update(this skill)
Project analysis outputs
domain-alignment.json, domain-concepts.json
vocabulary.md, test-case-list.md (always); shared files only in non-hierarchy-managed folders
Ordering rule: Within a single process:
documentation-automation always runs after hierarchy-management decomposition and owns the four shared files in each hierarchy node.
orgmodel-update runs from project analysis outputs at the org-model process level.
If both skills target the same folder, documentation-automation takes precedence for the four shared files (main.md, process.md, collaboration.md, domain-model.md). orgmodel-update must not silently overwrite hierarchy-aware navigation, breadcrumbs, or box-syntax diagrams.
orgmodel-update always owns and updates vocabulary.md and test-case-list.md regardless of hierarchy status, as these files are not generated by documentation-automation.
# OrgModel Update Summary**Project**: [Project Name]
**Generated**: [ISO8601 timestamp]
**Process Model**: [NN] - [Process Name]
**Source Analysis**: [source file references]
## Changes Applied### Structure Updates- [ ] Created new orgModel folder: `orgModel/[NN] - [Process Name]/`- [ ] Updated existing structure with [N] new elements
- [ ] Preserved [N] existing elements
### Document Updates- [ ] **main.md**: [summary of changes]
- [ ] **domain-model.md**: Added [N] entities, [N] concepts
- [ ] **process.md**: Updated with [N] new activities/flows
- [ ] **collaboration.md**: Added [N] new interaction patterns
- [ ] **vocabulary.md**: Added [N] terms, aligned [N] existing terms
- [ ] **test-case-list.md**: Added [N] test cases, updated [N] existing
### Validation Results- [ ] Cross-reference integrity maintained
- [ ] Terminology consistency verified
- [ ] Process flow completeness validated
- [ ] Test coverage assessment completed
## Next Steps- Review updated orgModel for completeness
- Validate process flows with stakeholders
- Update dependent organizational models
- Schedule integration testing
Core Functions
1. OrgModel Structure Management
Create/Update Process Folder
orgModel/[NN] - [Process Name]/
├── main.md # Process overview with navigation
├── domain-model.md # Actors, systems, entities from domain analysis
├── process.md # Process flows, activities, decision points
├── collaboration.md # Entity interactions and sequence diagrams
├── vocabulary.md # Canonical terminology mapping
├── test-case-list.md # Comprehensive test case registry
└── test-cases/ # Individual test case files (if testing required)
└── tc-[proc-id]-[sequence].md
Numbering Convention: Use next available NN sequence number in orgModel folder structure
2. Content Generation Patterns
main.md Structure
<!-- Identifier: I-[NN] -->
# [NN] - [Process Name]## Purpose
[Business purpose derived from requirements analysis]
## Process Flow
See [process.md](process.md) for detailed activity diagram.
## Collaborations
See [collaboration.md](collaboration.md) for entity interactions.
## Domain Model
See [domain-model.md](domain-model.md) for actors and entities.
## Sub-Processes
[List nested processes identified from analysis]
## Test Coverage
See [test-case-list.md](test-case-list.md) for verification test cases.
## Related Changes
<!-- Traceability to source requirements and changes -->
domain-model.md Structure
<!-- Identifier: DM-[NN] -->
# Domain Model: [Process Name]## Actors
[Human and system actors from domain analysis]
### [Actor Name]-**Type**: Human/System/External
-**Responsibilities**: [key responsibilities]
-**Interactions**: [primary entity interactions]
## Key Entities
[Business entities from domain concepts extraction]
### [Entity Name] -**Definition**: [entity definition]
-**Attributes**: [key attributes]
-**Relationships**: [entity relationships]
-**Domain Area**: [functional area]
## Systems and Components
[Technical systems involved in process]
### [System Name]-**Purpose**: [system role]
-**Interfaces**: [external connections]
-**Key Functions**: [primary capabilities]
process.md Structure
<!-- Identifier: P-[NN] -->
# Process: [Process Name]## Overview
[Process purpose and scope]
## Process Flow```mermaid
flowchart TD
A[Start] --> B[Activity 1]
B --> C{Decision Point}
C -->|Yes| D[Activity 2]
C -->|No| E[Activity 3]
D --> F[End]
E --> F
Activities
[Activity Name]
Input: [required inputs]
Process: [activity description]
Output: [produced outputs]
Responsible: [actor/role responsible]
Validation: [quality checks]
Decision Points
[Critical decision points with criteria]
Exception Handling
[Error conditions and recovery procedures]
#### collaboration.md Structure
```markdown
<!-- Identifier: C-[NN] -->
# Collaboration: [Process Name]
## Entity Interactions
```mermaid
sequenceDiagram
participant A as Actor
participant S as System
participant D as Data Store
A->>S: Request
S->>D: Query
D-->>S: Response
S-->>A: Result
Interaction Patterns
[Description of key interaction patterns]
Communication Channels
[How entities communicate]
Data Flow
[Information flow between entities]
#### vocabulary.md Structure
```markdown
<!-- Identifier: V-[NN] -->
# Vocabulary: [Process Name]
## Canonical Terms
[Standardized terminology for the process]
| Term | Definition | Aliases | Context |
|------|------------|---------|---------|
| [Term] | [Definition] | [Synonyms] | [Usage context] |
## Domain Alignment
[Mapping to enterprise domain models]
## Consistency Rules
[Guidelines for term usage across process]
test-case-list.md Structure
<!-- Identifier: TCL-[NN] -->
# Test Case List: [Process Name]## Test Coverage Overview
[Summary of testing scope and approach]
## Test Cases
| TC ID | Test Category | Title | Priority | Source Requirement |
|-------|---------------|-------|----------|-------------------|
| tc-[NN]-001 | Functional | [Test title] | High | R-[ID] |
## Test Categories-**Functional**: Core process functionality
-**Integration**: Cross-entity interactions
-**Exception**: Error handling and recovery
-**Performance**: Process efficiency measures
-**Compliance**: Regulatory/standards adherence
## Validation Criteria
[Process success criteria for testing]
3. Content Update Logic
Preservation Strategy:
Maintain existing content structure and identifiers
Add new elements without disrupting existing cross-references
Preserve manual customizations and annotations
Update metadata and change tracking
Integration Patterns:
Merge new domain entities with existing domain models
Append new process activities to existing flows
Integrate new collaboration patterns with existing interactions
Add new terminology while maintaining consistency
Extend test coverage without duplicating existing cases
Domain Model Updates with Class Diagrams
When updating domain-model.md, this skill now integrates with diagram generation:
Class Diagram Integration Process
Extract existing entities from textual domain model descriptions
Apply alignment results from domain-alignentities skill
Generate/update class diagram reflecting aligned domain structure
Embed diagram in domain-model.md following organizational patterns
Sync diagram with textual descriptions to ensure consistency
domain-model.md Enhanced Structure
<!-- Identifier: D-[NN] -->
# [Process Name] Domain Model## Domain Class Diagram```mermaid
classDiagram
class Entity:::category {
+attribute: Type
+operation()
}
Entity --> RelatedEntity
%% Styling Definitions
classDef actor fill:#e1f5fe
classDef entity fill:#f3e5f5
classDef enum fill:#fff3e0
classDef ai fill:#e8f5e8
Actors
[Textual descriptions of actors shown in diagram]
Core Entities
[Textual descriptions of entities with attributes and operations]
Key Relationships
[Textual descriptions of relationships shown in diagram]
#### Diagram-Text Synchronization
- **Entity alignment**: Ensure diagram entities match textual descriptions
- **Attribute consistency**: Sync diagram attributes with detailed attribute lists
- **Operation alignment**: Match diagram operations with described behaviors
- **Relationship validation**: Verify diagram associations match textual relationships
- **Styling consistency**: Apply organizational diagram styling standards with proper classDef definitions
- **Style preservation**: Maintain standard organizational colors (actor: #e1f5fe, entity: #f3e5f5, enum: #fff3e0, ai: #e8f5e8)
### 4. Validation and Integrity Checks
**Integration with Diagram Generation**:
- **Trigger diagram updates** when domain alignment results indicate changes
- **Coordinate with diagram-generatecollaboration** skill for class diagram generation
- **Maintain diagram version consistency** across organizational models
- **Preserve custom diagram styling** and layout preferences
- **Ensure styling definitions included** - All class diagrams must include classDef statements for proper rendering
- **Validate diagram syntax** - Check that both inline styling (:::category) and style definitions (classDef) are present
**Cross-Reference Validation**:
- Verify all internal links to process documents remain valid
- Ensure terminology consistency across all orgModel files
- Validate entity references between domain model and collaborations
- Check test case traceability to source requirements
**Structure Integrity**:
- Confirm file naming conventions compliance
- Validate Mermaid diagram syntax in process.md and collaboration.md
- Ensure required sections present in all core files
- Verify identifier uniqueness across orgModel structure
**Content Consistency**:
- Align terminology with vocabulary.md across all files
- Ensure actor consistency between domain-model.md and collaboration.md
- Validate process flow completeness and logical consistency
- Check test case coverage against identified process activities
### 5. EDPS-Hierarchy Guard
> **Purpose**: Prevent `orgmodel-update` from silently overwriting hierarchy-aware content (breadcrumbs, Sub-Processes tables, box-syntax diagrams) that was generated or managed by `documentation-automation`.
#### Guard Algorithm (run before writing `main.md`, `process.md`, `collaboration.md`, or `domain-model.md`)
1. For each target orgModel folder, search for `hierarchy-metadata.json` in:
- The folder itself
- Up to 3 ancestor levels within `orgModel/` (e.g., `../`, `../../`, `../../../`)
2. **If `hierarchy-metadata.json` IS found** → folder is EDPS-hierarchy-managed:
- **Do NOT generate** `main.md`, `process.md`, `collaboration.md`, or `domain-model.md` directly.
- Instead, write all proposed additions (new domain entities, aligned concepts, process notes) to `[folder]/pending-orgmodel-updates.md` using the format below.
- Log a recommendation: *"Re-run `documentation-automation` with the updated `domain-concepts.json` as context to incorporate these changes into the hierarchy-managed files."*
- **Exception — `--force-overwrite` flag**: When `orgmodel-update` is invoked with `--force-overwrite`, skip the guard and overwrite all files unconditionally. Use only for deliberate full regeneration in controlled workflows.
3. **If `hierarchy-metadata.json` is NOT found** → generate all files normally per existing behavior.
4. **Exempt files** — `vocabulary.md` and `test-case-list.md` are **always updated directly** regardless of guard outcome (step 2 or 3). These files are not generated by `documentation-automation`.
#### `pending-orgmodel-updates.md` Format
```markdown
# Pending OrgModel Updates
**Folder**: `orgModel/[NN] - [Process Name]/`
**Generated**: [ISO8601 timestamp]
**Source Analysis**: [path to domain-concepts.json and/or domain-alignment.json used as input]
**Guard Triggered By**: `hierarchy-metadata.json` found at `[path]`
> ⚠ This folder is managed by an EDPS hierarchy. The four shared files (`main.md`, `process.md`,
> `collaboration.md`, `domain-model.md`) were NOT overwritten. Apply the additions below manually,
> or re-run `documentation-automation --force` with the domain-concepts.json listed above as context.
## Proposed Additions
### New Domain Entities
| Entity | Definition | Domain Area | Source |
|--------|------------|-------------|--------|
| [EntityName] | [definition] | [area] | [source file ref] |
### New Vocabulary Terms
| Term | Definition | Aliases | Context |
|------|------------|---------|----------|
| [Term] | [definition] | [synonyms] | [usage context] |
### Process Notes
- [Any process flow additions or clarifications from the analysis]
## Human Action Required
- [ ] Review proposed additions above
- [ ] Merge applicable entities into `domain-model.md`
- [ ] Merge applicable terms into `vocabulary.md` (or confirm auto-update is sufficient)
- [ ] Re-run `documentation-automation` if structural changes to `process.md` or `collaboration.md` are needed
- [ ] Delete this file once all items are resolved
Usage Guidelines
Typical Workflow
Analyze Input: Process domain concepts, alignment results, and collaboration diagrams
Identify Target: Determine orgModel process (existing or new) for updates
EDPS-Hierarchy Guard Check(before any shared-file generation): For each target orgModel folder, run the guard algorithm in §Core Functions → §5 EDPS-Hierarchy Guard before writing main.md, process.md, collaboration.md, or domain-model.md. vocabulary.md and test-case-list.md are always updated — skip the guard for those files.
Structure Update: Create/modify orgModel folder structure as needed (only if not blocked by guard in step 3)
Content Integration: Update each core file with new elements, preserving existing content
Validation: Run integrity checks and cross-reference validation
Summary Generation: Document all changes and validation results
Integration Points
Domain Analysis: Incorporates entities and concepts from domain extraction
Process Modeling: Integrates with collaboration diagram generation
Requirements Traceability: Maintains links to source requirements
Change Management: Documents updates for organizational tracking
Testing Integration: Provides test case foundation for validation activities
Confirm terminology alignment with enterprise standards
Related Skills
Skill
Relationship
documentation-automation
Upstream / higher precedence for shared files. Triggered by hierarchy-management decomposition; owns main.md, process.md, collaboration.md, domain-model.md in hierarchy-managed folders. orgmodel-update defers to documentation-automation for those files when hierarchy-metadata.json is present. See documentation-automation/SKILL.md for its scope.
domain-extractconcepts
Provides domain-concepts.json — the primary input for this skill
domain-alignentities
Provides domain-alignment.json — the secondary input for entity alignment
diagram-generatecollaboration
Provides collaboration-diagrams.json; also validates EDPS boundary rules referenced in collaboration.md updates
hierarchy-management
Creates folder structure and hierarchy-metadata.json; presence of that file activates the EDPS-Hierarchy Guard in this skill
Configuration Options
Process Identification
Auto-numbering: Automatically assign next available orgModel sequence number
Manual numbering: Use specified process number for updates
Name mapping: Map requirements/domain areas to existing process models
Update Mode
Incremental: Add new elements to existing orgModel content
Refresh: Regenerate orgModel content while preserving customizations
Merge: Combine multiple analysis sources into single orgModel update
Validation Level
Basic: File structure and syntax validation
Standard: Cross-reference and consistency checking
Comprehensive: Full integrity validation with dependency analysis
Dependencies: domain-extractconcepts, domain-alignentities, diagram-generatecollaboration
Integration: GitHub Copilot, VS Code environment, EDPS skill framework, Mermaid class diagram generation
Maintenance: Update templates based on organizational model evolution
Diagram Support: Automatic class diagram generation and synchronization with textual domain models
