hoangvantuan 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" | pk-consult teach |
|
| "distill / đúc kết" | pk-distill |
|
| "lint / kiểm tra / dọn dẹp" | pk-lint check |
|
| "sửa kho / rebuild / restore" | pk-lint fix |
|
| "schema review / tiến hoá" | pk-lint evolve |
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-trackinbox-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-tracklight, 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