The Agent Writes the Companion📋

QuietCli's agent guidance asks the AI to author the contents of a scriptblock. That is a substantive responsibility: the agent chooses commands, arguments, parsers, conditions, counters and the final projection. Importing the module does not determine which facts are relevant. A useful companion begins with a question and a verified output format.

The module then supplies execution machinery that the agent can reuse. Invoke-QuietCli runs a native program and applies document or streaming analysis. New-QuietResult builds the common envelope. Invoke-QuietStep records an intermediate result inside a task. Invoke-QuietTask aggregates those steps, and ConvertTo-QuietJson serializes a bounded result. These functions support the workflow; they do not replace the domain parser.

Start with the contract📋

Before selecting a command, state the required properties and what would establish them. For a repository overview, distinguish the branch name from detached state, changed entries from untracked entries, and successful analysis from a complete answer. If the request requires filenames, retain them. If it only requires counts, compute those counts without retaining an unlimited collection of paths.

Next, verify the tool's installed version and the relevant documentation. Prefer a documented machine format over terminal presentation. Reduce output at the source where that preserves the requested meaning. A path filter that changes the scope must also change the contract; it cannot silently turn a whole-repository question into a directory-only answer.

The source inspection should be saved as a reference or comment in reusable code. This gives a future reader a way to distinguish a documented format assumption from an accidental pattern observed in one run. A change to the external CLI can then trigger a focused compatibility review.

Write inspectable code📋

This small example uses the original Git command and illustrates the document callback interface. Run it after importing QuietCli:

Invoke-QuietCli -FilePath git `
    -ArgumentList @('branch', '--show-current') `
    -WorkingDirectory $repository `
    -MaxOutputBytes 2048 -Parse {
        param($capture)
        $name = $capture.Stdout.Trim()
        [pscustomobject]@{
            Branch = $name
            Detached = ($name.Length -eq 0)
        }
    } | ConvertTo-QuietJson -MaxOutputBytes 2048

The parser consumes a capture locally and returns one value. It does not print the capture. The runtime adds execution status, including the native exit code. Consumers must inspect that status before trusting the domain properties; the presence of data alone does not establish success.

Arguments are passed as a list rather than concatenated into executable shell text. Use the explicit WorkingDirectory instead of relying on an unrelated current location. When a script needs an interpreter, invoke that interpreter explicitly. These choices make quoting, effects and inputs easier to review.

A request you can give an agent📋

The following is a task instruction, distinct from the master prompt that regenerates this series:

Inspect this repository using QuietCli in PowerShell 7.4+ Core.
Define the domain data before running a command: branch, detached
state, changed tracked entries, untracked entries and cleanliness.
Verify the Git format and describe the counting scope.
Reuse a supplied companion if it satisfies this contract.
Otherwise write an inspectable companion using documented formats.
Process native output locally. Register locally consumed results
with Invoke-QuietStep inside Invoke-QuietTask.
Return one final JSON document within 2048 UTF-8 bytes.
Preserve failure, timeout, omissions and unknown values.
Do not infer zero from failed or incomplete analysis.

The instruction defines the desired behavior and the review criteria. Its application still depends on the agent following it. QuietCli does not automatically intercept every command in the environment. The included SKILL.md is guidance; the runtime is executable code. Readers need the associated runtime files for examples that import them.

Check the companion before keeping it📋

Run a meaningful success case and cases that contradict convenient assumptions. For Git, use both a clean and modified repository, an untracked directory, a rename, and detached HEAD. For a JSON document, test malformed output and capture overflow. For a long stream, require a completion marker or another documented condition that establishes the necessary analysis.

Also inspect the final transmission. A task can execute correctly yet return insufficient data after its budget removes a projection. Verify the serialized UTF-8 size, Truncation, and any domain completeness fields. Label an illustrative result separately from an executed observation. The supplied runner records those observations in a report instead of asking readers to trust prose examples.

A companion should also document native exit conventions. Some tools distinguish a valid negative answer from execution failure through different exit codes. Verify that distinction before selecting accepted codes; broad acceptance can conceal an actual error. The parser still needs to validate the corresponding output and must not manufacture a positive domain answer merely because execution was permitted to complete.

Review reusable inputs as carefully as outputs. A repository path, time window or record limit changes the observation being made. Prefer explicit parameters over assumptions hidden in a profile or current directory. Keep selected diagnostics concise enough to help investigate a failure without exposing the entire capture.

Once the contract and checks hold, save the script and its assumptions together. Another task can then reuse a capability rather than recreate its parsing. Keep the unit of reuse small enough to understand: an overview companion should not silently become a general deployment decision engine. The next chapter explains how its common envelope supports that boundary.

Previous: Useful Answers · Series overview · Next: A Result Contract You Can Trust