beads-integration

The Beads Integration skill enables persistent task management for complex software projects by bridging Claude Code sessions with the Beads task tracking system. It is designed for engineers working on long-running projects, complex feature developments, or tasks that span multiple AI coding sessions, ensuring that context, dependencies, and progress are never lost when session limits or context windows are reached. By maintaining a persistent task graph, this skill allows the agent to maintain high-level awareness of project scope while managing fine-grained implementation details.

• Persistent memory: Enables task states, dependencies, and discovery notes to survive across session restarts and context compaction.

• Pivotal-style workflow: Orchestrates epics, stories, and bug tracking using clear status transitions (todo, in-progress, done) and dependency management.

• Bidirectional sync: Automatically synchronizes between local project documentation (tasks.md) and the Beads database, ensuring the source of truth remains consistent.

• Context priming: Automatically loads the project task graph via SessionStart and PreCompact hooks, ensuring the agent is always 'task-aware' upon entry or re-entry.

• Discovery tracking: Records technical insights, edge cases, and design decisions directly into task notes for future reference and architectural integrity.

• Intended for developers utilizing the Spec Kit framework who require robust tracking for multi-day or multi-week implementation tasks.

• Automatically invoked when discussing long-running work, project tracking, or when state persistence is required across session boundaries.

• Requires local installation of Beads (bd CLI) and proper configuration of .claude/hooks within the project repository.

• Provides commands for task initialization, priming, listing, and state updates to ensure seamless handoffs between human developers and the agent.

• Constraints: Primarily functions within the Claude Code CLI environment; relies on project-specific tasks.md files for task tracking alignment.