Skip to content

Commit 0a4e8ad

Browse files
clairernovotnyclairernovotny
committed
feat(docs): add agent guidance for .NET skills and migration plan
1 parent 92cd9d0 commit 0a4e8ad

2 files changed

Lines changed: 200 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,23 @@ docs/ # Architecture, config, quickstart
7878
- Generator scripts (`src/scripts/gen-*.sh`) read manifests to produce container artifacts
7979
- User manifests go in `~/.config/containai/manifests/` (processed at runtime)
8080

81+
# Agent Guidance: dotnet-skills
82+
83+
IMPORTANT: Prefer retrieval-led reasoning over pretraining for any .NET work.
84+
Workflow: skim repo patterns -> consult dotnet-skills by name -> implement smallest-change -> note conflicts.
85+
86+
Routing (invoke by name)
87+
- C# / code quality: modern-csharp-coding-standards, csharp-concurrency-patterns, api-design, type-design-performance
88+
- DI / config: dependency-injection-patterns, microsoft-extensions-configuration
89+
- Testing: testcontainers-integration-tests, playwright-blazor-testing, snapshot-testing
90+
91+
Quality gates (use when applicable)
92+
- dotnet-slopwatch: after substantial new/refactor/LLM-authored code
93+
- crap-analysis: after tests added/changed in complex code
94+
95+
Specialist agents
96+
- dotnet-concurrency-specialist, dotnet-performance-analyst, dotnet-benchmark-designer, docfx-specialist
97+
8198
## Code Conventions
8299

83100
- **Bash 4.0+ required** (not zsh or fish)

‎docs/cai-dotnet10-nativeaot-migration-plan.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
## Plan: Convert Runtime `cai` Bash CLI to `.NET 10` NativeAOT Single Binary with Integrated ACP
2+
3+
### Summary
4+
Migrate all **non-installer client-side runtime shell code** (`src/containai.sh` + `src/lib/*.sh`) into a well-factored `.NET 10` CLI that publishes as one native, trimmed binary: `cai`.
5+
Refactor existing `acp-proxy` command surface into `System.CommandLine` under `cai acp proxy ...` and preserve full functional capability (including undocumented runtime behavior currently embodied in shell/tests).
6+
Migrate tests to xUnit v3 (unit + ACP + key integration).
7+
Execution model uses orchestrator-led parallel subagents in separate worktrees, with mandatory review-agent passes and completion gates.
8+
**This plan is completion-bound: work keeps going until all acceptance gates are met.**
9+
10+
### Scope, Boundaries, and Decisions
11+
1. In scope:
12+
Runtime command behavior currently in `src/containai.sh` and `src/lib/*.sh`.
13+
2. Out of scope (this phase):
14+
Installer/build shell systems (`install.sh`, `src/build.sh`, packaging scripts), except minimal consumption updates for new `cai` binary paths when needed.
15+
3. Compatibility posture:
16+
**Clean break in command UX is allowed**, but **capability parity is required**.
17+
4. Must follow CLI design guildlines from https://clig.dev
18+
5. Native publish targets required now:
19+
Linux + macOS.
20+
6. Test migration level:
21+
Port all unit + ACP + key integration flows to xUnit v3 now.
22+
23+
### Required Skill Usage (from AGENTS guidance)
24+
Apply these skills explicitly during implementation and review:
25+
1. `dotnet-project-structure`:
26+
Use modern solution/project structure and keep `.slnx`/central props/package hygiene.
27+
2. `modern-csharp-coding-standards`:
28+
Enforce modern C# patterns, immutable option records, async correctness, cancellation discipline.
29+
3. `dependency-injection-patterns`:
30+
Organize command/services via composable `IServiceCollection` extensions.
31+
4. `api-design`:
32+
Keep internal/public command contracts stable and explicit.
33+
5. `type-design-performance`:
34+
Use efficient type boundaries and avoid unnecessary allocations in hot CLI paths.
35+
6. `csharp-concurrency-patterns`:
36+
ACP/session concurrency design for output serialization and request routing.
37+
7. `testcontainers-integration-tests`:
38+
Docker-dependent integration test architecture in xUnit.
39+
8. `dotnet-slopwatch` (quality gate after substantial changes):
40+
Detect shortcutting/regression-hiding patterns.
41+
9. `crap-analysis` (quality gate after test migration):
42+
Detect high-risk complexity/coverage hotspots.
43+
44+
### Target Architecture
45+
1. Projects:
46+
`src/ContainAI.Cli.Abstractions` (options/contracts/errors),
47+
`src/ContainAI.Cli` (application services/use-cases),
48+
`src/cai` (native host, `System.CommandLine` composition),
49+
retain `src/ContainAI.Acp` (protocol/session core),
50+
deprecate standalone `src/acp-proxy` executable role after merge.
51+
2. Command model:
52+
Per command: `Options` + validation + handler + use-case service + adapter interfaces.
53+
3. Infrastructure adapters:
54+
Docker, process execution, file system, terminal IO/prompts, config/env resolution, clock, path normalization.
55+
4. AOT/trim safety:
56+
Source-generated JSON, no reflection-dependent command binding, trim warnings treated as blockers.
57+
5. Binary outcome:
58+
One executable `cai` with integrated ACP subcommands.
59+
60+
### Command Surface to Implement in `System.CommandLine`
61+
Root commands and subcommands:
62+
1. `run`
63+
2. `shell`
64+
3. `exec`
65+
4. `doctor` (+ `fix` targets)
66+
5. `setup`
67+
6. `validate`
68+
7. `docker`
69+
8. `import`
70+
9. `export`
71+
10. `sync`
72+
11. `stop`
73+
12. `status`
74+
13. `gc`
75+
14. `ssh` (`cleanup`)
76+
15. `links` (`check`, `fix`)
77+
16. `config` (`list/get/set/unset`)
78+
17. `template` (`upgrade`)
79+
18. `update`
80+
19. `refresh`
81+
20. `uninstall`
82+
21. `completion`
83+
22. `version`
84+
23. `acp proxy <agent>`
85+
86+
### ACP Integration Plan
87+
1. Move parser/entrypoint behavior from `src/acp-proxy/Program.cs` into `cai` command tree.
88+
2. Keep `ContainAI.Acp` core session/protocol libraries; adapt `AgentSpawner` to invoke the new CLI path safely.
89+
3. Preserve ACP requirements:
90+
NDJSON behavior, stdout purity, initialize/session lifecycle, multi-session routing, concurrency safety, graceful shutdown.
91+
4. Remove runtime dependency on separate `acp-proxy` binary path in CLI behavior.
92+
93+
### Functional Migration Workstreams (for parallelization)
94+
#### Stream A: CLI Kernel & Composition
95+
1. Build root `System.CommandLine` graph, shared option primitives, DI bootstrap, command registration modules.
96+
2. Owns command parsing/dispatch architecture and cross-command conventions.
97+
98+
#### Stream B: Runtime + Docker Core
99+
1. Implement `run`, `shell`, `exec`, `docker`, `setup`, `validate`.
100+
2. Own context resolution, container discovery/creation/start, execution pathways.
101+
102+
#### Stream C: Lifecycle/Data Commands
103+
1. Implement `import`, `export`, `sync`, `stop`, `status`, `gc`, `ssh`, `links`, `config`, `template`, `update`, `refresh`, `uninstall`.
104+
2. Own config precedence, workspace state behaviors, lifecycle safety prompts.
105+
106+
#### Stream D: ACP Merge
107+
1. Integrate ACP command into root CLI.
108+
2. Own ACP session wiring, process spawning adaptations, protocol-level parity.
109+
110+
#### Stream E: Test Migration (xUnit v3)
111+
1. Port shell unit tests to C# unit tests.
112+
2. Port ACP integration tests to xUnit.
113+
3. Port key runtime integration scenarios with Docker-aware fixtures.
114+
115+
#### Stream F: Docs/CI/Release Wiring
116+
1. Update contributor docs and command references.
117+
2. Add/adjust CI pipelines for tests + NativeAOT publish matrix for Linux/macOS.
118+
3. Minimal install/runtime docs updates for binary-based flow.
119+
120+
### Parallel Worktree/Agent Execution Design
121+
1. Orchestrator agent responsibilities:
122+
Own integration branch, maintain parity checklist, assign streams, coordinate rebases, run final validation.
123+
2. Worktree strategy:
124+
One independent git worktree per stream; no overlapping file ownership where possible.
125+
3. Merge order:
126+
A first (foundation), B/C/D in parallel rebased on A, then E (test convergence), then F.
127+
4. Review-agent requirement per stream PR:
128+
One correctness/regression reviewer + one architecture/factoring reviewer.
129+
5. Merge target:
130+
All stream PRs merge into orchestrator integration branch first; only orchestrator merges to `main`.
131+
132+
### Behavior-Parity and Undocumented Feature Capture
133+
1. Build a parity inventory from:
134+
`src/containai.sh`, all `src/lib/*.sh`, current help text, completion behavior, integration/unit tests, and CLI docs.
135+
2. Mark each behavior as:
136+
`mandatory`, `intentional break`, or `deferred`.
137+
3. Any undocumented behavior exercised by tests/codepaths is treated as mandatory unless explicitly reclassified.
138+
4. Parity inventory is a hard gate for completion.
139+
140+
### Testing Plan (xUnit v3)
141+
1. Add/expand test projects:
142+
`tests/ContainAI.Cli.UnitTests`,
143+
`tests/ContainAI.Cli.IntegrationTests`,
144+
existing `tests/ContainAI.Acp.Tests`.
145+
2. Unit coverage:
146+
argument parsing, validation, option precedence, config/workspace resolution logic, docker command assembly.
147+
3. ACP test coverage:
148+
framing, stdout purity, initialize/session lifecycle, routing and cleanup, multi-session concurrency.
149+
4. Integration coverage:
150+
key end-to-end command flows for runtime-critical paths (`run/shell/exec/import/export/stop/status/gc/config/docker`).
151+
5. Quality gates:
152+
slopwatch and CRAP/coverage analysis executed before integration-branch final merge.
153+
154+
### CI and Publish Gates
155+
1. Build/test matrix:
156+
.NET build + xUnit v3 suites + ACP tests + key integration suites.
157+
2. Native publish matrix:
158+
Linux + macOS NativeAOT trimmed binary artifacts for `cai`.
159+
3. Failure policy:
160+
Any broken parity item, failing critical tests, or unresolved reviewer findings blocks merge.
161+
162+
### Important Changes to Interfaces/Types
163+
1. `System.CommandLine`-based command definitions become canonical command interface source.
164+
2. Shared options and resolution contracts move into strongly-typed abstractions (no shell global-state patterns).
165+
3. ACP command becomes internal subcommand of `cai`; standalone proxy executable path is retired from runtime contract.
166+
4. Error/result contracts become typed and testable (instead of implicit shell exit-path behavior).
167+
168+
### Assumptions and Defaults
169+
1. Installer shell remains for now; runtime shell is replaced.
170+
2. Command naming/flag cleanup is permitted if functionality remains.
171+
3. Linux + macOS native artifacts are mandatory in this phase.
172+
4. No backward-compat shell alias layer is required.
173+
174+
### Completion Criteria ("Keep Going Until")
175+
Work continues until all are true:
176+
1. One native `cai` binary fully handles runtime command set.
177+
2. `cai acp proxy <agent>` fully replaces runtime ACP proxy path and passes ACP tests.
178+
3. xUnit v3 migration is complete for unit + ACP + key integration suites.
179+
4. Parity inventory is closed with no unapproved gaps.
180+
5. Linux/macOS NativeAOT publish succeeds.
181+
6. Required review-agent findings are resolved.
182+
7. slopwatch and CRAP/coverage gates pass.
183+
8. Orchestrator branch passes full validation and is merged to `main`.

0 commit comments

Comments
 (0)