A01SuperIntelligenceBuilder

One real method. An imaginary API. A real coding agent.

A single C# file that sends one source-defined task to an installed command-line coding agent.

No NuGet packages. .NET 10. C# 14. Three built-in adapters.

SuperIntelligenceBuilder.WithFile("AGENTS.md")
    .CreateOrReplaceUtf8File("generated/hello.txt", "Hello, super intelligence!\n")
    .WithConciseOutput();

Only WithFile is implemented. It gives the coding agent the exact source statement; the agent interprets the invented method names and literal arguments as instructions. When C# execution resumes, the returned dynamic object accepts those invented calls without performing the named work again.

B01Run the sample

Install the .NET 10 SDK. A dry run needs only the SDK. A live run also needs one installed and authenticated coding agent.

Open a terminal in the complete project checkout, in the folder containing SuperIntelligenceBuilder.csproj.

Build and inspect

dotnet build
dotnet run

The default is a dry run. It reads the caller and instruction file, identifies the coding-agent executable it would use when one is discoverable, and prints the exact fluent statement. It does not test the agent's authentication or CLI compatibility, launch a process, create a file, or edit the workspace.

Permit a live run

dotnet run -- --yes,please,proceed

This explicit flag permits the live execution path. The sample asks the coding agent to write generated/hello.txt with Hello, super intelligence! followed by a newline.

If AGENTS.md already exists, there is a second gate before agent discovery: type exactly yes, please proceed to continue or no to stop. The comma-bearing CLI flag and the spaced terminal reply are different inputs. See Execution and completion for the full state table.

A successful run prints the agent summary and the path to its JSON completion report.

If no coding agent is installed, dry-run output says so. A permitted live run returns AgentNotFound and exits with code 3.

C00Install an agent

Install one supported command-line coding agent. You do not need all three; the builder contains the adapters.

Use the vendor installation pages for current operating-system requirements and authentication options.

The builder never installs software, signs in, or switches to another coding agent after a task starts.

D00Copy the dependency

To use the builder in another SDK-style .NET 10 project, copy SuperIntelligenceBuilder.cs into that project. The SDK includes the source file automatically.

The sample's Program.cs, project file and index.html are not library dependencies.

Keep the file's opening comment. It is the portable offline reference for installation, behavior, limits, and supported coding agents.

Run from the original source checkout. CallerFilePath stores the caller's path at compile time, and the builder reads that source file at runtime. The original source must still exist. Rebuild after moving it; a deployed binary alone cannot reconstruct the fluent statement.

E01How it works

1. WithFile locates the caller's source, resolves the workspace and Markdown instruction path, rejects unsafe paths, and reads both files.
2. Unless execution was explicitly permitted, it identifies a candidate coding-agent executable and returns the dry-run plan. No child process or output file is created.
3. On the live path, an existing instruction file requires the exact terminal reply before agent discovery continues.
4. The builder discovers the selected coding agent, probes its version and required CLI switches, and confirms the caller source has not changed.
5. It acquires the workspace lock and atomically creates a missing instruction file. The builder itself never truncates an existing file, although the fluent task may explicitly ask the coding agent to replace it.
6. It sends the coding agent the call-site path, line, member, source snapshot, instruction contents, permissions, and a unique run ID over UTF-8 standard input.
7. The builder reports completion only when the child process exits with code 0 and writes a valid run-specific report whose status is completed.

The location of WithFile is the call site. The coding agent interprets only the fluent statement at that location. After WithFile returns, the dynamic result accepts the invented method and property calls without performing the named work a second time.

F00Write useful instructions

Use legal C# identifiers, literal arguments and an explicit output path. The invented method names are instructions, not members of a fixed API.

SuperIntelligenceBuilder.WithFile("AGENTS.md")
    .WriteMarkdownFile("generated/review.md")
    .SummarizeThePublicTypesIn("src")
    .IncludeKnownLimitations()
    .DoNotModifySourceCode();

Use precise requests. The builder cannot make an ambiguous instruction deterministic.

Do not pass runtime secrets, computed values or side-effecting expressions. The coding agent receives source text, not the runtime values those expressions might produce.

Ordinary C# argument expressions still execute locally after WithFile returns. An argument that writes a file, calls a service, or reads a secret would still perform that action even though its surrounding fluent method is invented.

The returned dynamic object accepts unknown method and property calls without performing their names. Real object members retain their normal behavior. Execution returns the structured run result; awaiting the dynamic object or using arithmetic on it is unsupported.

G00Configure a run

var options = new SuperIntelligenceBuilder.Options
{
    Agent = SuperIntelligenceBuilder.AgentKind.Codex,
    Proceed = true,
    Timeout = System.TimeSpan.FromMinutes(5)
};
dynamic task = SuperIntelligenceBuilder.WithFile("AGENTS.md", options)
    .CreateOrReplaceUtf8File("generated/note.txt", "Done.\n");
SuperIntelligenceBuilder.RunResult result = task.Execution;
System.Console.WriteLine(result.Summary);

CancellationToken is a WithFile argument rather than an option. The root sample connects Ctrl+C to that token; library callers choose their own cancellation source.

Windows npm command shims are resolved through the installed package manifest and node.exe; no command shell is used.

Only absolute PATH entries are searched. Aliases, shell functions, relative entries, and nonstandard Windows shims are not supported. Set an explicit executable path when normal discovery cannot see the installation.

H02Execution and completion

Two gates before an agent can run

A live run first requires Proceed=true. The supplied command-line programs set it only for the exact flag --yes,please,proceed. If the Markdown instruction file already exists, the terminal then asks for one exact reply before agent discovery.

To continue exactly: yes, please proceed
To stop exactly:     no

y, yes, capitalization changes, extra whitespace, and other approximations do not continue. End-of-input fails closed with ConfirmationRequired. The dry run never asks for this reply.

Approval permits this one run to begin and acknowledges that the source-defined task may amend the instruction file and other workspace files. It does not approve every eventual edit, provide rollback, or replace review of the resulting diff and validation evidence.

Coding-agent permissions

Existing CLI settings, managed policy, and hooks still apply. The builder is not an operating-system sandbox for untrusted code. Prompts travel through UTF-8 standard input, and paths and source snapshots are JSON data rather than shell commands. This avoids shell interpolation; it does not prevent prompt injection from untrusted source.

Completion reports

Reports are stored under .superintelligence/runs/<run-id>/result.json.

{
  "protocol": "super-intelligence-builder/v1",
  "runId": "<run-id>",
  "status": "completed",
  "summary": "Created the requested file.",
  "changedFiles": ["generated/hello.txt"]
}

A report is an agent assertion, not independent proof that the result is correct.

Review the actual files. The self-reported changedFiles list is not a complete filesystem diff.

Timeouts, cancellation and failures can leave partial changes. The builder never rolls them back.

I01Diagnose failures

Library failures use BuilderException with a typed Error property and optional AgentExitCode. Cancellation uses OperationCanceledException; callers choose how to handle both.

J00Other coding tools

Only Codex, Claude Code and GitHub Copilot CLI have built-in adapters in this release. The tools below are a research catalog: this builder cannot launch them, does not fall back to them, and does not treat their permission models as interchangeable.

Adding an adapter requires a separate review of discovery, arguments, working-directory behavior, permissions, cancellation, and completion reporting.

K00Limits and verification

Source files are limited to 1 MiB, instruction text to 256 KiB and reports to 64 KiB; UTF-8 is required.

Symlinks and reparse points within the selected workspace path are rejected. These containment checks validate inputs; they are not an operating-system filesystem sandbox and cannot eliminate path races.

The lock coordinates only the same workspace; overlapping parent and child workspaces need external coordination.

Child processes launched by the coding agent inherit a recursion guard. If they run this builder again, the nested call returns without launching another agent.

Use ordinary JIT-compiled .NET builds. NativeAOT, trimming, and deployments without the caller's source file are outside this design.

Provider execution is nondeterministic. No builder can guarantee that natural-language requests produce correct code.

Build and runtime verification status is recorded in VALIDATION.md. No test binaries are distributed, but the record lists the builds, browser checks, guardrail cases, and authenticated agent runs that were actually performed.

L01Sources

CLI switches and installation guidance were checked against official vendor documentation on 2026-09-26.

The exact-phrase confirmation and civil diagnostic voice are inspired by Christian Hofstede-Kuhn's Bespoke: A Programming Language for People Who Say Please. This project remains ordinary C# and borrows the polite tone, not Bespoke syntax or semantics.

The manual renders offline because its styles and scripts are embedded. External documentation links and live coding-agent execution still require whatever network access their providers need.