# 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:

```bash
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
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.