> For the complete documentation index, see [llms.txt](https://evo-5.gitbook.io/evo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://evo-5.gitbook.io/evo/development/contributing.md).

# Contributing

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

## Getting Started

```bash
# 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](/evo/development/project-rules.md)

## 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`](/evo/architecture/design-principles.md) (Chinese, internal reference)
* **Storage decisions**: [`docs/storage-architecture.md`](/evo/architecture/storage-architecture.md)
* **Open-source principles**: [`docs/design-principles.md`](/evo/architecture/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:

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

## Questions?

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://evo-5.gitbook.io/evo/development/contributing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.