CodeWeave

CodeWeave is a .NET 10 console application for running configurable multi-role delivery workflows across OpenAI and Claude models.

The shipped workflow library lives under CodeWeave/workflows/. The current built-in workflows are:

• bug-fix
• feature
• greenfield

The repo also includes a fully inline sample at CodeWeave/workflows/workflow-full.sample.json.

Rename Transition

This branch completes the rename from AgentHarness to CodeWeave.

• AgentHarness.sln is now CodeWeave.sln.
• AgentHarness/AgentHarness.csproj is now CodeWeave/CodeWeave.csproj.
• AgentHarness.Tests/AgentHarness.Tests.csproj is now CodeWeave.Tests/CodeWeave.Tests.csproj.
• The shipped workflow library now lives under CodeWeave/workflows/.

During the transition, startup .env discovery still falls back to a legacy AgentHarness.csproj file when resolving the project root from build output directories. Update local scripts, automation, and command snippets to the new CodeWeave* paths.

Current Capabilities

The current branch supports:

• workflow-configured role, provider, and model defaults
• inline or file-backed intake requirements
• target repository discovery from --work-dir or the current shell directory
• optional CodeGraph-backed discovery when MCP is enabled in configuration
• curated handoffs between workflow stages
• discovery, planning, implementation, QA, and post-mortem workflow loops
• configurable review fan-out, approval thresholds, round limits, and operator overrides
• execution plans that can apply patches, run build/test commands, create branches, and create commits
• session checkpoints for resume support at safe workflow boundaries
• markdown artifacts, prompt audits, handoffs, execution journals, and review audit output under the session artifact folder

Repository Layout

• CodeWeave/: the console app and shipped runtime configuration
• CodeWeave.Tests/: xUnit coverage for configuration, orchestration, execution, providers, and services
• docs/: architecture and authoring notes
• plans/: supporting schema and planning artifacts

The most important runtime files are:

• CodeWeave/appsettings.json: provider, MCP, handoff, assembly, and execution defaults
• CodeWeave/workflows/feature/workflow.json: the default shipped feature workflow
• CodeWeave/workflows/workflow-full.sample.json: fully inline workflow sample
• CodeWeave/Program.cs: configuration bootstrapping and service registration
• CodeWeave/Configuration/HarnessCommandLine.cs: CLI switch mappings
• CodeWeave/Configuration/WorkflowLibrarySelector.cs: built-in workflow library discovery and selection

Configuration

Runtime configuration is assembled in this order:

1. CodeWeave/appsettings.json
2. the selected workflow file
3. environment variables
4. command-line switches

CLI switches bind into the Harness configuration section, so environment overrides like Harness__WorkflowPath still work alongside command-line usage.

The checked-in defaults currently use API transport for both OpenAI and Claude. CLI templates are present in configuration, but they are only used if you change a provider's InvocationMode to Cli. MCP discovery is configured but disabled by default in appsettings.json.

Set provider credentials through environment variables before running:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY

If you enable the shipped CodeGraph MCP entry, also set:

• CODEGRAPH_PAT

Startup diagnostics validate any enabled CLI provider commands and MCP server requirements before orchestration begins.

CLI Arguments

CodeWeave currently exposes these command-line switches:

Argument	Value	What it does
--workflow	path to workflow.json	Selects the workflow file before workflow configuration is loaded. Supports --workflow path and --workflow=path. ~/... is expanded.
--work-dir	directory path	Sets the harness working root. This becomes the target repository path for intake, the base folder for artifacts/<session-id>, and the default working directory for CLI provider execution unless the provider config overrides it.
--resume	session id such as 20260416-211440	Resumes an existing session from artifacts/<session-id> under --work-dir or the current directory.
--prompt	inline text or a file path	Skips the interactive intake prompt. If the value points to an existing file, the file contents become the requirements; otherwise the raw string is used as the request text.
--api-timeout-seconds	integer from 30 to 3600	Sets the HTTP timeout used by API-backed providers. The default is 1200 seconds.
--socratic-interview	YES or NO	Pre-answers the optional Socratic interview confirmation. When omitted, the harness asks interactively if discovery recommends an interview.

Argument Notes

• There is currently no separate --repo or --target flag. The repository root is inferred from --work-dir, or from the current directory when --work-dir is omitted.
• --workflow and --resume interact: if a resume checkpoint already records a workflow path, an explicit --workflow override must resolve to the same file or the run stops.
• --resume is intentionally strict. The run will refuse to continue if the checkpoint is missing, the workflow was already halted, the repository root changed, the expected branch changed, or the working tree is dirty while RequireCleanGitWorkingTree is enabled.
• --prompt accepts either plain text or a path, so it doubles as a lightweight "requirements file" switch.

For a fuller operator-oriented reference, see docs/cli-reference.md.

Run

Start the harness with interactive intake:

dotnet run --project .\CodeWeave

Run against a specific repository or workspace root:

dotnet run --project .\CodeWeave -- --work-dir D:\repos\SomeTargetRepo

Skip interactive intake and pass the request inline:

dotnet run --project .\CodeWeave -- --work-dir D:\repos\SomeTargetRepo --prompt "Add startup diagnostics for MCP servers"

Use a requirements file instead of inline text:

dotnet run --project .\CodeWeave -- --work-dir D:\repos\SomeTargetRepo --prompt .\plans\feature-request.md

Run with a custom workflow file:

dotnet run --project .\CodeWeave -- --workflow .\CodeWeave\workflows\workflow-full.sample.json

Resume a previous session:

dotnet run --project .\CodeWeave -- --work-dir D:\repos\SomeTargetRepo --resume 20260416-211440

Pre-answer the Socratic interview prompt:

dotnet run --project .\CodeWeave -- --socratic-interview NO

Resume Behavior

Resume uses a session.checkpoint.json file written into each session root. In the current branch, checkpoints are written at safe boundaries such as:

• after approved discovery
• after approved planning
• between approved implementation phases
• after approved QA
• when the workflow halts on a controlled rejection or gate decision

Artifact-only reconstruction is intentionally unsupported. If the session folder exists without a valid checkpoint, resume fails instead of guessing.

Related Docs

• docs/architecture/two-concept-model.md: core architecture — Agent + Agent Loop, capabilities vs extensions. Read this first.
• docs/architecture/prompt-pipeline.md: the four-layer prompt pipeline (static → template → handoff → assembly) and why it stays layered
• docs/architecture/extension-catalog.md: shipped IAgentLoopExtension implementations + status of planned extensions
• docs/cli-reference.md: CLI switch behavior and operator notes
• docs/workflow-engine.md: workflow runtime overview
• docs/workflow-authoring.md: workflow authoring reference
• docs/context-assembly-flow.md: prompt and handoff context flow
• docs/implementation-phase-execution-flow.md: execution loop details

Build And Test

dotnet build .\CodeWeave.sln
dotnet test .\CodeWeave.sln