@caiqueoak/flow 0.3.1 → 0.3.2

package/README.md

@@ -38,7 +38,7 @@ Flow internally loads only the guidance needed for discovery, planning, build, r
 
 When authorized, Flow keeps a concise artifact model: product truth in `PRD.md`, engineering truth in `ENGINEERING.md`, decisions in `DECISIONS.md`, execution context in `STATE.md`, the canonical work-item DAG in `BACKLOG.yaml`, and a human-readable derived projection in `GRAPH.md`. Work items use `SPEC.md` plus `TASKS.yaml`. `SUMMARY.md` is not part of the model.
 
-In `GRAPH.md`, work-item states are consistent: complete is green, in progress is blue, blocked is red when unfinished dependencies remain, and pending is yellow when all dependencies are complete and the item is ready to execute.
+In `GRAPH.md`, work-item states are consistent: complete is green, in progress is blue, blocked is red when unfinished dependencies remain, and pending is yellow when all dependencies are complete and the item is ready to execute. Each Mermaid card contains only the work-item ID and canonical title. Every dependency arrow goes from dependency to dependent item and uses the color and line style of its source card.
 
 ## Update
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caiqueoak/flow",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Readability-first, agent-agnostic software development workflow for coding agents.",
   "type": "module",
   "scripts": {

package/skills/flow/SKILL.md

@@ -47,7 +47,7 @@ Graph/control data is YAML:
 
 Do not create `SUMMARY.md`, completion logs, ad-hoc progress documents, handoff documents, reports, or any other new project artifact unless the developer explicitly requests or authorizes them. Completed `SPEC.md` files retain concise Overview and Validation sections.
 
-`GRAPH.md` is derived only. It must never become an independent source of truth and must be reconciled whenever work-item existence, dependencies, or status change. Preserve its established visual style and conventions while updating it.
+`GRAPH.md` is derived only. It must never become an independent source of truth and must be reconciled whenever work-item existence, title, dependencies, or status change. Before creating or changing it, read `references/graph.md` and follow that contract exactly; do not preserve an established style that conflicts with it.
 
 ## Work item model
 
@@ -121,6 +121,7 @@ Load only the reference needed for current state:
 - Ready planned tasks: `references/build.md`
 - Completed implementation awaiting validation: `references/review.md`
 - Decision impact or inconsistent artifacts: `references/reconcile.md`
+- Creating or updating `GRAPH.md`: additionally load `references/graph.md`
 
 ## Orchestration loop
 

package/skills/flow/references/graph.md

@@ -0,0 +1,62 @@
+# `GRAPH.md` Rules
+
+Every Flow `GRAPH.md` must be a derived, human-readable projection of
+`.flow/BACKLOG.yaml`. It never becomes an independent source of truth.
+
+## Card content
+
+Each Mermaid card contains exactly two lines:
+
+```text
+<work-item ID>
+<work-item title>
+```
+
+Do not include status, priority, folder, dependency lists, or explanatory
+prose inside a card. The title is the canonical `title` value from
+`BACKLOG.yaml`.
+
+## Status derivation and colors
+
+Derive status from the backlog and dependencies after every meaningful state
+transition.
+
+| Status | Meaning | Card color | Outgoing arrow style |
+| --- | --- | --- | --- |
+| Complete | Work item is accepted and complete. | Green (`#16a34a`) | Solid green |
+| In progress | Work item has active execution. | Blue (`#2563eb`) | Solid blue, thicker |
+| Pending | Every dependency is complete and the item is ready to start. | Yellow (`#d97706`) | Dashed yellow |
+| Blocked | The item is neither complete nor in progress and one or more dependencies are incomplete. | Red (`#dc2626`) | Dotted red |
+
+Use matching fill, stroke, and readable text colors for cards. Every graph
+must include a titled status legend using these colors.
+
+## Dependencies and arrows
+
+- Draw one arrow for every `depends_on` relationship in `BACKLOG.yaml`.
+- The arrow goes from dependency to dependent item.
+- Every outgoing arrow inherits the color and line style of its source card.
+- Recalculate Mermaid `linkStyle` indexes whenever edges change; do not leave
+  a stale style assignment behind.
+- Do not add visual-only dependency edges to force layout.
+
+## Parallelism and layout
+
+- Items on the same vertical rank must have no dependency on one another and
+  are candidates for parallel work.
+- Keep independent, ready items on the same vertical rank where Mermaid can
+  represent the real dependency graph without artificial edges.
+- Do not represent blocked items as pending merely because they are planned;
+  dependency readiness determines their graph status.
+
+## Synchronization checklist
+
+When work-item state, existence, title, or dependencies change:
+
+1. Update `BACKLOG.yaml` first.
+2. Recompute derived statuses using the definitions above.
+3. Update `GRAPH.md`, including cards, arrows, styles, legend, and parallel
+   layout.
+4. Update `STATE.md` when the active path or next ready work changes.
+5. Verify that every backlog item appears exactly once and every dependency
+   appears exactly once in the graph.