hermes-task-framework 1.0.0__py3-none-any.whl

task-framework/skills/task-lifecycle-portability/references/task-recovery-procedure.md

@@ -0,0 +1,63 @@
+# TASK.md Recovery Procedure
+
+When a task directory exists but `TASK.md` is missing (deleted, never created, or corrupted), reconstruct it from surrounding artifacts.
+
+## Step 0: Check symlink target first
+
+If the task has hash-based naming (rightmost 6 chars = `<hash6>`), check `~/.hermes/personal/tasks/<hash>/task.md`:
+
+```bash
+ls -la ~/.hermes/personal/tasks/<hash>/task.md
+# If exists → restore with:
+python3 ~/.hermes/skills/software-development/task-framework/scripts/manage_task.py relink <hash>
+```
+
+If the personal backup exists, symlink recovery is instant.
+
+## Step 1: Gather evidence
+
+| Source | What it tells you |
+|--------|------------------|
+| `~/.hermes/personal/tasks/<hash>/task.md` | content backup — instant recovery via relink |
+| `~/.hermes/personal/tasks/<hash>/memory.md` | TASK_MEMORY.md content backup |
+| `.hermes-task.json` | hash, name, outputs, dependencies |
+| `TASK_MEMORY.md` | last session's state, what was done, what broke |
+| `input/REQUIREMENTS.md` | original task spec |
+| `output/` | all generated files |
+| Root index (`tasks/TASKS.md`) | aggregated status from last index run |
+
+## Step 2: Identify task type and load its governing skill
+
+Scan directory for type-signature files — `REQUIREMENTS.md` + `RECORDING.md` + `COMPOSITING.md` → video-production task. Load the relevant skill that defines this task type's phases.
+
+> 🔴 Do NOT guess phase structure from memory or from other similar tasks. Load the domain skill and use its defined phases.
+
+## Step 3: Map evidence to skill's phase structure
+
+Cross-reference:
+- Phase directories in `output/` → confirm each matches a skill-defined phase
+- Outputs in `.hermes-task.json` → map each to the right phase's product
+- TASK_MEMORY.md execution notes → confirm sequence matches skill's defined order
+- Parallel deps → check annotations match skill's flow table
+
+## Step 4: Write TASK.md
+
+Follow the skill's template for format. Use the skill's standard phase names and dependency annotations. Mark all verified-completed items `[x]`.
+
+## Step 5: Verify before marking done
+
+Only mark phases `[x]` if the output artifact exists and can be verified. If a phase was in-progress but incomplete, mark `[ ]` and note in `## Notes`.
+
+## Step 6: Update indexes
+
+```bash
+python3 ~/.hermes/skills/software-development/task-framework/scripts/update-index.py
+```
+
+## Pitfalls
+
+- 🔴 **Do NOT infer phase structure from prior conversation** — load the domain skill
+- 🔴 **Do NOT invent phases that don't match the skill's template**
+- 🔴 **Do NOT reorder phases from the skill's defined sequence**
+- 🔴 **Always verify material existence** — directory existing ≠ phase completed
+- 🔴 **BREAK placement** — keep exactly where the skill template places them

task-framework/skills/task-timestamp-convention/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: task-timestamp-convention
+description: "Task directory naming conventions — timestamp format (local timezone) AND name content guidelines. Name must be self-explanatory: <system/domain>-<deliverable-type> not generic terms."
+version: 1.1.0
+author: Personal Suite
+license: MIT
+category: software-development
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags:
+      - task
+      - naming
+      - convention
+      - timestamp
+      - directory
+    relations:
+      - type: used_in_workflow
+        target: task-framework
+        properties:
+          reason: "Called during every task_create"
+          strength: strong
+---
+
+# Task Naming Conventions
+
+Two aspects: **timestamp format** and **name content**.
+
+## 1. Timestamp: Local Timezone
+
+When creating task directories, the timestamp must use **local time** (UTC+8), **not UTC**.
+
+```bash
+# ✅ CORRECT — local timezone
+TS=$(date +"%Y%m%d-%H%M%S")
+
+# ❌ WRONG — UTC (off by 8 hours)
+TS=$(date -u +"%Y%m%d-%H%M%S")
+```
+
+## 2. Name: Self-Explanatory Content
+
+The task name (after the timestamp) must describe **what system/domain** and **what deliverable type**. Generic terms like "architecture-diagram", "analysis", "research" alone are not acceptable.
+
+### Pattern
+
+```
+<system-or-domain>-<deliverable-type>
+```
+
+### Good vs Bad Examples
+
+| ❌ Bad (too generic) | ✅ Good (self-explanatory) |
+|---------------------|--------------------------|
+| `system-architecture-diagram` | `personal-suite-troupe-architecture` |
+| `api-design` | `eir-health-data-api-design` |
+| `bug-fix` | `user-service-login-500-error-fix` |
+| `code-review` | `heart-health-backend-PR-42-review` |
+| `research` | `memory-retrieval-trigger-mechanisms-research` |
+
+### Why
+
+Task names appear in `tasks/` directory listing, `tasks/README.md` index, and kanban cards. A name like `system-architecture-diagram` could mean any system — the agent and user must click into TASK.md to understand what task it is.
+
+### Exceptions
+
+Simple one-off actions that live in the task root for <24h may use short names. Anything expected to persist longer must follow the pattern above.
+
+## 3. Related
+
+- task-framework — parent skill governing task creation lifecycle
+- workflow-conditional-branching — decision-fork pattern for multi-phase tasks

task-framework/skills/task-tracker/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: task-tracker
+description: "任务跟踪回写 — 更新 TASK.md checkbox、追加 TASK_MEMORY.md、刷新索引。接收通用参数，隐藏 task-framework 内部约定"
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+category: software-development
+tags: [task, tracking, task-framework, checklist, memory]
+---
+
+# Task Tracker
+
+## 定位
+
+`task-tracker` 是任务层的 bookkeeping skill。它知道 task-framework 的内部约定（TASK.md checkbox 格式、TASK_MEMORY.md 追加格式、索引更新），对外暴露简单的参数接口。
+
+角色不需要知道 task-framework 的任何细节——它们只需要加载 `task-tracker` 并传入参数。
+
+## 参数
+
+| 参数 | 必须 | 类型 | 说明 |
+|------|------|------|------|
+| `task_dir` | ✅ | path | TASK.md 所在目录的绝对路径 |
+| `phase` | ✅ | string | 当前完成的 phase 标识，如 `Phase 0: scrutiny-pipeline` |
+| `executor` | ✅ | string | 执行者名称，如 `scrutaris` |
+| `findings` | ❌ | list | 关键发现行 |
+| `outputs` | ❌ | list | 产出文件路径（相对 task_dir） |
+| `next` | ❌ | string | 后续 phase |
+
+## 执行步骤
+
+1. 读取 `TASK.md`
+2. 找到包含 `<phase>` 文本的 `- [ ]` 行，改为 `- [x]`
+3. 在 `TASK_MEMORY.md` 末尾追加记录：
+
+```markdown
+## <phase> — <executor>
+
+- **执行时间**: <当前时间>
+- **状态**: completed
+- **关键发现**:
+  - <finding line 1>
+  - <finding line 2>
+- **输出**:
+  - `<output file 1>`
+- **下一步**: <next>
+```
+
+4. 运行 `python3 ~/.hermes/skills/software-development/task-framework/scripts/update-index.py`
+
+## 使用示例
+
+```
+加载 task-tracker：
+  task_dir: /home/hauzer/studio/hermes/tasks/20260709-204723.token-factory-troupe-e957c3
+  phase: Phase 0: scrutiny-pipeline
+  executor: scrutaris
+  findings:
+    - 词元供应市场规模 ¥2,426万亿次(2025)，+1,603% YoY
+    - 硅基流动毛利率 -24%，公有云越卖越亏
+    - 推广免费token占销售费用 64.7%
+  outputs:
+    - output/docs/00-scrutiny-report.md
+  next: Phase 1: domain-analysis
+```
+
+## 与 task-framework 的关系
+
+`task-tracker` 封装了 task-framework 的以下操作：
+- TASK.md checkbox 格式（`- [ ]` → `- [x]`）
+- TASK_MEMORY.md 追加格式
+- update-index.py 调用
+
+task-framework 不需要知道 `task-tracker` 的存在——它只提供 task 容器。`task-tracker` 是独立工具，消费 task-framework 的产出格式。
+
+## 与 orchestrator 的关系
+
+Orchestrator（stratis/corvan/valros）读取 TASK.md 的 `## Tracking` 段，获取 tracker skill 名和参数定义，注入到每个 phase 的 card body 或 worker brief 中。
+
+角色收到 card 后，在工作完成时按 brief 指令加载 `task-tracker` 并传入参数。角色不需要理解 task-framework——它只管传入参数。