Mellow Engineering

Mellow Compound Engineering Plugin

A Claude Code plugin implementing the compound engineering workflow for Mellow's iOS + TypeScript monorepo.

Philosophy

80% planning and review, 20% execution.

Each unit of engineering work should make subsequent units easier. The compound workflow captures learnings and feeds them back into the system.

Commands

Core Workflow

Command	Description
/workflows:plan	Research codebase and create implementation plan
/workflows:work	Execute implementation with MCP tool integration
/workflows:review	Run parallel review agents on changes
/workflows:compound	Document learnings to compound knowledge

Extended Commands

Command	Description
/deepen-plan	Enhance plan with parallel research agents
/triage	Route review findings into prioritized TODOs
/xcode-test	Build and test iOS app on simulator
/playwright-test	Run web tests and verify UI with Playwright
/resolve_parallel	Resolve multiple TODOs in parallel

Workflow Details

/workflows:plan

Research the codebase and create a structured implementation plan.

What it does:

• Detects platform (iOS, TypeScript, or database task)
• Researches existing patterns and conventions
• Creates a markdown plan with objectives, architecture, and success criteria

iOS Research:

• Reads PATTERN_GUIDELINES.md for Screen/View/ViewData/ViewActions pattern
• Checks MellowDesignSystem for available components
• Finds similar features for reference

TypeScript Research:

• Reads existing service routes and patterns
• Checks Zod schema usage
• Finds Fastify middleware patterns

/workflows:work

Execute implementation with MCP tool integration.

iOS Execution:

• Uses XcodeBuildMCP for build/test/run
• Enforces Screen/View/ViewData/ViewActions pattern
• Uses MellowDesignSystem tokens

TypeScript Execution:

• Runs type checking and linting
• Executes Vitest tests
• Uses Playwright for web verification

/workflows:review

Run parallel review agents on code changes.

Agents by file type (conditional activation):

• *.swift → ios-reviewer
• *.swift (UI files) → ios-reviewer, design-reviewer
• *.ts, *.tsx → typescript-reviewer
• *.tsx (UI files) → typescript-reviewer, design-reviewer
• *.sql → supabase-reviewer

Always run:

• security-reviewer
• quality-validator

Output: Unified review with P1/P2/P3 prioritized findings.

/workflows:compound

Document learnings to the compound knowledge base.

Categories:

• docs/compound/ios/ - Architecture, design system patterns
• docs/compound/typescript/ - Fastify, LangGraph patterns
• docs/compound/supabase/ - RLS, schema patterns
• docs/compound/cross-cutting/ - Shared patterns

/deepen-plan

Enhance an existing plan with parallel research agents.

Spawns agents for:

• Best practices research (Context7)
• Framework documentation lookup
• Git history analysis
• Codebase pattern search

/triage

Convert review findings into actionable TODOs.

Priority levels:

• P1: Blocks merge (security, architecture violations)
• P2: Should fix (patterns, performance)
• P3: Nice to have (style, improvements)

Output: Structured TODO files in .claude/todos/

/xcode-test

Build and test iOS app on simulator using XcodeBuildMCP.

Steps:

1. Build for simulator
2. Run test suite
3. Analyze failures
4. Capture screenshots (optional)

/playwright-test

Run web tests and verify UI using Playwright MCP.

Capabilities:

• Navigate to pages and capture snapshots
• Interact with elements (click, type, fill forms)
• Take screenshots for visual verification
• Check console for errors
• Monitor network requests
• Test responsive layouts

Steps:

1. Navigate to target URL
2. Capture accessibility snapshot
3. Execute test interactions
4. Verify expected state
5. Capture screenshots

/resolve_parallel

Resolve multiple TODOs simultaneously.

Process:

1. Load TODO files from .claude/todos/
2. Group independent TODOs
3. Spawn parallel resolver agents
4. Collect results and update status
5. Verify all fixes with build/test

Agents

Review Agents

Agent	Purpose
ios-reviewer	iOS architecture, design system, and code quality
typescript-reviewer	TypeScript code quality, strict typing, and @mellow/types usage
supabase-reviewer	Database patterns and RLS policies
security-reviewer	Security audit across stacks
performance-reviewer	Performance analysis
design-reviewer	UX patterns: entity mapping, state completeness, copy, accessibility
quality-validator	Run actual lint/type-check/test/build commands (mandatory gate)

Research Agents

Agent	Purpose
researcher	Codebase patterns, framework docs, git history, best practices

Design Agents

Agent	Purpose
figma-design-sync	Compare implementation with Figma designs

Skills

Atomic, composable skills referenced by agents and workflows.

Verification

Skill	Purpose
quality-gate	Platform-aware lint/type-check/test/build commands

Knowledge

Skill	Purpose
todo-management	TODO file format, priority levels, lifecycle
compound-knowledge	Compound doc format, routing, templates

Research

Skill	Purpose
codebase-search	Glob/Grep/Read patterns for finding code
context7-lookup	Framework documentation queries
git-history	Git log/show/diff/blame analysis

Automation

Skill	Purpose
ios-ui-automation	XcodeBuildMCP session, build, test, UI interactions
web-ui-automation	Playwright navigation, interactions, debugging

Git

Skill	Purpose
git-workflow	Commit conventions, branch strategy, worktrees

MCP Integration

The plugin leverages existing MCP servers:

• XcodeBuildMCP - iOS build, test, simulator, UI automation
• Playwright - Web browser testing
• Supabase - Database management, migrations, advisors
• Context7 - Framework documentation lookup
• Figma - Design context and screenshots

Quick Start

# Plan a feature
/workflows:plan Add user preferences screen to iOS app

# Enhance the plan with research
/deepen-plan

# Execute the plan
/workflows:work

# Test iOS changes
/xcode-test

# Test web changes
/playwright-test

# Review the changes
/workflows:review

# Convert findings to TODOs
/triage

# Fix issues in parallel
/resolve_parallel

# Document what you learned
/workflows:compound

Key Files

File	Purpose
CLAUDE.md	Core requirements for all reviewers
apps/mobile/Mellow/Core/Architecture/PATTERN_GUIDELINES.md	iOS architecture spec
apps/mobile/MellowDesignSystem/	Design system components
docs/compound/	Compound knowledge base
.claude/todos/	Structured TODO tracking

File Structure

.claude/plugins/mellow-engineering/
├── plugin.json
├── README.md
├── commands/
│   ├── workflows/
│   │   ├── plan.md
│   │   ├── work.md
│   │   ├── review.md
│   │   └── compound.md
│   ├── deepen-plan.md
│   ├── design-plan.md
│   ├── design-check.md
│   ├── triage.md
│   ├── xcode-test.md
│   ├── playwright-test.md
│   └── resolve_parallel.md
├── agents/
│   ├── review/
│   │   ├── ios-reviewer.md          # Architecture + design system + simplicity
│   │   ├── typescript-reviewer.md   # Types + patterns + simplicity
│   │   ├── supabase-reviewer.md
│   │   ├── security-reviewer.md
│   │   ├── performance-reviewer.md
│   │   ├── design-reviewer.md       # Entity mapping + states + copy + a11y
│   │   └── quality-validator.md     # Runs actual lint/test/build
│   ├── research/
│   │   └── researcher.md            # All research: codebase, docs, git, web
│   └── design/
│       └── figma-design-sync.md
└── skills/
    ├── quality-gate.md          # Verification commands
    ├── todo-management.md       # TODO format and lifecycle
    ├── compound-knowledge.md    # Compound doc patterns
    ├── codebase-search.md       # Code search patterns
    ├── context7-lookup.md       # Framework doc queries
    ├── git-history.md           # Git analysis patterns
    ├── ios-ui-automation.md     # XcodeBuildMCP interactions
    ├── web-ui-automation.md     # Playwright interactions
    └── git-workflow.md          # Commit conventions