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

# 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

# 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

# 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.