# Workspace Configuration

Augent workspaces are your working Git repositories where bundles are installed and configured. This document explains workspace structure, configuration files, and how bundles integrate into workspaces.

---

## Overview

A **workspace** is a Git repository containing:

- Augent configuration in `.augent/` directory
- Installed resources in AI coding platform directories
- Metadata tracking which bundles provide which resources

Augent automatically initializes workspaces when needed.

---

## Workspace Structure

```text
my-project/
├── .augent/                           # Augent workspace directory
│   ├── augent.yaml                    # Workspace bundle definition
│   ├── augent.lock                    # Locked bundle versions
│   └── augent.index.yaml          # Resource tracking
├── .claude/                           # Claude Code configuration
├── .cursor/                           # Cursor configuration
├── .opencode/                         # OpenCode configuration
├── CLAUDE.md                          # Claude Code agent config
├── AGENTS.md                          # Shared agent configuration
└── ...                                # Your project files
```

---

## Configuration Files

Config files are looked up in this order (first match wins): the current directory if it contains `augent.lock`, then `./augent.lock` (repo root), then `./.augent/augent.lock` (created by default on first install). See [Bundles spec](implementation/specs/bundles.md) for details.

### augent.yaml

Defines **direct** bundles installed in the workspace. Each entry is stored in a canonical form (not the install source string). Bundle order is preserved; later bundles override earlier ones when files overlap.

**Directory bundle** (name = directory name):

```yaml
name: my-project
bundles:
  - name: local-bundle
    path: ./local-bundle
```

**Git bundle** (name = `@owner/repo` or `@owner/repo/bundle-name` or `@owner/repo:path`; ref is stored in the lockfile, not in the name):

```yaml
  - name: '@owner/repo'
    git: https://github.com/owner/repo.git
    path: .
```

Dependencies of dependencies are not listed in `augent.yaml`; they appear only in `augent.lock`.

### augent.lock

Auto-generated lockfile with all bundles (direct and transitive) in installation order. Every Git bundle has `ref` and the **exact SHA** of the commit for reproducibility. See [Bundles spec](implementation/specs/bundles.md) and [ADR-003: Locking Mechanism](implementation/adrs/003-locking-mechanism.md).

**Never manually edit** — updated on install.

### augent.index.yaml

Tracks which bundles provide which resources, in installation order (including resources from dependencies). Each bundle lists its **bundle-relative paths** (e.g. `rules/debug.md`) and the **installed platform paths** (e.g. `.claude/rules/debug.md`). Augent uses this for conflict detection, modification tracking, and uninstallation.

**Optional:** This file is automatically generated. If deleted or missing, Augent will rebuild it by scanning installed files.

---

## Lazy Workspace Configuration

Augent can work without `augent.index.yaml`. When missing:

- **On Install**: Augent generates the workspace config file automatically
- **On Uninstall**: Augent scans the workspace to rebuild the config by detecting platforms, scanning installed files, and matching them to bundles from the lockfile

This is useful when migrating from another system or if the config is corrupted.

---

## Workspace Initialization

Augent initializes workspaces automatically on first `install`:

### Auto-Detection

```bash
cd /path/to/my-git-repo
augent install github:author/bundle
# .augent/ automatically created
```

### Manual Initialization

```bash
cd /path/to/my-git-repo
augent install github:author/bundle
# Workspace initialized with inferred name from git remote
```

### Naming

Augent infers workspace name from git remote:

| Git Remote | Workspace Name |
|-----------|----------------|
| `github.com/username/project` | `username/project` |
| `gitlab.com/username/project` | `username/project` |
| No remote | `<username>/<directory>` |

---

## Resource Installation

### How Resources Flow

1. **Download**: Bundle fetched to the augent cache (run `augent cache` to see the path)
2. **Transform**: Resources transformed to AI coding platform-specific format
3. **Merge**: Merged into existing resources (if applicable)
4. **Install**: Copied to AI coding platform directories
5. **Track**: Metadata added to `augent.index.yaml`

### Installation Locations

| Resource Type | Cursor | Claude Code | OpenCode |
|--------------|--------|-------------|----------|
| Rules | `.cursor/rules/` (`.mdc`) | `.claude/rules/` | `.opencode/rules/` |
| Skills | `.cursor/skills/` | `.claude/skills/` | `.opencode/skills/` (each skill in `{name}/SKILL.md`) |
| Commands | `.cursor/commands/` | `.claude/commands/` | `.opencode/commands/` |
| MCP | `.cursor/mcp.json` | `.mcp.json` (project root; Claude Code) | `.opencode/opencode.json` (MCP key in main config) |
| AGENTS.md | Merged into `AGENTS.md` | Merged into `CLAUDE.md` | Merged into `AGENTS.md` |
| Root files | Copied to workspace root |  |  |

### Merge Strategies

| File Type | Merge Strategy | Behavior |
|-----------|----------------|----------|
| Rules/Skills/Commands | Replace | Later bundle overwrites earlier |
| MCP config (mcp.json, opencode.json) | Deep | JSON merged, later values override |
| AGENTS.md / root file | Composite | Text merged with delimiter |
| Root files | Replace | Later bundle overwrites earlier |

---

## Modified File Detection

Augent tracks modifications to prevent data loss:

### Detection Process

1. Calculate hash of original file from cached bundle
2. Compare with current workspace file hash
3. If different, file is marked as modified
4. Modified files are copied to workspace bundle directory

### Handling Modified Files

**Before uninstall:**

```bash
augent uninstall my-bundle
# Warning: Some files modified
# Modified files backed up locally
```

**Before install:**

```bash
augent install new-bundle
# Warning: New bundle would overwrite modified files
# Modified files preserved locally
```

### Checking Modifications

```bash
# Augent warns about modifications automatically
augent install github:author/new-bundle

# View workspace configuration to see tracking
cat .augent/augent.index.yaml
```

---

## Platform Detection

Augent automatically detects installed AI coding platforms:

### Detection Methods

1. **Directory Check**
   - `.claude/` → Claude Code
   - `.cursor/` → Cursor
   - `.opencode/` → OpenCode

2. **File Check**
   - `CLAUDE.md` → Claude Code
   - `AGENTS.md` → Generic/OpenCode

### Installing for Specific Platforms

```bash
# Install only for specific platforms
augent install ./bundle --for cursor opencode

# Auto-detect platforms
augent install ./bundle
```

### Platform Aliases

| Alias | Full Name |
|-------|-----------|
| `claude` | `claude-code` |
| `cursor` | `cursor` |
| `opencode` | `opencode` |

---

## Locking and Reproducibility

### Lockfile Purpose

`augent.lock` ensures:

1. **Team consistency:** Same bundle versions across team
2. **Reproducibility:** Exact SHAs for all dependencies
3. **Safety:** Detects unexpected changes

### Frozen Install (CI/CD)

```bash
# Fail if lockfile would change
augent install --frozen
```

**Use cases:**

- CI/CD pipelines
- Production deployments
- Verifying exact dependencies

### Updating Lockfile

```bash
# Update to latest versions
augent install github:author/bundle

# Lockfile updated automatically
cat .augent/augent.lock
```

---

## Bundle Lifecycle

### Adding Bundles

Add to `augent.yaml` and run `augent install`:

- Bundle resolved and added to `augent.lock` and `augent.index.yaml`
- Resources installed to platform directories

### Removing from Configuration

Removing from `augent.yaml` and running `augent install`:

- Bundle **NOT** removed from lockfile or workspace config
- Files **NOT** uninstalled
- Allows temporary disabling without losing configuration

### Explicit Removal

Use `augent uninstall <name>` to completely remove:

- Files removed (unless overridden by other bundles)
- Entries removed from all config files
- Dependencies cleaned up if unused

### Configuration Files

| File | Contains | Updated When | Removed When |
|------|----------|--------------|--------------|
| `augent.yaml` | Direct bundles only (name, path/git) | Install adds entry; order preserved | Manual deletion |
| `augent.lock` | All bundles (direct + transitive), ref + exact SHA | Updated first on install | `augent uninstall` |
| `augent.index.yaml` | Installed file tracking, in order | Updated after lock and yaml | `augent uninstall` |

---

## Workspace Cleanup

### Removing Bundles

```bash
augent uninstall my-bundle
# Removes bundle files
# Updates configuration
# Preserves modified files
```

### Resetting Workspace

```bash
# Remove all Augent configuration
rm -rf .augent

# Clean agent directories (optional)
rm -rf .claude .cursor .opencode

# Reinstall bundles
augent install github:author/bundle
```

### Cache Management

```bash
# Show cache statistics
augent cache

# List cached bundles
augent cache list

# Clear all cached bundles
augent cache clear

# Remove specific bundle
augent cache clear --only github.com-author-repo
```

---

## Best Practices

### Version Control

**Commit `.augent/` directory:**

```bash
git add .augent/
git commit -m "Add debug-tools bundle"
```

**Commit lockfile for reproducibility:**

```bash
git add .augent/augent.lock
git commit -m "Lock dependency versions"
```

**Don't commit:**

- Agent directories with secrets

### Bundle Ordering

**Order matters:** Put overrides last. Entries are stored in canonical form (see [Bundles spec](implementation/specs/bundles.md)):

```yaml
bundles:
  - name: '@owner/base-config'
    git: https://github.com/owner/base-config.git
    path: .
  - name: '@owner/team-standards'
    git: https://github.com/owner/team-standards.git
    path: .
  - name: local-bundle
    path: ./local-bundle
```

### Team Collaboration

1. **Share `.augent/augent.yaml`:** Defines team bundles
2. **Commit lockfile:** Ensures everyone uses same versions
3. **Document modifications:** Track manual changes to resources
4. **Use frozen installs in CI:** Prevents unexpected updates

---

## Troubleshooting

### Bundle Not Found

```bash
Error: Bundle not found: my-bundle
```

**Check:**

- Bundle name is correct
- Bundle is installed (`augent list`)
- Case sensitivity matters

### Conflicts

```bash
Warning: File already provided by another bundle
```

**Resolution:**

- Check bundle order in `augent.yaml`
- Later bundles override earlier bundles
- Adjust order if needed

### Modified Files

```bash
Warning: Some files were modified
```

**Action:**

- Modified files backed up locally
- Review before uninstalling
- Manually merge if needed

### Lockfile Mismatch

```bash
Error: Lockfile would change (use --frozen to fail)
```

**Resolution:**

- Update lockfile: `augent install github:author/bundle`
- Or use `--frozen` for CI/CD

---

## See Also

- [Commands Reference](commands.md) - Managing workspaces via CLI
- [Bundle Format](bundles.md) - Creating and publishing bundles
- [Architecture Documentation](implementation/architecture.md) - Implementation details
