Repository Readiness Skill

Automatically prepare repositories for new work by analyzing configuration, structure, mission, and establishing complete work context.

Quick Start

# Manual trigger
/repo-readiness

# Auto-triggers before:
# - New task execution
# - Feature development
# - SPARC workflow initiation
# - Agent assignment

# Direct check
./scripts/check_repo_readiness.sh <repo-name>

When to Use

AUTO-EXECUTES (via hook):

Before starting any new task in a repository
When switching to a different repository
Before SPARC specification phase
Before agent assignment for new work

MANUAL TRIGGER:

When repository context is unclear
Before major refactoring
After long breaks from a repository
When onboarding to an existing project
Before cross-repo coordination

Prerequisites

Repository is cloned locally
Git is initialized
Read access to repository files
(Optional) Internet for external documentation lookup

Overview

The repo-readiness skill performs comprehensive analysis of a repository to establish complete work context before executing any new tasks. It replaces manual context gathering with automated, systematic preparation.

What It Analyzes

Configuration: CLAUDE.md, .claude/, .agent-os/
Structure: Directory organization, module architecture
Mission: Product vision, objectives, technical decisions
State: Git status, dependencies, environment setup
Standards: Compliance with workspace-hub standards
Context: Historical decisions, conventions, patterns

Output

Generates a comprehensive readiness report with:

Configuration summary
Structure analysis
Mission & objectives extraction
Readiness assessment (✅ Ready / ⚠️ Needs Attention / ❌ Not Ready)
Recommended actions
Context for AI agents

Core Operations

1. Configuration Analysis

Analyzes:

✓ Root CLAUDE.md
✓ .claude/CLAUDE.md (extended config)
✓ .claude.json (MCP settings)
✓ .mcp.json (MCP servers)
✓ .agent-os/ configuration
✓ Repository-specific rules

Extracts:

Critical rules and constraints
File organization standards
Testing requirements
AI agent guidelines
Tool preferences (UV, pytest, etc.)
Integration points

Example Output:

## Configuration Summary

### CLAUDE.md Status: ✅ Found
- **Location**: /root/CLAUDE.md
- **Critical Rules**:
  - TDD mandatory
  - YAGNI principle
  - UV environment required
- **File Organization**: Modular structure enforced
- **Testing**: pytest with 80% coverage minimum
- **AI Guidelines**: Question before implementation

### Extended Config: ✅ Found (.claude/CLAUDE.md)
- SPARC methodology enabled
- MCP integration configured
- HTML reporting standards defined

### MCP Configuration: ✅ Found
- Tools available: 47 MCP tools

2. Structure Assessment

Analyzes:

✓ Directory organization
✓ Module architecture
✓ File naming conventions
✓ Test structure
✓ Documentation presence
✓ Script organization

Checks Against:

FILE_ORGANIZATION_STANDARDS.md
Repository best practices
Module patterns
Naming conventions

Example Output:

## Structure Assessment

### Directory Organization: ✅ Compliant

repo/ ├── src/ ✅ Present │ └── modules/ ✅ Modular structure ├── tests/ ✅ Present │ ├── unit/ ✅ Organized │ └── integration/ ✅ Organized ├── docs/ ✅ Present ├── config/ ✅ Present ├── scripts/ ✅ Present ├── data/ ✅ Present └── reports/ ✅ Present


### Module Architecture: ✅ Well-Organized
- **Modules Found**: 5
  - data_processor/
  - visualization/
  - analysis/
  - reporting/
  - utilities/

### Naming Conventions: ⚠️ Minor Issues
- ✅ Python files use snake_case
- ✅ Modules use lowercase
- ⚠️ 2 files need organization (see details)

### Test Coverage: ✅ Good
- Unit tests: 45 files
- Integration tests: 12 files
- Test coverage: 85% (target: 80%)

3. Mission & Objectives Extraction

Sources:

✓ .agent-os/product/mission.md
✓ .agent-os/product/tech-stack.md
✓ .agent-os/product/roadmap.md
✓ .agent-os/product/decisions.md
✓ README.md
✓ docs/OVERVIEW.md

Extracts:

Project purpose and vision
Key objectives
Technical stack
Architecture decisions
Current roadmap
Recent decisions

Example Output:

## Mission & Objectives

### Project Purpose
Energy data analysis and visualization platform for offshore oil & gas operations.

### Key Objectives
1. Process BSEE production data with 99.9% accuracy
2. Generate interactive HTML reports with Plotly
3. NPV analysis for economic evaluation
4. Marine safety incident tracking
5. Support 10+ concurrent analysis workflows

### Technical Stack
- **Language**: Python 3.11+
- **Environment**: UV package manager
- **Testing**: pytest with 85% coverage
- **Visualization**: Plotly (interactive only)
- **Data**: Pandas, Polars
- **Reporting**: HTML with embedded plots

### Recent Decisions (Last 30 Days)
1. Migrated to UV from pip (2024-12-15)
2. Standardized on Plotly for all visualizations (2024-12-10)
3. Implemented SPARC workflow (2024-12-01)

4. State Assessment

Checks:

✓ Git status (clean/dirty)
✓ Branch information
✓ Remote status
✓ Dependencies installed
✓ Environment setup
✓ Recent commits
✓ Open issues/PRs

Example Output:

## Repository State

### Git Status: ✅ Clean
- **Branch**: main
- **Commits ahead**: 0
- **Commits behind**: 0
- **Uncommitted changes**: None
- **Last commit**: 2024-12-20 14:23 - "Update NPV calculation logic"

### Environment: ✅ Ready
- UV environment: ✅ Detected (.venv/)
- Dependencies: ✅ Synchronized (pyproject.toml == uv.lock)
- Python version: ✅ 3.11.7

### Dependencies Status: ⚠️ 2 Updates Available
- plotly: 5.17.0 → 5.18.0 (minor)
- pandas: 2.1.3 → 2.1.4 (patch)

5. Standards Compliance

Validates:

✓ Logging standards
✓ Testing framework standards
✓ HTML reporting standards
✓ File organization standards
✓ Development workflow compliance

Example Output:

## Standards Compliance

### Logging Standards: ✅ Compliant
- Standard format implemented
- Five log levels configured
- Rotation configured (10MB, 5 backups)

### Testing Standards: ✅ Compliant
- pytest configured
- Coverage threshold: 80% (current: 85%)
- Unit + integration tests present

### HTML Reporting: ✅ Compliant
- Interactive plots only (Plotly)
- CSV data with relative paths
- Reports in reports/ directory

### File Organization: ✅ Compliant
- Modular src/ structure
- Tests mirror source
- Documentation organized

6. Context Preparation

Generates:

✓ AI agent context summary
✓ Key conventions to follow
✓ Common patterns
✓ Recent changes
✓ Known issues
✓ Quick reference

Example Output:

## AI Agent Context

### Key Conventions
- **Imports**: Use absolute imports from src/
- **Testing**: Write tests before implementation (TDD)
- **Data Loading**: Use relative paths from reports/
- **Error Handling**: Use custom exceptions in src/exceptions.py
- **Logging**: Use module-level logger = logging.getLogger(__name__)

### Common Patterns
1. **Data Pipeline**: load → validate → process → visualize → report
2. **Configuration**: YAML files in config/input/ directory
3. **Execution**: Bash scripts in scripts/ directory
4. **Reporting**: HTML with Plotly in reports/ directory

### Recent Changes (Last 7 Days)
- Refactored NPV calculation to support multiple discount rates
- Added new marine safety incident categorization
- Updated BSEE data extractor for 2024 format
- Enhanced error handling in data validation

### Known Issues
- Issue #42: Slow performance on files >100MB (workaround documented)
- Issue #38: Timezone handling in date parsing (fix in progress)

### Quick Reference
- Main entry point: `scripts/run_analysis.sh`
- Configuration: `config/input/<feature>.yaml`
- Documentation: `docs/README.md`
- Examples: `examples/`

Readiness Assessment

Overall Readiness Score

Calculated from:

Configuration completeness (25%)
Structure compliance (20%)
Mission clarity (15%)
State health (20%)
Standards adherence (20%)

Readiness Levels:

✅ READY (90-100%)
   - All critical checks passed
   - Minor issues documented
   - Safe to proceed with new work

⚠️ NEEDS ATTENTION (70-89%)
   - Some issues need addressing
   - Can proceed with caution
   - Fix issues before major work

❌ NOT READY (<70%)
   - Critical issues present
   - Must resolve before proceeding
   - Blocks new work

Example Assessment

## Overall Readiness: ✅ READY (95%)

### Breakdown
- Configuration: ✅ 100% (All configs present and valid)
- Structure: ✅ 95% (2 minor file organization issues)
- Mission: ✅ 100% (Clear objectives and roadmap)
- State: ✅ 90% (2 dependency updates available)
- Standards: ✅ 95% (Full compliance, minor logging improvement)

### Recommended Actions
1. 📦 Update plotly to 5.18.0 (optional, minor version)
2. 📁 Organize 2 files in src/utilities/ into subfolders
3. 📝 Add logging to new marine_safety module (standard practice)

### Safe to Proceed: ✅ YES
All critical requirements met. Recommended actions can be addressed incrementally.

Execution Checklist

Pre-Check:

Repository path is valid
Git repository initialized
Read access to all files

Analysis Phase:

Reporting Phase:

Post-Check:

Save readiness report to .claude/readiness-report.md
Update repository context cache
Provide summary to user or agent

Hook Integration

Pre-Task Hook

This skill auto-executes as a pre-task hook:

Hook Configuration:

# .claude/hooks/pre-task.sh
#!/bin/bash
# Auto-execute repo-readiness before any task

REPO_PATH="$(pwd)"
SKILL_PATH="$HOME/.claude/skills/workspace-hub/repo-readiness"

# Execute readiness check
"$SKILL_PATH/check_readiness.sh" "$REPO_PATH"

# Exit code determines if task can proceed
# 0 = Ready, 1 = Not ready (blocks task)
exit $?

Trigger Conditions:

/create-spec command
/execute-tasks command
/plan-product command
Any SPARC workflow phase
Agent assignment via orchestrator

Bypass Hook (when needed):

# Force task execution even if not ready
SKIP_READINESS_CHECK=1 /execute-tasks "task description"

Post-Task Hook (Optional)

Update readiness state after work:

# .claude/hooks/post-task.sh
#!/bin/bash
# Update readiness cache after task completion

REPO_PATH="$(pwd)"
TASK_ID="$1"

# Re-run readiness to update cache
"$HOME/.claude/skills/workspace-hub/repo-readiness/check_readiness.sh" "$REPO_PATH" --update-cache

# Log task completion
echo "$(date): Task $TASK_ID completed" >> .claude/task-history.log

Automation Scripts

1. Check Readiness Script

Location: .claude/skills/workspace-hub/repo-readiness/check_readiness.sh

#!/bin/bash
# Repository Readiness Check Script

REPO_PATH="${1:-.}"
OUTPUT_FILE="${REPO_PATH}/.claude/readiness-report.md"

# Function: Check configuration
check_configuration() {
    local score=0

    # Check CLAUDE.md
    if [ -f "${REPO_PATH}/CLAUDE.md" ]; then
        echo "✅ Root CLAUDE.md found"
        ((score += 25))
    else
        echo "❌ Root CLAUDE.md missing"
    fi

    # Check extended config
    if [ -f "${REPO_PATH}/.claude/CLAUDE.md" ]; then
        echo "✅ Extended CLAUDE.md found"
        ((score += 25))
    fi

    # Check .agent-os
    if [ -d "${REPO_PATH}/.agent-os" ]; then
        echo "✅ Agent OS configuration found"
        ((score += 25))
    fi

    # Check MCP config
    if [ -f "${REPO_PATH}/.claude.json" ] || [ -f "${REPO_PATH}/.mcp.json" ]; then
        echo "✅ MCP configuration found"
        ((score += 25))
    fi

    echo "Configuration Score: ${score}/100"
    return $score
}

# Function: Check structure
check_structure() {
    local score=0
    local required_dirs=("src" "tests" "docs" "config" "scripts")

    for dir in "${required_dirs[@]}"; do
        if [ -d "${REPO_PATH}/${dir}" ]; then
            echo "✅ ${dir}/ present"
            ((score += 20))
        else
            echo "⚠️ ${dir}/ missing"
        fi
    done

    echo "Structure Score: ${score}/100"
    return $score
}

# Function: Check mission
check_mission() {
    local score=0

    if [ -f "${REPO_PATH}/.agent-os/product/mission.md" ]; then
        echo "✅ Mission defined"
        ((score += 50))
    fi

    if [ -f "${REPO_PATH}/.agent-os/product/roadmap.md" ]; then
        echo "✅ Roadmap defined"
        ((score += 50))
    fi

    echo "Mission Score: ${score}/100"
    return $score
}

# Function: Check state
check_state() {
    local score=0

    cd "$REPO_PATH" || exit 1

    # Check git status
    if git diff-index --quiet HEAD -- 2>/dev/null; then
        echo "✅ Git working directory clean"
        ((score += 50))
    else
        echo "⚠️ Uncommitted changes present"
        ((score += 25))
    fi

    # Check environment
    if [ -d ".venv" ] || [ -d "venv" ]; then
        echo "✅ Virtual environment detected"
        ((score += 50))
    fi

    echo "State Score: ${score}/100"
    return $score
}

# Main execution
main() {
    echo "========================================"
    echo "Repository Readiness Check"
    echo "Repository: ${REPO_PATH}"
    echo "Timestamp: $(date)"
    echo "========================================"
    echo ""

    # Run all checks
    check_configuration
    local config_score=$?

    check_structure
    local struct_score=$?

    check_mission
    local mission_score=$?

    check_state
    local state_score=$?

    # Calculate overall score
    local overall_score=$(( (config_score*25 + struct_score*20 + mission_score*15 + state_score*20) / 80 ))

    echo ""
    echo "========================================"
    echo "Overall Readiness: ${overall_score}%"

    if [ $overall_score -ge 90 ]; then
        echo "Status: ✅ READY"
        echo "========================================"
        return 0
    elif [ $overall_score -ge 70 ]; then
        echo "Status: ⚠️ NEEDS ATTENTION"
        echo "========================================"
        return 1
    else
        echo "Status: ❌ NOT READY"
        echo "========================================"
        return 2
    fi
}

main "$@"

2. Bulk Readiness Check

Check all repos in workspace:

#!/bin/bash
# Check readiness of all repositories in workspace-hub

WORKSPACE_ROOT="/mnt/github/workspace-hub"
READINESS_SCRIPT="$HOME/.claude/skills/workspace-hub/repo-readiness/check_readiness.sh"

# Get all repos from .gitignore
repos=$(grep -E "^[a-z].*/$" "${WORKSPACE_ROOT}/.gitignore" | sed 's/\///')

echo "Checking readiness of all repositories..."
echo ""

# Track results
ready_count=0
attention_count=0
not_ready_count=0

for repo in $repos; do
    repo_path="${WORKSPACE_ROOT}/${repo}"

    if [ -d "$repo_path" ]; then
        echo "Checking: $repo"

        if "$READINESS_SCRIPT" "$repo_path" > /dev/null 2>&1; then
            echo "  ✅ READY"
            ((ready_count++))
        else
            exit_code=$?
            if [ $exit_code -eq 1 ]; then
                echo "  ⚠️ NEEDS ATTENTION"
                ((attention_count++))
            else
                echo "  ❌ NOT READY"
                ((not_ready_count++))
            fi
        fi
    fi
done

echo ""
echo "Summary:"
echo "  Ready: $ready_count"
echo "  Needs Attention: $attention_count"
echo "  Not Ready: $not_ready_count"

Error Handling

Missing Configuration

Error: CLAUDE.md not found

❌ Critical: No CLAUDE.md found in repository root

Action Required:
1. Create CLAUDE.md with repository configuration
2. Use template from workspace-hub/templates/CLAUDE.md
3. Re-run readiness check

Quick Fix:
cp ~/workspace-hub/templates/CLAUDE.md ./CLAUDE.md

Incomplete Structure

Error: Required directories missing

⚠️ Warning: Required directories missing
   Missing: tests/, docs/

Action Required:
1. Create missing directories
2. Follow FILE_ORGANIZATION_STANDARDS.md
3. Re-run readiness check

Quick Fix:
mkdir -p tests/{unit,integration} docs config scripts

Unclear Mission

Error: No mission.md found

⚠️ Warning: Project mission not defined
   Missing: .agent-os/product/mission.md

Action Required:
1. Create .agent-os/product/mission.md
2. Define project purpose and objectives
3. Document technical decisions

Quick Fix:
mkdir -p .agent-os/product
cp ~/workspace-hub/templates/mission.md .agent-os/product/

Dirty Git State

Error: Uncommitted changes present

⚠️ Warning: Repository has uncommitted changes
   Files modified: 5

Action Required:
1. Review uncommitted changes: git status
2. Commit changes: git add . && git commit -m "message"
3. Or stash: git stash
4. Re-run readiness check

Environment Issues

Error: Virtual environment not found

⚠️ Warning: No virtual environment detected

Action Required:
1. Create UV environment: uv venv
2. Install dependencies: uv pip install -r requirements.txt
3. Activate environment: source .venv/bin/activate
4. Re-run readiness check

Metrics & Success Criteria

Performance Metrics

Metric	Target	Measurement
Check Time	< 5 seconds	Time to complete all checks
Accuracy	> 95%	Correct readiness assessment
False Positives	< 5%	Incorrectly marked as ready
False Negatives	< 2%	Incorrectly marked as not ready
Cache Hit Rate	> 80%	Using cached readiness data

Coverage Metrics

Metric	Target	Current
Repos with CLAUDE.md	100%	Track per repo
Repos with mission.md	100%	Track per repo
Structure compliance	> 95%	Average across repos
Standards adherence	> 90%	Average compliance score

Adoption Metrics

Metric	Target	Measurement
Hook installation	100% repos	Pre-task hook installed
Auto-execution rate	> 95%	Tasks with readiness check
Manual check usage	> 10/week	Explicit readiness checks
Issue detection	> 50%	Issues caught before work

Integration Points

With SPARC Workflow

Readiness check before each SPARC phase:

# Before Specification
/repo-readiness → Analyze context → /create-spec

# Before Architecture
/repo-readiness → Verify structure → /sparc-architecture

# Before Implementation
/repo-readiness → Check environment → /execute-tasks

With Compliance Check

Combined health validation:

# Readiness + compliance
/repo-readiness && /compliance-check

# Report both
./scripts/health-check.sh --full

With Agent Orchestration

Provide context to agents:

// Agent receives readiness report
{
  "task": "implement-feature-X",
  "repository": "digitalmodel",
  "readiness": {
    "status": "ready",
    "score": 95,
    "context": {
      "conventions": [...],
      "patterns": [...],
      "recent_changes": [...]
    }
  }
}

With Repo Sync

Ensure readiness before bulk operations:

# Check readiness before sync
./scripts/repository_sync sync all --check-readiness

Best Practices

1. Run Before Every New Task

# Always start with readiness check
/repo-readiness

# Then proceed with work
/create-spec "new feature"

2. Keep Configuration Updated

# Update CLAUDE.md when rules change
# Update mission.md when objectives change
# Update roadmap.md when priorities shift

3. Address Issues Promptly

# Don't ignore warnings
# Fix structural issues immediately
# Keep environment synchronized

4. Use Cache Wisely

# Cache valid for 1 hour by default
# Force refresh when configuration changes
/repo-readiness --force-refresh

5. Monitor Across All Repos

# Weekly bulk check
./scripts/bulk_readiness_check.sh > reports/readiness-$(date +%Y-%m-%d).txt

# Track trends
# Maintain >95% readiness across all repos

Related Skills

compliance-check - Standards validation
repo-sync - Multi-repo management
sparc-workflow - Development methodology
session-start-routine - Session initialization

References

Version History

1.0.0 (2026-01-07): Initial release - comprehensive repository readiness skill with configuration analysis, structure assessment, mission extraction, state checking, standards compliance, auto-hook integration, bulk checking capabilities, error handling, and metrics tracking