How to Validate a Workflow Diagram with the Archify CLI Using the Showcase Quality Profile

To validate a workflow diagram with the Archify CLI using the showcase quality profile, run node archify/bin/archify.mjs validate workflow <file> --quality showcase to enforce strict composition and readability checks that ensure the diagram is ready for public presentation.

The Archify CLI from the tt-a1i/archify repository provides a validation pipeline for architecture diagrams defined in JSON IR format. When you validate a workflow diagram with the Archify CLI, appending the --quality showcase flag activates a restrictive rule-set that blocks publication unless the artifact meets presentation-grade standards for layout, reachability, and composition.

What Defines the Showcase Quality Profile

The showcase quality profile applies a stricter rule-set than standard validation modes, requiring all nodes to be reachable, routes to clear legends, and the final artifact to pass strict composition checks. According to the source code in archify/bin/archify.mjs, invoking this profile triggers the extractQualityArgs function (lines 75-108) to set the environment variable ARCHIFY_QUALITY_PROFILE=showcase.

This environment variable signals the workflow renderer to enable high-severity validation rules that evaluate desktop-readability and visual composition. Unlike the default profile, showcase treats layout violations as fatal errors rather than warnings, ensuring the diagram renders correctly across different viewports before validation succeeds.

The Validation Pipeline Explained

The CLI orchestrates validation through a five-stage pipeline implemented in the main driver and shared helpers:

1. Argument Parsing

The CLI entry point parses the command validate workflow alongside the input file path and quality flags. The extractQualityArgs helper in archify/renderers/shared/cli.mjs isolates the --quality showcase argument from the process arguments array.

2. Environment Setup

Before spawning the subprocess, the CLI constructs the rendererEnv object (lines 41-47 in archify/bin/archify.mjs), explicitly injecting ARCHIFY_QUALITY_PROFILE=showcase into the environment. This ensures the workflow renderer inherits the correct validation mode regardless of the parent shell’s configuration.

3. Renderer Execution

The CLI resolves the workflow renderer path via rendererPath('workflow') and spawns the process at archify/renderers/workflow/render-workflow.mjs. The renderer loads the input JSON IR and executes both the schema validator and the layout engine against the showcase criteria.

4. Diagnostics Collection

If the renderer encounters a violation, it exits with a non-zero status. The rendererFailure handler (lines 78-90 in archify/bin/archify.mjs) intercepts the exit code and harvests structured diagnostics from the subprocess stderr, normalizing them for CLI output.

5. Receipt Generation

When the --json flag is present, the CLI invokes reportValidateFailure (lines 84-85) to emit a machine-readable receipt. This JSON object contains the validation status, check counts, specific error codes, and an array of supportedFixes for any failed rules.

Running the Validation Command

First, install the CLI globally using the package manager:

npx skills add tt-a1i/archify -g

Prepare your workflow diagram as a JSON file following the Archify IR schema. The repository includes a sample at examples/agent-tool-call.workflow.json for testing.

Execute validation with the showcase profile and JSON output:

node archify/bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

Successful Validation Output

When all 12 checks pass, the CLI returns a receipt confirming compliance:

{
  "schemaVersion": 1,
  "ok": true,
  "command": "validate",
  "stage": "validate",
  "type": "workflow",
  "input": "examples/agent-tool-call.workflow.json",
  "error": null,
  "diagnostics": [],
  "validation": {
    "checksPassed": 12,
    "checkCount": 12,
    "compositionProfile": "signal-flow",
    "compositionStatus": "pass"
  }
}

Handling Validation Failures

If the diagram violates showcase rules—such as failing desktop-readability standards—the CLI returns a detailed error payload:

{
  "ok": false,
  "command": "validate",
  "stage": "validate",
  "type": "workflow",
  "input": "examples/agent-tool-call.workflow.json",
  "error": "Final artifact failed composition/desktop-readability.",
  "diagnostics": [
    {
      "code": "artifact/composition/desktop-readability",
      "severity": "error",
      "message": "Final artifact failed composition/desktop-readability.",
      "subject": { "check": "composition/desktop-readability" },
      "evidence": { "details": [] },
      "supportedFixes": [
        "reduce the viewBox width, shorten node copy, widen affected nodes, or split the diagram"
      ]
    }
  ]
}

Interpreting Error Codes and Fixes

The showcase profile enforces specific error codes like artifact/composition/desktop-readability. Each diagnostic object includes a supportedFixes array containing actionable remediation strategies. The test suite in archify/test/cli-output-types.test.mjs asserts that these fields are present for all validation failures, ensuring the CLI remains consistent across versions.

When you encounter a composition error, apply one of the suggested fixes—such as reducing the viewBox width or splitting the diagram—and rerun the validation command until the compositionStatus returns pass.

Summary

• The showcase quality profile sets ARCHIFY_QUALITY_PROFILE=showcase via extractQualityArgs in archify/bin/archify.mjs to enable strict validation rules.
• The validation pipeline parses arguments, configures the rendererEnv, executes the workflow renderer at archify/renderers/workflow/render-workflow.mjs, and collects diagnostics via rendererFailure.
• Use node archify/bin/archify.mjs validate workflow <file> --quality showcase --json to generate machine-readable receipts with detailed check results.
• Failed checks return specific error codes (e.g., artifact/composition/desktop-readability) with remediation guidance in the supportedFixes field.

Frequently Asked Questions

What is the difference between the default quality profile and the showcase profile in Archify?

The default profile performs basic schema validation and layout checks, while the showcase profile enforces stricter composition rules through the ARCHIFY_QUALITY_PROFILE=showcase environment variable. It requires all nodes to be reachable, routes to clear legends, and artifacts to meet desktop-readability standards before validation succeeds.

How do I fix a desktop-readability error when validating with the showcase profile?

When you encounter the artifact/composition/desktop-readability error code, apply one of the supportedFixes suggested in the JSON output: reduce the viewBox width, shorten node copy text, widen affected nodes, or split the diagram into multiple smaller diagrams. Rerun the validation command after adjustments to verify the fix.

Can I validate workflow diagrams without installing Archify globally?

Yes, you can run the CLI directly using node pointing to the local binary path. The command node archify/bin/archify.mjs validate workflow <file> --quality showcase works regardless of global installation status, provided the repository dependencies are available in node_modules.

Where does the Archify CLI store the validation rules for the showcase profile?

The showcase rules are implemented in the workflow renderer at archify/renderers/workflow/render-workflow.mjs, which checks the ARCHIFY_QUALITY_PROFILE environment variable set by the CLI driver in archify/bin/archify.mjs. The specific schema and layout constraints are enforced by the renderer's validation engine when the environment variable equals showcase, as verified by the test suite in archify/test/cli-output-types.test.mjs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}