POG Task Manager
這是一個專為管理 POG Task (pog-task/list/**/*.yaml) 設計的 VS Code 擴充套件。它旨在協助開發者與 LLM Agent 高效協作，提供直觀的介面來檢視、管理和追蹤專案任務。
🌐 English Version: README.en.md
🛒 Marketplace: POG Task Manager
🧩 Prompt Orchestration Governance (POG)
提示編排治理 (Prompt Orchestration Governance, POG)
一個將提示詞 (Prompts) 視為軟體開發生命週期 (SDLC) 中一等軟體資產的綜合管理框架。POG 提供了系統化的流程來發現、標準化、驗證、版本控制和部署提示詞，同時維持治理與品質控制。
📖 白皮書: Prompt Orchestration Governance Whitepaper
核心概念：什麼是 POG Task？
從人類意圖到 Agent 可執行的工作。
POG Task 是一個 AI 原生的任務治理模型，將任務視為結構化、可解釋且可審計的意圖單元 (Units of Intention)。
不僅僅是將任務視為待辦事項清單，POG Task 強調：
- 結構化流 (Structured Stream)：使用 YAML 格式儲存，對 AI 友善且易於解析。
- 推理軌跡 (Reasoning Trace)：透過
record.md 記錄 Agent 的思考過程與執行細節。
- 人機協作：明確區分人類的「意圖定義」與 Agent 的「執行與推理」。
此擴充套件即是為了在 VS Code 中與 POG Task 系統無縫協作而設計，讓您能輕鬆管理這些結構化意圖。
架構
系統依賴於一個基於檔案、Git 友好的結構，支援透明度和可攜性。
儲存庫結構
pog-task/
├── pog-task-agent-instructions.md # Agent 操作指南
├── pog-task-design.md # 系統設計文檔
├── list/ # 活躍任務資料庫
│ └── {project}/
│ └── {module}/
│ ├── {task}.yaml # 結構化任務 (AI 可讀)
│ └── record/ # 執行產物
│ └── {uuid}/ # 每個任務的唯一資料夾
│ └── record.md # 執行和推理軌跡
為什麼選擇基於檔案？
- Git 整合：利用最經久考驗的版本化記憶體系統。
- 共通語言：Markdown 和 YAML 是人類和 LLM 原生的共通語言。
- 可攜性：零鎖定。適用於 VS Code、CI/CD、Agent 框架或任何文字編輯器。
組件
1. 任務流 (*.yaml)
任務儲存在 YAML 檔案中，分層目錄組織。關於目錄結構與命名約定請參閱 pog-task/README.md 或 pog-task/pog-task-design.md。
2. 推理記錄 (record.md)
對於複雜任務，record.md 檔案充當執行過程的「大腦」。它捕捉 Agent 的思考過程、原始使用者提示詞 (Prompt) 以及計畫的演變。這對於除錯 Agent 行為和確保意圖對齊至關重要。
3. VS Code 外掛 (可選介面)
該外掛是一個介面，而非核心。它用於視覺化 task.yaml 流，協助人類編寫對 AI 友好的任務，並檢查執行記錄。
工作流
1. 定義意圖
人類（或 Agent）在 *.yaml 檔案中建立一個任務。它定義了目標、優先級和初始上下文。
2. 指派與認領
Agent（或人類）識別待處理的任務並透過更新任務狀態和將其指派給自己來「認領」它。這避免了多 Agent 環境中的衝突。
3. 執行與推理
Agent 建立 record.md 來記錄其計畫。它執行工作（編碼、研究等），並隨之更新記錄。
4. 完成與驗證
一旦完成，Agent 在 YAML 檔案中將任務標記為完成並完善記錄。人類可以審查 record.md，不僅驗證輸出，也驗證過程。
功能特色 (Features)
1. 任務列表管理 (Task List Management)
提供直觀的側邊欄樹狀視圖 (Tree View)，自動依照 Project 與 Module 分組顯示任務。支援豐富的狀態圖示與層級展開，讓您一眼掌握專案進度。
- 即時監聽：自動監聽
pog-task/list/**/*.yaml 檔案變更，新增或修改任務會立即反映在列表中。
- 狀態篩選：可過濾顯示特定狀態（如 In Progress, Pending）的任務。
2. Agent 協作整合 (Prompt Templates)
內建 Agent Prompt Template 管理功能，針對不同場景（如：建立新任務、執行現有任務）提供標準化的 Prompt。
- 一鍵複製：快速產生並複製 Agent 指令，直接貼上給 LLM 使用。
- 上下文注入：自動將任務上下文 (Context) 整合進 Prompt 中。
3. 任務詳情與推理記錄 (Task Detail & Record)
- Webview 編輯器：透過表單介面檢視與編輯任務詳細資訊。
- Record 存取：快速開啟任務對應的
record.md，檢視執行過程與推理紀錄。
4. Jira 整合 (Jira Integration — Server / Data Center)
提供最小可用的 Jira 串接：把帶有外部 issue key 的 task 集中到獨立的 Issue Tasks view，並用三顆 view title 按鈕完成 Pull / Push 流程。中間階段（agent 寫 code、人工 review）對 Jira 完全靜默，避免雙向同步帶來的衝突處理成本。
issue 欄位：task.schema.json 新增 optional issue: string，用來存外部 issue key（例如 PROJ-123）。- Issue Tasks view：與既有 Task List 並存，只顯示
issue 欄位非空的 task，label 顯示 [KEY] Title。
- 三顆 view title 按鈕：
- $(cloud-download) Pull Todos — 跑 JQL，把每個 issue 寫成 YAML task 到
pog-task/list/<pullProject>/<pullModule>/<KEY> - <slug>.yaml，已存在的 issue 跳過不覆蓋。
- $(cloud-upload) Push Selected — 列出
issue 非空、status ∈ {in_review, completed} 的 task，QuickPick 勾選後做 transition + 留 comment（含 task notes、最後一筆 history、git log --grep=<KEY> 的 commit 列表與 URL），並在 task history 補一筆 progress。
- $(gear) Set Connection — InputBox 設定 baseUrl 與 PAT；PAT 進 VS Code SecretStorage（
pog-task-manager.jira.token），不入 settings.json。
- Settings（
pog.taskManager.jira.*）：baseUrl / defaultJql / pullProject (default jira) / pullModule (default inbox) / inReviewTransitionName (default In Review) / doneTransitionName (default Done)。
- 已知限制：僅 Jira Server / Data Center（REST v2 + Bearer PAT）；無雙向同步；commit URL 內建支援 GitHub / GitLab / 標準 SSH remote，Bitbucket Server 需自行擴充。
Agent Task 指南 (Task Usage)
POG Task Manager 提供了兩種主要的 Task 生成功能，協助您快速啟動與 Agent 的協作：
1. 建立新任務 (Create Task)
適用於從零開始建立一個新任務。
- 使用時機：當您有一個新的構想或需求，需要 Agent 協助將其轉化為正式的 POG Task。
- 產生內容：包含閱讀 Agent Guide、Category 定義，以及建立任務與
record.md 的標準步驟。
- 操作方式：在 Task List 列表中選擇 "Create Task"，或在任務列表空白處右鍵選擇 "Copy Task Create"。
"Copy Task Create" 範例：
# Step 1: Read Context
請閱讀以下文件及相關資源：
- pog-task/pog-task-agent-instructions.md
- pog-task/task.schema.json
# Step 2: Create or Join Task
請在 pog-task/list 下操作：
- project: {${project}}
- module: {${module}}
- 如果任務不存在 → 新建任務 (立即建立一個新的 yaml 檔案)
- 如果任務已存在 → 加入該任務 (直接修改 yaml 檔案)
- parent task id: {${task.id}}
# Step 3: Generate Task Record
請生成 record.md 檔案（位於 pog-task/list/${project}/${module}/record/{task-uuid}/record.md），內容包含：
- Original Prompt
- Task 目標
- Execution Plan / Checklist
- 相關參考文件
- implementation plan 的內容也記錄下來
- 每做到一個段落 就透過 git commit 的方式提交一次，commit message 概述該段落的內容
# Step 4: 理解任務 本次任務：
xxxxxxxx
# Step 5: Update Progress
- 更新 status: in_progress → in_review
- 更新 checklist / notes / actual_hours
- 在 history 中加入執行紀錄
- 在 record.md 中記錄關鍵決策與產出物 把 walkthrough 的內容也記錄下來
- 重要 在未建立 新的 task 時，後續修改的提示與實現，從 Step 2 開始繼續實現
2. 執行任務 (Execute Task)
適用於執行已經存在的任務。
- 使用時機：當任務已經建立（處於 Pending 或 In Progress 狀態），您希望指派 Agent 開始實際工作。
- 產生內容：
- Context：自動包含任務所在的 YAML 檔案與對應的
record.md 路徑。
- 指令：明確指示 Agent 執行特定 ID 的任務，並更新狀態與進度。
- 操作方式：在任務列表中的特定任務上右鍵，選擇 "Copy Task Execute"。
"Copy Task Execute" 範例：
# Step 1: Read Context
請閱讀以下文件及相關資源：
- pog-task/pog-task-agent-instructions.md
- pog-task/list/${project}/${module}/${filename}
- pog-task/list/${project}/${module}/record/${task.id}/record.md
# Step 2: Update Progress
- 更新 status: in_progress
- 更新 checklist / notes / actual_hours
- 在 history 中加入執行紀錄
- 在 record.md 中記錄關鍵決策與產出物 把 implementation plan 的內容也記錄下來
- 每做到一個段落 就透過 git commit 的方式提交一次，commit message 概述該段落的內容
# Step 3: Execute Task
請執行 pog-task/list/${project}/${module}/${filename} 中指定 Task：
- task id: ${task.id}
# Step 4: Update Progress
- 更新 status: in_progress → in_review
- 更新 checklist / notes / actual_hours
- 在 history 中加入執行紀錄
- 在 record.md 中記錄關鍵決策與產出物 把 walkthrough 的內容也記錄下來
- 重要 在未建立 新的 task 時，後續修改的提示與實現，從 Step 2 開始繼續實現
使用方式 (Usage)
專案結構準備:
確保您的專案根目錄下有 pog-task/list/ 資料夾，並包含符合 POG Task 規範的 .yaml 檔案 (例如 common/improve/task.yaml)。
啟動與瀏覽:
安裝套件後，點擊 VS Code Activity Bar 中的 POG Task Manager 圖示，即可開啟任務列表。
常用操作:
- Refresh Tasks: 在 Command Palette 輸入
POG Task Manager: Refresh Tasks 可手動強制重新讀取所有任務。
- Context Menu: 在任務項目上點擊右鍵，可執行相關操作（如複製 Prompt、開啟 Record、切換狀態等）。
- Init POG Task: 在 Command Palette 輸入
POG Task Manager: Init POG Task 可快速初始化專案結構。
