# Pk Harness

> 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ể.

- Skill: `hoangvantuan/pk-harness` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hoangvantuan/pk-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangvantuan/pk-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: hoangvantuan (https://skillmd.com/u/hoangvantuan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hoangvantuan/pk-harness

---


# 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-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

| 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`