project-orchestrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Orchestrator

项目协调器

Đây là skill điều phối duy nhất mà agent load ĐẦU TIÊN cho mọi yêu cầu liên quan đến app Flutter trong project. Nó không viết code, chỉ quyết định bước tiếp theo và load đúng 1 skill con tương ứng.

这是代理针对项目中所有Flutter应用相关请求首先加载的唯一协调技能。它不编写代码，仅决定下一步操作并加载对应的子技能。

Nguyên tắc

原则

Một Agent CLI duy nhất, không spawn agent con, không mô phỏng multi-agent.
Mỗi bước chỉ load đúng 1 skill con cần thiết, không load tất cả cùng lúc (tránh loãng context).
OpenSpec (CLI thật của Fission-AI, không phải 1 file .md đơn) là nguồn sự thật duy nhất:
- ```
openspec/specs/<domain>/spec.md
```
  — hành vi hiện tại của hệ thống (source of truth).
- ```
openspec/changes/<change-name>/{proposal.md, design.md, tasks.md, specs/<domain>/spec.md}
```
  — đề xuất thay đổi đang làm dở (delta spec).
- ```
openspec/config.yaml
```
  — context/tech stack cố định (Flutter, Riverpod, GoRouter, Feature-First) và rules, được tự động inject vào mọi artifact, KHÔNG cần agent tự nhắc lại các rule này mỗi lần.
QUAN TRỌNG - phân định trách nhiệm:
```
flutter-skill
```
KHÔNG được tự ý đọc/ghi trực tiếp vào
```
openspec/specs/
```
hay
```
openspec/changes/
```
bằng cách tự bịa thao tác file, và KHÔNG tự chạy raw
```
openspec
```
CLI qua bash để thay thế vòng đời spec. Toàn bộ vòng đời change (tạo, sinh artifact, thực thi, validate, merge) PHẢI đi qua slash command
```
/opsx:*
```
đã cấu hình (profile mở rộng:
```
new
```
,
```
continue
```
,
```
ff
```
,
```
propose
```
,
```
explore
```
,
```
apply
```
,
```
verify
```
,
```
sync
```
,
```
archive
```
,
```
bulk-archive
```
,
```
onboard
```
).
```
flutter-skill
```
là kỹ thuật Flutter cụ thể được dùng BÊN TRONG các bước đó (đặc biệt là trong
```
/opsx:apply
```
), không phải lớp thay thế chúng.
Không hỏi lại user những thứ có thể suy ra từ
```
config.yaml
```
/
```
specs/
```
hiện có hoặc dùng mặc định hợp lý (xem phần "Quy tắc mặc định" bên dưới), NHƯNG luôn hỏi user ở bước UI-checkpoint (trong bước 4, mỗi khi task có UI) - đây là điểm dừng có chủ đích, không phải điểm dừng do thiếu thông tin.

仅使用一个Agent CLI，不生成子代理，不模拟多代理模式。
每个步骤仅加载所需的一个子技能，不同时加载所有技能（避免上下文分散）。
OpenSpec（Fission-AI的真实CLI，而非单一.md文件）是唯一的事实来源：
- ```
openspec/specs/<domain>/spec.md
```
  — 系统当前行为（事实来源）。
- ```
openspec/changes/<change-name>/{proposal.md, design.md, tasks.md, specs/<domain>/spec.md}
```
  — 正在进行的变更提案（增量规范）。
- ```
openspec/config.yaml
```
  — 固定上下文/技术栈（Flutter、Riverpod、GoRouter、Feature-First）及规则，会自动注入到所有工件中，无需代理每次重复提及这些规则。
重要 - 职责划分：
```
flutter-skill
```
不得擅自通过伪造文件操作直接读写
```
openspec/specs/
```
或
```
openspec/changes/
```
，也不得通过bash直接运行原始
```
openspec
```
CLI来替代规范生命周期。整个变更生命周期（创建、生成工件、执行、验证、合并）必须通过已配置的斜杠命令
```
/opsx:*
```
完成（扩展配置：
```
new
```
,
```
continue
```
,
```
ff
```
,
```
propose
```
,
```
explore
```
,
```
apply
```
,
```
verify
```
,
```
sync
```
,
```
archive
```
,
```
bulk-archive
```
,
```
onboard
```
）。
```
flutter-skill
```
是在这些步骤中（尤其是
```
/opsx:apply
```
内）使用的特定Flutter技术，而非它们的替代层。
对于可从现有
```
config.yaml
```
/
```
specs/
```
推导或使用合理默认值的信息，无需再次询问用户（见下文“默认规则”部分），但在UI检查点步骤（步骤4中，只要任务涉及UI）必须询问用户——这是有意设置的暂停点，而非因信息缺失导致的暂停。

Quy trình (checklist tuần tự, map đúng vào vòng đời opsx thật)

流程（顺序清单，与真实opsx生命周期对应）

Giai đoạn Planning (opsx tự lo, flutter-skill chỉ đọc kết quả)

规划阶段（opsx自动处理，flutter-skill仅读取结果）

Nếu chưa rõ hướng đi →
```
/opsx:explore
```
để bàn trước (không tạo file). Nếu đã rõ →
```
/opsx:new <ten-change>
```
để tạo scaffold, rồi
```
/opsx:ff
```
(nhanh, sinh hết artifact 1 lần) hoặc
```
/opsx:continue
```
(từng bước, review kỹ hơn) để có đủ
```
proposal.md
```
+
```
specs/
```
(delta) +
```
design.md
```
+
```
tasks.md
```
. Nếu muốn gộp 2 bước làm 1: dùng
```
/opsx:propose <ten-change>
```
thay cho
```
new
```
+
```
ff
```
.
- ```
flutter-skill
```
  KHÔNG tự viết
```
proposal.md
```
  /
```
tasks.md
```
  thay cho opsx.
Đọc kết quả:
```
tasks.md
```
(danh sách việc cần làm) + delta
```
specs/<domain>/spec.md
```
(yêu cầu/data model mới) trong
```
changes/<change-name>/
```
.

1.5. Load

git-checkpoint/SKILL.md

phần "Branch theo từng change" — tạo/chuyển sang branch

change/<change-name>

NGAY trước khi đụng vào code, không code thẳng trên

main

So sánh Data Model giữa delta spec (bước 1) và spec đã archive (
```
openspec/specs/<domain>/spec.md
```
).
- Nếu có thay đổi field/bảng → load
```
schema-migration/SKILL.md
```
  TRƯỚC KHI vào giai đoạn Implementation.
- Nếu không đổi model → bỏ qua, sang bước 3.
Load
```
architecture/SKILL.md
```
+
```
design-system/SKILL.md
```
để xác nhận blueprint/token trước khi code (không tự quyết định lại nếu đã khóa trong
```
config.yaml
```
).

若方向不明确 → 使用
```
/opsx:explore
```
先进行讨论（不创建文件）。若方向明确 → 使用
```
/opsx:new <变更名称>
```
创建脚手架，然后使用
```
/opsx:ff
```
（快速模式，一次性生成所有工件）或
```
/opsx:continue
```
（分步模式，更细致审核）生成完整的
```
proposal.md
```
+
```
specs/
```
（增量） +
```
design.md
```
+
```
tasks.md
```
。若想合并两步操作：使用
```
/opsx:propose <变更名称>
```
替代
```
new
```
+
```
ff
```
。
- ```
flutter-skill
```
  不得替代opsx编写
```
proposal.md
```
  /
```
tasks.md
```
  。
读取结果：
```
changes/<变更名称>/
```
下的
```
tasks.md
```
（待办任务列表） + 增量
```
specs/<domain>/spec.md
```
（新需求/数据模型）。

1.5. 加载

git-checkpoint/SKILL.md

中“按变更创建分支”部分 — 在接触代码前立即创建/切换到

change/<变更名称>

分支，不得直接在

main

分支上编码。

对比数据模型：将增量规范（步骤1）与已归档的规范（
```
openspec/specs/<domain>/spec.md
```
）进行对比。
- 若字段/表有变更 → 在进入实施阶段前加载
```
schema-migration/SKILL.md
```
  。
- 若模型无变更 → 跳过此步骤，进入步骤3。
加载
```
architecture/SKILL.md
```
+
```
design-system/SKILL.md
```
，在编码前确认蓝图/令牌（若已在
```
config.yaml
```
中锁定，则不得自行重新决定）。

Giai đoạn Implementation — chạy BÊN TRONG

/opsx:apply

实施阶段 — 在

/opsx:apply

内运行

Gọi
```
/opsx:apply
```
để bắt đầu thực thi
```
tasks.md
```
. Với MỖI task trong danh sách:
- Nếu task cần logic phía server (tính toán tiền, phân quyền phức tạp, webhook, cron - xem điều kiện chi tiết trong
```
backend-coding/SKILL.md
```
  ) → load
```
backend-coding/SKILL.md
```
  TRƯỚC, viết schema/RLS/Edge Function xong mới sang bước code Flutter. Nếu task chỉ là CRUD đơn giản → bỏ qua bước này,
```
flutter-coding
```
  tự gọi Supabase client SDK trực tiếp.
- Load
```
flutter-coding/SKILL.md
```
  để sinh code Flutter cho task đó (dựa trên
```
agent-plugins
```
  , tuân theo architecture/design-system, gọi đúng RPC/Edge Function/table vừa tạo nếu có).
- Load
```
mcp-loop/SKILL.md
```
  để build/chạy/tự sửa lỗi ngay sau khi code xong task đó (tối đa 5 lần lặp) - test cả luồng client gọi backend thật, không chỉ UI.
- Nếu lỗi lặp do API/package deprecated →
```
rag-fallback/SKILL.md
```
  , thử tối đa 2 lần nữa.
- Đánh dấu task hoàn thành trong
```
tasks.md
```
  (theo đúng cơ chế
```
/opsx:apply
```
  đang track), rồi sang task tiếp theo.
- Nếu 1 task có phần UI đáng kể → load
```
ui-checkpoint/SKILL.md
```
  ngay sau khi task đó pass MCP, hỏi user xác nhận trước khi coi task này là "done".

调用
```
/opsx:apply
```
开始执行
```
tasks.md
```
。对于列表中的每个任务：
- 若任务涉及服务端逻辑（金额计算、复杂权限、webhook、定时任务 - 详见
```
backend-coding/SKILL.md
```
  中的条件）→ 先加载
```
backend-coding/SKILL.md
```
  ，完成schema/RLS/Edge Function编写后再进入Flutter编码步骤。若任务仅为简单CRUD → 跳过此步骤，
```
flutter-coding
```
  直接调用Supabase客户端SDK。
- 加载
```
flutter-coding/SKILL.md
```
  为该任务生成Flutter代码（基于
```
agent-plugins
```
  ，遵循架构/设计系统，若已创建则调用正确的RPC/Edge Function/表）。
- 加载
```
mcp-loop/SKILL.md
```
  在任务编码完成后立即构建/运行/自动修复错误（最多循环5次） - 测试客户端调用真实服务端的完整流程，而非仅测试UI。
- 若因API/包弃用导致重复错误 → 使用
```
rag-fallback/SKILL.md
```
  ，最多再尝试2次。
- 在
```
tasks.md
```
  中标记任务完成（遵循
```
/opsx:apply
```
  的跟踪机制），然后进入下一个任务。
- 若某任务包含大量UI内容 → 在该任务通过MCP后立即加载
```
ui-checkpoint/SKILL.md
```
  ，询问用户确认后再将该任务标记为“完成”。

Giai đoạn Đóng gói (opsx tự lo, flutter-skill chỉ trigger đúng lúc)

打包阶段（opsx自动处理，flutter-skill仅在正确时机触发）

Sau khi TẤT CẢ task trong
```
tasks.md
```
pass (mcp-loop + ui-checkpoint đều OK) → gọi
```
/opsx:verify
```
để chạy validation gate cuối cùng của OpenSpec.
Nếu
```
/opsx:verify
```
pass → load
```
git-checkpoint/SKILL.md
```
để commit code, sau đó gọi
```
/opsx:sync
```
(merge delta spec vào spec chính, dùng cho checkpoint) rồi
```
/opsx:archive
```
(hoàn tất change, chuyển vào
```
changes/archive/
```
). Sau khi archive xong,
```
git-checkpoint
```
merge branch
```
change/<change-name>
```
vào
```
main
```
và xóa branch.
- Có thể gọi
```
/opsx:sync
```
  sớm hơn (giữa chừng, sau vài task) nếu muốn checkpoint nhỏ hơn - không bắt buộc chờ đến cuối.
Chỉ khi user yêu cầu rõ ràng ("build apk", "đóng gói") → load
```
release/SKILL.md
```
. Không tự động build mỗi lần archive xong.

当
```
tasks.md
```
中所有任务通过（mcp-loop + ui-checkpoint均通过）→ 调用
```
/opsx:verify
```
运行OpenSpec的最终验证关卡。
若
```
/opsx:verify
```
通过 → 加载
```
git-checkpoint/SKILL.md
```
提交代码，然后调用
```
/opsx:sync
```
（将增量规范合并到主规范，用于检查点）再调用
```
/opsx:archive
```
（完成变更，移至
```
changes/archive/
```
）。归档完成后，
```
git-checkpoint
```
将
```
change/<变更名称>
```
分支合并到
```
main
```
并删除该分支。
- 若需要更小的检查点，可提前调用
```
/opsx:sync
```
  （中途完成几个任务后），无需等到最后。
仅当用户明确要求（如“构建apk”、“打包”）→ 加载
```
release/SKILL.md
```
。不得在每次归档完成后自动构建。

Quy tắc mặc định (Fallback Rules) - dùng khi

config.yaml

specs/

chưa nói rõ

默认规则（回退规则）- 当

config.yaml

specs/

未明确说明时使用

Nên khai báo sẵn các mặc định này trong

openspec/config.yaml

(mục

context

rules

) để không phải lặp lại mỗi lần:

Chưa chỉ định backend → mặc định Firebase (đơn giản nhất cho MVP).
Chưa chỉ định state management → Riverpod (đã khóa trong architecture.md, không đổi giữa chừng).
Chưa chỉ định style → Material 3, theo
```
design-system/SKILL.md
```
.
Chưa chỉ định nền tảng build → mặc định APK (iOS cần máy Mac, hỏi lại nếu user yêu cầu iOS mà đang không phải Mac).

建议在

openspec/config.yaml

的

context

rules

部分预先声明这些默认值，避免每次重复：

未指定服务端 → 默认使用Firebase（MVP最简方案）。
未指定状态管理 → 使用Riverpod（已在architecture.md中锁定，中途不得更改）。
未指定样式 → 使用Material 3，遵循
```
design-system/SKILL.md
```
。
未指定构建平台 → 默认构建APK（iOS需要Mac设备，若用户要求iOS但当前非Mac环境则需询问）。

3 trường hợp PHẢI dừng và hỏi user (không tự động hóa)

必须暂停并询问用户的3种情况

Thiếu API key/credentials (Firebase, Google Maps...).
Lỗi compile lặp lại sau khi đã thử
```
mcp-loop
```
+
```
rag-fallback
```
.
Yêu cầu vượt khả năng môi trường hiện tại (build iOS trên Windows/Linux).

Ngoài 3 trường hợp trên và bước UI-checkpoint (trong bước 4, mỗi khi task có UI), agent chạy hết một lượt mà không dừng hỏi lặt vặt.

缺少API密钥/凭证（Firebase、Google Maps等）。
在尝试
```
mcp-loop
```
+
```
rag-fallback
```
后仍重复出现编译错误。
请求超出当前环境能力（如在Windows/Linux上构建iOS）。

除上述3种情况及UI检查点（步骤4中，只要任务涉及UI）外，代理应一次性运行完成，无需中途反复询问。

project-orchestrator

Original

Translation

Project Orchestrator

项目协调器

Nguyên tắc

原则

Quy trình (checklist tuần tự, map đúng vào vòng đời opsx thật)

流程（顺序清单，与真实opsx生命周期对应）

Giai đoạn Planning (opsx tự lo, flutter-skill chỉ đọc kết quả)

规划阶段（opsx自动处理，flutter-skill仅读取结果）

Giai đoạn Implementation — chạy BÊN TRONG
`/opsx:apply`

实施阶段 — 在
`/opsx:apply`
内运行

Giai đoạn Đóng gói (opsx tự lo, flutter-skill chỉ trigger đúng lúc)

打包阶段（opsx自动处理，flutter-skill仅在正确时机触发）

Quy tắc mặc định (Fallback Rules) - dùng khi
`config.yaml`
/
`specs/`
chưa nói rõ

默认规则（回退规则）- 当
`config.yaml`
/
`specs/`
未明确说明时使用

3 trường hợp PHẢI dừng và hỏi user (không tự động hóa)

必须暂停并询问用户的3种情况

project-orchestrator

Original

Translation

Project Orchestrator

项目协调器

Nguyên tắc

原则

Quy trình (checklist tuần tự, map đúng vào vòng đời opsx thật)

流程（顺序清单，与真实opsx生命周期对应）

Giai đoạn Planning (opsx tự lo, flutter-skill chỉ đọc kết quả)

规划阶段（opsx自动处理，flutter-skill仅读取结果）

Giai đoạn Implementation — chạy BÊN TRONG /opsx:apply

实施阶段 — 在/opsx:apply内运行

Giai đoạn Đóng gói (opsx tự lo, flutter-skill chỉ trigger đúng lúc)

打包阶段（opsx自动处理，flutter-skill仅在正确时机触发）

Quy tắc mặc định (Fallback Rules) - dùng khi config.yaml/specs/ chưa nói rõ

默认规则（回退规则）- 当config.yaml/specs/未明确说明时使用

3 trường hợp PHẢI dừng và hỏi user (không tự động hóa)

必须暂停并询问用户的3种情况

Giai đoạn Implementation — chạy BÊN TRONG
`/opsx:apply`

实施阶段 — 在
`/opsx:apply`
内运行

Quy tắc mặc định (Fallback Rules) - dùng khi
`config.yaml`
/
`specs/`
chưa nói rõ

默认规则（回退规则）- 当
`config.yaml`
/
`specs/`
未明确说明时使用