Skip to content

Workflows

Jump to bottom
Prince Lad edited this page Jan 20, 2026 · 1 revision

Workflows

This page documents common workflows, interaction patterns, and behavior matrices for Forge.

Table of Contents

Focus-Based Behavior Matrix

The app tracks two focus modes that determine which keybindings are active:

  1. Menu Focus — Top-bar menu is active (highlighted in yellow/bold)
  2. View Focus — Content area (current view) is active (default starting state)

Key Bindings by Context and Focus

Context Focus Key Behavior
Any Menu Tab Cycle menu items
Any Menu Up/Down Navigate menu
Any Menu Enter Switch to view, set focus=View
Dashboard View Tab Go to Changes, sync menu
Changes View Tab Go to History, sync menu
Changes View Space Toggle staging for selected file
Changes View Enter Commit staged files
Any View Esc Return focus to menu
Any View ? Toggle help overlay
Dashboard View Ctrl+F Toggle search mode

Focus State Indication:

  • Menu Focus: Top-bar menu is highlighted (yellow/bold)
  • View Focus: Status bar shows "Focus: Menu" or "Focus: View"
  • Tab Behavior: Changes based on focus
    • In Menu focus: cycles menu items
    • In View focus: cycles between views (Dashboard → Changes → History → Branches → Merge → Board → Modules → Settings)

Menu Selection Sync:

  • When tabbing in View focus, the menu selection index automatically syncs with the current view
  • Pressing Esc in any view returns focus to the menu without changing views

Dashboard → Changes Workflow

This is the primary workflow for viewing and staging file changes.

1. User sees list of projects (Git-discovered)
2. Select project with Up/Down
3. Press Tab → Switch to Changes view
4. View shows:
   - Left: File list from git status
   - Right: Diff preview for selected file
5. Press Space to stage/unstage files
6. Type commit message
7. Press Enter to commit (only commits staged files)

Detailed Steps

  1. Project Selection

    • Dashboard displays all Git repositories discovered in the workspace
    • Use Up/Down arrow keys to navigate
    • Selected project is highlighted

  2. Navigate to Changes

    • Press Tab to switch to Changes view
    • View focus automatically set to View mode

  3. Review File Changes

    • Left pane: List of changed files from git status
    • Right pane: Diff preview for selected file
    • Files marked with status: Modified (M), Added (A), Deleted (D), Untracked (?)

  4. Stage Files

    • Navigate to desired file with Up/Down
    • Press Space to toggle staging
    • Staged files show with [S] marker

  5. Commit Changes

    • Type commit message in the commit message area
    • Press Enter to commit staged files
    • Commit only applies to staged files (Git default behavior)

  6. Remote Operations (if implemented)

    • Press f to fetch from remote
    • Press p to push to remote
    • Status messages display operation results

Merge Conflict Resolution Workflow

Visual workflow for resolving Git merge conflicts.

1. Git detects merge conflict
2. User navigates to Merge Visualizer (Tab through views)
3. View shows:
   - Left pane: List of conflicted files
   - Center pane: Local version diff
   - Right pane: Incoming version diff
4. User resolves mentally, chooses which to accept
5. Press Left/Right to focus different panes
6. Press Enter to mark chosen pane as "accepted" (green highlight)
7. Accepted choices tracked in HashMap<FilePath, ResolutionChoice>

Detailed Steps

  1. Conflict Detection

    • Merge conflicts are detected automatically via git status
    • Conflicted files appear with special marker

  2. Navigate to Merge Visualizer

    • Press Tab repeatedly to reach Merge Visualizer view
    • Or use menu navigation to select directly

  3. Review Conflicts

    • Left pane: List of all conflicted files
    • Center pane: Local version (your changes)
    • Right pane: Incoming version (their changes)
    • Navigate conflicted files with Up/Down

  4. Choose Resolution

    • Press Left to focus center pane (local version)
    • Press Right to focus right pane (incoming version)
    • Press Enter to mark chosen version as accepted
    • Accepted pane is highlighted in green

  5. Track Decisions

    • Resolution choices are tracked in a HashMap
    • Format: HashMap<FilePath, ResolutionChoice>
    • Can review all decisions before finalizing

  6. Finalize Resolution

    • Once all conflicts are resolved, exit to Changes view
    • Stage resolved files and commit as normal

Module Management Workflow

Workflow for managing project modules and team developers.

1. Navigate to Modules view (Tab multiple times)
2. Left side: Modules list | Right side: Developers list
3. In Modules list:
   - Press 'n' to create new module
   - Press 'e' to edit selected module name
   - Press 'd' to delete module
   - Press 'a' to assign developer
4. In Developers list:
   - Press 'n' to create new developer
   - Press 'd' to delete developer
5. Data persisted to .forge/*.json on each change

Detailed Steps

  1. Navigate to Modules View

    • Press Tab repeatedly until Modules view is active
    • Or use menu to select Modules directly

  2. Module Management (Left Pane)

    • Create New Module:
      • Press n to enter creation mode
      • Type module name
      • Press Enter to confirm
    • Edit Module:
      • Navigate to module with Up/Down
      • Press e to enter edit mode
      • Modify name
      • Press Enter to save
    • Delete Module:
      • Navigate to module with Up/Down
      • Press d to delete (confirmation prompt may appear)
    • Assign Developer:
      • Navigate to module with Up/Down
      • Press a to assign developer from list
      • Select developer from popup

  3. Developer Management (Right Pane)

    • Press Tab or Right to switch to Developers pane
    • Create New Developer:
      • Press n to enter creation mode
      • Type developer name
      • Press Enter to confirm
    • Delete Developer:
      • Navigate to developer with Up/Down
      • Press d to delete
      • Unassigns developer from all modules

  4. Data Persistence

    • All changes are automatically persisted to .forge/modules.json and .forge/developers.json
    • Files created in repository root if not present
    • JSON format for easy manual editing if needed

  5. Progress Tracking

    • Module progress is tracked separately in .git/forge/progress.txt
    • Progress increments on commits associated with modules
    • Progress caps at 100% (saturation math)

Remote Operations Workflow

Workflow for fetch and push operations with remote repositories.

Note: This feature was implemented on January 20, 2026. Key UX consideration: fetch (f) and push (p) shortcuts only trigger when NOT typing a commit message, allowing users to type characters like "fix bug" without losing the 'f' or 'p' characters.

1. User is in Dashboard or Changes view
2. Press 'f' to fetch from remote
   - Status bar shows: "Fetching from origin..."
   - On success: "✓ Fetched N objects from origin"
   - On failure: "✗ Fetch failed: <error message>"
3. Press 'p' to push to remote
   - Status bar shows: "Pushing to origin..."
   - On success: "✓ Pushed to origin"
   - On failure: "✗ Push failed: <error message>"
4. Operations execute in background with status feedback

Detailed Steps

  1. Fetch from Remote

    • Ensure you're in Dashboard or Changes view (not typing commit message)
    • Press f key
    • Status message appears: "Fetching from origin..."
    • On success: Git fetch completes, status shows objects fetched
    • On failure: Error message displayed in status bar

  2. Push to Remote

    • Ensure you're in Dashboard or Changes view (not typing commit message)
    • Ensure you have commits to push
    • Press p key
    • Status message appears: "Pushing to origin..."
    • On success: Commits pushed to remote
    • On failure: Error message displayed (e.g., "permission denied", "non-fast-forward")

  3. Commit Message Context

    • When typing a commit message, f and p keys insert the characters normally
    • Fetch/push shortcuts are disabled during commit message entry
    • This prevents accidental remote operations when typing messages like "fix bug" or "update packages"

  4. Status Bar Feedback

    • All remote operations provide immediate visual feedback
    • Success messages: Green checkmark (✓)
    • Failure messages: Red cross (✗)
    • Clear, actionable error messages for troubleshooting

See Also

Clone this wiki locally