@starci/skills 1.1.0

package/workflows/README.md

@@ -0,0 +1,37 @@
+# Workflows
+
+A workflow is a pre-composed chain of operators: an ordered list of **steps**, each step a list of
+**branches** that run in parallel (at most three), with optional **loops** back to an earlier step and
+**presets** for a branch's Requirements. The files here are examples, not the only chains allowed.
+
+How the entry uses them:
+
+1. Read the `when` of every example. If the request matches one, run that chain; its presets fill
+   `request.json` and the person is asked only for fields with no default.
+2. If none matches, compose a chain from the operators' `## Next` tables and `routing.json`, under the
+   same rules `scripts/validate-workflows.mjs` enforces on these files:
+   - every branch names a real operator and presets only fields that operator declares;
+   - every required Input of a branch is produced by an earlier step;
+   - branches of one step share no write alias (two operators may not write the same checkout or
+     root at once; `frontend.surface.audit` fans out by matrix entry because it writes nothing);
+   - a loop goes back to an earlier step and carries `maxRounds`;
+   - the chain ends at `git.publish`, `release.deploy`, or `user`.
+3. A composed chain that would be useful again becomes a new file here, with its `when`.
+
+Every source-writing branch commits on `session/<sessionId>`; `git.publish` merges it. A blocked branch
+re-enters as a new step; a loop counts toward the operator's own `maxRounds`.
+
+| Workflow | When | Steps | Parallel | Ends |
+| --- | --- | --- | --- | --- |
+| `frontend-new-surface` | a surface that does not exist yet (`new`) | bind ×2 → business → direction → resolve → apply → audit → quality → publish | audit by matrix | `git.publish` |
+| `frontend-reconstruct` | rebuild an existing surface, business facts kept | bind → direction → resolve → apply → audit → quality → publish | audit by matrix | `git.publish` |
+| `frontend-refine` | repair inside an approved structure | bind → direction → resolve → apply → audit → quality → publish | audit by matrix | `git.publish` |
+| `backend-feature` | a backend contract for one feature | bind → business (model) → architecture → backend apply → quality → business (reconcile) → publish | — | `git.publish` |
+| `full-feature` | backend and a new frontend surface together | bind ×2 → business → architecture → [backend apply ∥ direction] → [quality ∥ resolve] → apply → audit → quality → business (reconcile) → publish | two steps of two, audit by matrix | `git.publish` |
+| `frontend-with-uat` | a frontend change a person asked to walk through | bind ×2 → … audit → quality → uat → publish | audit by matrix | `git.publish` |
+| `release` | a published head must reach production | bind → quality → release | — | `release.deploy` |
+| `content-unit` | one curriculum unit end to end | content.generate (review exchange inside) | — | `user` |
+
+File shape (`schemaVersion` 9): `id` equals the file name; `when` has `en` and `vi`; `chain` is an
+array of steps, each an array of `{ operator, requirements?, fanout?: "matrix", maxParallel?: 1..3 }`;
+`loops` is an array of `{ from, to, when, maxRounds }`; `ends` is `user` or an operator of the last step.

package/workflows/README.vi.md

@@ -0,0 +1,37 @@
+# Workflow
+
+Một workflow là một chuỗi operator ghép sẵn: danh sách **bậc** theo thứ tự, mỗi bậc là danh sách
+**nhánh** chạy song song (tối đa ba), kèm **vòng lặp** quay về một bậc trước và **preset** cho Yêu cầu
+của từng nhánh. Các file ở đây là ví dụ, không phải những chuỗi duy nhất được phép.
+
+Cửa vào dùng chúng như sau:
+
+1. Đọc `when` của mọi ví dụ. Request khớp ví dụ nào thì chạy chuỗi đó; preset điền vào
+   `request.json`, người chỉ bị hỏi những field không có mặc định.
+2. Không khớp cái nào thì tự ghép chuỗi từ bảng `## Next` của các operator và `routing.json`, theo
+   đúng luật mà `scripts/validate-workflows.mjs` ép lên các file này:
+   - mỗi nhánh gọi tên một operator có thật và chỉ preset field mà operator đó khai;
+   - mọi Input bắt buộc của một nhánh phải do một bậc trước sinh ra;
+   - các nhánh cùng bậc không chung alias ghi (hai operator không được cùng ghi một checkout hay một
+     root; `frontend.surface.audit` toả theo entry của matrix vì nó không ghi gì);
+   - vòng lặp quay về bậc trước và mang `maxRounds`;
+   - chuỗi kết thúc ở `git.publish`, `release.deploy` hoặc `user`.
+3. Chuỗi tự ghép mà còn dùng lại được thì thành một file mới ở đây, kèm `when`.
+
+Mọi nhánh ghi source đều commit trên `session/<sessionId>`; `git.publish` merge nó. Nhánh bị chặn vào
+lại thành bậc mới; vòng lặp tính vào `maxRounds` của chính operator.
+
+| Workflow | Khi | Các bậc | Song song | Kết thúc |
+| --- | --- | --- | --- | --- |
+| `frontend-new-surface` | bề mặt chưa tồn tại (`new`) | bind ×2 → business → direction → resolve → apply → audit → quality → publish | audit theo matrix | `git.publish` |
+| `frontend-reconstruct` | dựng lại bề mặt đã có, giữ fact nghiệp vụ | bind → direction → resolve → apply → audit → quality → publish | audit theo matrix | `git.publish` |
+| `frontend-refine` | sửa bên trong cấu trúc đã duyệt | bind → direction → resolve → apply → audit → quality → publish | audit theo matrix | `git.publish` |
+| `backend-feature` | một contract backend cho một feature | bind → business (model) → architecture → backend apply → quality → business (reconcile) → publish | — | `git.publish` |
+| `full-feature` | backend và bề mặt frontend mới cùng lúc | bind ×2 → business → architecture → [backend apply ∥ direction] → [quality ∥ resolve] → apply → audit → quality → business (reconcile) → publish | hai bậc hai nhánh, audit theo matrix | `git.publish` |
+| `frontend-with-uat` | thay đổi frontend mà người yêu cầu đi thử | bind ×2 → … audit → quality → uat → publish | audit theo matrix | `git.publish` |
+| `release` | head đã publish phải lên production | bind → quality → release | — | `release.deploy` |
+| `content-unit` | một đơn vị giáo trình từ đầu tới cuối | content.generate (có exchange review bên trong) | — | `user` |
+
+Hình dạng file (`schemaVersion` 9): `id` bằng tên file; `when` có `en` và `vi`; `chain` là mảng bậc,
+mỗi bậc là mảng `{ operator, requirements?, fanout?: "matrix", maxParallel?: 1..3 }`; `loops` là mảng
+`{ from, to, when, maxRounds }`; `ends` là `user` hoặc một operator của bậc cuối.

package/workflows/backend-feature.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 9,
+  "id": "backend-feature",
+  "when": {
+    "en": "Server behaviour, an API contract, persistence or a job changes for one business feature; the architecture is decided first and the promise is reconciled after the code lands.",
+    "vi": "Hành vi server, contract API, persistence hay job đổi cho một feature nghiệp vụ; kiến trúc quyết trước, lời hứa được đối chiếu sau khi code đã vào."
+  },
+  "chain": [
+    [
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "be"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "business.decide",
+        "requirements": {
+          "mode": "model"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "architecture.decide",
+        "requirements": {
+          "alternatives": 1,
+          "selectionPolicy": "automatic"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "backend.source.apply"
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      }
+    ],
+    [
+      {
+        "operator": "business.decide",
+        "requirements": {
+          "mode": "reconcile"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "git.publish"
+      }
+    ]
+  ],
+  "ends": "git.publish"
+}

package/workflows/content-unit.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 9,
+  "id": "content-unit",
+  "when": {
+    "en": "One curriculum unit needs its brief, its language editions, its code tracks and an independent review; publishing to MinIO stays with a person.",
+    "vi": "Một đơn vị giáo trình cần brief, các ấn bản ngôn ngữ, track code và một lượt review độc lập; đưa lên MinIO vẫn là việc của người."
+  },
+  "chain": [
+    [
+      {
+        "operator": "content.generate",
+        "requirements": {
+          "maxReviewRounds": 2
+        }
+      }
+    ]
+  ],
+  "ends": "user"
+}

package/workflows/frontend-new-surface.json

@@ -0,0 +1,81 @@
+{
+  "schemaVersion": 9,
+  "id": "frontend-new-surface",
+  "when": {
+    "en": "A page, flow, or surface that does not exist yet must be created; the person named the target route and its business promise is known or will be decided first.",
+    "vi": "Một trang, luồng hay bề mặt chưa tồn tại cần được tạo; người dùng nêu route đích, lời hứa nghiệp vụ đã có hoặc sẽ được quyết trước."
+  },
+  "chain": [
+    [
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "be"
+        }
+      },
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "fe",
+          "runtimeNeed": "consume"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "business.decide",
+        "requirements": {
+          "mode": "model"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.direction.decide",
+        "requirements": {
+          "intent": "create",
+          "changeLevel": "new"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.presentation.resolve"
+      }
+    ],
+    [
+      {
+        "operator": "frontend.source.apply",
+        "requirements": {
+          "mode": "apply"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.surface.audit",
+        "fanout": "matrix",
+        "maxParallel": 3
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      }
+    ],
+    [
+      {
+        "operator": "git.publish"
+      }
+    ]
+  ],
+  "ends": "git.publish",
+  "loops": [
+    {
+      "from": "frontend.surface.audit",
+      "to": "frontend.presentation.resolve",
+      "when": "an application-owned node fails a claim or a proof rule",
+      "maxRounds": 2
+    }
+  ]
+}

package/workflows/frontend-reconstruct.json

@@ -0,0 +1,67 @@
+{
+  "schemaVersion": 9,
+  "id": "frontend-reconstruct",
+  "when": {
+    "en": "An existing surface is rebuilt: composition, region order, hierarchy or responsive structure change while business facts, behaviour and API semantics stay.",
+    "vi": "Dựng lại một bề mặt đã có: đổi composition, thứ tự vùng, hierarchy hay cấu trúc responsive trong khi fact nghiệp vụ, hành vi và API giữ nguyên."
+  },
+  "chain": [
+    [
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "fe",
+          "runtimeNeed": "consume"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.direction.decide",
+        "requirements": {
+          "intent": "modify",
+          "changeLevel": "reconstruct"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.presentation.resolve"
+      }
+    ],
+    [
+      {
+        "operator": "frontend.source.apply",
+        "requirements": {
+          "mode": "apply"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.surface.audit",
+        "fanout": "matrix",
+        "maxParallel": 3
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      }
+    ],
+    [
+      {
+        "operator": "git.publish"
+      }
+    ]
+  ],
+  "ends": "git.publish",
+  "loops": [
+    {
+      "from": "frontend.surface.audit",
+      "to": "frontend.presentation.resolve",
+      "when": "an application-owned node fails a claim or a proof rule",
+      "maxRounds": 2
+    }
+  ]
+}

package/workflows/frontend-refine.json

@@ -0,0 +1,67 @@
+{
+  "schemaVersion": 9,
+  "id": "frontend-refine",
+  "when": {
+    "en": "The approved structure of a surface stays; only typography, spacing, labels, controls, states, tokens or Grammar conformance inside it are repaired.",
+    "vi": "Cấu trúc đã duyệt của bề mặt giữ nguyên; chỉ sửa typography, spacing, label, control, state, token hay conformance Grammar bên trong."
+  },
+  "chain": [
+    [
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "fe",
+          "runtimeNeed": "consume"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.direction.decide",
+        "requirements": {
+          "intent": "audit-repair",
+          "changeLevel": "refine"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.presentation.resolve"
+      }
+    ],
+    [
+      {
+        "operator": "frontend.source.apply",
+        "requirements": {
+          "mode": "apply"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.surface.audit",
+        "fanout": "matrix",
+        "maxParallel": 3
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      }
+    ],
+    [
+      {
+        "operator": "git.publish"
+      }
+    ]
+  ],
+  "ends": "git.publish",
+  "loops": [
+    {
+      "from": "frontend.surface.audit",
+      "to": "frontend.presentation.resolve",
+      "when": "an application-owned node fails a claim or a proof rule",
+      "maxRounds": 2
+    }
+  ]
+}

package/workflows/frontend-with-uat.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": 9,
+  "id": "frontend-with-uat",
+  "when": {
+    "en": "A frontend change must also be walked by a real person's journey before it is published; a person asked for the UAT run by name.",
+    "vi": "Một thay đổi frontend còn phải đi qua hành trình của người thật trước khi publish; có người yêu cầu đích danh lần chạy UAT."
+  },
+  "chain": [
+    [
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "be"
+        }
+      },
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "fe",
+          "runtimeNeed": "consume"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.direction.decide",
+        "requirements": {
+          "intent": "modify",
+          "changeLevel": "reconstruct"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.presentation.resolve"
+      }
+    ],
+    [
+      {
+        "operator": "frontend.source.apply",
+        "requirements": {
+          "mode": "apply"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.surface.audit",
+        "fanout": "matrix",
+        "maxParallel": 3
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      }
+    ],
+    [
+      {
+        "operator": "uat.verify"
+      }
+    ],
+    [
+      {
+        "operator": "git.publish"
+      }
+    ]
+  ],
+  "ends": "git.publish",
+  "loops": [
+    {
+      "from": "frontend.surface.audit",
+      "to": "frontend.presentation.resolve",
+      "when": "an application-owned node fails a claim or a proof rule",
+      "maxRounds": 2
+    }
+  ]
+}

package/workflows/full-feature.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": 9,
+  "id": "full-feature",
+  "when": {
+    "en": "One feature needs both a backend contract and a new frontend surface; backend implementation and frontend direction run side by side after the architecture is decided.",
+    "vi": "Một feature cần cả contract backend lẫn bề mặt frontend mới; hiện thực backend và hướng frontend chạy song song sau khi kiến trúc đã quyết."
+  },
+  "chain": [
+    [
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "be"
+        }
+      },
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "fe",
+          "runtimeNeed": "consume"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "business.decide",
+        "requirements": {
+          "mode": "model"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "architecture.decide",
+        "requirements": {
+          "alternatives": 1,
+          "selectionPolicy": "automatic"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "backend.source.apply"
+      },
+      {
+        "operator": "frontend.direction.decide",
+        "requirements": {
+          "intent": "create",
+          "changeLevel": "new"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      },
+      {
+        "operator": "frontend.presentation.resolve"
+      }
+    ],
+    [
+      {
+        "operator": "frontend.source.apply",
+        "requirements": {
+          "mode": "apply"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "frontend.surface.audit",
+        "fanout": "matrix",
+        "maxParallel": 3
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      }
+    ],
+    [
+      {
+        "operator": "business.decide",
+        "requirements": {
+          "mode": "reconcile"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "git.publish"
+      }
+    ]
+  ],
+  "ends": "git.publish",
+  "loops": [
+    {
+      "from": "frontend.surface.audit",
+      "to": "frontend.presentation.resolve",
+      "when": "an application-owned node fails a claim or a proof rule",
+      "maxRounds": 2
+    }
+  ]
+}

package/workflows/release.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": 9,
+  "id": "release",
+  "when": {
+    "en": "A published head must reach production: verify it, deploy it, and prove the steady state; recovery and rollback are inside release.deploy.",
+    "vi": "Một head đã publish phải lên production: kiểm, deploy và chứng minh trạng thái ổn định; phục hồi và rollback nằm trong release.deploy."
+  },
+  "chain": [
+    [
+      {
+        "operator": "workspace.bind",
+        "requirements": {
+          "role": "be"
+        }
+      }
+    ],
+    [
+      {
+        "operator": "quality.verify"
+      }
+    ],
+    [
+      {
+        "operator": "release.deploy"
+      }
+    ]
+  ],
+  "ends": "release.deploy"
+}