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

# KROW Mobile Development Skills

This directory contains project-specific skills for AI agents working on the KROW mobile applications. These skills encode the development standards, architecture patterns, UI system usage, and release practices defined in the mobile documentation.

## Overview

These skills help AI agents contribute effectively to mobile application development by providing:
- **Clear guidelines** on development standards and constraints
- **Architecture patterns** for Clean Architecture implementation
- **Design system rules** for consistent UI implementation
- **Release procedures** for version management and deployment

## Available Skills

### 1. krow-mobile-development-rules

**Purpose:** Enforce development standards and prevent architectural degradation

**Covers:**
- File creation and package structure (feature-first packaging)
- Naming conventions (Dart standards)
- Logic placement boundaries (strict separation of concerns)
- Localization integration (core_localization package)
- Data Connect integration strategy
- Prototype migration rules
- Navigation with safe extensions
- Session management patterns
- Error handling requirements

**Use When:**
- Creating new mobile features or packages
- Implementing BLoCs, Use Cases, or Repositories
- Integrating with Firebase Data Connect backend
- Migrating code from prototypes
- Reviewing mobile code for compliance

**Key Documentation:**
- Source: `docs/MOBILE/00-agent-development-rules.md`

### 2. krow-mobile-architecture

**Purpose:** Maintain Clean Architecture across the mobile codebase

**Covers:**
- High-level architecture overview
- Package structure and responsibilities
- Dependency direction rules
- Feature isolation and communication
- Data Connect service and session management
- BLoC lifecycle and state emission safety
- Avoiding prop drilling patterns
- Data Connect connectors pattern overview

**Use When:**
- Architecting new mobile features
- Debugging state management or BLoC lifecycle issues
- Preventing prop drilling in UI code
- Managing session state and authentication
- Understanding package boundaries and dependencies
- Refactoring legacy code to Clean Architecture

**Key Documentation:**
- Source: `docs/MOBILE/01-architecture-principles.md`
- Related: `docs/MOBILE/03-data-connect-connectors-pattern.md`

### 3. krow-mobile-design-system

**Purpose:** Ensure visual consistency using immutable design tokens

**Covers:**
- Design system ownership and authority
- Colors usage rules (UiColors)
- Typography usage rules (UiTypography)
- Icons usage rules (UiIcons)
- Spacing and layout constants (UiConstants)
- Smart widgets usage
- Theme configuration
- POC → Production workflow
- Anti-patterns to avoid

**Use When:**
- Implementing any UI in mobile features
- Migrating POC/prototype designs to production
- Creating themed widgets or components
- Reviewing UI code for design system compliance
- Matching colors and typography from designs
- Adding icons, spacing, or layout elements

**Key Documentation:**
- Source: `docs/MOBILE/02-design-system-usage.md`

### 4. krow-mobile-release

**Purpose:** Manage mobile app releases, versioning, and hotfixes

**Covers:**
- Versioning strategy (semantic versioning with milestones)
- CHANGELOG management and format
- Git tagging strategy
- GitHub Actions workflows (product-release, hotfix)
- APK signing setup (24 GitHub Secrets)
- Release process (dev → stage → prod)
- Hotfix procedures
- Troubleshooting release issues

**Use When:**
- Preparing for mobile app releases
- Updating CHANGELOG files with new features
- Triggering GitHub Actions release workflows
- Creating hotfix branches for production issues
- Understanding version numbering
- Documenting release notes

**Key Documentation:**
- Source: `docs/MOBILE/05-release-process.md`
- Comprehensive: `docs/RELEASE/mobile-releases.md` (900+ lines)

## Skill Organization

Each skill follows this structure:

```
.agents/skills/
├── krow-mobile-development-rules/
│   └── SKILL.md
├── krow-mobile-architecture/
│   └── SKILL.md
├── krow-mobile-design-system/
│   └── SKILL.md
└── krow-mobile-release/
    └── SKILL.md
```

## Skill Descriptions

Each skill includes a description in its frontmatter that helps AI agents determine when to use it. These descriptions are designed to be "pushy" to ensure skills are triggered appropriately.

## Using These Skills

### For AI Agents

1. **Skill triggering is automatic** based on:
   - User task description matching skill description
   - Context keywords (mobile, flutter, feature, release, etc.)
   - Task type (implementation, architecture, UI, release)

2. **Skills can be combined** - multiple skills may be relevant:
   - Development rules + Architecture (implementing features)
   - Architecture + Design System (creating UI with proper structure)
   - Release + Development rules (preparing releases)

3. **Reference documentation** when needed:
   - Skills provide comprehensive guidance
   - Link to source documentation for deep dives
   - Include examples and anti-patterns

### For Developers

These skills serve as:
- **Quick reference** for mobile development standards
- **Onboarding material** for new team members
- **Code review checklist** for ensuring compliance
- **Architecture guide** for feature implementation

## Skill Maintenance

### Updating Skills

When mobile documentation changes:
1. Review corresponding skill(s)
2. Update skill content to match new standards
3. Update examples and patterns
4. Keep descriptions current for proper triggering

### Adding New Skills

Consider creating new skills for:
- New architectural patterns (e.g., state management approaches)
- New subsystems (e.g., analytics, crash reporting)
- Complex workflows spanning multiple skills
- Domain-specific patterns (e.g., payment processing)

## Related Documentation

### Mobile Documentation Structure
```
docs/MOBILE/
├── 00-agent-development-rules.md      → krow-mobile-development-rules
├── 01-architecture-principles.md      → krow-mobile-architecture
├── 02-design-system-usage.md          → krow-mobile-design-system
├── 03-data-connect-connectors-pattern.md (not in skills)
├── 04-use-case-completion-audit.md    (not in skills yet)
└── 05-release-process.md              → krow-mobile-release

docs/RELEASE/
└── mobile-releases.md                 → krow-mobile-release (comprehensive)
```

## Enforcement

These skills encode **NON-NEGOTIABLE** standards. When AI agents:
- Create features → Must follow development rules
- Implement UI → Must use design system
- Prepare releases → Must follow release process
- Structure code → Must maintain Clean Architecture

**Zero tolerance for violations** ensures:
- Architectural integrity
- Visual consistency
- Code quality
- Maintainability
- Scalability

## Questions or Issues?

If you encounter:
- **Unclear guidelines** - Refer to source documentation
- **Conflicting patterns** - Architecture document takes precedence
- **Missing patterns** - Document assumption and ask for clarification
- **Technical debt** - Follow skills for new code, refactor legacy gradually

## Summary

These skills transform documentation into actionable, contextual guidance for AI agents working on KROW mobile applications. They ensure consistency, prevent architectural degradation, and accelerate development while maintaining quality standards.

**Key Principles:**
- Clean Architecture with strict boundaries
- Feature isolation via zero cross-feature imports
- Immutable design system
- Semantic versioning and structured releases
- Localization-first user interfaces

When in doubt, consult the skills or source documentation. Architecture is not negotiable.