hive-project-management

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:

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

owner: "claude-sonnet-4"

Updating Progress

When completing tasks:

1. Mark tasks with [x] in the markdown content
2. Update last_updated timestamp
3. 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:

1. Mark all tasks complete
2. Set status: completed
3. Set owner: null
4. Add final notes

Releasing Without Completing

If handing off to another agent:

1. Set owner: null
2. Add notes about current state
3. Leave status unchanged

Creating New Projects

To create a new project:

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

Best Practices

1. Always claim before working - Set owner to prevent conflicts
2. Update frequently - Keep last_updated current
3. Be descriptive in notes - Future agents need context
4. Use blocking correctly - Only set blocked: true for external dependencies
5. Manage dependencies - Keep blocked_by/blocks accurate
6. Release when done - Set owner: null when finished or handing off
7. 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