# External Task Management

> Use an external task-management CLI as the source of truth for agent execution tracking (instead of built-in todos), including bootstrap/install flow, status-transition rules, and observer-friendly reporting. Use for tasks that require backend portability, persistent progress across agent runtimes, or external supervision.

- Skill: `cristoslc/external-task-management` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add cristoslc/external-task-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cristoslc/external-task-management/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: UNLICENSED
- Author: cristoslc (https://skillmd.com/u/cristoslc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cristoslc/external-task-management

---


# External Task Management

Prefer external task CLI tracking over built-in todo systems.

## Default workflow (current default: `bd`)
1. Check for `bd` availability:
   - `command -v bd`
2. If missing, install `bd`:
   - macOS (Homebrew): `brew install beads`
   - Linux (Cargo): `cargo install beads`
3. Initialize and validate:
   - `bd --help`
   - `bd ready`
4. Track every meaningful work item with `bd` records.

## Canonical task states
Use this logical mapping even if the CLI uses different labels:
- `todo`: identified, not started
- `in_progress`: actively being worked
- `blocked`: cannot proceed due to dependency
- `done`: completed and verified

## Operating rules
1. Create/update external tasks at the start of work, after each major milestone, and before final response.
2. Keep task titles short and action-oriented.
3. Store handoff notes in the task entry rather than ephemeral chat context when possible.
4. Include references to related artifact IDs in task notes. Valid prefixes: `VISION-NNN`, `EPIC-NNN`, `PRD-NNN`, `SPIKE-NNN`, `ADR-NNN`.

## Spec lineage tagging (bd-specific)
When creating `bd` tasks that implement a spec artifact:
- Tag the origin spec with `--external-ref <ID>` (e.g., `--external-ref PRD-003`). This is immutable — it records which spec seeded the work.
- Tag all tasks with `spec:<ID>` labels (e.g., `--labels spec:PRD-003`). These are mutable — add labels as cross-spec impact is discovered.
- When a task affects multiple specs, add additional labels: `bd label add <task-id> spec:PRD-007`.
- Use `bd dep relate` for bidirectional links between tasks in different plans.
- Query all work for a spec with: `bd list --label spec:PRD-003`.

## Observer pattern expectations
1. Maintain a compact current-status view that can be queried externally.
2. Ensure blockers are explicit and include required next action.
3. Use consistent tags/labels so supervisors can filter by stream, owner, or phase.

## Failure and fallback
If `bd` cannot be installed or is unavailable in the environment:
1. Log the failure reason in your work notes.
2. Fall back to a neutral text task ledger (JSONL or Markdown checklist) in the working directory.
3. Continue the same canonical state model and keep updates externally visible.
4. Mark that this fallback should be replaced once a preferred CLI is selected by SPIKE-001.

## Pending decision
The default CLI may change after `SPIKE-001 External Task CLI Evaluation`. Update this skill when the spike completes.