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