LocalForge Architect

Turn a Windows development request into a safe, catalog-validated local stack plan while keeping execution under explicit human control.

Comment

Inspiration

Setting up a local Windows development environment is rarely one decision. A developer must align framework versions, runtimes, databases, ports, HTTPS, services, public-preview policy, and installation constraints. A language model can help interpret the request, but it should not become a privileged shell. We built LocalForge Architect so AI remains advisory while LocalForge's native managers remain authoritative.

What existed before Build Week

LocalForge already existed as a native Windows local-development control center with a manual Sites planner, recipe and package catalogs, compatibility checks, managed services, databases, HTTPS, backups, diagnostics, and guarded tunnels. It does not require Docker, WSL, Hyper-V, or another virtualization layer for its normal path.

The Build Week contribution is the optional Architect planning layer, its typed provider boundary, the responsive Learn experience, the guarded Agency Git review/export workflow, and the related security, test, and demo evidence. The manual planner remains available whether AI is configured or not.

What it does

  • Converts a natural-language development request into a versioned, typed proposal.
  • Resolves only catalog-backed recipes, runtimes, packages, services, and providers.
  • Runs LocalForge compatibility, installation-planning, and tunnel-safety checks before presenting a result.
  • Shows warnings, blockers, source disclosure, validation receipts, and confirmation requirements.
  • Prefills the existing manual Sites planner only after explicit confirmation.
  • Keeps Auto Install, Custom Plan, Plan, and Plan + Create available without AI.
  • Provides seven responsive Learn paths that delegate to the same manual planner.
  • Adds metadata-only Agency handoffs and an offline, plan-confirmed Git status, initialization, and clean-HEAD bundle workflow for one selected project.
  • Lets Agency-mode Architect propose Git review/export steps without crossing the Git execution boundary.

How we built it

The durable policy lives in Rust. localforge-core defines strict request, intent, proposal, and trust-receipt models; provider boundaries; catalog resolution; compatibility checks; installation planning; and Agency Git safety. The CLI exposes deterministic, parseable JSON. Tauri exposes narrow asynchronous commands with redacted public errors. React provides validation, loading, retry, fixture disclosure, blocker, confirmation, and manual-handoff states.

The OpenAI provider uses the Responses API with tools: [], store: false, and a strict JSON schema; its API key remains in the native backend. The same validated boundary supports a loopback-only Ollama provider. The demo includes a real local qwen3:4b readiness check and WordPress proposal. Timed framework scenes use an explicitly labeled deterministic fixture so live and fixture modes cannot be confused.

How Codex and GPT-5.6 helped

Codex with GPT-5.6 accelerated repository analysis, architecture mapping, Rust and React implementation, adversarial security review, test expansion, evidence capture, and demo production. It helped turn broad product goals into typed manager boundaries and repeatable release gates, then exercised those boundaries with regression and failure-path tests.

Human decisions remained authoritative for product scope, the manual-first execution boundary, recipe maturity, provider claims, licensing, public release choices, and final submission approval. The primary Codex project thread /feedback Session ID is 019f42ae-c729-7970-97b4-1ef5b4b42d73.

Safety design

There is no command, script, environment, arbitrary path, or free-form URL field in the Architect output schema. Unknown IDs and versions fail closed. The React surface can request a plan or prefill validated values; it cannot use Architect to install, start, expose, or mutate a project. Installation still passes through RecipeManager, InstallPlanner, CompatibilityManager, and the existing confirmation gates.

API keys are requested through a native Windows dialog, protected for the current Windows user, and never returned to React. Prompts, model responses, authorization headers, and credentials are excluded or redacted from project metadata, diagnostics, and user-facing errors.

Agency Git supports no remote, push, pull, fetch, clone, commit, credential, or hook operation. Mutations require a fresh plan digest and explicit human confirmation. Public tunnels remain selected-site actions with preflight checks; Architect cannot expose a site.

Challenges

The hardest problem was adding useful AI assistance without creating a second execution engine. Another was making Agency collaboration helpful without copying source, backups, or secrets, and without allowing a model to drive Git or network commands. We solved both by keeping every new flow inside typed managers and confirmation-bound plans.

We also had to make evidence honest. Fixture mode is visibly labeled, live local-model evidence is identified separately, and the submission distinguishes the pre-existing LocalForge platform from the Build Week extension.

Accomplishments

  • 625 Rust workspace tests passed with zero failures.
  • 39 Tauri Rust tests passed.
  • 33 desktop Playwright tests passed.
  • Strict workspace and Tauri Clippy passed with warnings denied.
  • The production native desktop build and close-to-tray smoke passed.
  • Twelve current 1920x930 native screenshots passed the capture gate.
  • Four deterministic demo scenarios passed parseability, stability, safe refusal, and no-data-root assertions.
  • A live local Ollama qwen3:4b request returned a validated WordPress plan through the same read-only LocalForge pipeline.
  • The final 89-second English demo uses real LocalForge product footage and first-party motion graphics.

What we learned

AI is most useful here as an intent interpreter, not as an authority. The model can suggest a coherent stack quickly, but deterministic native policy must decide whether every recipe, version, service, database, tunnel, and transition is allowed. Keeping the proposal typed also made the UI, CLI JSON, tests, and security review substantially clearer.

What's next

  • Package the Build Week extension into a higher-version MSIX and repeat the exact-package installation, update, runtime, framework, diagnostics, and Microsoft Store gates.
  • Extend Agency collaboration through explicit, credential-safe provider adapters instead of unrestricted Git commands.
  • Expand recipe-backed planning while preserving the same fail-closed schema and manual execution boundary.

Built With

Share this project:

Updates