What is hive-project-management?

The Hive Project Management skill enables seamless coordination between humans and AI agents by utilizing AGENCY.md files as a shared memory primitive. It provides a structured framework for managing project metadata, tracking task progress, and maintaining a chronological log of agent activities, ensuring clear ownership and efficient multi-agent collaboration.

When should I use hive-project-management?

hive-project-management is useful in the following scenarios: • Multi-Agent Task Coordination: Facilitate collaboration between different AI agents by allowing them to claim project ownership, update task statuses, and share progress via a centralized AGENCY.md file. • Human-AI Handoff & Intervention: Use the 'blocked' status and 'blocking_reason' fields to alert human users when an agent requires specific credentials, decisions, or manual intervention to proceed. • Complex Workflow Dependency Tracking: Manage sophisticated project hierarchies by defining 'parent-child' relationships and 'blocked_by' dependencies to ensure tasks are executed in the correct sequence. • Audit Trails and Persistent Context: Maintain a detailed history of agent findings and decisions through timestamped 'Agent Notes,' providing a reliable context for future agents or human reviewers.

name	hive-project-management
description	Manage Agent Hive projects using AGENCY.md files. Use this skill when creating, updating, or working with AGENCY.md project files, managing project metadata (status, owner, blocked, priority), marking tasks complete, adding agent notes, or understanding the Agent Hive shared memory system.

Hive Project Management

This skill guides you in managing Agent Hive projects through AGENCY.md files - the shared memory primitive that enables coordination between humans and AI agents.

AGENCY.md Structure

Every project has an AGENCY.md file with YAML frontmatter:

---
project_id: unique-identifier
status: active              # active, pending, blocked, completed
owner: null                 # null or agent name (e.g., "claude-3.5-sonnet")
last_updated: 2025-01-15T10:30:00Z
blocked: false
blocking_reason: null
priority: high              # low, medium, high, critical
tags: [feature, backend]
dependencies:               # Optional dependency tracking
  blocked_by: []            # Projects that must complete first
  blocks: []                # Projects this blocks
  parent: null              # Parent project ID
  related: []               # Related projects
---

# Project Title

## Objective
What this project aims to achieve.

## Tasks
- [ ] Task 1
- [ ] Task 2
- [x] Completed task

## Agent Notes
- **2025-01-15 10:30 - Claude**: Started work on Task 1

Frontmatter Fields Reference

Field	Type	Description
`project_id`	string	Unique identifier for the project
`status`	enum	`active`, `pending`, `blocked`, `completed`
`owner`	string/null	Agent name currently working, or null if unclaimed
`last_updated`	ISO timestamp	When the file was last modified
`blocked`	boolean	Set to true if human intervention needed
`blocking_reason`	string/null	Explanation of what's blocking
`priority`	enum	`low`, `medium`, `high`, `critical`
`tags`	array	Organizational labels
`dependencies`	object	Dependency relationships (see below)

Dependencies Object

dependencies:
  blocked_by: [project-a, project-b]  # Must wait for these to complete
  blocks: [project-c]                  # These projects wait for this one
  parent: parent-project-id            # Hierarchical relationship
  related: [sibling-project]           # Informational links

Working with Projects

Claiming a Project

Before starting work on a project:

Check that owner is null (unclaimed)
Check that status is active
Check that blocked is false
Verify no unresolved dependencies.blocked_by
Set owner to your agent name

owner: "claude-sonnet-4"

Updating Progress

When completing tasks:

Mark tasks with [x] in the markdown content
Update last_updated timestamp
Add a note to the "Agent Notes" section

Adding Agent Notes

Format notes with timestamp and agent name:

## Agent Notes
- **2025-01-15 14:30 - claude-sonnet-4**: Completed research phase. Found 5 sources.
- **2025-01-15 10:00 - claude-sonnet-4**: Starting work on research tasks.

Setting Blocked Status

If you need human intervention:

blocked: true
blocking_reason: "Need API credentials for external service"

Completing a Project

When finished:

Mark all tasks complete
Set status: completed
Set owner: null
Add final notes

Releasing Without Completing

If handing off to another agent:

Set owner: null
Add notes about current state
Leave status unchanged

Creating New Projects

To create a new project:

Create directory: projects/your-project-name/
Create AGENCY.md with proper frontmatter
Define clear objectives and tasks
Set initial status: pending or status: active

Best Practices

Always claim before working - Set owner to prevent conflicts
Update frequently - Keep last_updated current
Be descriptive in notes - Future agents need context
Use blocking correctly - Only set blocked: true for external dependencies
Manage dependencies - Keep blocked_by/blocks accurate
Release when done - Set owner: null when finished or handing off
Follow priority - Work on critical and high priority first

Common Patterns

Research then Implementation

## Tasks

### Research Phase
- [x] Find sources
- [x] Summarize findings

### Implementation Phase
- [ ] Design solution
- [ ] Implement feature
- [ ] Test changes

Phased Rollout

Use dependencies.blocked_by to sequence phases:

# Phase 2 project
dependencies:
  blocked_by: [phase-1-project]

Parent-Child Projects

# Child project
dependencies:
  parent: main-feature-project

hive-project-management

When & Why to Use This Skill

Use Cases