From 1f6fa77ded0830f853750a9f97416402c521fb78 Mon Sep 17 00:00:00 2001
From: 7000pctAUTO <lukems3823@gmail.com>
Date: Tue, 3 Feb 2026 08:59:28 +0000
Subject: [PATCH] chore: add project configuration files

---
 README.md | 327 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 312 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index daf6d7f..1ae354c 100644
--- a/README.md
+++ b/README.md
@@ -1,32 +1,329 @@
 # Git Agent Sync
 
-A CLI tool that manages isolated git worktrees for AI coding agents.
+A CLI tool that manages isolated git worktrees for AI coding agents, enabling parallel development without conflicts.
 
-## Features
+## Overview
 
-- Create isolated worktrees per AI agent
-- Auto-configure environment variables
-- Track changes with agent attribution
-- Generate unified diffs for code review
-- Safely merge changes back to main branch
+Git Agent Sync solves the problem of managing multiple AI coding agents working on the same codebase. Each agent gets its own isolated git worktree, allowing parallel development without branch conflicts.
+
+### Key Features
+
+- **Per-Agent Worktree Isolation** - Each agent works in a separate git worktree
+- **Automatic Environment Configuration** - Environment variables and dependencies are auto-configured
+- **Change Tracking** - Track agent-specific file changes with metadata
+- **Unified Diff Generation** - Generate diffs for code review with agent attribution
+- **Safe Merge Workflows** - Merge changes back to main with validation checks
 
 ## Installation
 
+### From Source
+
+```bash
+# Clone and install
+git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/git-agent-sync.git
+cd git-agent-sync
+npm install
+npm run build
+
+# Link globally
+npm link
+```
+
+### Global Installation
+
 ```bash
 npm install -g git-agent-sync
 ```
 
-## Usage
+## Quick Start
+
+1. **Initialize in a git repository:**
 
 ```bash
-git-agent-sync create <agent-name>
-git-agent-sync list
-git-agent-sync status <agent-name>
-git-agent-sync diff <agent-name>
-git-agent-sync merge <agent-name>
-git-agent-sync destroy <agent-name>
+cd your-git-repo
+git-agent-sync init
 ```
 
+2. **Create a workspace for an agent:**
+
+```bash
+git-agent-sync create claude-code
+```
+
+3. **Work in the workspace:**
+
+```bash
+cd .agent-workspaces/agent-claude-code
+# Make your changes
+git status
+```
+
+4. **Generate a diff for review:**
+
+```bash
+git-agent-sync diff claude-code
+```
+
+5. **Merge changes back to main:**
+
+```bash
+git-agent-sync merge claude-code
+```
+
+6. **Clean up when done:**
+
+```bash
+git-agent-sync destroy claude-code
+```
+
+## Commands
+
+### create
+
+Create an isolated worktree for an AI agent.
+
+```bash
+git-agent-sync create <agent-name> [options]
+```
+
+**Options:**
+- `-p, --path <path>` - Custom path for the workspace
+- `-t, --template <template>` - Path to environment template directory
+- `--no-install` - Skip automatic dependency installation
+- `--env <key=value>` - Set environment variable (can be used multiple times)
+
+**Example:**
+```bash
+git-agent-sync create claude-code --env API_KEY=abc123
+```
+
+### list
+
+List all active agent workspaces.
+
+```bash
+git-agent-sync list [options]
+```
+
+**Options:**
+- `--json` - Output as JSON
+- `--verbose` - Show detailed information
+
+**Example:**
+```bash
+git-agent-sync list --verbose
+```
+
+### status
+
+Show detailed changes for a specific agent workspace.
+
+```bash
+git-agent-sync status [agent-name] [options]
+```
+
+**Options:**
+- `--short` - Show short summary only
+- `--output <file>` - Export to file
+
+**Example:**
+```bash
+git-agent-sync status claude-code --short
+```
+
+### diff
+
+Generate unified diffs for code review.
+
+```bash
+git-agent-sync diff [agent-name] [options]
+```
+
+**Options:**
+- `-o, --output <file>` - Export diff to file
+- `--short` - Show short summary only
+- `--json` - Output as JSON
+- `--text` - Output as plain text
+- `--compare <branch>` - Compare to a specific branch
+
+**Example:**
+```bash
+git-agent-sync diff claude-code --output diff.md
+```
+
+### merge
+
+Safely merge agent changes back to main branch.
+
+```bash
+git-agent-sync merge <agent-name> [options]
+```
+
+**Options:**
+- `--force` - Force merge even with conflicts
+- `--dry-run` - Preview merge without making changes
+- `--message <msg>` - Custom merge commit message
+
+**Example:**
+```bash
+git-agent-sync merge claude-code --dry-run
+```
+
+### destroy
+
+Safely remove an agent workspace.
+
+```bash
+git-agent-sync destroy <agent-name> [options]
+```
+
+**Options:**
+- `--force` - Skip confirmation and remove without preservation
+- `--preserve` - Preserve uncommitted changes as a patch file
+- `--output <path>` - Path for patch file
+
+**Example:**
+```bash
+git-agent-sync destroy claude-code --preserve
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GIT_AGENT_SYNC_PATH` | Custom path for agent workspaces | `./.agent-workspaces` |
+| `GIT_AGENT_SYNC_CONFIG` | Path to global config file | `~/.git-agent-sync/config.json` |
+| `GIT_AGENT_SYNC_TEMPLATE` | Path to environment template directory | `~/.git-agent-sync/templates/default` |
+| `GIT_AGENT_SYNC_AUTO_INSTALL` | Auto-install dependencies (true/false) | `true` |
+
+### Global Config
+
+Location: `~/.git-agent-sync/config.json`
+
+```json
+{
+  "workspacePath": "./.agent-workspaces",
+  "defaultBranch": "main",
+  "autoInstall": true,
+  "templates": {
+    "default": "~/.git-agent-sync/templates/default"
+  }
+}
+```
+
+### Workspace Config
+
+Location: `.agent-workspace.json` (in workspace root)
+
+```json
+{
+  "agentName": "claude-code-1",
+  "branch": "agent-claude-code-1",
+  "createdAt": "2024-01-15T10:30:00Z",
+  "mainBranch": "main",
+  "environment": {
+    "AGENT_ID": "claude-code-1",
+    "WORKSPACE_PATH": "/path/to/workspace"
+  }
+}
+```
+
+## Examples
+
+### Parallel Agent Development
+
+```bash
+# Create workspaces for multiple agents
+git-agent-sync create claude-1
+git-agent-sync create claude-2
+git-agent-sync create gpt-4
+
+# Work in parallel
+cd .agent-workspaces/agent-claude-1
+# ... make changes
+
+cd .agent-workspaces/agent-claude-2
+# ... make changes
+
+# Review changes
+git-agent-sync diff claude-1
+git-agent-sync diff claude-2
+
+# Merge when ready
+git-agent-sync merge claude-1
+git-agent-sync merge claude-2
+```
+
+### Custom Template
+
+```bash
+# Create a custom template
+mkdir -p ~/.git-agent-sync/templates/nodejs
+cat > ~/.git-agent-sync/templates/nodejs/.env.template <<EOF
+NODE_ENV=development
+AGENT_ID={agentName}
+WORKSPACE_PATH={workspacePath}
+EOF
+
+# Use the template
+git-agent-sync create my-agent --template ~/.git-agent-sync/templates/nodejs
+```
+
+## Architecture
+
+```
+git-agent-sync/
+├── src/
+│   ├── commands/       # CLI command implementations
+│   │   ├── create.ts   # Create worktree
+│   │   ├── list.ts     # List workspaces
+│   │   ├── status.ts   # Show changes
+│   │   ├── diff.ts     # Generate diffs
+│   │   ├── merge.ts    # Merge to main
+│   │   └── destroy.ts  # Remove workspace
+│   ├── config/         # Configuration management
+│   ├── utils/          # Utility functions
+│   │   ├── git-utils.ts    # Git operations
+│   │   ├── file-utils.ts   # File operations
+│   │   ├── env-utils.ts    # Environment setup
+│   │   └── diff-utils.ts   # Diff formatting
+│   └── types/          # TypeScript types
+├── templates/          # Environment templates
+├── tests/              # Test files
+└── bin/                # CLI entry point
+```
+
+## Troubleshooting
+
+### Common Errors
+
+| Error | Solution |
+|-------|----------|
+| Git repository not found | Run command from within a git repository or initialize one first |
+| Agent workspace already exists | Use a different agent name or destroy existing workspace first |
+| Merge conflicts detected | Resolve conflicts manually or use `--force` flag with caution |
+| Invalid agent name format | Use alphanumeric characters and hyphens only |
+| Permission denied for workspace directory | Check directory permissions or use `--path` flag for alternative location |
+
+### Debug Mode
+
+Enable verbose output with:
+
+```bash
+git-agent-sync --verbose <command>
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Run the test suite: `npm test`
+6. Submit a pull request
+
 ## License
 
-MIT
+MIT License - see LICENSE file for details.