SharpClawCode: Instructions file for Codex

AGENTS.md

Project Identity

SharpClaw Code is a C#-native coding-agent harness inspired by the current Rust claw-code surface.

Primary stack:

• .NET 10
• C# 13
• Microsoft Agent Framework
• System.CommandLine
• Spectre.Console
• System.Text.Json
• Microsoft.Extensions.Hosting
• idiomatic Microsoft dependency injection

This repository should grow into a production-grade, cross-platform agent runtime with strong Windows compatibility. Favor concrete, maintainable architecture over framework-heavy indirection.

Current Repository State

The repository may begin sparse or empty. Before implementing anything:

1. Inspect the current solution and folder layout.
2. Align new work to what already exists unless the user explicitly asks for restructuring.
3. If the intended architecture is not present yet, create the smallest real vertical slice that establishes it cleanly.

Do not scaffold broad placeholder trees with no executable value.

Non-Negotiable Engineering Rules

• Target .NET 10 and C# 13.
• Prefer clear, explicit, strongly typed code over clever abstractions.
• Use async/await end-to-end anywhere I/O or external process work exists.
• Use records for immutable contracts where appropriate.
• Use interfaces for infrastructure seams and runtime orchestration seams.
• Avoid unnecessary repository patterns and avoid overengineered CQRS.
• Keep domain and protocol contracts dependency-light.
• Use System.Text.Json, never Newtonsoft.Json.
• Use Microsoft.Extensions.Logging abstractions for logging.
• Prefer file-scoped namespaces.
• Favor small, testable classes with focused responsibilities.
• Preserve machine-readable state and JSON output support across major features.
• Route dangerous shell execution or file mutation through an explicit permission policy layer.
• Model long-running or lifecycle-managed subsystems explicitly and use hosted services where appropriate.
• Build for cross-platform support, with strong Windows behavior and path/process compatibility.
• Do not hardcode secrets, API keys, tokens, or machine-specific paths.
• Add concise XML docs for all public APIs and major internal services.
• Add TODO comments only when paired with a concrete reason.