EmboFlow/docs/development-workflow.md

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:

make guardrails

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

5. Use The Local Hooks

Install local hooks once per clone:

make bootstrap

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

5.1 Preferred Local Commands

Use the repo entry commands instead of ad hoc command strings whenever possible:

make bootstrap
make test
make dev-api
make dev-web
make dev-worker
make serve-api
make serve-web
make infra-up
make infra-down
make guardrails

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.