camp

![camp banner](docs/images/banner.jpg)

# camp

> **Part of [Festival](https://github.com/Obedience-Corp/festival)** - mission-based AI workspace management. Camp handles workspace management; [fest](https://github.com/Obedience-Corp/fest) handles hierarchical planning. Together they give structure to how you work across multiple projects, contexts, and AI agents.

Campaign workspace manager for multi-project AI development.

## Features

- **Navigation** - Category shortcuts, fuzzy finding, bookmarks (`go`, `pin`, `shortcuts`)
- **Project Management** - Git submodules, worktrees, and project scaffolding (`project add/list/remove/new/worktree`)
- **Planning** - Intents, status flows, dungeon for deprioritized work (`intent`, `flow`, `dungeon`, `gather`)
- **Productivity** - Leverage scoring to identify high-impact work (`leverage`)
- **Git Integration** - Campaign-level git operations (`commit`, `log`, `push`, `status`)
- **Campaign Ops** - Health checks, file operations, cross-campaign tools (`doctor`, `copy`, `move`, `sync`)
- **Shell Integration** - Native cd behavior with zsh, bash, and fish (`shell-init`)
- **Tab Completion** - Smart completion for categories, projects, and paths

## Installation

### Go Install

```bash
go install github.com/Obedience-Corp/camp@latest
```

### From Source

```bash
git clone https://github.com/Obedience-Corp/camp
cd camp
just install stable
```

### Shell Integration

Add to your shell config to enable the `cgo` navigation function and tab completion:

**Zsh** (~/.zshrc):
```bash
eval "$(camp shell-init zsh)"
```

**Bash** (~/.bashrc):
```bash
eval "$(camp shell-init bash)"
```

**Fish** (~/.config/fish/config.fish):
```fish
camp shell-init fish | source
```

The eval hook provides:
- **`cgo` function** - Shell-native navigation with actual `cd` behavior
- **Tab completion** - Context-aware completion for categories, projects, and commands
- **`camp` completion** - Full command completion for the camp CLI

After adding the eval line, restart your shell or run `source ~/.zshrc` (or equivalent).

## Quick Start

```bash
# 1. Initialize a campaign
mkdir my-campaign && cd my-campaign
camp init

# 2. Add shell integration (restart shell after)
echo 'eval "$(camp shell-init zsh)"' >> ~/.zshrc

# 3. Navigate!
cgo p          # Jump to projects/
cgo f          # Jump to festivals/
cgo p api      # Fuzzy find "api" in projects/
```

## Category Shortcuts

Navigate instantly with single-letter shortcuts:

| Shortcut | Directory              | Description            |
|----------|------------------------|------------------------|
| `p`      | projects/              | Project subdirectories |
| `f`      | festivals/             | Festival methodology   |
| `w`      | workflow/              | Workflow directory     |
| `ai`     | ai_docs/               | AI documentation       |
| `d`      | docs/                  | Human documentation    |
| `i`      | .campaign/intents/     | Intents via `camp intent` |
| `wt`     | projects/worktrees/    | Git worktrees          |
| `du`     | dungeon/               | Archived work          |
| `cr`     | workflow/code_reviews/ | Code review materials  |
| `pi`     | workflow/pipelines/    | CI/CD pipelines        |
| `de`     | workflow/design/       | Design documents       |
| `ex`     | workflow/explore/      | Exploratory notes      |

`cgo i` remains available as an operator shortcut into the hidden intent state,
but the normal human interface is `camp intent`.

## Commands

### Navigation - `cgo`

The `cgo` shell function is your primary interface:

```bash
# Jump to campaign root
cgo

# Jump to category
cgo p               # projects/
cgo f               # festivals/

# Fuzzy search within category
cgo p api           # projects/api-* (matches api-service, api-gateway, etc.)
cgo f fest          # festivals/*fest*

# Run command from category (without changing directory)
cgo -c p ls           # List contents of projects/
cgo -c f fest status  # Run fest status from festivals/
```

**Bookmarks**: Pin frequently visited directories for quick access:

```bash
camp pin             # Bookmark current directory
camp pins            # List all bookmarks
camp unpin           # Remove bookmark
```

**Shortcuts**: View all category shortcuts and custom shortcuts:

```bash
camp shortcuts       # List all available shortcuts
```

### Setup

```bash
camp init                  # Initialize current directory
camp init my-campaign      # Create and initialize new directory
camp clone <url>           # Clone a campaign with full submodule setup
```

### Project Management

```bash
camp project add <url>     # Add git submodule
camp project list          # List all projects
camp project remove <name> # Remove a project
camp project new <name>    # Create a new project
camp project worktree      # Manage git worktrees
camp project commit        # Commit within a project
```

All project commands support `--project / -p` with tab completion to target a project by name:

```bash
camp project commit --project camp -m "Fix bug"   # Explicit project
camp project commit -m "Fix bug"                   # Auto-detect from cwd
camp project worktree add feature -p camp          # Worktree for specific project
```

Monorepo subprojects are addressable with `@` syntax (e.g., `obey-platform-monorepo@obey`).

### Planning

Intents, status flows, and the dungeon provide lightweight planning tools:

```bash
# Intents - capture ideas, goals, and work items
camp intent                # Manage campaign intents
camp intent add --campaign other-campaign "Capture idea"  # Cross-campaign capture (add only)
camp gather                # Import external data into the intent system

# Flows - track work status
camp flow                  # Manage status workflows for organizing work

# Dungeon - archive deprioritized work
camp dungeon               # Move items to/from the dungeon
```

### Productivity

```bash
# Leverage scoring - identify high-impact work
camp leverage              # Compute leverage scores for campaign projects
```

See [docs/leverage-score.md](docs/leverage-score.md) for details on the scoring algorithm.

### Git Integration

Campaign-level git operations:

```bash
camp commit                # Commit changes in the campaign root
camp log                   # Show git log of the campaign
camp push                  # Push campaign changes to remote
camp push all              # Push all submodules with unpushed changes
camp pull                  # Pull latest changes
camp pull all              # Pull all submodules
camp status                # Show git status of the campaign
camp status all            # Dashboard of all submodules (branch, dirty/clean, push status, unmerged branches)
camp status all --view     # Interactive TUI viewer with per-repo detail
```

### Campaign Operations

```bash
camp doctor                # Diagnose and fix campaign health issues
camp sync                  # Safely synchronize submodules
camp copy                  # Copy a file or directory within the campaign
camp move                  # Move a file or directory within the campaign
camp run                   # Execute command from campaign root, or just recipe in a project
```

### Global Commands

```bash
camp list                  # List all registered campaigns
camp switch                # Switch to a different campaign
camp transfer              # Copy files between campaigns
camp register              # Register campaign in global registry
camp unregister            # Remove campaign from registry
```

### System

```bash
camp settings              # Manage camp configuration
camp date                  # Append date suffix to file or directory name
camp version               # Show version information
```

### Shell Integration

```bash
camp shell-init zsh       # Output zsh init script
camp shell-init bash      # Output bash init script
camp shell-init fish      # Output fish init script
```

#### How the Eval Hook Works

T

[truncated…]