Sylang Studio: Your First Project

4.1 Installing Sylang Studio and touring the workbench

Sylang Studio is the reference IDE for the Sylang language. It's a browser-based application built with TanStack Start, React 19 and Vite, served from a Node SSR backend, and you sign in with GitHub OAuth through Supabase. It's published under the MIT license at github.com/balaji-embedcentrum/sylang-studio. Under the hood it's a fork of Hermes Studio, with all the Sylang-specific MBSE tooling layered on top of an existing agent-IDE base.

Installation

The recommended install is a sibling clone of two repositories: sylang-core, the language ecosystem, and sylang-studio, the IDE itself. The companion projects that ship with this book use the same layout.

# Prerequisite: Node.js 22+, pnpm 9+, git

# 1. Clone the language ecosystem as a sibling
git clone https://github.com/balaji-embedcentrum/sylang-core.git \
  ~/Documents/sylang-core
cd ~/Documents/sylang-core
pnpm install
pnpm -r build

# 2. Clone the IDE
git clone https://github.com/balaji-embedcentrum/sylang-studio.git \
  ~/Documents/sylang-studio
cd ~/Documents/sylang-studio
pnpm install

# 3. Configure environment
cp .env.example .env
# Edit .env to set SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_KEY,
# ANTHROPIC_API_KEY, HERMES_API_URL, HERMES_API_TOKEN.

# 4. Launch
pnpm dev
# → http://localhost:3000

If you're evaluating Sylang for a whole organization, read the operations docs in sylang-studio/docs/. They cover the production-tier deployment, including the Cloudflare edge, the Docker Compose topology and per-user workspace isolation.

First sign-in: GitHub OAuth

On first launch, your browser opens a minimal sign-in screen at http://localhost:3000/. You sign in with GitHub OAuth via Supabase; there's no local username or password store. Studio sets up your workspace on your first successful sign-in and binds it to your GitHub identity for later sessions.

If your organization needs internal SSO, you can add Supabase's SAML or OIDC providers as extra sign-in paths.

The workbench: a quick tour

If you've used VS Code, a JetBrains IDE or Eclipse, the layout will feel familiar. There are three vertical regions (left sidebar, center editor, right sidebar) plus a bottom panel, and you can collapse each one. Arrange them to suit the way you work. The eight themes inherited from Hermes Studio let you pick your own visual default.

The main panels

1. File Explorer (left). A file tree of your Sylang project, rooted at the workspace directory. Icons show each file's validation state (green check, yellow triangle, red circle). Right-click a file for its file-type menu: Generate VML on a .fml, Generate VCF on a .vml, Open FMEA Workbench on a .flr, and Run Coverage Report on the project root.
2. Block-aware editor (center). For Sylang files (.req, .fun, .blk and so on), the editor renders the parsed DSL with TipTap instead of showing plain text. Each def clause becomes a structured block with its own inline controls. For everything else (Markdown, source code, JotX), CodeMirror 6 takes over.
3. Diagram editor (right, switchable). Diagrams computed live from the source: feature tree (.fml), internal block diagram (.blk), state machine (.smd), use case (.ucd), sequence (.seq), fault tree (.fta) and feature variants (.vml). Each diagram type uses whichever renderer suits it best: D3, Konva or Sigma.
4. FMEA workbench (right, switchable on .flr files). A full AIAG/VDA seven-step UI: Structure → Function → Failure → Risk → Optimization → Results. It's backed by the shared symbol manager, so any change you make in the workbench shows up at once in the underlying .flr file.
5. Traceability Graph (right, switchable). An interactive D3/Sigma graph of every symbol and every relationship in the workspace, with a click-to-inspect side panel. You can filter it by symbol kind, safety level, status or variant.
6. Coverage Report (right, switchable). The five-state symbol classification from Chapter 15 (isolated / orphan / sink / connected / broken), with per-edge source —rel→ target detail, sortable worst-first.
7. Variant matrix (right, switchable on .fml/.vml). VML feature toggling, VCF generation and the 150% PLE model, all in interactive form.
8. Agent chat (bottom). A live, SSE-streamed conversation with the configured AI agent. You see each tool call as it happens: the panel shows the agent calling specific MCP tools such as sylang_get_symbol_by_id and sylang_validate_file.
9. Terminal (bottom, switchable). An xterm-backed shell in the workspace, handy for running sylang parse/fmea/fta/trace directly.
10. Git panel (bottom, switchable). Clone any repo, then edit, commit and push from the UI. Workspaces are GitHub-native: your changes are first-class git commits attributed to you, the signed-in user.

Your first file

Our medical-domain anchor for Chapter 4 is an insulin infusion pump, and the first file is the product-line root. Open Sylang Studio, select a new empty workspace, create InfusionPumpProductLine.ple and type in the following:

hdef productline InfusionPumpProductLine
  name "Insulin Infusion Pump Product Line"
  description """
    Continuous subcutaneous insulin infusion (CSII) pump platform for
    type-1 and type-2 diabetes management. Wearable patch-pump and
    pole-mounted variants. IEC 62304 Software Safety Class C.
  """
  owner "Medical Devices Platform Engineering"
  domain "medical", "diabetes-care", "drug-delivery", "Class-III"
  compliance "IEC 62304", "ISO 14971", "ISO 13485", "FDA 21 CFR 820"
  firstrelease "2027-06-01"
  tags "infusion-pump", "insulin", "Class-C"
  safetylevel SIL-3
  status approved
  region "Global", "North America", "Europe\

Exercises

4.2 Writing your first feature model with the agent

With the product-line root in place, the next artifact in the usual authoring order is the feature model: the hierarchy of what can vary across variants. In this subchapter you'll write the infusion pump's feature model with the agent in the loop. Along the way you'll see how the agent loads skills, how often it calls MCP tools and how the validator feeds back. You'll also see why the agent, not you, is the primary author.

The agent's first turn

Open the agent chat panel (bottom of the workbench, or Cmd-J) and type a prompt that names the artifact you want. A typical first prompt for the infusion-pump feature model looks like this:

As soon as the agent receives the prompt, you can watch its first move in the chat panel. It loads the relevant skill files and queries the existing project state through MCP.

[09:14:22] Loading skill: sylang-fundamentals (cross-cutting reference)
[09:14:22] Loading skill: sylang-features-variants (.fml authoring)
[09:14:23] MCP call: sylang_get_all_symbols (returns 1 symbol: productline InfusionPumpProductLine)
[09:14:23] MCP call: sylang_get_symbol_by_id { id: "InfusionPumpProductLine" }
[09:14:23] MCP call: sylang_get_keyword_reference { fileType: "fml" }
[09:14:25] Generating artifact proposal...

As a rough illustration of scale, the context loaded here is about 950 lines of Markdown across three skills, plus a few hundred tokens of structured query results. The agent takes it in within a few hundred milliseconds.

The agent answers with a complete .fml file, proposed as a diff against the empty project. As a rough guide, expect it something like 8 to 15 seconds after you submit the prompt. The chat panel shows the diff with the usual add and remove markings. You review it, then accept it (in full or in part) or ask the agent to revise.

The proposed artifact

Here's the agent's first-cut proposal for the infusion-pump feature model, slightly abridged:

use productline InfusionPumpProductLine

hdef featureset InfusionPumpFeatures
  name "Insulin Infusion Pump Feature Set"
  description "Feature model for wearable and pole-mounted insulin pump variants."
  owner "Medical Devices Platform Architecture"
  safetylevel SIL-3
  status approved
  listedfor ref productline InfusionPumpProductLine

  def feature CoreInfusion mandatory
    name "Core insulin infusion"
    safetylevel SIL-3

    def feature FormFactor mandatory
      name "Pump form factor"
      def feature WearablePump alternative
        name "Wearable patch pump"
      def feature PoleMountedPump alternative
        name "Pole-mounted pump with tubing"

    def feature DoseLimiting mandatory
      name "Dose limiting"
      safetylevel SIL-3

    def feature OcclusionDetection mandatory
      name "Occlusion detection"
      safetylevel SIL-3

  def feature DataIntegration optional
    name "Data integration"

    def feature CgmIntegration optional
      name "Continuous glucose monitor integration"

    def feature PredictiveLgs optional
      name "Predictive low-glucose suspend"
      requires ref feature CgmIntegration

Validation feedback

When you accept the diff, the file is written to disk as InfusionPumpFeatures.fml in the project's System/ directory. The agent chose that directory by convention, and you can override it. The validator runs automatically, the file's icon turns into a green check and the diagram view re-renders to show the feature tree.

Your role: review, not authorship

Your role in this exchange is review: judging whether the agent's proposal correctly captures the engineering intent. You're not expected to write the artifact from scratch, because the agent is the primary author. Three features make this kind of review work:

1. Artifact-oriented. You read the proposed Sylang code, not a prose description of it. That asks more of you than a summary would. It's also more reliable, because the artifact is what the validator checks and what the auditor examines.
2. Diff-mediated. You see what the agent wants to add or change, not a full dump of the resulting file. That keeps your attention on the change and lets you accept parts of it.
3. Open to more review. You can ask the agent to critique its own proposal: review your proposed feature model against IEC 62304 and ISO 14971; what gaps do you see? You can also ask for an alternative, or have a separate reviewer agent take a look.

Iteration: extending the feature model

The first cut is rarely final. A typical session takes several rounds before the model is ready for downstream artifacts. Here's a representative second turn:

This time the agent doesn't rewrite the file. It makes a focused change: a new def feature CloudDataExport under DataIntegration, with its requires and excludes relationships. The diff is small, so your review is quick. Over a handful of rounds like this, the model settles into its final state.

Exercises

4.3 Functions and requirements with the agent

In Subchapter 4.2 you wrote the feature model with the agent. Now we move to the next two artifact types in the usual order: the function model (.fun) and the safety requirement set (.req). Watch how the agent uses what you've already written as context for its next proposals. The project hangs together because the agent walks the existing artifact graph through MCP queries and proposes new artifacts that fit into it.

The function model

With the feature model in place, ask the agent to derive the function model:

This is where the agent starts to look different from a generic LLM completion. You'll notice three things:

1. No new skill is loaded. sylang-features-variants covers .fun files as well as .fml. It was loaded in the previous turn and is still in context.
2. It queries the existing project via MCP. sylang_get_symbols_by_kind { kind: "feature" } returns the feature identifiers, so nobody has to tell the agent which features exist.
3. Its identifiers are correct by construction. The function model's enables relationships point at real feature identifiers, checked with sylang_resolve_symbol before the proposal reaches you. You supply the engineering intent; the agent supplies an artifact with the right identifiers to realize it.

The agent comes back with a complete InfusionPumpFunctions.fun file holding about a dozen function definitions. If your prompt was unambiguous, it passes validation on the first try. The chat transcript captures the reasoning (the prompt, the feature model it read, the proposal), and the artifact captures the result. The diff makes both reviewable.

Safety requirements from the IEC 62304 chain

Requirements are where agent help pays off most, and where the stakes are highest. Here's a representative third-turn prompt:

This prompt asks for two related artifacts: the safety goals (.sgl) and the requirements (.req) that derive from them. The agent answers with a multi-file proposal, two diffs in the same chat turn, which you can accept together or one at a time.

The two files cross-reference each other correctly. Each def safetygoal in the .sgl is the target of a derivedfrom ref safetygoal in the .req. The references resolve cleanly because the agent wrote both files in the same reasoning pass.

Here's a representative requirement from the proposal:

  def requirement REQ_INS_001
    name "Limit maximum bolus to programmed safety ceiling"
    description """
      The infusion pump shall not deliver a bolus exceeding the
      MaxBolusUnits parameter currently programmed for the patient,
      regardless of the source of the bolus request (manual,
      bolus-calculator-derived, or remote-initiated).
    """
    reqtype safety
    safetylevel SIL-3
    status approved
    rationale """Bolus overdose is the most-reported severe-harm event
      in FDA MAUDE database queries for insulin pumps (2010-2023). The
      ceiling provides a hardware-enforced backstop independent of
      software computation paths."""
    verificationcriteria """HIL test: request bolus = MaxBolusUnits + 1
      via each of the three sources. Verify no bolus delivered;
      verify DTC emitted."""
    derivedfrom ref safetygoal SG_NoBolusOverdose
    implements ref function BolusController, BolusGuardian
    allocatedto ref block PumpController

1. The description uses prescriptive shall form, as the safety standards require. The agent learned this from the sylang-requirements skill file and applies it consistently.
2. The rationale cites a publicly verifiable source (the FDA MAUDE database) instead of asserting an unsupported claim. That's the standard an auditor expects of a rationale, and the agent meets it because the skill file asks for it.
3. The verificationcriteria names a concrete test approach, which meets the rule that every requirement be testable. The test cases in the downstream .tst file (written later) realize these criteria.

When the agent needs more context

Not every prompt produces an artifact you can accept straight away. If the artifact's conventions are unusual or still settling, or the domain knowledge behind it is thin, you may get a proposal you have to reject and re-prompt.

Sylang's agent integration handles this with a clarification turn. When the agent's confidence is low (it shows this with an indicator in the chat panel), it asks you a clarifying question instead of producing a proposal.

Closing the chapter's first loop

You now have a product line, a feature model, a function model, safety goals and a first set of safety requirements. That's the spine of an MBSE deliverable. What's left for Chapter 4 is to extend the spine into architectural blocks (Subchapter 4.4) and to show the surrounding tooling that closes the development loop.

Exercises

4.4 Architecture and verification with the agent

This subchapter continues the infusion-pump walkthrough from 4.2 and completes the project's first slice: architectural blocks (.blk), interfaces (.ifc) and a test set (.tst). By now the agent follows the patterns you saw in 4.2 and 4.3, so we'll focus on what's specific to architecture and tests. That means three things: how the agent handles the one-block-per-file convention, how interfaces stay consistent with blocks, and how test cases bind to requirements through the satisfies relationship.

Block authoring: one file per block

Sylang's rule that each .blk file holds exactly one block makes a specific demand on the agent. When you ask for the pump controller's architecture, the agent has to propose several files, one per block, instead of one file with many block definitions. Its answer is a multi-file diff with one entry per file.

Here's a decomposition the agent might propose for the infusion pump, with six blocks:

Each block lives in its own .blk file. The agent writes both directions of each relationship for you: PumpController decomposesto each of the other five, and each of the other five carries decomposedfrom PumpController. You don't need to check the inverse edges by hand. The agent's reasoning closes the loop, and the validator confirms it.

Interface authoring: cross-block consistency

The companion interface set (.ifc) names the operations, signals, datatypes and parameters that flow between blocks. Valid syntax is the easy part. The real challenge is a consistent interface set: every signal a block needs must be provided by another block (or an external system), and every referenced datatype must be defined.

The agent's strategy is to read all the block files it just wrote and pull out their needs and provides declarations. It then generates the interface set so that every needs has a matching interface definition. The resulting .ifc has no unresolved interface references by construction. The validator confirms it: no SYLANG_UNRESOLVED_REFERENCE errors.

Test authoring: binding to requirements

Tests close the development loop. Give the agent a prompt like propose test cases for the safety requirements; use HIL method where possible, manual method where HIL is not feasible. You'll get a .tst file with one def testcase per requirement, and sometimes more.

Each test case carries:

• name and description, which identify the test
• method: HIL, SIL, PIL, VIL, MIL, manual or automated
• setup, steps, expected and passcriteria: the behavioral specification a test engineer executes
• testresult: notrun in the proposed artifact, then intest, pass, fail or blocked as the test is executed
• satisfies ref requirement: the binding from the test back to the requirement(s) it verifies

The iteration cycle in practice

How long does a first pass take? My working estimate is about 90 minutes to two hours for a competent user with an attentive agent, from an empty workspace to validated test cases.

The result isn't production-ready. It covers only the dose-limiting safety chain, leaves the occlusion-detection chain and the variant features for later, and has no FMEA or fault tree. But you can open it in Sylang Studio, view it in the diagram renderers and step through it in the traceability matrix.

Each later iteration adds another slice: the occlusion-detection chain, the variant configuration, the FMEA, the fault tree, the safety mechanisms, and the reactive documentation that produces the safety case.

Closing Chapter 4

In this chapter you've installed Sylang Studio, toured the IDE and written a first project across the main artifact types. You've seen how the agent integration mediates that work, what its MCP tool calls look like, and how validation and review feel in practice. That's enough grounding to start productive work on your own projects.

Chapter 5 turns to the project-management constructs, .agt and .spr, that organize the agent-mediated work itself. They give you explicit agent declarations, task assignment and two-way traceability between project work items and the engineering artifacts they produce. They're the difference between agent help as an ad hoc productivity tool and agent help as an auditable engineering process.

Exercises