### Install Pre-commit Hook Script

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-sync/SKILL.md

Installs the pre-commit hook.

```bash
bash ${CLAUDE_PROJECT_DIR}/hooks/pre-commit/install_hooks.sh
```

--------------------------------

### One-time setup command

Source: https://github.com/krus210/archspec/blob/main/CONTRIBUTING.md

Command to set up the local virtual environment and install development dependencies.

```bash
make bootstrap     # python3 -m venv .venv + pip install -r requirements-dev.txt
```

--------------------------------

### Go Extensions Example

Source: https://github.com/krus210/archspec/blob/main/docs/EXTENDING.md

An example of a 'go_extensions' block in SERVICE_MAP.yaml for language-specific configuration.

```yaml
go_extensions:
  optimistic_locking_field: "row_version"
  outbox_table: "outbox_events"
```

--------------------------------

### Scanner Output Example

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-sync/SKILL.md

An example of the JSON output from the scanner, showing repository root, target, files scanned, and detected consumers.

```json
{
     repo_root,
     target,
     files_scanned,
     consumers: [{name, protocol, endpoints_used: [...], source, confidence,
                  discovered_via: "monorepo-scan"}, ...]
     }
     
```

--------------------------------

### Inline Pragma Example (Single Rule)

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of a single-rule inline pragma in Go code.

```go
// archspec:ignore AI-002 -- migration script, single-use
repo.Save(ctx, item)
publisher.Publish(ctx, event)
```

--------------------------------

### Before: SERVICE_MAP.yaml with no exceptions

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of SERVICE_MAP.yaml with an empty exceptions list.

```yaml
exceptions: []
```

--------------------------------

### Install Claude Code plugin

Source: https://github.com/krus210/archspec/blob/main/README.md

Recommended installation method for the archspec plugin via the Claude Code marketplace.

```bash
/plugin marketplace add krus210/archspec
/plugin install archspec@archspec
```

--------------------------------

### Declarative Exception Example

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of how to define exceptions in the SERVICE_MAP.yaml file.

```yaml
exceptions:
  - rule: AI-001
    scope:
      endpoint: "GET /admin/health"
    reason: "internal admin endpoint, no client retries possible"
    approved_by: "@alice"
    adr: "docs/adr/0042-skip-idempotency-on-admin.md"
    expires: "2026-12-31"
  - rule: AI-002
    scope:
      function: "internal/migrations/backfill.go::runBackfill"
    reason: "migration job, single-use, runs once during cutover"
    approved_by: "@bob"
    adr: "docs/adr/0043-backfill-outbox-bypass.md"
    expires: "2026-06-30"
```

--------------------------------

### Reverse Scan Command Example

Source: https://github.com/krus210/archspec/blob/main/CHANGELOG.md

Command-line arguments for the reverse scan mode in scan_go.py.

```bash
--reverse-scan <repo-root> --target <service-name>
```

--------------------------------

### YAML Entry Example

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-sync/SKILL.md

Example of a YAML block structure for API endpoints, including details like protocol, idempotency, contract, and SLA.

```yaml
- name: <user-provided or scanner-derived>
  protocol: HTTP|gRPC
  idempotency:
    required: <bool>
    # if required is true: key_source and storage are required by schema
    key_source: <user-provided>
    storage: <user-provided or "not-implemented">   # see § Truthful state values
  contract: <user-provided or "not-documented">     # use "TODO" only if user said "I'll write the schema"
  sla:
    p99_latency: <user-provided or "not-measured">
    availability: <user-provided or "not-measured">

```

--------------------------------

### DET-015 Pragma Format Discipline Example

Source: https://github.com/krus210/archspec/blob/main/docs/VALIDATION_RULES.md

Example of a correctly formatted pragma with a reason comment.

```go
// archspec:ignore AI-002 -- migration script, single-use
```

--------------------------------

### Linter Activation Example

Source: https://github.com/krus210/archspec/blob/main/docs/EXTENDING.md

Shows how a linter activates based on the 'service.language' field in a service's SERVICE_MAP.yaml.

```yaml
service:
  language: python      # → /archspec:validate runs linters/python/
```

--------------------------------

### Inline Pragma Example (Block Scope)

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of a block-scoped inline pragma in Go code, suppressing multiple rules.

```go
// archspec:ignore-block AI-001 AI-007 -- legacy adapter, removal scheduled Q3
func legacyHandler(ctx context.Context, r *http.Request) error {
    // ... pre-existing code ...
}
```

--------------------------------

### YAML edits example

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-investigate/SKILL.md

Example of proposed YAML edits in a unified-diff snippet.

```diff
api:
  endpoints:
+   - name: BulkCreateListings
+     protocol: HTTP
+     idempotency:
+       required: true
+       key_source: "header: X-Idempotency-Key"
+       storage: "redis: idemp:{key}"
+     contract: "api/openapi.yaml#/paths/~1listings~1bulk/post"
+     sla: { p99_latency: "300ms", availability: "99.9%" }
```

--------------------------------

### Python Extensions Example

Source: https://github.com/krus210/archspec/blob/main/docs/EXTENDING.md

An example of a 'python_extensions' block in SERVICE_MAP.yaml for language-specific configuration.

```yaml
service:
  language: python

python_extensions:
  framework: fastapi
  idempotency_decorator: "@idempotent"
  outbox_helper: "events.OutboxPublisher"
```

--------------------------------

### Before: Legacy handler with inline pragmas

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of legacy Go code with inline archspec pragmas for AI-002 exceptions.

```go
package legacy

func ProcessOrderV1(ctx context.Context, o Order) error {
    // archspec:ignore AI-002 -- legacy v1 path, removed when v2 is GA
    repo.Save(ctx, o)
    publisher.Publish(ctx, OrderProcessedV1{ID: o.ID})
    return nil
}

func ProcessRefundV1(ctx context.Context, r Refund) error {
    // archspec:ignore AI-002 -- legacy v1 path, removed when v2 is GA
    repo.Save(ctx, r)
    publisher.Publish(ctx, RefundProcessedV1{ID: r.ID})
    return nil
}

func CancelOrderV1(ctx context.Context, id string) error {
    o, err := repo.Load(ctx, id)
    if err != nil {
        return err
    }
    o.Status = "cancelled"
    // archspec:ignore AI-002 -- legacy v1 path, removed when v2 is GA
    repo.Save(ctx, o)
    publisher.Publish(ctx, OrderCancelledV1{ID: id})
    return nil
}

func RetryShipmentV1(ctx context.Context, id string) error {
    s, err := repo.Load(ctx, id)
    if err != nil {
        return err
    }
    // archspec:ignore AI-002 -- legacy v1 path, removed when v2 is GA
    repo.Save(ctx, s)
    publisher.Publish(ctx, ShipmentRetriedV1{ID: id})
    return nil
}

func ArchiveOrderV1(ctx context.Context, id string) error {
    // archspec:ignore AI-002 -- legacy v1 path, removed when v2 is GA
    repo.Save(ctx, Order{ID: id, Archived: true})
    publisher.Publish(ctx, OrderArchivedV1{ID: id})
    return nil
}
```

--------------------------------

### Metadata Example

Source: https://github.com/krus210/archspec/blob/main/docs/SERVICE_MAP_SPEC.md

Example of the 'metadata' section, including schema version, source of truth, CI drift check, and last reviewed date.

```yaml
metadata:
  schema_version: "1.0"
  source_of_truth: local
  drift_check_in_ci: true
  last_reviewed: "2026-04-25"
```

--------------------------------

### Mermaid diagram example

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-investigate/SKILL.md

Example of a chat-only Mermaid diagram highlighting new/changed nodes with a :new class.

```mermaid
flowchart LR
  classDef new stroke:#0a0,stroke-width:2px;
  svc[listing-service]
  newEp[POST /listings/bulk]:::new
  newEp --> svc
  svc --> kafka>listings.created v1]
```

--------------------------------

### DEP-002/003/004 - Multi-service graph consistency example

Source: https://github.com/krus210/archspec/blob/main/CHANGELOG.md

Examples illustrating graph consistency issues flagged by DEP-002, DEP-003, and DEP-004.

```yaml
caller A names B in downstream.sync but B does not list A as upstream.
published topic with no consumer in the monorepo.
A.upstream lists B, but B does not call A and shares no event with it.
```

--------------------------------

### After: Legacy handler with inline pragmas removed

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of the same legacy Go code after inline pragmas have been removed.

```go
package legacy

func ProcessOrderV1(ctx context.Context, o Order) error {
    repo.Save(ctx, o)
    publisher.Publish(ctx, OrderProcessedV1{ID: o.ID})
    return nil
}

func ProcessRefundV1(ctx context.Context, r Refund) error {
    repo.Save(ctx, r)
    publisher.Publish(ctx, RefundProcessedV1{ID: r.ID})
    return nil
}

func CancelOrderV1(ctx context.Context, id string) error {
    o, err := repo.Load(ctx, id)
    if err != nil {
        return err
    }
    o.Status = "cancelled"
    repo.Save(ctx, o)
    publisher.Publish(ctx, OrderCancelledV1{ID: id})
    return nil
}

func RetryShipmentV1(ctx context.Context, id string) error {
    s, err := repo.Load(ctx, id)
    if err != nil {
        return err
    }
    repo.Save(ctx, s)
    publisher.Publish(ctx, ShipmentRetriedV1{ID: id})
    return nil
}

func ArchiveOrderV1(ctx context.Context, id string) error {
    repo.Save(ctx, Order{ID: id, Archived: true})
    publisher.Publish(ctx, OrderArchivedV1{ID: id})
    return nil
}
```

--------------------------------

### After: SERVICE_MAP.yaml with declarative exception

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of SERVICE_MAP.yaml with a declarative exception covering the legacy package.

```yaml
exceptions:
  - rule: AI-002
    scope:
      path: "internal/legacy/**"
    reason: "legacy v1 publish path; will be removed when v2 GA ships"
    approved_by: "@alice"
    adr: "docs/adr/0051-legacy-v1-publish-path.md"
    expires: "2026-09-30"
```

--------------------------------

### Scaffolding

Source: https://github.com/krus210/archspec/blob/main/docs/EXTENDING.md

Directory structure for the Python linter example.

```text
linters/python/
├── README.md
├── archspec_python_linter/
│   ├── __init__.py
│   ├── __main__.py
│   ├── finding.py
│   ├── servicemap.py
│   └── handler_idempotency.py
├── pyproject.toml
└── testdata/
    └── handler_idempotency/
        ├── ok/
        │   ├── SERVICE_MAP.yaml
        │   └── app.py
        └── bad/
            ├── SERVICE_MAP.yaml
            └── app.py
```

--------------------------------

### Inline Exception for Backfill Script

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of using an inline pragma to bypass the outbox for a one-time migration job.

```go
// archspec:ignore-block AI-002 -- backfill: events emitted post-write
// during the cutover from direct-publish to outbox.
func runBackfillFor(ctx context.Context, ids []string) error {
    for _, id := range ids {
        item, err := repo.Load(ctx, id)
        if err != nil {
            return err
        }
        if err := repo.Save(ctx, item); err != nil {
            return err
        }
        if err := publisher.Publish(ctx, item.toEvent()); err != nil {
            return err
        }
    }
    return nil
}
```

--------------------------------

### DEP-001 - write-path x events consistency example

Source: https://github.com/krus210/archspec/blob/main/CHANGELOG.md

Conditions flagged by the DEP-001 check for write-path and events consistency.

```yaml
consistency.write_path.pattern == "outbox" and events.published == []
events.published != [] and pattern is direct
```

--------------------------------

### SERVICE_MAP.yaml example for handler idempotency

Source: https://github.com/krus210/archspec/blob/main/docs/EXTENDING.md

A sample SERVICE_MAP.yaml file demonstrating the configuration for service metadata, API endpoints, and idempotency settings.

```yaml
metadata:
  schema_version: "1.0"
  source_of_truth: local
  drift_check_in_ci: true
  last_reviewed: "2026-04-25"
service:
  name: orders
  team: payments
  language: python
  repo: github.com/example/orders
  domain: orders
  ownership: { primary: "@alice", oncall: "@oncall" }
  responsibilities: ["accept order requests"]
  invariants: ["idempotent create"]
api:
  version: 1
  endpoints:
    - name: create_order
      protocol: HTTP
      idempotency:
        required: true
        key_source: "header: X-Idempotency-Key"
        storage: redis
      contract: "openapi/orders.yaml#/paths/~1orders/post"
      sla: { p99_latency: "200ms", availability: "99.9%" }
  changelog: []
dependencies:
  upstream: []
  downstream: { sync: [], async: [] }
  storage: []
events: { published: [], consumed: [] }
consistency:
  model: eventual
  bounded_aggregate: order
  write_path: { pattern: outbox }
  read_path: { consistency: eventual }
  cross_service_invariants: []
concurrency: { aggregates: [], hot_keys: [], shared_state: [] }
```

--------------------------------

### DET-006 - TODO catcher example

Source: https://github.com/krus210/archspec/blob/main/CHANGELOG.md

Example of fields flagged by the DET-006 check for literal 'TODO'.

```yaml
dependencies.downstream.sync[].timeout
dependencies.storage[].name
events.{published,consumed}[].contract
api.endpoints[].contract
api.endpoints[].sla.{p99_latency,availability}
```

--------------------------------

### Standalone skills installation

Source: https://github.com/krus210/archspec/blob/main/README.md

Alternative installation method for archspec by cloning the repository and creating symbolic links to the skills directory.

```bash
git clone https://github.com/krus210/archspec
ln -s "$PWD/archspec/skills/architecture-sync"        ~/.claude/skills/
ln -s "$PWD/archspec/skills/architecture-investigate" ~/.claude/skills/
```

--------------------------------

### Manual Invocation

Source: https://github.com/krus210/archspec/blob/main/linters/go/README.md

Example of how to manually invoke the Go linters from within the linters/go/ directory.

```bash
go run ./linters/go <subcommand> --service-map docs/SERVICE_MAP.yaml --code .
```

--------------------------------

### Folder Layout

Source: https://github.com/krus210/archspec/blob/main/docs/EXTENDING.md

Illustrates the directory structure for adding new linters, with the Go linter as an example and a placeholder for new language linters.

```tree
linters/
├── go/                       (ships day one)
│   ├── README.md
│   ├── main.go
│   ├── handler_idempotency.go
│   ├── outbox_pattern.go
│   ├── optimistic_locking.go
│   └── testdata/
└── <your-language>/          (add yours here)
    ├── README.md
    ├── ...                   (any language and build system)
    └── testdata/
```

--------------------------------

### Full Service Map Example

Source: https://github.com/krus210/archspec/blob/main/docs/SERVICE_MAP_SPEC.md

A realistic Service Map file exercising every optional section, demonstrating various configurations for service metadata, API endpoints, dependencies, storage, events, consistency, concurrency, edge cases, scenarios, failure modes, and exceptions.

```yaml
metadata:
  schema_version: "1.0"
  source_of_truth: local
  drift_check_in_ci: true
  last_reviewed: "2026-04-25"
service:
  name: listings-service
  team: marketplace
  language: go
  repo: github.com/example/listings-service
  domain: listings
  ownership:
    primary: "@alice"
    oncall: "@listings-oncall"
  responsibilities:
    - "expose REST API for listings"
    - "publish ListingCreated events"
  invariants:
    - "all writes go through the outbox"
    - "listing IDs are monotonic"
api:
  version: 2
  endpoints:
    - name: CreateListing
      protocol: HTTP
      idempotency:
        required: true
        key_source: header:Idempotency-Key
        key_ttl: "24h"
        storage: redis
        on_duplicate: return_original
      contract: openapi/listings.yaml#/paths/~1listings/post
      sla:
        p99_latency: "200ms"
        availability: "99.9%"
    - name: GetListing
      protocol: HTTP
      idempotency:
        required: false
      contract: openapi/listings.yaml#/paths/~1listings~1{id}/get
      sla:
        p99_latency: "100ms"
        availability: "99.95%"
  changelog: []
dependencies:
  upstream:
    - api-gateway
  downstream:
    sync:
      - service: pricing-service
        timeout: "300ms"
        retries: 2
        fallback: "cache"
        on_failure: "degrade"
    async:
      - topic: "listings.created"
        contract: "schemas/listing_created.json"
        qos: at-least-once
  storage:
    - type: postgres
      name: listings_db
      owned_by: listings-service
    - type: redis
      name: idempotency_cache
      owned_by: listings-service
events:
  published:
    - topic: "listings.created"
      contract: "schemas/listing_created.json"
      version: 1
  consumed:
    - topic: "users.deleted"
      contract: "schemas/user_deleted.json"
      expected_version: 1
consistency:
  model: eventual
  bounded_aggregate: listing
  write_path:
    pattern: outbox
  read_path:
    consistency: read-your-writes
  cross_service_invariants:
    - "a listing always has a valid owner_id"
concurrency:
  aggregates:
    - name: listing
      write_strategy: optimistic
  hot_keys:
    - "listing:popular"
  shared_state:
    - "idempotency_cache"
edge_cases:
  - id: EC-001
    description: "duplicate listing creation"
    test: "internal/handler/listing_test.go::TestEC001"
scenarios:
  - id: S-001
    description: "happy path create listing"
    test: "tests/e2e/scenario_001_test.go"
    monitor: "synthetic-ms-listings-create"
failure_modes:
  - when: "kafka unavailable"
    user_sees: "create succeeds, indexer eventually catches up"
    detection: "lag metric > 30s"
exceptions:
  - rule: AI-001
    scope:
      endpoint: "GET /admin/health"
    reason: "internal admin endpoint, no client retries"
    approved_by: "@alice"
    adr: "docs/adr/0042-skip-idempotency-on-admin.md"
    expires: "2026-12-31"

```

--------------------------------

### Minimal Service Map Example

Source: https://github.com/krus210/archspec/blob/main/docs/SERVICE_MAP_SPEC.md

The smallest file that passes DET-001, demonstrating the basic structure of a service map specification.

```yaml
metadata:
  schema_version: "1.0"
  source_of_truth: local
  drift_check_in_ci: true
  last_reviewed: "2026-04-25"
service:
  name: minimal-service
  team: platform
  language: go
  repo: github.com/example/minimal-service
  domain: example
  ownership:
    primary: "@alice"
    oncall: "@oncall"
  responsibilities:
    - "expose REST API"
  invariants:
    - "all writes go through the outbox"
api:
  version: 1
  endpoints: []
  changelog: []
dependencies:
  upstream: []
  downstream:
    sync: []
    async: []
  storage: []
events:
  published: []
  consumed: []
consistency:
  model: eventual
  bounded_aggregate: example
  write_path:
    pattern: outbox
  read_path:
    consistency: eventual
  cross_service_invariants: []
concurrency:
  aggregates: []
  hot_keys: []
  shared_state: []

```

--------------------------------

### Try it

Source: https://github.com/krus210/archspec/blob/main/examples/go-microservice-fixture/README.md

Commands to validate the service map and build the Go service.

```bash
cd examples/go-microservice-fixture
"$(git rev-parse --show-toplevel)/bin/archspec-python" \
  ../../skills/architecture-sync/scripts/validate_servicemap.py docs/SERVICE_MAP.yaml
go build ./...
```

--------------------------------

### Run Sync Entry Point

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-sync/SKILL.md

Executes the main synchronization script to regenerate diagrams and ARCHITECTURE.md.

```bash
${CLAUDE_PROJECT_DIR}/bin/archspec-python ${CLAUDE_PROJECT_DIR}/skills/architecture-sync/scripts/sync.py docs/SERVICE_MAP.yaml docs
```

--------------------------------

### Declarative Exception Example

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of adding a declarative exception for an admin endpoint that does not require idempotency.

```yaml
api:
  endpoints:
    - name: GetAdminHealth
      protocol: HTTP
      idempotency:
        required: false
      contract: "openapi/admin.yaml#/paths/~1admin~1health/get"
      sla: { p99_latency: "50ms", availability: "99.99%" }

exceptions:
  - rule: AI-001
    scope:
      endpoint: "GET /admin/health"
    reason: "internal admin endpoint, no client retries possible"
    approved_by: "@alice"
    adr: "docs/adr/0042-skip-idempotency-on-admin.md"
    expires: "2026-12-31"
```

--------------------------------

### Bootstrap: Auto-discover Go Services

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-sync/SKILL.md

Command to run the Go service scanner to auto-discover endpoints, downstream syncs, storage, and events.

```bash
${CLAUDE_PROJECT_DIR}/bin/archspec-python ${CLAUDE_PROJECT_DIR}/skills/architecture-sync/scripts/scan_go.py . > /tmp/archspec-scan.json
```

--------------------------------

### Run all suites

Source: https://github.com/krus210/archspec/blob/main/benchmarks/README.md

This command executes all defined benchmark suites.

```bash
./benchmarks/run.sh
```

--------------------------------

### Full local check for release

Source: https://github.com/krus210/archspec/blob/main/CONTRIBUTING.md

Commands to run a full local check before creating a release.

```bash
.venv/bin/ruff check .
.venv/bin/python -m pytest -q
```

--------------------------------

### Inline Exception for Single Statement

Source: https://github.com/krus210/archspec/blob/main/docs/EXCEPTIONS.md

Example of using a line-scoped inline pragma for a single statement.

```go
key := r.Header.Get("X-Idempotency-Key")
if key == "" {
    // archspec:ignore AI-001 -- legacy clients without the header are
    // allowed to retry; we hash the body instead.
    key = hashBody(r.Body)
}
```

--------------------------------

### AI-002 Outbox Pattern Migration Suppression

Source: https://github.com/krus210/archspec/blob/main/docs/VALIDATION_RULES.md

Example of inline suppression for AI-002 for migration scripts.

```go
// archspec:ignore AI-002 -- migration: backfill outbox
```

--------------------------------

### Bootstrap a service

Source: https://github.com/krus210/archspec/blob/main/README.md

Command to initialize archspec for a new service, creating the necessary configuration files and hooks.

```bash
cd path/to/your-service
/archspec:init
```

--------------------------------

### AI-001 Idempotency Exception Suppression

Source: https://github.com/krus210/archspec/blob/main/docs/VALIDATION_RULES.md

Example of inline suppression for AI-001 when it applies to a single function.

```go
// archspec:ignore AI-001 -- <reason>
```

--------------------------------

### Bootstrap: Copy Seed Files

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-sync/SKILL.md

Commands to create necessary directories and copy template files for service mapping and schema definition during the bootstrap process.

```bash
mkdir -p docs/adr docs/diagrams .servicemap
cp ${CLAUDE_PROJECT_DIR}/skills/architecture-sync/templates/SERVICE_MAP.template.yaml docs/SERVICE_MAP.yaml
cp ${CLAUDE_PROJECT_DIR}/skills/architecture-sync/schema/servicemap.schema.json .servicemap/schema.json
```

--------------------------------

### Sequence Diagram Jinja Interaction

Source: https://github.com/krus210/archspec/blob/main/CHANGELOG.md

Example of Jinja template interaction causing newline issues in sequence diagrams.

```jinja
{% if ep.is_read %}read{% else %}write{% endif %}
```

--------------------------------

### Check Architecture Script

Source: https://github.com/krus210/archspec/blob/main/skills/architecture-sync/SKILL.md

Command to run the architecture audit script.

```bash
${CLAUDE_PROJECT_DIR}/bin/archspec-python \
  ${CLAUDE_PROJECT_DIR}/skills/architecture-sync/scripts/check_architecture.py \
  <repo-root> [--issues-only|--full]
```

--------------------------------

### Run a single suite

Source: https://github.com/krus210/archspec/blob/main/benchmarks/README.md

To run a specific benchmark suite, use the --suite flag followed by the suite name.

```bash
./benchmarks/run.sh --suite determinism
./benchmarks/run.sh --suite schema
./benchmarks/run.sh --suite violations
```

--------------------------------

### DET-001: Schema validation example

Source: https://github.com/krus210/archspec/blob/main/docs/VALIDATION_RULES.md

Illustrates common failures in schema validation for SERVICE_MAP.yaml, such as missing keys, wrong types, unknown properties, and pattern mismatches.

```text
metadata.last_reviewed: 2026-4-25 (must be YYYY-MM-DD)
```

--------------------------------

### app.py example for handler idempotency

Source: https://github.com/krus210/archspec/blob/main/docs/EXTENDING.md

A Python FastAPI application snippet where the handler does not read the idempotency key from the request headers, intended to trigger a linting rule.

```python
from fastapi import FastAPI, Request

app = FastAPI()


@app.post("/orders")
async def create_order(request: Request):
    payload = await request.json()
    return {"id": payload.get("id")}
```

--------------------------------

### DET-003: Test and contract path existence example

Source: https://github.com/krus210/archspec/blob/main/docs/VALIDATION_RULES.md

Highlights common failures in test and contract path existence, such as deleted/renamed files, incorrect separators, and outdated references.

```text
internal\handler\foo_test.go
```

--------------------------------

### Creating a GitHub release

Source: https://github.com/krus210/archspec/blob/main/CONTRIBUTING.md

Command to create a GitHub release using the gh CLI.

```bash
gh release create vX.Y.Z --title "vX.Y.Z — title" --notes "..."
```