Pinvou Agent Project Conventions

Core constraints

0. Local private memory

• If .codex-memory.md exists at the repository root, read it before starting work. It is local private memory and must not be committed.

1. Development and pull request conventions

The contribution workflow — syncing origin/main, conflict-resolution expectations, commit-message format and DCO, PR language, and local/CI checks — is defined once in CONTRIBUTING.md. The rules below restate only what an agent working in this repository must apply to every task:

• Before the first development work for a new task and before creating its pull request, safely sync the latest origin/main and align every submodule with the parent repository gitlink. Do not repeatedly sync only because main advances during continued development or review of the same task. Before merge, the Merge Queue runs applicable gates against the combined tree on the latest main; manually rebase only when a real conflict or queue integration failure requires changing the branch.
• Before the final commit and pull request creation, self-review requirement completeness, root cause and related cases, implementation boundaries, impact on existing functionality, exceptional states, and verification sufficiency. Passing tests does not replace this review.
• Fix and verify any in-scope gap found during self-review. Disclose and await a decision for out-of-scope changes, mutually exclusive approaches, unverified scenarios, or regression risks.

2. CodeWhale and fork boundaries

CodeWhale provides the foundation for model calls, streaming output, tool loops, Sessions, Skills, Commands, MCP, Hooks, and Compaction. Pinvou Agent does not reimplement these capabilities.

Place extensions according to these boundaries:

• Keep Pinvou-specific semantics in the fork only when they must participate in the foundation lifecycle and cannot be implemented in the app, a Skill, or MCP. Prefer contributing reusable fixes upstream.
• When adding or modifying fork-distinct behavior, update docs/fork-modifications.md, the relevant fingerprints, and behavior tests in the same pull request, then run ./scripts/fork-guard.sh --fast.
• When only the CodeWhale gitlink changes without a behavior change, update the register and fingerprints as required by the guard. New behavior tests are not mandatory when existing tests can be shown to cover the behavior.
• Treat docs/fork-policy.md and docs/fork-modifications.md as the single sources of truth for the fork baseline, size, topics, and synchronization process.

3. Cross-platform architecture boundaries

Pinvou Agent is organized by business capability first and platform adaptation second:

• Keep business logic in features/. Only low-level capabilities reused across features belong in the global platform/. Dependencies must flow app → features → platform/core, never in reverse.
• React code must not inspect the user agent or access Tauri globals directly. Consume semantic capabilities through get_platform_capabilities and can(capability).
• Express OS differences with cfg(target_os) and explicit interfaces. Return unsupported explicitly for unavailable capabilities; do not silently reuse another platform's implementation.
• If conditional compilation or platform implementation details must remain outside an adapter layer, use an explicit exception supported by the architecture guard, document the concrete reason at the top of the file, and add a test covering the scenario. Exceptions must not be used merely to avoid moving a module.
• Use project npm commands for builds; do not run npx tauri build/bundle directly. After changes, run python3 scripts/architecture-guard.py and tests for the affected area.

Modular development conventions

• Define module boundaries by responsibility, state ownership, reason for change, dependency direction, and independent testability, not by file length or total repository size.
• Place new or modified functionality in a clearly scoped feature, platform, or core module. Do not continue adding unrelated responsibilities to an existing module. Coordinate across modules through narrow, stable interfaces.
• When responsibilities are mixed, state is coupled, dependencies point backward, or independent testing is difficult, split the code incrementally along behavior boundaries while preserving existing behavior and public API compatibility in every batch.
• Do not mechanically split files, compress code, or sacrifice naming, comments, error handling, or readability to satisfy a metric. File size is a review signal, not a compliance gate.

4. Community edition development conventions

• Before starting, search existing issues, pull requests, and foundation capabilities to avoid duplicate work. Confirm the approach and acceptance criteria before large features or breaking changes.
• Community features must work completely without private services, internal addresses, or enterprise-only data. Integrate enterprise capabilities through generic extension interfaces.
• New features must form a complete, usable workflow and handle key errors, insufficient permissions, and unsupported platforms. Placeholder code or fake data is not a completed implementation.
• Preserve compatibility with existing configuration, data, and public interfaces. Confirm unavoidable breaking changes first and provide a migration path and regression tests.
• Application UI copy must reuse pinvou3-app/src/shared/i18n.js and provide Simplified Chinese, English, and Japanese. Do not introduce single-language copy in components or depend on fallback from another language.
• Use secure defaults and clearly inform users when changes involve network access, uploads, external commands, or new dependencies. Update tests and documentation with behavior changes.
• Never put accounts, passwords, keys, tokens, cookies, customer or private data, or internal addresses in code, commits, pull requests, examples, or logs. Report suspected disclosures privately according to SECURITY.md.

Project facts

• pinvou3-app/: Tauri 2 + React/Vite desktop application and Engine wrapper.
• CodeWhale/: Pinvou/CodeWhale submodule; changes follow the CodeWhale and fork boundaries above.
• Runtime data is stored under ~/.pinvou3/ (sessions, settings.json, bundle, knowledge, and connectors).
• Bundle extension sources live in pinvou3-app/src-tauri/resources/common/bundle/; they are compiled into the application and extracted to ~/.pinvou3/bundle/.
• Start development with ./pinvou3-app/run-dev.sh.
• The root VERSION file is the single source of truth for the version. After changing it, run node scripts/sync-version.mjs; CI verifies consistency with --check.

Policy entry points

• CONTRIBUTING.md: single source of truth for contribution, DCO, checks, and pull request workflow. CONTRIBUTING.zh-CN.md is a Chinese reference; when content conflicts, CONTRIBUTING.md takes precedence.
• SECURITY.md: private reporting process for vulnerabilities and sensitive information.
• docs/fork-policy.md / docs/fork-modifications.md: CodeWhale fork policy and current inventory.
• pinvou3-app/src/ARCHITECTURE.md, pinvou3-app/src-tauri/src/README.md, and pinvou3-app/src-tauri/config/README.md: frontend, Rust, and platform configuration boundaries.
• docs/architecture-guard.md: architecture guard rules.
• docs/commit-message-convention.md: commit message convention.