Org Planning Skill

Version: 1.1.0 Compiler: skill-compiler/1.0.0 Last Updated: 2026-01-23

Agent-accessible project planning via org-mode with hierarchical structures, task dependencies, programmatic queries, and integration with beads execution layer.

When to Activate

Use this skill when:

• Planning a project or querying task status
• Checking if tasks are blocked by dependencies
• Listing next actions or updating task states
• Managing task dependencies via org-edna
• Delegating tasks to beads execution layer
• Checking status of delegated tasks
• Working with the planning/ directory
• Interacting with org-mode files programmatically

Core Principles

1. Use org-todo for State Changes

Always use (org-todo STATE) to change task states, never direct property manipulation.

org-edna triggers only fire through org-todo; direct property manipulation bypasses the dependency cascade system entirely.

2. JSON Output for Agent Consumption

All programmatic queries should return JSON with {success, data/error} structure.

Reliable parsing, consistent error handling, and clear success/failure signaling across shell boundaries.

3. IDs Are Forever

Use org-id for stable task references; prefer UUIDs for agent-created tasks.

File paths and line numbers change; org-id provides stable references that survive refactoring and archiving.

4. Cache Awareness

org-ql caches results per-buffer keyed on query+action pairs.

Actions must be pure/side-effect-free for reliable caching; cache invalidates only on buffer modification.

5. Explicit Dependency Modeling

Use both BLOCKER and TRIGGER properties even when redundant.

BLOCKER documents what blocks this task; TRIGGER documents what this task enables - bidirectional documentation aids understanding.

6. Suppress Interactive Prompts

Wrap operations in let-bindings that disable note prompts and confirmations.

Agent operations must complete without user interaction; prompts cause hangs in non-interactive contexts.

7. Condition-Case Everything

Wrap all agent-facing functions in condition-case for error capture.

Errors should be returned as data, not thrown as exceptions that break the calling agent.

8. Delegation Awareness

Tasks delegated to beads execution layer use DELEGATED_TO property and WAITING state.

Org-mode is the planning layer; beads is the execution layer. DELEGATED_TO creates bidirectional traceability; WAITING accurately reflects that the task awaits external completion.

Workflow

Phase 1: Query Planning State

Retrieve current state of tasks, projects, or dependencies.

1. Determine query type - next actions, blocked tasks, by project, by state, overdue, scheduled
2. Select appropriate beadsmith/agent-* function or construct org-ql query
3. Execute via emacsclient --eval
4. Parse JSON response - strip outer quotes, unescape internal quotes
5. Check success field before using data

Outputs: JSON with task list including id, heading, todo state, tags, dates, blocker info; file and line references for each task

;; List all NEXT actions
(beadsmith/agent-list-next-actions)

;; Custom query
(beadsmith/agent-query '(and (todo) (deadline :to 7)))

emacsclient --eval '(beadsmith/agent-list-next-actions)' \
  | sed 's/^"//;s/"$//' | sed 's/\\"/"/g' | jq .

Phase 2: Check Task Dependencies

Determine if a task is blocked and by what.

1. Get task ID (from prior query or known identifier)
2. Call beadsmith/agent-task-blocked-p with the ID
3. Parse response for blocked status and blocking_tasks array
4. If blocked, optionally query status of blocking tasks

Outputs: Boolean blocked status, list of blocking task IDs if blocked, original BLOCKER property string

(beadsmith/agent-task-blocked-p "task-id-here")

emacsclient --eval '(beadsmith/agent-task-blocked-p "task-id")' \
  | sed 's/^"//;s/"$//' | sed 's/\\"/"/g' | jq .

Phase 3: Update Task State

Change a task's TODO state, potentially triggering cascades.

1. Verify task exists via beadsmith/agent-get-task
2. Check if task is blocked (for transitions to DONE)
3. Call beadsmith/agent-set-todo-state or beadsmith/agent-complete-task
4. Verify state change succeeded via response
5. Note that TRIGGER properties will fire automatically if completing

Outputs: Success/failure status, new state confirmation, side effects from triggers

;; Set to specific state
(beadsmith/agent-set-todo-state "task-id" "NEXT")

;; Complete task (fires triggers)
(beadsmith/agent-complete-task "task-id")

emacsclient --eval '(beadsmith/agent-complete-task "task-id")' \
  | sed 's/^"//;s/"$//' | sed 's/\\"/"/g' | jq .

Phase 4: Get Task Details

Retrieve full information about a specific task.

1. Call beadsmith/agent-get-task with known task ID
2. Parse response for all task properties
3. Use for displaying task info or making decisions

Outputs: Complete task record with heading, state, tags, dates, dependencies, location

(beadsmith/agent-get-task "task-id-here")

Phase 5: Create or Modify Tasks

Add new tasks or update existing task properties.

1. For new tasks - find insertion point, use org-insert-heading, set properties including ID
2. For modifications - locate via org-id-find, use org-entry-put for properties
3. Always call org-id-add-location after creating new IDs
4. Save buffer after modifications

Outputs: New task ID if created, confirmation of modification

;; Create task with ID (at point in org buffer)
(org-insert-heading)
(insert "TODO New task heading")
(org-entry-put nil "ID" (org-id-new))
(org-id-add-location (org-entry-get nil "ID") (buffer-file-name))
(save-buffer)

;; Modify property
(org-with-point-at (org-id-find "task-id" 'marker)
  (org-entry-put nil "SCHEDULED" "<2026-01-25 Sat>")
  (save-buffer))

Phase 6: Delegate to Beads Execution Layer

Hand off a task to the beads execution layer for agent swarm execution.

1. Evaluate if task is appropriate for delegation (see spawn-to-beads skill for criteria)
2. Use spawn-to-beads skill to create bead epic and establish bidirectional reference
3. Org task receives DELEGATED_TO property with bead epic ID
4. Org task transitions to WAITING state
5. When bead epic completes, complete-to-org skill updates org task to DONE

Outputs: Org task in WAITING state with DELEGATED_TO property, bead epic created with source_org_id reference

;; Mark task as delegated (after bead epic created)
(org-with-point-at (org-id-find "task-id" 'marker)
  (org-entry-put nil "DELEGATED_TO" "bd-epic-id")
  (org-todo "WAITING")
  (save-buffer))

# Check if task is delegated
emacsclient --eval '(beadsmith/agent-get-task "task-id")' \
  | sed 's/^"//;s/"$//' | sed 's/\\"/"/g' \
  | jq '.data.delegated_to // "not delegated"'

Phase 7: Query Delegated Tasks

Find tasks that are delegated to beads and check their status.

1. Query for tasks with DELEGATED_TO property
2. For each, the property value is the bead epic ID
3. Use bd epic status to check completion
4. If epic complete, trigger complete-to-org workflow

Outputs: List of delegated tasks with their bead epic IDs, completion status of each delegation

;; Query all delegated tasks
(beadsmith/agent-query '(and (todo) (property "DELEGATED_TO")))

# Find all delegated tasks
emacsclient --eval '(beadsmith/agent-query (quote (and (todo) (property "DELEGATED_TO"))))' \
  | sed 's/^"//;s/"$//' | sed 's/\\"/"/g' | jq .

Patterns

Anti-Patterns to Avoid

Quality Checklist

Before completing:

• Using beadsmith/agent-* functions for all agent operations
• JSON responses parsed correctly (quote stripping, unescaping)
• Success field checked before accessing data
• Errors handled gracefully with informative messages
• State changes use org-todo, not direct property manipulation
• Interactive prompts suppressed in all code paths
• Task IDs are stable (org-id based, not file:line)
• org-ql queries have optimizable predicates first
• Timeout protection on emacsclient calls
• Daemon health verified before operation sequences
• Delegated tasks have DELEGATED_TO property and WAITING state
• Delegation uses spawn-to-beads skill (not manual property setting)
• Completed delegations update org via complete-to-org skill

Examples

Morning planning review

# Check what's scheduled for today
emacsclient --eval '(beadsmith/agent-list-scheduled-today)' | parse_json

# Check for overdue items
emacsclient --eval '(beadsmith/agent-list-overdue)' | parse_json

# Get next actions
emacsclient --eval '(beadsmith/agent-list-next-actions)' | parse_json

Complete a task and verify cascade

# Complete the task
result=$(emacsclient --eval '(beadsmith/agent-complete-task "task-a")' | parse_json)

# Verify cascade - check if dependent task is now unblocked
status=$(emacsclient --eval '(beadsmith/agent-task-blocked-p "task-b")' | parse_json)

# task-b should now have blocked=false if task-a was its only blocker

Find all blocked tasks and their blockers

# Get tasks with BLOCKER property
blocked=$(emacsclient --eval '(beadsmith/agent-list-blocked)' | parse_json)

# For each, check what's actually blocking
for id in $(echo "$blocked" | jq -r '.data[].id'); do
  emacsclient --eval "(beadsmith/agent-task-blocked-p \"$id\")" | parse_json
done

Custom query for high-priority tasks due this week

emacsclient --eval '(beadsmith/agent-query 
  (quote (and (todo) 
              (priority "A") 
              (deadline :to 7))))' | parse_json

Delegate task to beads and check status

# 1. Identify task appropriate for delegation
task_id="task-implement-auth"

# 2. Use spawn-to-beads skill to create epic (see that skill for details)
# This returns the bead epic ID and updates the org task

# 3. Later, check delegated tasks status
emacsclient --eval '(beadsmith/agent-query 
  (quote (and (todo "WAITING") (property "DELEGATED_TO"))))' | parse_json

# 4. For each delegated task, check bead epic status
# bd epic status <epic-id>

# 5. When epic complete, complete-to-org skill updates org task

API Reference

Query Functions

Mutation Functions

Dependency Functions

Response Format

All functions return JSON:

{"success": true, "data": [...]}
{"success": false, "error": "Error message"}

org-edna Dependency Syntax

Finders (Target Selection)

Conditions

Actions (for TRIGGER)

Consideration (Quantifiers)

Examples

;; Block until both tasks complete
:BLOCKER: ids("task-a" "task-b")

;; When done, set next sibling to NEXT and schedule for today
:TRIGGER: next-sibling todo!(NEXT) scheduled!(".")

TODO States

Integration Properties

Human Override Behavior

Governance Decision (2026-01-23): When a human completes an org task that has DELEGATED_TO set, warn but take no automatic action.

Why No Auto-Cancellation

• Bead epic may be partially complete with valuable work
• Auto-cancellation risks data loss
• Human override may be intentional (e.g., task no longer needed)
• Epic data preserved for audit trail

Warning Pattern

When completing a task with DELEGATED_TO:

;; Check before completing
(when (org-entry-get nil "DELEGATED_TO")
  (message "WARNING: Task has delegated epic %s - epic may need manual cleanup"
           (org-entry-get nil "DELEGATED_TO")))

Weekly Review Process

During GTD weekly review, check for orphaned epics:

# Find DONE tasks with DELEGATED_TO still set
emacsclient --eval '(beadsmith/agent-query 
  (quote (and (todo "DONE") (property "DELEGATED_TO"))))' | parse_json

# For each, check if epic is still open
# If so, decide: close epic, or was completion a mistake?

Orphaned epics should be manually reviewed and either:

• Closed (work no longer needed)
• Continued (org completion was premature)
• Archived (for historical record)

Related Skills

Infrastructure

Prerequisites

• Emacs daemon running: systemctl --user status emacs
• org-ql and org-edna packages loaded
• Planning files in ~/src/beadsmith/planning/

References

• org-ql GitHub
• org-edna documentation
• Org-mode manual
• GNU Emacs emacsclient manual
• Research synthesis from alphapapa/org-ql issues and discussions
• Research synthesis from org-edna community patterns