| name | pk-harness |
| description | Orchestrator cho bộ pk-*. Dùng khi yêu cầu phức hợp cần phối hợp nhiều skill (vừa plan vừa track, vừa capture vừa distill), hoặc khi không rõ nên dùng skill pk-* nào. Cũng dùng khi user muốn xem bức tranh toàn cảnh dự án, hoặc yêu cầu workflow nhiều bước liên quan .cockpit/. KHÔNG dùng nếu yêu cầu rõ ràng khớp một skill pk-* cụ thể. |
PK Harness: Orchestrator (skill-only)
Entry point quản lý dự án + tri thức. Đọc state, route, chạy skill inline, tổng hợp kết quả.
Bản đồ skill
| Skill | Lớp | Vai trò | Ghi |
|---|
pk-analyze | 4 | Phân tích read-only: metrics, dashboard, issues | Không |
pk-init | 4 | Tạo/sửa objective, tools, constraints | Có |
pk-plan | 2 | Tạo/sửa plan, milestones, actions | Có |
pk-track | 2 | Track progress, deep review, inbox execution | Có |
pk-capture | 3 | Ghi nhanh vào inbox thống nhất | Có (inbox) |
pk-reflect | 2 | Rút bài học (light/deep) | Có (qua capture) |
pk-distill | 3 | Đúc kết inbox knowledge → wiki/skills/workflows | Có (knowledge) |
pk-consult | 3 | Tham vấn tri thức (query/run/teach) | Có (log usage) |
pk-lint | 3 | Rà soát, dọn dẹp, schema evolution | Có (sửa/evolve) |
pk-shared | 4 | Quy tắc chung: 6 reference files | Không (tham khảo) |
Phase 0: Context check
if .cockpit/ không tồn tại:
→ chạy pk-init mode new (inline)
return
else:
→ Phase 1
Phase 1: Snapshot + Intent routing
Snapshot
Tự đọc context snapshot duy nhất (../pk-shared/references/snapshot-contract.md):
ls -1 .cockpit/ # Detect cấu trúc
objective.md toàn bộ
tools.md toàn bộ
plan.md frontmatter
actions/ scan frontmatter
inbox/ scan frontmatter + captured_at mỗi item
schema-signals.md toàn bộ
SCHEMA.md toàn bộ
knowledge/index.md toàn bộ
skills/registry.md toàn bộ
workflows/registry.md toàn bộ
Pinned pages full body
6 file thuộc khối @ của AGENTS.md (objective.md, tools.md, SCHEMA.md, 3 registry) nếu đã thấy nội dung trong context thì KHÔNG nạp lại — xem ../pk-shared/references/snapshot-contract.md, mục "Dedup 6 file khối @" (gồm cả luật "ghi thì mất hiệu lực"). ls -1 .cockpit/ vẫn luôn chạy.
Snapshot xong → đặt marker SNAPSHOT_LOADED (theo Snapshot Contract, mục "Nguyên tắc idempotent"). Skill được gọi inline thấy marker → KHÔNG đọc lại snapshot.
Intent routing
| State | User intent | Chạy skill |
|---|
| Chưa có .cockpit/ | Bất kỳ | pk-init new |
| Có .cockpit/, không objective | Mặc định | pk-capture / pk-consult / pk-distill / pk-lint / pk-reflect (light) / pk-analyze (knowledge-only). Danh sách canonical: ../pk-shared/references/snapshot-contract.md (Graceful Degradation) |
| Có objective, chưa plan | Mặc định | pk-plan new |
| Có objective + plan | Mặc định / "hôm nay" | pk-analyze (dashboard) |
| "sửa mục tiêu / KR / KI / constraints" | pk-init update-objective |
| "sửa tools" | pk-init update-tools |
| "thêm action / sửa plan" | pk-plan update |
| "track / cập nhật" | pk-analyze → pk-track light |
| "review sâu / phân tích sâu" | pk-analyze deep → pk-track deep |
| "capture / ghi nhanh / note" | pk-capture |
| "capture auto" / (ambient trigger: mạch việc hoàn tất) | pk-capture mode auto |
| "inbox" | pk-track inbox-only (execution) HOẶC pk-distill (knowledge); cả hai domain → xem mục Inbox routing đặc biệt bên dưới |
| "rút bài học / retro" | pk-reflect light |
| "AAR / phỏng vấn sâu" | pk-reflect deep |
| "hỏi kho / tra cứu" | pk-consult query |
| "chạy skill / workflow" | pk-consult run |
| "soạn onboarding / dạy lại X / lộ trình học" |
Intent mơ hồ: snapshot → thu hẹp → tối đa 1 câu clarify. Không đoán mò, không chạy sai skill.
Collision: state gợi ý khác user intent → ưu tiên user intent + xác nhận.
Inbox routing đặc biệt
User nói "inbox" / "xử lý inbox":
- Kiểm tra inbox count by domain
- Chỉ có execution →
pk-track inbox-only
- Chỉ có knowledge →
pk-distill
- Cả hai → hỏi user: "Inbox có N execution + M knowledge. Xử lý bên nào trước?"
Phase 2: Thực thi inline
Đọc SKILL.md skill đích, theo flow. Khi flow chuyển sang skill khác, đọc tiếp SKILL.md kia (cùng agent, inline).
Dashboard (mặc định khi có plan)
pk-analyze (focus=full). Render dashboard hợp nhất + nhắc review nếu cần.
Track light
pk-analyze (focus: track) → analysispk-track light, dùng analysis
Deep review (chuỗi tuần tự inline)
pk-analyze deep → root cause, rồi pk-track deep theo flow của pk-track (gồm delegate cấu trúc, phát hiện tri thức, và log).
Phase 3: Tổng hợp
- Gom kết quả.
- Render tóm tắt: thay đổi gì, next step gì.
- Inbox vượt ngưỡng nhắc (canonical:
../pk-shared/references/schemas.md, mục "Ngưỡng nhắc xử lý": >= 10 item pending hoặc có item pending > 14 ngày) → đề xuất distill/track trong cùng câu tổng kết. User gật mới chạy.
- Gợi ý rút bài học nếu flow có thực chất:
"Muốn rút bài học phiên này? (chạy pk-reflect)"
KHÔNG tự chạy. User đồng ý mới chạy.
Error handling
| Lỗi | Xử lý |
|---|
.cockpit/ không tồn tại | Route pk-init new |
| objective.md rỗng (knowledge-only) | Chỉ route knowledge skills + pk-analyze knowledge-only (danh sách canonical: snapshot-contract.md, Graceful Degradation) |
| File corrupt | Báo cụ thể file, đề xuất sửa |
| Skill flow lỗi giữa chừng | Báo bước lỗi, giữ thay đổi đã ghi |
Tham khảo
- Sơ đồ luồng:
references/flows.md
- Snapshot contract:
../pk-shared/references/snapshot-contract.md
- Cross-call rules:
../pk-shared/references/cross-call-rules.md
