Checklist

Collaborative task checklist manager for AI agents with sequential, parallel, and looping execution. Features agent coordination, dependencies, deadlock prev...

Security Scan

The skill appears to implement a local checklist CLI as described, but there are mismatches (an undeclared dependency on jq and no install/wrapper for the 'checklist' command) and it writes to the user's home directory, so review and test in isolation before using.

Purpose & Capability

The files and SKILL.md align with a local checklist/agent coordination tool (templates, checklist.sh, commands like create/claim/depend). However the shipped script relies heavily on the jq binary (JSON processing) but the skill's metadata/requirements do not declare jq as required. Also the SKILL.md expects a 'checklist' CLI command while the code provides scripts/checklist.sh with no install script or instructions to place it on PATH — this is an incoherence between claimed UX and provided artifacts.

Instruction Scope

The instructions and examples are scoped to creating and running checklists and include expected safety checks (deadlock, loop limits). They also assume running local CLI commands that will read/write files under the user's home (~/.checklist). Reading/writing user files is expected for this purpose, but the SKILL.md is vague about how the CLI is made available and therefore grants broad discretion to run commands in the user's environment (create/modify files in HOME).

Install Mechanism

There is no install specification despite a sizable executable script being included. That means the skill bundle contains code that could be executed, but there are no documented or automated steps to install or register the 'checklist' command. This discrepancy raises friction and risk: users/agents might attempt to run 'checklist' but it won't exist, or they may run the script directly without proper review. Also, the script will copy templates into ~/.checklist on first run (writing to disk).

Credentials

The skill does not request environment variables, credentials, or external service tokens. Its file access is limited to the user's home directory (~/.checklist) and included template files. No network endpoints, secret exfiltration, or unrelated credentials are requested by the skill artifacts.

Persistence & Privilege

The skill does persist state to ~/.checklist and creates files (agents.json, active checklists, templates). It does not request elevated privileges, is not always-enabled, and does not modify system-wide or other skills' configuration. Writing to the user's home directory is expected for a local CLI but is a persistence action users should be aware of.

What to consider before installing

What to consider before installing: - The code implements a local CLI (scripts/checklist.sh) and will create ~/.checklist and write templates there on first run — expect persistent files in your home directory. - The script depends on the jq binary (used throughout) but the skill metadata doesn't list jq as a required binary; install jq or inspect/modify the script before running. - SKILL.md shows commands like 'checklist run' but the bundle does not include an installer or a wrapper that puts checklist in PATH — decide how you'll install or run scripts/checklist.sh (and review it) before executing. - There are no network calls or credentials in the examined files, but review the remainder of the script (the truncated portion) before running to confirm no unexpected network or exec behavior. - If you want lower risk, review the script content, run it in an isolated environment (VM/container), and ensure jq is from a trusted package source. If you plan to allow autonomous agent invocation, understand the agent could execute local commands that modify files under your home directory.

Collaborative task checklist manager for AI agents with advanced execution modes.

---

🎯 When to Use

Use this skill when:

• Multi-agent collaboration - Multiple AI agents need to coordinate
• Sequential tasks - Steps must execute in order
• Parallel tasks - Steps can run simultaneously
• Looping workflows - Repeat until condition is met
• Complex coordination - Avoid deadlocks and infinite loops

---

🌐 Execution Modes

1. Sequential (串行)

Steps execute one after another:

A → B → C → D

2. Parallel (并行)

Steps execute simultaneously:

A
B ← Branch together
C

3. Loop (循环)

Repeat until exit condition:

while condition:
    A → B
    if exit_condition:
        break

---

⚡ Quick Commands

Execution Control

# Set execution mode
checklist mode sequential   # 串行
checklist mode parallel    # 并行
checklist mode loop       # 循环

# Configure loop
checklist loop set 5                 # Set max 5 iterations
checklist loop condition "<expr>"   # Set exit condition
checklist loop count                 # Show current loop count

# Run checklist
checklist run                        # Execute with current mode
checklist run --dry-run             # Preview without executing

# Safety
checklist check                      # Check for deadlocks
checklist validate                   # Validate entire workflow

Agent Commands

checklist agent register <name>
checklist agent use <name>
checklist assign <item> <agent>
checklist claim
checklist status

Task Commands

checklist create <template>
checklist done <item>
checklist depend <item> <dep>
checklist tree

---

🔄 Execution Modes Detail

Sequential Mode

✅ Sequential: Items execute in order
   1 → 2 → 3 → 4 → 5

✅ Item 3 can only start after Item 2 completes

Parallel Mode

✅ Parallel: Items in same "group" run together
   Group 1: [1, 2] (parallel)
         ↓
   Group 2: [3, 4] (parallel)
         ↓
   Group 3: [5] (final)

Loop Mode

✅ Loop: Repeat until exit condition

Loop Config:
  - Max iterations: 5 (default, configurable)
  - Exit conditions:
    - All items done
    - Custom condition met
    - Manual break

Loop Example:
  Iteration 1: [1, 2, 3] → Check exit → Continue
  Iteration 2: [1, 2, 3] → Check exit → Continue
  Iteration 3: [1, 2, 3] → Exit condition met → Stop

---

🛡️ Safety Features

1. Loop Protection

# Default: Max 5 iterations
checklist loop set 5

# After 5 loops, automatically exits
# Even if not all items complete

2. Exit Conditions

# Exit when specific item done
checklist loop condition "item.5.done == true"

# Exit when all required items done
checklist loop condition "all_required_done"

# Exit when iteration count reached
checklist loop condition "count >= 5"

3. Deadlock Prevention

# Check for potential deadlocks
checklist check

🔍 Deadlock Detection:
   - Circular dependencies: NONE
   - Unreachable items: NONE
   - Agent conflicts: NONE
   ✅ Workflow is safe to execute

4. Validation

# Validate entire workflow
checklist validate

🔍 Validation:
   - All items have valid references: ✅
   - No circular dependencies: ✅
   - Agents assigned: 3/15
   - Max loop iterations: 5
   - Exit condition: defined
   ✅ Checklist is valid

---

📋 Usage Examples

Example 1: Sequential Deployment

User: Deploy app sequentially

AI: [Execute: checklist create deploy]
[Execute: checklist mode sequential]

✅ Mode: Sequential

Execution Order:
  ⏳ 1. Run tests
  ⏳ 2. Build
  ⏳ 3. Deploy to staging
  ⏳ 4. Verify
  ⏳ 5. Deploy to prod

Example 2: Parallel Testing

User: Run tests in parallel

AI: [Execute: checklist create test-suite]
[Execute: checklist mode parallel]

✅ Mode: Parallel

Parallel Groups:
  Group 1 (concurrent):
    🔄 Unit tests
    🔄 Integration tests  
    🔄 Lint checks
    ↓ All complete →
  Group 2:
    ✅ Generate report

Example 3: Loop with Exit

User: Poll API until successful, max 5 times

AI: [Execute: checklist create api-poll]
[Execute: checklist mode loop]
[Execute: checklist loop set 5]
[Execute: checklist loop condition "item.3.done == true"]

Loop Config:
  - Max iterations: 5
  - Exit: item #3 (API success)
  - Current: 0/5

Iteration 1:
  ⏳ 1. Send request
  ⏳ 2. Check response
  ⏳ 3. Verify success
  → Not done, continue...

Iteration 3:
  ⏳ 1. Send request
  ⏳ 2. Check response
  ✅ 3. Verify success ← Exit condition met!
  
🔄 Loop exited at iteration 3
✅ Exit condition satisfied

Example 4: Deadlock Prevention

User: Create conflicting dependencies

AI: [Execute: checklist add "Task A"]
[Execute: checklist add "Task B"]
[Execute: checklist depend 1 2]
[Execute: checklist depend 2 1]

[Execute: checklist check]

🔍 Deadlock Detection:
   ⚠️  WARNING: Circular dependency detected!
   
   1 → 2 → 1
   
   Resolution suggestions:
   - Remove one dependency
   - Merge into single item
   
✅ Checklist NOT safe - fix before running

---

🔧 Implementation

Loop State

{
  "loop": {
    "enabled": true,
    "mode": "sequential|parallel|loop",
    "max_iterations": 5,
    "current_iteration": 0,
    "exit_condition": "item.3.done == true",
    "exit_reason": "condition_met|max_reached|manual"
  }
}

Safety Checks

Before Execution:
1. Validate all references ✓
2. Check circular dependencies ✓
3. Verify agents available ✓
4. Check loop config ✓
5. Confirm exit condition ✓

During Execution:
- Monitor for infinite loops
- Track iteration count
- Check exit conditions

After Execution:
- Final validation
- Generate completion report

---

🎯 Best Practices

1. Always Set Exit Conditions

# Good
checklist loop condition "item.success.done == true"

# With timeout
checklist loop set 10

2. Use Sequential for Dependent Tasks

checklist mode sequential
checklist depend 2 1
checklist depend 3 2

3. Use Parallel for Independent Tasks

checklist mode parallel
# Items in same group run together

4. Check Before Running

checklist check   # Deadlock check
checklist validate   # Full validation

5. Monitor Loop Count

checklist loop count   # Show current iteration

---

⚠️ Important Notes

Loop Safety

Scenario	Behavior
No exit condition	Uses max_iterations (default: 5)
Exit condition never met	Stops at max_iterations
Deadlock detected	Blocks execution, shows warning
Circular dependency	Prevents running, suggests fix

Maximum Limits

Limit	Default	Max
Loop iterations	5	100
Parallel items	10	50
Total items	100	500

---

🦞 Summary

One line: Complex task → Choose mode (sequential/parallel/loop) → Set safety limits → Run with confidence → Automatic exit

---