# Contributing To EmboFlow

## Core Rule

Keep `design/` and implementation aligned in the same change set.

Do not treat design files as background notes. If a code change affects product behavior, workflow behavior, data models, contracts, runtime assumptions, permissions, or deployment assumptions, update the corresponding design documents before closing the task.

## Required Workflow

1. Read the relevant files under `design/` before implementing.
2. Summarize the intended contract you are changing.
3. Implement the code change.
4. Update the affected design files in the same work session.
5. Install the local git hooks once per clone:

```bash
bash scripts/install_hooks.sh
```

6. Use English-only commit messages with a gitmoji prefix, for example:

```text
:sparkles: add workflow guardrails and CI checks
```

7. Run the local sync check when needed:

```bash
python3 scripts/check_doc_code_sync.py . --strict
```

8. If design and code still diverge, document that explicitly in your final summary.

## When Design Updates Are Required

Update design files when a change affects:

- user-visible behavior
- workflow nodes or execution paths
- data model or storage structure
- API or schema contracts
- plugin or executor behavior
- workspace, project, or permission rules
- deployment or runtime assumptions

## When Design Updates May Be Skipped

Design updates are usually not required for:

- pure refactors with no behavior change
- test-only changes
- formatting, comments, and naming cleanup

Even in those cases, verify that no documented statement became false indirectly.

## Primary Design Locations

- `design/00-overview/`
- `design/01-product/`
- `design/02-architecture/`
- `design/03-workflows/`
- `design/05-data/`
- `design/08-decisions/`

## Local Tooling

This repository includes:

- git hook templates under `.githooks/`
- a hook installer:

```bash
bash scripts/install_hooks.sh
```

- a design/code sync checker:

```bash
python3 scripts/check_doc_code_sync.py . --strict
```

- a commit message validator:

```bash
python3 scripts/check_commit_message.py --rev-range HEAD
```

The hooks and CI enforce:

- English-only commit messages with a gitmoji prefix
- design/code consistency checks
- repository unit tests before push