AI authoring tools
Aliot Software Architecture registers nine tools through VS Code's language-model API: eight read-only tools and swaml_run_tests, which runs use cases and tests. Compatible chat/agent clients can enable or reference them; the extension supplies deterministic language services, not a model or subscription. Desktop and browser hosts use the same tools. They are not a standalone MCP server, and an external agent does not receive them merely by installing the extension.
Keep a .swaml model open. Start with guidance, inspect actual source and library declarations, then validate a proposal. Apply accepted changes through the editor/client's normal reviewed edit mechanism and revalidate. None of these tools writes a document or fetches remote examples. Only swaml_run_tests executes anything: bounded deterministic runs of use cases and tests, whose results are evidence of one run each, never a proof.
| Prompt reference / registered tool | Inputs | Result |
|---|---|---|
#swamlGuidance / swaml_agent_guidance |
{} |
Pinned language/core identity, extension version, authoring invariants, view names and bundled skill locations. |
#swamlContext / swaml_agent_context |
Optional uri, range, version |
Source/selection text, diagnostics, real symbols, dependency revisions and fingerprints. |
#swamlValidate / swaml_validate_draft |
Required text; optional uri, range, version |
ok, complete trial-context diagnostics and source revisions. Does not apply or return an edit plan. |
#swamlSearch / swaml_search_library |
Required query; optional uri, limit (1 to 100) |
Workspace/configured/bundled-library declarations with URI/range and origin, plus the official examples link. |
#swamlResolve / swaml_resolve_symbol |
Required name; optional uri, position |
Qualified catalog/occurrence matches and ambiguity; with a source position, the actual indexed reference binding. |
#swamlTrace / swaml_requirement_trace |
Optional uri, name |
Requirement documentation and typed attribute source values, resolved satisfy claims with their design and verify claims with the last recorded result of their test (pass, fail, inconclusive, no checks or not run; stale after a source change), a per-requirement summary, locations and explicit execution/evidence limits. |
#swamlDiagnostic / swaml_explain_diagnostic |
Required code; optional uri |
The diagnostic catalogue entry for a real code. Unknown codes ask the caller to inspect the attached diagnostic. |
#swamlRunTests / swaml_run_tests |
Optional uri, cases (Package::Case names), package, untilNs, maxSteps, trace, details |
Runs one case, a package or (with neither) every case of the workspace. Each result: case, kind, subject, result (pass, fail, inconclusive, no checks, or error when it could not start), reason, message, failing statement identity and location, time and run summary; skipped cases after cancellation or the time budget. Requires a valid workspace. details adds the compact per-statement evidence, trace the traces. The results also appear on the diagrams. |
#swamlTestResults / swaml_test_results |
Optional uri, cases, details |
The last recorded result of each run case, newest first, with run identity, time and stale when the sources changed after the run. Runs nothing. |
Source and selection rules
An omitted URI uses the active swa.ml source/diagram document. Otherwise pass an absolute document URI, such as file:///E:/Models/controller.swaml; a filesystem path alone is not a URI. Context and draft tools default to the current open version of that exact document. If that same document has a nonempty active selection, its range becomes the default. Pass an explicit full-document range when proposing complete text while a selection is active. LSP positions are zero-based { "line": 0, "character": 0 }; ranges contain start and end positions.
Explicit version values must match the open source version. Draft validation builds a separate model with all relevant dependencies and the pinned library, checks snapshots and leaves the live source unchanged. A rejected or stale proposal must be refreshed. Errors are returned as a JSON object containing error; validation failures contain diagnostics and ok: false.
Name-only resolve is a catalog lookup, not permission to access private state or call across components. Use a qualified path to disambiguate, or supply a URI and source position to inspect an existing semantic reference. Requirement short names can also be ambiguous; use Package::Requirement. A requirement claim is intent and never a passed test.
Example workflow
With the example model from the README open, ask a compatible agent:
Use #swamlGuidance and #swamlContext to inspect this model. Use #swamlSearch to find the real Flow view definition. Propose a change and run #swamlValidate before presenting it for review.
A complete draft request with no active selection has this shape:
{
"uri": "file:///E:/Models/example.swaml",
"version": 3,
"text": "package Example { component Demo {} view overview: Swaml::Views::General of Demo; }"
}
An external coding agent can instead follow the bundled portable workflows under resources/reference/skills/swaml-author/ and swaml-validate/, and invoke the headless CLI. Language rules and diagnostics come from the pinned implementation; tool output is evidence to inspect, not an instruction to bypass source scopes or edit approval.