Skills
skills/cristoslc/swain/execution-tracking

execution-tracking

SKILL.md

Execution Tracking

Abstraction layer for agent execution tracking. Other skills (e.g., spec-management) express intent using abstract terms; this skill translates that intent into concrete CLI commands.

Before first use: Read references/bd-cheatsheet.md for complete command syntax, flags, ID formats, and anti-patterns.

Artifact handoff protocol

This skill receives handoffs from spec-management based on a four-tier tracking model:

Tier Artifacts This skill's role
Implementation SPEC, STORY, BUG Create a tracked implementation plan and task breakdown before any code is written
Coordination EPIC, VISION, JOURNEY Do not track directly — spec-management decomposes these into children first, then hands off the children
Research SPIKE Create a tracked plan when the research is complex enough to benefit from task breakdown
Reference ADR, PERSONA, RUNBOOK No tracking expected

If invoked directly on a coordination-tier artifact (EPIC, VISION, JOURNEY) without prior decomposition, defer to spec-management to create child SPECs or STORYs first, then create plans for those children.

Term mapping

Other skills use these abstract terms. This skill maps them to the current backend (bd):

Abstract term Meaning bd command
implementation plan Top-level container grouping all tasks for a spec artifact bd create "Title" -t epic --external-ref <SPEC-ID> --json
task An individual unit of work within a plan bd create "Title" -t task --parent <epic-id> --json
origin ref Immutable link from a plan to the spec that seeded it --external-ref <ID> flag on epic creation
spec tag Mutable label linking a task to every spec it affects --labels spec:<ID> on create, --add-label spec:<ID> on update
dependency Ordering constraint between tasks bd dep add <child> <parent> (child depends on parent)
ready work Unblocked tasks available for pickup bd ready --json (NOT bd list --ready)
claim Atomically take ownership of a task bd update <id> --claim --json
complete Mark a task as done bd close <id> --reason "..."
abandon Close a task that will not be completed bd close <id> --reason "Abandoned: <why>" --json
escalate Abandon + invoke spec-management to update upstream artifacts Abandon, then invoke spec-management skill

Configuration

The skill stores persistent project-level configuration in .agents/execution-tracking.vars.json. This file is created on first run and checked on every subsequent invocation.

First-run setup

If .agents/execution-tracking.vars.json does not exist, create it by asking the user the questions below (use sensible defaults if the user says "just use defaults"):

Key Type Default Question
use_dolt boolean false "Should bd use Dolt for remote sync? (Requires a running Dolt server)"
auto_prime boolean true "Run bd prime automatically on bootstrap to load workflow context?"
fallback_format "jsonl" | "markdown" "jsonl" "If bd is unavailable, use JSONL or Markdown for the fallback ledger?"

Write the file as pretty-printed JSON:

{
  "use_dolt": false,
  "auto_prime": true,
  "fallback_format": "jsonl"
}

On subsequent runs, read the file and apply its values — don't re-ask.

Applying config

  • use_dolt: When false, skip all bd dolt * commands (start, stop, push, pull). When true, run bd dolt start during bootstrap and bd dolt push at session end.
  • auto_prime: When true, run bd prime at bootstrap step 7. When false, skip it.
  • fallback_format: Controls the format used by the Fallback section.

Bootstrap workflow

  1. Load config: Read .agents/execution-tracking.vars.json. If missing, run first-run setup above.
  2. Check availability: command -v bd
  3. If missing, install:
    • macOS: brew install beads
    • Linux: cargo install beads
    • If install fails, go to Fallback.
  4. Check for existing database: look for .beads/ directory.
  5. If no .beads/, initialize: bd init.
  6. Validate: bd doctor --json. If errors, try bd doctor --fix.
  7. If use_dolt is true: start the Dolt server with bd dolt start.
  8. If git status shows modified .beads/dolt-*.pid or .beads/dolt-server.activity: these are ephemeral runtime files that were tracked by mistake. See .beads/README.md § "Remediation: Untrack Ephemeral Runtime Files" for the fix.
  9. If auto_prime is true: bd prime for dynamic workflow context.

Statuses

bd accepts exactly four status values: open, in_progress, blocked, closed. It rejects aliases like todo or done. See the cheatsheet for the full status table and valid values.

To express abandonment, use bd close <id> --reason "Abandoned: ..." — see Escalation.

Operating rules

  1. Always use --json on create/update/close — bd's human-readable output varies between versions, but JSON is stable and machine-parseable. Capture issue IDs from the JSON response so subsequent commands can reference them reliably.
  2. Always include --description when creating issues — a title alone loses the "why" behind a task. Future agents (or your future self) picking up this work need enough context to act without re-researching.
  3. Create/update tasks at the start of work, after each major milestone, and before final response — this keeps the external tracker useful as a live dashboard rather than a post-hoc record.
  4. Keep task titles short and action-oriented — they appear in bd ready output, tree views, and notifications where space is limited.
  5. Store handoff notes in task notes (--notes or --append-notes) rather than ephemeral chat context — chat history is lost between sessions, but task notes persist and are visible to any agent or observer.
  6. Include references to related artifact IDs in labels (e.g., spec:SPEC-003) — this makes it possible to query all work touching a given spec with bd list -l spec:SPEC-003.
  7. Never use bd edit — it opens $EDITOR (vim/nano) which blocks agents. Use bd update with inline flags instead.
  8. Prefix abandonment reasons with Abandoned: when closing incomplete tasks — this convention makes abandoned work queryable (bd search "Abandoned:") so nothing silently disappears.

Spec lineage tagging

When creating tasks that implement a spec artifact:

# Create epic with immutable origin ref
bd create "Implement auth" -t epic --external-ref SPEC-003 --json

# Create child tasks with spec label
bd create "Add JWT middleware" -t task \
  --parent <epic-id> --labels spec:SPEC-003 --json

# Add cross-spec impact later
bd update <task-id> --add-label spec:SPEC-007

# Query all work for a spec
bd list -l spec:SPEC-003

# Bidirectional link between tasks in different plans
bd dep relate <task-a> <task-b>

Escalation

When work cannot proceed as designed, use this protocol to abandon tasks and flow control back to spec-management for upstream changes before re-planning.

Triage table

Scope Situation Action
Single task Alternative approach exists Abandon task, create replacement under same plan
Single task Spec assumption is wrong Abandon task, invoke spec-management to update SPEC, create replacement task
Multiple tasks Direction change needed Abandon affected tasks, create ADR + update SPEC via spec-management, seed new tasks
Entire plan Fundamental rethink required Abandon all tasks, abandon SPEC (and possibly EPIC) via spec-management, create new SPEC if needed

Abandoning tasks

# Single task
bd close <id> --reason "Abandoned: <why>" --json

# Batch — close all open tasks under an epic
for id in $(bd list --parent <epic-id> --status=open --json | jq -r '.[].id'); do
  bd close "$id" --reason "Abandoned: <why>" --json
done

# Preserve in-progress notes before closing
bd update <id> --append-notes "Abandoning: <context about partial work>"
bd close <id> --reason "Abandoned: <why>" --json

Escalation workflow

  1. Record the blocker. Append notes to the plan epic explaining why work cannot proceed:

    bd update <epic-id> --append-notes "Blocked: <description of blocker>"

  2. Invoke spec-management. Choose the appropriate scope:

    • Spec tweak — update the SPEC's assumptions or requirements, then return here.
    • Design pivot — create an ADR documenting the decision change, update affected SPECs, then return here.
    • Full abandon — transition the SPEC (and possibly EPIC) to Abandoned phase via spec-management.

  3. Seed replacement plan from the updated spec. Create a new implementation plan linked to the same (or new) SPEC via origin ref:

    bd create "Implement <updated approach>" -t epic --external-ref <SPEC-ID> --json

  4. Link lineage. Preserve traceability between abandoned and replacement work:

    • Use the same spec:<SPEC-ID> labels on new tasks.
    • Reference abandoned task IDs in the new epic's description or notes: 
      bd update <new-epic-id> --append-notes "Replaces abandoned tasks: <old-id-1>, <old-id-2>"

Cross-spec escalation

When abandoned tasks carry multiple spec: labels, each referenced spec may need upstream changes. Check every spec label on the abandoned tasks and invoke spec-management for each affected spec before re-planning.

# List spec labels on an abandoned task
bd show <id> --json | jq -r '.labels[]' | grep '^spec:'

"What's next?" flow

When asked what to work on next, show ready work from the execution backend:

# Check for bd availability and initialization
command -v bd && [ -d .beads ]

# Show unblocked tasks (blocker-aware)
bd ready --json

# If there are in-progress tasks, show those too
bd list --status=in_progress --json

If bd is initialized and has tasks, present the results. If bd is not initialized or has no tasks, report that and defer to the spec-management skill's specgraph.sh next for artifact-level guidance.

When invoked from the spec-management skill's combined "what's next?" flow, this skill provides the task layer — concrete claimable work items — complementing the spec layer's artifact-level readiness view.

Observer pattern expectations

  1. Maintain compact current-status view: bd status and bd list --pretty.
  2. Ensure blockers are explicit: bd blocked shows issues with unsatisfied deps.
  3. Use consistent labels so supervisors can filter by stream, owner, or phase.

Plan ingestion (superpowers integration)

When a superpowers plan file exists (produced by the writing-plans skill), use the ingestion script instead of manually decomposing tasks. The script parses the plan's ### Task N: blocks and registers them in bd with full spec lineage.

Script location: scripts/ingest-plan.py (relative to this skill)

When to use

  • A superpowers plan file exists at docs/plans/YYYY-MM-DD-<name>.md
  • The plan follows the writing-plans format (header + ### Task N: blocks)
  • You have an origin-ref artifact ID to link the plan to

Usage

# Parse and register in bd
python3 scripts/ingest-plan.py <plan-file> <origin-ref>

# Parse only (preview without creating bd tasks)
python3 scripts/ingest-plan.py <plan-file> <origin-ref> --dry-run

# With additional labels
python3 scripts/ingest-plan.py <plan-file> <origin-ref> --labels epic:EPIC-009

What it does

  1. Parses the plan header (title, goal, architecture, tech stack)
  2. Splits on ### Task N: boundaries
  3. Creates a bd epic with --external-ref <origin-ref>
  4. Creates child tasks with --labels spec:<origin-ref> and full task body as description
  5. Wires sequential dependencies (Task N+1 depends on Task N)

When NOT to use

  • The plan file doesn't follow superpowers format — fall back to manual task breakdown
  • You need non-sequential dependencies — use the script, then adjust deps manually with bd dep add
  • The plan is very short (1-2 tasks) — manual creation is faster

Fallback

If bd cannot be installed or is unavailable:

  1. Log the failure reason.
  2. Fall back to a neutral text task ledger (JSONL or Markdown checklist) in the working directory.
  3. Use the same status model (open, in_progress, blocked, closed) and keep updates externally visible.
Weekly Installs
4
Repository
cristoslc/swain
First Seen
9 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
opencode4
gemini-cli4
github-copilot4
codex4
kimi-cli4
cursor4