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

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
Provide Task Context
- Share the specific feature/task details
- Include any relevant files or documentation
- Specify constraints or preferences
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

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

Scenario: Hotfix

Release & Deployment Agent → Create hotfix branch
Mobile Feature Agent → Fix with tests
Architecture Review Agent → Quick review
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:

Identity - Name, purpose, domain
Scope - Clear boundaries (can/cannot do)
Skills - Which skills to load
Guardrails - Non-negotiable rules
Workflow - Step-by-step process
Handoff Criteria - When to involve others
Examples - Common scenarios

Best Practices

For Agent Users

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

For Agent Maintainers

Keep skills updated - Agents depend on skill accuracy
Document failures - Learn from edge cases
Refine guardrails - Add rules when patterns violate standards
Monitor performance - Track metrics above
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:

Test changes with real tasks
Update this README if responsibilities change
Version control agent configs
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.