Task Delegation

Task Delegation

Delegate user stories to specialized agents with complete context, clear ownership, and standardized workflow.

What This Skill Provides

• Delegation brief template: Comprehensive task handoff format
• Initialization script: Auto-create delegation documents with story context
• Validation: Verify delegation completeness before handoff
• AI-guided workflow: Create complete delegation briefs with acceptance criteria

When to Use

• Delegating story implementation to agents
• Creating delegation briefs for parallel workstreams
• Ensuring agents have complete context before starting
• Validating delegation readiness

Quick Start

1. Initialize Delegation

# From project root
./scripts/init-delegation.sh us-001 fullstack-engineer

Creates:

specs/{feature}/stories/us-001/delegation/
└── fullstack-engineer.delegation.md  ← Fill this

Auto-extracts context from story tracker.

2. Fill Delegation Brief

Use AI-guided prompt:

/create-delegation-brief

Guides you through:

• Context and user value
• Acceptance criteria (agent-specific)
• Dependencies (what must be ready first)
• Technical details (files, architecture)
• Handoff requirements (what next story needs)
• Standards reference

3. Validate Completeness

./scripts/validate-delegation-brief.sh us-001 fullstack-engineer

Checks:

• All required sections present
• No [Fill] placeholders
• Acceptance criteria defined with checkboxes
• Branch/worktree assigned

Exit code 0 = passed, 1 = failed.

Legacy Delegation Workflow (Reference)

Core Principles

1. Complete Context Transfer

Every delegation includes:

• User story specification
• Acceptance criteria
• Dependencies (what must be ready first)
• Handoff requirements (what next story needs)
• Branch/worktree assignment
• Constitution/spec references

2. Clear Ownership

One agent per story, no shared ownership:

• Agent assigned to specific worktree
• Agent owns story from start to merge
• Agent responsible for tests and documentation
• Agent reports completion status

3. Structured Communication

Standardized handoff format:

• Delegation: Feature Lead → Agent
• Progress: Agent → Feature Lead
• Completion: Agent → Feature Lead
• Questions: Agent ↔ Feature Lead

Delegation Workflow

Phase 1: Story Assignment

Command: /delegate.assign <story-id> <agent-id>

Delegation Package:

## Story Delegation: US1 - Natural Language Bird Search API

**Assigned To**: Agent-FullStack-A  
**Worktree**: `worktrees/feat-us1`  
**Branch**: `feat/us1-bird-search`  
**Estimated Effort**: 2 days  
**WIP Slot**: 1 of 3

### Story Context
From Feature: Natural Language Bird Search  
Spec Reference: `specs/001-bird-search-ui/spec.md`  
Constitution: `birdmate/AGENTS.md` (Principles I, II, III)

### User Story
**As a** birdwatcher  
**I want** to search for birds using natural language descriptions  
**So that** I can identify birds without knowing scientific names

**Acceptance Criteria**:
- [ ] POST /api/search endpoint accepts text query
- [ ] Returns top 5 matching bird species with confidence scores
- [ ] Query logged with timestamp (Constitution Principle IV)
- [ ] 80%+ test coverage (Constitution Principle III)
- [ ] Response time < 2s (NFR-001)

### Dependencies
**Prerequisites** (MUST be complete before starting):
- ✅ T010: Database schema created
- ✅ T016: OpenAI embeddings generated
- ✅ T022: Shared TypeScript types defined

**Provides to Next Story** (US2 - Search UI):
- API contract: POST /api/search (see contracts/api.openapi.yml)
- Response schema: BirdSearchResult[]
- Error codes: 400 (invalid query), 500 (search failed)

### Technical Guidance
**Stack**: Node.js + TypeScript + Express + SQLite + OpenAI SDK  
**Test Framework**: Vitest  
**Key Files**:
- `backend/src/api/routes/search.ts` (endpoint)
- `backend/src/services/searchService.ts` (logic)
- `backend/src/db/queries/vectorSearch.ts` (embeddings)
- `backend/tests/api/search.test.ts` (integration tests)

**Constitution Compliance**:
- Principle III: TDD mandatory (write tests first)
- Principle IV: Log all queries to search_queries table
- Principle II: Reference eBird taxonomy only

### Skills to Apply
- **tdd-workflow**: Red → Green → Refactor cycle
- **claude-framework**: Error handling, input validation, logging
- **fullstack-expertise**: Backend API design patterns

### Questions?
Contact Feature Lead via: `/delegate.question <story-id> <question>`

Phase 2: Agent Acceptance

Command: /delegate.accept <story-id>

Agent acknowledges delegation and confirms:

## Story Accepted: US1

**Agent**: Agent-FullStack-A  
**Acknowledged**: 2025-12-23 10:00 AM  
**Clarifications Needed**: None  
**Estimated Start**: Immediately  
**Estimated Completion**: 2025-12-25 EOD

**Setup Verified**:
- ✅ Worktree created: `worktrees/feat-us1`
- ✅ Branch checked out: `feat/us1-bird-search`
- ✅ Dependencies confirmed complete
- ✅ Tests run successfully (0 implemented yet)
- ✅ Constitution reviewed

**Next Steps**:
1. Write API endpoint tests (TDD)
2. Implement search service
3. Integrate OpenAI embeddings
4. Run test suite (target: 80%+ coverage)
5. Update API documentation

Phase 3: Progress Reporting

Command: /delegate.progress <story-id> <status>

Daily progress updates:

## Progress Update: US1 - Day 1

**Date**: 2025-12-23  
**Status**: 🔄 In Progress (40% complete)  
**Blockers**: None  

**Completed Today**:
- ✅ Wrote API endpoint tests (15 test cases)
- ✅ Implemented basic search route handler
- ✅ Integrated OpenAI embedding similarity search
- ✅ Test coverage: 45% (target: 80%)

**Planned for Tomorrow**:
- ⏳ Implement query logging (Constitution Principle IV)
- ⏳ Add error handling for invalid queries
- ⏳ Increase test coverage to 80%+
- ⏳ Update API documentation

**Risks**:
- OpenAI API rate limiting (handling with exponential backoff)

**Questions**:
- Should we cache embedding similarity results? (Performance NFR-001)

Phase 4: Story Completion

Command: /delegate.complete <story-id>

Completion checklist:

## Story Completion: US1 - Natural Language Bird Search API

**Agent**: Agent-FullStack-A  
**Completed**: 2025-12-25 3:00 PM  
**Branch**: `feat/us1-bird-search`  
**Pull Request**: #123

### Acceptance Criteria ✅
- ✅ POST /api/search endpoint accepts text query
- ✅ Returns top 5 matching bird species with confidence scores
- ✅ Query logged with timestamp (Constitution Principle IV)
- ✅ 82% test coverage (exceeds 80% target)
- ✅ Response time: 1.2s average (meets < 2s requirement)

### Constitution Compliance ✅
- ✅ Principle III: TDD applied (tests written first)
- ✅ Principle IV: All queries logged to search_queries table
- ✅ Principle II: eBird taxonomy referenced correctly

### Deliverables
**Code Changes**:
- `backend/src/api/routes/search.ts` (new)
- `backend/src/services/searchService.ts` (new)
- `backend/src/db/queries/vectorSearch.ts` (new)
- `backend/tests/api/search.test.ts` (new, 18 tests)

**Documentation**:
- Updated: `contracts/api.openapi.yml` (POST /api/search)
- Updated: `README.md` (API usage examples)

**Tests**:
- Unit tests: 12 passing
- Integration tests: 6 passing
- Coverage: 82% (backend/src/services/)

### Handoff to Next Story (US2)
**Provides**:
- API endpoint: POST /api/search
- Request schema: `{ query: string }`
- Response schema: `BirdSearchResult[]` (see shared/types/index.ts)
- Error codes: 400 (invalid), 429 (rate limit), 500 (server error)
- Example queries: See tests/api/search.test.ts

**Dependencies Resolved**:
- ✅ API contract matches contracts/api.openapi.yml
- ✅ Response types exported from shared/types/
- ✅ CORS configured for frontend integration

**Known Limitations**:
- Caching not implemented (defer to US3)
- Rate limiting: 10 requests/min (may need adjustment)

### Ready for Merge
- ✅ All tests passing
- ✅ Branch synced with main (no conflicts)
- ✅ Code review requested
- ✅ Documentation complete

Phase 5: Handoff Review

Command: /delegate.review <story-id>

Feature lead validates completion:

## Story Review: US1

**Reviewer**: Feature Lead  
**Review Date**: 2025-12-25 4:00 PM  
**Status**: ✅ APPROVED

### Validation Checklist
- ✅ Acceptance criteria met (5/5)
- ✅ Constitution compliance verified
- ✅ Test coverage adequate (82% > 80%)
- ✅ Handoff documentation complete
- ✅ No merge conflicts with main
- ✅ API contract matches spec

### Cross-Story Consistency
- ✅ No conflicts with US2 (UI implementation)
- ✅ No conflicts with US3 (caching layer)
- ✅ Shared types properly exported

### Merge Approved
**Action**: Merge `feat/us1-bird-search` → `main`  
**Next**: Assign Agent-FullStack-A to US4 (WIP slot available)

**Feedback to Agent**:
- Excellent test coverage
- Good error handling
- Suggestion: Consider adding query validation schemas for future stories

Delegation Patterns

Pattern 1: Sequential Stories (Dependent)

Story 1 → Story 2 → Story 3

Story 2 CANNOT start until Story 1 completes.

Example:
- US1: Build API endpoint
- US2: Build UI that calls API (depends on US1)
- US3: Add caching to API (depends on US1)

Delegation Timing:
- Assign US1 immediately
- Assign US2 after US1 merge
- Assign US3 after US1 merge (parallel with US2)

Pattern 2: Parallel Stories (Independent)

Story 1 || Story 2 || Story 3

All stories can run simultaneously (no dependencies).

Example:
- US1: Build backend API
- US2: Build frontend UI (mocked API)
- US3: Setup deployment pipeline

Delegation Timing:
- Assign all 3 stories immediately
- Use worktrees: feat-us1, feat-us2, feat-us3
- Merge in any order

Pattern 3: Mixed Dependencies

     US1 (API)
      ↓
  ┌───┴───┐
  ↓       ↓
 US2     US3
(UI)   (Cache)
  ↓       ↓
  └───┬───┘
      ↓
    US4
  (E2E Tests)

Delegation Strategy:
1. Assign US1 (slot 1)
2. Wait for US1 completion
3. Assign US2 and US3 simultaneously (slots 1, 2)
4. Wait for both completions
5. Assign US4 (slot 1)

Communication Protocols

Agent → Feature Lead

Status Updates (daily):

/delegate.progress us1 "40% complete, on track, no blockers"

Questions:

/delegate.question us1 "Should we cache embedding results for performance?"

Blocked:

/delegate.blocked us1 "Waiting for US3 API contract definition"

Completion:

/delegate.complete us1

Feature Lead → Agent

Delegation:

/delegate.assign us2 agent-fullstack-b

Clarification:

/delegate.clarify us1 "Yes, implement caching in US3, not US1. Keep US1 simple."

Priority Change:

/delegate.reprioritize us2 "HIGH - blocking frontend demo"

WIP Limit Enforcement

Maximum 3 concurrent delegations:

## WIP Tracker

| Slot | Story | Agent | Status | Branch |
|------|-------|-------|--------|--------|
| 1    | US1   | Agent-A | 🔄 WIP | feat-us1 |
| 2    | US2   | Agent-B | 🔄 WIP | feat-us2 |
| 3    | US3   | Agent-C | 🔄 WIP | feat-us3 |

❌ CANNOT delegate US4 - all slots full
✅ Wait for US1, US2, or US3 completion

When story completes:

1. Free up WIP slot
2. Select next story from backlog
3. Delegate to available agent
4. Update WIP tracker

Commands Reference

AI-Assisted Prompts

Communication Flow

Quick Reference

Best Practices

✅ Do This

• Complete context: Include all dependencies, specs, and acceptance criteria
• Clear ownership: One agent per story, no ambiguity
• Daily updates: Require progress reports from all agents
• Early questions: Agents should ask clarifications immediately
• Handoff documentation: Every story documents what next story needs

❌ Don't Do This

• Partial delegation: Don't assign stories without complete context
• Shared ownership: Never split one story across multiple agents
• Silent agents: Require daily progress updates
• Scope creep: Keep story boundaries clear and enforced
• Skip handoffs: Every story must document outputs

Success Metrics

• ✅ Zero ambiguity: All agents understand their assignments
• ✅ WIP limit respected: Never exceed 3 concurrent stories
• ✅ Daily visibility: Progress updates from all agents
• ✅ Smooth handoffs: Next story has everything it needs
• ✅ High completion rate: Stories merge successfully without rework