The First NexFlow CLI Should Refuse to Run Agents — A Practical Guide for Developers

This guide explains why the initial NexFlow CLI should be a validation-and-inspection tool only, and gives a practical implementation workflow for building a stable, review-friendly CLI that refuses to run agents. It covers required commands, output schema, testing, common failure modes, and trade-offs for teams integrating NexFlow into editor tooling and CI.

Why refuse to run agents in the first CLI?

When a specification project gains a CLI, users will expect it to execute the system. For NexFlow, however, launching agents from the first public CLI creates two problems: it turns early implementation choices into de facto specification decisions, and it raises safety/credential/permission questions before the spec’s runtime behavior is defined. The speculative runtime concerns include storage semantics, credential isolation, policy enforcement, event logging, and error-handling defaults — all areas the spec aims to settle deliberately.

Starting with a validation-only CLI reduces risk and preserves a specification-first workflow: make manifests readable and machine-checkable, iterate on diagnostics and semantic checks, and only then design a runtime whose defaults are informed by real-world validation patterns.

Required command surface for a validation-only NexFlow CLI

RFC-0011 (reference implementation guidance) proposes a minimal command set. Each command must be strictly non-executing and limited to static analysis or local file operations.

• validate — Parse manifests, run schema validation, and run bounded semantic checks. Must not call providers, start processes, or read external systems beyond explicit, opt-in discovery paths.
• inspect — Present a compact, human-readable summary of declared manifests, actors, permissions, extensions, and any fields that imply runtime actions (for example, execute_command or auto-updating memory). Must not resolve secrets or contact external servers.
• graph — Emit a static, deterministic relationship map between tasks, actors, permissions, handoffs and declared artifacts; can produce plain text, DOT, or JSON. Must not infer runtime ordering from dynamic signals or execute task code.
• init — Create a provider-neutral starter manifest set in a target directory. It may write YAML files locally but must refuse to overwrite conflicting files unless an explicit overwrite mode is provided.

Implementation workflow — step-by-step

1. Pin schema and examples

   Start with the repository’s published manifest version (for example, v0.1.0) and the maintained examples. Lock the validator to this spec version so diagnostics are stable across environments.

2. Design deterministic discovery

   Require an explicit path argument for project discovery. Do not walk parent directories by default or merge arbitrary YAML files. Accept exactly one of: a manifest bundle file, a project directory, or a defined manifest list. Record and report the discovered inventory.

3. Implement structural schema validation

   Use the published JSON Schemas to validate manifests. For each failure, emit a structured diagnostic with severity, stable error code, file path, manifest kind, YAML/JSON path, and a concise message. Provide both human-readable output and a machine-readable format (JSON).

4. Add bounded semantic checks

   Implement the non-executing cross-manifest reference smoke checks already present in the repository: missing or duplicate references, unresolved targets, and obvious ambiguities. Keep a clear list of checks run and mark which semantic checks remain out-of-scope.

5. Expose inspect and graph summaries

   Return a compact map of declared agents, tasks, permissions, integrations and fields that imply runtime actions. Graph output should show static edges only — e.g., task dependencies and actor assignments — without attempting to infer live state, execution order, or authority resolution.

6. Provide stable machine contract

   Standardize a JSON diagnostic contract. An example machine entry should include fields such as:

   { "severity": "error", "code": "NF-SCHEMA-REQUIRED", "file": "examples/minimal-team/agents.yaml", "kind": "AgentSet", "path": "$.agents[0].id", "message": "Required field is missing." }

   Use stable codes to avoid CI breakage when wording changes.

7. Document scope and limitations

   Every successful run must include a summary of which checks executed and which checks were intentionally skipped (e.g., credential validation, runtime policy checks, external provider conformance). Make the CLI refuse to run agents and state that refusal explicitly in output when users query for runtime features.

Edge cases, trade-offs and common failure modes

Discovery mismatches

Problem: A developer gets different validation results locally and in CI because discovery walked different files.

Mitigation: Record and print the exact file inventory used. Make discovery deterministic by default and allow an explicit bundle file or file list for CI. Avoid implicit merging from parent directories.

Partial semantic checks

Problem: Passing schema validation may give a false sense of safety when deeper semantics (policy, approval sufficiency, authority) are not verified.

Mitigation: Always list executed checks in the report. Return a non-zero code when required semantic checks — defined by the CLI release notes — are missing. Do not mark a manifest set as fully conformant unless the CLI implements a published conformance level.

Over-eager inspect output

Problem: Inspecting manifests could inadvertently reveal secrets or trigger external lookups.

Mitigation: Never resolve secret references or contact external systems. Treat inspect as a local, static projection. For fields that reference external servers or credentials, surface only the reference name and a caution that resolution was not attempted.

Errors presented as opaque text

Problem: Validators that only print human prose frustrate editor integrations and CI parsing.

Mitigation: Emit both a readable summary and a structured JSON output with stable diagnostic codes, file paths, and YAML/JSON pointers for editor tooling and SARIF conversion.

Testing and validation checklist

• Unit tests for schema validation with both valid and invalid example files from the repository.
• Integration tests for deterministic discovery and explicit inventory reporting (local vs CI mirroring).
• Tests that inspect refuses to resolve secrets and never performs network I/O.
• Unit tests for JSON diagnostic contract and stable error codes.
• Smoke tests that confirm init refuses to overwrite files without an explicit flag.

Practical use cases for teams

• Editor and pre-commit hooks that run nexflow validate to catch schema problems before review.
• CI jobs that run nexflow validate –format json and annotate PRs with stable diagnostic codes.
• Code review surface: nexflow inspect to get a compact project map without requiring reviewers to open dozens of files.
• Dependency audits: nexflow graph to detect missing handoffs or isolated tasks before attempting automation design.

Short FAQ

Q: If the CLI refuses to run agents, how will teams try automation locally?

A: The validation CLI is explicitly an inspection and review tool. Runtime implementations and provider integrations are a subsequent project that should be designed after observing common manifest patterns and validation failures.

Q: Won't users ask for agent execution anyway?

A: Yes. The CLI should state the limitation clearly and provide guidance: run validation/inspect/graph to prepare manifests for a future runtime; do not expect the CLI to start agent processes or contact model providers.

Q: Should init create provider configuration files or credentials?

A: No. init should be provider-neutral. It can create manifest stubs but must not configure cloud services or store secrets.

Conclusion

Building the first NexFlow CLI as a validation-and-inspection tool preserves the specification-first intent, prevents accidental standardization of dangerous defaults, and produces stable tooling that teams can rely on for editor and CI workflows. The recommended command set — validate, inspect, graph, and init — combined with deterministic discovery, structured diagnostics, and clear scope reporting, gives reviewers and integrators a stable foundation while keeping runtime decisions explicit and deferred.