sepehr
4f7e808855
Next.js dashboard with git statistics, AI-powered summaries via Ollama, and research documents for project planning. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
37 KiB
stepsCompleted, status, completedAt, inputDocuments, workflowType, project_name, user_name, date
| stepsCompleted | status | completedAt | inputDocuments | workflowType | project_name | user_name | date | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
complete | 2025-04-25 |
|
epics-and-stories | GitPulse | Ramez | 2025-04-25 |
GitPulse - Epic Breakdown
Overview
This document provides the complete epic and story breakdown for GitPulse, decomposing the requirements from the PRD, UX Design, and Architecture requirements into implementable stories.
Requirements Inventory
Functional Requirements
FR1: The user can initiate a recursive disk scan to discover Git repositories on their machine
FR2: The user can configure which root directories to scan
FR3: The user can exclude directories from scanning via a .gitpulseignore file (glob syntax)
FR4: The system can detect Git repositories by identifying .git folders
FR5: The user can manually trigger a rescan to refresh the repository list
FR6: The system can gracefully handle inaccessible directories (skip and log, no crash)
FR7: The system can cache scan results for instant reload on subsequent launches
FR8: The user can view repositories in a card grid showing branch, status (clean/dirty/ahead/behind), last commit, and stash count
FR9: The user can view repositories in a sortable, filterable list view with multi-select
FR10: The user can toggle between card grid and list view
FR11: The user can sort repositories by status, last activity date, branch name, or ahead/behind count
FR12: The user can filter repositories by status (clean, dirty, ahead, behind, dormant)
FR13: The system can display visual status indicators (color/badges) for instant pattern recognition across all repos
FR14: The system can render large repository lists (100+) without UI degradation
FR15: The user can select multiple repositories and execute batch git pull
FR16: The user can select multiple repositories and execute batch git push
FR17: The user can select multiple repositories and execute batch git fetch
FR18: The user can batch git status across multiple repositories
FR19: The system can report per-repo results for batch operations (success/failure with details)
FR20: The system can handle partial success — repos that succeed continue, repos that fail are reported with error details
FR21: The user can see specific error details (e.g., merge conflicts, auth errors) for failed repos
FR22: The user can enable Ollama integration for local, private repository health summaries
FR23: The user can configure cloud API keys (Gemini, DeepSeek, OpenAI, Anthropic) for AI-powered analysis
FR24: The system can generate one-line repository health summaries via the configured AI backend
FR25: The system can suggest commit messages based on staged changes via the configured AI backend
FR26: The system can detect and flag dormant repositories beyond a configurable threshold
FR27: The user can see a visual privacy indicator showing whether data processing is local or cloud-based
FR28: The system can operate entirely without any AI backend configured (deterministic status parsing as default)
FR29: The user can route different AI tasks to different providers (e.g., Ollama for commits, cloud for analysis)
FR30: The system can provide cross-repo analysis when using a cloud AI model (e.g., shared library dependencies across repos)
FR31: The user can run GitPulse as a background system tray agent with the dashboard closed
FR32: The system can monitor for remote changes and alert the user via native OS notifications
FR33: The system can send push reminders for repos with unpushed commits older than a configurable threshold
FR34: The user can configure GitPulse to auto-launch at system startup (opt-in)
FR35: The user can access common operations (status, pull, push) via the system tray context menu
FR36: The user can configure scan root directories via a settings interface
FR37: The user can configure AI backend settings (Ollama endpoint, cloud API keys, per-task routing)
FR38: The user can configure notification behavior (frequency, types, thresholds)
FR39: The user can configure system tray agent behavior (launch at startup, monitoring interval)
FR40: User settings are persisted locally and survive application restarts
FR41: The user can reset all settings to defaults
FR42: The user can launch GitPulse without any account, login, or network configuration
FR43: The system can operate fully offline (all core features work without network access)
FR44: The user can manually check for application updates via system tray or settings
FR45: The user can download GitPulse as a single binary (no installer wizard required)
FR46: The system can run on Windows, macOS, and Linux from initial release
NonFunctional Requirements
NFR1: Cold startup < 3 seconds
NFR2: Disk scan speed < 5 seconds (SSD, <100 repos)
NFR3: Memory usage < 200 MB with 50+ repos
NFR4: Binary size ~15 MB
NFR5: Batch operation throughput < 30 seconds (pull/push 20 repos)
NFR6: UI rendering responsiveness < 16ms per frame (60fps)
NFR7: Async AI loading — Smart Status does not block dashboard
NFR8: Incremental scan reload < 1 second from cache
NFR9: API key storage via OS keychain/secure storage, not plaintext
NFR10: Privacy by default — no data leaves machine unless cloud backend explicitly enabled
NFR11: Data flow transparency — visual indicator for cloud data transit
NFR12: Scan scope control — .gitpulseignore exclusions enforced
NFR13: Zero telemetry by default — opt-in only
NFR14: Git execution isolation — malicious repo cannot compromise application
NFR15: Dependency auditing — Rust/npm vulnerabilities checked before release
NFR16: Ollama version compatibility (API v1) with graceful fallback
NFR17: Cloud API compliance — stable API versions; rate limit handling
NFR18: Git version compatibility >= 2.20 on all platforms
NFR19: Native OS integration — platform-native tray, notifications, startup
NFR20: AI offline resilience — deterministic fallback when Ollama/cloud unavailable
NFR21: Scan fault tolerance — completes even if individual directories fail
NFR22: Batch fault tolerance — successful repos complete even when others fail
NFR23: Crash recovery — state preserved across crashes
NFR24: User data persistence — settings, scan configs, API keys survive updates
NFR25: Keyboard navigation for all core operations
NFR26: High contrast support — status indicators distinguishable in dark/high contrast mode
NFR27: Screen reader compatibility — ARIA markup on key dashboard components
Additional Requirements (Architecture)
- Starter template:
npm create tauri-app@latest -- --template react-ts --manager npm gitpulse - Post-scaffold stack: Zustand, Tailwind CSS, Vitest, Playwright
- Tauri plugins: tauri-plugin-store, tauri-plugin-shell, tauri-plugin-fs, tauri-plugin-autostart, tauri-plugin-notification
- Rust crates: keyring (OS keychain), thiserror (errors), async-trait (AI trait)
- Virtualization: @tanstack/react-virtual for 100+ repo rendering (FR14/NFR6)
- AiProvider trait: health_summary, suggest_commit_message, cross_repo_analysis, provider_type, is_local
- 5 provider implementations: Ollama, Gemini, DeepSeek, OpenAI, Anthropic
- CI/CD: GitHub Actions matrix (Windows x64, macOS x64+ARM, Linux x64)
- Distribution: GitHub Releases, single binary per platform, manual updates only
- Code signing deferred to Phase 1.5
- Error handling: AppError enum (ScanError, GitError, AiError, ConfigError), no unwrap in production
- IPC: Commands (CRUD) + Events (async streaming), namespace:event format
- Frontend state: Zustand stores as presentation cache, Rust = source of truth
- Dormancy detection logic in scanner.rs or commands/dashboard.rs
- .gitpulseignore parser using ignore or globset crate
- i18n framework (react-i18next or typesafe-i18n) ready from day 1
UX Design Requirements
UX-DR1: Implement Tailwind design token system — status colors (clean/dirty/ahead/behind/dormant), privacy colors (local/cloud), neutral palette, spacing scale (4px base) UX-DR2: Implement StatusBadge component — 5 variants (color+icon+label), 3 sizes (sm/md/lg), WCAG AA accessible UX-DR3: Implement RepoCard component — anatomy (header/branch/stats/footer/AI line), 6 states, keyboard nav, click-expand, right-click context menu UX-DR4: Implement RepoRow component — checkbox, status icon, name, branch, ahead/behind, last commit, action menu, sortable columns UX-DR5: Implement StatsBar component — 5 metric cards, collapsible, clickable-to-filter, collapse at <900px width UX-DR6: Implement PrivacyBadge component — local (shield/green) and cloud (cloud/amber) modes, transition animation, aria-live UX-DR7: Implement BatchToolbar component — slide-down on selection, progress counter, disable during ops UX-DR8: Implement SmartStatusLine component — AI summary with blue left border, skeleton loading, graceful absence on error UX-DR9: Implement EmptyState component — 0 repos CTA ("Open Settings"), 0 filter results ("Clear filter"), scan progress transition UX-DR10: Implement dark mode (default) and light mode with system fonts and 4px spacing grid UX-DR11: Implement Card Grid layout — auto-fill minmax(280px, 1fr), 16px gap, 2-5 cards per row based on window width UX-DR12: Implement List View layout — 56px rows, fixed/flexible columns, virtualized rendering UX-DR13: Implement TopBar (48px) — title, Grid/List toggle, filter pills with counts, rescan button, PrivacyBadge UX-DR14: Implement command palette (Cmd/Ctrl+K) — fuzzy search, keyboard navigable, 8+ commands UX-DR15: Implement keyboard shortcuts — Cmd/Ctrl+K/G/L/R/,, Cmd/Ctrl+A, Escape, Space, Enter UX-DR16: Implement right-click context menu — Pull/Push/Fetch, Open Terminal/File Manager, Copy Path, Refresh UX-DR17: Implement skeleton loading (initial scan), streaming progress (batch ops), inline loading (AI queries) UX-DR18: Implement inline error feedback — red border + text on cards/rows, never modal for batch errors UX-DR19: Implement WCAG 2.1 AA — 4.5:1 contrast, ARIA labels, focus indicators, screen reader support, reduced motion, high contrast mode UX-DR20: Implement responsive window breakpoints — sm(<900px)/md(900-1199px)/lg(1200-1599px)/xl(>=1600px) UX-DR21: Implement window persistence — position/size remembered via tauri-plugin-store UX-DR22: Implement toastless design — all feedback inline, native OS notifications via tray only UX-DR23: Implement window close behavior — close minimizes to tray, Cmd/Ctrl+Q quits UX-DR24: Implement Radix UI primitives layer — Dialog, Select, Tooltip, DropdownMenu, Checkbox, ToggleGroup, Popover UX-DR25: Implement 3-layer component architecture — Layer 1 (Radix+Tailwind primitives), Layer 2 (domain components), Layer 3 (feature compositions)
FR Coverage Map
| FR | Epic | Description |
|---|---|---|
| FR1 | Epic 1 | Recursive disk scan for Git repos |
| FR2 | Epic 1 | Configure root directories to scan |
| FR3 | Epic 1 | .gitpulseignore exclusion |
| FR4 | Epic 1 | Detect repos via .git folders |
| FR5 | Epic 1 | Manual rescan trigger |
| FR6 | Epic 1 | Handle inaccessible directories |
| FR7 | Epic 1 | Cache scan results |
| FR8 | Epic 1 | Card grid view with repo details |
| FR9 | Epic 1 | Sortable/filterable list view |
| FR10 | Epic 1 | Toggle card/list view |
| FR11 | Epic 1 | Sort by status/activity/branch/ahead-behind |
| FR12 | Epic 1 | Filter by status |
| FR13 | Epic 1 | Visual status indicators |
| FR14 | Epic 1 | Render 100+ repos without degradation |
| FR15 | Epic 2 | Batch git pull |
| FR16 | Epic 2 | Batch git push |
| FR17 | Epic 2 | Batch git fetch |
| FR18 | Epic 2 | Batch git status |
| FR19 | Epic 2 | Per-repo batch results |
| FR20 | Epic 2 | Partial success handling |
| FR21 | Epic 2 | Error details for failed repos |
| FR22 | Epic 3 | Ollama integration for local AI |
| FR23 | Epic 3 | Cloud API key configuration |
| FR24 | Epic 3 | AI health summaries |
| FR25 | Epic 3 | AI commit message suggestions |
| FR26 | Epic 3 | Dormant repo detection |
| FR27 | Epic 3 | Visual privacy indicator |
| FR28 | Epic 3 | Operate without AI backend |
| FR29 | Epic 3 | Per-task AI provider routing |
| FR30 | Epic 3 | Cross-repo AI analysis |
| FR31 | Epic 4 | Background system tray agent |
| FR32 | Epic 4 | Remote change monitoring & alerts |
| FR33 | Epic 4 | Push reminders for unpushed commits |
| FR34 | Epic 4 | Auto-launch at startup (opt-in) |
| FR35 | Epic 4 | Tray context menu operations |
| FR36 | Epic 5 | Configure scan root directories |
| FR37 | Epic 5 | Configure AI backend settings |
| FR38 | Epic 5 | Configure notification behavior |
| FR39 | Epic 5 | Configure system tray behavior |
| FR40 | Epic 5 | Persist settings locally |
| FR41 | Epic 5 | Reset settings to defaults |
| FR42 | Cross-cutting | No account/login required |
| FR43 | Cross-cutting | Fully offline operation |
| FR44 | Cross-cutting | Manual update check |
| FR45 | Cross-cutting | Single binary distribution |
| FR46 | Cross-cutting | Windows/macOS/Linux support |
Epic List
Epic 1: Repository Discovery & Dashboard
Users can discover all Git repositories on their machine and see them at a glance with status, branch, and activity information in both card grid and list views.
FRs covered: FR1, FR2, FR3, FR4, FR5, FR6, FR7, FR8, FR9, FR10, FR11, FR12, FR13, FR14
Key NFRs: NFR1 (cold startup <3s), NFR2 (scan <5s), NFR3 (memory <200MB), NFR6 (60fps), NFR8 (cache reload <1s), NFR21 (scan fault tolerance), NFR23 (crash recovery)
Standalone value: "Launch and Know" moment — users open GitPulse and instantly see all their repos with visual status. Fully functional without any other epic.
Epic 2: Batch Git Operations
Users can select multiple repositories and execute pull, push, fetch, and status operations in batch, with per-repo success/failure reporting and partial success handling.
FRs covered: FR15, FR16, FR17, FR18, FR19, FR20, FR21
Key NFRs: NFR5 (batch 20 repos <30s), NFR14 (git isolation), NFR22 (batch fault tolerance)
Standalone value: Once repos are displayed (Epic 1), users can immediately act on them in bulk. Complete batch operation domain.
Epic 3: AI-Powered Repository Insights
Users can leverage local (Ollama) or cloud AI providers for repository health summaries, commit message suggestions, dormancy detection, and cross-repo analysis — with clear privacy indicators.
FRs covered: FR22, FR23, FR24, FR25, FR26, FR27, FR28, FR29, FR30
Key NFRs: NFR7 (async AI loading), NFR9 (API key via keychain), NFR10 (privacy by default), NFR11 (data flow transparency), NFR16 (Ollama compat), NFR17 (cloud API compliance), NFR20 (AI offline resilience)
Standalone value: Adds intelligent analysis layer. Works without AI (deterministic fallback) and with any combination of providers. Privacy-first with visual indicators.
Epic 4: Background Agent & Notifications
Users can run GitPulse as a background system tray agent that monitors for remote changes, sends push reminders, and provides quick access to common operations via tray context menu.
FRs covered: FR31, FR32, FR33, FR34, FR35
Key NFRs: NFR19 (native OS integration), NFR18 (Git >= 2.20 compat)
Standalone value: Transforms GitPulse from a "check when needed" tool to an "always watching" agent. Tray menu provides quick operations even with dashboard closed.
Epic 5: Settings & Preferences
Users can configure all aspects of GitPulse — scan roots, AI backends, per-task AI routing, notification behavior, system tray behavior — with settings persisted locally and resettable to defaults.
FRs covered: FR36, FR37, FR38, FR39, FR40, FR41
Key NFRs: NFR24 (data persistence)
Standalone value: Complete configuration management. Users can customize every aspect of their GitPulse experience.
Cross-Cutting Requirements (span all epics)
FRs: FR42 (no account), FR43 (fully offline), FR44 (update check), FR45 (single binary), FR46 (cross-platform)
NFRs: NFR4 (binary ~15MB), NFR12 (scan scope control), NFR13 (zero telemetry), NFR15 (dependency auditing), NFR25 (keyboard nav), NFR26 (high contrast), NFR27 (screen reader)
UX-DRs: Applied across all epics as design system standards
Natural Dependencies
- Epic 1 is the foundation — all other epics build on having repos discovered and displayed
- Epic 2 requires Epic 1 (needs repo list for batch operations)
- Epic 3 requires Epic 1 (needs repo data for AI analysis), integrates with Epic 5 for AI config
- Epic 4 requires Epic 1 (needs repo list for monitoring), integrates with Epic 5 for tray/notification config
- Epic 5 can be developed in parallel with Epics 2-4, but settings UI for each epic should be available when that epic ships
Epic 1: Repository Discovery & Dashboard
Story 1.1: App Shell & First Launch Experience
As a user, I want to launch GitPulse and see a polished dark-mode dashboard with an empty state prompting me to configure scan roots, So that I have a clear starting point.
Acceptance Criteria:
Given GitPulse is launched for the first time When no scan roots are configured Then the dashboard shows an empty state with a "Open Settings" CTA And the TopBar (48px) shows title, Grid/List toggle, filter area, rescan button, and PrivacyBadge placeholder And dark mode is the default with system fonts and 4px spacing grid And window position and size are persisted via tauri-plugin-store
FRs: FR2 (partial) | UX-DRs: UX-DR9, UX-DR10, UX-DR13, UX-DR22, UX-DR24, UX-DR25
Story 1.2: Scan Root Configuration
As a user, I want to configure which root directories GitPulse should scan for repositories, So that I control the scope of discovery.
Acceptance Criteria:
Given the settings interface is open When the user adds a scan root directory path Then the path is validated (exists, is directory, readable) And invalid paths show inline error feedback And configured roots are persisted via tauri-plugin-store and survive restarts And user can remove previously configured roots
FRs: FR2
Story 1.3: Recursive Repository Discovery
As a user,
I want GitPulse to recursively scan my configured directories and discover Git repositories by detecting .git folders,
So that I don't have to manually add each one.
Acceptance Criteria:
Given scan root directories are configured
When a scan is initiated
Then the scanner recursively walks the directory tree
And detects Git repositories by identifying .git folders
And collects repo metadata (path, current branch, ahead/behind, dirty/clean status, last commit date, stash count)
And directories matching .gitpulseignore patterns (glob syntax) are excluded
And scan completes within 5 seconds on SSD with <100 repos
FRs: FR1, FR3, FR4 | NFRs: NFR2, NFR12
Story 1.4: Scan Fault Tolerance
As a user, I want GitPulse to skip inaccessible or permission-denied directories gracefully, So that one problem directory doesn't stop the entire scan.
Acceptance Criteria:
Given a scan is running When the scanner encounters an inaccessible or permission-denied directory Then the directory is skipped and logged And the scan continues without crashing And error count is available for display
FRs: FR6 | NFRs: NFR21
Story 1.5: Scan Result Caching & Manual Rescan
As a user, I want GitPulse to cache scan results so subsequent launches load instantly, and I want a manual rescan button to refresh on demand, So that I get instant access to my repos without waiting.
Acceptance Criteria:
Given a scan has completed successfully When GitPulse is relaunched Then cached results load within 1 second And the user sees the repository dashboard immediately Given the user clicks the rescan button in the TopBar When a rescan is triggered Then the scan runs fresh and updates the cache And streaming progress is visible during the scan
FRs: FR5, FR7 | NFRs: NFR8, NFR23
Story 1.6: Repository Card Grid View
As a user, I want to see my discovered repositories as cards in a responsive grid, each showing branch, status indicator, last commit, and stash count, So that I can assess all repos at a glance.
Acceptance Criteria:
Given repositories have been discovered When the card grid view is active Then each repo displays as a card with: repo name, branch name, StatusBadge (clean/dirty/ahead/behind/dormant), last commit relative time, stash count And the grid uses auto-fill minmax(280px, 1fr) with 16px gap And cards are keyboard navigable (Tab, Enter to expand) And status colors use the design token system (clean=green, dirty=red, ahead=blue, behind=orange, dormant=gray) And cards have 6 visual states (default, hover, selected, active, loading, error)
FRs: FR8, FR13 | UX-DRs: UX-DR1, UX-DR2, UX-DR3, UX-DR11
Story 1.7: Repository List View with Multi-Select
As a user, I want to see repositories in a compact list with sortable columns and multi-select checkboxes, So that I can efficiently manage many repositories.
Acceptance Criteria:
Given repositories have been discovered When the list view is active Then repos display in 56px rows with columns: checkbox, status icon, name, branch, ahead/behind, last commit, action menu And multi-select is supported via checkboxes and Cmd/Ctrl+A And columns are sortable by clicking headers And rendering is virtualized for 100+ repos
FRs: FR9, FR14 | UX-DRs: UX-DR4, UX-DR12 | NFRs: NFR6
Story 1.8: View Toggle, Sorting, and Filtering
As a user, I want to toggle between card and list view, sort by various fields, and filter by status, So that I can customize the dashboard to my workflow.
Acceptance Criteria:
Given repositories are displayed in either view When the user clicks the Grid/List toggle in the TopBar Then the view switches between card grid and list view Given the user clicks a column header or sort option Then repos sort by status, last activity date, branch name, or ahead/behind count Given the user clicks a filter pill in the TopBar Then repos filter by status (clean, dirty, ahead, behind, dormant) And filter pills show counts for each status And keyboard shortcuts work: Cmd/Ctrl+G (grid), Cmd/Ctrl+L (list), Cmd/Ctrl+, (toggle)
FRs: FR10, FR11, FR12 | UX-DRs: UX-DR13, UX-DR15
Story 1.9: Stats Bar & Command Palette
As a user, I want to see aggregate stats across all repos and access a command palette for quick actions, So that I have an overview and can navigate efficiently.
Acceptance Criteria:
Given repositories are loaded When the StatsBar is visible Then it shows 5 metric cards: total repos, clean, dirty, ahead, behind And clicking a metric filters the repo list by that status And StatsBar collapses at <900px width Given the user presses Cmd/Ctrl+K When the command palette opens Then fuzzy search is available across 8+ commands (toggle view, rescan, filter by status, open settings, pull/push selected) And the palette is keyboard navigable (arrows, Enter, Escape)
UX-DRs: UX-DR5, UX-DR14, UX-DR15
Story 1.10: Loading States & Responsive Design
As a user, I want skeleton loading during scans and a dashboard that adapts to window resizing, So that the experience feels polished at any size and stage.
Acceptance Criteria:
Given a scan is in progress When the dashboard is loading Then skeleton loading placeholders are shown (not spinners) Given the window is resized When crossing breakpoints (sm<900, md 900-1199, lg 1200-1599, xl>=1600) Then layout adapts with 2-5 cards per row accordingly And window position and size are remembered across sessions
UX-DRs: UX-DR17, UX-DR20, UX-DR21
Story 1.11: Accessibility Foundation
As a user, I want the dashboard to be keyboard navigable with screen reader support and high contrast compatibility, So that GitPulse is usable regardless of ability.
Acceptance Criteria:
Given the user navigates via keyboard Then all core operations are accessible (Tab, Enter, Escape, arrow keys) And focus indicators are visible and distinct Given a screen reader is active Then ARIA labels are present on key dashboard components And StatusBadge includes aria-live for status changes Given high contrast mode is enabled Then status indicators are distinguishable beyond color alone (icons + labels)
UX-DRs: UX-DR19 | NFRs: NFR25, NFR26, NFR27
Epic 2: Batch Git Operations
Story 2.1: Repository Multi-Select & Batch Toolbar
As a user, I want to select multiple repositories and see a batch action toolbar appear, So that I know which operations I can run on my selection.
Acceptance Criteria:
Given repositories are displayed in list view When the user selects one or more repos via checkboxes or Cmd/Ctrl+A Then a BatchToolbar slides down showing Pull, Push, Fetch, Status buttons And a selection counter shows "N repos selected" And all batch buttons are disabled while an operation is in progress
UX-DRs: UX-DR7
Story 2.2: Batch Git Pull
As a user,
I want to select multiple repos and execute git pull on all of them,
So that I can update all repos at once.
Acceptance Criteria:
Given multiple repos are selected and the batch toolbar is visible
When the user clicks "Pull"
Then git pull executes across selected repos in parallel via tokio::process::Command
And per-repo progress is shown in the streaming toolbar
And the operation completes within 30 seconds for 20 repos
FRs: FR15 | NFRs: NFR5, NFR14
Story 2.3: Batch Git Push
As a user, I want to batch push selected repositories, So that I can sync local commits to remotes efficiently.
Acceptance Criteria:
Given multiple repos are selected
When the user clicks "Push"
Then git push executes across selected repos in parallel
And per-repo progress is shown
And auth errors are caught and reported per repo
FRs: FR16
Story 2.4: Batch Git Fetch
As a user, I want to batch fetch selected repositories, So that I can check for remote changes without merging.
Acceptance Criteria:
Given multiple repos are selected
When the user clicks "Fetch"
Then git fetch executes across selected repos in parallel
And ahead/behind counts are updated after fetch
And per-repo results are shown
FRs: FR17
Story 2.5: Batch Git Status
As a user,
I want to run git status across multiple repos,
So that I can see which repos have uncommitted changes.
Acceptance Criteria:
Given multiple repos are selected
When the user clicks "Status"
Then git status runs across selected repos
And dirty/clean status is updated for each repo
And cards/rows update their StatusBadge accordingly
FRs: FR18
Story 2.6: Batch Results Reporting & Partial Success
As a user, I want to see per-repo results with specific error details for batch operations, So that I know exactly what succeeded and failed.
Acceptance Criteria:
Given a batch operation is running When some repos succeed and others fail Then successful repos complete normally (partial success) And failed repos show inline error feedback (red border + error text on card/row, never modal) And specific error details are shown (merge conflicts, auth errors, network errors) And the toolbar shows final summary: "N succeeded, M failed"
FRs: FR19, FR20, FR21 | UX-DRs: UX-DR18 | NFRs: NFR22
Story 2.7: Right-Click Context Menu
As a user, I want to right-click a repository for quick actions like pull, push, fetch, open terminal, or open file manager, So that I can act on individual repos without multi-selecting.
Acceptance Criteria:
Given the user right-clicks on a repo card or row When the context menu appears Then options include: Pull, Push, Fetch, Open in Terminal, Open in File Manager, Copy Path, Refresh And each option triggers the corresponding action And the menu is keyboard navigable
UX-DRs: UX-DR16
Epic 3: AI-Powered Repository Insights
Story 3.1: AI Provider Trait & Ollama Integration
As a user, I want to connect GitPulse to my local Ollama instance for private AI-powered insights, So that I can get intelligent summaries without sending data to the cloud.
Acceptance Criteria:
Given Ollama is configured with an endpoint URL When GitPulse connects to Ollama Then the AiProvider trait is implemented with health_summary, suggest_commit_message, cross_repo_analysis, provider_type, is_local methods And Ollama provider uses API v1 with graceful fallback on version mismatch And health check verifies the endpoint is reachable And when Ollama is unavailable, deterministic status parsing is used as fallback
FRs: FR22, FR28 | NFRs: NFR16, NFR20
Story 3.2: Cloud AI Provider Configuration & Secure Key Storage
As a user, I want to configure API keys for cloud providers (Gemini, DeepSeek, OpenAI, Anthropic) stored in my OS keychain, So that I can use cloud AI securely.
Acceptance Criteria:
Given the AI settings section is open When the user enters an API key for a provider Then the key is stored via the OS keychain (keyring crate), not plaintext And a connection test verifies the key works And the key is never displayed in full after saving
FRs: FR23 | NFRs: NFR9
Story 3.3: AI Health Summary (Smart Status Line)
As a user, I want to see a one-line AI-generated health summary for each repository, So that I can quickly understand repo state without reading git output.
Acceptance Criteria:
Given an AI provider is configured and a repo has status data When the SmartStatusLine component renders Then a one-line summary appears with a blue left border And loading shows skeleton animation (non-blocking) And on error, the line is absent (graceful degradation, no error shown) And PrivacyBadge indicates local vs cloud processing
FRs: FR24, FR27 | UX-DRs: UX-DR6, UX-DR8 | NFRs: NFR7, NFR10, NFR11
Story 3.4: AI Commit Message Suggestions
As a user, I want AI to suggest commit messages based on my staged changes, So that I can write better commit messages faster.
Acceptance Criteria:
Given a repository has staged changes When the user requests a commit message suggestion Then the AI generates a suggestion based on the staged diff And the suggestion is shown inline (non-blocking) And the feature works with any configured AI provider
FRs: FR25
Story 3.5: Dormant Repository Detection
As a user, I want GitPulse to flag repositories with no activity beyond a configurable threshold, So that I can identify stale projects.
Acceptance Criteria:
Given a configurable dormancy threshold (default: 30 days) When a repo's last commit is older than the threshold Then the repo is flagged with "dormant" status And the StatusBadge shows the dormant variant (gray) And dormant repos appear in the dormant filter
FRs: FR26
Story 3.6: Per-Task AI Provider Routing
As a user, I want to route different AI tasks to different providers, So that I can optimize for speed, cost, or privacy per task type.
Acceptance Criteria:
Given multiple AI providers are configured When the user sets routing rules (e.g., Ollama for commits, cloud for analysis) Then each AI task routes to the configured provider And fallback to a default provider if the routed provider is unavailable
FRs: FR29
Story 3.7: Cross-Repository AI Analysis
As a user, I want AI to analyze patterns across my repositories, So that I can understand relationships like shared library dependencies.
Acceptance Criteria:
Given a cloud AI provider is configured (cross-repo analysis not available with Ollama) When the user requests cross-repo analysis Then the AI provides insights about shared dependencies, patterns, and relationships across repos And PrivacyBadge shows "cloud" indicator during analysis
FRs: FR30 | NFRs: NFR17
Epic 4: Background Agent & Notifications
Story 4.1: System Tray Agent & Window Management
As a user, I want GitPulse to minimize to the system tray when I close the window, So that it stays available in the background.
Acceptance Criteria:
Given GitPulse is running When the user closes the window Then the app minimizes to system tray (platform-native tray icon) And double-clicking the tray icon reopens the dashboard Given the user presses Cmd/Ctrl+Q Then the app quits entirely
FRs: FR31 | UX-DRs: UX-DR23 | NFRs: NFR19
Story 4.2: Tray Context Menu Operations
As a user, I want to right-click the tray icon for quick access to common operations, So that I can act without opening the dashboard.
Acceptance Criteria:
Given GitPulse is running in the tray When the user right-clicks the tray icon Then a context menu shows: status overview, Pull All, Push All, Open Dashboard, Quit And selecting an action executes it immediately And status overview shows clean/dirty/ahead/behind counts
FRs: FR35
Story 4.3: Remote Change Monitoring & Alerts
As a user, I want GitPulse to periodically check for remote changes and alert me via native OS notifications, So that I stay informed about upstream activity.
Acceptance Criteria:
Given background monitoring is enabled When remote changes are detected on a monitored repo Then a native OS notification is sent identifying the repo and change count And the monitoring interval is configurable
FRs: FR32
Story 4.4: Push Reminders for Unpushed Commits
As a user, I want GitPulse to remind me about unpushed commits older than a configurable threshold, So that I don't forget to push important work.
Acceptance Criteria:
Given a repo has unpushed commits older than the configured threshold When the background check runs Then a native OS notification reminds the user to push And the notification identifies the repo and commit age And the threshold is configurable in settings
FRs: FR33
Story 4.5: Auto-Launch at System Startup
As a user, I want to configure GitPulse to start automatically with my system, So that monitoring begins without manual intervention.
Acceptance Criteria:
Given auto-launch is enabled in settings (opt-in, default off) When the system starts up Then GitPulse launches and minimizes to tray And tauri-plugin-autostart handles platform-specific startup registration
FRs: FR34
Epic 5: Settings & Preferences
Story 5.1: Settings Interface Foundation
As a user, I want a clean settings interface organized into sections, So that I can find and configure any aspect of GitPulse easily.
Acceptance Criteria:
Given the user opens settings (via menu, keyboard shortcut, or empty state CTA) When the settings dialog appears Then sections are organized as: Scan, AI, Notifications, System Tray And all settings are persisted via tauri-plugin-store And settings survive application restarts
FRs: FR40
Story 5.2: Scan Configuration Settings
As a user, I want to manage scan root directories and exclusions in settings, So that I can control repository discovery behavior.
Acceptance Criteria:
Given the Scan settings section When the user adds/removes scan root directories Then changes take effect on next scan And the dormancy threshold is configurable And .gitpulseignore patterns can be previewed
FRs: FR36
Story 5.3: AI Backend Settings & Per-Task Routing
As a user, I want to configure AI providers, API keys, and per-task routing, So that I can control how AI features work.
Acceptance Criteria:
Given the AI settings section When the user configures providers Then Ollama endpoint URL is configurable And cloud API keys can be entered (stored in OS keychain) And per-task routing can be set (health summary → provider, commit message → provider) And connection test buttons verify each provider
FRs: FR37
Story 5.4: Notification Behavior Settings
As a user, I want to configure notification frequency, types, and thresholds, So that I'm alerted about what matters without being overwhelmed.
Acceptance Criteria:
Given the Notifications settings section When the user configures notifications Then individual notification types can be enabled/disabled (remote changes, push reminders) And the monitoring interval is configurable And push reminder threshold is configurable
FRs: FR38
Story 5.5: System Tray & Startup Settings
As a user, I want to configure tray behavior and auto-launch, So that GitPulse runs the way I prefer.
Acceptance Criteria:
Given the System Tray settings section When the user configures tray behavior Then auto-launch at startup can be toggled (opt-in) And minimize-to-tray on close can be toggled And monitoring behavior is configurable
FRs: FR39
Story 5.6: Reset Settings to Defaults
As a user, I want to reset all settings to defaults, So that I can start fresh if my configuration becomes problematic.
Acceptance Criteria:
Given any settings section When the user clicks "Reset to Defaults" Then a confirmation dialog appears And on confirmation, all settings revert to defaults And API keys are preserved (with option to clear)
FRs: FR41