26 KiB
AutoForge development roadmap
Status and authority
- Initialized: 2026-10-28.
- Current phase: initial orchestration; no application functionality exists yet.
- Active assignment: Step-01, ready for manual worker execution.
- Last accepted step: none.
- Current state and handoff: STATE.md.
- Authority: the supplied master charter, as superseded by the repository structure and agent handoff amendment. The amendment's naming and layout win.
- This document describes the intended architecture and future capabilities. Planned projects, interfaces, milestones, and demonstrations are not claims of implemented or verified functionality.
Product goals
Build one extensible, local-first .NET 10 platform combining:
- Deterministic vehicle simulation and virtual electronic control modules.
- Diagnostics, telemetry, visualization, calibration management, and eventually explicitly authorized module-specific programming.
- Local AI planning and vehicle knowledge with independently validated runbooks.
Support arbitrary vehicle module inventories, not a fixed ECU/TCU list. Vehicle, module, protocol, and calibration definitions must be data-driven and applicable to specific hardware/software identities. Unknown or restricted capabilities must remain explicit. Simulation, manual diagnostics, manual calibration work, and tests must function without an AI service or cloud account.
Preserve the complete product vision through incremental, integrated vertical slices. Do not finish one major subsystem in isolation before integrating it.
Repository and manual workflow
The only top-level project directories are docs, src, and prompts.
Necessary root configuration files are allowed. Preserve Git metadata and
existing protected repository infrastructure; these are not project directories.
- All application projects and automated test projects belong under
src. - The primary solution will be
src/AutoForge.slnx. - Tests belong under
src/tests, never a top-leveltestsdirectory. - Generated test evidence, if retained, belongs in an ignored location under
src, not a top-levelartifactsdirectory. - Technical/product documentation belongs under
docs. - All file-based orchestrator/worker communication belongs under
prompts. - Do not create a nested
AutoForgerepository directory. - Do not initialize a repository, automatically commit, or push.
.github/copilot-instructions.md, if present, is read-only. If absent, do not create it or an alternative intended to override it.
The orchestrator writes assignments and maintains this roadmap and state. The worker alone writes application code, tests, technical documentation, and the root README; executes builds/tests; and writes the corresponding report. The orchestrator reviews the assignment, report, relevant source and tests, Git changes, documentation, and actual reported command evidence. It does not execute application builds/tests or implement fixes.
Handoffs are manual. No agent invocation, messaging automation, polling, watchers, automatic prompt pickup, or unattended progression is permitted.
Assignments use Step-01.md, Step-02.md, etc. Reports use
Step-01-Report.md, Step-02-Report.md, etc. Corrective assignments use the
original number plus sequential uppercase letters, for example Step-01A.md
and Step-01A-Report.md, then Step-01B.md. Accept all necessary corrections
before assigning the next major step. Do not use the superseded numeric-dot
prompt/report naming convention.
Architecture baseline
Initial physical projects
Step-01 creates only four projects:
| Project | Responsibility | Allowed project references |
|---|---|---|
src/AutoForge.Core |
Platform-neutral foundational value types, invariants, and shared contracts | None |
src/AutoForge.Application |
Use-case coordination and application-facing services; initially explicit execution-target selection | Core |
src/tests/AutoForge.UnitTests |
Focused domain and application behavior tests | Core, Application |
src/tests/AutoForge.IntegrationTests |
Real application composition and cross-project behavior, without hardware/cloud | Core, Application |
This is deliberately a headless foundation. It must include real behavior and tests, not empty assemblies or always-passing test placeholders. Application shells arrive in Step-05 when working services can support them. This is staging, not a substitution for either required shell.
Planned boundaries, added only when used
| Boundary / likely project | Responsibilities and dependency direction |
|---|---|
| Core | Vehicle/module identities, capability states, provenance, units, versioned domain schemas; no UI, inference, transport implementation, or storage dependencies |
| Application | Diagnostic use cases, provider selection, calibration/runbook validation, approval, execution coordination, application ports; depends on Core |
| Diagnostics | Addressing, protocol/service handling, decoding, transport interfaces and communication trace; depends on Core and only needed Application contracts |
| Simulation | Virtual clock, coupled dynamics, virtual modules, simulated transport, deterministic faults; depends on shared contracts/Diagnostics, never on an LLM or UI |
| Persistence / telemetry infrastructure | Recording, replay, calibration/version storage, audit and knowledge repositories implementing application ports; introduce a project only when justified |
| AI / knowledge integration | Provider adapters, research and retrieval, schema-constrained planning; consumes restricted application query/planning ports, never hardware-driver access |
| Hardware adapter | Verified OBDX Pro GT/native integration behind shared diagnostic ports; Windows-specific code isolated from browser/shared UI |
| Shared UI components RCL | Data-driven gauges, charts, controls, layouts; consumes platform-neutral view models/contracts |
| Shared application screens RCL | Profile, diagnostics, simulation, calibration, replay, knowledge, AI, settings screens; composes components and calls application services |
| Standalone Blazor WebAssembly shell | Browser composition, routing and shared RCL hosting; no native driver references |
| MAUI Blazor Hybrid shell | Windows-first native composition hosting the same RCLs; platform services injected at the host boundary |
| Local .NET hardware service | Browser-to-native bridge when needed; explicit authorization and local exposure controls, not a required cloud backend |
These are logical responsibilities, not an instruction to create all assemblies now. Keep related responsibilities together until an actual dependency or platform boundary justifies extraction. Avoid premature microservices.
Planned dependency flow:
flowchart TD
Browser[Standalone Blazor WebAssembly] --> Screens[Shared screens RCL]
Hybrid[MAUI Blazor Hybrid] --> Screens
Screens --> Components[Shared components RCL]
Screens --> App[Application use cases and ports]
AI[Local AI and knowledge adapters] --> App
App --> Core[Core domain and contracts]
Sim[Simulation and virtual modules] --> Ports[Diagnostic and application ports]
Store[Recording and persistence adapters] --> Ports
Native[Native hardware adapter] --> Ports
Bridge[Local hardware service] --> App
Ports --> Core
App --> Ports
Ports in the diagram are logical contracts, not an additional required project. Composition roots wire implementations. Dependency injection does not grant AI or UI unrestricted programming authority.
Invariants
- Explicit target: simulation, recorded replay, and physical hardware are distinct execution targets. Never infer, silently switch, or fall back between them. Descriptor selection is not a connection or a successful operation.
- Layered diagnostics: separate physical transport, vehicle network, addressing, diagnostic protocol/services, decoding, calibration operations, and application commands. Generic OBD-II does not imply access to all modules.
- Determinism: fixed virtual time and reproducible inputs/seeds drive simulation. Do not use wall-clock timing, rendering frequency, or LLM sensor generation as the physics source. Timeouts/faults must be reproducible.
- Physical consistency: RPM, gear ratio, speed, torque/load, fuel use, and temperatures derive from coupled state within documented model assumptions. Simplified predictions must not be marketed as validated real-world results.
- Independent oracle: tests may inspect simulation ground truth through an isolated test boundary; application and AI paths may not bypass diagnostics to access it.
- Truthful data: distinguish vehicle configuration, firmware, calibration, calibration definitions, diagnostic captures, and telemetry recordings. Version persisted schemas; preserve originals and applicability information.
- Telemetry lineage: preserve source/module identity, units, sampling, data quality, raw/decoded/derived/estimated/simulated classification, and both simulation and capture time as applicable.
- Separate operations: live simulation, recorded-session replay, and deterministic scenario re-execution are not interchangeable. Comparisons identify source, configuration, scenario, confidence, and limitations.
- Safe execution: AI proposes versioned logical runbooks. A deterministic validator/executor checks identity, applicability, limits, dependencies, approvals, preconditions, backup, readback, unrelated-data preservation, diagnostics, and supported recovery.
- Three verifications: backup verification, programming verification, and functional verification are distinct. Missing, interrupted, or uncertain verification cannot be reported as success.
- Evidence and authority: VERIFIED, UNVERIFIED, INFERRED, and SYNTHETIC information retain sources, applicability, confidence, verification status, and limitations. Similarity search is not authority for offsets or exact compatibility. Unknown calibration locations remain unknown.
- Physical gates: first hardware integration is read-only. Capability discovery, transport selection, simulation approval, or an AI recommendation never authorizes physical writes. Physical programming requires separate explicit authorization and module-specific controlled evidence.
- Prohibited functionality: no emissions defeat, anti-theft bypass, mileage falsification, safety-system disabling, or unrestricted safety-critical writes.
- Local-first and replaceable AI: allow local OpenAI-compatible endpoints, initially considering LM Studio and Qwen3.5-9B around a practical 16 GB model memory budget. Verify actual availability, licensing, context, and memory use at implementation time; do not make a model or fine-tuning a core dependency.
- Honest errors and support: no fake providers, silent defaults, fabricated manufacturer protocol behavior, fabricated backups, or unverified platform claims. Protect vehicle identifiers, recordings, model assets, and local service endpoints. Never commit secrets or private runtime datasets.
Milestones and acceptance gates
All milestones below are unimplemented. Only Step-01 is currently assigned. Dependencies indicate acceptance prerequisites, not permission for automatic handoff. Later assignments refine these scopes using actual implementation evidence; they must not silently discard required capabilities.
| Step | Milestone | Depends on | Status | Principal acceptance gate |
|---|---|---|---|---|
| 01 | Repository and solution foundation | Repository inspection | READY FOR WORKER | Four-project .NET 10 foundation, explicit target-selection behavior, real unit/integration tests, successful recorded build/test evidence, accurate README and architecture docs |
| 02 | Vehicle profiles and module model | 01 accepted | PLANNED | Versioned profile round trips, validation, extensible module inventory, identity/applicability and explicit capability states; clearly synthetic vehicle fixture |
| 03 | Virtual modules and diagnostic communication | 02 | PLANNED | Application discovers/identifies synthetic modules and reads telemetry/DTCs through a simulated transport; trace, negative responses and deterministic timeout tests |
| 04 | Deterministic vehicle dynamics | 03 | PLANNED | Coupled engine/transmission/road-load model, virtual clock and lifecycle controls; identical scenarios/inputs reproduce outputs under a documented numerical contract |
| 05 | Both application shells and live dashboard | 04 | PLANNED | Standalone WASM and Windows MAUI Hybrid share two logical RCLs; select a profile, control simulation and display independently collected live telemetry |
| 06 | Telemetry recording and replay | 05 | PLANNED | Persist raw messages and decoded signals with metadata; playback/seek/speed controls feed the same gauges without silently reconstructing missing data |
| 07 | Calibration management and simulated programming | 06 | PLANNED | Versioned definitions/diffs, verified baseline and backup, approved simulated write, readback/unrelated-data checks, audit and supported restore; no physical writes |
| 08 | Local AI, knowledge, and validated runbooks | 07 | PLANNED | Replaceable local inference, applicable knowledge retrieval, structured logical runbook, independent validation/approval and simulation-only execution |
| 09 | Comparative evaluation and complete synthetic demonstration | 08 | PLANNED | Complete demonstration below plus deterministic fault/regression matrix and independent verification of intended and unintended changes |
| 10 | Verified OBDX Pro GT read-only integration | 09 plus documented device research/access | PLANNED / HARDWARE GATE | Source-backed device support matrix, explicit physical target, real read-only identification/diagnostics/telemetry recording where supported; no write path |
| 11 | Advanced dashboards, analysis, and comparisons | 09; 10 for real captures | PLANNED | Persist configurable layouts/thresholds/units, linked charts, raw-data inspection, multi-run/multi-vehicle comparisons with lineage and uncertainty |
| 12 | Broader diagnostic protocols and hardware adapters | 10 | PLANNED | Conformance-backed additional CAN/ISO-TP/UDS/KWP2000/J2534 or legacy adapters where verified; same application ports and capability restrictions |
| 13 | Curated vehicle knowledge and research workflow | 08; 12 where needed | PLANNED | Sourced profile/module/calibration knowledge, review/promotion workflow, exact applicability, licensing/access controls; research cannot authorize writes |
| 14 | Higher-fidelity simulation and virtual module coverage | 09; 13 for verified datasets | PLANNED | Validated model extensions, richer transmissions/environment/module interactions and reproducible fault coverage; published fidelity limits |
| 15 | AI evaluation and optional specialization | 08, 09, 13 and adequate datasets | PLANNED | Held-out deterministic runbook evaluations, refusal/uncertainty cases, memory/latency measurements; LoRA/QLoRA only if justified by measured benefit |
| 16 | Programming qualification without physical writes | 07, 09, 10, applicable 12/13 evidence | PLANNED | Module-specific safety case, bench plan, voltage/state/identity checks, interruption/recovery tests in simulation, legal authorization and defined go/no-go criteria |
| 17 | Explicitly authorized controlled bench programming | 16 and separate user authorization | PLANNED / AUTHORIZATION GATE | Authorized supported bench target only; verified backup completeness, transfer/readback/recovery evidence and audit; no general vehicle-write enablement |
| 18 | Approved vehicle/module-specific programming | 17 and separate vehicle-operation authorization | PLANNED / AUTHORIZATION GATE | Explicit per-operation approvals, compatibility/operating-state/power/security checks and proven recovery limits; strict module-specific support matrix |
| 19 | Packaging, extensibility, and additional platforms | 05, 09; feature-specific gates remain | PLANNED | Offline-friendly reproducible releases, documented supported hosts, feature manifests/DI, compatibility/migration regression evidence |
| 20 | Optional MCP and firmware-emulation research | 08, 13; isolated research approvals | OPTIONAL / PLANNED | Concrete benefit and separate ADR; restricted tools retain validator/approval boundary; emulation limitations and proprietary-data rights documented |
Scope details for Steps 02-10
- 02: vehicle specifications and configuration/tune selection, arbitrary module identities, supported/unsupported/unknown/inaccessible/restricted capability states, firmware/calibration identity, relationships, provenance, validation, schema versioning, and multiple synthetic variants. Never imply a diagnostic capture contains a complete firmware image.
- 03: synthetic module state/storage, identification, telemetry definitions, DTC retrieval and simulated clearing, request/response semantics, addressing, session state where appropriate, delays, invalid requests, unsupported services, interruption and negative responses. Authentic protocol semantics require sources; synthetic behavior is labeled.
- 04: start/stop/pause/resume/reset/step, configurable pacing independent of simulation results, save/load configuration, seeded scenarios, engine idle, throttle/load/torque/fuel, transmission/shift scheduling, mass/drivetrain/road load, temperatures, and a stationary-to-45-MPH-to-stop scenario with a five-minute hold. Report mathematical assumptions and repeatability tolerances.
- 05: reusable data-bound gauges and feature screens, navigation and settings, profile/module selection, connection state and diagnostics; compile-time feature composition first, no unsupported arbitrary assembly loading. Missing MAUI workloads are blockers, not permission to replace either shell. Native browser access eventually uses a verified local .NET service, never browser P/Invoke.
- 06: versioned recording format, module/source/units/time/quality metadata, raw plus decoded retention, interrupted/corrupt session handling, replay play/pause/stop/restart/seek/navigation/speed. Acquisition must not depend on visible gauges. Mark captured versus interpolated/reconstructed samples.
- 07: scalar/table definitions with ranges/scaling/units and dependencies; original/proposed/tested/approved versions, structured diffs, verified backup completeness, approval binding, audit, readback, unrelated-data preservation, restoration where supported, explicit failure/recovery outcomes.
- 08: local inference provider configuration, structured queries plus optional semantic retrieval, source-backed applicability checks, versioned runbook schema and restricted tools. Include natural-language diagnostics, driving scenarios, and calibration planning; AI cannot emit arbitrary hardware frames/offset writes. Missing knowledge and disconnected inference produce explicit outcomes without disabling non-AI functionality.
- 09: equivalent baseline/modified scenarios and initial state, independent calibration oracle, behavioral/fuel/shift comparisons with confidence labels, fault reports, replay/raw-trace inspection and an auditable verification report. Include timeout, unsupported service, malformed response, wrong identity/version, interruption, corruption/checksum, partial write, reset, incompatible config, DTC and failed-verification cases.
- 10: verify OBDX Pro GT protocols, drivers, OS/architecture constraints, manufacturer libraries/SDKs, actual J2534 support and C# integration using attributable sources before implementation. Missing device/driver access means real-hardware verification is blocked, not passed by mocks. Restrict services to verified read-only allowlists; diagnostic access does not imply every module is discoverable or programmable.
Longer-term scope preservation
Steps 11-20 retain richer gauges/clusters/charts and dashboard editing, comparison and analysis, more vehicle/module/protocol coverage, independently validated research, curated datasets, advanced dynamics and transmission modeling, local model evaluation/specialization, authorized programming, and supported release packaging. New MAUI platforms require platform-specific evidence. Avalonia is an optional feasibility investigation, not a promise that Razor embeds unchanged. Optional MCP does not bypass runbook safety. Firmware emulation is separate from the initial behavioral simulator, never an implied capability of synthetic modules.
Bench and vehicle programming milestones may not proceed on roadmap status alone. If authorization, applicable definitions, safe test equipment, licensing, recovery evidence, or manufacturer procedures are missing, retain a blocked gate and continue only independent safe work through an explicit new assignment.
Required synthetic end-to-end demonstration
Target acceptance: Step-09. Use the explicitly synthetic AutoForge test truck, initial warm idle 650 RPM and proposed warm idle 1,250 RPM. These values and any memory layout are synthetic, not manufacturer calibration data.
- Load the synthetic vehicle; inspect its modules and current calibration.
- Start simulation; display original idle telemetry; record and stop the run.
- Request the idle change in natural language. The local AI identifies the applicable module/parameter and produces a versioned logical runbook.
- Deterministically validate identity, definition, range/dependencies, execution target and approval; back up the original virtual calibration and verify it.
- Apply only the approved simulated change. Verify the operation, read calibration back, confirm the target value and independently confirm unrelated values.
- Re-run the same scenario/initial state using the modified calibration; observe the changed idle behavior and record the second run.
- Replay either recording; compare both runs, preserving their source, time, configuration, fidelity, and confidence metadata.
- Inspect underlying diagnostic communications and a report separating backup, programming, and functional verification with supported recovery limitations.
Evidence must cover all these actions without privileged application/AI access to the test oracle. Add a table-based shift-schedule case later; do not imply all calibration requests are scalar edits. Simulation fuel-use changes are estimates, not proven real-world economy improvements.
Test and evidence strategy
- Worker selects maintained .NET 10-compatible test packages after inspecting the installed SDK and package compatibility. No speculative SDK/package signatures.
- Unit tests cover invariants, validation, decoding, algorithms, and failure semantics. Integration tests exercise real composition across boundaries, serialization/persistence, transports, and execution as those features arrive.
- Add simulation-specific test projects only when they have real responsibilities.
Keep all tests in
src/testsand separate privileged oracle access. - Use deterministic fixtures/seeds/virtual time; define reproducibility and numeric tolerance contracts. Keep test infrastructure independent of AI/cloud/hardware.
- Adapter contract and hardware tests distinguish stub evidence from real devices. AI evaluations include held-out invalid/unsupported/uncertain requests and deterministic validators, not only LLM-as-judge.
- Record exact commands, target framework/platform, configuration, exit outcomes, test counts and failures, and durable evidence references in each worker report.
- Run the smallest relevant builds/tests plus required regression coverage. Missing prerequisites or unexecuted tests are BLOCKED/NOT EXECUTED, never PASSED.
- Every assignment requires appropriate real unit/integration tests, documentation and README review. No empty "integration" tests or success-shaped placeholders.
- The orchestrator inspects evidence without claiming independent runtime execution.
Decisions, completed work, remaining work, and blockers
Initial decisions
- D-001: amendment layout and Step-XX naming supersede the original examples.
- D-002: one .NET 10 solution; minimal headless Core/Application foundation first.
- D-003: standalone WASM plus Windows-first MAUI Hybrid, shared components/screens; no Blazor Server substitution.
- D-004: common diagnostic/application interfaces across simulation, replay and physical providers; explicit execution target, no fallback.
- D-005: deterministic simulation and independent verification are prerequisites for AI-assisted calibration execution and physical integration.
- D-006: local-first replaceable inference; no initial fine-tuning/vector/MCP/cloud dependency. Storage implementations are chosen when real use cases arrive.
- D-007: initial hardware is read-only; bench and vehicle writes have separate authorization/evidence gates and retain prohibited-operation restrictions.
- D-008: handoffs remain manual; only the worker builds/tests and implements.
The worker records the relevant accepted decisions as technical ADRs when creating or changing the implementation. Future changes require a reason and roadmap/state history, not repeated redesign without evidence.
Completed
- Read both supplied instruction sets and inspected the existing repository.
- Established the initial planned boundaries, sequence, and first worker assignment.
Remaining
- All application implementation, build/test verification, and technical documentation work, beginning with Step-01.
- Review Step-01 and any corrections before issuing Step-02.
Known blockers and uncertainties
No confirmed initialization blocker. The orchestrator has not inspected installed .NET SDKs, workloads, package compatibility, inference availability, or hardware. The worker must inspect prerequisites; absence of evidence is not compatibility. Physical hardware access, applicable manufacturer definitions, and programming authorization are future gates, not current claims.