EmboFlow Development Workflow

Goal

Keep repository design artifacts and implementation changes aligned as EmboFlow evolves.

Working Agreement

EmboFlow is being developed from explicit design documents under design/. Development should follow a doc-aware workflow instead of letting code drift ahead without recorded decisions.

Standard Change Flow

1. Read Before Editing

Before changing code, review the design files that define the affected area:

product scope
architecture boundaries
workflow model
data model
deployment model
accepted ADRs

2. Identify Impact

Decide whether the change affects:

product behavior
object model
workflow/run/task semantics
node or plugin contract
storage assumptions
user or permission behavior
deployment/runtime assumptions

If yes, the matching design files must be updated.

3. Change Code And Docs Together

Do not defer the design update. Treat design edits as part of the implementation, not follow-up cleanup.

4. Run The Consistency Check

From the repo root:

python3 scripts/check_doc_code_sync.py . --strict

Interpret warnings manually. The script is a guardrail, not a replacement for judgment.

5. Use The Local Hooks

Install local hooks once per clone:

bash scripts/install_hooks.sh

This enables:

commit-msg: require English-only gitmoji commit messages
pre-commit: block staged code/config drift without doc updates
pre-push: run commit-message validation, doc/code sync checks, and repository tests

6. Close With Explicit Status

Every implementation summary should state one of:

Aligned
Partially aligned
Doc-first

and name the exact design files that were reviewed or updated.

EmboFlow-Specific Review Checklist

Before closing a non-trivial change, confirm whether any of these need updates:

raw asset vs canonical dataset model
workflow definition vs workflow run model
node schema and plugin contract
executor vs scheduler separation
MongoDB collection or document shape
workspace/project/user boundary
deployment topology or storage assumptions

Automation

This repository now uses both local and remote guardrails:

local git hooks from .githooks/
commit message validation
CI checks in .github/workflows/guardrails.yml

These checks are intended to keep design documents, code changes, and commit history coherent.

2.4 KiB Raw Blame History