# ren-lingyu/git-agent-workflow architecture

> Architecture diagram of the GitHub repository ren-lingyu/git-agent-workflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ren-lingyu/git-agent-workflow
- Repository: https://github.com/ren-lingyu/git-agent-workflow

## Overview

GAW is a Git-native tool for keeping agent workspace state and history alongside a project repository. Its principal workflow is to select a workspace, validate it, edit and stage its contents, commit agent history (optionally associated with project commits), and inspect that history. The README also documents repository initialization, deployment, branch lifecycle operations, local ref metadata, and hook-based protection. No source excerpts were provided, so relationships below rely only on README statements; directory paths identify unsampled subsystems.

Main entry points: [`lisp/src/cli/cli.api.lisp`](https://github.com/ren-lingyu/git-agent-workflow/blob/main/lisp/src/cli/cli.api.lisp) (Command interface), [`lisp/src/deploy`](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/deploy) (Deploy local state), [`lisp/src/config`](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/config) (Config validation), [`lisp/src/init`](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/init) (Initialize history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["Command interface<br/>[cli.api.lisp]"]
end

subgraph group_lifecycle["Repository lifecycle"]
  node_init["Initialize history"]
  node_deploy["Deploy local state"]
  node_branch["Branch lifecycle"]
end

subgraph group_daily["Daily workflow"]
  node_workspace["Workspace selection"]
  node_config["Config validation"]
  node_check["Repository checks"]
  node_commit["Agent commits"]
  node_show["History display"]
end

subgraph group_protocol["Git protocol"]
  node_state["Workflow state"]
  node_refs["Reference operations"]
  node_current["Current source ref<br/>[current.core.lisp]"]
  node_git["Git operations"]
  node_hook["Branch protection hook"]
end

node_user(("Git user"))
node_gitrepo[("Git repository")]

node_user -->|"runs commands"| node_cli
node_cli -->|"initializes"| node_init
node_cli -->|"deploys"| node_deploy
node_cli -->|"manages branches"| node_branch
node_cli -->|"checks state"| node_check
node_cli -->|"commits state"| node_commit
node_cli -->|"shows history"| node_show
node_init -->|"uses deployment"| node_deploy
node_deploy -->|"verifies worktree"| node_check
node_deploy -->|"installs protection"| node_hook
node_config -->|"resolves source ref"| node_current
node_config -->|"reads config blob"| node_git
node_workspace -->|"manages workspace paths"| node_gitrepo
node_commit -->|"records agent history"| node_gitrepo
node_refs -->|"tracks local metadata"| node_gitrepo
node_git -->|"operates on"| node_gitrepo
node_hook -->|"protects branches"| node_gitrepo
node_show -->|"reads history"| node_gitrepo

click node_cli "https://github.com/ren-lingyu/git-agent-workflow/blob/main/lisp/src/cli/cli.api.lisp"
click node_init "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/init"
click node_deploy "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/deploy"
click node_branch "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/branch"
click node_workspace "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/workspace"
click node_config "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/config"
click node_check "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/check"
click node_commit "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/commit"
click node_show "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/show"
click node_state "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/state"
click node_refs "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/refs"
click node_current "https://github.com/ren-lingyu/git-agent-workflow/blob/main/lisp/src/refs/current.core.lisp"
click node_git "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/git"
click node_hook "https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/hook"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_init,node_deploy,node_branch,node_gitrepo toneAmber
class node_workspace,node_config,node_check,node_commit,node_show toneMint
class node_state,node_refs,node_current,node_git,node_hook toneRose
```

## Components

### User interface

- [Command interface](https://github.com/ren-lingyu/git-agent-workflow/blob/main/lisp/src/cli/cli.api.lisp): `lisp/src/cli/cli.api.lisp`

### Repository lifecycle

- [Initialize history](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/init): `lisp/src/init`
- [Deploy local state](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/deploy): `lisp/src/deploy`
- [Branch lifecycle](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/branch): `lisp/src/branch`

### Daily workflow

- [Workspace selection](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/workspace): `lisp/src/workspace`
- [Config validation](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/config): `lisp/src/config`
- [Repository checks](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/check): `lisp/src/check`
- [Agent commits](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/commit): `lisp/src/commit`
- [History display](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/show): `lisp/src/show`

### Git protocol

- [Workflow state](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/state): `lisp/src/state`
- [Reference operations](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/refs): `lisp/src/refs`
- [Current source ref](https://github.com/ren-lingyu/git-agent-workflow/blob/main/lisp/src/refs/current.core.lisp): `lisp/src/refs/current.core.lisp`
- [Git operations](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/git): `lisp/src/git`
- [Branch protection hook](https://github.com/ren-lingyu/git-agent-workflow/tree/main/lisp/src/hook): `lisp/src/hook`

### Other components

- **Git user**
- **Git repository**

## Connections

- Git user → Command interface: runs commands (evidence: `README.org`)
- Command interface → Initialize history: initializes (evidence: `README.org`)
- Command interface → Deploy local state: deploys (evidence: `README.org`)
- Command interface → Branch lifecycle: manages branches (evidence: `README.org`)
- Command interface → Repository checks: checks state (evidence: `README.org`)
- Command interface → Agent commits: commits state (evidence: `README.org`)
- Command interface → History display: shows history (evidence: `README.org`)
- Initialize history → Deploy local state: uses deployment (evidence: `README.org`)
- Deploy local state → Repository checks: verifies worktree (evidence: `README.org`)
- Deploy local state → Branch protection hook: installs protection (evidence: `README.org`)
- Config validation → Current source ref: resolves source ref (evidence: `README.org`)
- Config validation → Git operations: reads config blob (evidence: `README.org`)
- Workspace selection → Git repository: manages workspace paths (evidence: `README.org`)
- Agent commits → Git repository: records agent history (evidence: `README.org`)
- Reference operations → Git repository: tracks local metadata (evidence: `README.org`)
- Git operations → Git repository: operates on (evidence: `README.org`)
- Branch protection hook → Git repository: protects branches (evidence: `README.org`)
- History display → Git repository: reads history (evidence: `README.org`)
