Build a model from source documents

Goal

Turn requirements or design documents into an ArchiMate and BPMN model with packages, elements, connectors and diagrams, and prove it by counting back and rendering. For an architect. You end with a model whose packages, elements, relationships and diagrams match an agreed plan, with counts checked against the repository and every diagram looked at.

Where it runs

This scenario needs the MCP server. Computer use covers its UI steps.

Before you start

• The start-of-session check done, with the target model confirmed (Start a session safely).
• The technologies the plan uses loaded and enabled. ArchiMate and BPMN ship with EA. Check that ArchiMate3 and BPMN2.0 are loaded. A technology that is disabled in Manage Technology still reads as loaded to EA itself, so ask for the runtime reading and look for a source of live, not registered but not enabled.
• The source documents in a place the AI can read.
• A target: a new model, or a new top-level package in an existing model. Do not build on top of content you have not looked at.
• A baseline of the target package, or of its parent, before the first write.
• Enough session budget. A large build is best split into one session per phase. Seed each session with a targeted question about the current state, not an open-ended request to describe the repository.

An architect holds a requirements document, an architecture description or a set of design notes, and wants a model, not a summary. The AI reads the documents, proposes a plan (the packages, which elements each layer holds, which relationships exist, which diagrams to draw), and waits for approval. It then builds in a fixed order so that each step has what it needs: packages, then elements, then connectors, then diagrams. A connector needs both endpoints to exist, and a diagram needs the elements and connectors it shows.

The build ends with verification against the plan, not against itself. A build that agrees with its own counts proves it is consistent, not that it is complete. The skill is ea-modeling, with ea-change-management for the baseline.

Steps

1. AI with computer use; otherwise you If EA is not running or the model is not open, start EA and open it. AI Power Tools ea-start-here runs the start-of-session check.

2. You Confirm the target model.

3. AI ea-modeling reads the documents and writes the plan: the package nesting, an element inventory by layer with technology and stereotype for each, the relationships, and the diagrams with their types. It also lists what the documents say that the plan leaves out, and why.

4. You Approve the plan. It is the customer-visible shape of the model, so it is yours to approve. Nothing is created before you agree.

5. AI Power Tools ea-change-management takes a baseline of the target. You decide whether to, for a target that already holds content.

6. AI Power Tools ea-modeling checks what already exists, by name, and records the id of anything found, so that a re-run skips it instead of duplicating it.

7. AI Power Tools ea-modeling creates the package hierarchy, parents before children, one at a time. Confirm the parent of each top-level package, and read back the stored name of any package whose name contains &, <, > or a quote.

8. AI Power Tools ea-modeling creates the elements in bulk (create_elements_bulk). For a stereotype from a technology, it names the technology and the stereotype, so the element type is resolved from the technology and the stereotype is bound to the profile. Tagged values are set in the same call. If a base element type is also named, AI Power Tools honors it and warns when it disagrees with what the stereotype expects. A bulk call skips an element whose name, package and stereotype already exist and reports the existing id.

9. AI Power Tools ea-modeling creates the connectors in bulk (create_connectors_bulk), using the relationship vocabulary of the technology you are modeling in. A connector is skipped as a duplicate only when type, stereotype and name all match. Connectors run from the client (source) to the supplier (target), so the direction of each relationship in the plan matters.

   A technology can declare connector stereotypes of its own, and the Westbrook illustration does: Uses, Flows and realizes, each with three tagged values (data flow classification, integration pattern and SLA tier). EA stores a connector's stereotype by its bare name, and a separate binding ties the connector to the technology. So a connector named Uses can be bound to WBA::Uses, bound to another language's Uses, or bound to nothing. Use the declared connector stereotype where one fits, and otherwise a plain connector type with no stereotype. To tie a connector to the technology, the AI sets the technology-qualified name. A connector created with only the bare name may not be bound to the technology, so check it (see Checking the result).

10. AI Power Tools ea-modeling creates each diagram with its technology binding, places the elements and connectors, applies a layout, and sets the diagram's note last, as one sentence saying what it shows.

11. AI Power Tools ea-modeling counts back against the plan: elements per package (list_package_tree), a stereotype tally that shows whether each stereotype is bound to a profile or ad hoc (summarize_stereotype_usage), elements with no connectors (find_orphan_elements), and a sample of tagged values.

12. You Look at every rendered diagram (verify_diagram, which reloads and renders). Elements stacked at the origin, a missing connector and a clipped label are all things a count cannot find.

13. AI ea-modeling corrects and re-verifies. You decide when a correction changes the plan.

14. AI ea-modeling reports what was built and what was left out.

Counts come from the repository, not from the AI's record of what it created.

Prompts to use

Opening

Follow-ups

Recommended models

Ratings are guidance based on the kind of reasoning the skill needs, not measured benchmarks.

Checking the result

• Accurate. Spot-check elements against the source documents: names, stereotypes, tagged values and the direction of relationships. A stereotyped element has its profile binding, and no element carries a stereotype that no loaded technology declares. A connector that carries a technology's connector stereotype is bound to that technology and not merely named the same. Where local code execution is available, the stereotype provenance census shows this for connectors as well as elements (Assess the language situation).
• Complete. Per-package element counts and total connector counts match the plan, or the report explains each difference. Every planned diagram exists, holds its planned elements, and shows its connectors. Elements with no connectors are only those the plan says may stand alone. Items the documents mention but the plan left out are listed.
• Nothing unintended changed. Comparing the model with the baseline from step 5 shows only the new content. Existing packages are unchanged.

Variations

• Build from a structured specification. The input is a machine-readable inventory: a package tree, each element with its stereotype and tags, the connectors, and the diagrams. The document-reading step shrinks to checking the specification. The build follows the same phases in strict order, ends with a verification report of element counts, and can run against a package that already exists without duplicating anything. A specification can mark some content as deliberately imperfect, such as an orphan element or an oddly named package kept to test governance. The build must not "correct" it, and the verification checks that it is there. Use this for a repeatable build, a demo, or a test model.
• Very large one-shot loads. For more than about 100 elements of plain catalog data, where local code execution is available, scripting inside EA is faster and costs no AI context. Seed with a script, then verify and refine through AI Power Tools. Up to about 30 elements, its bulk operations are the right choice.
• Add to an existing model. Skip the whole-model plan, run the existence check carefully, and build into a new package. See Protect a change with a baseline.
• Offer navigation diagrams. After a load that creates a hierarchy, the AI offers click-through diagrams. See Load a hierarchy and generate navigation diagrams.

Limitations

• Success is not persistence. A create reports that data was written, not that EA accepted every property. Look at the rejected-property and type-mismatch notes in each result.
• Stereotype binding depends on the technology being loaded and enabled. If it is not, an element can be created with a stereotype name and no profile binding. Check at the start, and check again with the stereotype tally.
• Creating a single technology-typed element does not accept tagged values. Set tags afterward, or create the element through the bulk operation.
• EA draws a relationship between two placed elements whether or not a stored link exists. Telling AI Power Tools not to write links does not stop EA from drawing them. Place with no automatic layout when a stored link would be wrong.
• The default layout is a start. An automatic layout of a large diagram is rarely presentable. Use Compose a diagram and Tidy and style a diagram.
• Moving a package is done in EA's own Browser window, a UI step that is AI with computer use; otherwise you. The move operation applies to elements only. An empty package with a wrong parent can instead be recreated.
• Member operations use different identifiers. See Model classes.