ralph-loop-gen

Ralph Loop Gen Skill

Task Management System Template Generator - Generates a complete task management structure template based on user input or JSON configuration.

⚠️ Note: This skill only generates task template files and is not responsible for actually executing tasks. During execution, other agents need to manually or automatically read these template files.

Usage

Method 1: Command-line interactive input

# 基本用法
bun ~/.pi/agent/skills/ralph-loop-gen/lib.ts

# 指定任务集名称
bun ~/.pi/agent/skills/ralph-loop-gen/lib.ts --name myProject

# 指定项目名称
bun ~/.pi/agent/skills/ralph-loop-gen/lib.ts --name myProject --project "我的项目"

Specify output directory

bun ~/.pi/agent/skills/ralph-loop-gen/lib.ts --name myProject --output ./task

### 方式 2: Python 脚本生成（推荐）

```bash
# 使用 Python 脚本从 JSON 生成任务
python3 ~/.pi/agent/skills/ralph-loop-gen/generate.py --config /path/to/tasks.json

# 指定输出目录
python3 ~/.pi/agent/skills/ralph-loop-gen/generate.py --config tasks.json --output ./task

Input format

Format 1: Simple list (interactive input)

任务1: 初始化项目结构
任务2: 安装依赖 -> 依赖: 任务1
任务3: 配置开发环境 -> 依赖: 任务2
任务4: 编写UI组件 (High, 4h) -> 依赖: 任务2
任务5: 编写API接口 (High, 4h) -> 依赖: 任务3
任务6: 集成测试 -> 依赖: 任务4, 任务5

Format 2: JSON configuration (Python script)

{
  "taskSetName": "codmate-perf",
  "projectName": "CodMate 性能优化",
  "outputDir": "./task",
  "goals": [
    {"metric": "List 滚动 FPS", "before": "~30", "target": "60+", "improvement": "100%"},
    {"metric": "CPU 占用（空闲）", "before": "~15%", "target": "<5%", "improvement": "67%"}
  ],
  "tasks": [
    {
      "id": "001",
      "title": "建立性能基准测试",
      "priority": "High",
      "estimated": "3h",
      "description": "建立性能基准测试框架，用于量化优化效果",
      "steps": [
        "安装和配置 Instruments Time Profiler",
        "创建性能测试数据集（1000+ 会话）",
        "建立基准测试脚本（滚动、搜索、加载）",
        "记录当前性能指标（FPS、CPU、内存、响应时间）",
        "创建性能回归测试用例"
      ],
      "dependencies": [],
      "acceptance": [
        "性能测试脚本可运行",
        "基准数据已记录到 docs/performance-baseline.md",
        "测试数据集已创建"
      ]
    },
    {
      "id": "002",
      "title": "替换 SessionListColumnView 的 List 为 LazyVStack",
      "priority": "High",
      "estimated": "2h",
      "description": "将 SessionListColumnView 中的 List 组件替换为 LazyVStack，提升滚动性能",
      "steps": [
        "备份当前 SessionListColumnView.swift",
        "将 List + ForEach 替换为 ScrollView + LazyVStack",
        "保留 selection 绑定功能",
        "保留 Section header 功能",
        "保留 contextMenu 功能",
        "运行性能测试对比",
        "回归测试：选择、拖拽、右键菜单"
      ],
      "dependencies": ["001"],
      "acceptance": [
        "滚动 FPS 达到 60+（基准数据对比）",
        "选择功能正常",
        "拖拽功能正常",
        "右键菜单功能正常"
      ]
    }
  ]
}

Output structure

Generate the following directory structure:

task/
└── {任务集名}/
    ├── 任务索引.md          # 任务总览、依赖关系、执行计划
    ├── 当前任务.md          # 当前待执行任务（指向第一个任务）
    ├── 任务001.md
    ├── 任务002.md
    ├── 任务003.md
    └── completed/           # 已完成任务目录

Template files

Template files are located in the templates/ directory:

• templates/index.md - Task index template
• templates/task.md - Single task template

Templates use {{占位符}} syntax, and lib.ts/generate.py will replace them automatically.

index.md template variables

• {{TOTAL_TASKS}} - Total number of tasks
• {{COMPLETED}} - Number completed
• {{IN_PROGRESS}} - Number in progress
• {{TODO}} - Number not started
• {{LOCKED}} - Number locked
• {{PROJECT_NAME}} - Project name
• {{CREATED_TIME}} - Creation time
• {{TASK_ROWS}} - Task list table rows
• {{DEP_GRAPH}} - Dependency graph
• {{PARALLEL_GROUPS}} - Parallel task grouping
• {{PROGRESS_PERCENT}} - Progress percentage
• {{ELAPSED_TIME}} - Elapsed time
• {{ESTIMATED_REMAINING}} - Estimated remaining time
• {{GOALS_TABLE}} - Project/performance target table (optional)
• {{EXECUTION_PLAN}} - Execution plan (optional)

task.md template variables

• {{TASK_ID}} - Task ID (e.g., Task 001)
• {{TASK_TITLE}} - Task title
• {{STATUS}} - Task status
• {{PRIORITY}} - Priority
• {{ESTIMATED_TIME}} - Estimated time
• {{DESCRIPTION}} - Task description
• {{DEPENDENCIES_LIST}} - Dependency task list
• {{ACCEPTANCE_CRITERIA}} - Acceptance criteria
• {{IMPLEMENTATION_STEPS}} - Implementation steps
• {{PARALLEL_HINT}} - Parallel hints
• {{LOCK_OWNER}} - Occupant
• {{LOCK_TIME}} - Lock time
• {{LOCK_TIMEOUT}} - Lock timeout

---

Multi-Agent Parallel Development Guide

Dependency definition

Specify dependencies in the task list:

任务1: 基础设施 (无依赖)
任务2: 前端开发 -> 依赖: 任务1
任务3: 后端开发 -> 依赖: 任务1
任务4: 集成测试 -> 依赖: 任务2, 任务3

Identify parallelizable tasks

Rule: If two tasks depend on the same task and do not depend on each other, they can be parallelized.

Example：

• Task 2 depends on Task 1
• Task 3 depends on Task 1
• ✅ Task 2 and Task 3 can be parallelized

Manual scheduling strategy

Strategy 1: Execute by batch

批次 1: 任务1 (所有 Agent 等待)
批次 2: 任务2 (Agent A) + 任务3 (Agent B) 并行
批次 3: 任务4 (等待批次2完成)

Strategy 2: Pipeline execution

Agent A: 任务1 → 任务2 → 任务4
Agent B: 任务1 → 任务3 → 任务5

Strategy 3: Task pool mode

1. 将所有无依赖任务放入"待执行池"
2. 各 Agent 从池中取任务
3. 任务完成后，将依赖此任务的其他任务放入池
4. 重复直到所有任务完成

Conflict avoidance

File-level conflicts：

• Different Agents modifying the same file → manual coordination, or split the task
• Suggestion: clearly specify the files involved in the task description

Branch management suggestions：

# 每个 Agent 使用独立分支
git checkout -b agent-a/task2
git checkout -b agent-b/task3

# 完成后合并到主分支
git checkout main
git merge agent-a/task2
git merge agent-b/task3

Progress tracking

Check periodically task/{任务集名}/任务索引.md：

1. Check whether all dependency tasks have been completed
2. Update task status
3. Identify the next executable task

Task locking mechanism

Locking rules

1. Lock immediately when claiming a task

   # Agent A 领用任务002
   # 更新任务002.md
   状态: Locked → In Progress
   占用者: Agent A
   锁定时间: 2025-01-20 14:30:00
   

2. Simultaneously update the task index

   | 002 | 任务标题 | Locked | ... | ... | Agent A | 14:30:00 |
   

3. Lock timeout release

   • Default lock duration: estimated time × 2
   • Automatically released after timeout; other Agents can claim it
   • The lock timeout can be adjusted in the task file

4. Unlock conditions

   • Task completed → status updated to Done, moved to completed/ directory
   • Blocked → status updated to Blocked, release lock
   • Timeout → automatically released
   • Manual release: Agent proactively gives up

Lock state transitions

Todo → Locked → In Progress → Done → [移至 completed/]
  ↓        ↓
Blocked  超时释放

Blocking handling

When a task is blocked：

1. Record the blocking reason

   ## 阻塞原因
   - 等待任务003完成（状态：In Progress）
   - 等待API密钥审批
   - 技术问题：需要解决XXX
   

2. Update status

   • Status:In Progress → Blocked
   • Release lock (clear occupant)

3. Agent choice

   • Wait for the blocking to be resolved (recommended)
   • Claim another executable task

After the blocking is resolved：

1. Check whether all dependencies are complete
2. Re-lock the task
3. Continue execution

Multi-Agent collaboration workflow

# Agent A 开始工作
1. 读取 task/{任务集名}/任务索引.md
2. 查找状态为 Todo 的任务
3. 检查依赖任务是否都为 Done
4. 锁定任务（更新状态为 Locked，记录占用者）
5. 更新任务索引
6. 开始执行

# Agent B 同时开始工作
1. 读取 task/{任务集名}/任务索引.md
2. 查找状态为 Todo 的任务
3. 发现任务002已被 Agent A 锁定
4. 寻找下一个可执行任务
5. 锁定任务003
6. 开始执行

# 任务阻塞处理
1. Agent A 发现任务004被阻塞
2. 记录阻塞原因
3. 更新状态为 Blocked
4. 释放锁定
5. 查找其他可执行任务

Example: 3-Agent parallel development

任务列表：
001: 初始化项目 (无依赖)
002: 设计数据库 (依赖 001)
003: 设计 API (依赖 001)
004: 实现 API 接口 (依赖 003)
005: 实现前端页面 (依赖 003)
006: 编写单元测试 (依赖 004, 005)
007: 集成测试 (依赖 006)

调度方案：
阶段 1:
  - Agent A: 任务001 (3h)

阶段 2:
  - Agent A: 任务002 (2h)
  - Agent B: 任务003 (2h)

阶段 3:
  - Agent A: 任务004 (2h)
  - Agent B: 任务005 (2h)
  - Agent C: 等待

阶段 4:
  - Agent A: 任务006 (2h)
  - Agent B: 等待
  - Agent C: 等待

阶段 5:
  - Agent A: 任务007 (2h)

总耗时: ~11h (3 Agent 并行)

Best practices

1. Moderate task granularity: too large affects parallelism, too small increases coordination cost
2. Explicit dependencies: avoid implicit dependencies
3. Update status promptly: make it easy for other Agents to determine whether they can start
4. Synchronize regularly: each Agent reports progress periodically
5. Reserve buffer: consider that tasks may time out

---

Advanced features

Automatic batch grouping

The system automatically identifies parallelizable batches based on dependencies and displays them in the task index:

### 批次 1（可立即执行）
- 任务001: 建立性能基准测试 (Agent A)  ✅ 可并行执行

### 批次 2（等待批次1完成）
- 任务002: 替换 List 为 LazyVStack (Agent A)  ✅ 可并行执行
- 任务003: 优化动画性能 (Agent B)  ✅ 可并行执行
- 任务004: 搜索 debounce (Agent B)  ✅ 可并行执行

Execution plan generation

The system generates an execution plan based on task dependencies and estimated times:

## 执行计划（3 Agent 并行）

阶段 1: Agent A (3h)
└── 任务001: 建立性能基准测试

阶段 2: (3h)
├── Agent A: 任务002 (2h) + 等待 (1h)
├── Agent B: 任务003 (2h) + 等待 (1h)
└── Agent C: 任务004 (1.5h) + 任务005 (1.5h)

总耗时: ~18 小时（3 Agent 并行）

Goal tracking

Supports adding a project goals table to the task index:

## 性能优化目标

| 指标 | 优化前 | 目标 | 测量方法 |
|------|--------|------|----------|
| List 滚动 FPS | ~30 | 60+ | Instruments GPU/CPU |
| CPU 占用（空闲） | ~15% | <5% | Activity Monitor |

---

Quick start

1. Create a task configuration file

# 创建 tasks.json
cat > tasks.json << 'EOF'
{
  "taskSetName": "my-project",
  "projectName": "我的项目",
  "outputDir": "./task",
  "tasks": [
    {
      "id": "001",
      "title": "初始化项目",
      "priority": "High",
      "estimated": "2h",
      "description": "初始化项目基础结构",
      "steps": [
        "创建项目目录",
        "初始化 Git",
        "创建 README"
      ],
      "dependencies": [],
      "acceptance": [
        "项目目录创建完成",
        "Git 仓库初始化完成",
        "README 文件创建完成"
      ]
    }
  ]
}
EOF

2. Generate a task template

# 使用 Python 脚本生成
python3 ~/.pi/agent/skills/ralph-loop-gen/generate.py --config tasks.json

3. View the generated tasks

# 查看任务索引
cat task/my-project/任务索引.md

# 查看当前任务
cat task/my-project/当前任务.md

4. Start execution

# 编辑任务文件，更新状态
vim task/my-project/任务001.md

# 更新状态: Todo → Locked → In Progress
# 填写占用者和锁定时间
# 按照实施步骤执行

---

Experience summary

Task design principles

1. Single responsibility: each task does only one thing
2. Verifiable: has clear acceptance criteria
3. Estimable: has a reasonable estimated time
4. Parallelizable: minimize the depth of the dependency chain as much as possible

Dependency relationship design

1. Avoid circular dependencies: ensure the dependency graph is a DAG
2. Minimize dependencies: depend only on necessary tasks
3. Explicit dependencies: explain in the task description why the dependency exists
4. Test dependencies: ensure that after the dependency task is completed, the current task can start immediately

Acceptance criteria design

1. Quantifiable: use measurable indicators
2. Testable: can be verified through tests
3. Complete coverage: covers all key functions
4. User-visible: focus on the effects users can perceive