SuperAPI AI Directory

async-issue-manager

General & other

View repository

Updated 10-16 08:49

About this skill

Async Issue Manager

A purely local asynchronous task management system. Uses the file system instead of a database, Git instead of cloud services, and Agents instead of manual follow-up.

Core Philosophy

When people are offline, the Agent is still working.

你(早上): "帮我研究一下 xxx"
  ↓
Agent 自动建 Issue → 排优先级 → 打标签
  ↓
白天每小时自动调度 → 判断派给哪个 Agent
  ↓
分析师/写手/探索者/临时工 → 各自执行
  ↓
完成 → 移入 .issues/closed/ → Git commit
  ↓
你(晚上): 看 closed/ 里的结果

Directory Structure

.issues/
├── open/           # 待处理的任务
│   └── 035-研究xxx方案.md
├── in-progress/    # 正在执行的任务
│   └── 034-写教程.md
├── closed/         # 已完成的任务
│   ├── 001-修复bug.md
│   └── 002-写文档.md
└── index.json      # 索引(ID 计数器 + 全量记录)

Issue File Format

Each Issue is a Markdown file with YAML front matter:

---
id: 35
title: 研究 xxx 方案
priority: P1
labels: research, analysis
status: open
assignee: unassigned
created_at: 2026-02-21T10:00:00
updated_at: 2026-02-21T10:00:00
---

## 问题描述

具体描述任务内容...

## 期望结果

分析报告,包含方案对比...

Priority

Priority Meaning Scheduling Frequency
P0 Urgent Handle immediately
P1 Important Next scheduling cycle
P2 Normal Handle in queue
P3 Low Whenever there's time

Tags

Tags determine who the task is assigned to:

Tag Corresponding Agent Specialty
analysis, bug, performance Analyst In-depth analysis, architecture design
docs, writing Writer Chinese writing, tutorials
research, cleanup Explorer Information collection, organization
群聊, 社交 Social Agent Group chat interaction

How to Use

1. Create an Issue (CLI)

# 在 Skill 目录内运行
python3 scripts/manager.py create \
  --title "研究 Peekaboo 集成方案" \
  --body "调研 Peekaboo macOS 自动化框架,评估与 OpenClaw 的集成可能" \
  --priority P1 \
  --labels research analysis

2. Create an Issue (Agent natural language)

When the user states a task, the Agent should:

  1. Determine that this is a task that can be executed asynchronously
  2. Extract the title, priority, and tags
  3. Call manager.py create to create the Issue
  4. Confirm that creation succeeded

Example Conversation:

用户: "帮我研究一下 karry_viber 的 Accessibility Service 方案"
Agent: 已创建 Issue #36: 研究 karry_viber Accessibility Service 方案 [P1, research]

3. View Issues

# 列出所有 open Issues
python3 scripts/manager.py list --status open

# 查看单个 Issue
python3 scripts/manager.py show 35

# 按标签过滤
python3 scripts/manager.py list --labels research

4. Assign an Issue

python3 scripts/manager.py assign 35 analyst

5. Close an Issue

python3 scripts/manager.py close 35 --resolution "分析报告已生成,见 data/analysis.md"

Automation Components

Automatic Scheduling (hourly)

scripts/auto-dispatch.sh — cron runs hourly:

  1. Run the inspection system to scan for problems
  2. Broadcast all open Issues to matching Agents
  3. Trigger the main Agent to decide on work assignment

Scheduling Logic: The main Agent reads open Issues and, based on tags and priority, decides which sub-Agent to assign execution to. It is not rigid rule-based routing, but intelligent judgment.

Inspection System (twice a day)

scripts/inspector.py — Automatically discovers problems and creates Issues:

Check Item Description
not-implemented stubs Features not implemented in the code
Documentation Sync Code changed but documentation was not updated
Unused Skills Skills not modified for 30 days
MEMORY.md size Over 10KB needs trimming
Meditation Output Whether meditation was completed yesterday
Evolution Log Whether there is a record in evolution-log

Inspection finds problems → automatically creates an Issue → automatically assigns work for handling in the next scheduling cycle.

Documentation Sync Checker(extensible, refer to inspector.py 's check_docs_sync method):

  • Automatically scan all Git projects and Skills
  • Code was changed but README/SKILL.md was not updated
  • New projects are automatically included in monitoring, no manual configuration required

Broadcast system

scripts/broadcast.py — Based on the Agent subscription configuration, push the Issue to matching Agents:

# Agent 订阅配置示例
AGENT_SUBSCRIPTIONS = {
    "analyst": {
        "labels": ["bug", "performance", "analysis"],
        "priority": ["P0", "P1"]
    },
    "writer": {
        "labels": ["docs", "writing"],
        "priority": ["P1", "P2"]
    }
}

Cron configuration example

# 每小时自动调度
0 * * * * cd /workspace && bash scripts/auto-dispatch.sh

# 早晨巡查(06:30)
30 6 * * * cd /workspace && python3 scripts/inspector.py

# 晚间巡查(22:00)
0 22 * * * cd /workspace && python3 scripts/inspector.py

In OpenClaw, use the built-in cron system instead of the system crontab:

  • sessionTarget: "isolated" + payload.kind: "agentTurn" For tasks that require Agent judgment
  • sessionTarget: "main" + payload.kind: "systemEvent" For simple triggers

Git management

The entire .issues/ directory is included in Git management:

# 每小时自动 commit
git add .issues/ && git commit -m "issues: auto-update $(date +%H:%M)" && git push

Benefits:

  • Complete history is traceable (who created it, who changed it, when it was closed)
  • Does not depend on any external services (GitHub Issues, Jira, Notion)
  • Available offline, local speed
  • Multi-device sync relies on git push/pull

Applicable scenarios

Scenario Approach
Office workers Drop tasks in the morning → Agents run automatically during the day → Review results in the evening
Developers The inspection system automatically discovers bugs → creates an Issue → Agent fixes it
Content creation Create a "write tutorial" Issue → writer Agent generates a draft → human review
Research Create a "research xxx" Issue → explorer collects materials → analyst produces a report

Installation

  1. Copy the entire async-issue-manager/ directory to your workspace's skills/ directory
  2. Create the .issues/ directory structure:mkdir -p .issues/{open,in-progress,closed}
  3. Set the environment variable WORKSPACE to point to your workspace root directory (or let the script detect it automatically)
  4. Configure the cron scheduled task (refer to the Cron configuration above)
  5. Run examples/quickstart.sh to verify the installation

Notes

  • Issue IDs increase globally and will not repeat
  • The inspection system automatically deduplicates—Issues with the same title will not be created repeatedly
  • File movement (open → in-progress → closed) is handled automatically by scripts
  • index.json is the index file; do not edit it manually