AGENTS.md · vastsa/PI-Desktop

Sections

1. 0. Interaction Language
2. 1. Read Before You Change
3. 2. Instruction Scope
4. 3. Preserve Existing Behavior by Default
5. 4. Respect the Architecture
6. 5. Multi-Agent Isolation Is Mandatory
7. 6. Small, Coherent Changes — and When to Refactor
8. 7. Architecture Ratchet
9. 8. State, UI, and Host Responsibilities
10. 9. Async and Lifecycle Safety
11. 10. Compatibility and Persistence
12. 11. Security, AI Boundaries, and Error Handling
13. 12. Testing Is Part of Implementation
14. 13. Specs Stay Synchronized
15. 14. GitHub Issue Intake
16. 15. GitHub Pull Request Intake
17. 16. E2E Validates Integration Candidates, Not Branch Names
18. 17. Git Hygiene and Commit Messages
19. 18. Delivery Report
20. 19. Maintaining This File

First lines (shown under the repo's LGPL-3.0 license)

# AGENTS.md

Policy-Sync: 2026-09-26.1

Mandatory rules for AI coding agents working in PI-Desktop.

`CLAUDE.md` is the Claude Code / Claude Cowork entry point and a condensed
mirror of the non-negotiables in this file. This file is authoritative.
When you change either file, update the other so the non-negotiables stay
aligned, and set the same `Policy-Sync:` token in both. The gate is
`pnpm check:agent-policy` (`scripts/check-agent-policy-sync.mjs`).

PI-Desktop is released software with real users. Treat every change as
production maintenance, not prototype work.

Optimize for, in order:

1. Correctness
2. User data safety
3. Security
4. Backward compatibility
5. Architectural integrity
6. Testability
7. Maintainability
8. Delivery speed

> Optimize for changing the system safely, not merely changing it quickly.

---

## 0. Interaction Language

- Reply to the user in the language they used. When the request is in
  Chinese, answer in Chinese and keep it terse.
- Keep code, identifiers, comments, commit messages, specs, ADRs, log
  strings, protocol field names, and repository documentation in English.
- GitHub issue / PR discussion follows the original author's language.

---

## 1. Read Before You Change

Before non-trivial work:

1. Run `git status --short` and confirm the workspace state. Preserve
   changes from the user and other agents.
2. Locate the affected packages and read the nearest `AGENTS.md` in each
   target directory (deeper files can tighten root rules; on conflict the
   closest file to the target wins).
3. Read the target package's `README.md`, the relevant ADRs under
   `docs/adr/`, and the source and tests around the change point. Note
   the current behavior and the invariants that must hold.
4. Read the applicable domain spec:
   * `docs/spec/00-baseline.md`
   * relevant documents under `docs/spec/`
5. For development and validation policy, read:
   * `docs/spec/06-delivery/03-ai-development-workflow.md`
   * `docs/spec/06-delivery/04-e2e-test-plan.md`
   * `docs/spec/06-delivery/05-change-checklist.md`
6. Decide "direct change" vs "refactor first" per § 6, and identify which
   risks require automated tests per § 12.

Source of truth is the current code, `package.json`, type definitions,
schemas, and executable scripts. When documentation contradicts the
implementation, verify first and call out the drift in delivery.

Only ask the user when different interpretations would materially change
public contracts, user-visible behavior, data compatibility, or produce
irreversible effects. Otherwise proceed on a minimal, reversible
assumption and state it clearly.

### Workflow policy precedence

`AGENTS.md` is the top-level repository policy for AI-agent development
workflow. Domain specifications remain authoritative for product
behavior, architecture, protocol contracts, persistence semantics,
security boundaries, and acceptance criteria.

If a delivery document conflicts with the branch / worktree / integration
/ E2E workflow defined in this file:

1. do not silently choose one
2. treat the conflict as documentation drift
3. follow the workflow in this file
4. update the conflicting document as part of the same change when
   authorized

In particular, do not merge task code into local `main` merely because
an older document describes local-main E2E integration.

---

## 2. Instruction Scope

Do not maintain per-file lists in this root file. Route to the nearest
`AGENTS.md`, the package `README.md`, and the tests instead.

Common scoped rules:

| Area | Rules |
| --- | --- |
| Electron main process | `apps/desktop/electron/AGENTS.md` |
| Renderer & UI | `apps/desktop/src/AGENTS.md` |
| Rust host-core | `crates/host-core/AGENTS.md` |
| Node agent runtime | `packages/agent-runtime/AGENTS.md` |
| Plugin SDK | `packages/plugin-sdk/AGENTS.md` |
| Shared contracts | `packages/shared/AGENTS.md` |
| IPC surface | `apps/desktop/electron/ipc/AGENTS.md` |

Directories without a local `AGENTS.md` follow this file, the package
README, existing tests, and current code patterns.

---

## 3. Preserve Existing Behavior by Default

Unless the task explicitly requires behavior to change:

* do not remove existing functionality
* do not change user-visible behavior
* do not change default values
* do not change persisted data semantics
* do not change IPC / RPC contracts
* do not change Plugin SDK contracts
* do not weaken security or permissions
* do not introduce breaking changes

Refactoring must be behavior-preserving by default. Never hide a
behavior change inside a `refactor` commit.

If a breaking change is truly required, document:

* what breaks
* why it is necessary
* affected surfaces
* migration path
* compatibility impact

---

## 4. Respect the Architecture

Frozen process model:

```text
Renderer
   ↓
Preload IPC
   ↓
Electron Main
   ↓
Rust Host Core / Node Agent Runtime
   ↓
pi-ai / pi-agent-core
```

Ownership:

```text
Renderer       = UI and interaction