This track modifies VibeX source: new Host capabilities, Application Core, the desktop shell, or the remote protocol. Plugins consume those capabilities as described in Plugin architecture.

Before work, read root CONTEXT.md, the ADRs in docs/adr/ that apply, and apply maiden-skill in full. Then load the smallest set of SKILL.md files matched by the Agent Skill rules in CONTEXT.md. Cross-layer changes load every matching skill together. A new Tauri command also covers IPC, frontend integration, and tests.

Layout

The repo is a pnpm workspace plus a Cargo workspace. The Rust toolchain is pinned in rust-toolchain.toml (currently nightly-2025-12-04).

Three process layers

1. The frontend talks to the backend only through invoke and event subscriptions.
2. The Tauri shell registers commands and holds AppState. Commands live under src-tauri/src/commands/ by domain.
3. crates/* implement the business. Services are injected through the Deployment trait. The desktop concrete type is LocalDeployment.

Agent subsystem

New agent, conversation, and turn work goes through crates/agents (AgentRuntime, AgentConnectionManager) and the event-sourced conversation core. The CLI-executor path has been removed. ExecutorActionType keeps only ScriptRequest. crates/executors still owns script execution, the executor config schema, and log normalization. Agent execution stays in crates/agents.

Conversation events append to conversation_event and project into the timeline. The frontend renders AgentTimelineConversation only. A conversation has at most one in-flight turn. See Conversation and Turn state machine.

Application Core and remote

Desktop commands, Web routes, and the remote-desktop adapter authenticate and map DTOs/errors, then call the same Application Core. The frontend uses BackendTransport: TauriTransport locally, WebTransport in the browser and on a workstation. One window binds one Host. One data directory has one Host occupant at a time. See Application Core.

Maiden principles

User-visible completeness outranks keeping a wrong abstraction. Defects are fixed at the origin. Names state behavior. Comments record why a decision exists. Backup files, commented experiments, and incorrect intermediate states are removed. Local source and deployed source are the same artifact. UI copy helps act, decide, understand state, recover, or judge a consequence.

Environment

• Node 22, pnpm 10.x (CI uses pnpm 10.13.1).
• Rust nightly, see rust-toolchain.toml. The first cargo install follows that file.
• SQLx CLI: cargo install sqlx-cli --no-default-features --features sqlite. After query changes run pnpm run prepare-db.
• Optional cargo install cargo-watch.
• Secrets stay in a local .env. .dev-ports.json and generated Tauri dev config are local runtime artifacts.

Startup installs a single rustls crypto provider (install_rustls_crypto_provider). reqwest is built in no-provider mode. Construct TLS clients after that function runs.

Dev ports are allocated dynamically into .dev-ports.json. scripts/run-tauri-dev-desktop.js writes src-tauri/tauri.dev.generated.conf.json per run.

Commands

From the repository root:

pnpm install                 # JS deps; required before any pnpm script
pnpm run dev                 # Tauri desktop + Vite HMR
pnpm run check               # frontend tsc --noEmit + cargo check
pnpm run lint                # eslint max-warnings 0; clippy -D warnings --features qa-mode
pnpm run format              # cargo fmt --all + prettier

Frontend (frontend/ or pnpm --filter ./frontend):

pnpm test
pnpm exec vitest run src/path/file.test.ts
pnpm exec vitest run -t "renders tool card"
pnpm run check
pnpm run lint

Backend:

cargo test --workspace
cargo test -p agents
cargo test -p agents acp_session_resume
cargo clippy --workspace --all-targets --features qa-mode -- -D warnings

Codegen. Re-run when inputs change. CI fails :check on stale artifacts:

pnpm run generate-types
pnpm run generate-types:check
pnpm run prepare-db
pnpm run prepare-db:check

generate-types runs with SQLX_OFFLINE=true. The generator merges: it keeps declarations outside its replacement list, replaces replacement_declarations(), and drops removed_declarations(). To export a new #[derive(TS)] type, add insert_declaration::<T>() in src-tauri/src/bin/generate_types.rs, then generate.

Recommended flow

1. Read CONTEXT.md, relevant ADRs, maiden-skill, and directly matching SKILL.md files.
2. Isolate the branch with a git worktree (using-git-worktrees skill in-repo).
3. For a behavior change, write a failing test first (tdd skill), then the smallest implementation.
4. Run targeted tests, then the matching check / lint.
5. After type, SQL, or agent-schema changes, run the matching generate/prepare.
6. pnpm run format.
7. Open a PR per PR and security.

Frontend

Prettier: 2 spaces, semicolons, single quotes, ES5 trailing commas, 80 columns. ESLint forbids unused imports and requires exhaustive switches. React component files are PascalCase .tsx. Hooks start with use. Utilities and config are camelCase.

Visual design follows root DESIGN.md: macOS Tahoe target. Liquid Glass is reserved for navigation and control chrome. Content surfaces stay opaque. Every route is wrapped in LegacyDesignScope (historical name; treat it as the active design scope). Tokens live in frontend/src/styles/legacy/index.css. Tailwind config is tailwind.legacy.config.js. Use role classes such as --surface-*, --text-*, .settings-surface. Product color uses tokens and role classes. Radii go through --radius (14px).

Visible copy helps act, decide, understand state, recover from an error, or judge a consequence. UI copy omits implementation notes such as “settings live in settings.json”.

Rust

Edition 2024, rustfmt.toml. Grouped imports. CI clippy runs --features qa-mode -- -D warnings. Local pnpm run lint enables qa-mode (including the QaMock executor) the same way.

Domain logic belongs in a crate and is reached through Deployment. Command handlers stay thin. New conversation capability goes in crates/agents. Scripts, config schema, and normalized logs stay in crates/executors.

Generated artifacts

These files are generated; refresh them with the matching command before commit:

• shared/types.ts
• crates/db/.sqlx offline query cache
• src-tauri/tauri.dev.generated.conf.json
• built packages/*/dist

After a SQL query! / query_as! or a migration, run pnpm run prepare-db. After exporting a #[derive(TS)] type, run pnpm run generate-types. Name those generated files in the PR.

Module boundaries

shared/types.ts is the frontend/backend contract. The frontend talks through invoke and shared/types.ts. Plugins import the public SDK only. Official bundled plugins are reference packages on that same contract. A Host special case keyed by plugin ID is debt to delete.

A behavior change or regression fix starts with a failing test, then the smallest implementation. Tests ship with the change.

Frontend

Unit tests sit beside sources: *.test.ts, *.test.tsx, *.spec.ts, *.spec.tsx. Vitest + jsdom. IPC is mocked in unit tests. Broader regressions live in frontend/tests/. E2E lives in frontend/tests-e2e/, chosen by target-platform feasibility.

cd frontend
pnpm exec vitest run src/pages/settings/AgentSettings.test.tsx

UI changes (layout, style, routing, client state) are verified with real interaction before merge: click, type, submit, navigate; visit every route that shares the state; cover empty and error states; check desktop and narrow viewports for layout work. Without browser tools, use unit tests, the dev server, or a render script, and state in the PR what was left unverified.

Rust

In-crate src unit tests and tests/ integration tests. Prefer:

cargo test -p agents acp_session_resume
cargo test -p plugins bundled_office

Then cargo test --workspace when the blast radius warrants it. SQLx tests follow offline cache or the test-database convention. Keep SQLX_OFFLINE aligned with CI.

Plugin contract

Changes to packages/plugin-sdk or plugin-cli run that package’s pnpm test and build. Changes to Host parsing or the contribution registry add crate tests and at least one real linked-install path (official Office or the workflow-creator fixture). Reference packages must keep using only the public SDK.

CI

.github/workflows/test.yml runs on pull_request and push to master. It includes dependency licenses and advisories, frontend checks, Rust clippy (qa-mode), and tests. generate-types:check and prepare-db:check fail on stale artifacts. Run the checks you touched before push.

Commits

History uses Conventional Commits: feat:, fix(scope):, chore(scope):, docs(scope):, plus explicit merge commits. One commit, one change. Titles are imperative.

Pull request

The description includes:

• A short summary of the user-visible result.
• Linked issue, PRD, or ADR.
• Test commands and results.
• Screenshots or recordings for visible UI.
• Generated files: shared/types.ts, .sqlx, plugin locks.
• UI paths left unverified in a browser, if any.

Keep the diff small. Split refactors from features. Agent refactors finish on the ACP path.

Security

• Secrets, tokens, and pairing codes live in a local .env, the OS keychain, or the Host token store. They live only in those stores.
• Error envelopes on the remote protocol and plugin Workers strip secrets. Main token and device token travel in protected headers or the keychain.
• Plugin packages are Full Trust. Official plugins merged into the Host, and APIs merged into the SDK, run at local rights. A new Host capability needs a schema, tests, and docs before plugins may call it.
• Public Host exposure terminates TLS on a reverse proxy. Cross-origin allow lists use exact Origins.
• CI runs pnpm audit --prod --audit-level high and rustsec/audit-check. Licenses: pnpm run dependency:licenses.
• Crash reports stay in the local data directory by default. Content leaves the machine when the user chooses Submit on GitHub.
• Docs and UI use placeholders. Samples use placeholders.

Review axes

Code review checks standards and spec together. Over-engineering review deletes reinvented stdlib, speculative abstraction, and flexibility with no caller. Correctness review covers failure paths, occupancy, event sequence, exclusive permission resolution, and freshness of generated artifacts.