task-startup

Original source / Raw SKILL.md

---
name: task-startup
description: Comprehensive work session initialization orchestrator that validates environment, creates properly named branches, and prepares development environment for new tasks
category: productivity
version: 2.0.0
---

# Task-Startup Skill

**Comprehensive work session initialization orchestrator** for consistent and reliable task startup.

## Purpose

Automate session-start workflows by:
- Validating git status and working directory cleanliness
- Checking and auto-fixing development environment (Docker, database, dependencies)
- Creating properly named feature branches from develop
- Logging session start timestamps

## When to Use

Trigger this skill when:
- Starting a new development task or feature
- Beginning work on a new task
- Setting up environment for development session
- Need to ensure clean git state before starting work
- Keywords: "start task", "begin work", "new task", "startup task"

## Core Workflow

### Phase 1: Configuration Management

**Check for shared configuration file**:
1. Look for `.task_wrapup_skill_data.json` in current working directory
2. This file is shared with task-wrapup skill for consistency
3. If not found, create default configuration by prompting user for:
   - Project name
   - Default base branch (typically "development")
   - Docker configuration (enabled, services, health check URL)
   - Environment validation preferences

**Configuration location**: `.task_wrapup_skill_data.json` in project root

**Manage configuration**:
```bash
# Create new config (interactive)
scripts/config_manager.py create

# Create with project name
scripts/config_manager.py create --project-name "MyProject"

# Show current config
scripts/config_manager.py show

# Validate config
scripts/config_manager.py validate

# Get config file path
scripts/config_manager.py path
```

### Phase 2: Preflight Validation

**Execute preflight checks** using `scripts/preflight-checks.sh`:

1. **Verify git repository**: Ensure current directory is a git repository
2. **Check current branch**: Get current branch name for validation
3. **Protected branch check**: Abort if on main/master/production branches
4. **Working directory status**: Check for uncommitted changes
5. **Stash detection**: Warn about stashed work that may need attention
6. **Base branch verification**: Confirm on development or prepare to switch

**Exit codes**:
- `0`: All checks passed
- `1`: On protected branch (cannot start task)
- `2`: Uncommitted changes detected
- `3`: Stashed work detected
- `4`: Not a git repository

**Behavior**:
- Abort if on protected branch
- Warn and prompt user if uncommitted changes or stashes exist
- Prepare to switch to base branch if needed

**Environment variables**:
- `BASE_BRANCH`: Default base branch (default: "development")
- `PROTECTED_BRANCHES`: Space-separated protected branches (default: "main master production")

### Phase 3: Environment Health Checks

**Execute environment validation** using `scripts/environment-health.sh`:

#### Docker Validation
- Check if Docker daemon is running
- Verify container status
- **Auto-fix**: Start Docker services if configured and not running
- Test health endpoint if specified in config
- Wait for services to become ready

#### Database Validation
- Check for pending migrations (Rails-specific)
- **Auto-fix**: Run migrations automatically if configured
- Verify database connectivity

#### Dependencies Validation
- Check npm/yarn packages for outdated versions
- Check Ruby gems (bundler) status
- Alert on missing or outdated dependencies
- **Note**: Does not auto-update, only alerts

#### Environment Variables
- Verify .env files exist (.env, .env.development)
- Check critical environment variables are defined
- Warn about missing required variables

**Auto-fix behavior**:
- Docker services: Auto-start if `DOCKER_AUTO_START=true`
- Database migrations: Auto-run if `AUTO_MIGRATE=true`
- Dependencies: Alert only, no auto-fix
- Environment variables: Alert only, no auto-fix

**Exit codes**:
- `0`: All checks passed or auto-fixed
- `10`: Docker not running (auto-fix failed or disabled)
- `11`: Database not ready
- `12`: Pending migrations (auto-migrate disabled)
- `13`: Dependencies outdated
- `14`: Environment variables missing

**Environment variables**:
- `DOCKER_ENABLED`: Enable Docker checks (default: "true")
- `DOCKER_AUTO_START`: Auto-start Docker if not running (default: "true")
- `DOCKER_HEALTH_URL`: Health endpoint to test (default: "http://localhost:3000/health")
- `CHECK_MIGRATIONS`: Enable migration checks (default: "true")
- `AUTO_MIGRATE`: Auto-run migrations (default: "true")
- `CHECK_DEPS`: Enable dependency checks (default: "true")

### Phase 4: Task Name Resolution

**Determine task name to work on**:

**If user provides task name in initial prompt**:
- Use the user-provided task name directly
- Skip to Phase 5: Branch Creation

**If user does NOT provide task name in initial prompt**:
- Present menu of options:
  - **a) Specify task name**: User provides task name for branch creation
  - **b) Use default task name**: Use a generic timestamp-based name
  - **c) Skip task name**: Create branch without specific task name (uses "new-task")
- Wait for user selection before proceeding

**Task name formatting**:
- Should be concise and descriptive (e.g., "user-auth", "payment-api", "fix-login")
- Will be automatically sanitized (lowercase, hyphens for spaces)
- Max length: 30 characters (to keep branch names reasonable)

### Phase 5: Branch Creation

**Create feature branch** using `scripts/branch-create.sh`:

**Branch naming convention**:
- Pattern: `feature/{sanitized-task-name}`
- Max length: 50 characters
- Sanitization: lowercase, hyphens for spaces/special chars

**Examples**:
- Task name "user-auth": `feature/user-auth`
- Task name "Payment API": `feature/payment-api`
- Task name "Fix Dashboard Loading": `feature/fix-dashboard-loading`

**Execution**:
```bash
# With task name
scripts/branch-create.sh "user-auth"

# Without task name (uses default)
scripts/branch-create.sh
```

**Behavior**:
1. Capture current branch as parent branch (for PR automation)
2. Switch to base branch (development) if not already there
3. Create new branch with sanitized name
4. Checkout new branch
5. Create session state file (`.task_session_state.json`) for PR automation
6. Display confirmation with branch name

**Session State File**:
The branch creation process automatically creates `.task_session_state.json` in the project root to enable automated pull request creation via the task-wrapup skill. This file tracks:
- Parent branch (for PR targeting)
- Feature branch name
- Task name
- Session creation timestamp

**Important**: `.task_session_state.json` should be added to `.gitignore` as it contains local session state.

**Environment variables**:
- `BRANCH_PREFIX`: Branch prefix (default: "feature")
- `MAX_LENGTH`: Max branch name length (default: 50)
- `BASE_BRANCH`: Base branch to create from (default: "development")

### Phase 6: Session Initialization & OmniFocus Integration

**Automatic OmniFocus Task Creation** (if configured):

When OmniFocus integration is enabled, the skill automatically creates a task in OmniFocus to track your work session:

1. **Check Configuration**: Verifies `omnifocus.auto_log_tasks` is enabled and `omnifocus.project_name` is set
2. **Load Session State**: Reads `.task_session_state.json` for task context
3. **Create OmniFocus Task**: Executes `scripts/session-init.py` to create task via OmniFocus skill
4. **Store Task ID**: Saves OmniFocus task ID back to session state for later completion

**OmniFocus Task Details**:
- **Task Name**: `Work on: {task-name}` (e.g., "Work on: user-auth")
- **Project**: Configured OmniFocus project name
- **Notes**: Includes branch name, parent branch, timestamp, and session context
- **Purpose**: Tracks work sessions in OmniFocus for time management and task completion

**Execution** (automatic via skill):
```bash
python3 scripts/session-init.py --directory .
```

**Configuration Commands**:
```bash
# Set OmniFocus project for this directory
python3 scripts/config_manager.py set-omnifocus --omnifocus-project "Development"

# Get current OmniFocus project
python3 scripts/config_manager.py get-omnifocus

# Example output: Development
```

**Session State Integration**:
The OmniFocus task ID is stored in `.task_session_state.json`:
```json
{
  "task_name": "user-auth",
  "branch_name": "feature/user-auth",
  "parent_branch": "development",
  "created_at": "2025-01-15T14:30:22",
  "omnifocus_task_id": "abc123xyz",
  "omnifocus_created_at": "2025-01-15T14:30:25"
}
```

**Task Completion**: When you complete your work session using the task-wrapup skill, the OmniFocus task is automatically marked as complete using the stored task ID.

**Log session start** (traditional logging):
1. Record timestamp of session start
2. Record branch name created
3. Record task name
4. Store in session log (if configured)

**Session log structure** (if enabled):
```
.claude/sessions/2025-01-15-143022.md

# Session Start: 2025-01-15 14:30:22

**Branch**: feature/user-auth
**Task**: user-auth
**Started**: 2025-01-15 14:30:22
**OmniFocus Task**: abc123xyz
```

**Purpose**: Future time tracking, session analytics, work pattern analysis, OmniFocus task management integration

### Phase 7: Final Summary

**Display session initialization results**:
- ✅ Preflight checks passed
- ✅ Environment health validated (with auto-fixes applied)
- ✅ Task name: user-auth
- ✅ Branch created: feature/user-auth
- ✅ Session logged

**Ready to work**: Environment prepared and ready for task implementation

**Note**: The user is responsible for describing and coordinating the task implementation themselves.

## Configuration Schema

Configuration shared with task-wrapup skill in `.task_wrapup_skill_data.json`:

```json
{
  "schema_version": "1.0",
  "project_name": "MyProject",
  "created_at": "2025-01-15T10:30:00",
  "last_updated": "2025-01-15T10:30:00",

  "task_start": {
    "default_base_branch": "development",
    "protected_branches": ["main", "master", "production"],

    "branch_naming": {
      "prefix": "feature",
      "max_length": 50
    },

    "environment": {
      "docker": {
        "enabled": true,
        "auto_start": true,
        "health_check_url": "http://localhost:3000/health",
        "services": ["backend", "frontend", "db"]
      },
      "database": {
        "check_migrations": true,
        "auto_migrate": true
      },
      "dependencies": {
        "check_updates": true,
        "package_managers": ["npm", "bundler"]
      },
      "env_files": {
        "required": [".env", ".env.development"],
        "critical_vars": ["DATABASE_URL", "SECRET_KEY_BASE"]
      }
    },

    "logging": {
      "session_logs_dir": ".claude/sessions",
      "track_start_time": true,
      "create_session_file": false
    }
  },

  "omnifocus": {
    "project_name": "Development",
    "auto_log_tasks": true,
    "prompt_if_missing": true
  },

  "summary_generation": { ... },
  "communication": { ... },
  "worklog": { ... },
  "documentation": { ... }
}
```

## Usage Examples

### Basic Usage - Start New Task with Name
```
User: "Start new task for user-auth"
```

The skill will:
1. Run preflight checks (git status, working directory)
2. Validate environment (Docker, DB, dependencies)
3. Extract task name "user-auth" from prompt
4. Create branch: `feature/user-auth`
5. Display ready-to-work confirmation

### Start Task - Prompt for Name
```
User: "Start task"
```

The skill will:
1. Run all validation checks
2. Prompt: "What is the task name?" with options:
   - a) Specify task name
   - b) Use default (timestamp-based)
   - c) Skip (uses "new-task")
3. Create branch from task name
4. Ready to work

### Start Task with Inline Name
```
User: "Startup task payment-api"
```

The skill will:
1. Complete all validation
2. Use "payment-api" as task name
3. Create branch: `feature/payment-api`
4. Display confirmation

## Error Handling

### Preflight Failures

**Protected Branch Error**:
```
❌ Cannot start new task from protected branch: main
   New tasks must be started from development branch
```
**Action**: Switch to development manually or let skill switch automatically

**Uncommitted Changes**:
```
⚠️  Uncommitted changes detected:
 M backend/app/models/user.rb
 M frontend/src/components/Login.tsx

Please commit or stash changes before starting new task
```
**Action**: Commit changes or stash, then re-run skill

**Stashed Work**:
```
⚠️  3 stashed change(s) detected:
stash@{0}: WIP on feature/old-task: abc123 work in progress
stash@{1}: WIP on feature/another: def456 more work
stash@{2}: WIP on develop: ghi789 old stash

Consider applying or clearing stashes before starting new task
```
**Action**: Review and clear stashes, or continue with warning

### Environment Failures

**Docker Not Running**:
```
⚠️  No Docker containers running
🔄 Attempting to start Docker services...
✅ Docker services started
```
**Auto-fix**: Starts services automatically if enabled

**Pending Migrations**:
```
⚠️  5 pending migration(s) detected
🔄 Running migrations...
✅ Migrations complete
```
**Auto-fix**: Runs migrations automatically if enabled

**Outdated Dependencies**:
```
⚠️  12 outdated npm package(s)
   Run 'npm outdated' to see details
```
**Action**: User decides whether to update before proceeding

## Integration with Other Skills

### Task-Wrapup Skill
- **Shared configuration**: Uses same `.task_wrapup_skill_data.json` file
- **Complementary workflow**: task-startup begins session, task-wrapup ends it
- **Session continuity**: Session logs can inform wrap-up summaries

## Bundled Scripts

### scripts/config_manager.py
**Purpose**: Manage shared configuration file

**Features**:
- Create new configuration (interactive or scripted)
- Load and validate existing configuration
- Compatible with task-wrapup skill configuration
- Schema validation and migration support

**CLI**:
```bash
python3 scripts/config_manager.py create [--project-name NAME] [--directory DIR]
python3 scripts/config_manager.py show [--directory DIR]
python3 scripts/config_manager.py validate [--directory DIR]
python3 scripts/config_manager.py path [--directory DIR]

# OmniFocus Integration
python3 scripts/config_manager.py set-omnifocus --omnifocus-project "Development" [--directory DIR]
python3 scripts/config_manager.py get-omnifocus [--directory DIR]
```

### scripts/preflight-checks.sh
**Purpose**: Git and working directory validation

**Features**:
- Protected branch detection
- Working directory cleanliness check
- Stash detection and warning
- Base branch verification
- Non-destructive (read-only checks)

**Environment**: BASE_BRANCH, PROTECTED_BRANCHES

### scripts/environment-health.sh
**Purpose**: Development environment validation and auto-fixing

**Features**:
- Docker daemon and container checks with auto-start
- Database migration status with auto-migrate
- Dependency version checking (npm, bundler)
- Environment variable validation
- Intelligent auto-fix capabilities

**Environment**: DOCKER_ENABLED, DOCKER_AUTO_START, DOCKER_HEALTH_URL, CHECK_MIGRATIONS, AUTO_MIGRATE, CHECK_DEPS, CRITICAL_VARS

### scripts/branch-create.sh
**Purpose**: Consistent branch naming and creation

**Features**:
- Automatic name sanitization
- Length constraints (50 chars)
- Lowercase normalization
- Base branch switching

**Environment**: BRANCH_PREFIX, MAX_LENGTH, BASE_BRANCH

### scripts/session-init.py
**Purpose**: OmniFocus task creation during session initialization

**Features**:
- Automatic OmniFocus task creation for work sessions
- Integration with OmniFocus skill via omnifocus_manager.rb
- Reads configuration from .task_wrapup_skill_data.json
- Loads session state from .task_session_state.json
- Stores OmniFocus task ID back to session state
- Dry-run mode for testing without creating tasks

**CLI**:
```bash
# Create OmniFocus task automatically
python3 scripts/session-init.py --directory .

# Dry-run mode (test without creating)
python3 scripts/session-init.py --directory . --dry-run
```

**Requirements**:
- OmniFocus skill installed at ~/.claude/skills/omnifocus/
- OmniFocus project configured via config_manager.py
- Session state file exists (.task_session_state.json)

**Output** (JSON):
```json
{
  "status": "success",
  "message": "OmniFocus task created successfully",
  "task_id": "abc123xyz",
  "task_name": "Work on: user-auth",
  "project": "Development"
}
```

**Error Handling**:
- Skips if OmniFocus auto-logging disabled
- Prompts if project name not configured
- Reports errors if OmniFocus script fails
- Non-blocking: skill continues even if OmniFocus creation fails

## Best Practices

### Configuration Strategy
1. Create configuration once per project
2. Commit `.task_wrapup_skill_data.json` to version control if team-shared
3. Add to `.gitignore` if contains sensitive data
4. Update configuration as project needs evolve

### Workflow Integration
1. Always start tasks with this skill for consistency
2. Let auto-fix handle environment issues when safe
3. Use descriptive task names for clarity
4. User is responsible for task description and coordination

### Team Coordination
1. Establish team conventions for task naming
2. Use consistent base branch across team
3. Document protected branches in configuration
4. Share configuration file structure for new projects

## Future Enhancements

### Planned Features
- Team notification when starting tasks
- Time estimation integration
- Dependency auto-update option
- Multiple branch naming conventions
- Task tracking integration (Jira/Linear)

### Potential Improvements
- IDE integration for automatic environment setup
- Serena memory integration for context loading
- Task dependency checking
- Automated code review prep
- Integration with /sc:load for project context

---

**Author**: Claude Code SuperClaude Framework
**License**: MIT
**Repository**: ~/.claude/skills/task-startup/
**Version**: 2.0.0


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/config_manager.py

```python
#!/usr/bin/env python3
"""
Configuration manager for task-start skill.
Shares configuration file with task-wrapup skill (.task_wrapup_skill_data.json).
"""

import json
import os
import sys
from datetime import datetime
from pathlib import Path
from typing import Dict, Any, Optional

CONFIG_FILENAME = ".task_wrapup_skill_data.json"
SCHEMA_VERSION = "1.0"

class ConfigManager:
    """Manages shared configuration file for task-start and task-wrapup skills."""

    def __init__(self, project_dir: str = "."):
        self.project_dir = Path(project_dir).resolve()
        self.config_path = self.project_dir / CONFIG_FILENAME

    def exists(self) -> bool:
        """Check if config file exists."""
        return self.config_path.exists()

    def load(self) -> Dict[str, Any]:
        """Load configuration from file."""
        if not self.exists():
            raise FileNotFoundError(f"Config file not found: {self.config_path}")

        with open(self.config_path, 'r') as f:
            return json.load(f)

    def save(self, config: Dict[str, Any]) -> None:
        """Save configuration to file."""
        config['last_updated'] = datetime.now().isoformat()

        with open(self.config_path, 'w') as f:
            json.dump(config, f, indent=2)

    def create_default(self, project_name: str, **kwargs) -> Dict[str, Any]:
        """Create default configuration structure."""
        now = datetime.now().isoformat()

        config = {
            "schema_version": SCHEMA_VERSION,
            "project_name": project_name,
            "created_at": now,
            "last_updated": now,

            # Task-start specific configuration
            "task_start": {
                "default_base_branch": "development",
                "protected_branches": ["main", "master", "production"],
                "branch_naming": {
                    "prefix": "feature",
                    "include_issue_number": True,
                    "max_length": 50
                },
                "github": {
                    "enabled": True,
                    "default_behavior": "fetch_highest_priority",
                    "labels_priority_order": ["urgent", "high", "medium", "low"]
                },
                "environment": {
                    "docker": {
                        "enabled": True,
                        "auto_start": True,
                        "health_check_url": "http://localhost:3000/health",
                        "services": ["backend", "frontend", "db"]
                    },
                    "database": {
                        "check_migrations": True,
                        "auto_migrate": True
                    },
                    "dependencies": {
                        "check_updates": True,
                        "package_managers": ["npm", "bundler"]
                    },
                    "env_files": {
                        "required": [".env", ".env.development"],
                        "critical_vars": ["DATABASE_URL", "SECRET_KEY_BASE"]
                    }
                },
                "logging": {
                    "session_logs_dir": ".claude/sessions",
                    "track_start_time": True,
                    "create_session_file": False
                },
                "integrations": {
                    "frontend_debug_skill": True,
                    "invoke_on_github_issue": True
                }
            },

            # Shared configuration (used by task-wrapup)
            "summary_generation": kwargs.get("summary_generation", {
                "strategy": "hybrid",
                "sources": {
                    "git_commits": True,
                    "todo_tasks": True,
                    "serena_memory": True,
                    "file_changes": True
                }
            }),

            "communication": kwargs.get("communication", {
                "email": {"enabled": False, "recipients": []},
                "sms": {"enabled": False, "recipients": []},
                "slack": {"enabled": False, "channel": ""}
            }),

            "worklog": kwargs.get("worklog", {
                "enabled": False,
                "prompt_for_duration": True
            }),

            "documentation": kwargs.get("documentation", {
                "enabled": True,
                "auto_update": True,
                "paths": ["README.md", "CHANGELOG.md"]
            }),

            "omnifocus": kwargs.get("omnifocus", {
                "project_name": None,
                "auto_log_tasks": True,
                "prompt_if_missing": True
            })
        }

        return config

    def prompt_for_config(self) -> Dict[str, Any]:
        """Interactive configuration creation."""
        print("📋 Task-Start Configuration Setup")
        print("=" * 50)

        # Project name
        project_name = input("Project name: ").strip()
        if not project_name:
            print("❌ Project name is required")
            sys.exit(1)

        # Base branch
        base_branch = input("Default base branch [development]: ").strip() or "development"

        # Docker configuration
        docker_enabled = input("Is this a dockerized project? [Y/n]: ").strip().lower() != 'n'

        docker_config = {}
        if docker_enabled:
            docker_config = {
                "enabled": True,
                "auto_start": input("Auto-start Docker services? [Y/n]: ").strip().lower() != 'n',
                "health_check_url": input("Health check URL [http://localhost:3000/health]: ").strip() or "http://localhost:3000/health",
                "services": input("Docker services (comma-separated) [backend,frontend,db]: ").strip().split(',') or ["backend", "frontend", "db"]
            }
        else:
            docker_config = {"enabled": False}

        # GitHub integration
        github_enabled = input("Enable GitHub integration? [Y/n]: ").strip().lower() != 'n'

        # OmniFocus integration
        print("\n🎯 OmniFocus Integration")
        omnifocus_project = input("OmniFocus project name for this directory (leave blank to skip): ").strip()

        # Create config
        config = self.create_default(project_name)
        config["task_start"]["default_base_branch"] = base_branch
        config["task_start"]["environment"]["docker"] = docker_config
        config["task_start"]["github"]["enabled"] = github_enabled

        if omnifocus_project:
            config["omnifocus"]["project_name"] = omnifocus_project
            print(f"✅ OmniFocus project '{omnifocus_project}' will be used for task logging")

        return config

    def validate(self, config: Dict[str, Any]) -> tuple[bool, list[str]]:
        """Validate configuration structure."""
        errors = []

        # Check required top-level fields
        required_fields = ["schema_version", "project_name", "created_at"]
        for field in required_fields:
            if field not in config:
                errors.append(f"Missing required field: {field}")

        # Check task_start section
        if "task_start" not in config:
            errors.append("Missing task_start configuration section")
        else:
            task_start = config["task_start"]

            # Check required task_start fields
            if "default_base_branch" not in task_start:
                errors.append("Missing task_start.default_base_branch")

            if "environment" not in task_start:
                errors.append("Missing task_start.environment section")

        return len(errors) == 0, errors


def main():
    """CLI interface for configuration management."""
    import argparse

    parser = argparse.ArgumentParser(description="Manage task-start configuration")
    parser.add_argument("command", choices=["create", "show", "validate", "path", "set-omnifocus", "get-omnifocus"],
                       help="Command to execute")
    parser.add_argument("--directory", default=".", help="Project directory")
    parser.add_argument("--project-name", help="Project name (for create)")
    parser.add_argument("--omnifocus-project", help="OmniFocus project name (for set-omnifocus)")

    args = parser.parse_args()

    manager = ConfigManager(args.directory)

    if args.command == "create":
        if manager.exists():
            print(f"⚠️  Config file already exists: {manager.config_path}")
            overwrite = input("Overwrite? [y/N]: ").strip().lower() == 'y'
            if not overwrite:
                print("❌ Cancelled")
                sys.exit(0)

        if args.project_name:
            config = manager.create_default(args.project_name)
        else:
            config = manager.prompt_for_config()

        manager.save(config)
        print(f"✅ Configuration created: {manager.config_path}")

    elif args.command == "show":
        if not manager.exists():
            print(f"❌ Config file not found: {manager.config_path}")
            sys.exit(1)

        config = manager.load()
        print(json.dumps(config, indent=2))

    elif args.command == "validate":
        if not manager.exists():
            print(f"❌ Config file not found: {manager.config_path}")
            sys.exit(1)

        config = manager.load()
        valid, errors = manager.validate(config)

        if valid:
            print("✅ Configuration is valid")
        else:
            print("❌ Configuration validation failed:")
            for error in errors:
                print(f"  - {error}")
            sys.exit(1)

    elif args.command == "path":
        print(manager.config_path)

    elif args.command == "set-omnifocus":
        if not args.omnifocus_project:
            print("❌ OmniFocus project name is required")
            sys.exit(1)

        if not manager.exists():
            print(f"❌ Config file not found: {manager.config_path}")
            print("💡 Create a config file first with 'create' command")
            sys.exit(1)

        config = manager.load()
        config["omnifocus"]["project_name"] = args.omnifocus_project
        manager.save(config)
        print(f"✅ OmniFocus project set to: {args.omnifocus_project}")

    elif args.command == "get-omnifocus":
        if not manager.exists():
            print(f"❌ Config file not found: {manager.config_path}")
            sys.exit(1)

        config = manager.load()
        omnifocus_project = config.get("omnifocus", {}).get("project_name")

        if omnifocus_project:
            print(omnifocus_project)
        else:
            print("No OmniFocus project configured", file=sys.stderr)
            sys.exit(1)


if __name__ == "__main__":
    main()

```

### scripts/branch-create.sh

```bash
#!/usr/bin/env bash
#
# Branch creation script for task-startup skill
# Creates properly named feature branches from task names
#

set -e

# Colors
GREEN='\033[0;32m'
BLUE='\033[0;34m'
YELLOW='\033[1;33m'
NC='\033[0m'

# Configuration
BRANCH_PREFIX="${BRANCH_PREFIX:-feature}"
MAX_LENGTH="${MAX_LENGTH:-50}"
BASE_BRANCH="${BASE_BRANCH:-development}"

# Function to sanitize branch name
sanitize_name() {
    local name="$1"

    # Convert to lowercase
    name=$(echo "$name" | tr '[:upper:]' '[:lower:]')

    # Replace spaces and special chars with hyphens
    name=$(echo "$name" | sed 's/[^a-z0-9-]/-/g')

    # Remove multiple consecutive hyphens
    name=$(echo "$name" | sed 's/-\+/-/g')

    # Remove leading/trailing hyphens
    name=$(echo "$name" | sed 's/^-//;s/-$//')

    # Truncate to max length
    if [ ${#name} -gt $MAX_LENGTH ]; then
        name="${name:0:$MAX_LENGTH}"
        # Remove trailing hyphen if truncation created one
        name=$(echo "$name" | sed 's/-$//')
    fi

    echo "$name"
}

# Function to create branch name
create_branch_name() {
    local task_name="$1"

    local sanitized_name=$(sanitize_name "$task_name")
    echo "${BRANCH_PREFIX}/${sanitized_name}"
}

# Function to switch to base branch
switch_to_base() {
    local current_branch=$(git branch --show-current)

    if [ "$current_branch" != "$BASE_BRANCH" ]; then
        echo -e "${BLUE}🔄 Switching to base branch: $BASE_BRANCH${NC}"
        git checkout "$BASE_BRANCH"
    fi
}

# Function to create and checkout new branch
create_and_checkout() {
    local branch_name="$1"

    echo -e "${BLUE}🌿 Creating branch: $branch_name${NC}"

    # Create and checkout new branch
    git checkout -b "$branch_name"

    echo -e "${GREEN}✅ Branch created and checked out: $branch_name${NC}"
    echo
    echo "Current branch: $(git branch --show-current)"
}

# Function to create session state file
create_session_state() {
    local feature_branch="$1"
    local parent_branch="$2"
    local task_name="$3"
    local project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
    local state_file="${project_root}/.task_session_state.json"

    echo -e "${BLUE}📝 Creating session state...${NC}"

    # Generate ISO 8601 UTC timestamp
    local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

    # Build JSON
    cat > "$state_file" <<EOF
{
  "schema_version": "1.0",
  "created_at": "$timestamp",
  "feature_branch": "$feature_branch",
  "parent_branch": "$parent_branch",
  "task_name": "$task_name"
}
EOF

    if [ -f "$state_file" ]; then
        echo -e "${GREEN}✅ Session state created: $state_file${NC}"
    else
        echo -e "${YELLOW}⚠️  Warning: Failed to create session state${NC}"
    fi
}

# Main script
if [ $# -lt 1 ]; then
    echo "Usage: $0 <task-name>"
    echo
    echo "Examples:"
    echo "  $0 'user-auth'"
    echo "  $0 'payment-api'"
    echo "  $0 'fix-login'"
    exit 1
fi

TASK_NAME="$1"

# Generate branch name
BRANCH_NAME=$(create_branch_name "$TASK_NAME")

echo "📋 Branch Configuration:"
echo "   Task Name: $TASK_NAME"
echo "   Branch Name: $BRANCH_NAME"
echo

# Capture parent branch before switching
PARENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "$BASE_BRANCH")

# Switch to base branch if needed
switch_to_base

# Create and checkout new branch
create_and_checkout "$BRANCH_NAME"

# Create session state file for PR automation
create_session_state "$BRANCH_NAME" "$PARENT_BRANCH" "$TASK_NAME"

```

### scripts/session-init.py

```python
#!/usr/bin/env python3
"""
Session Initialization Script for Task-Startup Skill

Handles automatic OmniFocus task creation when starting a new work session.
Integrates with OmniFocus skill via omnifocus_manager.rb script.
"""

import json
import os
import sys
import subprocess
from datetime import datetime
from pathlib import Path
from typing import Dict, Any, Optional


class SessionInitializer:
    """Manages OmniFocus task creation during session startup."""

    def __init__(self, project_dir: str = "."):
        self.project_dir = Path(project_dir).resolve()
        self.config_path = self.project_dir / ".task_wrapup_skill_data.json"
        self.session_state_path = self.project_dir / ".task_session_state.json"
        self.omnifocus_script = Path.home() / ".claude" / "skills" / "omnifocus" / "scripts" / "omnifocus_manager.rb"

    def load_config(self) -> Optional[Dict[str, Any]]:
        """Load configuration from shared config file."""
        if not self.config_path.exists():
            print(json.dumps({
                "status": "error",
                "code": "NO_CONFIG",
                "message": f"Configuration file not found: {self.config_path}"
            }), file=sys.stderr)
            return None

        try:
            with open(self.config_path, 'r') as f:
                return json.load(f)
        except json.JSONDecodeError as e:
            print(json.dumps({
                "status": "error",
                "code": "INVALID_JSON",
                "message": f"Invalid JSON in config file: {e}"
            }), file=sys.stderr)
            return None
        except Exception as e:
            print(json.dumps({
                "status": "error",
                "code": "LOAD_ERROR",
                "message": f"Error loading config: {e}"
            }), file=sys.stderr)
            return None

    def load_session_state(self) -> Optional[Dict[str, Any]]:
        """Load current session state."""
        if not self.session_state_path.exists():
            print(json.dumps({
                "status": "error",
                "code": "NO_SESSION_STATE",
                "message": f"Session state file not found: {self.session_state_path}"
            }), file=sys.stderr)
            return None

        try:
            with open(self.session_state_path, 'r') as f:
                return json.load(f)
        except json.JSONDecodeError as e:
            print(json.dumps({
                "status": "error",
                "code": "INVALID_JSON",
                "message": f"Invalid JSON in session state: {e}"
            }), file=sys.stderr)
            return None
        except Exception as e:
            print(json.dumps({
                "status": "error",
                "code": "LOAD_ERROR",
                "message": f"Error loading session state: {e}"
            }), file=sys.stderr)
            return None

    def save_session_state(self, session_state: Dict[str, Any]) -> bool:
        """Save updated session state."""
        try:
            with open(self.session_state_path, 'w') as f:
                json.dump(session_state, f, indent=2)
            return True
        except Exception as e:
            print(json.dumps({
                "status": "error",
                "code": "SAVE_ERROR",
                "message": f"Error saving session state: {e}"
            }), file=sys.stderr)
            return False

    def create_omnifocus_task(self, task_name: str, project_name: str, notes: str) -> Optional[str]:
        """
        Create OmniFocus task using omnifocus_manager.rb script.

        Returns task ID if successful, None otherwise.
        """
        if not self.omnifocus_script.exists():
            print(json.dumps({
                "status": "error",
                "code": "SCRIPT_NOT_FOUND",
                "message": f"OmniFocus manager script not found: {self.omnifocus_script}"
            }), file=sys.stderr)
            return None

        try:
            # Build command
            cmd = [
                "ruby",
                str(self.omnifocus_script),
                "--create",
                "--name", task_name,
                "--project", project_name,
                "--notes", notes
            ]

            # Execute command
            result = subprocess.run(
                cmd,
                capture_output=True,
                text=True,
                timeout=30
            )

            if result.returncode != 0:
                print(json.dumps({
                    "status": "error",
                    "code": "OMNIFOCUS_ERROR",
                    "message": f"OmniFocus task creation failed: {result.stderr}"
                }), file=sys.stderr)
                return None

            # Parse output to extract task ID
            try:
                output = json.loads(result.stdout)
                if output.get("status") == "success" and "task_id" in output:
                    return output["task_id"]
                else:
                    print(json.dumps({
                        "status": "error",
                        "code": "INVALID_RESPONSE",
                        "message": f"Unexpected response from OmniFocus script: {result.stdout}"
                    }), file=sys.stderr)
                    return None
            except json.JSONDecodeError:
                print(json.dumps({
                    "status": "error",
                    "code": "PARSE_ERROR",
                    "message": f"Failed to parse OmniFocus script output: {result.stdout}"
                }), file=sys.stderr)
                return None

        except subprocess.TimeoutExpired:
            print(json.dumps({
                "status": "error",
                "code": "TIMEOUT",
                "message": "OmniFocus task creation timed out"
            }), file=sys.stderr)
            return None
        except Exception as e:
            print(json.dumps({
                "status": "error",
                "code": "EXECUTION_ERROR",
                "message": f"Error executing OmniFocus script: {e}"
            }), file=sys.stderr)
            return None

    def initialize_session(self) -> bool:
        """
        Main initialization method that creates OmniFocus task for new session.

        Returns True if successful, False otherwise.
        """
        # Load configuration
        config = self.load_config()
        if not config:
            return False

        # Check if OmniFocus integration is enabled
        omnifocus_config = config.get("omnifocus", {})
        if not omnifocus_config.get("auto_log_tasks", True):
            print(json.dumps({
                "status": "skipped",
                "message": "OmniFocus auto-logging is disabled in configuration"
            }))
            return True  # Not an error, just skipped

        # Get OmniFocus project name
        project_name = omnifocus_config.get("project_name")
        if not project_name:
            if omnifocus_config.get("prompt_if_missing", True):
                print(json.dumps({
                    "status": "warning",
                    "code": "NO_PROJECT",
                    "message": "No OmniFocus project configured. Use config_manager.py set-omnifocus to configure."
                }), file=sys.stderr)
            return True  # Not a hard failure

        # Load session state
        session_state = self.load_session_state()
        if not session_state:
            return False

        # Extract session information
        task_name = session_state.get("task_name", "New Task")
        branch_name = session_state.get("branch_name", "unknown-branch")
        parent_branch = session_state.get("parent_branch", "unknown")
        created_at = session_state.get("created_at", datetime.now().isoformat())

        # Build task notes with session context
        notes = f"""Work Session: {task_name}

Branch: {branch_name}
Parent Branch: {parent_branch}
Created: {created_at}

This task was automatically created by the task-startup skill.
Complete this task when you finish the work session using task-wrapup skill."""

        # Create OmniFocus task
        task_id = self.create_omnifocus_task(
            task_name=f"Work on: {task_name}",
            project_name=project_name,
            notes=notes
        )

        if not task_id:
            return False

        # Store task ID in session state for later completion
        session_state["omnifocus_task_id"] = task_id
        session_state["omnifocus_created_at"] = datetime.now().isoformat()

        if not self.save_session_state(session_state):
            return False

        # Success output
        print(json.dumps({
            "status": "success",
            "message": "OmniFocus task created successfully",
            "task_id": task_id,
            "task_name": f"Work on: {task_name}",
            "project": project_name
        }))

        return True


def main():
    """Command-line interface for session initialization."""
    import argparse

    parser = argparse.ArgumentParser(description="Initialize work session with OmniFocus integration")
    parser.add_argument("--directory", default=".", help="Project directory")
    parser.add_argument("--dry-run", action="store_true", help="Simulate without creating task")

    args = parser.parse_args()

    if args.dry_run:
        print(json.dumps({
            "status": "info",
            "message": "Dry run mode - no task will be created"
        }))

    initializer = SessionInitializer(args.directory)
    success = initializer.initialize_session()

    sys.exit(0 if success else 1)


if __name__ == "__main__":
    main()

```

### scripts/preflight-checks.sh

```bash
#!/usr/bin/env bash
#
# Preflight checks for task-start skill
# Validates git status, working directory, and branch state
#

set -e

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# Configuration
BASE_BRANCH="${BASE_BRANCH:-development}"
PROTECTED_BRANCHES="${PROTECTED_BRANCHES:-main master production}"

# Exit codes
EXIT_SUCCESS=0
EXIT_PROTECTED_BRANCH=1
EXIT_UNCOMMITTED_CHANGES=2
EXIT_STASHED_WORK=3
EXIT_NOT_GIT_REPO=4

echo "🔍 Running preflight checks..."
echo

# Check if we're in a git repository
if ! git rev-parse --is-inside-work-tree > /dev/null 2>&1; then
    echo -e "${RED}❌ Not a git repository${NC}"
    exit $EXIT_NOT_GIT_REPO
fi

# Get current branch
CURRENT_BRANCH=$(git branch --show-current)
echo "📍 Current branch: $CURRENT_BRANCH"

# Check if on protected branch
for protected in $PROTECTED_BRANCHES; do
    if [ "$CURRENT_BRANCH" = "$protected" ]; then
        echo -e "${RED}❌ Cannot start new task from protected branch: $protected${NC}"
        echo -e "   New tasks must be started from $BASE_BRANCH branch"
        exit $EXIT_PROTECTED_BRANCH
    fi
done
echo -e "${GREEN}✅ Not on protected branch${NC}"

# Check for uncommitted changes
if ! git diff --quiet || ! git diff --cached --quiet; then
    echo -e "${YELLOW}⚠️  Uncommitted changes detected:${NC}"
    git status --short
    echo
    echo "Please commit or stash changes before starting new task"
    exit $EXIT_UNCOMMITTED_CHANGES
fi
echo -e "${GREEN}✅ No uncommitted changes${NC}"

# Check for stashed work
STASH_COUNT=$(git stash list | wc -l | tr -d ' ')
if [ "$STASH_COUNT" -gt 0 ]; then
    echo -e "${YELLOW}⚠️  $STASH_COUNT stashed change(s) detected:${NC}"
    git stash list | head -3
    echo
    echo "Consider applying or clearing stashes before starting new task"
    exit $EXIT_STASHED_WORK
fi
echo -e "${GREEN}✅ No stashed work${NC}"

# Check if on base branch
if [ "$CURRENT_BRANCH" != "$BASE_BRANCH" ]; then
    echo -e "${YELLOW}⚠️  Not on base branch ($BASE_BRANCH)${NC}"
    echo "   Will switch to $BASE_BRANCH before creating new branch"
else
    echo -e "${GREEN}✅ On base branch ($BASE_BRANCH)${NC}"
fi

echo
echo -e "${GREEN}✅ All preflight checks passed${NC}"
exit $EXIT_SUCCESS

```

### scripts/environment-health.sh

```bash
#!/usr/bin/env bash
#
# Environment health checks for task-start skill
# Validates Docker, database, dependencies, and environment variables
#

set -e

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Configuration from environment or defaults
DOCKER_ENABLED="${DOCKER_ENABLED:-true}"
DOCKER_AUTO_START="${DOCKER_AUTO_START:-true}"
DOCKER_HEALTH_URL="${DOCKER_HEALTH_URL:-http://localhost:3000/health}"
CHECK_MIGRATIONS="${CHECK_MIGRATIONS:-true}"
AUTO_MIGRATE="${AUTO_MIGRATE:-true}"
CHECK_DEPS="${CHECK_DEPS:-true}"

# Exit codes
EXIT_SUCCESS=0
EXIT_DOCKER_NOT_RUNNING=10
EXIT_DB_NOT_READY=11
EXIT_MIGRATIONS_PENDING=12
EXIT_DEPS_OUTDATED=13
EXIT_ENV_MISSING=14

echo "🏥 Running environment health checks..."
echo

# Function to check Docker status
check_docker() {
    if [ "$DOCKER_ENABLED" != "true" ]; then
        echo "⏭️  Docker checks skipped (not enabled)"
        return 0
    fi

    echo "🐳 Checking Docker status..."

    if ! command -v docker-compose &> /dev/null && ! command -v docker &> /dev/null; then
        echo -e "${YELLOW}⚠️  Docker not found (skipping Docker checks)${NC}"
        return 0
    fi

    # Check if Docker daemon is running
    if ! docker info &> /dev/null; then
        echo -e "${RED}❌ Docker daemon not running${NC}"
        return $EXIT_DOCKER_NOT_RUNNING
    fi

    # Check if containers are running
    if command -v docker-compose &> /dev/null; then
        RUNNING_CONTAINERS=$(docker-compose ps --services --filter "status=running" 2>/dev/null | wc -l | tr -d ' ')
    else
        RUNNING_CONTAINERS=$(docker ps --format '{{.Names}}' | wc -l | tr -d ' ')
    fi

    if [ "$RUNNING_CONTAINERS" -eq 0 ]; then
        echo -e "${YELLOW}⚠️  No Docker containers running${NC}"

        if [ "$DOCKER_AUTO_START" = "true" ]; then
            echo -e "${BLUE}🔄 Attempting to start Docker services...${NC}"
            if command -v docker-compose &> /dev/null; then
                docker-compose up -d
            else
                echo -e "${YELLOW}⚠️  docker-compose not found, cannot auto-start${NC}"
                return $EXIT_DOCKER_NOT_RUNNING
            fi

            # Wait a bit for services to start
            echo "⏳ Waiting for services to start..."
            sleep 5

            # Re-check
            if command -v docker-compose &> /dev/null; then
                RUNNING_CONTAINERS=$(docker-compose ps --services --filter "status=running" 2>/dev/null | wc -l | tr -d ' ')
            fi

            if [ "$RUNNING_CONTAINERS" -eq 0 ]; then
                echo -e "${RED}❌ Failed to start Docker services${NC}"
                return $EXIT_DOCKER_NOT_RUNNING
            fi
            echo -e "${GREEN}✅ Docker services started${NC}"
        else
            echo "   Auto-start disabled. Please start Docker manually:"
            echo "   docker-compose up -d"
            return $EXIT_DOCKER_NOT_RUNNING
        fi
    else
        echo -e "${GREEN}✅ Docker containers running: $RUNNING_CONTAINERS${NC}"
    fi

    # Check health endpoint if specified
    if [ -n "$DOCKER_HEALTH_URL" ]; then
        echo "🔍 Checking health endpoint: $DOCKER_HEALTH_URL"
        if curl -sf "$DOCKER_HEALTH_URL" > /dev/null 2>&1; then
            echo -e "${GREEN}✅ Health check passed${NC}"
        else
            echo -e "${YELLOW}⚠️  Health check failed (services may still be starting)${NC}"
        fi
    fi

    return 0
}

# Function to check database migrations
check_database() {
    if [ "$CHECK_MIGRATIONS" != "true" ]; then
        echo "⏭️  Database checks skipped"
        return 0
    fi

    echo
    echo "🗄️  Checking database migrations..."

    # Try Rails migrations check
    if [ -f "bin/rails" ] || [ -f "Gemfile" ]; then
        echo "📋 Checking Rails migrations..."

        # Check for pending migrations
        if command -v docker-compose &> /dev/null; then
            PENDING=$(docker-compose exec -T backend rails db:migrate:status 2>/dev/null | grep -c "^\s*down" || true)
        else
            PENDING=$(rails db:migrate:status 2>/dev/null | grep -c "^\s*down" || true)
        fi

        if [ "$PENDING" -gt 0 ]; then
            echo -e "${YELLOW}⚠️  $PENDING pending migration(s) detected${NC}"

            if [ "$AUTO_MIGRATE" = "true" ]; then
                echo -e "${BLUE}🔄 Running migrations...${NC}"
                if command -v docker-compose &> /dev/null; then
                    docker-compose exec -T backend rails db:migrate
                else
                    rails db:migrate
                fi
                echo -e "${GREEN}✅ Migrations complete${NC}"
            else
                echo "   Auto-migrate disabled. Please run:"
                echo "   docker-compose exec backend rails db:migrate"
                return $EXIT_MIGRATIONS_PENDING
            fi
        else
            echo -e "${GREEN}✅ No pending migrations${NC}"
        fi
    else
        echo "⏭️  No Rails detected, skipping migration check"
    fi

    return 0
}

# Function to check dependencies
check_dependencies() {
    if [ "$CHECK_DEPS" != "true" ]; then
        echo "⏭️  Dependency checks skipped"
        return 0
    fi

    echo
    echo "📦 Checking dependencies..."

    # Check npm/yarn
    if [ -f "package.json" ]; then
        echo "🔍 Checking npm/yarn packages..."
        if command -v npm &> /dev/null; then
            OUTDATED=$(npm outdated 2>/dev/null | tail -n +2 | wc -l | tr -d ' ')
            if [ "$OUTDATED" -gt 0 ]; then
                echo -e "${YELLOW}⚠️  $OUTDATED outdated npm package(s)${NC}"
                echo "   Run 'npm outdated' to see details"
            else
                echo -e "${GREEN}✅ npm packages up to date${NC}"
            fi
        fi
    fi

    # Check bundler
    if [ -f "Gemfile" ]; then
        echo "🔍 Checking Ruby gems..."
        if command -v bundle &> /dev/null; then
            if bundle check &> /dev/null; then
                echo -e "${GREEN}✅ Ruby gems satisfied${NC}"
            else
                echo -e "${YELLOW}⚠️  Missing or outdated gems${NC}"
                echo "   Run 'bundle install' or 'docker-compose exec backend bundle install'"
            fi
        fi
    fi

    return 0
}

# Function to check environment variables
check_environment() {
    echo
    echo "🔐 Checking environment variables..."

    # Check for .env files
    if [ -f ".env" ]; then
        echo -e "${GREEN}✅ .env file found${NC}"
    else
        echo -e "${YELLOW}⚠️  .env file not found${NC}"
    fi

    if [ -f ".env.development" ]; then
        echo -e "${GREEN}✅ .env.development file found${NC}"
    else
        echo -e "${YELLOW}⚠️  .env.development file not found (may be optional)${NC}"
    fi

    # Check critical environment variables (if .env exists)
    if [ -f ".env" ]; then
        CRITICAL_VARS="${CRITICAL_VARS:-DATABASE_URL SECRET_KEY_BASE}"
        MISSING_VARS=()

        for var in $CRITICAL_VARS; do
            if ! grep -q "^${var}=" .env 2>/dev/null; then
                MISSING_VARS+=("$var")
            fi
        done

        if [ ${#MISSING_VARS[@]} -gt 0 ]; then
            echo -e "${YELLOW}⚠️  Missing critical environment variables:${NC}"
            for var in "${MISSING_VARS[@]}"; do
                echo "   - $var"
            done
        else
            echo -e "${GREEN}✅ Critical environment variables present${NC}"
        fi
    fi

    return 0
}

# Run all checks
FAILED=0

check_docker || FAILED=$?
check_database || FAILED=$?
check_dependencies || FAILED=$?
check_environment || FAILED=$?

echo
if [ $FAILED -eq 0 ]; then
    echo -e "${GREEN}✅ All environment health checks passed${NC}"
else
    echo -e "${YELLOW}⚠️  Some health checks failed (code: $FAILED)${NC}"
    echo "   Fix issues above or continue with caution"
fi

exit $FAILED

```