Contributing

Contributions are welcome! This guide covers the development workflow and requirements.

Getting Started

# Clone the repository
git clone https://github.com/TIZ36/evo.git
cd evo

# Install dependencies
pnpm install

# Run the full check suite
pnpm check

Development Commands

Command	Description
pnpm test	Run tests with Vitest
pnpm typecheck	TypeScript type checking
pnpm build	Build all packages and plugin bundle
pnpm check	Full verification: test + typecheck + build + rule scan
pnpm rule:scan	Scan for sensitive information violations

Before Opening a PR

1. Run the full check: pnpm check must pass
2. Keep changes scoped: One topic per PR
3. Follow project rules: See Project Rules

Project Structure

evo/
├── src/
│   ├── core/           # Memory domain model and interfaces
│   ├── cordis/         # Cordis plugin
│   ├── deepseek/       # DeepSeek Harness adapter
│   ├── hook/           # Claude Code / Codex hook
│   └── client/         # Web panel (plain JS)
├── plugin/             # Pre-built plugin bundle for marketplaces
├── tests/              # Test suites
├── docs/               # This documentation
├── examples/           # Configuration examples
└── scripts/            # Build and maintenance scripts

Plugin Bundle

The plugin/ directory contains a pre-built bundle committed to the repository:

• Both Claude Code and Codex install plugins by copying the repo
• They run no build step and don't restore pnpm dependencies
• So the plugin must be runnable exactly as checked in

pnpm build regenerates the bundle, and pnpm test fails if it drifts from source.

Design Documents

• Design authority: docs/reference/evo-reference.md (Chinese, internal reference)
• Storage decisions: docs/storage-architecture.md
• Open-source principles: docs/design-principles.md

Code Style

• TypeScript with strict mode
• ESM modules ("type": "module")
• No unnecessary comments — code should be self-explanatory
• Interfaces over concrete types for extensibility

Testing

Tests use Vitest and cover:

• Core memory operations
• Reflection and consolidation
• Hook behavior
• Iron rule enforcement (no sensitive data)

Run specific tests:

pnpm test -- tests/core/
pnpm test -- --grep "reflection"

Questions?

Open an issue on GitHub for questions or discussions before starting large changes.