# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an MCP (Model Context Protocol) Server for development workflow automation, specifically designed to support iOS (Swift) and Android (Kotlin) projects. The server provides token-optimized tools that detect project type, track Git workflow status, run code quality checks, and provide phase-specific guidance following Conventional Commits and Git Flow standards.

## Common Commands

### Build and Development
```bash
# Install dependencies
npm install

# Build the project (compiles TypeScript to dist/)
npm run build

# Run in development mode
npm run dev

# Lint the codebase
npm run lint
```

### Testing the MCP Server
After building, test the server by adding it to Claude Code's MCP settings (`~/.claude/mcp.json`):
```json
{
  "mcpServers": {
    "dev-flow": {
      "command": "node",
      "args": ["/absolute/path/to/dev-flow-mcp/dist/index.js"]
    }
  }
}
```

## Architecture

### Core Components

**`src/index.ts`** - Main MCP server entry point
- Sets up the MCP server with tools, prompts, and resources
- Implements per-tool caching with separate TTLs (project: 60s, git: 5s, quality: 10s)
- Defines 5 main tools: `dev_status`, `dev_flow`, `dev_fix`, `dev_check`, `dev_next`
- Exposes prompts for proactive Claude suggestions
- Provides subscribable resources via `dev://status` and `dev://config`

**`src/detector.ts`** - Project type detection
- Auto-detects iOS projects (`.xcodeproj`, `.xcworkspace`, `Podfile`, Swift files)
- Auto-detects Android projects (`build.gradle`, `settings.gradle`, `AndroidManifest.xml`)
- Returns `ProjectInfo` with type, name, path, source directory, and config files
- Checks for available tools (swiftlint, swiftformat, ktlint, detekt, gradle, etc.)

**`src/git/workflow.ts`** - Git workflow analysis
- Determines workflow phase based on branch, changes, commits, and PR status
- Extracts task IDs from branch names (e.g., `TASK-123` from `feature/TASK-123-description`)
- Integrates with GitHub CLI (`gh`) to fetch PR status (OPEN/MERGED/CLOSED)
- Supports Git Flow patterns (feature/, release/, hotfix/ branches)

**`src/platforms/ios.ts`** - iOS-specific quality checks
- Runs SwiftLint for linting (count-only, no full output)
- Runs SwiftFormat for formatting checks
- Provides fix commands: `swiftformat` + `swiftlint --fix`
- Executes commands quietly with output redirected to temp files to minimize token usage

**`src/platforms/android.ts`** - Android-specific quality checks
- Runs ktlint via Gradle for linting and formatting
- Runs detekt for static analysis
- Auto-detects `./gradlew` or falls back to `gradle`
- Provides fix commands: `./gradlew ktlintFormat`

### Workflow Phases

The system tracks 8 workflow phases:
- `IDLE` - On master/main, ready for new task
- `STARTING` - Need to create feature branch
- `DEVELOPING` - On feature branch with changes
- `READY_TO_PUSH` - Has unpushed commits
- `WAITING_QA` - Pushed, waiting for QA testing
- `PR_OPEN` - PR created and under review
- `PR_MERGED` - PR merged, returned to master
- `READY_TO_RELEASE` - Ready to create release tag (commits since last tag)

### Token Optimization Strategy

All tools are designed to minimize token usage:
- **Ultra-compact output formats** using pipes (`|`) and emoji symbols
- **Per-tool caching** prevents redundant executions (separate TTLs for project/git/quality data)
- **Count-only checks** - tools return only error/warning counts, not full output
- **Quiet execution** - command output redirected to temp files, only summaries returned
- **Smart summarization** - only last few lines of logs kept when errors occur

Example: `dev_status` returns `DEVELOPING|❌3|fix` (30 tokens vs 100+ tokens for verbose status)

### Data Flow

1. **Project Detection**: `detectProjectType()` scans for project markers, cached for 60s
2. **Git Analysis**: `getWorkflowStatus()` checks branch/commits/PRs, cached for 5s
3. **Quality Checks**: Platform-specific linters run, cached for 10s
4. **Tool Response**: Formatted minimal output returned to Claude
5. **Next Action**: Phase-specific command suggestions follow Conventional Commits format

### Standards Compliance

**Conventional Commits**: All commit suggestions use `type(scope): message` format
- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

**Git Flow**: Branch naming follows patterns
- `feature/*` for new features
- `release/*` for release preparation
- `hotfix/*` for production fixes

**PR Templates**: Structured with summary and testing checklist

## Key Implementation Details

- The server uses `@modelcontextprotocol/sdk` v1.25.1 for MCP protocol implementation
- All child processes use `execSync` with `stdio: ['pipe', 'pipe', 'pipe']` to capture output
- Temporary log files are created in `os.tmpdir()` and cleaned up after use
- Error handling is defensive - failures return zeros/empty strings rather than crashing
- The `getCached()` helper ensures data consistency across multiple tool calls in the same session

## Extending the Server

To add a new platform (e.g., web frontend):
1. Create `src/platforms/{platform}.ts` with quality check functions
2. Add detection logic to `src/detector.ts`
3. Import and integrate in `src/index.ts` tool handlers
4. Follow the token-optimization patterns (count-only, quiet execution, caching)