Skip to content

Core Concepts

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

Core Concepts

Understanding git-forest requires understanding its core concepts and metaphors. This guide explains the fundamental building blocks of the forest ecosystem.

The Forest Metaphor

git-forest uses a cultivation metaphor to describe software development:

  • Your codebase is a forest that needs cultivation
  • Plans define what you want to grow
  • Plants are individual work items (like seedlings)
  • Planners determine what needs to be planted
  • Planters do the actual work (like gardeners)
  • Harvesting means completing and integrating work

This metaphor shifts teams from "merge and forget" to cultivate and harvest.

Design Principles

git-forest is built on these core principles:

  1. Idempotent - Running the same command multiple times is safe
  2. Deterministic - Same inputs always produce same outputs
  3. Reconcile Desired State - Define what you want, not how to get there
  4. Automation-Friendly - Every command supports --json output
  5. Clear Ownership - Every field has a clear owner (plan/user/planter)
  6. Safe Concurrency - Locking prevents conflicts

?? Forest

The Forest represents the overall state of your git-forest installation in a repository.

What is a Forest?

A forest is:

  • Repository-local state stored in .git-forest/
  • Configuration files and metadata
  • Installed plans and their state
  • All plants and their lifecycle information
  • Planter assignments and workload

Forest Structure

.git-forest/
  forest.yaml              # Forest metadata
  config.yaml              # Configuration
  lock                     # Concurrency lock
  plans/<plan-id>/         # Installed plans
  plants/<planId__slug>/   # Plant state and history
  planters/<planter-id>/   # Planter state
  planners/<planner-id>/   # Planner definitions
  logs/                    # Activity logs

Forest Lifecycle

# Initialize a forest
git-forest init

# Check forest status
git-forest status

# View configuration
git-forest config show

?? Plan

A Plan is a versioned package that defines the desired state for your codebase in a specific area.

What is a Plan?

Plans contain:

  • Planners - Generators that analyze code and produce plants
  • Planters - Executors that work on plants
  • Plant Templates - Patterns for the work to be done
  • Scopes - What parts of the codebase to focus on
  • Policies - Rules for execution (safety, risk level, etc.)

Plan Sources

Plans can come from:

  • GitHub repositories - tweakch/git-forest-plans/sample
  • URLs - https://github.com/...
  • Local paths - ./local/plan or config/plans/...

Plan Catalog

git-forest includes 54 pre-defined plans across 10 categories:

Category Focus
Engineering Excellence Code health, sustainability
Quality & Reliability Testing, correctness
Performance & Scalability Speed, efficiency
Security & Compliance Security best practices
Team & Process Developer experience
Documentation & Knowledge Living docs
Evolution & Migration Strategic change
AI-Native AI-assisted development
Meta/Governance Plan management
Experimental Innovation

See Plans Catalog for complete details.

Working with Plans

# List installed plans
git-forest plans list

# Install a plan
git-forest plans install config/plans/engineering-excellence/dependency-hygiene.yaml

# Show plan details
git-forest plans show dependency-hygiene

# Reconcile a plan (generate plants)
git-forest plan dependency-hygiene reconcile

# Remove a plan
git-forest plans remove dependency-hygiene

?? Plant

A Plant is a concrete, trackable work item with a stable identity and lifecycle.

What is a Plant?

Each plant has:

  • Stable Key - planId:plantSlug (e.g., sample:backend-hygiene)
  • Status - Current lifecycle stage
  • Title & Description - What needs to be done
  • Assignments - Which planters are working on it
  • Branches - Associated git branches
  • History - Complete audit trail
  • Candidates - Proposed changes (diffs/PRs)

Plant Identity

Plants use a deterministic key format:

planId:plantSlug

Examples:

  • dependency-hygiene:remove-unused-packages
  • secret-hygiene:rotate-api-keys
  • test-coverage:add-unit-tests-auth

Plants can also be referenced by short forms like P01, P02 when unambiguous.

Plant Lifecycle

Plants follow this status flow:

planned ? planted ? growing ? harvestable ? harvested
                                          ?
                                      archived

Status Definitions:

  • planned - Plant created, no work started yet
  • planted - Planter assigned and working
  • growing - Changes are being proposed/applied
  • harvestable - Work complete, ready for integration
  • harvested - Integrated and closed
  • archived - Removed from active work (plan changed)

See Plant Lifecycle for complete details.

Working with Plants

# List all plants
git-forest plants list

# Filter by status
git-forest plants list --status planned

# Filter by plan
git-forest plants list --plan dependency-hygiene

# Show plant details
git-forest plant P01 show
git-forest plant dependency-hygiene:remove-unused show

# Assign a planter
git-forest plant P01 assign dependency-cleaner

# Set user-owned fields
git-forest plant P01 set priority high
git-forest plant P01 set notes "Focus on backend first"

# View history
git-forest plant P01 history

# Mark as harvested
git-forest plant P01 harvest

?? Planner

A Planner is a deterministic generator that produces a desired set of Plants from a Plan + repository context.

What is a Planner?

Planners:

  • Analyze your repository against a plan's goals
  • Generate plants deterministically
  • Always produce the same plant keys for the same input
  • Run during reconciliation

Planner Guarantees

Determinism: Same plan + repo context = same plant keys

# First reconcile
git-forest plan dependency-hygiene reconcile
# Plants: P01, P02, P03

# Second reconcile (no code changes)
git-forest plan dependency-hygiene reconcile
# Plants: P01, P02, P03 (same keys, no duplicates)

Planner Types

Planners typically fall into categories:

  • Code Analyzers - Scan code for patterns
  • Dependency Scanners - Analyze dependencies
  • Test Evaluators - Assess test coverage
  • Security Auditors - Find security issues
  • Documentation Checkers - Verify docs

Working with Planners

# List planners
git-forest planners list

# List planners for a specific plan
git-forest planners list --plan dependency-hygiene

# Run a specific planner
git-forest planner code-analyzer run --plan dependency-hygiene

?? Planter

A Planter is an executor or "agent" that proposes changes for plants under policy constraints.

What is a Planter?

Planters:

  • Are assigned to specific plants
  • Work on plants to produce changes
  • Can create branches, diffs, or PRs
  • Operate under capacity limits and policies
  • Can be built-in (from plans) or custom (user-defined)

Planter Modes

Propose Mode (safe):

  • Generates candidate diffs only
  • No direct code changes
  • Creates proposals for review

Apply Mode (requires permission):

  • May open PRs or apply patches
  • Requires proper configuration
  • Subject to policy constraints

Planter Capacity

Each planter has:

  • Available Capacity - How many plants it can handle
  • Active Assignments - Current workload
  • Capabilities - What types of work it can do

Working with Planters

# List planters
git-forest planters list

# Show planter details
git-forest planter dependency-cleaner show

# Assign planter to plant
git-forest plant P01 assign dependency-cleaner

# Or use planter-centric assignment
git-forest planter dependency-cleaner assign P01

# Plant with branch creation
git-forest planter dependency-cleaner plant P01 --branch auto --yes

# Grow the plant (propose changes)
git-forest planter dependency-cleaner grow P01 --mode propose

# Grow with apply mode (if allowed)
git-forest planter dependency-cleaner grow P01 --mode apply

# Unassign
git-forest plant P01 unassign dependency-cleaner

?? Reconciliation

Reconciliation is the core process that brings your forest to the desired state.

What is Reconciliation?

Reconciliation:

  1. Runs planners to determine desired state
  2. Compares desired state with current state
  3. Creates missing plants
  4. Updates plan-owned fields
  5. Archives removed plants
  6. Never overwrites user-owned fields

Reconciliation Contract

Guarantees:

  • Deterministic generation
  • Idempotent execution
  • Clear ownership boundaries
  • Safe to run multiple times
# Reconcile a plan
git-forest plan dependency-hygiene reconcile

# Dry-run (see what would change)
git-forest plan dependency-hygiene diff

# Reconcile with specific forum (AI vs file-based)
git-forest plan dependency-hygiene reconcile --forum ai
git-forest plan dependency-hygiene reconcile --forum file

Output Example:

Reconciling plan 'dependency-hygiene@v1.0.0'...
Planners: +2 ~0 -0
Planters: +3 ~1 -0
Plants:   +4 ~6 -0 (archived 0)
done

?? Ownership Model

git-forest has a clear ownership model for fields:

Plan-Owned Fields

Updated by reconcile:

  • Plant title
  • Plant description
  • Default priority
  • Scope assignments
  • Recommended planters

User-Owned Fields

Set by users, never overwritten:

  • Custom priority
  • User notes
  • Manual assignments
  • User-specific config

Planter-Owned Fields

Written by planters:

  • Candidate diffs
  • Analysis results
  • Health signals
  • Branch references

Drift Tracking

git-forest tracks when plan-owned fields are manually overridden:

  • plan_owned_hash - Last known plan value
  • user_overrides - User modifications

?? Concurrency & Locking

git-forest ensures safe concurrent access through locking.

Lock Mechanism

  • Lock File: .git-forest/lock
  • Timeout: Configurable via locks.timeoutSeconds
  • Lock Info: Owner process, timestamp, duration

Lock Behavior

# First process acquires lock
git-forest plan sample reconcile

# Second process attempts (blocks)
git-forest plan sample reconcile
# Error: Lock held by process 1234 for 5 seconds
# Exit code: 23

Configuration

# .git-forest/config.yaml
locks:
  timeoutSeconds: 15

?? Automation Support

git-forest is designed for CI/CD integration:

JSON Output

Every command supports --json:

git-forest status --json
git-forest plants list --json
git-forest plan sample reconcile --json

Stable Exit Codes

Code Meaning
0 Success
2 Invalid arguments
10 Forest not initialized
11 Plan not found
12 Plant not found
13 Planter not found
20 Schema validation failed
23 Lock timeout
30 Git operation failed
40 Execution not permitted

See Exit Codes Reference for complete list.

Configuration Layers

git-forest uses layered configuration:

Layer Priority

  1. User-level (highest): ~/.git-forest/config.yaml
  2. Repo-level: .git-forest/config.yaml
  3. Plan defaults (lowest): From plan package

Common Settings

# Git settings
git:
  remote: origin
  baseBranch: main

# Branch templates
branches:
  template: "{planter}/{plantSlug}"

# LLM profiles
llm:
  profile:
    default: gpt-forest-backend-v1

# Execution mode
execution:
  mode: manual  # or auto

# Lock settings
locks:
  timeoutSeconds: 15

Next Steps

Now that you understand the core concepts:

Key Takeaways

? Forest = Repository state in .git-forest/
? Plan = Versioned package defining desired improvements
? Planner = Deterministic generator creating plants
? Plant = Trackable work item with stable key and lifecycle
? Planter = Executor that proposes/applies changes
? Reconciliation = Process bringing forest to desired state

The forest metaphor helps teams think about continuous cultivation rather than one-time changes.

Clone this wiki locally