110 lines
2.5 KiB
Markdown
110 lines
2.5 KiB
Markdown
# 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
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make bootstrap
|
|
make test
|
|
make dev-api
|
|
make dev-web
|
|
make dev-worker
|
|
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.
|