The Bridge Layer: Command Reference — Vocabulary, Output Contract, and Repository Standard

This page is the reference companion to The Bridge Layer: the command vocabulary, the JSON output contract, the resolution rules, and the repository standard that binds them together. Read the essay for the argument; look things up here.

The Pattern in One Page

One set of commands runs everywhere and adapts to its context. Not one command per tool, not one command per repository type — one vocabulary that detects where it is running, adapts its behaviour, returns structured output for agents, returns readable output for developers, and works with any IDE, harness, or orchestrator.

The command name is stable. The binding is per-repository. validate means the same thing in every repository, even though it runs different tools underneath.

Four layers, each with a non-overlapping responsibility:

The Command Contract

That contract buys five properties: consistency (every command behaves predictably), discoverability (help explains everything), portability (any consumer can call any command), adaptability (commands adjust to context), and observability (every invocation emits a structured record).

The Command Catalogue

Each command is a contract — a promise about what the repository can be asked to do. The implementation lives in the repository; the contract lives in the interface. The set is finite because validation is a fixed set of questions, not a fixed set of tools: the tool answering "are the tests passing?" changes by language; the question does not.

Core Lifecycle Commands

Quality Check Commands

Build and Package Commands

Workflow Commands

Discovery and Navigation Commands

Observability Commands

Agent-Specific Commands

Validation Profiles

Different contexts need different validation depths. The repository declares which checks belong to which profile.

Is the Catalogue Complete?

No, and it should not try to be. The lifecycle commands (status, capabilities, validate, init) and the quality-check commands (lint, test, typecheck, security-scan) cover the majority of real validation workflows, and are stable and defensible. session and repair are more speculative: they assume agent identity is tracked at the interface level, which may belong instead to the harness or to session context — they remain useful as contracts even if implementation is deferred.

Candidate additions worth considering:

• watch — continuous validation on file change (useful for agent daemon mode)
• diff — semantic diff of validation results between two refs (regression detection)
• plan — return an execution plan without running it (composition of --dry-run across all checks)
• costs — estimated token/time/resource cost of a validation run (budget-aware agents)

What matters is that the core is finite and the extension mechanism is defined: repositories extend the vocabulary with an x-<namespace> prefix (for example x-migrate-db).

The JSON Output Contract

When an agent invokes validate, it needs to answer: which checks passed and which failed? What is the severity of each failure? Is this failure retryable, or does it need a human? What is the suggested remediation?

Exit codes and text cannot be parsed reliably. Structured JSON with behavioural annotations — retryable, user_fixable, ai_guidance — gives the agent a recovery contract. The same JSON feeds the human console.

The Output Schema

{
  "command": "validate",
  "session_id": "abc-123",
  "repository": "auth-service",
  "binding": "<command-definitions>/validate",
  "profile": "standard",
  "status": "failed",
  "duration_ms": 12450,
  "checks": [
    {
      "name": "linting",
      "tool": "ruff",
      "status": "failed",
      "severity": "error",
      "retryable": false,
      "user_fixable": true,
      "ai_guidance": "Run 'ruff check . --fix' to auto-remediate 12 of 15 issues. 3 require manual review.",
      "repair": {
        "command": "ruff check . --fix",
        "confidence": "high",
        "estimated_issues_fixed": 12,
        "remaining_manual": 3,
        "manual_guidance": "Review E501 violations in src/auth.py and src/models.py"
      },
      "details": {
        "files": ["src/auth.py:42", "src/models.py:18"],
        "rule": "E501",
        "message": "Line too long"
      }
    }
  ],
  "metrics": {
    "total_checks": 4,
    "passed": 3,
    "failed": 1,
    "duration_ms": 12450
  }
}

Field Definitions

Top-level fields:

Per-check fields:

Repair object:

The Recovery Contract

This turns validation from a gate into a guided workflow. The agent does not just learn what failed — it learns what to do next.

The Execution Flow

A typical validation, end to end:

Resolution Rules

When a command is invoked, resolution happens in this order. The most specific definition wins: repository file → adapter → interface default.

1. Explicit wins. If <command-definitions>/<name> exists, it runs. Period.
2. Adapters fill gaps. With no explicit command, check the repository's adapters for language defaults — templates that know how to lint, test, and typecheck a given language.
3. Built-in defaults. With no adapter, the interface supplies sensible defaults for known commands, auto-detecting the repository type and doing the right thing.

The command is intelligent, not the user. No configuration mapping to parse — the file either exists or it does not.

The Repository Standard

The standard is deliberately minimal: one directory at the repository root, containing files and folders with conventional names. No TOML, no schema.

The rule is simple: if a file exists at <command-definitions>/<name>, it is the implementation of <name>. No indirection, no mapping. The file's existence is the per-repository binding.

Anatomy of a Command

A command is any executable file — bash, Python, Node, anything the system can run. The contract is three lines long:

1. Input: receive arguments and environment variables
2. Output: print JSON to stdout (with --json) or human-readable text
3. Exit code: 0 = success, non-zero = failure

#!/bin/bash
# <command-definitions>/validate
# This file IS the binding. It validates THIS repository.

set -e

# Detect what kind of repo this is
if [ -f "pyproject.toml" ]; then
    TYPE="python"
elif [ -f "package.json" ]; then
    TYPE="node"
elif [ -f "Cargo.toml" ]; then
    TYPE="rust"
else
    TYPE="generic"
fi

# Run validations based on type
case $TYPE in
    python)
        echo '{"step": "lint", "tool": "ruff"}' >&2
        ruff check . --output-format=json || true

        echo '{"step": "test", "tool": "pytest"}' >&2
        pytest --tb=short || true
        ;;
    node)
        npm run lint
        npm test
        ;;
    *)
        echo "No validation configured for $TYPE" >&2
        exit 1
        ;;
esac

# Output final status (interface helpers can format this)
echo '{"status": "complete", "command": "validate"}'

The maintainer writes this once. Tools, IDEs, and agents then run validate and get consistent results.

The Per-Repository Binding

The critical insight is that there is no indirection.

Traditional:  config.toml → "validate" → "make validate" → actual command
                 (indirection 1)   (indirection 2)

Bridge layer: <command-definitions>/validate → actual command
                 (no indirection)

That gives four properties: self-documenting (reading the file shows exactly what runs), version-controlled (commands live in the repository, with full history), debuggable (run the file directly during development), and portable (copy the command directory to any repository and it works).

Minimal Adoption

# Step 1: Create the directory
mkdir -p <command-definitions>

# Step 2: Create one command
cat > <command-definitions>/validate << 'EOF'
#!/bin/bash
echo "Validating..."
pytest
EOF
chmod +x <command-definitions>/validate

# Step 3: Run it
validate
# Output: Validating...
#         [pytest output]

No schema to learn. Just files.

Transparency and Discoverability

A command interface is only as useful as it is discoverable. Every command in the vocabulary — core primitive or repository extension — must be visible, understandable, and actionable. Agents have no intuition; they need explicit contracts:

1. What commands exist? → capabilities returns the full vocabulary
2. What does each command do? → help <command> returns description, arguments, examples
3. How do I use it? → the output contract states what to expect

Built-in defaults are living templates. Even when a repository declares nothing, the interface's defaults show exactly what would run:

{
  "commands": [
    {
      "name": "validate",
      "description": "Run quality gate validation",
      "source": "default",
      "detected_type": "python",
      "implementation": "ruff check . && pytest && mypy ."
    },
    {
      "name": "commit",
      "description": "Commit with validation",
      "source": "default",
      "detected_type": "git",
      "implementation": "validate --profile quick && git commit"
    }
  ]
}

The source and implementation fields tell the human and the agent exactly what will run: no surprises, a template to copy into a repository binding, and a pattern agents can learn from.

Customization is highlighted. When a repository does declare a command, the interface must say so at invocation:

$ validate
▶ Using repository binding: <command-definitions>/validate
  (the default would have run: ruff check . && pytest)

Running custom validation...
[output from <command-definitions>/validate]

That matters for four reasons: the user knows they are not running default behaviour; when something breaks they know where to look; they see what the default would have done, which tells them whether their customization is necessary; and agents get an explicit signal about binding resolution, enabling better error recovery and reasoning.

Help output is a contract. Every command supports help <command>:

NAME
  validate - Run quality gate validation

SYNOPSIS
  validate [--profile <name>] [--json] [--dry-run]

DESCRIPTION
  Runs the repository's validation suite, which may include linting,
  type checking, tests, and security scans. The exact checks depend on
  the repository's command definition or the default for the detected
  repository type.

OPTIONS
  --profile <name>    Validation profile: quick, standard, full, audit
  --json              Machine-readable output
  --dry-run           Show what would be run without executing

OUTPUT CONTRACT
  Returns structured JSON with:
  - status: passed | failed
  - checks: array of check results
  - repair: suggested remediation commands

EXAMPLES
  validate                    # Run with default profile
  validate --profile quick    # Fast validation (lint only)
  validate --json             # Machine-readable output

SEE ALSO
  capabilities    List all available commands
  help commit     Learn about the commit command

The help output is simultaneously human documentation, agent prompt context, a contract specification, and the reference a maintainer compares against when overriding behaviour. Five transparency principles follow: all commands are visible (capabilities), all commands are documented (help <command>), the binding source is transparent (repository definition, adapter, or default), the implementation is inspectable, and customisation is highlighted.

The Console: A Consumer, Not an Invoker

The console does not invoke commands. It consumes their output. The interface is the producer; the console is the consumer. That decoupling means the console can be built independently, and can aggregate across repositories without knowing how any particular repository runs its checks.

Every invocation emits a structured record capturing the command name and arguments, the binding resolved, duration, check results, and agent identity. Observability becomes a byproduct of the command interface, not an add-on.

What the Console Enables

• Fleet-wide visibility: a platform team monitors 200 repositories through a single console and sees that 12 have failing security scans, 5 have stale validation results, and 3 have agents in retry loops.
• Autonomous remediation: an agent detects a linting failure, invokes validate --profile quick, reads the repair field, applies the suggested fix, and re-validates — without human intervention.
• Trend analysis: validation failure rates over time, by check type and by repository, surfacing systemic issues that per-repository tools cannot see.
• Tool migration without disruption: a team switches harnesses. They rewrite 5 lines in their wrapper plugin. The repository logic is untouched.

Two Consumers, One Output

The same structured output serves both:

• Agents parse the JSON for behavioural annotations (retryable, repair, ai_guidance) and act autonomously.
• Human operators view the same data through a console that renders pass/fail grids, trend charts, and drill-down views.

There is no separate "AI output" and "human output." There is one contract, rendered two ways — so any change to the contract is automatically visible to both consumers.

Wrappers Stay Thin

A wrapper does three things: calls <command> --json, parses the JSON, and maps the result to the host tool's native format. Because it contains no repository logic, it never changes when the repository changes — only when the host tool's API changes.

Wrappers can be packaged with emerging plugin standards so they install into IDEs, harnesses, and agents without custom distribution work. Where no standard exists yet, a declarative manifest is enough:

{
  "name": "validate-plugin",
  "version": "1.0.0",
  "description": "Validate repository quality gates",
  "commands": {
    "validate": {
      "invoke": "bridge",
      "args": ["validate", "--json"]
    }
  }
}

Glossary

Further Reading

• The Bridge Layer — the essay this page accompanies
• Software Design Principles — the design discipline the command contract applies
• Prompt Structure for the Software Orchestrator — how agents consume explicit contracts
• Engineering Structure for the Software Orchestrator — where repository-level definitions live
• Workflow Structure for the Software Orchestrator — the gates these commands expose
• The DevOps Engineer's Guide to Effective AI Usage — aibook.ocooee.com