Skip to content

Quickstart

This walkthrough runs the core Swax commands end-to-end: init → discover → plan. By the end you will have a traceability graph and a Markdown impact report on disk. When the remote specs change later, swax update mirrors them and rebuilds the graph in one step (see Commands reference).

0. Prerequisites

1. Initialize the project

swax --env-file .env init

init interactively prompts for:

  1. Repository URL — git source of the specifications.
  2. Path to specs inside the repo — the subdirectory to copy.
  3. Local download path — where the specs land in the project.

It writes .swax/config.yml, shallow-clones the repository (depth=1), and copies the specs into the local download path.

2. Discover the traceability graph

swax --env-file .env discover

discover rebuilds .swax/traceability.yml from scratch. It:

  1. Parses the local specs.
  2. Runs a two-pass LLM analysis:
  3. First pass — initial dependency hypotheses.
  4. Refine pass — schema-informed re-analysis of uncertain pairs.
  5. Merges confident edges with resolved uncertain pairs.
  6. Guarantees every discovered endpoint appears as a graph node.
  7. Deduplicates and writes deterministic YAML.

The graph stores paths only — no HTTP methods, no resource abstraction.

3. Generate an Impact Report

swax --env-file .env plan

plan analyzes spec changes since the last discover and prints a Markdown Impact Report to stdout. It:

  1. Parses the local baseline specs.
  2. Shallow-clones the spec repository fresh.
  3. Classifies the endpoint diff (added / removed / modified).
  4. Maps changed endpoints onto the traceability graph to find transitively affected endpoints.
  5. Runs a single-turn LLM analysis.

With no changes, it skips the LLM and prints a LOW-risk "No changes detected" report.

The report contains Summary, Risk (HIGH / MEDIUM / LOW), Modified Endpoints, Affected Endpoints, Requirements, and Checklist sections.

Result

After this walkthrough your project contains:

.swax/
  config.yml          # written by init
  traceability.yml    # written by discover
<download_path>/      # the copied specifications

Keeping the project current

When the remote spec repository moves on, swax --env-file .env update mirrors the local specs to the remote state and rebuilds the graph conditionally: removals only are pruned deterministically without an LLM call, and added/updated specs get a single-turn incremental revision (or a first build via the discover flow when no graph exists yet).

Next steps