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

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

bash scripts/install_hooks.sh

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

:sparkles: add workflow guardrails and CI checks

Run the local sync check when needed:

python3 scripts/check_doc_code_sync.py . --strict

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 scripts/install_hooks.sh

a design/code sync checker:

python3 scripts/check_doc_code_sync.py . --strict

a commit message validator:

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

2.2 KiB Raw Blame History