How to Validate Code Changes in PI-Desktop: The Complete Workflow

To validate code changes in PI-Desktop, you must execute local type-checking, linting and unit tests, synchronize any relevant specification documents, run the mandatory end-to-end test suites mapped in the E2E matrix, and complete the merge through an isolated request branch after all remote gates pass.

PI-Desktop enforces a rigorous validation pipeline that ties local checks to architectural constraints defined in the frozen process model. This guide maps the exact steps required to ensure every change remains correct, secure, and synchronized with the project's immutable delivery rules.

Local Validation Pipeline

Every modification to the codebase begins with the standard validation commands documented in the README.md. These gates catch type errors, style violations, and regression bugs before they enter the shared pipeline.

Type Checking and Static Analysis

Run the static analysis tools to verify type safety across the TypeScript boundaries:

pnpm typecheck        # Validates types across Renderer and Main processes

pnpm lint             # Enforces ESLint and Prettier rules

According to the repository structure, these commands traverse the Renderer → Preload IPC → Electron Main layers to ensure interface contracts remain intact.

Unit and Integration Tests

Execute the fast feedback test suite to verify business logic in isolation:

pnpm test             # Runs unit and integration tests

This validates behavior within the Node Agent Runtime and Rust Host Core without spinning up the full Electron application.

Specification Synchronization (R1)

If your change touches user-visible behavior, protocol definitions, or API surfaces, you must update the corresponding specification documents. The 03-ai-development-workflow.md mandates R1 — Spec-first / Spec-sync: every code-bearing change must be accompanied by synchronized documentation.

• Update docs/spec/ files to reflect behavioral changes
• Verify protocol updates in the pi-ai and pi-agent-core interface definitions
• Cross-reference the AGENTS.md file if modifying agent-centric workflows

End-to-End Testing Requirements (R3)

PI-Desktop requires that every code change passes at least one relevant E2E suite selected from the coverage matrix. Consult the 04-e2e-test-plan.md to identify which suites map to your modified surface area.

# Example: Running the UI regression suite for a component change

pnpm e2e:ui

# Example: Running the full integration suite for protocol changes

pnpm e2e:integration

If a required suite cannot execute in your local environment due to hardware constraints or external dependencies, you must record this limitation per the Local Validation and E2E Execution Policy and ensure the suite passes in the trusted CI environment before merging.

The Request Branch Workflow (R4)

PI-Desktop uses an immutable request-branch/worktree policy that isolates development from the main branch. This prevents contamination of the frozen process model spanning Electron Main → Rust Host Core → pi-agent-core.

Creating Isolated Worktrees

Instead of switching branches in your working directory, create a dedicated worktree:

git fetch origin main
git worktree add -b feat/your-feature ../worktrees/feat-your-feature origin/main
cd ../worktrees/feat-your-feature

This approach maintains a clean main worktree while allowing isolated validation of your changes across the full architecture stack.

Conventional Commits and Push

Follow R2 — Commit-per-change by staging your changes with a conventional commit message:

git add .
git commit -m "feat(ui): add dark-mode toggle button"
git push -u origin feat/your-feature

Open a pull request targeting main and verify that the remote CI pipeline executes the required E2E suites listed in the E2E test plan.

Merge Gates and Cleanup

After the PR passes all automated gates—including the mandatory E2E coverage specified in R3—merge using the repository's merge gate:

gh pr merge <PR-NUMBER> --merge

Immediately clean up the isolated workspace to prevent worktree sprawl:

git worktree remove ../worktrees/feat-your-feature
git branch -d feat/your-feature

This cleanup step ensures compliance with the Definition of Done defined in the AI-development workflow specification.

Summary

• Run local gates first: Execute pnpm typecheck, pnpm lint, and pnpm test to catch errors early in the Renderer and Main processes.
• Sync specifications: Update relevant docs/spec/ files whenever modifying user-visible or protocol-visible behavior per rule R1.
• Execute mandatory E2E: Select and pass at least one E2E suite from the coverage matrix in docs/spec/06-delivery/04-e2e-test-plan.md per rule R3.
• Use request branches: Create isolated worktrees for each change and merge only after passing remote gates per rule R4.
• Clean up worktrees: Remove temporary worktrees and branches immediately after merging to maintain repository hygiene.

Frequently Asked Questions

What local commands are required to validate code changes in PI-Desktop?

You must run pnpm typecheck for static analysis, pnpm lint for code style enforcement, and pnpm test for unit and integration validation. These commands verify type safety across the Electron IPC boundary and business logic within the Rust Host Core and Node Agent Runtime.

When is it mandatory to update the specification documents?

Specification updates are mandatory whenever your change affects user-facing behavior, protocol definitions, or API contracts. This aligns with R1 — Spec-first / Spec-sync in the AI-development workflow spec. Changes to the pi-ai or pi-agent-core interfaces always require synchronized documentation updates in the docs/spec/ directory.

How do I determine which E2E test suites to run?

Consult the coverage matrix in docs/spec/06-delivery/04-e2e-test-plan.md. The matrix maps code surfaces (UI components, protocol handlers, agent runtimes) to specific suites such as e2e:ui or e2e:integration. Every code-bearing change must pass at least one relevant suite before merging.

What is the frozen process model and why does it affect validation?

The frozen process model defines the immutable architecture stack: Renderer → Preload IPC → Electron Main → Rust Host Core / Node Agent Runtime → pi-ai / pi-agent-core. This strict layering prevents unsafe cross-boundary changes. The validation pipeline enforces compliance with this model by requiring specification updates and E2E tests that verify cross-process communication contracts remain unbroken.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}