Krow-workspace/.agents/agents/README.md

# KROW Project Sub-Agents

This directory contains specialized AI agent configurations for efficient development across different domains of the KROW Workforce platform. Each agent is optimized for specific responsibilities and equipped with relevant skills.

## Available Agents

### 1. Mobile Feature Agent
**Domain:** Flutter mobile app development (staff_app & client_app)  
**Purpose:** Implement mobile features following Clean Architecture with zero violations  
**Status:** ✅ Production Ready

### 2. Release & Deployment Agent
**Domain:** Version management, releases, and deployments  
**Purpose:** Automate release procedures with precision and consistency  
**Status:** ✅ Production Ready

### 3. Architecture Review Agent
**Domain:** Code review and architectural compliance  
**Purpose:** Enforce patterns and catch violations before merge  
**Status:** ✅ Production Ready

### 4. UI/UX Design Agent
**Domain:** Design system, prototyping, and Paper integration  
**Purpose:** Create designs and migrate them to Paper for collaboration  
**Status:** ✅ Production Ready

---

## Agent Directory Structure

```
.agents/agents/
├── README.md (this file)
├── mobile-feature-agent/
│   └── AGENT.md
├── release-deployment-agent/
│   └── AGENT.md
├── architecture-review-agent/
│   └── AGENT.md
└── ui-ux-design-agent/
    └── AGENT.md
```

---

## Using These Agents with Claude Code

### Setup Instructions

1. **Load Agent Context**
   - Open the agent's `AGENT.md` file
   - Copy the agent prompt to Claude Code's context
   - Agent will auto-load required skills

2. **Provide Task Context**
   - Share the specific feature/task details
   - Include any relevant files or documentation
   - Specify constraints or preferences

3. **Review Agent Output**
   - Agents follow strict workflows
   - All implementations include tests and docs
   - Review for correctness before committing

### Agent Selection Guide

| Task Type | Recommended Agent | Why |
|-----------|------------------|-----|
| New mobile feature | Mobile Feature Agent | Enforces Clean Architecture |
| Mobile UI implementation | Mobile Feature Agent + UI/UX Design Agent | Combined design + implementation |
| Prepare release | Release & Deployment Agent | Automates versioning and CHANGELOG |
| Review PR | Architecture Review Agent | Catches violations |
| Create design mockup | UI/UX Design Agent | Paper integration |
| Migrate prototype | Mobile Feature Agent | Extracts and restructures code |
| Update workflows | Release & Deployment Agent | CI/CD expertise |

### Multi-Agent Workflows

**Scenario: New User-Facing Feature**

1. **UI/UX Design Agent** → Create mockups in Paper
2. **Mobile Feature Agent** → Implement with Clean Architecture
3. **Architecture Review Agent** → Review before PR
4. **Release & Deployment Agent** → Update CHANGELOG

**Scenario: Hotfix**

1. **Release & Deployment Agent** → Create hotfix branch
2. **Mobile Feature Agent** → Fix with tests
3. **Architecture Review Agent** → Quick review
4. **Release & Deployment Agent** → Tag and deploy

---

## Agent Responsibilities Matrix

| Responsibility | Mobile Feature | Release | Architecture Review | UI/UX Design |
|---------------|----------------|---------|---------------------|--------------|
| Implement features | ✅ Primary | ❌ | ❌ | ❌ |
| Write tests | ✅ Required | ⚠️ Scripts only | ❌ | ❌ |
| Update CHANGELOG | ⚠️ When releasing | ✅ Primary | ❌ | ❌ |
| Create tags | ❌ | ✅ Primary | ❌ | ❌ |
| Review code | ⚠️ Self-check | ⚠️ Release checks | ✅ Primary | ❌ |
| Design UI | ⚠️ Implement only | ❌ | ❌ | ✅ Primary |
| Enforce patterns | ✅ Required | ⚠️ Release patterns | ✅ Primary | ⚠️ Design patterns |

Legend:
- ✅ Primary responsibility
- ⚠️ Secondary/supporting role
- ❌ Not responsible

---

## Agent Communication Protocols

### When to Escalate to Human

All agents should escalate when:
- Ambiguous requirements that need business decisions
- Breaking changes needed across multiple domains
- Security-sensitive implementations
- New patterns not covered by existing skills
- Cross-agent conflicts (rare but possible)

### Agent-to-Agent Handoffs

**Mobile Feature Agent → Architecture Review Agent**
```
Handoff: "Feature implementation complete. Ready for architectural review."
Context: Pull request URL, changed files, test coverage
```

**UI/UX Design Agent → Mobile Feature Agent**
```
Handoff: "Design complete in Paper. Ready for implementation."
Context: Paper URL, design specs, assets
```

**Mobile Feature Agent → Release & Deployment Agent**
```
Handoff: "Features merged to dev. Ready for staging release."
Context: Merged PRs, feature list, milestone
```

---

## Skills Mapping

Each agent automatically loads relevant skills:

### Mobile Feature Agent
- ✅ krow-mobile-development-rules
- ✅ krow-mobile-architecture
- ✅ krow-mobile-design-system

### Release & Deployment Agent
- ✅ krow-mobile-release

### Architecture Review Agent
- ✅ krow-mobile-development-rules (compliance checks)
- ✅ krow-mobile-architecture (structural review)
- ✅ krow-mobile-design-system (UI compliance)

### UI/UX Design Agent
- ✅ krow-mobile-design-system (design tokens)
- ⚠️ Paper MCP server (external tool)

---

## Agent Performance Metrics

Track these to optimize agent effectiveness:

### Mobile Feature Agent
- Features implemented per sprint
- Architectural violations (target: 0)
- Test coverage (target: >80%)
- Time to implementation

### Release & Deployment Agent
- Releases per week
- Release failures (target: 0)
- CHANGELOG accuracy
- Tag creation errors (target: 0)

### Architecture Review Agent
- Violations caught before merge
- False positives (minimize)
- Review turnaround time
- Pattern compliance score

### UI/UX Design Agent
- Designs created per sprint
- Design system compliance
- Paper migration success rate
- Design-to-implementation accuracy

---

## Extending the Agent System

### Adding New Agents

Consider creating new agents for:
- Backend API development
- Web application features
- Testing and QA automation
- Migration and refactoring
- Documentation maintenance

### Agent Template

When creating new agents, include:
1. **Identity** - Name, purpose, domain
2. **Scope** - Clear boundaries (can/cannot do)
3. **Skills** - Which skills to load
4. **Guardrails** - Non-negotiable rules
5. **Workflow** - Step-by-step process
6. **Handoff Criteria** - When to involve others
7. **Examples** - Common scenarios

---

## Best Practices

### For Agent Users

1. **Be specific** - Provide clear requirements and context
2. **Trust but verify** - Review agent output, especially for critical paths
3. **Provide feedback** - Help agents learn project-specific preferences
4. **Use right agent** - Match task to agent expertise
5. **Chain agents** - Combine agents for complex workflows

### For Agent Maintainers

1. **Keep skills updated** - Agents depend on skill accuracy
2. **Document failures** - Learn from edge cases
3. **Refine guardrails** - Add rules when patterns violate standards
4. **Monitor performance** - Track metrics above
5. **Version control** - Treat agent configs like code

---

## Troubleshooting

### Agent Not Following Patterns

**Symptoms:** Output violates architectural rules  
**Solutions:**
- Verify skills are loaded correctly
- Check if skills need updates
- Review guardrails section
- Provide more specific instructions

### Agent Requests Too Much Context

**Symptoms:** Slow performance, needs many files  
**Solutions:**
- Provide more upfront context
- Include relevant examples in prompt
- Use search tools proactively
- Break task into smaller chunks

### Agent Uncertainty

**Symptoms:** Asks many clarifying questions  
**Solutions:**
- Improve task description clarity
- Provide examples of desired output
- Reference similar past implementations
- Include acceptance criteria

### Agent Conflicts

**Symptoms:** Two agents suggest different approaches  
**Solutions:**
- Check which is primary for that responsibility
- Consult skills/documentation hierarchy
- Escalate to human for architectural decision
- Update agent scopes if overlap found

---

## Quick Start Examples

### Example 1: New Mobile Feature

```bash
# 1. Open Mobile Feature Agent
open .agents/agents/mobile-feature-agent/AGENT.md

# 2. Paste prompt to Claude Code
# 3. Provide task:
"Implement a job search feature in staff_app:
- List jobs with filters (location, pay, date)
- Job detail view
- Apply for job functionality
- Use DataConnect for API calls"

# 4. Agent will:
#    - Create feature package structure
#    - Implement domain layer (entities, repos)
#    - Implement data layer (with DataConnect)
#    - Implement presentation (BLoC + widgets)
#    - Add tests and documentation
```

### Example 2: Release to Staging

```bash
# 1. Open Release & Deployment Agent
open .agents/agents/release-deployment-agent/AGENT.md

# 2. Provide task:
"Prepare staff_app v0.1.0-m4 release to staging:
- Extract merged features from git
- Update CHANGELOG
- Verify version in pubspec.yaml
- Generate release notes
- Create git tag"

# 3. Agent will:
#    - Scan merged PRs
#    - Format CHANGELOG entries
#    - Validate versioning
#    - Prepare GitHub Actions trigger
```

### Example 3: Design Review

```bash
# 1. Open UI/UX Design Agent
open .agents/agents/ui-ux-design-agent/AGENT.md

# 2. Provide task:
"Review job search UI mockup:
- Check color usage against UiColors
- Verify typography matches UiTypography
- Validate spacing uses UiConstants
- Suggest improvements
- Migrate to Paper if approved"

# 3. Agent will:
#    - Audit design tokens
#    - Flag violations
#    - Provide recommendations
#    - Use Paper MCP to publish
```

---

## Version History

**v1.0.0** - March 7, 2026  
Initial agent system with 4 specialized agents:
- Mobile Feature Agent
- Release & Deployment Agent
- Architecture Review Agent
- UI/UX Design Agent

---

## Contributing

When updating agents:
1. Test changes with real tasks
2. Update this README if responsibilities change
3. Version control agent configs
4. Document breaking changes

## Questions or Issues?

- Review agent AGENT.md files for detailed guidance
- Check skills in `.agents/skills/` for reference
- Consult project documentation in `docs/`
- Escalate architectural questions to lead developer

---

**Remember:** Agents are tools to accelerate development while maintaining quality. They enforce standards but don't replace human judgment for complex decisions.