@brickhouse-tech/sync-agents 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# sync-agents
+
+One set of agent rules to rule them all. `sync-agents` keeps your AI coding agent configurations in a single `.agents/` directory and syncs them to agent-specific directories (`.claude/`, `.windsurf/`) via symlinks. This ensures all agents follow the same rules, skills, and workflows without duplicating files.
+
+AGENTS.md serves as an auto-generated index of everything in `.agents/` and is symlinked to CLAUDE.md for Claude compatibility.
+
+## Installation
+
+```bash
+npm install @brickhouse-tech/sync-agents
+```
+
+or globally:
+
+```bash
+npm install -g @brickhouse-tech/sync-agents
+```
+
+## Topology
+
+`.agents/` is the source of truth. It contains all rules, skills, workflows, and state for your agents:
+
+```
+.agents/
+  ├── rules/
+  │   ├── rule1.md
+  │   ├── rule2.md
+  │   └── ...
+  ├── skills/
+  │   ├── skill1.md
+  │   ├── skill2.md
+  │   └── ...
+  ├── workflows/
+  │   ├── workflow1.md
+  │   ├── workflow2.md
+  │   └── ...
+  └── STATE.md
+```
+
+Running `sync-agents sync` creates symlinks from `.agents/` subdirectories into `.claude/` and `.windsurf/`. Any changes to `.agents/` are automatically reflected in the target directories because they are symlinks, not copies.
+
+AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively.
+
+## STATE.md
+
+`.agents/STATE.md` tracks the current state of your project from the agent's perspective. It serves as a resumption point after failures or interruptions -- the agent can read STATE.md to determine where it left off and what tasks remain. Update it regularly to keep agents in sync with progress.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `init` | Initialize the `.agents/` directory structure with `rules/`, `skills/`, `workflows/`, `STATE.md`, and generate `AGENTS.md` |
+| `sync` | Create symlinks from `.agents/` into `.claude/` and `.windsurf/`, and symlink `AGENTS.md` to `CLAUDE.md` |
+| `status` | Show the current sync status of all targets and symlinks |
+| `add <type> <name>` | Add a new rule, skill, or workflow from a template (type is `rule`, `skill`, or `workflow`) |
+| `index` | Regenerate `AGENTS.md` by scanning the contents of `.agents/` |
+| `clean` | Remove all synced symlinks and empty target directories (does not remove `.agents/`) |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-h`, `--help` | Show help message |
+| `-v`, `--version` | Show version |
+| `-d`, `--dir <path>` | Set project root directory (default: current directory) |
+| `--targets <list>` | Comma-separated list of sync targets (default: `claude,windsurf`) |
+| `--dry-run` | Show what would be done without making changes |
+| `--force` | Overwrite existing files and symlinks |
+
+## Usage
+
+```bash
+# Initialize .agents/ structure in the current project
+sync-agents init
+
+# Add a new rule
+sync-agents add rule no-eval
+
+# Add a new skill
+sync-agents add skill debugging
+
+# Add a new workflow
+sync-agents add workflow deploy
+
+# Sync to all targets (.claude/ and .windsurf/)
+sync-agents sync
+
+# Sync to a specific target only
+sync-agents sync --targets claude
+
+# Preview sync without making changes
+sync-agents sync --dry-run
+
+# Force overwrite existing symlinks
+sync-agents sync --force
+
+# Check sync status
+sync-agents status
+
+# Regenerate the AGENTS.md index
+sync-agents index
+
+# Remove all synced symlinks
+sync-agents clean
+
+# Work in a different directory
+sync-agents sync --dir /path/to/project
+```

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@brickhouse-tech/sync-agents",
+  "version": "0.1.0",
+  "description": "AWS CFT Utilities to fill the gaps for Cloud Formation",
+  "keywords": [
+    "cft",
+    "aws",
+    "cloudformation"
+  ],
+  "homepage": "https://github.com/brickhouse-tech/sync-agents#readme",
+  "bugs": {
+    "url": "https://github.com/brickhouse-tech/sync-agents/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brickhouse-tech/sync-agents.git"
+  },
+  "author": "Nicholas McCready",
+  "bin": {
+    "sync-agents": "src/sh/sync-agents.sh"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "scripts": {
+    "test": "npx bats test/"
+  },
+  "dependencies": {
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20",
+    "@commitlint/config-conventional": "^20",
+    "commitlint": "20",
+    "sort-package-json": "3.6"
+  }
+}

package/src/md/RULE_TEMPLATE.md

@@ -0,0 +1,6 @@
+
+---
+trigger: always_on
+---
+
+# ${NAME}

package/src/md/STATE_TEMPLATE.md

@@ -0,0 +1,42 @@
+
+---
+trigger: always_on
+---
+
+# State
+
+This is the state template for sync-agents. It is used to define the state of the agent and its environment. The state markdown file itself is a human readble source for the agent to read and understand its current situation. It can be used to track the progress of the agent, identify any issues or challenges it may be facing, and provide a clear overview of its goals and objectives. The state is an important tool for the agent to use in order to make informed decisions and take appropriate actions to achieve its goals. By maintaining an up-to-date state, the agent can continuously learn and evolve, becoming more effective and efficient in its tasks.
+
+The goal is to improve the performance of the agent by providing it with a clear and structured representation of its current situation. This allows the agent to make informed decisions and take appropriate actions to achieve its goals. The state is also used to track the progress of the agent and identify any issues or areas for improvement. By maintaining an up-to-date state, the agent can continuously learn and evolve, becoming more effective and efficient in its xtasks.
+
+## TRACKING Agent State
+
+Every state tracking will begin with a header of `### YYYYMMDDHHMMSS STATE: <STATE_NAME or OBJECTIVE` followed by a description of the state, any relevant information about the agent's performance, issues, or updates, and any actions taken or planned to address the current state. This format allows for easy tracking and monitoring of the agent's progress over time, as well as providing a clear record of the agent's history and development. By maintaining a detailed and organized state history, the agent can learn from past experiences and make informed decisions to improve its performance in the future.> 
+
+The format above will be written below the `## STATE HISTORY BELOW` header in the STATE.md file. This allows for easy tracking and monitoring of the agent's progress over time, as well as providing a clear record of the agent's history and development. By maintaining a detailed and organized state history, the agent can learn from past experiences and make informed decisions to improve its performance in the future.
+
+## Formatted Agent State
+
+The formatted agent state will be a structured representation of the agent's current situation, including its goals, objectives, performance metrics, and any relevant information about its environment. This formatted state will be used by the agent to make informed decisions and take appropriate actions to achieve its goals. By maintaining an up-to-date and well-structured formatted state, the agent can continuously learn and evolve, becoming more effective and efficient in its tasks. The formatted state will also be used to track the progress of the agent and identify any issues or areas for improvement, allowing for continuous optimization of the agent's performance.
+
+Example:
+
+The state is structured as follows:
+
+```json
+{
+  "agent_name": "string",
+  "goals": ["string"],
+  "skills": ["string"],
+  "workflows": ["string"],
+  "issues": ["string"],
+  "last_updated": "timestamp"
+}
+```
+to `.agents/state.json`
+
+## STATE HISTORY BELOW
+
+
+
+

package/src/sh/sync-agents.sh

@@ -0,0 +1,569 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+AGENTS_DIR=".agents"
+AGENTS_MD="AGENTS.md"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_JSON="${SCRIPT_DIR}/../../package.json"
+TEMPLATES_DIR="${SCRIPT_DIR}/../md"
+
+# Pull version from package.json
+if [[ -f "$PACKAGE_JSON" ]]; then
+  VERSION="$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' "$PACKAGE_JSON" | head -1)"
+else
+  VERSION="unknown"
+fi
+
+# Agent target directories
+TARGETS=("claude" "windsurf")
+
+# Colors (disabled if not a terminal)
+if [[ -t 1 ]]; then
+  BOLD='\033[1m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[0;33m'
+  RED='\033[0;31m'
+  CYAN='\033[0;36m'
+  RESET='\033[0m'
+else
+  BOLD='' GREEN='' YELLOW='' RED='' CYAN='' RESET=''
+fi
+
+info()  { echo -e "${GREEN}[info]${RESET} $*"; }
+warn()  { echo -e "${YELLOW}[warn]${RESET} $*"; }
+error() { echo -e "${RED}[error]${RESET} $*" >&2; }
+
+usage() {
+  cat <<EOF
+${BOLD}sync-agents${RESET} v${VERSION} - One set of agent rules to rule them all.
+
+${BOLD}USAGE${RESET}
+  sync-agents <command> [options]
+
+${BOLD}COMMANDS${RESET}
+  init                          Initialize .agents/ directory structure and AGENTS.md
+  sync                          Sync .agents/ to .claude/ and .windsurf/ via symlinks
+  status                        Show current sync status
+  add <type> <name>             Add a new rule, skill, or workflow from template
+  index                         Regenerate AGENTS.md index from .agents/ contents
+  clean                         Remove all synced symlinks (does not remove .agents/)
+
+${BOLD}OPTIONS${RESET}
+  -h, --help                    Show this help message
+  -v, --version                 Show version
+  -d, --dir <path>              Set project root directory (default: current directory)
+  --targets <list>              Comma-separated targets to sync (default: claude,windsurf)
+  --dry-run                     Show what would be done without making changes
+  --force                       Overwrite existing files/symlinks
+
+${BOLD}EXAMPLES${RESET}
+  sync-agents init              # Initialize .agents/ structure
+  sync-agents add rule no-eval  # Add a new rule called "no-eval"
+  sync-agents sync              # Sync to .claude/ and .windsurf/
+  sync-agents sync --targets claude
+  sync-agents status            # Show current state
+  sync-agents clean             # Remove synced symlinks
+
+EOF
+}
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+find_project_root() {
+  local dir="${1:-.}"
+  dir="$(cd "$dir" && pwd)"
+
+  # Walk up to find a directory with .agents or .git
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/$AGENTS_DIR" ]] || [[ -d "$dir/.git" ]]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+
+  # Fallback to current directory
+  pwd
+}
+
+ensure_agents_dir() {
+  if [[ ! -d "$PROJECT_ROOT/$AGENTS_DIR" ]]; then
+    error ".agents/ directory not found. Run 'sync-agents init' first."
+    exit 1
+  fi
+}
+
+create_symlink() {
+  local source="$1"
+  local target="$2"
+  local dry_run="${3:-false}"
+
+  if [[ "$dry_run" == "true" ]]; then
+    echo "  would link: $target -> $source"
+    return 0
+  fi
+
+  local target_dir
+  target_dir="$(dirname "$target")"
+  mkdir -p "$target_dir"
+
+  if [[ -L "$target" ]]; then
+    local existing
+    existing="$(readlink "$target")"
+    if [[ "$existing" == "$source" ]]; then
+      return 0  # Already correct
+    fi
+    if [[ "$FORCE" == "true" ]]; then
+      rm "$target"
+    else
+      warn "Symlink already exists: $target -> $existing (use --force to overwrite)"
+      return 1
+    fi
+  elif [[ -e "$target" ]]; then
+    if [[ "$FORCE" == "true" ]]; then
+      rm -rf "$target"
+    else
+      warn "File already exists: $target (use --force to overwrite)"
+      return 1
+    fi
+  fi
+
+  ln -sf "$source" "$target"
+  info "Linked: $target -> $source"
+}
+
+# --------------------------------------------------------------------------
+# Commands
+# --------------------------------------------------------------------------
+
+cmd_init() {
+  info "Initializing $AGENTS_DIR/ directory structure..."
+
+  mkdir -p "$PROJECT_ROOT/$AGENTS_DIR/rules"
+  mkdir -p "$PROJECT_ROOT/$AGENTS_DIR/skills"
+  mkdir -p "$PROJECT_ROOT/$AGENTS_DIR/workflows"
+
+  # Copy STATE.md template if STATE.md doesn't exist
+  if [[ ! -f "$PROJECT_ROOT/$AGENTS_DIR/STATE.md" ]]; then
+    if [[ -f "$TEMPLATES_DIR/STATE_TEMPLATE.md" ]]; then
+      cp "$TEMPLATES_DIR/STATE_TEMPLATE.md" "$PROJECT_ROOT/$AGENTS_DIR/STATE.md"
+      info "Created $AGENTS_DIR/STATE.md from template"
+    else
+      # Inline fallback if template not found
+      cat > "$PROJECT_ROOT/$AGENTS_DIR/STATE.md" <<'STATE_EOF'
+
+---
+trigger: always_on
+---
+
+# State
+
+## STATE HISTORY BELOW
+
+
+STATE_EOF
+      info "Created $AGENTS_DIR/STATE.md"
+    fi
+  else
+    warn "$AGENTS_DIR/STATE.md already exists, skipping"
+  fi
+
+  # Generate AGENTS.md if it doesn't exist
+  if [[ ! -f "$PROJECT_ROOT/$AGENTS_MD" ]]; then
+    generate_agents_md
+    info "Created $AGENTS_MD"
+  else
+    warn "$AGENTS_MD already exists, skipping (run 'sync-agents index' to regenerate)"
+  fi
+
+  info "Initialization complete. Directory structure:"
+  print_tree "$PROJECT_ROOT/$AGENTS_DIR"
+}
+
+cmd_add() {
+  local type="${1:-}"
+  local name="${2:-}"
+
+  if [[ -z "$type" ]] || [[ -z "$name" ]]; then
+    error "Usage: sync-agents add <rule|skill|workflow> <name>"
+    exit 1
+  fi
+
+  case "$type" in
+    rule|rules)     type="rules" ;;
+    skill|skills)   type="skills" ;;
+    workflow|workflows) type="workflows" ;;
+    *)
+      error "Unknown type: $type. Must be one of: rule, skill, workflow"
+      exit 1
+      ;;
+  esac
+
+  ensure_agents_dir
+
+  local filepath="$PROJECT_ROOT/$AGENTS_DIR/$type/$name.md"
+
+  if [[ -f "$filepath" ]] && [[ "$FORCE" != "true" ]]; then
+    error "File already exists: $filepath (use --force to overwrite)"
+    exit 1
+  fi
+
+  # Use RULE_TEMPLATE for all types, substituting name
+  if [[ -f "$TEMPLATES_DIR/RULE_TEMPLATE.md" ]]; then
+    sed "s/\${NAME}/$name/g" "$TEMPLATES_DIR/RULE_TEMPLATE.md" > "$filepath"
+  else
+    cat > "$filepath" <<TMPL_EOF
+
+---
+trigger: always_on
+---
+
+# $name
+TMPL_EOF
+  fi
+
+  info "Created $type: $filepath"
+
+  # Regenerate index
+  generate_agents_md
+  info "Updated $AGENTS_MD index"
+}
+
+cmd_sync() {
+  ensure_agents_dir
+
+  local agents_abs
+  agents_abs="$(cd "$PROJECT_ROOT/$AGENTS_DIR" && pwd)"
+
+  info "Syncing $AGENTS_DIR/ to agent directories..."
+
+  for target in "${ACTIVE_TARGETS[@]}"; do
+    local target_dir="$PROJECT_ROOT/.$target"
+    info "Syncing to .${target}/"
+
+    # Sync subdirectories: rules, skills, workflows
+    for subdir in rules skills workflows; do
+      if [[ -d "$agents_abs/$subdir" ]]; then
+        local source_rel
+        source_rel="$(python3 -c "import os.path; print(os.path.relpath('$agents_abs/$subdir', '$(dirname "$target_dir/$subdir")'))" 2>/dev/null || echo "../$AGENTS_DIR/$subdir")"
+        create_symlink "$source_rel" "$target_dir/$subdir" "$DRY_RUN"
+      fi
+    done
+  done
+
+  # Symlink AGENTS.md -> CLAUDE.md
+  if [[ -f "$PROJECT_ROOT/$AGENTS_MD" ]]; then
+    create_symlink "$AGENTS_MD" "$PROJECT_ROOT/CLAUDE.md" "$DRY_RUN"
+  fi
+
+  info "Sync complete."
+}
+
+cmd_status() {
+  echo -e "${BOLD}sync-agents${RESET} v${VERSION}"
+  echo ""
+
+  # Check .agents/ directory
+  if [[ -d "$PROJECT_ROOT/$AGENTS_DIR" ]]; then
+    echo -e "${GREEN}[ok]${RESET} $AGENTS_DIR/ exists"
+    print_tree "$PROJECT_ROOT/$AGENTS_DIR"
+  else
+    echo -e "${RED}[missing]${RESET} $AGENTS_DIR/ not found"
+  fi
+
+  echo ""
+
+  # Check AGENTS.md
+  if [[ -f "$PROJECT_ROOT/$AGENTS_MD" ]]; then
+    echo -e "${GREEN}[ok]${RESET} $AGENTS_MD exists"
+  else
+    echo -e "${RED}[missing]${RESET} $AGENTS_MD not found"
+  fi
+
+  # Check CLAUDE.md symlink
+  if [[ -L "$PROJECT_ROOT/CLAUDE.md" ]]; then
+    local link_target
+    link_target="$(readlink "$PROJECT_ROOT/CLAUDE.md")"
+    echo -e "${GREEN}[ok]${RESET} CLAUDE.md -> $link_target"
+  elif [[ -f "$PROJECT_ROOT/CLAUDE.md" ]]; then
+    echo -e "${YELLOW}[warn]${RESET} CLAUDE.md exists but is not a symlink"
+  else
+    echo -e "${RED}[missing]${RESET} CLAUDE.md not found"
+  fi
+
+  echo ""
+
+  # Check each target
+  for target in "${TARGETS[@]}"; do
+    local target_dir="$PROJECT_ROOT/.$target"
+    if [[ -d "$target_dir" ]] || [[ -L "$target_dir/rules" ]]; then
+      echo -e "${CYAN}.$target/${RESET}"
+      for subdir in rules skills workflows; do
+        if [[ -L "$target_dir/$subdir" ]]; then
+          local link_target
+          link_target="$(readlink "$target_dir/$subdir")"
+          echo -e "  ${GREEN}[synced]${RESET} $subdir -> $link_target"
+        elif [[ -d "$target_dir/$subdir" ]]; then
+          echo -e "  ${YELLOW}[local]${RESET} $subdir (not symlinked)"
+        else
+          echo -e "  ${RED}[missing]${RESET} $subdir"
+        fi
+      done
+    else
+      echo -e "${RED}[not synced]${RESET} .$target/"
+    fi
+  done
+}
+
+cmd_index() {
+  ensure_agents_dir
+  generate_agents_md
+  info "Regenerated $AGENTS_MD"
+}
+
+cmd_clean() {
+  info "Removing synced symlinks..."
+
+  for target in "${ACTIVE_TARGETS[@]}"; do
+    local target_dir="$PROJECT_ROOT/.$target"
+    for subdir in rules skills workflows; do
+      if [[ -L "$target_dir/$subdir" ]]; then
+        rm "$target_dir/$subdir"
+        info "Removed: .$target/$subdir"
+      fi
+    done
+
+    # Remove target dir if empty
+    if [[ -d "$target_dir" ]] && [[ -z "$(ls -A "$target_dir" 2>/dev/null)" ]]; then
+      rmdir "$target_dir"
+      info "Removed empty directory: .$target/"
+    fi
+  done
+
+  # Remove CLAUDE.md symlink
+  if [[ -L "$PROJECT_ROOT/CLAUDE.md" ]]; then
+    rm "$PROJECT_ROOT/CLAUDE.md"
+    info "Removed: CLAUDE.md symlink"
+  fi
+
+  info "Clean complete."
+}
+
+# --------------------------------------------------------------------------
+# Index generator
+# --------------------------------------------------------------------------
+
+generate_agents_md() {
+  local outfile="$PROJECT_ROOT/$AGENTS_MD"
+  local agents_dir="$PROJECT_ROOT/$AGENTS_DIR"
+
+  cat > "$outfile" <<'HEADER'
+
+---
+trigger: always_on
+---
+
+# AGENTS
+
+> Auto-generated by [sync-agents](https://github.com/brickhouse-tech/sync-agents). Do not edit manually.
+> Run `sync-agents index` to regenerate.
+
+This file indexes all rules, skills, and workflows defined in `.agents/`.
+
+HEADER
+
+  # Rules
+  echo "## Rules" >> "$outfile"
+  echo "" >> "$outfile"
+  if compgen -G "$agents_dir/rules/*.md" > /dev/null 2>&1; then
+    for f in "$agents_dir/rules/"*.md; do
+      local name
+      name="$(basename "$f" .md)"
+      echo "- [$name](.agents/rules/$name.md)" >> "$outfile"
+    done
+  else
+    echo "_No rules defined yet. Add one with \`sync-agents add rule <name>\`._" >> "$outfile"
+  fi
+  echo "" >> "$outfile"
+
+  # Skills
+  echo "## Skills" >> "$outfile"
+  echo "" >> "$outfile"
+  if compgen -G "$agents_dir/skills/*.md" > /dev/null 2>&1; then
+    for f in "$agents_dir/skills/"*.md; do
+      local name
+      name="$(basename "$f" .md)"
+      echo "- [$name](.agents/skills/$name.md)" >> "$outfile"
+    done
+  else
+    echo "_No skills defined yet. Add one with \`sync-agents add skill <name>\`._" >> "$outfile"
+  fi
+  echo "" >> "$outfile"
+
+  # Workflows
+  echo "## Workflows" >> "$outfile"
+  echo "" >> "$outfile"
+  if compgen -G "$agents_dir/workflows/*.md" > /dev/null 2>&1; then
+    for f in "$agents_dir/workflows/"*.md; do
+      local name
+      name="$(basename "$f" .md)"
+      echo "- [$name](.agents/workflows/$name.md)" >> "$outfile"
+    done
+  else
+    echo "_No workflows defined yet. Add one with \`sync-agents add workflow <name>\`._" >> "$outfile"
+  fi
+  echo "" >> "$outfile"
+
+  # State reference
+  echo "## State" >> "$outfile"
+  echo "" >> "$outfile"
+  echo "- [STATE.md](.agents/STATE.md)" >> "$outfile"
+  echo "" >> "$outfile"
+}
+
+# --------------------------------------------------------------------------
+# Tree printer (lightweight, no dependency on `tree`)
+# --------------------------------------------------------------------------
+
+print_tree() {
+  local dir="$1"
+  local prefix="${2:-}"
+  local entries=()
+
+  # Collect entries
+  while IFS= read -r entry; do
+    entries+=("$entry")
+  done < <(ls -1A "$dir" 2>/dev/null | sort)
+
+  local count=${#entries[@]}
+  if [[ $count -eq 0 ]]; then
+    return 0
+  fi
+  local i=0
+
+  for entry in "${entries[@]}"; do
+    i=$((i + 1))
+    local connector="├── "
+    local child_prefix="│   "
+    if [[ $i -eq $count ]]; then
+      connector="└── "
+      child_prefix="    "
+    fi
+
+    if [[ -d "$dir/$entry" ]]; then
+      echo "${prefix}${connector}${entry}/"
+      print_tree "$dir/$entry" "${prefix}${child_prefix}"
+    elif [[ -L "$dir/$entry" ]]; then
+      local link_target
+      link_target="$(readlink "$dir/$entry")"
+      echo "${prefix}${connector}${entry} -> ${link_target}"
+    else
+      echo "${prefix}${connector}${entry}"
+    fi
+  done
+}
+
+# --------------------------------------------------------------------------
+# Main
+# --------------------------------------------------------------------------
+
+main() {
+  local command=""
+  local custom_dir=""
+  local custom_targets=""
+  DRY_RUN="false"
+  FORCE="false"
+
+  # Parse arguments
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      -v|--version)
+        echo "sync-agents v${VERSION}"
+        exit 0
+        ;;
+      -d|--dir)
+        custom_dir="$2"
+        shift 2
+        ;;
+      --targets)
+        custom_targets="$2"
+        shift 2
+        ;;
+      --dry-run)
+        DRY_RUN="true"
+        shift
+        ;;
+      --force)
+        FORCE="true"
+        shift
+        ;;
+      -*)
+        error "Unknown option: $1"
+        usage
+        exit 1
+        ;;
+      *)
+        if [[ -z "$command" ]]; then
+          command="$1"
+        else
+          # Collect remaining args for subcommands
+          break
+        fi
+        shift
+        ;;
+    esac
+  done
+
+  # Resolve project root
+  if [[ -n "$custom_dir" ]]; then
+    PROJECT_ROOT="$(cd "$custom_dir" && pwd)"
+  else
+    PROJECT_ROOT="$(find_project_root)"
+  fi
+
+  # Resolve active targets
+  if [[ -n "$custom_targets" ]]; then
+    IFS=',' read -ra ACTIVE_TARGETS <<< "$custom_targets"
+  else
+    ACTIVE_TARGETS=("${TARGETS[@]}")
+  fi
+
+  # Dispatch command
+  case "${command:-}" in
+    init)
+      cmd_init
+      ;;
+    sync)
+      cmd_sync
+      ;;
+    status)
+      cmd_status
+      ;;
+    add)
+      cmd_add "$@"
+      ;;
+    index)
+      cmd_index
+      ;;
+    clean)
+      cmd_clean
+      ;;
+    "")
+      usage
+      exit 0
+      ;;
+    *)
+      error "Unknown command: $command"
+      usage
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"