Skip to content

Repository Overview Guide

Jump to bottom
Alexander Klee edited this page Dec 18, 2025 · 1 revision

Repository Overview Guide

This comprehensive guide is designed for team leads who need a complete understanding of their git-forest repository's current state.

Overview

The repository-overview plan is a meta-governance plan that provides a holistic view across all dimensions of your forest by running multiple specialized planners.

When to Use This Plan

Use the repository-overview plan when you need to:

? Prepare for Sprint Planning - Understand current state before planning
? Generate Status Reports - Create comprehensive reports for stakeholders
? Conduct Team Reviews - Share complete picture during standups/retros
? Monitor Project Health - Set up continuous monitoring in CI/CD
? Onboard New Team Members - Give new members a complete picture
? Make Strategic Decisions - Have all data for technical debt prioritization

What This Plan Provides

The repository-overview plan analyzes 10 key dimensions:

1. ?? Repository Structure & Organization

  • Directory organization and layout
  • File naming conventions
  • Module boundaries and separation
  • Configuration consistency
  • Build system structure

2. ?? Code Health & Quality

  • Code complexity metrics
  • Duplication levels
  • Maintainability index
  • Technical debt hotspots
  • Code smells and anti-patterns

3. ?? Plan Catalog Status

  • Plan category coverage
  • Plan completeness
  • Plan metadata quality
  • Plan interdependencies
  • Missing plan areas

4. ?? Plant Lifecycle Analysis

  • Plants by status (planned, planted, growing, harvestable, harvested)
  • Age distribution
  • Completion trends
  • Stuck or blocked plants
  • Success rate metrics

5. ?? Planter Capacity & Workload

  • Active planters
  • Workload distribution per planter
  • Capability coverage
  • Performance metrics
  • Capacity constraints

6. ?? Documentation Completeness

  • API documentation coverage
  • User guides availability
  • Architecture documentation
  • Code comment quality
  • Documentation consistency with code

7. ?? CI/CD Pipeline Health

  • Build success rate
  • Test pass rate
  • Pipeline duration trends
  • Failure frequency
  • Reliability metrics

8. ? Test Coverage

  • Line coverage percentages
  • Branch coverage
  • Critical path coverage
  • Test distribution (unit, integration, e2e)
  • Test quality metrics

9. ?? Dependency Health

  • Outdated dependencies
  • Security vulnerabilities
  • License compliance
  • Dependency tree health
  • Update urgency assessment

10. ?? Technical Debt Inventory

  • Debt types and categories
  • Debt locations in codebase
  • Impact assessment
  • Resolution effort estimates
  • Debt trends over time

Quick Start

Installation & Basic Usage

# 1. Initialize forest (if not already done)
git-forest init

# 2. Install the repository overview plan
git-forest plans install config/plans/meta-governance/repository-overview.yaml

# 3. Reconcile the plan to generate analysis plants
git-forest plan repository-overview reconcile

# 4. View all generated plants
git-forest plants list --plan repository-overview

# 5. View detailed status
git-forest status

Generate Comprehensive Overview Report

# Reconcile to ensure latest analysis
git-forest plan repository-overview reconcile

# Generate the overview report plant
git-forest plant repository-overview:generate-repository-overview show

# Export to JSON for processing
git-forest plant repository-overview:generate-repository-overview show --json > overview-report.json

Update Status Dashboard

# Generate interactive dashboard
git-forest plant repository-overview:update-status-dashboard show

# Export dashboard data
git-forest plant repository-overview:update-status-dashboard show --json > dashboard.json

View Specific Analysis Dimensions

# Repository structure analysis
git-forest plant repository-overview:analyze-repository-structure show

# Code health assessment
git-forest plant repository-overview:assess-code-health show

# Plan catalog evaluation
git-forest plant repository-overview:evaluate-plan-catalog show

# Plant lifecycle analysis
git-forest plant repository-overview:analyze-plant-lifecycle show

# Planter capacity evaluation
git-forest plant repository-overview:evaluate-planter-capacity show

# Documentation completeness
git-forest plant repository-overview:check-documentation-completeness show

# CI pipeline health
git-forest plant repository-overview:assess-ci-pipeline-health show

# Test coverage
git-forest plant repository-overview:evaluate-test-coverage show

# Dependency health
git-forest plant repository-overview:analyze-dependency-health show

# Technical debt inventory
git-forest plant repository-overview:inventory-technical-debt show

Usage Scenarios

Scenario 1: Sprint Planning Preparation

Goal: Prepare for the upcoming sprint planning session

# Run the overview plan
git-forest plans install config/plans/meta-governance/repository-overview.yaml
git-forest plan repository-overview reconcile

# Get metrics summary
git-forest plants list --plan repository-overview --json > sprint-prep-metrics.json

# Review key areas
git-forest plant repository-overview:analyze-plant-lifecycle show
git-forest plant repository-overview:inventory-technical-debt show

Expected Outcome:

  • Complete picture of work in progress (plants by status)
  • Technical debt concentration map
  • Areas needing attention in next sprint
  • Planter capacity for new work

Scenario 2: Team Status Review

Goal: Provide status update during team standup or review

# Generate latest overview
git-forest plan repository-overview reconcile

# Create status report
git-forest plant repository-overview:generate-repository-overview show

# Get specific metrics
git-forest plant repository-overview:assess-code-health show
git-forest plant repository-overview:assess-ci-pipeline-health show

Expected Outcome: Comprehensive status report covering all key areas for team sharing

Scenario 3: Executive Summary

Goal: Create high-level summary for stakeholders or management

# Generate overview with focus on metrics
git-forest plan repository-overview reconcile
git-forest plant repository-overview:update-status-dashboard show --json

# Extract key metrics:
# - repository_health_score
# - code_quality_score
# - test_coverage_percentage
# - ci_success_rate
# - technical_debt_ratio

Expected Outcome: Data-driven executive summary with key health indicators

Scenario 4: Continuous Monitoring in CI

Goal: Set up automated daily overview reports

# Example GitHub Actions workflow
name: Forest Overview

on:
  push:
    branches: [ main ]
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

jobs:
  overview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup git-forest
        run: dotnet tool install --global git-forest
      
      - name: Initialize and run overview
        run: |
          git-forest init
          git-forest plans install config/plans/meta-governance/repository-overview.yaml
          git-forest plan repository-overview reconcile
          git-forest plants list --json > overview-status.json
      
      - name: Upload results
        uses: actions/upload-artifact@v3
        with:
          name: overview-report
          path: overview-status.json

Expected Outcome: Daily automated overview reports tracking repository health over time

Key Planners in Detail

repository-structure-analyzer

Purpose: Analyzes overall structure and organization
Identifies:

  • Directory organization issues
  • File naming inconsistencies
  • Module boundary violations
  • Configuration drift
  • Build system complexity

code-health-overview

Purpose: High-level assessment of code quality
Measures:

  • Cyclomatic complexity
  • Code duplication
  • Maintainability index
  • Technical debt concentration
  • Code smell frequency

plan-catalog-status

Purpose: Evaluates plan catalog completeness
Checks:

  • Coverage across all categories
  • Plan metadata completeness
  • Plan version consistency
  • Missing plan opportunities
  • Plan interdependency conflicts

plant-lifecycle-analyzer

Purpose: Analyzes plant ecosystem health
Tracks:

  • Status distribution
  • Age of plants in each status
  • Completion velocity
  • Blocked plants
  • Success rate trends

planter-capacity-analyzer

Purpose: Evaluates planter workload and capabilities
Monitors:

  • Active planters
  • Work distribution
  • Capability coverage
  • Performance metrics
  • Capacity bottlenecks

documentation-completeness

Purpose: Assesses documentation coverage and quality
Evaluates:

  • API documentation
  • User guides
  • Architecture docs
  • Code comments
  • Doc-code consistency

ci-pipeline-health

Purpose: Monitors CI/CD pipeline reliability
Tracks:

  • Build success rate
  • Test pass rate
  • Pipeline duration
  • Failure patterns
  • Stability trends

test-coverage-overview

Purpose: Comprehensive test coverage analysis
Measures:

  • Line coverage
  • Branch coverage
  • Critical path coverage
  • Test distribution
  • Test effectiveness

dependency-health-summary

Purpose: Summarizes dependency status and security
Identifies:

  • Outdated dependencies
  • Security vulnerabilities
  • License issues
  • Dependency tree complexity
  • Update priorities

technical-debt-inventory

Purpose: Inventories and categorizes technical debt
Maps:

  • Debt types
  • Debt locations
  • Impact assessment
  • Resolution effort
  • Debt accumulation trends

Key Planters in Detail

overview-reporter

Purpose: Generates comprehensive overview reports
Creates:

  • Markdown reports for human reading
  • JSON metrics for automation
  • HTML dashboards for visualization
  • Trend analysis over time

status-dashboard-generator

Purpose: Creates interactive status dashboards
Includes:

  • Health score gauges
  • Plant status charts
  • Code quality trends
  • Planter workload visualizations
  • CI pipeline timelines
  • Test coverage gauges
  • Dependency security alerts
  • Technical debt heatmaps

metrics-aggregator

Purpose: Aggregates metrics from multiple planners
Provides:

  • Metric collection from all sources
  • Data normalization
  • Statistical analysis
  • Trend detection
  • Comparative reports

Metrics & Targets

Key metrics tracked by the repository-overview plan:

Metric Target Description
repository_health_score 80+ Overall repository health
active_plans_count monitored Number of installed plans
plant_completion_rate 70%+ Percentage of completed work
code_quality_score 85+ Aggregated code quality
documentation_coverage 90%+ Documentation completeness
ci_pipeline_health 95%+ CI/CD success rate
technical_debt_ratio monitored Technical debt percentage

Safety & Policies

The repository-overview plan is designed with safety in mind:

? Read-only operations - Never modifies code or configuration
? Advisory only - All outputs are informational
? CI-safe - Can run in automated pipelines
? Deterministic - Same inputs produce same outputs
? Idempotent - Running multiple times is safe

Integration with Other Plans

The repository-overview plan complements other meta-governance plans:

  • forest-maintenance - Use overview to identify maintenance needs
  • forest-governance - Use overview metrics to inform governance policies
  • risk-aware-planning - Use overview to identify high-risk areas
  • harvest-discipline - Use overview to track completion progress

Tips for Team Leads

?? Run Regularly - Schedule daily or weekly for trend tracking
?? Focus on Trends - Single snapshots are useful, but trends are more valuable
?? Share with Team - Make overview results visible to entire team
?? Use for Planning - Let overview data drive sprint planning
?? Monitor Key Metrics - Track health score and key metrics over time
?? Identify Patterns - Look for patterns in plant lifecycle and planter workload
?? Address Bottlenecks - Use overview to identify and address bottlenecks early
?? Celebrate Progress - Use metrics to celebrate improvements with team

Customization

Customize the repository-overview plan by:

  1. Adjusting metric targets - Edit the metrics section in plan YAML
  2. Adding custom planners - Extend with your own analysis planners
  3. Modifying plant templates - Customize overview report types
  4. Changing execution mode - Adjust policies to fit workflow
  5. Setting resource limits - Tune resource usage for environment

Troubleshooting

Plan installation fails

# Ensure you're in a git repository
git status

# Ensure forest is initialized
git-forest init

Reconciliation produces no plants

# Check that the plan is installed
git-forest plans list

# Ensure planners are properly configured
cat config/plans/meta-governance/repository-overview.yaml

Plants show errors

# View plant details to see specific errors
git-forest plant repository-overview:<plant-name> show

# Check planter logs
ls -la .git-forest/logs/

Next Steps

Support

For questions or issues:

  1. Check Common Issues
  2. Review FAQ
  3. Visit GitHub Issues

Clone this wiki locally