Specman 1.4 Manual

Since version 1.3, the diagram files have a pseudocode-like format which makes them machine-readable e.g. to feed code generators or AI agent based programming pipelines. The file structure follows an EBNF grammar defined in SpecmanModel_V002.g4, which is part of the delivery. It is explicitly designed to also integrate AI support in the process of creating specifications. Using Specman’s autoload mode and its headless sanitizer makes it possible to set up a collaborative environment where the user is working with the WYSIWYG UI while an AI agent is supporting in the background. Specifications are supposed to be designed as both human-readable and technically exact, using a natural but precise language according to basic clean code development principles and the central ideas of Domain-Driven Design. The result is a document with structure and textual content which is perfectly understandable for AI agents.

Specman provides a high-quality PDF export, so that the diagrams can be shared easily with everyone involved in the software engineering process. Reviewers only need a standard tool like Adobe’s Acrobat Reader to open and comment on the exported diagrams. See anagramms-export.pdf for an example of a PDF export of the "Anagrams" diagram.

The yellow highlighting in the screenshot above indicates changes which were made in change mode. Similar to Microsoft Word, e.g. deleting text in change mode does not actually remove the text; instead, it is displayed as struck through with a yellow background as if someone had marked the section with a text marker. Changes in a model are therefore immediately recognizable by everyone. This is a crucial aspect in iterative development where specifications evolve over time.

Folding up a structured step which includes any change marks will cause the unfold-button beside the step number to be displayed in the highlight color of the hidden changes. I.e. even if details are hidden, it is still visible that there are changes in the folded up section.

Since version 1.2.1, Specman supports multiple change sets, which is of interest e.g. if there are multiple change requests to be considered in parallel within a single development iteration.

To get an idea of what real-world specifications look like in Specman, see the bird’s view on a mid-size system usecase specification from ongoing project development.

Creates a simple step in the diagram. The new step is immediately focused, i.e. pressing the button multiple times creates multiple steps one after the other.

Creates a subsequence of steps with an initial simple step immediately added within. Subsequences are not part of original Nassi-Shneiderman diagrams. They bring structure into larger sequences like chapters in a book. These substructures may be directly used as a reasonable indicator for how to structure the code when implementing the specification.

The steps within the subsequence are numbered on a lower level, e.g. step 2.1, 2.2, 2.3 within subsequence step 2.

Subsequences can be folded up to hide their content when the details are currently not of interest. Moving the mouse just to the right of the subsequence’s step number brings up a small button with a minus sign. Pressing this button folds up the subsequence. The button then shows a plus sign for unfolding the subsequence again.

Creates a loop step with an initial simple step in its repetition sequence immediately added. The repetition sequence must not be empty. So if the first step needs to be something other than a simple step, add a step of the required type and remove the initial first step afterward.

Creates a loop step with an additional horizontal empty bar at the bottom. This is functionally identical with the loop step, but sometimes the extra bar makes the lower boundary of the loop easier to recognize. E.g. if there are catch steps at the end of the loop’s repetition sequence.

Creates an if-else step with an initial simple step in its if and else branches. The division ratio of the branches may be changed by clicking on the separating line between the branches and moving it right or left.

Creates an if step. Unlike the if-else step, the left branch is empty and its width cannot be modified.

Creates a case step with the default branch on the left and two other initial case branches on the right. Additional branches can be added by pressing the corresponding button from the steps creation toolbar (see below). Branch removal is achieved by placing the cursor in the branch’s heading or condition edit area and pressing the delete button from the step & document properties toolbar. However, two case branches and the default branch are the minimum which a case step has to provide. Otherwise it’s an if or if-else step.

Creates a new branch in a previously created case step. The creation by button click requires placing the cursor into an existing branch’s heading edit area first. The new branch is then added left from the cursor-selected branch. Alternatively the new branch can be created by drag & drop which requires dragging into an existing branch’s heading. A vertical insertion bar indicates where the new branch will be created when releasing the mouse button.

Creates a break step which can be understood as the occurrence of a business exception. It causes the following steps to be skipped down to the place where the exception gets caught. If it is not caught anywhere the exception causes the complete usecase to be aborted which is described in the diagram. However, this is usually not a good idea as it makes the reader wonder if this was designed by intention or if the design is not yet complete.

There are two flavours for using break steps: The compact form is the one being used in the anagram example: The preceding step describes some system functionality and the break step simply mentions an exceptional situation which may occur in the step before. An appropriate check for the situation is implicitly assumed to be included in the described functionality. The more comprehensive form includes a preceding step which explicitly consists of nothing else but the check for a particular exceptional situation where the break step(s) then expresses the abortion of the step sequence in case the situation is present. This form is recommended, if the situation takes some more text to be described or if it is of particular importance in the overall context. The actual system functionality is then described in a step following the break step(s).

Creates a catch step for a previously defined break step. Unlike all other steps, it is not just inserted at the drop position: the creation takes the following steps, no matter whether the button is pressed or dragged into the diagram.

If a development project is working with a programming language that supports exceptions, it is strongly recommended to represent break and catch by throwing and catching exceptions in the code. In this case, it is a good idea to use relatively short expressions in the break step text, from which exception type names can be directly derived.

Catch steps are displayed in visually separated sections with a gray bar above and below, making it clear that they are not part of the normal control flow. Multiple catch steps for the same sequence are placed side by side, each with its own handling sequence below its heading. New catch steps are appended on the right. Right-clicking the step number of a catch heading brings up a context menu with Move left and Move right to change the order, and the widths of the catch steps can be changed by dragging the dividers between them. As in loops, the handling sequence must not be empty, i.e. its last step cannot be deleted.

A single catch step can also handle several break steps, just like catch (A | B e) in Java. The additional break steps are called co-catches. To add one, place the cursor in the heading of the catch step and press the catch step button, or drop the button onto the heading. The dialog then adds the chosen break step as a co-catch of this catch step instead of creating a new one. The headings of co-catches are stacked below the main heading, and each heading is coupled with its own break step, whose text it shows. A co-catch can be moved up and down among the other co-catches by the context menu of its step number.

Pressing the Ctrl key while clicking the step number of a break step jumps to the heading of its catch step. The same works the other way round, from the catch heading to the break step.

Deleting works as follows, using Delete from the step number’s context menu:

The catch area can be folded up like any other structured step. The button for this is on the right of the gray bar above the catch area. It shows up when you move the mouse there, and stays visible as long as the area is folded.

Text formatting is based on an HTML subset. However, Specman is a WYSIWYG editor, so you never have to deal with HTML source code when using the UI. The toolbar and the menus work like in a word processor, and what they offer is what HTML offers: paragraphs with a paragraph style (body text, headings, block quotes, preformatted text), character styles, font, size, color and alignment. The text is saved as HTML in the diagram file, together with a plain text rendition for tools which don’t want to deal with HTML like full text search in IDEs.

HTML is used for text formatting only. Lists, images and tables are not part of the text content, even though HTML could express them. In Specman they are independent building blocks of the step content, each being an edit area of its own, see Lists, Tables and Images. This allows Specman to render them better than a plain HTML component could, and, above all, to track changes at a much finer granularity (see Change Tracking). An added list item, a removed table row or a deleted image is marked individually instead of marking a whole text as changed.

Formatting is done with the formatting toolbar above the diagram and the menus Edit, Format and Insert. The toolbar provides familiar options such as bold, italic, underline, font, size, color and alignment, plus the paragraph style box. The Format menu has even more character styles, e.g. subscript and superscript. Strikethrough and text background colors are missing on purpose: they are reserved for the markings of change mode, see Change Tracking.

Pasting with Ctrl+V depends on where the content comes from:

Complete steps are copied, cut and pasted using the step context menu rather than operating on text content, see Moving, copying and deleting steps.

The toolbar buttons for unordered and ordered lists turn the paragraph at the caret into a list item. Text before and after it stays what it was. Pressing Enter splits the item at the caret. Pressing Backspace at the start of an item dissolves it back into plain text, which is also the way out of a list: Enter in an empty item just creates the next empty item. Pressing one of the list buttons within an item dissolves it as well.

A list item can contain more than text, e.g. images and tables. Lists cannot be nested yet.

The table button of the formatting toolbar allows to add a table at the caret position of a text. Cells can contain the same things as a step, i.e. texts, lists, images, and tables. There is no header row and no formatting of the table itself.

The structure of a table is edited with the mouse in the thin margin around it:

Hovering over such a spot highlights it and changes the mouse cursor, and a click executes the action. While the mouse is over the top left corner, Ctrl+C, Ctrl+X and Delete copy, cut and delete the table.

In a cell, Tab moves to the next cell, and Tab in the very last cell appends a row. Column widths are changed by dragging the dividers between the columns. The divider at the right edge of the table changes the width of the entire table. Pressing Esc while dragging cancels the change.

The image button of the formatting toolbar opens a file chooser for JPG, PNG, GIF, BMP and SVG files. Alternatively, a bitmap can be pasted from the clipboard (see above). A bitmap is embedded in the diagram file as a PNG, so the original file is no longer needed.

An SVG file is embedded as its source text instead, so it stays a vector graphic, sharp at any zoom factor and in the PDF export as well. SVG graphics cannot be edited in Specman. Specman displays only what its SVG renderer supports. A file which cannot be displayed is refused with a message naming the reason.

Clicking an image selects it. Delete or Backspace removes it, and Ctrl+C or Ctrl+X copies or cuts it. To continue typing below the image, press Enter. Dragging the narrow bar at the right edge of the image changes its size. An image is never wider than the diagram, and its size follows the zoom factor.

If you insert images to illustrate model structures like domain class diagrams, see chapter Class diagrams with PlantUML for a better alternative.

Step links are links to other steps within the text, like "see step 2.3". They are inserted with the step link button of the formatting toolbar, or by Insert > Link to Stepnumber…​. The dialog lists all steps by number and the beginning of their text. A filter field narrows the list, and a click on an entry inserts the link at the caret.

A step link is displayed as the step number on a light gray background. It behaves like a single character: you cannot type into it, the cursor jumps over it, and Backspace removes it entirely. If it needs to point somewhere else, remove it and insert a new one.

The number in a step link follows its step automatically when the numbering changes. If the step is deleted, the link remains with a question mark behind the number, e.g. 2.3?. Deleting a step which is the target of a link causes a confirmation message to appear.

Ctrl+click on a step link scrolls to the step it points to. Ctrl+Alt+Left goes back to where you came from, and Ctrl+Alt+Right forward again.

A hyperlink is text which leads somewhere else: to a web page, a mail address or another Specman document. Hyperlinks are displayed in blue and underlined. For links to steps within a document, step links are the better choice, as they follow the numbering.

Insert > Hyperlink…​ or the hyperlink button of the formatting toolbar opens a dialog for the link text and the URL. Selecting text before opening the dialog makes the text the link text. To change a link later, put the caret into it and choose Format > Hyperlink Properties…​, which opens the same dialog.

Ctrl+click follows a link. While Ctrl is pressed, the mouse cursor over a link turns into a hand, and a tooltip says what to do. A click without Ctrl just places the caret, so link texts can be edited like any other text.

The following link types are supported:

The PDF export draws hyperlinks in blue and underlined as well. They are not clickable there.

To move a step, press the mouse button on its step number, keep it pressed, move the mouse to the new place and release it. As when creating steps by drag & drop, a half-transparent gray insertion bar shows where the step will be placed. The step takes its entire content with it, nested steps included, and gets a new step number. It stays the same step, so links to it stay valid and the displayed step number is automatically updated.

Some steps cannot be dragged: the only step of a sequence (because a sequence must not be empty), steps marked as deleted, and the placeholders which change mode leaves behind at the old position of a moved step. A step cannot be dropped into itself either.

In change mode, a move is tracked as a move, see Change Tracking.

Delete from the step number’s context menu removes the step including everything inside. The last step of a sequence cannot be deleted. If the step is the target of a link, Specman asks for confirmation, and the links are marked as defective once the step is actually removed, see Step links. In change mode, the step is marked as deleted instead of removed, see Change Tracking. For catch steps, see above.

Copy puts the step including everything inside onto the clipboard. Cut does the same and deletes the step afterwards, with the rules of Delete above. Paste inserts the clipboard content as a new step directly below the step whose menu was used, in the same sequence. For a structured step this means below the entire step, not inside it. The items are disabled for steps marked as deleted and for catch steps.

Cutting is not the same as moving: the links to the cut step become defective, and in change mode it shows up as a deletion at the old and an addition at the new position, instead of one move. If the only reason for cutting is a different place within the same diagram, drag & drop is the better choice. It is also the safer one for steps containing break steps. If the catch sequence of such a break step is not part of the cut step itself, cutting removes the catch sequence with all its handling steps. Specman warns before doing so.

Pasting works across diagrams, and also between two Specman windows. What happens to the change marks of the pasted step depends on where it comes from:

For the handling of meta tags in pasted steps, see the section Copy & Paste in the chapter Meta tags.

The clipboard content of copied steps is also available as plain text in the file format of the diagram, so steps can be pasted into any text editor, mail or AI chat. The other way round, steps written in this format can be pasted into a diagram. If the clipboard content doesn’t parse, Specman reports that it cannot be pasted as a step.

Change tracking is switched on and off with the toggle button Track changes in the diagram toolbar:

While the button is pressed, Specman is in change mode: every edit is tracked and highlighted in the color of the current changeset (see below). Otherwise Specman is in normal mode and edits are applied without any tracking. Whether change mode is on and which changeset is selected is saved with the diagram, so it is restored when you open the file again. A new diagram starts in normal mode.

Deleting something in change mode doesn’t remove it, but marks it as deleted, so that the reader can see what is going to disappear. The exception is content which was itself added in change mode: it carries no history worth keeping, so deleting it simply removes it.

In change mode, the following modifications are tracked:

Not tracked are meta tags (see below), shading, the fold state of steps and the order of case branches and catch areas.

Added text has a background in the changeset color, added steps a pale panel in that color. Deleted text is struck through on a background in the changeset color. A deleted step gets a panel in the changeset color, a black step number tab and light-gray, struck-through text on black.

Moving a step leaves a placeholder behind at its old position: a black-tabbed step with empty content, and a step number label like 2 > 5 ("moved from 2 to 5"). At the new position, the step carries the changeset color and the label 5 < 2 ("came from 2"). It’s all one move, so accepting or rejecting it always takes care of both places.

If a folded step contains changes, its unfold button is displayed in the color of the changeset to which the first hidden change belongs. So even a folded step shows that there is something to look at, and by which changeset.

Sometimes more than one set of changes is in the air: several change requests being considered in parallel within one iteration, or changes of changes in a multi-loop coordination, where each round of feedback should be recognizable on its own. For this, Specman provides changesets. Each changeset has its own color, and all of them are displayed at the same time.

There are five changesets, which are predefined and cannot be changed or extended yet: yellow, lilac, blue, orange and pink. The colors were chosen to remain distinguishable for people with most kinds of color vision deficiency.

The current changeset is the one which new changes are assigned to. It is chosen in the Change Set dropdown, and it is recognizable at any time by the colored dot and by the background color of the dropdown. Accepting, rejecting and merging, as described below, always refer to the current changeset only.

The toolbar buttons Accept changes and Reject changes accept or reject all changes of the current changeset in the entire diagram, including intro and outro. Changes of other changesets are not touched. There is no way of accepting or rejecting changes selectively yet, e.g. for a single step.

Accepting makes the changes part of the specification: added content loses its marking and deleted content is actually removed. A moved step stays at its new position and the placeholder at the step’s original position disappears.

Rejecting does the opposite: added content is removed, deleted content is restored, and moved steps return to their old position.

Both operations are a single undo step.

The toolbar button Merge change sets pulls the changes of another changeset into the current one:

Pressing the button opens a list of all changesets except the current one. The changes of the one you choose are recolored into the current changeset, which makes it the target of the merge. This is typically the consolidation step at the end of a multi-loop coordination: the outcome gets merged into a single changeset, which is the basis for development and testing. Merging can be undone.

Even with only a few changes, they can be hard to find in a large diagram. The toolbar button Collapse for review folds up all structured steps which contain no changes, so that only the parts of the diagram remain open which are worth a reviewer’s attention.

The configurations of a diagram are managed in the dialog which is opened by choosing Meta Tags…​ from the File menu. Alternatively, you can reach it from a step number’s context menu, see below. The dialog lists all configurations of the diagram. Pressing New…​ creates a configuration, Edit…​ changes the selected one (a double click on a list entry does the same), and Delete removes it.

Most of the dialog for creating or editing a configuration is self-explanatory, and the preview shows what the tags will look like. The name is how the tags at steps refer to their configuration. It must be unique in the diagram, may only consist of letters, digits and underscores, and cannot be changed once tags use the configuration. The label is the text displayed in the tags of this configuration, if any. Either a label or an icon must be provided. The icon comes from an SVG file and is embedded in the diagram file, so the original file isn’t needed any more. A border is optional and off by default, and the freetext option is on by default.

Changes to a configuration take effect immediately in all tags which refer to it. Deleting a configuration also removes all tags which refer to it. If there are any, Specman asks for confirmation first. Creating, changing and deleting a configuration can be undone and redone like any other operation. The configurations are saved with the diagram, i.e. every diagram has its own set of configurations.

To attach a tag to a step, right-click the step number and choose the configuration of the tag from the Tags submenu. The menu items show the icon and label of the configurations (or their name if they have no label). Configurations for which the step already has a tag are grayed out, as a step can only have one tag per configuration. The submenu’s last entry Configure…​ opens the dialog for managing the configurations, so a missing configuration can be created without going back to the File menu.

The first tag attached to a step hangs directly to the left of the step number, the next one to the left of that, and so on. If the step has a fold button, it is always located to the left of the last tag. This is deliberate, because the fold button is only visible while the mouse is hovering over its location. If a step is too narrow to show all of its tags, the tags farthest to the left are cut off.

Tags can be attached to every step that has its own step number, with these exceptions:

Attaching and removing tags is not part of change tracking: it is not marked as a change, and works the same way in change mode and normal mode.

Each tag has its own context menu, brought up by right-clicking the tag:

The order of tags can also be changed by dragging a tag with the mouse. A vertical line shows where the tag will end up when the mouse button is released.

Right-click the number label of a step and choose Copy Link from the context menu. The URL is in the clipboard now, ready to be pasted into a ticket, a source code comment or the URL field of a hyperlink in the text of another diagram (see Hyperlinks). The menu item is grayed out as long as the diagram hasn’t been saved, because there is no file to address yet.

The first time you copy a URL to a file, Specman asks for an alias for it.

The reason for aliases: a path is different on every computer, so a URL with a path only works for the one who copied it. An alias is the same for everybody. Each team member tells Specman once, on their own computer, which file the alias stands for, and the same URL works for all of them.

The dialog shows the resulting URL while you type. An alias consists of letters, digits, underscores and hyphens, has up to 20 characters, and must be unique regardless of letter case. Specman proposes an alias if the aliases of other files in the same directory show a pattern which fits the new file name. E.g. if you have uc730 for CRM UC-730 Delete Customer.nsd, it proposes uc135 for CRM UC-135 Send Newsletter.nsd. If you leave the alias empty, URLs to this file contain its path. Both an alias and an empty alias are remembered, so the dialog doesn’t come up again for this file.

File > Aliases…​ lists the aliases you have so far, together with their files. A double click on an alias edits it, a double click on a file chooses another file, which you need when a file has moved or was renamed. Files which don’t exist any more are marked as missing. Delete removes the selected row, after which Specman asks for an alias again the next time you copy a URL in that file. Nothing is stored before you save, and saving is only possible while the aliases are unique. The list can also be opened with the All…​ button of the alias dialog.

There are three ways to follow a URL:

If the file of the URL is the one shown in the window, Specman scrolls to the addressed step, and Ctrl+Alt+Left takes you back to where you came from, as with step links. If the URL refers to a different file, it depends on the way you follow it: Ctrl+L loads the file into the window, after asking whether to save unsaved changes, while a hyperlink opens it in a new Specman window, because a window shows only one diagram.

If the alias of a URL is unknown in your user settings, Specman asks which file it stands for, and remembers the answer. A file chooser opens, with a file preselected if the other existing aliases allow a suggestion.

If you installed Specman with the Windows installer, the specman:// protocol is registered with the operating system. This makes it possible to follow a Specman URL, e.g. by pasting or typing it into the address field of Windows Explorer or a web browser. If you use the portable bundle, check your operating system’s documentation on how to register the protocol yourself.

Specman’s command-line interface provides the operation --resolve-link for two reasons:

The resolver is started with the same launchers as the sanitizer (see The sanitizer), e.g.

Without URLs as arguments it reads them from standard input, one per line, so other tools can feed it.

The output has exactly one line per URL, in the same order. Each line consists of three fields, separated by a tab (so it can be pasted into a spreadsheet): the status, the file the URL leads to, and a detail. The status is

The exit code is 1 if at least one line is an ERROR, otherwise 0. Aliases are taken from the settings of the user who runs the command.

The PlantUML button next to the image button of the formatting toolbar (or Insert > PlantUML diagram) adds a PlantUML diagram at the caret, just like an image.

A file chooser lets you pick an existing file with PlantUML source. The source is taken over into the diagram, so the original file is not needed afterwards (but see Includes below). The Empty diagram button of the dialog starts with an empty diagram and opens a PlantUML source editor right away. Pressing Esc before having entered any content removes the diagram again.

A double click on the diagram, or selecting Edit from its context menu, opens an editor for the source next to the diagram.

The screenshot shows this source:

The diagram does not follow while you type. It is updated by F5 in the editor and when the editor is left. This is deliberate: most intermediate states while typing result in unusable diagrams, even if the source conforms to the PlantUML syntax. For example, a half-typed relation to a class which does not exist yet makes PlantUML create that class implicitly, so the diagram would be rebuilt with every keystroke.

The line below the text shows the F5 hint or, as long as the source has a problem, PlantUML’s message with the line number. The editor can only be left with source which PlantUML accepts. A click elsewhere or Ctrl+Enter takes the source over, Esc discards your changes.

Specman has four rules in addition to the PlantUML syntax:

The context menu of the diagram has two more items: Import…​ replaces the source by the content of a file, with the same rules as above, and Delete removes the diagram. Selecting, deleting, copying and resizing work as described for images, see Images.

Larger projects need a more sophisticated form of class modeling than a lean tool like PlantUML can offer. They typically use professional UML modeling tools such as Visual Paradigm, Enterprise Architect or MagicDraw. An important aspect of these tools is the distinction between the model on the one hand and diagrams on the other hand. A diagram is a restricted view on the model, drawn for a specific purpose.

Take the diagram shown in section Editing the source above. It contains the customer with its orders because that is what the use case "Delete customer" needs. The model itself may well be much larger and also contain the relations to invoices, deliveries, returns, newsletters, contact history and so on. Other use cases need other excerpts and appropriately tailored diagrams. The business object "customer", however, which shows up in several diagrams, is defined only once in the model. The diagrams only refer to it instead of defining it anew. This is different with PlantUML, where every diagram defines its own classes.

For the human readers of a specification, the diagrams are what matters in the first place. They show at a glance the relations and details which are relevant for the particular use case. For a collaborating AI agent, the model is what matters most. The agent’s skill has to tell it where to find the model in a machine-readable form, see Teaching the agent: what belongs in a skill. This could be, for example, an export in XMI, produced by the modeling tool. XML Metadata Interchange is the OMG standard for exchanging UML models.

The diagrams, on the other hand, do not have to be optimally machine-readable if the model already is. They can simply be integrated into the specification as screenshots as explained in the section about Images above. This has the great advantage that they make full use of the layout capabilities of the UML tool. Ideally, sophisticated layout would not be necessary at all, because diagrams are kept simple by strict conventions, e.g. those of the C4 model. In practice, this is often impossible, because in larger projects you cannot always choose how complicated the relations to be considered are. That is exactly what the professional tools are for.

The following diagram, taken from a real project, gives an idea without going into any details.

Wouldn’t it then be smart to specify the procedures in UML as well - e.g. as activity diagrams - if a professional tool is at hand anyway? In principle, this is possible, but it gives up the particular advantages Specman brings to this work, see the Introduction. For example, none of the UML tools we know offers a change mode for iterative software engineering. They offer versioning and model comparison, but they do not mark changes in the diagram itself the way Specman or MS Word do, see Change Tracking. So a reasonable compromise is to model the class structures in a UML tool, as they change less often, and the procedures in Specman. The two tools complement each other. Up to now there has no "Classman" tool been invented yet as a counterpart to Specman ;-)

Choose File > Settings and switch on Auto-load. Specman then watches the working copy and loads it whenever it changes. Additionally switching on Auto-save (5 seconds is a good choice) makes Specman write your own edits to the working copy, so the agent always works on your latest state.

Specman creates the working copy next to the model file when loading or saving a diagram, as long as auto-load or auto-save is on. A new diagram therefore needs to be saved once before an agent can work on it.

The agent needs to know the file format. The grammar SpecmanModel_V002.g4 and the reference model specman-reference-v1.4-model-v2.nsd are located in the root directory of the installation, next to the launcher. Point your agent to them, and tell it how to work with them, see Teaching the agent.

The numbers refer to the picture above.

Your own edits in the window take the opposite way: auto-save writes them into the working copy, so the agent always works on your latest state. Once you are happy with the result, save the diagram (save in the picture). This is the only thing which writes the model file. Loading a diagram (load) is the moment where Specman creates the working copy.

Loading replaces the entire diagram, including the undo history. Undo does not reach back behind the agent’s changes. Your edits that have not yet been written to the working copy yet are replaced without asking, which is why auto-save is recommended.

The sanitizer checks a file and repairs what can be repaired automatically. It is a command-line operation of Specman: it runs without a window and without a running Specman, and usually only takes a second to check and repair a file. There are two reasons for the sanitizer to exist:

Specman comes with a console launcher for such operations, called Specman CLI here. The launcher depends on how Specman was installed:

There are three possible results:

If the sanitizer changed the file, Specman loads it a second time, and the diagram may update twice.

An agent does not know Specman, so it has to be told what this chapter told you. Specman deliberately doesn’t deliver a ready-made instruction file such as a skill: these age quickly with every new agent generation, and they need to be tailored to your project anyway. Therefore, this section only lists what belongs in a skill. Put it into whatever your agent loads on its own, e.g. a separate skill file, a CLAUDE.md or an AGENTS.md, so that it applies whenever the agent is asked to work on a Specman diagram.

Some things only you know and are part of the instructions as well: the exact command to start Specman CLI on your machine (see above), the language of your specifications, and the terminology and the level of detail your specifications follow. It is usually reasonable to provide a class model along with the Specman modells which provides the vocabulary.

The format can express change marks, so an agent can record its edits as changes, just like you would in change mode, see Change Tracking. It often works, but it requires some care: the agent has to write the marks itself, and the sanitizer doesn’t check them. If the result looks odd, have a look at the marks in the diagram and ask the agent to correct them, before accepting or rejecting anything.