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

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

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

1. pk-analyze (focus: track) → analysis
2. pk-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

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