| name | okr-harness |
| description | Quản lý mục tiêu OKR. Trigger: OKR, mục tiêu, dự án, kế hoạch, tracking, review, dashboard, tiến độ, inbox, capture, retro, bài học. |
OKR Harness: Orchestrator (skill-only)
Entry point quản lý mục tiêu OKR. Đọc state, route, chạy skill inline, tổng hợp kết quả.
Bản đồ skill
| Skill | Vai trò | Ghi |
|---|
okr-analyze | Phân tích read-only: metrics, issues, priority, dashboard, trace (xem lại history) | Không |
okr-init | Tạo/sửa objective, KR/KI, resources | Có |
okr-plan | Tạo/sửa plan, milestones, actions | Có |
okr-track | Track progress, deep review, inbox, closure, sync | Có |
okr-capture | Ghi nhanh vào inbox | Có (inbox) |
okr-retro | Rút bài học từ phiên, ghi .okr/lessons/ (record-only) | Có (lessons) |
okr-shared | Quy tắc chung: SOT, schemas, quality gate, delegate, priority | Không |
Phase 0: Context check
if .okr/ không tồn tại:
→ chạy okr-init mode new (inline)
return
else:
→ Phase 1 (đọc state + xác định intent)
Phase 1: Đọc state + xác định intent
Preload
Orchestrator tự đọc nhanh (không gọi skill) để xác định state. Đây là Tier 1 của Preload Contract (canonical: okr-shared/references/preload.md):
ls -1 .okr/ → cấp 1, KHÔNG đệ quy: phát hiện context/ + file lẻ/thư mục lạ (cho audit)
objective.md → frontmatter: type (project/ongoing), status, period
plan.md → frontmatter: có/không, counters
resources.md → đọc TOÀN BỘ body (capacity, skills, tool, tài liệu, ngân sách)
actions/ → scan frontmatter: count active, có overdue/blocked?
inbox/ → scan frontmatter: count pending
lessons/index.md → đọc TOÀN BỘ (bài học, auto-load mỗi phiên)
context/index.md → conditional: nạp TOÀN BỘ nếu context/ tồn tại (như lessons/index.md)
Chỉ frontmatter (trừ resources.md, lessons/index.md, và context/index.md khi tồn tại đọc toàn bộ). Không đọc objective/plan body, action body, log, archive, file detail bài học, hay context/<slug>.md body (on-demand, xem contract mục "KHÔNG preload").
Lessons đã nạp → dùng làm context định hướng khi skill đề xuất/điều chỉnh trong phiên (đối chiếu area/target liên quan). Quy tắc áp dụng: okr-shared/references/preload.md "Áp dụng lessons".
context/index.md (nếu nạp) → áp dụng quy tắc okr-shared/references/preload.md "Áp dụng context": trước khi skill ghi/đề xuất, quét cột "Khi nào cần đọc", nạp body file khớp. Mọi file mới sinh trong phiên phải reachable theo bản đồ neo (canonical: preload.md "Reachability khi ghi").
Intent routing
| State | User intent | Chạy skill (inline) |
|---|
| Chưa có .okr/ | Bất kỳ | okr-init new |
| Có objective, chưa plan | Mặc định | okr-plan new |
| Có objective + plan | Mặc định / "hôm nay" | okr-analyze (dashboard) |
| "sửa mục tiêu / KR / KI" | okr-init update-objective |
| "tài nguyên / capacity / skill / tool" | okr-init update-resource |
| "thêm action / sửa plan / sửa action" | okr-plan update |
| "track / cập nhật / update" | okr-analyze → okr-track light |
| "review sâu / đánh giá / phân tích" | okr-analyze deep → okr-track deep |
| "capture / ghi nhanh / note" | okr-capture |
| "inbox / xử lý inbox" | okr-track inbox-only |
| "tổng kết / closure / kết thúc" | okr-track closure |
| "trace / history / xem lại" | okr-analyze trace |
| "rút bài học / tổng kết phiên / retro" | okr-retro |
Collision: state gợi ý khác user intent → ưu tiên user intent + xác nhận lại.
Phase 2: Thực thi inline
Đọc SKILL.md của skill đích, theo đúng flow của nó. Khi một flow cần chuyển sang skill khác (vd track deep cần áp dụng thay đổi cấu trúc), đọc tiếp SKILL.md kia và thực thi, mang theo context đã có.
Dashboard (mặc định khi có plan)
Chạy okr-analyze (focus=full, max_items=2, horizon_days=3). Render dashboard + nhắc review nếu cần (xem "Nhắc review").
Track light
- Chạy
okr-analyze (focus: progress, overdue, blocked) → thu được analysis.
- Chạy
okr-track light, dùng analysis làm input. Tương tác user, cập nhật progress, archive, next action.
Deep review (chuỗi tuần tự inline, KHÔNG agent team)
- Chạy
okr-analyze mode deep: đọc toàn bộ .okr/ + log history, root cause mỗi issue (≥3 "tại sao?").
- Chạy
okr-track deep, mang theo analysis: trình bày root cause → đề xuất điều chỉnh → all-changes confirm. User chọn áp dụng.
- Ghi progress fields (việc của okr-track).
- Áp dụng thay đổi cấu trúc: với mỗi thay đổi đã confirm thuộc cấu trúc, đọc tiếp
okr-init/okr-plan và thực thi với pre_confirmed: true (xem okr-shared delegate-protocol). Cùng agent thực hiện, không spawn.
- Ghi log review.
Trước đây deep review chạy bằng agent team (analyst + tracker qua SendMessage). Skill-only gộp thành chuỗi tuần tự một agent: phân tích → track → áp dụng. Mất tính song song, đổi lại chạy được ở mọi nền tảng.
Init / Plan
Chạy okr-init (mode new/update-objective/update-resource) hoặc okr-plan (new/update). Tương tác user theo flow. Confirm trước ghi.
Capture
Chạy okr-capture: phân loại type, ghi inbox/YYYY-MM-DD-HHmm-slug.md. Xem okr-capture SKILL.md.
Inbox / Closure
Chạy okr-track với mode tương ứng (inbox-only / closure).
Trace
Chạy okr-analyze mode trace (read-only: xem lại history/archive/log). Xem okr-analyze/references/flow-trace.md.
Phase 3: Tổng hợp
- Gom kết quả các bước.
- Render tóm tắt cho user: thay đổi gì, next step gì.
- Gợi ý rút bài học nếu flow có thực chất (xem
## Rút bài học).
Error handling
| Lỗi | Xử lý |
|---|
.okr/ không tồn tại | Route okr-init new |
| File corrupt | Báo cụ thể file nào, đề xuất sửa |
| Skill flow lỗi giữa chừng | Báo bước nào lỗi, giữ thay đổi đã ghi, hỏi user tiếp |
| Phân tích thiếu dữ liệu | Tiếp tục với dữ liệu có, ghi rõ phần thiếu trong báo cáo |
Nhắc review
Khi hiển thị dashboard, áp quy tắc "Nhắc review" canonical ở okr-shared/references/metrics.md (first match, phân Project/Ongoing). Period overdue (Project) là cảnh báo riêng, ưu tiên cao hơn, render block đầu dashboard. KHÔNG định nghĩa ngưỡng riêng ở đây để tránh lệch với analyze/track.
Test scenarios
Happy path: Daily check-in
- User:
/okr-harness
- Orchestrator đọc state → có objective + plan + actions active
- Chạy
okr-analyze inline → dashboard
- Render: KR progress, action summary, top 2 priority, review reminder
- User: "track"
- Chạy
okr-analyze (analysis) → okr-track light inline
- Tương tác user, cập nhật, archive, next action
- Render tóm tắt
Happy path: Deep review
- User: "review sâu"
- Chạy
okr-analyze deep: root cause mọi issue
- Chạy
okr-track deep: trình bày root cause + đề xuất → all-changes confirm
- User approve → ghi progress fields
- Có thay đổi cấu trúc → đọc tiếp
okr-init/okr-plan (pre_confirmed) áp dụng inline
- Ghi log review
- Render tóm tắt toàn bộ thay đổi
Error path: Chưa init
- User:
/okr-harness
.okr/ không tồn tại- Chạy
okr-init new → hướng dẫn tạo objective + resource
Error path: Thiếu dữ liệu phân tích
okr-analyze gặp file thiếu frontmatter- Báo cụ thể file/field thiếu
- Tiếp tục track với phần dữ liệu có, ghi chú phần thiếu trong tóm tắt
Rút bài học
Thay cho cơ chế tự cải tiến cũ. Việc rút bài học do skill okr-retro đảm nhiệm, user chủ động.
Gợi ý cuối flow: sau khi tổng hợp (Phase 3), với flow có thực chất (track, deep review, init, plan, inbox; trừ dashboard/capture/trace đơn giản), thêm đúng 1 dòng:
"Muốn rút bài học phiên này? (chạy okr-retro)"
KHÔNG tự chạy. User đồng ý hoặc tự gõ "rút bài học" → chạy okr-retro inline.
okr-retro ghi 3 loại bài học vào .okr/lessons/ (skill = công cụ, workflow = bản đồ điều phối, project = tri thức):
- Loại A (skill/công cụ): năng lực harness, luôn shared. Hàng đợi port thủ công về repo gốc
objective-kit.
- Loại C (workflow/bản đồ): lưỡng tính. Shared = quy trình tổng quát chờ port; local = playbook riêng project, sống tại chỗ.
- Loại B (project/tri thức): dữ kiện tại chỗ, auto-load mỗi phiên qua index.
Record-only: okr-retro KHÔNG tự sửa file skill, KHÔNG ghi CHANGELOG. Chi tiết: okr-retro SKILL.md.
Tham khảo
- I/O từng skill:
references/skill-contract.md
- Sơ đồ luồng:
references/flows.md
