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

task-framework/skills/task-framework/scripts/task-runner.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Task Runner — execute a command with timestamped stdout/stderr logging
+# Usage: task-runner.sh <task-dir> <command...>
+#
+# Creates:
+#   <task-dir>/logs/output.YYYYMMDD-HHMMSS.log
+#   <task-dir>/logs/error.YYYYMMDD-HHMMSS.log
+# stdout and stderr also go to terminal.
+# Exit code preserved.
+
+set -e
+
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 <task-dir> <command...>" >&2
+    exit 1
+fi
+
+TASK_DIR="$1"
+shift
+
+mkdir -p "$TASK_DIR/logs"
+
+TIMESTAMP=$(date '+%Y%m%d-%H%M%S')
+OUTPUT_LOG="$TASK_DIR/logs/output.${TIMESTAMP}.log"
+ERROR_LOG="$TASK_DIR/logs/error.${TIMESTAMP}.log"
+
+# Header
+echo "-------- $(date '+%Y-%m-%d %H:%M:%S') --------" > "$OUTPUT_LOG"
+echo "-------- $(date '+%Y-%m-%d %H:%M:%S') --------" > "$ERROR_LOG"
+echo "Command: $*" >> "$OUTPUT_LOG"
+echo "Command: $*" >> "$ERROR_LOG"
+echo "--------" >> "$OUTPUT_LOG"
+echo "--------" >> "$ERROR_LOG"
+
+# Run command with split tee
+# stdout → both terminal and output log
+# stderr → both terminal and error log
+"$@" 2> >(tee "$ERROR_LOG" >&2) | tee "$OUTPUT_LOG"
+
+EXIT_CODE=$?
+echo "Exit code: $EXIT_CODE" | tee -a "$OUTPUT_LOG" | tee -a "$ERROR_LOG" >/dev/null
+exit $EXIT_CODE

task-framework/skills/task-framework/scripts/task_ref.py

@@ -0,0 +1,119 @@
+"""Task reference resolution utilities.
+
+Usage:
+    from task_ref import resolve_ref, check_cycles, create_task_meta
+"""
+import os, glob, json, hashlib, random, datetime, re, sys, subprocess
+
+TASKS_ROOT = os.path.expanduser(os.environ.get("HERMES_TASKS_ROOT", "~/studio/hermes/tasks"))
+
+def _hash6():
+    return hashlib.md5(str(random.random()).encode()).hexdigest()[:6]
+
+def resolve_ref(ref_str):
+    """Resolve ref:hash/output_name to absolute path."""
+    if not ref_str.startswith('ref:'):
+        return ref_str
+    parts = ref_str[4:].split('/', 1)
+    hash_id = parts[0]
+    output_name = parts[1] if len(parts) > 1 else None
+    
+    matches = glob.glob(os.path.join(TASKS_ROOT, f'*{hash_id}*'))
+    if not matches:
+        raise FileNotFoundError(f'Task with hash {hash_id} not found in {TASKS_ROOT}')
+    
+    task_dir = matches[0]
+    meta_path = os.path.join(task_dir, '.hermes-task.json')
+    if not os.path.exists(meta_path):
+        raise FileNotFoundError(f'.hermes-task.json not found in {task_dir}')
+    
+    with open(meta_path) as f:
+        meta = json.load(f)
+    
+    if output_name:
+        if output_name not in meta.get('outputs', {}):
+            raise KeyError(f'Output "{output_name}" not declared in {task_dir}/.hermes-task.json. '
+                           f'Available: {list(meta.get("outputs", {}).keys())}')
+        return os.path.join(task_dir, meta['outputs'][output_name])
+    
+    return task_dir
+
+def check_cycles(meta):
+    """Walk dependency graph, raise ValueError on cycles."""
+    seen = [meta['hash']]
+    stack = list(meta.get('dependencies', []))
+    while stack:
+        h = stack.pop()
+        if h in seen:
+            raise ValueError(f'Cycle detected: {h} already in path {" → ".join(seen)}')
+        seen.append(h)
+        matches = glob.glob(os.path.join(TASKS_ROOT, f'*{h}*'))
+        if matches:
+            dep_meta_path = os.path.join(matches[0], '.hermes-task.json')
+            if os.path.exists(dep_meta_path):
+                dep_meta = json.load(open(dep_meta_path))
+                stack.extend(dep_meta.get('dependencies', []))
+    return True
+
+def create_task_meta(task_dir, name, dependencies=None, related=None, supersedes=None, board="default"):
+    """Create .hermes-task.json in a task directory. Returns the hash.
+    Also creates a kanban card on the specified board and stores the card ID."""
+    h = _hash6()
+    meta = {
+        "hash": h,
+        "name": name,
+        "created_at": datetime.datetime.now().isoformat(),
+        "outputs": {},
+        "dependencies": dependencies or [],
+        "related": related or [],
+        "supersedes": supersedes or [],
+        "kanban_card_id": "",
+    }
+    
+    # Check cycles before writing
+    if meta['dependencies']:
+        check_cycles(meta)
+    
+    meta_path = os.path.join(task_dir, '.hermes-task.json')
+    with open(meta_path, 'w') as f:
+        json.dump(meta, f, indent=2, ensure_ascii=False)
+    
+    # Create kanban card
+    dirname = os.path.basename(task_dir)
+    title = f"{name} [task:{dirname}]"
+    env = {**os.environ}
+    env.pop("HERMES_KANBAN_BOARD", None)  # Avoid env leak override
+    try:
+        result = subprocess.run(
+            ["hermes", "kanban", "boards", "switch", board],
+            capture_output=True, text=True, timeout=10, env=env,
+        )
+        result = subprocess.run(
+            ["hermes", "kanban", "create", title, "--assignee", "default"],
+            capture_output=True, text=True, timeout=15, env=env,
+        )
+        if result.returncode == 0:
+            # Parse card ID from output: "Created t_xxx  (ready, ...)"
+            out = result.stdout.strip()
+            m = re.search(r'Created (t_[a-f0-9]+)', out)
+            if m:
+                card_id = m.group(1)
+                meta["kanban_card_id"] = card_id
+                # Update .hermes-task.json with card id
+                with open(meta_path, 'w') as f:
+                    json.dump(meta, f, indent=2, ensure_ascii=False)
+    except Exception as e:
+        print(f"  ⚠ kanban card creation failed: {e}", file=sys.stderr)
+    
+    return h
+
+def set_output(task_dir, name, path):
+    """Register a named output in .hermes-task.json."""
+    meta_path = os.path.join(task_dir, '.hermes-task.json')
+    if not os.path.exists(meta_path):
+        raise FileNotFoundError(f'No .hermes-task.json in {task_dir}')
+    with open(meta_path) as f:
+        meta = json.load(f)
+    meta['outputs'][name] = path
+    with open(meta_path, 'w') as f:
+        json.dump(meta, f, indent=2, ensure_ascii=False)

task-framework/skills/task-framework/scripts/update-index.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+update-index.py — Update tasks/ root index files.
+
+Regenerates both:
+  1. tasks/README.md  — summary table (directory façade)
+  2. tasks/TASKS.md   — aggregated checklist view (deep overview)
+
+Usage:
+  python3 scripts/update-index.py                     # default: ~/studio/hermes/tasks
+  python3 scripts/update-index.py --tasks-dir /path   # custom path
+"""
+
+import os, sys, re, glob
+
+TASKS_ROOT = os.path.expanduser(os.environ.get("HERMES_TASKS_ROOT", "~/studio/hermes/tasks"))
+
+def gather_tasks(tasks_root):
+    """Return sorted list of (dirname, ts, name, title, status, desc, checklist, notes, related_tasks, related_tickets, cluster_info)."""
+    task_dirs = sorted(glob.glob(os.path.join(tasks_root, "2*/")))
+    results = []
+    for d in task_dirs:
+        dirname = os.path.basename(d.rstrip('/'))
+        parts = dirname.split('.', 1)
+        ts = parts[0]
+        name = parts[1] if len(parts) > 1 else dirname
+
+        task_md_path = os.path.join(d, "TASK.md")
+        title = name
+        status = "—"
+        desc = ""
+        checklist = []
+        notes = []
+        related_tasks = []
+        related_tickets = []
+        cluster_info = {"affinity": "", "claimed_by": ""}
+
+        # Read .hermes-task.json for cluster fields
+        meta_path = os.path.join(d, ".hermes-task.json")
+        if os.path.exists(meta_path):
+            try:
+                import json
+                with open(meta_path) as f:
+                    meta = json.load(f)
+                cluster_info["affinity"] = meta.get("affinity", "")
+                cluster_info["claimed_by"] = meta.get("claimed_by", "") or ""
+            except Exception:
+                pass
+
+        if os.path.exists(task_md_path):
+            content = open(task_md_path, encoding='utf-8').read()
+
+            # Title: # Task: <title> or first # heading
+            m = re.search(r'^# Task:\s*(.+)$', content, re.MULTILINE)
+            if m:
+                title = m.group(1).strip()
+            else:
+                m = re.search(r'^#\s+(.+)$', content, re.MULTILINE)
+                if m:
+                    title = m.group(1).strip()
+
+            # Status: ## Status or ## 状态
+            m = re.search(r'^## (?:Status|状态)\s*\n\s*(.+?)\s*$', content, re.MULTILINE)
+            if m:
+                status = m.group(1).strip()
+
+            # Goal / Description: ## Goal or ## 目标 or ## 概述
+            m = re.search(r'^## (?:Goal|目标|概述)\s*\n\s*(.+?)\s*$', content, re.MULTILINE)
+            if m:
+                desc = m.group(1).strip()
+
+            # Checklist: ## Checklist or ## 步骤 or ## Checklist（步骤）
+            in_cl = False
+            for line in content.split('\n'):
+                if line.startswith('## Checklist') or line.startswith('## 步骤'):
+                    in_cl = True
+                    continue
+                if in_cl:
+                    if line.startswith('## '):
+                        break
+                    if line.strip().startswith('- ['):
+                        checklist.append(line.strip())
+
+            # Notes: ## Notes or ## 备注
+            in_nt = False
+            for line in content.split('\n'):
+                if line.startswith('## Notes') or line.startswith('## 备注'):
+                    in_nt = True
+                    continue
+                if in_nt and line.startswith('## '):
+                    break
+                if in_nt and line.strip():
+                    notes.append(line.strip())
+
+            # Related Tasks: ## Related Tasks table
+            in_rt = False
+            header_skipped = False
+            for line in content.split('\n'):
+                if line.startswith('## Related Tasks'):
+                    in_rt = True
+                    header_skipped = False
+                    continue
+                if in_rt:
+                    if line.startswith('## '):
+                        break
+                    if not line.strip():
+                        continue
+                    # Skip header row and separator row
+                    striped = line.strip()
+                    if striped.startswith('|') and '---' in striped:
+                        header_skipped = True
+                        continue
+                    if striped.startswith('|') and header_skipped:
+                        # Parse table row: | type | task_path | description |
+                        cols = [c.strip() for c in striped.strip('|').split('|')]
+                        if len(cols) >= 3:
+                            rtype = cols[0].strip()
+                            task_path = cols[1].strip().strip('`')
+                            rdesc = cols[2].strip()
+                            related_tasks.append({
+                                'type': rtype,
+                                'task_path': task_path,
+                                'description': rdesc
+                            })
+
+            # Related Tickets: ## Related Tickets table
+            in_rti = False
+            header_skipped_rti = False
+            for line in content.split('\n'):
+                if line.startswith('## Related Tickets'):
+                    in_rti = True
+                    header_skipped_rti = False
+                    continue
+                if in_rti:
+                    if line.startswith('## '):
+                        break
+                    if not line.strip():
+                        continue
+                    striped = line.strip()
+                    if striped.startswith('|') and '---' in striped:
+                        header_skipped_rti = True
+                        continue
+                    if striped.startswith('|') and header_skipped_rti:
+                        cols = [c.strip() for c in striped.strip('|').split('|')]
+                        if len(cols) >= 2:
+                            ticket_id = cols[0].strip().strip('`').lstrip('#')
+                            rdesc_ti = cols[1].strip()
+                            related_tickets.append({
+                                'ticket_id': ticket_id,
+                                'description': rdesc_ti
+                            })
+
+        results.append((dirname, ts, name, title, status, desc, checklist, notes, related_tasks, related_tickets, cluster_info))
+    return results
+
+def gen_readme(tasks):
+    """Generate README.md — summary table with ticket links."""
+    lines = ["# Tasks", "",
+             "Project tasks managed under `tasks/`. Each task is a self-contained unit of work.",
+             "",
+             "| Timestamp | Name | Status | Ticket | Description |",
+             "|---|---|---|---|---|"]
+    for dirname, ts, name, title, status, desc, _, _, _, related_tickets, cluster_info in tasks:
+        s = status.replace('\n', ' ').strip()
+        d = desc.replace('\n', ' ').strip()[:60]
+        if not d:
+            d = title[:60]
+        ticket_tag = ""
+        if related_tickets:
+            ids = ", ".join(f"#{t['ticket_id']}" for t in related_tickets)
+            ticket_tag = f"{ids}"
+        cl_tag = ""
+        if cluster_info.get("affinity") and cluster_info["affinity"] != "any":
+            cl_tag = f"[{cluster_info['affinity']}]"
+            if cluster_info.get("claimed_by"):
+                cl_tag += f" →{cluster_info['claimed_by']}"
+        lines.append(f"| {ts} | {name} | {s} {cl_tag} | {ticket_tag} | {d} |")
+
+    # Inbox
+    inbox_dir = os.path.join(TASKS_ROOT, "inbox")
+    inbox_items = []
+    if os.path.isdir(inbox_dir):
+        inbox_items = sorted(os.listdir(inbox_dir))
+    if inbox_items:
+        lines.extend(["", "### Inbox"] + [f"- {item}" for item in inbox_items])
+
+    lines.append("")
+    return '\n'.join(lines)
+
+def gen_tasks_md(tasks):
+    """Generate TASKS.md — aggregated checklist view with relationship display."""
+    lines = ["# Tasks 聚合索引", "",
+             "所有任务的状态、Checklist 和关联关系汇总。由 `scripts/update-index.py` 自动生成，无需手动编辑。",
+             "", "---", ""]
+    for dirname, ts, name, title, status, desc, checklist, notes, related_tasks, related_tickets, cluster_info in tasks:
+        lines.append(f"## [{name}]({dirname}/)")
+        lines.append("")
+        lines.append(f"**状态:** {status.replace(chr(10), ' ').strip()}")
+        if cluster_info.get("affinity"):
+            cl_line = f"**Cluster:** affinity={cluster_info['affinity']}"
+            if cluster_info.get("claimed_by"):
+                cl_line += f", claimed_by={cluster_info['claimed_by']}"
+            lines.append(cl_line)
+            lines.append("")
+        if desc:
+            lines.append("")
+            lines.append(f"**目标:** {desc}")
+        lines.append("")
+        lines.append(f"**目录:** `{dirname}/`")
+
+        # Related tasks display
+        if related_tasks:
+            lines.append("")
+            lines.append("**关联任务:**")
+            lines.append("")
+            lines.append("| 关系 | 任务 | 说明 |")
+            lines.append("|------|------|------|")
+            for rt in related_tasks:
+                t = rt['type']
+                p = rt['task_path']
+                d = rt['description']
+                lines.append(f"| {t} | `{p}` | {d} |")
+
+        # Related tickets display
+        if related_tickets:
+            lines.append("")
+            lines.append("**关联 Ticket:**")
+            for rti in related_tickets:
+                tid = rti['ticket_id']
+                td = rti['description']
+                lines.append(f"- #{tid} — {td}")
+
+        if checklist:
+            done = sum(1 for c in checklist if c.startswith('- [x]'))
+            total = len(checklist)
+            lines.append("")
+            lines.append(f"### Checklist ({done}/{total} done)")
+            for item in checklist:
+                lines.append(f"- {item}")
+
+        if notes:
+            lines.append("")
+            lines.append("### Notes")
+            for n in notes[:5]:
+                lines.append(f"- {n}")
+
+        lines.extend(["", "---", ""])
+    return '\n'.join(lines)
+
+def get_inbox(tasks_root):
+    inbox_dir = os.path.join(tasks_root, "inbox")
+    items = []
+    if os.path.isdir(inbox_dir):
+        items = [f for f in os.listdir(inbox_dir)
+                 if os.path.isfile(os.path.join(inbox_dir, f)) or os.path.isdir(os.path.join(inbox_dir, f))]
+    return sorted(items)
+
+def write_readme(tasks_root):
+    tasks = gather_tasks(tasks_root)
+    content = gen_readme(tasks)
+    path = os.path.join(tasks_root, "README.md")
+    with open(path, 'w', encoding='utf-8') as f:
+        f.write(content)
+    return path, len(content)
+
+def write_tasks_md(tasks_root):
+    tasks = gather_tasks(tasks_root)
+    content = gen_tasks_md(tasks)
+    path = os.path.join(tasks_root, "TASKS.md")
+    with open(path, 'w', encoding='utf-8') as f:
+        f.write(content)
+    return path, len(content)
+
+def main():
+    tasks_root = TASKS_ROOT
+    for i, arg in enumerate(sys.argv[1:]):
+        if arg == '--tasks-dir' and i+2 < len(sys.argv):
+            tasks_root = os.path.abspath(sys.argv[i+2])
+
+    if not os.path.isdir(tasks_root):
+        print(f"Error: tasks root not found: {tasks_root}", file=sys.stderr)
+        sys.exit(1)
+
+    p1, s1 = write_readme(tasks_root)
+    p2, s2 = write_tasks_md(tasks_root)
+    tasks = gather_tasks(tasks_root)
+    print(f"Updated:")
+    print(f"  {p1}  ({s1}B)")
+    print(f"  {p2}  ({s2}B)")
+    print(f"  Found {len(tasks)} active tasks")
+
+if __name__ == '__main__':
+    main()

task-framework/skills/task-framework/templates/TASK.md

@@ -0,0 +1,114 @@
+# Task: <Name>
+
+<!--
+  TASK.md 关键字段规范（所有 task 遵守）：
+  - # Task: <Name>         — 标题（英文）
+  - ## Status              — 状态（英文）
+  - ## Goal                — 目标（英文）
+  - ## Checklist           — 步骤清单（英文）
+  - ## Notes               — 备注（英文）
+  - ## Related Tasks       — 关联任务关系表（可选）
+  脚本 update-index.py 只解析以上英文关键字段。
+  中文字段（## 状态、## 目标、## 步骤）为向下兼容而支持，新 task 请用英文。
+-->
+
+## Status
+
+active — <brief description of current work>
+
+## Goal
+
+<one-liner>
+
+## Skills (用于跨 skill 组合任务)
+
+- `<skill-name>` — <该 skill 在本任务中的用途>
+
+## Repo
+
+<!-- 可选字段。若任务关联独立的项目仓库，在此声明路径。
+     所有源码级产出（设计文档、代码、配置、测试）放到此仓库中，
+     而非 task/output/。执行日志和调试信息仍放在 task/output/logs/。
+     没有此字段时，所有产出放 task/output/（默认行为）。 -->
+
+路径: `<绝对路径，如 ~/studio/hermes/projects/agora/>`
+用途: <一句话描述>
+
+## Affinity (cluster task)
+
+<!-- 控制此任务被哪个节点认领。影响 .hermes-task.json 的 affinity 字段。
+     不带 cluster 时此字段无任何效果，保留无害。 -->
+
+- `any` — 任何节点可认领
+- `<hash6>` — 指定节点（推荐；跨机器同步安全）
+- `<suite-name>` — 拥有此套件的节点（如 `hermes-personal-suite`）
+- `<tag>` — 能力标签匹配（如 `gpu`, `docker`）
+- 逗号分隔 → AND 逻辑（`hermes-personal-suite,gpu` 两样都有才匹配）
+
+注意：不要用 `local`。tasks repo 同步到其他机器后，每台都会把 `local` 当成自己的任务，造成混乱。用 node_id（hash6）代替。
+
+## 环境要求
+
+| 项目 | 最低要求 | 说明 |
+|------|---------|------|
+| Python | <版本> | <说明> |
+| <依赖项> | <版本> | <说明> |
+| 磁盘 | <空闲空间> | <用途> |
+| API Key | <Key 名称> | <用途说明> |
+
+## Data Flow
+
+跨 phase 文件传递路径。phase 执行时 CWD 在自己的子目录，跨目录引用使用相对路径（`../`）。
+
+| 文件 | 来源 Phase | 被消费 Phase | 格式说明 |
+|------|-----------|-------------|---------|
+| `phase_01_<skill>/<file>` | Phase 1 | Phase N | <格式文档> |
+| `phase_02_<skill>/<file>` | Phase 2 | Phase N | <格式文档> |
+
+## Phase 目录
+
+- `phase_01_<skill>/` — <产出物说明>
+- `phase_02_<skill>/` — <产出物说明>
+- `phase_03_<skill>/` — <产出物说明>
+
+## Checklist
+
+- [ ] Phase 1 — <investigation / reading / understanding>
+- [ ] Phase 2 — <execution / writing / implementation>
+- [ ] BREAK: <optional — delete if no pause needed here>
+- [ ] Phase 3 — <verification / review / cleanup>
+
+## Tracking
+
+<!-- 可选。每个 phase 完成后需要更新的跟踪记录。
+     编排者（stratis/corvan/valros）读到本节后，自动注入到各 phase 的 card/worker brief 中。 -->
+
+加载 `task-tracker` skill，传入以下参数：
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| `task_dir` | 本 TASK.md 所在目录的绝对路径 | 让 tracker 定位任务 |
+| `phase` | 当前完成的 phase 标识 | 如 Phase 0: scrutiny-pipeline |
+| `executor` | 执行者名称 | 如 scrutaris |
+| `findings` | 关键发现（每行一条） | 从产出中提炼 3-5 条 |
+| `outputs` | 产出文件路径（相对 task_dir） | 如 output/docs/00-report.md |
+| `next` | 下一个 phase | 如 Phase 1: domain-analysis |
+
+## Notes
+
+## Related Tickets
+
+<!-- 可选。关联的 ticket。填写 ticket_id 后 task_create 会自动将 task hash 写回 ticket 的 task_id 字段。 -->
+
+| Ticket ID | 关系说明 |
+|-----------|---------|
+| `#<ticket_id>` | 创建源 / 相关事项 |
+
+## Related Tasks
+
+<!-- 可选。关联任务关系表：depends_on = 前置依赖（本任务开始前必须完成），related = 主题相关/互为参考，supersedes = 本任务替代/废弃了哪个旧任务 -->
+| 类型 | 关联 Task | 关系说明 |
+|------|----------|---------|
+| depends_on | `YYYYMMDD-HHMMSS.<name>-<hash6>/` | 本任务依赖的前置任务 |
+| related | `YYYYMMDD-HHMMSS.<name>-<hash6>/` | 主题相关、互为参考 |
+| supersedes | `YYYYMMDD-HHMMSS.<name>-<hash6>/` | 本任务替代/废弃了哪个旧任务 |

task-framework/skills/task-framework/templates/TASK_MEMORY.md

@@ -0,0 +1,27 @@
+# TASK_MEMORY.md — 任务操作记忆
+
+按时间倒序（最新在最上面）或正序（最新在最下面）追加。推荐正序，方便跨 session 顺读。
+
+## 2026-06-06 HH:MM
+
+**操作:** 做了什么
+**原因:** 为什么这么做
+**改动:** 改了什么文件/目录，具体改动
+**问题:** 遇到的问题
+**解决:** 怎么解决的
+**结果:** 最终结果
+**素材状态:** phase-dir(内容✅/⚠️/❌) ...
+**下一步:** 下次 session 要继续做什么
+
+---
+
+## 记录规范
+
+- 每个 session（或每次连续操作）写一条 `## 日期 时间` 记录
+- **操作:** 必填，一句话概括
+- **原因:** 可选，决策理由
+- **改动/问题/解决/结果:** 按需填写
+- **素材状态:** 推荐维护，快速知道什么能复用
+- **下一步:** 跨 session 必填，新 session 的起点
+- 纯命令输出不要写这里（放 `logs/`）
+- checklist 勾选不要写这里（放 `TASK.md`）