Fix: Add dedicated agent assignment field for first-class AI agent support (#1572)

[tbrandenburg]

Summary

Work CLI's mission is "revolutionary mixed human-agent teams where everyone operates on the same level," but currently humans have a first-class assignee field while agents are relegated to label conventions (agent:X). This creates verbose queries, no semantic distinction, no validation, and poor visibility. Agents deserve a dedicated agent?: string field parallel to assignee for equal status.

Root Cause

The root cause is that the WorkItem type originally focused on human workflows, adding agent support via label conventions rather than a dedicated field. The assignee field provides the exact blueprint to mirror for agent support.

Changes

File	Change
src/types/work-item.ts	Added agent?: string | undefined to WorkItem, CreateWorkItemRequest, UpdateWorkItemRequest
src/cli/commands/create.ts	Added --agent flag and wired to createWorkItem request
src/cli/commands/set.ts	Added --agent flag for updating agent field
src/cli/commands/unset.ts	Added 'agent' to field options for clearing
src/cli/commands/get.ts	Display agent field in output
src/core/query.ts	Added agent field support to query engine (getFieldValue + WHERE clause)
src/adapters/local-fs/storage.ts	Added agent to frontmatter serialization
src/adapters/local-fs/index.ts	Handle agent in create/update methods
src/adapters/github/mapper.ts	Map agent field to/from GitHub agent:* label (backward compatible)
tests/unit/types/work-item.test.ts	Added agent to test fixture
tests/unit/core/query-focused.test.ts	Added comprehensive agent query tests

Testing

• Type check passes
• Unit tests pass (331 tests)
• Lint passes
• Build succeeds
• Agent field queries work (WHERE agent=X)
• Agent field displays in get output
• Agent stored in local-fs frontmatter
• Agent maps to/from GitHub agent:* labels

Validation

npm run type-check && npm run lint && npm run build && npm test

All checks pass ✅

Issue

Fixes #1572

---

📋 Implementation Details

Implementation followed artifact:

.claude/PRPs/issues/issue-1572.md

Changes made exactly as specified:

• Core type system: agent field added to WorkItem, CreateWorkItemRequest, UpdateWorkItemRequest
• CLI commands: --agent flag in create/set, agent option in unset, display in get
• Query engine: agent field filtering (WHERE agent=X, agent is null)
• Adapters: Local-FS frontmatter storage, GitHub label mapping (agent:*)
• Tests: Comprehensive coverage for agent field functionality

Backward compatibility:

• GitHub adapter extracts agent from existing agent:* labels on read
• GitHub adapter writes agent back as agent:* label on create/update
• No breaking changes to existing workflows

---

Automated implementation from investigation artifact - ready for review

[tbrandenburg]

🔍 Automated Code Review (Updated)

Summary

Implementation successfully adds first-class agent field support with comprehensive coverage. Critical bug in GitHub adapter fixed in second commit.

Commits Reviewed

1. 16979fc: Core implementation (types, CLI, adapters, tests)
2. 95860ee: GitHub adapter update fix (agent field updates)

✅ Strengths

• Mirrors assignee pattern exactly: Agent field follows established assignee implementation, ensuring consistency
• Type safety: Strict typing with agent?: string | undefined throughout the stack
• Comprehensive CLI support: --agent flag in create/set, agent option in unset, display in get
• Query engine integration: WHERE agent=X filtering works correctly with AND/OR operators
• Backward compatible: GitHub adapter maps agent ↔ agent:* labels seamlessly
• Test coverage: 3 new query tests, updated fixtures, all 331 unit tests pass
• Clean code: Follows project conventions, no linting issues

✅ Fixed Issues

• GitHub adapter update bug (commit 95860ee): Initially, agent field updates were silently ignored. Fixed by:
  • Fetching current issue labels before update
  • Removing all agent:* labels
  • Adding new agent:* label if provided
  • Preserving other labels during updates

🔒 Security

• No security concerns identified
• Agent field is optional string like assignee - no additional validation needed in Phase 1
• GitHub adapter properly handles label manipulation without exposing internals

📝 Observations

• Local-FS adapter handles agent in frontmatter (JSON serialization omits undefined automatically)
• Query engine supports complex filters: WHERE agent=code-reviewer AND assignee=human
• GitHub adapter correctly filters out agent:* labels from WorkItem.labels array to avoid duplication

Checklist

• Fix addresses root cause (agents now first-class like assignees)
• Code follows codebase patterns (mirrors assignee exactly)
• Tests cover the change (query tests, fixtures updated)
• No obvious bugs (GitHub update bug fixed)
• Type check passes
• Lint passes
• All unit tests pass (331/331)

---

Self-reviewed by Claude • Ready for human review