gitFlow/implementation.md

Git Flow — Detailed Development Plan

Overview

Git Flow is a Go CLI tool that discovers Git repositories under a user-specified parent directory, periodically scans their status, and presents findings with AI-driven suggestions for next actions (e.g., "commit pending changes", "push branch X", "pull latest from main").

---

Phase 0: Project Scaffolding & Tooling

Task	Details	Deliverable
Module init	go mod init github.com/<user>/gitflow	go.mod
Directory layout	Flat-to-modular structure appropriate for a CLI (see layout below)	Dir tree
Tooling	Add golangci-lint config, Makefile, .gitignore	Dev tooling
CI skeleton	GitHub Actions: lint + test on push	.github/workflows/ci.yml

Recommended Directory Layout

gitflow/
├── cmd/gitflow/          # main entry point
├── internal/
│   ├── scanner/          # repo discovery + git status scanning
│   ├── presenter/        # output formatting (table, JSON, TUI)
│   ├── scheduler/        # periodic scan loop
│   ├── ai/               # AI agent integration
│   ├── config/           # CLI flags, env vars, config file parsing
│   └── git/              # thin wrappers around git commands
├── pkg/                  # shared types (RepoInfo, Status, etc.)
├── go.mod / go.sum
├── Makefile
├── .golangci.yml
└── readme.md

---

Phase 1: Core — Repo Discovery & Status Scanning

This is the foundational layer. Everything else depends on it.

1.1 Define the Domain Types (pkg/types.go or internal/scanner/types.go)

type RepoStatus int
const (
    StatusUnknown RepoStatus = iota
    StatusClean
    StatusModified
    StatusAhead
    StatusBehind
    StatusDiverged
    StatusDetached
    StatusBare
    StatusError
)

type RepoInfo struct {
    Path           string
    RemoteURL      string
    Branch         string
    Status         RepoStatus
    ModifiedFiles  []string
    StagedFiles    []string
    UntrackedFiles []string
    AheadBy        int
    BehindBy       int
    StashCount     int
    LastFetch      time.Time
    Error          string
}

type ScanResult struct {
    ScannedAt  time.Time
    ParentDir  string
    Repos      []RepoInfo
    TotalCount int
    ErrorCount int
}

1.2 Repo Discovery (internal/scanner/discover.go)

• Walk the directory tree starting from the parent directory
• Detect .git directories (including bare repos, submodules, worktrees)
• Respect .gitignore-style exclusion patterns via a --exclude flag
• Respect depth limits via a --depth / --max-depth flag
• Use filepath.WalkDir for efficient traversal (no os.FileInfo allocations)

Pattern: Single-responsibility — the discoverer only finds repos; status scanning is a separate step.

1.3 Status Scanner (internal/scanner/status.go)

• For each discovered repo, run git porcelain commands:
  • git status --porcelain -b for branch, ahead/behind, modified/staged/untracked
  • git remote -v for remote URL
  • git stash list for stash count
• Parse output into RepoInfo
• Resilience patterns from Go skill:
  • Timeout each git command (e.g., 10s via context.WithTimeout)
  • Handle repos with errors gracefully — mark as StatusError, don't crash
  • Run scans concurrently with a bounded worker pool (errgroup + semaphore)

1.4 Git Command Wrapper (internal/git/)

• Thin wrapper: func Status(ctx context.Context, repoPath string) (RepoInfo, error)
• Uses os/exec with context for cancellation/timeout
• No external git library dependency — os/exec is sufficient for porcelain commands

---

Phase 2: CLI & Configuration

2.1 CLI Framework

Use Cobra + Viper (standard Go CLI stack):

Flag	Type	Default	Description
--dir / -d	string	. (cwd)	Parent directory to scan
--interval / -i	duration	0 (run once)	Rescan interval (e.g., 5m, 30s)
--format / -f	string	table	Output format: table, json, compact
--exclude	[]string	[]	Glob patterns to exclude
--max-depth	int	0 (unlimited)	Max traversal depth
--ai	bool	false	Enable AI suggestions
--ai-provider	string	openai	AI backend
--ai-model	string	gpt-4o	AI model
--watch / -w	bool	false	Watch mode (alias for interval)

2.2 Configuration File

Support ~/.gitflow.yaml for defaults:

ai:
  provider: openai
  api_key_env: OPENAI_API_KEY
  model: gpt-4o
defaults:
  interval: 5m
  format: table
  exclude:
    - "node_modules"
    - "vendor"

2.3 Commands

gitflow scan          # one-shot scan
gitflow watch         # periodic scan (uses --interval)
gitflow config        # show/edit config
gitflow version       # version info

---

Phase 3: Presentation Layer

3.1 Table Output (default)

Rich terminal table using bubbletea / lipgloss (or simpler: tablewriter):

  REPOSITORY          BRANCH       STATUS     AHEAD/BEHIND   CHANGES
  ~/projects/api      main         ✓ clean         0 / 0        -
  ~/projects/web      feat/login   ✗ modified      3 / 0       2M, 1U
  ~/projects/lib      main         ⚠ behind        0 / 5        -
  ~/projects/legacy   (detached)   ⚠ detached      -           -

  4 repos scanned | 1 clean | 2 need attention | 2 errors

3.2 JSON Output

For scripting / piping:

{
  "scanned_at": "2026-01-01T12:00:00Z",
  "parent_dir": "/home/user/projects",
  "repos": [...],
  "summary": {"total": 4, "clean": 1, "attention": 2, "errors": 1}
}

3.3 Compact Output

One line per repo with color-coded status symbols.

---

Phase 4: Periodic Scanner (Scheduler)

4.1 Watch Mode (internal/scheduler/scheduler.go)

• Runs scan on a time.Ticker at the configured interval
• Clears terminal and re-renders (or uses TUI refresh)
• Handles SIGINT/SIGTERM for graceful shutdown
• Shows time until next scan in footer

Pattern: Use signal.NotifyContext for graceful shutdown. Defer cleanup immediately after resource acquisition.

4.2 Change Detection

• Between scans, compare current vs previous ScanResult
• Highlight repos that changed state
• Optionally trigger desktop notifications (via beeep or notify-send)

---

Phase 5: AI Agent Integration

5.1 AI Module (internal/ai/)

Interface-first design (for testability and provider flexibility):

type Provider interface {
    Suggest(ctx context.Context, repos []RepoInfo) ([]Suggestion, error)
}

type Suggestion struct {
    RepoPath string
    Action   string   // "commit", "push", "pull", "stash", "pr", "cleanup"
    Message  string   // Human-readable suggestion
    Command  string   // Suggested git command to run
    Priority int      // 0=low, 1=medium, 2=high
}

5.2 Providers

1. OpenAI (default): GPT-4o with structured output (JSON Schema) for reliable parsing
2. Ollama (local/offline): Support for local models
3. Anthropic Claude: Alternative cloud provider

5.3 Prompt Design

Construct a prompt that includes:

• A summary table of all repos and their statuses
• The top 3-5 repos needing attention
• Instructions to output structured JSON with specific action types

5.4 AI Output Display

• Show suggestions in a separate section below the status table
• Color-coded by priority
• Optional: --ai-execute flag to auto-run suggested commands (with confirmation)

---

Phase 6: Polish & Advanced Features

Feature	Description
Color themes	Light/dark terminal themes via lipgloss
TUI mode	Full interactive TUI with bubbletea — navigate repos, expand details, trigger AI suggestions
Custom actions	User-defined rules: "if behind > 10 commits, mark as critical"
Webhook/notifications	Send alerts to Slack/Discord when repos need attention
Multi-platform	Test on Linux, macOS, Windows (WSL)
Completion	Shell completions for bash, zsh, fish via Cobra

---

Technology Choices Summary

Concern	Choice	Rationale
CLI framework	Cobra + Viper	Industry standard, completions, env binding
Git interaction	os/exec (porcelain)	No dependency needed; porcelain output is stable
TUI (optional)	Bubble Tea + Lip Gloss	Best Go TUI ecosystem
AI integration	HTTP client + JSON Schema	Provider-agnostic, no heavy SDK required
Concurrency	errgroup + semaphore	Bounded parallelism, error propagation
Testing	testing + testify	Standard + assertions
Linting	golangci-lint	Comprehensive Go linting

---

Milestone Schedule

Milestone	Scope	Estimated Effort
M1 — Skeleton	Phase 0: module, layout, Makefile, CI	0.5 day
M2 — Discovery	Phase 1: repo walker + git status parser	1–2 days
M3 — CLI	Phase 2: Cobra commands, flags, config	1 day
M4 — Display	Phase 3: table + JSON + compact output	1 day
M5 — Watch	Phase 4: scheduler, auto-refresh, signals	1 day
M6 — AI	Phase 5: provider interface, OpenAI, suggestions	1–2 days
M7 — Polish	Phase 6: TUI, themes, completions, docs	2–3 days

Total estimated effort: ~7–10 days for a solid v1.0

---

Implementation Progress

All phases from this plan are implemented and merged into main (branch per phase, merged with --no-ff, no remote pushes).

Phase	Branch	Status
0 — Scaffolding	feat/phase-0-scaffolding	✅ done
1 — Discovery & scanning	feat/phase-1-discovery-scanning	✅ done
2 — CLI & configuration	feat/phase-2-cli-config	✅ done
3 — Presentation	feat/phase-3-presentation	✅ done
4 — Scheduler / watch	feat/phase-4-scheduler	✅ done
5 — AI agent	feat/phase-5-ai	✅ done
6 — Polish	feat/phase-6-polish	✅ done

Deviations from the plan

• LastFetch field dropped (phase 1): the only reliable source is a reflog of the remote-tracking ref, which does not exist on fresh clones; noted as future work instead.
• Full bubbletea TUI deferred (phase 6): the plan listed it as optional; watch mode + completions + themes + notifications were implemented instead.
• Webhooks deferred (phase 6): desktop notifications cover the alerting case; Slack/Discord noted as future work.
• AI defaults: ai-model defaults to gpt-4o (plan) with provider-specific fallbacks (ollama → llama3.2, anthropic → claude-3-5-haiku-latest); --ai-execute implemented with an allowlist + per-command confirmation instead of a bare auto-run.
• testify was not added: stdlib testing covers all suites, keeping the dependency tree minimal.