This tool is still under development

Fully git-friendly lightweight requirements management system with tracing model verification, change detection, and propagation.

Run example analysis with:

uv run syntagmax --render-tree --cwd ./example/obsidian-driver/ analyze

To initialize a new Syntagmax project in the current directory:

uv run syntagmax init

This command creates a .syntagmax directory with:

• config.toml: A template configuration file with common options.
• project.syntagmax: A basic metamodel definition to get you started.

Syntagmax uses a TOML configuration file (default .syntagmax/config.toml).

Each input defines a source of requirements or artifacts:

Impact analysis helps identify potentially outdated artifacts by comparing their parent revisions.

AI analysis configuration. Settings can also be placed in ~/.syntagmax/config (global configuration) which are overridden by the project configuration.

Environment variables can also be used for API keys (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY). Configuration file values take precedence.

Note on AWS Bedrock: Currently, only Anthropic Claude models are supported on Bedrock. boto3 must be installed manually to use Bedrock.

Syntagmax includes a Model Context Protocol (MCP) server that allows LLMs to interact with your requirements directly.

• list_artifacts: Returns a list of all artifacts in the system.
• search_artifacts: Search for requirements by keyword.
• get_artifact_content: Fetch full details of a specific requirement (including traceability).

To start the server using Server-Sent Events (SSE):

uv run syntagmax mcp run .syntagmax/config.toml --transport sse --port 8000

To use Syntagmax with an MCP client that supports SSE, point it to the server's endpoint:

{
  "mcpServers": {
    "syntagmax": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

Note: When running via SSE, the server must be started manually or managed by a process manager before the client connects.

base = ".."

[[input]]
name = "requirements"
dir = "requirements/REQS"
driver = "obsidian"

[[input]]
name = "implementation"
dir = "app/src/main"
driver = "text"
atype = "SRC"
filter = "**/*.kt"

[metrics]
enabled = true
output_format = "markdown"
output_file = "output/metrics.md"

[metamodel]
filename = "project.syntagmax"

[ai]
provider = "anthropic"
model = "claude-sonnet-4-6"

Syntagmax automatically extracts revision history for each artifact using Git. This provides traceability and helps track changes over time.

Each artifact is attached with a set of revisions. A revision includes:

• Short Hash: The 7-character commit hash.
• Timestamp: Date and time of the commit.
• Author: Email of the commit author.

• Text-based artifacts (e.g., source code sections, Obsidian requirements): Syntagmax uses git blame to identify all commits that affected the specific lines where the artifact is defined.
• Sidecar artifacts: Syntagmax identifies the last commit that affected the primary file (e.g., an image) and all commits that affected the sidecar metadata file.

If you want to skip git history extraction (e.g., if you are not in a git repository or want to speed up analysis), use the --no-git flag:

uv run syntagmax analyze .syntagmax/config.toml --no-git

The analyze command is the primary way to process your project. It supports a dynamic execution pipeline where you can request a specific target step.

uv run syntagmax analyze [CONFIG_FILE] [STEP]

Syntagmax will automatically resolve and execute all dependencies required for the requested step:

Example:

# Run impact analysis only
uv run syntagmax analyze .syntagmax/config.toml impact

Syntagmax allows defining a custom metamodel for artifacts and their attributes using a simple DSL. This metamodel is used for static validation of requirements and other artifacts.

Companion VS Code Extension: syntagmax-vscode

artifact REQ:
    attribute id is mandatory string
    attribute contents is mandatory string
    attribute parent is optional reference to parent
    attribute status is mandatory enum [draft, active, retired]
    attribute verify is optional string
    attribute priority is mandatory integer

The attributes id and contents are always mandatory for all artifacts, but the type is flexible.

Python-style comments (# ...) are supported.

Presence: mandatory or optional.

Modifier:

• multiple: (Optional) Allows an attribute to have multiple values. Multiple values are extracted into a list. If a multiple attribute is missing, it defaults to an empty list [].

Types:

• string: Any text.
• integer: A whole number.
• boolean: true or false.
• reference [to parent]: A reference to another artifact (e.g., SRS-001). The optional to parent modifier marks the attribute as a parent indicator, used for building the artifact hierarchy.
  • Nominal Revision: For "via commit" traces, you can specify a parent's revision using the @ symbol: parent: SRS-001@c2d94e4. This allows for impact analysis to identify if a requirement is outdated relative to its parent.
• enum [<values>]: A fixed set of allowed values (comma-separated).

When impact analysis is enabled ([impact] enabled = true), Syntagmax performs the following checks:

1. Via Commit: If a parent reference includes a revision (e.g., SRS-001@c2d94e4), Syntagmax compares it with the parent's actual latest revision. If they differ, the link is marked as suspicious.
2. Via Timestamp: If no revision is specified and the metamodel trace mode is timestamp, the link is marked as suspicious if the parent was modified later than the artifact.

Suspicious links are highlighted in the artifact tree (printed in yellow) and included in the impact analysis report.

Note: Impact analysis requires a clean git worktree. You can bypass this check using the --allow-dirty-worktree flag.

Metamodel traces can specify an analysis mode:

trace from REQ to SYS is mandatory via commit
trace from SYS to ARCH is optional via timestamp

• via commit: Requires specific revision pinning in the artifact (e.g. parent: SYS-001@c2d94e4).
• via timestamp: Uses modification times to detect potential staleness. Defaults to older nominal revision if not specified.

Multiple values can be specified by repeating the attribute:

[<
ID = REQ-1
tag = security
tag = performance
>>>
This requirement has multiple tags.
>]

In this case, artifact.fields['tag'] will be ['security', 'performance'].

In Obsidian (YAML):

attrs:
  author:
    - Alice
    - Bob

This will result in artifact.fields['author'] being ['Alice', 'Bob'].

Syntagmax provides a command to renumber artifact IDs according to a schema. This is useful when you want to ensure a consistent naming convention across your project.

mkdir tmp
cp -rf ./example/renumber-demo ./tmp/
uv run syntagmax --cwd ./tmp/renumber-demo edit renumber --all

To renumber artifacts, use the edit renumber command:

uv run syntagmax edit renumber --all

• --all: Renumber all artifacts.
• --atype <type>: Renumber only artifacts of a specific type.
• --schema <schema>: Use a custom schema for renumbering.
• --dry-run: Show what changes would be made without actually modifying any files.

The ID schema can include the following macros:

• {atype}: The type of the artifact (e.g., REQ, SYS).
• {num}: A sequential number.
• {num:padding}: A sequential number with zero-padding (e.g., {num:3} for 001).

Example schema: myproject-{atype}-{num:4}

• Implement automatic change propagation
• Enhance AI-based analysis and tracing