hermes-task-framework 1.1.0__tar.gz → 1.2.1__tar.gz

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hermes-task-framework
-Version: 1.1.0
+Version: 1.2.1
 Summary: Structured task management skills for Hermes Agent — task creation, decomposition, stage gates
 Project-URL: Source, https://github.com/nuffin/hermes-task-framework-pip
 Requires-Python: >=3.11

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-external-repos-pattern/SKILL.md

@@ -130,23 +130,19 @@ This pattern extends the `task-framework` skill's directory structure. The `task
 
 For `task_reset --hard` semantics: `repos/` is never deleted by cleanup operations (same as `input/`). Custom `clean.sh` scripts can further refine which directories to protect.
 
-## Kanban Escalation: Multi-Repo Tasks → Kanban
+## Optional: Escalate to External Task Manager
 
-When a task involves **multiple independent external repos** (e.g. cloning 5+ repos from an awesome-list for study), the work typically decomposes into parallel workstreams. The user's convention is **one kanban card per task-framework task** (not one card per sub-operation):
-
-User signal: *"一个 clone 任务创建一个 card"* / *"这是多个任务了，放到 default 看板里"*
+When a task involves **multiple independent external repos** (e.g. cloning 5+ repos from an awesome-list for study), the work typically decomposes into parallel workstreams. The recommended convention is **one tracking card per task-framework task** (not one card per sub-operation):
 
 **Right approach:**
 1. Create a single task-framework task with its own `repos/` directory
-2. Create one kanban card for that task, `--workspace dir:<task-path>`
-3. Update the bridge db.yaml to map task hash ↔ card id
+2. If using an external task manager (kanban board, issue tracker, etc.), create one card/issue for that task and link it via the task hash
+3. Map the external card ID back to `.hermes-task.json` if your workflow requires bidirectional linking
 
 **Wrong approach:**
-- Creating one kanban card per individual sub-repo
+- Creating one tracking card per individual sub-repo
 - Mixing unrelated work into one card
 
-See also: `kanban-orchestrator` skill for decomposition playbook, `kanban-bridge` for task ↔ card mapping.
-
 ## Custom Clean Methods (Implemented)
 
 Each task can protect sensitive directories from cleanup via a `scripts/clean.sh` script:
@@ -178,9 +174,9 @@ echo "[clean] output/ cleaned"
 - 没有 clean.sh 时回退到默认行为，不破坏现有任务
 
 **本 task 的 clean.sh 示例路径：**
-`tasks/20260615-213922.awesome-obsidian-vaults-cc6b3b/scripts/clean.sh`
+`tasks/<ts>.<task-name>-<hash6>/scripts/clean.sh`
 该脚本保护 `repos/`、`input/`，只清理 `output/`。
 
 **Framework 集成状态：**
-- `task-framework` SKILL.md 已更新，记录了 clean.sh 查找顺序和模板（`~/hermes/skills/software-development/task-framework/SKILL.md` 的 Task Directory Structure 章节）
+- `task-framework` SKILL.md 已更新，记录了 clean.sh 查找顺序和模板
 - `analysis` task-type 生命周期文档也加了自定义清理的提示

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/SKILL.md

@@ -1,5 +1,5 @@
 ---
-author: Hauzer S. Lee
+author: Hermes Agent
 category: software-development
 description: 'Three-layer task system: (1) methodology — decompose complex work into
   composable operations (info-search, code-write, paper-reproduce…) and composite
@@ -33,7 +33,7 @@ tags:
 - operations
 - logging
 - pdf
-version: 1.1.0
+version: 1.2.1
 ---
 
 ---
@@ -121,28 +121,28 @@ When you receive a task request:
 
 ## Environment Variables
 
-This skill uses environment variables for portability across machines. After Personal Suite installation, these are set in `~/.hermes/personal/env.sh`:
+This skill uses environment variables for portability across machines. After installation, these are set in `~/.hermes/env.sh`:
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| `HERMES_TASKS_ROOT` | `~/studio/hermes/tasks` | Task container root (`tasks/2*/`, `tasks/inbox/`) |
-| `HERMES_PROJECTS_ROOT` | `~/studio/hermes/projects` | Project repos root |
+| `HERMES_TASKS_ROOT` | `$HERMES_TASKS_ROOT` | Task container root (`tasks/2*/`, `tasks/inbox/`) |
+| `HERMES_PROJECTS_ROOT` | `$HERMES_PROJECTS_ROOT` | Project repos root |
 
 **Usage rule:** All inline shell commands in this SKILL.md use `$HERMES_TASKS_ROOT` instead of bare `tasks/` paths. When running commands from a Hermes session, source the env file first:
 
 ```bash
-source ~/.hermes/personal/env.sh
+source ~/.hermes/env.sh
 ```
 
-If the variable is unset, fall back to `~/studio/hermes/tasks` (the historical default).
+Root resolution order is: `HERMES_TASKS_ROOT`, `HERMES_TASKS_DIR` compatibility alias, active-profile `tasks.data_dir`, global `tasks.data_dir`, then `~/studio/hermes/tasks`. The historical `~/.hermes/tasks` directory is compatibility-only: never create, mirror, populate, or symlink task directories there. When a custom `tasks.data_dir` is configured, it is the only task root used.
 
 ## Task Directory Structure
 
-The canonical tasks root is defined by `$HERMES_TASKS_ROOT` (default: `~/studio/hermes/tasks/`). All relative paths (e.g. `tasks/YYYYMMDD-*`) in documentation are relative to this root. When the user says "tasks" without qualification, this directory is the default reference — not the abstract concept of "任务". "创建一个任务" means creating a `YYYYMMDD-HHMMSS.<name>-<hash6>/` structure here using this skill.
+The canonical tasks root is defined by `$HERMES_TASKS_ROOT` or configuration (default: `~/studio/hermes/tasks/`). All relative paths (e.g. `tasks/YYYYMMDD-*`) in documentation are relative to this root. When the user says "tasks" without qualification, this directory is the default reference — not the abstract concept of "任务". "创建一个任务" means creating a `YYYYMMDD-HHMMSS.<name>-<hash6>/` structure here using this skill. Task directories must be real directories; do not create task-root or task-directory symlinks.
 
 🔴 **Semantic disambiguation (important):** When the user says "任务" or "task", first determine whether they mean (a) a task-framework managed task (in `tasks/YY.../` directories) or (b) a generic concept. Clues: specific name/timestamp, operating on a task directory → (a); abstract discussion → (b). For (a), always use task-framework tools (task_create, task_set_status, etc.) — never raw `mv`/`cp`/`rm` on task directories. For (b), handle as normal conversation.
 
-```\ntasks/\n├── README.md                  ← summary index (directory façade)\n├── TASKS.md                   ← aggregated checklist view (done/total per task)\n├── YYYYMMDD-HHMMSS.<task-name>-<hash6>/\n│   ├── README.md              ← goal, scope, key findings\n│   ├── TASK.md                ← checklist with status + checkboxes\n│   ├── CHANGELOG.md          ← per-task changelog: auto-appended log of decisions, state, findings\n│   ├── MEMORY.md               ← compact §-delimited durable facts (ports, rules, constraints). REQUIRED to maintain — see compact-directory-memory skill for format and trigger rules.
+```\ntasks/\n├── README.md                  ← summary index (directory façade)\n├── TASKS.md                   ← aggregated checklist view (done/total per task)\n├── YYYYMMDD-HHMMSS.<task-name>-<hash6>/\n│   ├── README.md              ← goal, scope, key findings\n│   ├── TASK.md                ← checklist with status + checkboxes\n│   ├── CHANGELOG.md          ← per-task changelog: auto-appended log of decisions, state, findings\n│   ├── MEMORY.md               ← compact §-delimited durable facts (ports, rules, constraints). REQUIRED to maintain — see your memory management skill (if available) for format and trigger rules.
 │   ├── input/                 ← **source files** — NEVER deleted by cleanup operations\n│   │                           (PDF, DOCX, images, REQUIREMENTS.md copied from inbox)\n│   ├── output/                ← **generated files** — CAN be safely deleted entirely\n│   │   ├── docs/              ← analysis documents, reports (for analysis tasks)\n│   │   ├── logs/              ← execution logs\n│   │   ├── tts-<hash6>/       ← pipeline phase dirs (for pipeline tasks)\n│   │   ├── RECORDING.md       ← pipeline generated specs\n│   │   ├── COMPOSITING.md\n│   │   └── ...\n│   ├── inbox/                 ← proposal inbox (one file/dir per idea)\n│   └── declined/              ← rejected proposals (with DECLINED.md)\n```
 
 **`input/` 目录** — 存放从 inbox 复制来的源文件（PDF、DOCX、图片、REQUIREMENTS.md 等）。**核心规则：所有删除操作不得触及 `input/`。**
@@ -283,7 +283,7 @@ tasks/<ts>.<name>-<hash6>/
 ├── recording-bd71ef/        ← browser-video-recording 的工作目录
 │   ├── video.mp4
 │   └── timeline.txt
-├── compositing-c9f3a2/      ← video-audio-compositing 的工作目录
+├── compositing-c9f3a2/      ← <domain-skill> 的工作目录
 │   └── output.mp4
 ├── docs/                   ← 共享文档（timestamps.json、多 phase 共用文件等）
 └── logs/
@@ -328,7 +328,7 @@ When a task has a `run.py` at its root, use it as the single entry point. The au
 |------|------|------|
 | (无标注) | 按顺序串行，在前一阶段之后执行 | `Phase 2 — 录制视频` |
 | `和 Phase X 同步进行` | 和 Phase X 并行执行 | `Phase 2 (browser-video-recording) — 和 Phase 1 同步进行, 录制视频` |
-| `等待 Phase X 完成` | Phase X 完成后才执行，不关心其他阶段 | `Phase 3 (video-audio-compositing) — 等待 Phase 1 完成, 等待 Phase 2 完成, 合成` |
+| `等待 Phase X 完成` | Phase X 完成后才执行，不关心其他阶段 | `Phase 3 (<domain-skill>) — 等待 Phase 1 完成, 等待 Phase 2 完成, 合成` |
 
 **Implementation:** 并行阶段通过 `delegate_task()` 启动子代理执行。等待阶段通过 `process(action='wait')` 或检查输出产物来判断完成。
 
@@ -343,7 +343,7 @@ When a task has a `run.py` at its root, use it as the single entry point. The au
 
 - `text-to-speech` — 生成语音音频
 - `browser-video-recording` — 录制浏览器操作视频
-- `video-audio-compositing` — 合成音视频
+- `<domain-skill>` — 合成音视频
 
 ## 环境要求
 
@@ -357,7 +357,7 @@ When a task has a `run.py` at its root, use it as the single entry point. The au
 
 - [ ] Phase 1 (text-to-speech) — 根据解说脚本生成 N 段音频
 - [ ] Phase 2 (browser-video-recording) — 和 Phase 1 同步进行, 录制浏览器操作视频
-- [ ] Phase 3 (video-audio-compositing) — 等待 Phase 1 完成, 等待 Phase 2 完成, 将音频合成到视频的正确时间点
+- [ ] Phase 3 (<domain-skill>) — 等待 Phase 1 完成, 等待 Phase 2 完成, 将音频合成到视频的正确时间点
 - [ ] BREAK: 检查最终视频效果
 ```
 
@@ -417,7 +417,7 @@ Unimplemented phases (5-7 in the template) return True (skip, don't fail).
 
 用一个文件描述完整流水线，`generate_all()` 自动拆解生成各子 spec。
 
-参考 `standards/video-production-spec.md`，工具入口 `video-audio-compositing/scripts/utils/production_spec.py`：
+参考 `standards/video-production-spec.md`，工具入口 `<domain-skill>/scripts/utils/production_spec.py`：
 
 ```python
 from utils.production_spec import generate_all
@@ -570,7 +570,7 @@ The agent reads TASK.md from top to bottom:
 **BREAK 行** → 执行到此时暂停，输出内容给用户。用户确认后将 `[ ] BREAK:` 改成 `[x] DONE:`，下次自动跳过。
 
 
-**🔴 执行纪律：非 BREAK 不停** — 完成一个 `[ ]` 项后，立即找到下一个未完成的 `[ ]` 项。如果中间没有 `[ ] BREAK:`，直接执行，绝不询问"要不要继续"。用户对停顿询问非常反感。
+**🔴 执行纪律：非 BREAK 不停** — 完成一个 `[ ]` 项后，立即找到下一个未完成的 `[ ]` 项。如果中间没有 `[ ] BREAK:`，直接执行，绝不询问"要不要继续"。Frequent confirmation prompts disrupt workflow.
 
 ---
 
@@ -663,7 +663,7 @@ The script handles: directory creation (`<ts>.<name>-<hash6>/`), subdirs (`input
    执行: `uv run python <script>`
    ```
 
-5. **Kanban 卡片**（如有 kanban 集成）：在 `default` 看板创建卡片，卡片标题 `<task-name> [task:<目录名>]`，assignee `default`，卡片 ID 写入 `.hermes-task.json`。
+5. **(Optional) External task manager card** — if using an external task manager (kanban board, issue tracker, etc.), create a card/issue with title `<task-name> [task:<目录名>]` and store its ID in `.hermes-task.json`.
 
 Skill 的 `scripts/create_task.py` 接口约定：
 
@@ -683,7 +683,7 @@ task_hash = sys.argv[3]
 # ... skill 自己的逻辑
 ```
 
-**示例：** 创建带 browser-screen-record-task 模板的任务：
+**示例：** 创建带 `<custom-skill>` 模板的任务：
 
 ```bash
 # Step 1: script creates base structure
@@ -825,8 +825,8 @@ python3 scripts/update-index.py  # from the skill directory
 Output:
 ```
 Updated:
-  /home/hauzer/studio/hermes/tasks/README.md  (1464B)
-  /home/hauzer/studio/hermes/tasks/TASKS.md   (6912B)
+  $HERMES_TASKS_ROOT/README.md  (1464B)
+  $HERMES_TASKS_ROOT/TASKS.md   (6912B)
   Found 9 active tasks
 ```
 
@@ -921,17 +921,17 @@ python3 scripts/manage_task.py reset <hash_or_dir> [--no-hard]
 
 # ── 底层操作 ──
 # 初始化一个任务（创建目录 + TASK.md + CHANGELOG.md + .hermes-task.json）
-python3 scripts/manage_task.py init 5d5a1a
-python3 scripts/manage_task.py init tasks/20260605-233355.health-sales-demo-5d5a1a/
+python3 scripts/manage_task.py init <hash6>
+python3 scripts/manage_task.py init tasks/<ts>.<task-name>-<hash6>/
 
 # 导出任务（tar.gz）
-python3 scripts/manage_task.py export 5d5a1a
+python3 scripts/manage_task.py export <hash6>
 
 # 导入任务
-python3 scripts/manage_task.py import tasks/20260605-233355.health-sales-demo-5d5a1a.tar.gz
+python3 scripts/manage_task.py import tasks/<ts>.<task-name>-<hash6>.tar.gz
 
 # 按 hash 重建（查找最近 tar.gz）
-python3 scripts/manage_task.py rebuild 5d5a1a
+python3 scripts/manage_task.py rebuild <hash6>
 
 # 一次性迁移：将旧个人存储目录下的文件迁移到统一目录
 python3 scripts/manage_task.py migrate
@@ -957,15 +957,15 @@ python3 scripts/manage_task.py list
 
 ```bash
 # 源机器：导出
-cd ~/studio/hermes
-python3 scripts/manage_task.py  # from the skill directory export 5d5a1a
-git add tasks/*5d5a1a*.tar.gz
-git commit -m "export 5d5a1a"
+cd "$HERMES_TASKS_ROOT"
+python3 scripts/manage_task.py  # from the skill directory export <hash6>
+git add tasks/*<hash6>*.tar.gz
+git commit -m "export <hash6>"
 git push
 
 # 目标机器：拉取 + 导入
 git pull
-python3 scripts/manage_task.py  # from the skill directory rebuild 5d5a1a
+python3 scripts/manage_task.py  # from the skill directory rebuild <hash6>
 ```
 
 ### 旧任务（无 hash）的管理
@@ -993,7 +993,7 @@ After modifying any TASK.md, README.md, or log file inside a task directory, run
 
 ## Task Tracking (automatic phase completion log)
 
-When TASK.md includes a `## Tracking` section, orchestrators (stratis/corvan/valros)
+When TASK.md includes a `## Tracking` section, orchestrators
 inject tracking instructions into each dispatched card. The executor loads
 `task-tracker` skill after each phase to:
 - Mark the phase checkbox `[x]` in TASK.md
@@ -1170,7 +1170,7 @@ check_cycles(meta)  # raises ValueError on cycle
 |------|------|------|---------|
 | `TASK.md` | checklist、状态、要求 | 创建时填充 | 手动维护 |
 | `CHANGELOG.md` | 操作记录、决策、发现、阻塞原因 | 自动追加 | 按时间追加，永不删除 |
-| `MEMORY.md` | 跨阶段的硬事实（端口、规则、公约） | 手动维护 | §-delimited, compact format; MUST use `compact-directory-memory` skill for format and trigger rules. Review after every phase completion or session that changes task state. |
+| `MEMORY.md` | 跨阶段的硬事实（端口、规则、公约） | 手动维护 | §-delimited, compact format; MUST use your memory management skill (if available) for format and trigger rules. Review after every phase completion or session that changes task state. |
 | `logs/` | 命令输出 | 自动生成 | 可清理 |
 | `.hermes-task.json` | hash、outputs、依赖 | 自动维护 | 随任务更新 |
 
@@ -1191,7 +1191,7 @@ check_cycles(meta)  # raises ValueError on cycle
 ```
 ## 2026-06-06 13:00
 
-**操作:** 重命名 task 目录 demo-video-production-v2 → health-sales-demo-5d5a1a
+**操作:** 重命名 task 目录 <old-name> → <task-name>-<hash6>
 **原因:** 遵循新命名规则，目录名需包含 hash
 **改动:**
 - 目录改名
@@ -1285,7 +1285,7 @@ python3 scripts/manage_task.py create <task-name>  # from the skill directory
 post-flight 的 Integrity Check 会检查"本轮的复杂程度是否达到了触发条件"，
 Pending Action Scan 会处理"达到了但没有 task 目录 → 立即补建"。
 CHANGELOG.md 的创建和维护是 post-flight 后置链的固定组成部分。
-同样，**当 `compact-directory-memory` skill 可用时，post-flight 应触发 MEMORY.md
+同样，**当 your memory management skill 可用时，post-flight 应触发 MEMORY.md
 的审查**：检查现有事实是否过时、本 session 是否产生了需要记录的新事实。
 
 - **`.hermes-task.json` 必须在任务根目录** — 和 TASK.md 同级
@@ -1300,16 +1300,16 @@ CHANGELOG.md 的创建和维护是 post-flight 后置链的固定组成部分。
 | Operation catalog out of date | Add new operations as they're discovered. |
 | **🔴 Never fill task placeholders from conversation history** | When user says \"create a task named X\", create an empty template with all `{placeholder}` intact. Do NOT infer URL, steps, or operations from earlier chat context unless user explicitly says \"根据上面的对话\" or similar. Corrected multiple times — the user will delete and re-create if you guess. |\n| **🔴 File moves must be ln/cp + verify + rm** | Never `mv`. Use `ln <src> <dst>`, verify with `ls -la`, then `rm <src>`. |
 | **🔴 Missing `## 环境要求` in TASK.md** | Executor pre-flight forces this check. Always include it. |
-| **🔴 Confirm CWD before creating tasks** | Project root must have `tasks/` dir. If not, confirm user expects `~/studio/hermes/tasks/` as base. |
-| **🔴 "tasks" naming ambiguity + no manual management** | When user says "tasks" or "task", first disambiguate: (a) task-framework managed → use task_create/task_set_status/etc., never raw `mv`/`cp`/`rm` on task dirs; (b) generic concept → normal conversation. See `PROJECT_STRUCTURE.md` for the full convention. Corrected: manual `mv` on a task dir instead of using framework. |
+| **🔴 Confirm CWD before creating tasks** | Project root must have `tasks/` dir. If not, confirm user expects `$HERMES_TASKS_ROOT/` as base. |
+| **🔴 "tasks" naming ambiguity + no manual management** | When user says "tasks" or "task", first disambiguate: (a) task-framework managed → use task_create/task_set_status/etc., never raw `mv`/`cp`/`rm` on task dirs; (b) generic concept → normal conversation. Corrected: manual `mv` on a task dir instead of using framework. |
 | 🔴 Log accumulation | Clean old logs with `rm tasks/*.<name>/logs/*.YYYYMMDD-*.log`. |
 | 🔴 Root index files stale | After creating/updating/deleting any task, run `python3 scripts/update-index.py  # from the skill directory` to regenerate both `tasks/README.md` and `tasks/TASKS.md`. Users rely on these indexes for overview. |
 | **🔴 Data Flow table not consulted** | In cross-skill composite tasks, a phase that produces a file (e.g. TTS → `audio_manifest.json`) must write it in the format expected by the consumer phase. The `## Data Flow` table's `格式说明` column tells you where to find that format spec. Don't guess the schema — load the referenced skill/reference file and read it. Corrected in discussion about how compositing finds audio manifest format. |
 | **`tasks/2*/` glob matches active tasks only** | Inbox/declined don't start with `2` — natural filtering. |
 | **`## Status` empty line matters** | `grep -A2` not `-A1` to skip blank line after header. |
 | LLM reasoning where a script would do | If you've repeated the same manual sequence twice, write a script. The LLM should handle judgment, not memorized mechanical steps. |
-| **🔴 Don't stop & ask between checklist items unless there's a BREAK** | Execution Logic says: `[ ] BREAK:` → pause; `[ ]` → execute immediately. After completing one item, scan for the next unchecked `[ ]`. If there's no BREAK between them, execute it right away — do NOT ask 'do you want to continue?'. User corrected: '继续呀！！！你为什么要听下呢？这里有说要break吗？' Parallel dependencies (e.g. 'and Phase 1 同步进行') don't imply you should wait for instructions — check if the dependency is already resolved and act. |
+| **🔴 Don't stop & ask between checklist items unless there's a BREAK** | Execution Logic says: `[ ] BREAK:` → pause; `[ ]` → execute immediately. After completing one item, scan for the next unchecked `[ ]`. If there's no BREAK between them, execute it right away — do NOT ask 'do you want to continue?'. Parallel dependencies (e.g. 'and Phase 1 同步进行') don't imply you should wait for instructions — check if the dependency is already resolved and act. |
 | **🔴 Never modify REQUIREMENTS.md** | REQUIREMENTS.md is user-owned. If changes are needed, tell the user what to change and let them do it themselves. Do NOT edit it directly — the user won't know what changed. Corrected twice in one session. |
 | **🔴 Input source files go in input/, output/ is for generated files** | `task_reset --hard` does `rm -rf output/`. Any source file (PDF, DOCX, images, REQUIREMENTS.md) placed in `output/` will be lost. Always put source material in `input/`. |
 | **🔴 Inbox source files must be copied to task** | When creating a task from an inbox file (PDF/DOCX/etc.), copy the file into the task's `input/` directory. A Data Flow reference to `tasks/inbox/...` is fragile — the inbox item could be moved or deleted independently of the task. The task must be self-contained. |
-| **🔴 Design discussion ≠ execution signal** | When the user makes observations, suggestions, or asks how a system/skill/process should work (e.g. "在从 REQUIREMENTS.md 生成 RECORDING.md 的时候，xxx 应该 yyy"), they are in **design/discussion mode**. Do NOT start executing pipeline steps or making code changes based on a design opinion. Wait for explicit go-ahead ("可以了" / "继续" / "跑吧"). Corrected with extreme frustration — user hadn't finished their thought. |
+| **🔴 Design discussion ≠ execution signal** | When the user makes observations, suggestions, or asks how a system/skill/process should work (e.g. "在从 REQUIREMENTS.md 生成 RECORDING.md 的时候，xxx 应该 yyy"), they are in **design/discussion mode**. Do NOT start executing pipeline steps or making code changes based on a design opinion. Wait for explicit go-ahead. This pattern has caused confusion in practice. |

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/docs/product-requirements.md

@@ -6,7 +6,7 @@
 
 ## 一、概述
 
-Task Framework 是 Hermes Personal Suite 的核心技能之一，提供从任务创建、执行到归档的完整工作流。它覆盖三层能力：
+Task Framework 是 Hermes 的核心技能之一，提供从任务创建、执行到归档的完整工作流。它覆盖三层能力：
 
 - **方法论** — 如何把一句话需求拆成可执行的操作
 - **容器** — 如何在文件系统中有序组织任务产物
@@ -61,5 +61,5 @@ Task Framework 是 Hermes Personal Suite 的核心技能之一，提供从任务
 | 组件 | 关系 |
 |------|------|
 | `quality-gate` skill | 任务修改后自动触发质量门禁 |
-| `GIT.md` rule | git 操作前置同步（Pre-Change Sync）和后置清理（Post-Change Workflow） |
-| `dump-to-stage` skill | 任务的记忆备份不冲突 — task-framework 管任务内容，dump-to-stage 管系统状态 |
+| Git workflow rules | git 操作前置同步（Pre-Change Sync）和后置清理（Post-Change Workflow）（if available） |
+| Memory/state backup skill (if available) | 任务的记忆备份不冲突 — task-framework 管任务内容，backup skill 管系统状态 |

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/auto-runner.md

@@ -29,4 +29,4 @@ Phases without an implementation should return `True` (skip, don't fail) so the
 
 ## Venv
 
-Use `~/.venvs/playwright/bin/python` if available (has playwright, edge-tts, matplotlib, Pillow).
+Use the task's `.venv` if available (e.g. playwright, edge-tts, matplotlib, Pillow).

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/composites/software-dev.md

@@ -12,7 +12,7 @@ Standard round-trip for implementing a feature from scratch.
 5. project-tasks   → 更新 TASK.md，标记完成
 ```
 
-> **Note on docs:** The user prefers a four-doc split for feature work: 产品需求 (PRD), 产品设计 (product design), 技术需求 (TRD), 技术设计 (technical design). See `references/operations/document-write.md` for details. For small/straightforward features, a PRD+TRD pair may suffice — use judgment.
+> **Note on docs:** The recommended pattern is a four-doc split for feature work: 产品需求 (PRD), 产品设计 (product design), 技术需求 (TRD), 技术设计 (technical design). See `references/operations/document-write.md` for details. For small/straightforward features, a PRD+TRD pair may suffice — use judgment.
 
 ## Loop Patterns
 

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/generating-output-documents.md

@@ -139,7 +139,7 @@ Add a `> **发文：** ... ｜ **文号：** ... ｜ **目标节点：** ...` li
    ```
    This script has its own markdown→HTML renderer that handles Chinese headings, pipe tables, blockquotes, lists, code blocks, and `---` horizontal rules without pandoc's YAML issue.
 
-3. **Font Requirements:** This system has `WenQuanYi Zen Hei` at `/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc`. The CSS font-family MUST list this font first. Do NOT use:
+3. **Font Requirements:** Ensure a CJK font is installed (e.g., WenQuanYi Zen Hei, Noto Sans CJK). The CSS font-family MUST list an installed CJK font first. Do NOT use:
    - `Noto Sans CJK SC` (not installed)
    - `Source Han Sans SC` (not installed)
    - `SimSun` (not installed)

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/operations/document-write.md

@@ -159,14 +159,14 @@ When writing or updating any of the four docs:
 
 ## Cross-Referencing with Session History
 
-When writing "as-built" docs for work already implemented, use the `conversation-message-list` skill to review the actual conversation and extract the precise set of changes:
+When writing "as-built" docs for work already implemented, use the `conversation-message-list` skill (if available) to review the actual conversation and extract the precise set of changes:
 
 ```bash
 # Get the session ID for the relevant conversation
 hermes sessions list
 
 # Show compact Q&A history (no tool calls)
-python3 ~/.hermes/skills/hermes/conversation-message-list/scripts/list-messages.py <session_id>
+python3 scripts/list-messages.py <session_id>
 ```
 
 This gives a tool-call-free list of every user question and final answer, which maps directly to feature requirements and design decisions.
@@ -177,9 +177,9 @@ This gives a tool-call-free list of every user question and final answer, which
 |---------|------------|
 | Writing only PRD without design/tech docs | Split into all four to cover product + implementation perspectives |
 | ASCII diagrams with ambiguous proportion | Mark flex ratios explicitly (`flex: 2` / `flex: 1`) in the diagram caption |
-| Ignoring user feedback-coupling | Use feedback-station skill to cross-reference doc sections with user feedback IDs |
+| Ignoring user feedback-coupling | Use feedback-station skill (if available) to cross-reference doc sections with user feedback IDs |
 | Doc status unchanged after implementation | Update status from "需求讨论中" to actual development phase |
 | No known-issues section in tech design | Always include a backlog/Known Issues table to track gaps |
 | Overwriting existing PRD structure | Read existing doc first, then append/update sections — don't rewrite from scratch |
-| Writing docs from memory instead of session replay | Use `conversation-message-list` skill to re-read the actual conversation for accurate change scope |
+| Writing docs from memory instead of session replay | Use `conversation-message-list` skill (if available) to re-read the actual conversation for accurate change scope |
 | Forgetting to update sibling docs | When any one doc changes, check and update all four — they form a coherent set |

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/research-workflow.md

@@ -109,7 +109,7 @@ Each subagent's prompt must include:
 Example task spec:
 
 ```
-"context": "输出文件：~/studio/project/tasks/*.research/docs/competitor-qinjia.md
+"context": "输出文件：$HERMES_TASKS_ROOT/<ts>.<name>/docs/competitor-<name>.md
 格式规范：
 # 亲家科技
 ## 产品体系
@@ -132,7 +132,7 @@ delegate_task(
 )
 ```
 
-Max concurrent tasks for this user: 3. Time budget: ~5-10 min each.
+Max concurrent tasks: 3 (adjust per environment). Time budget: ~5-10 min each.
 
 ## Compile results
 

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/task-hash-naming.md

@@ -23,8 +23,8 @@ The hash suffix at the end of the directory name ensures:
 
 Example:
 ```
-tasks/20260605-233355.health-sales-demo-5d5a1a/
-├── .hermes-task.json     ← hash: "5d5a1a", name: "health-sales-demo-5d5a1a"
+tasks/<ts>.<task-name>-<hash6>/
+├── .hermes-task.json     ← hash: "<hash6>", name: "<task-name>-<hash6>"
 ├── TASK.md
 └── ...
 ```

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/task-lifecycle-example.md

@@ -15,12 +15,12 @@ For research/documentation tasks, also create docs/:
 
 ```
 ts=$(date '+%Y%m%d-%H%M%S')
-mkdir -p "tasks/${ts}.kangyang-center-research/logs/"
-mkdir -p "tasks/${ts}.kangyang-center-research/docs/"
+mkdir -p "tasks/${ts}.<task-name>/logs/"
+mkdir -p "tasks/${ts}.<task-name>/docs/"
 ```
 
 Result: `tasks/20260601-164001.paper-reproduction/` (code) or
-         `tasks/20260602-041236.kangyang-center-research/` (research)
+         `tasks/20260602-041236.<task-name>/` (research)
 
 ## 2. Status — active
 
@@ -106,11 +106,11 @@ tasks/
         └── error.20260601-171200.log
 ```
 
-For a **research/documentation task** (康养中心调研):
+For a **research/documentation task** (<task-name>):
 
 ```
 tasks/
-└── 20260602-041236.kangyang-center-research/
+└── 20260602-041236.<task-name>/
     ├── README.md              ← overview + key findings summary
     ├── TASK.md                ← checklist (Phase 1-5)
     ├── docs/                  ← organized markdown research materials

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/task-types/analysis.md

@@ -57,4 +57,4 @@ rm -rf output/            # 删除所有生成文档和日志
 
 1. 确认所有交付物在 `output/docs/` 中
 2. 更新 TASK.md 状态为 `completed`
-3. 运行 `python3 ~/.hermes/skills/software-development/task-framework/scripts/update-index.py` 更新索引
+3. 运行 `python3 scripts/update-index.py` 更新索引

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/task-types/external-audit.md

@@ -53,4 +53,4 @@ rm -rf output/            # 删除所有分析文档和日志
 
 1. 确认所有交付物在 `output/docs/` 中
 2. 更新 TASK.md 状态为 `completed`
-3. 运行 `python3 ~/.hermes/skills/software-development/task-framework/scripts/update-index.py` 更新索引
+3. 运行 `python3 scripts/update-index.py` 更新索引

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/references/task-types/video-production-pipeline.md

@@ -2,10 +2,10 @@
 
 ## 创建
 
-1. 通过 `task_create --skill browser-screen-record-task` 创建
+1. 通过 `task_create --skill <video-skill>` 创建
 2. 创建 `tasks/<ts>.<name>-<hash6>/` 目录，含 `input/` `output/` `scripts/`
 3. 用户填写的 `REQUIREMENTS.md` 和 `images/`（封面图片）放在 `input/`
-4. `browser-screen-record-task` 的 `scripts/create_task.py` 生成初始 `TASK.md`
+4. `<video-skill>` 的 `scripts/create_task.py` 生成初始 `TASK.md`
 5. 写入 `.hermes-task.json`
 
 ## 执行
@@ -50,7 +50,7 @@ tasks/<ts>.<name>-<hash6>/
 └── .hermes-task.json
 ```
 
-> **迁移说明：** 现有 pipeline 任务（如 `health-sales-demo-5d5a1a`）可能还把 REQUIREMENTS.md 和 images/ 放在根目录。后续对此任务操作时，应迁移到 `input/` + `output/` 模型。
+> **迁移说明：** 现有 pipeline 任务（如 `<task-name>-<hash6>`）可能还把 REQUIREMENTS.md 和 images/ 放在根目录。后续对此任务操作时，应迁移到 `input/` + `output/` 模型。
 
 ## 修改
 
@@ -62,7 +62,7 @@ tasks/<ts>.<name>-<hash6>/
 ```bash
 # 方式 A（推荐）：通过 pipeline.py
 cd tasks/<ts>.<name>-<hash6>/
-python3 ~/.hermes/skills/media/video-production-pipeline/scripts/pipeline.py --clean
+python3 <skill-path>/scripts/pipeline.py --clean
 
 # 方式 B：通用清理（input/ 安全）
 rm -rf output/
@@ -74,4 +74,4 @@ rm -rf output/
 
 1. 确认 `output/compositing-<hash6>/output.mp4` 存在且可播放（ffprobe 验证）
 2. 更新 TASK.md 状态为 `completed`
-3. 运行 `python3 ~/.hermes/skills/software-development/task-framework/scripts/update-index.py` 更新索引
+3. 运行 `python3 scripts/update-index.py  # from the skill directory` 更新索引

{hermes_task_framework-1.1.0 → hermes_task_framework-1.2.1}/hermes_task_framework/skills/task-framework/scripts/manage_task.py

@@ -2,14 +2,14 @@
 """
 task-framework 任务生命周期管理工具
 
-管理 ~/studio/hermes/tasks/ 下的任务文件（默认，可通过 config.yaml 配置）。
+管理 $HERMES_TASKS_ROOT 下的任务文件（默认，可通过 config.yaml 配置）。
 不再使用镜像目录——所有文件直接存放在任务目录下。
 
-配置优先级（同 token-consumption-tracker 模式）：
+配置优先级：
   1. HERMES_TASKS_ROOT 或 HERMES_TASKS_DIR 环境变量
   2. 当前 profile config.yaml: tasks.data_dir
   3. 全局 ~/.hermes/config.yaml: tasks.data_dir
-  4. Fallback: ~/studio/hermes/tasks
+  4. Fallback: ~/studio/hermes/tasks (legacy ~/.hermes/tasks is never populated)
 
 Commands:
     create    创建新任务（目录 + hash + 元数据 + 模板 + 可选 inbox 移入）
@@ -22,17 +22,17 @@ Commands:
     reindex   重建索引文件（README.md + TASKS.md）
     init      为任务创建目录 + TASK.md + CHANGELOG.md + .hermes-task.json
     export    将任务打包为可移植 tar.gz
-    import    从 tar.gz 恢复任务
-    rebuild   按 hash 查找最近 tar.gz 并导入
+    import    从 tar.gz 或 zip 恢复任务
+    rebuild   按 hash 查找最近 tar.gz 或 zip 并导入
     migrate   一次性迁移：将旧存储目录下的文件迁移到统一目录
     ensure-all 全量注册所有现有任务
 """
-import os, sys, glob, json, shutil, re, tarfile, tempfile, hashlib, random, argparse, secrets
+import os, sys, glob, json, shutil, re, tarfile, zipfile, tempfile, hashlib, random, argparse, secrets
 from datetime import datetime
 from pathlib import Path
 
 
-# ── config resolution (mirrors token-consumption-tracker pattern) ──
+# ── config resolution ──
 
 def _read_config_yaml(config_path):
     if not config_path or not os.path.exists(str(config_path)):
@@ -46,9 +46,11 @@ def _read_config_yaml(config_path):
 
 
 def _resolve_tasks_root() -> str:
-    """Priority chain: env → profile config → global config → fallback."""
-    # 1. Env var
-    env = os.environ.get("HERMES_TASKS_DIR", "").strip()
+    """Resolve the task root with ROOT as canonical and DIR as legacy fallback."""
+    # 1. Canonical env var, then the legacy pip-package compatibility alias.
+    env = os.environ.get("HERMES_TASKS_ROOT", "").strip()
+    if not env:
+        env = os.environ.get("HERMES_TASKS_DIR", "").strip()
     if env:
         return os.path.expanduser(env)
 
@@ -76,7 +78,7 @@ def _resolve_tasks_root() -> str:
             if val and isinstance(val, str):
                 return os.path.expanduser(val)
 
-    # 4. Fallback
+    # 4. Canonical fallback. Never populate the legacy ~/.hermes/tasks root.
     return os.path.expanduser("~/studio/hermes/tasks")
 
 
@@ -360,8 +362,15 @@ def cmd_import(archive_path):
         print(f"Archive not found: {archive_path}")
         return False
     with tempfile.TemporaryDirectory(prefix="task-import-") as tmp:
-        with tarfile.open(archive_path, 'r:gz') as tar:
-            tar.extractall(path=tmp)
+        if tarfile.is_tarfile(archive_path):
+            with tarfile.open(archive_path, 'r:gz') as tar:
+                tar.extractall(path=tmp)
+        elif zipfile.is_zipfile(archive_path):
+            with zipfile.ZipFile(archive_path) as archive:
+                archive.extractall(path=tmp)
+        else:
+            print(f"Unsupported archive format: {archive_path}")
+            return False
         extracted = os.listdir(tmp)
         print(f"Extracted: {extracted}")
 
@@ -415,16 +424,25 @@ def cmd_import(archive_path):
 
 
 def cmd_rebuild(hash_or_archive):
-    if tarfile.is_tarfile(hash_or_archive):
+    if os.path.isfile(hash_or_archive) and (
+        tarfile.is_tarfile(hash_or_archive) or zipfile.is_zipfile(hash_or_archive)
+    ):
         return cmd_import(hash_or_archive)
     h = hash_or_archive
     if not re.match(r'^[a-z0-9]{6}$', h):
         print(f"Invalid hash: {h}")
         return False
-    pattern = os.path.join(TASKS_ROOT, f"*{h}*.tar.gz")
-    matches = sorted(glob.glob(pattern), key=os.path.getmtime, reverse=True)
+    patterns = [
+        os.path.join(TASKS_ROOT, f"*{h}*.tar.gz"),
+        os.path.join(TASKS_ROOT, f"*{h}*.zip"),
+    ]
+    matches = sorted(
+        [match for pattern in patterns for match in glob.glob(pattern)],
+        key=os.path.getmtime,
+        reverse=True,
+    )
     if not matches:
-        print(f"No tar.gz found for hash {h} in {TASKS_ROOT}")
+        print(f"No tar.gz or zip found for hash {h} in {TASKS_ROOT}")
         return False
     archive = matches[0]
     print(f"Found: {archive}")
@@ -489,7 +507,7 @@ def cmd_list():
 
 def cmd_migrate():
     """One-shot migration: copy files from old personal storage to task dir."""
-    old_root = os.path.expanduser("~/.hermes/personal/tasks")
+    old_root = os.path.expanduser("~/.hermes/tasks")
     if not os.path.isdir(old_root):
         print("No old personal/tasks directory to migrate from.")
         return True
@@ -592,8 +610,8 @@ def cmd_create(name, from_inbox=None, description=None):
     cl_tmpl = _load_template('CHANGELOG.md')
     if cl_tmpl:
         cl_content = cl_tmpl.replace(
-            '## 2026-06-06 HH:MM',
-            f"## {datetime.now().strftime('%Y-%m-%d %H:%M')}")
+            '## 2026-06-06 HH:MM:SS',
+            f"## {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
     else:
         cl_content = f"# CHANGELOG.md -- {h}\n"
     with open(os.path.join(task_dir, 'CHANGELOG.md'), 'w') as f: