@brickhouse-tech/sync-agents 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brickhouse Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,13 @@
 # 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.
+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/`, `.cursor/`, `.github/copilot/`) 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
 
+### npm
+
 ```bash
 npm install @brickhouse-tech/sync-agents
 ```
@@ -16,6 +18,13 @@ or globally:
 npm install -g @brickhouse-tech/sync-agents
 ```
 
+### Standalone (no npm required)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/src/sh/sync-agents.sh -o /usr/local/bin/sync-agents
+chmod +x /usr/local/bin/sync-agents
+```
+
 ## Topology
 
 `.agents/` is the source of truth. It contains all rules, skills, workflows, and state for your agents:
@@ -37,7 +46,7 @@ npm install -g @brickhouse-tech/sync-agents
   └── 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.
+Running `sync-agents sync` creates symlinks from `.agents/` subdirectories into `.claude/`, `.windsurf/`, `.cursor/`, and `.github/copilot/`. 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.
 
@@ -50,7 +59,10 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
 | 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` |
+| `sync` | Create symlinks from `.agents/` into all target directories, and symlink `AGENTS.md` to `CLAUDE.md` |
+| `watch` | Watch `.agents/` for changes and auto-regenerate `AGENTS.md` |
+| `import <url>` | Import a rule/skill/workflow from a URL |
+| `hook` | Install a pre-commit git hook for auto-sync |
 | `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/` |
@@ -63,7 +75,7 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
 | `-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`) |
+| `--targets <list>` | Comma-separated list of sync targets (default: `claude,windsurf,cursor,copilot`) |
 | `--dry-run` | Show what would be done without making changes |
 | `--force` | Overwrite existing files and symlinks |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brickhouse-tech/sync-agents",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Simple scripts to DRY up common agent interactions across multiple LLM providers.",
   "keywords": [
     "agents",

package/src/md/SKILL_TEMPLATE.md

@@ -0,0 +1,23 @@
+---
+trigger: always_on
+---
+
+# ${NAME}
+
+## Description
+
+Brief description of what this skill enables.
+
+## Usage
+
+When to use this skill and how to invoke it.
+
+## Examples
+
+```
+Example usage or invocation here.
+```
+
+## Notes
+
+Any caveats, prerequisites, or related skills.

package/src/md/STATE_TEMPLATE.md

@@ -1,42 +1,16 @@
-
 ---
 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
+Track project progress, current objectives, and resumption context.
+Update this file regularly so agents can pick up where they left off.
 
-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.
+## Format
 
-Example:
+### YYYYMMDDHHMMSS STATE: <objective>
 
-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`
+Description of current state, progress, blockers, and next steps.
 
 ## STATE HISTORY BELOW
-
-
-
-

package/src/md/WORKFLOW_TEMPLATE.md

@@ -0,0 +1,24 @@
+---
+trigger: always_on
+---
+
+# ${NAME}
+
+## Trigger
+
+Describe when this workflow should be activated.
+
+## Steps
+
+1. Step one
+2. Step two
+3. Step three
+
+## Conditions
+
+- Pre-conditions that must be met
+- Any guards or checks
+
+## Output
+
+What the workflow produces or changes when complete.

package/src/sh/sync-agents.sh

@@ -8,14 +8,18 @@ PACKAGE_JSON="${SCRIPT_DIR}/../../package.json"
 TEMPLATES_DIR="${SCRIPT_DIR}/../md"
 
 # Pull version from package.json
+# Try relative path first (works in repo / npm local install),
+# then resolve via node for global installs where the symlink target differs.
 if [[ -f "$PACKAGE_JSON" ]]; then
   VERSION="$(sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' "$PACKAGE_JSON" | head -1)"
+elif command -v node >/dev/null 2>&1; then
+  VERSION="$(node -p "require('@brickhouse-tech/sync-agents/package.json').version" 2>/dev/null || echo "unknown")"
 else
   VERSION="unknown"
 fi
 
 # Agent target directories
-TARGETS=("claude" "windsurf")
+TARGETS=("claude" "windsurf" "cursor" "copilot")
 
 # Colors (disabled if not a terminal)
 if [[ -t 1 ]]; then
@@ -33,6 +37,27 @@ info()  { echo -e "${GREEN}[info]${RESET} $*"; }
 warn()  { echo -e "${YELLOW}[warn]${RESET} $*"; }
 error() { echo -e "${RED}[error]${RESET} $*" >&2; }
 
+# Resolve target directory path (copilot uses .github/copilot/ instead of .copilot/)
+resolve_target_dir() {
+  local target="$1"
+  local root="$2"
+  if [[ "$target" == "copilot" ]]; then
+    echo "$root/.github/copilot"
+  else
+    echo "$root/.$target"
+  fi
+}
+
+# Resolve relative path from target dir back to .agents/ (accounts for depth)
+resolve_agents_rel() {
+  local target="$1"
+  if [[ "$target" == "copilot" ]]; then
+    echo "../../$AGENTS_DIR"
+  else
+    echo "../$AGENTS_DIR"
+  fi
+}
+
 usage() {
   cat <<EOF
 ${BOLD}sync-agents${RESET} v${VERSION} - One set of agent rules to rule them all.
@@ -42,17 +67,20 @@ ${BOLD}USAGE${RESET}
 
 ${BOLD}COMMANDS${RESET}
   init                          Initialize .agents/ directory structure and AGENTS.md
-  sync                          Sync .agents/ to .claude/ and .windsurf/ via symlinks
+  sync                          Sync .agents/ to agent directories 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/)
+  watch                         Watch .agents/ for changes and auto-regenerate index
+  import <url>                  Import a rule/skill/workflow from a URL
+  hook                          Install a pre-commit git hook for auto-sync
 
 ${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)
+  --targets <list>              Comma-separated targets (overrides .agents/config)
   --dry-run                     Show what would be done without making changes
   --force                       Overwrite existing files/symlinks
 
@@ -170,6 +198,19 @@ STATE_EOF
     warn "$AGENTS_DIR/STATE.md already exists, skipping"
   fi
 
+  # Create default config if it doesn't exist
+  if [[ ! -f "$PROJECT_ROOT/$AGENTS_DIR/config" ]]; then
+    cat > "$PROJECT_ROOT/$AGENTS_DIR/config" <<CONFIG_EOF
+# sync-agents configuration
+# Comma-separated list of sync targets (available: claude, windsurf, cursor, copilot)
+# Override per-command with: sync-agents sync --targets claude,cursor
+targets = claude,windsurf,cursor,copilot
+CONFIG_EOF
+    info "Created $AGENTS_DIR/config"
+  else
+    warn "$AGENTS_DIR/config already exists, skipping"
+  fi
+
   # Generate AGENTS.md if it doesn't exist
   if [[ ! -f "$PROJECT_ROOT/$AGENTS_MD" ]]; then
     generate_agents_md
@@ -210,8 +251,19 @@ cmd_add() {
     exit 1
   fi
 
-  # Use RULE_TEMPLATE for all types, substituting name
-  if [[ -f "$TEMPLATES_DIR/RULE_TEMPLATE.md" ]]; then
+  # Use type-specific template (RULE_TEMPLATE, SKILL_TEMPLATE, WORKFLOW_TEMPLATE)
+  local template_name
+  case "$type" in
+    rules)     template_name="RULE_TEMPLATE.md" ;;
+    skills)    template_name="SKILL_TEMPLATE.md" ;;
+    workflows) template_name="WORKFLOW_TEMPLATE.md" ;;
+    *)         template_name="RULE_TEMPLATE.md" ;;
+  esac
+
+  if [[ -f "$TEMPLATES_DIR/$template_name" ]]; then
+    sed "s/\${NAME}/$name/g" "$TEMPLATES_DIR/$template_name" > "$filepath"
+  elif [[ -f "$TEMPLATES_DIR/RULE_TEMPLATE.md" ]]; then
+    # Fallback to rule template if type-specific template missing
     sed "s/\${NAME}/$name/g" "$TEMPLATES_DIR/RULE_TEMPLATE.md" > "$filepath"
   else
     cat > "$filepath" <<TMPL_EOF
@@ -240,14 +292,16 @@ cmd_sync() {
   info "Syncing $AGENTS_DIR/ to agent directories..."
 
   for target in "${ACTIVE_TARGETS[@]}"; do
-    local target_dir="$PROJECT_ROOT/.$target"
-    info "Syncing to .${target}/"
+    local target_dir
+    target_dir="$(resolve_target_dir "$target" "$PROJECT_ROOT")"
+    local agents_rel
+    agents_rel="$(resolve_agents_rel "$target")"
+    info "Syncing to ${target_dir#"$PROJECT_ROOT"/}/"
 
     # 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")"
+        local source_rel="$agents_rel/$subdir"
         create_symlink "$source_rel" "$target_dir/$subdir" "$DRY_RUN"
       fi
     done
@@ -297,9 +351,11 @@ cmd_status() {
 
   # Check each target
   for target in "${TARGETS[@]}"; do
-    local target_dir="$PROJECT_ROOT/.$target"
+    local target_dir
+    target_dir="$(resolve_target_dir "$target" "$PROJECT_ROOT")"
+    local display_dir="${target_dir#"$PROJECT_ROOT"/}"
     if [[ -d "$target_dir" ]] || [[ -L "$target_dir/rules" ]]; then
-      echo -e "${CYAN}.$target/${RESET}"
+      echo -e "${CYAN}${display_dir}/${RESET}"
       for subdir in rules skills workflows; do
         if [[ -L "$target_dir/$subdir" ]]; then
           local link_target
@@ -312,7 +368,7 @@ cmd_status() {
         fi
       done
     else
-      echo -e "${RED}[not synced]${RESET} .$target/"
+      echo -e "${RED}[not synced]${RESET} ${display_dir}/"
     fi
   done
 }
@@ -323,22 +379,141 @@ cmd_index() {
   info "Regenerated $AGENTS_MD"
 }
 
+cmd_watch() {
+  ensure_agents_dir
+
+  local watch_dir="$PROJECT_ROOT/$AGENTS_DIR"
+
+  if command -v fswatch >/dev/null 2>&1; then
+    info "Watching $AGENTS_DIR/ for changes... (Ctrl+C to stop)"
+    cmd_index
+    fswatch -o "$watch_dir" | while read -r _; do
+      info "Change detected, regenerating index..."
+      cmd_index
+    done
+  elif command -v inotifywait >/dev/null 2>&1; then
+    info "Watching $AGENTS_DIR/ for changes... (Ctrl+C to stop)"
+    cmd_index
+    inotifywait -m -r -e modify,create,delete,move --format '%w%f' "$watch_dir" | while read -r _; do
+      info "Change detected, regenerating index..."
+      cmd_index
+    done
+  else
+    error "Neither fswatch (macOS) nor inotifywait (Linux) found."
+    error "Install with: brew install fswatch  OR  apt install inotify-tools"
+    exit 1
+  fi
+}
+
+cmd_import() {
+  local url="${1:-}"
+  if [[ -z "$url" ]]; then
+    error "Usage: sync-agents import <url>"
+    exit 1
+  fi
+
+  ensure_agents_dir
+
+  local filename
+  filename="$(basename "$url")"
+  if [[ "$filename" != *.md ]]; then
+    filename="${filename}.md"
+  fi
+
+  # Auto-detect type from URL path
+  local type=""
+  case "$url" in
+    */rules/*)    type="rules" ;;
+    */skills/*)   type="skills" ;;
+    */workflows/*) type="workflows" ;;
+  esac
+
+  if [[ -z "$type" ]]; then
+    echo "Could not detect type from URL. Choose:"
+    echo "  1) rule"
+    echo "  2) skill"
+    echo "  3) workflow"
+    read -rp "Selection (1-3): " choice
+    case "$choice" in
+      1) type="rules" ;;
+      2) type="skills" ;;
+      3) type="workflows" ;;
+      *) error "Invalid selection"; exit 1 ;;
+    esac
+  fi
+
+  mkdir -p "$PROJECT_ROOT/$AGENTS_DIR/$type"
+  local dest="$PROJECT_ROOT/$AGENTS_DIR/$type/$filename"
+
+  info "Importing $url → $AGENTS_DIR/$type/$filename"
+
+  if ! curl -fsSL "$url" -o "$dest"; then
+    error "Failed to download: $url"
+    exit 1
+  fi
+
+  info "Imported successfully."
+  cmd_index
+}
+
+cmd_hook() {
+  if [[ ! -d "$PROJECT_ROOT/.git" ]]; then
+    error "Not a git repository (no .git/ found)."
+    exit 1
+  fi
+
+  local hook_dir="$PROJECT_ROOT/.git/hooks"
+  local hook_file="$hook_dir/pre-commit"
+  mkdir -p "$hook_dir"
+
+  local marker="sync-agents start"
+
+  if [[ -f "$hook_file" ]] && grep -q "$marker" "$hook_file"; then
+    info "Git hook already installed in $hook_file"
+    return 0
+  fi
+
+  local hook_block
+  hook_block="$(cat <<'HOOK'
+
+# --- sync-agents start ---
+if command -v sync-agents >/dev/null 2>&1; then
+  sync-agents sync 2>/dev/null
+  sync-agents index 2>/dev/null
+  git add AGENTS.md CLAUDE.md .claude/ .windsurf/ .cursor/ .github/copilot/ 2>/dev/null || true
+fi
+# --- sync-agents end ---
+HOOK
+)"
+
+  if [[ -f "$hook_file" ]]; then
+    echo "$hook_block" >> "$hook_file"
+    info "Appended sync-agents hook to existing $hook_file"
+  else
+    printf '#!/bin/sh\n%s\n' "$hook_block" > "$hook_file"
+    chmod +x "$hook_file"
+    info "Created git hook: $hook_file"
+  fi
+}
+
 cmd_clean() {
   info "Removing synced symlinks..."
 
   for target in "${ACTIVE_TARGETS[@]}"; do
-    local target_dir="$PROJECT_ROOT/.$target"
+    local target_dir
+    target_dir="$(resolve_target_dir "$target" "$PROJECT_ROOT")"
+    local display_dir="${target_dir#"$PROJECT_ROOT"/}"
     for subdir in rules skills workflows; do
       if [[ -L "$target_dir/$subdir" ]]; then
         rm "$target_dir/$subdir"
-        info "Removed: .$target/$subdir"
+        info "Removed: ${display_dir}/$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/"
+      info "Removed empty directory: ${display_dir}/"
     fi
   done
 
@@ -529,11 +704,22 @@ main() {
     PROJECT_ROOT="$(find_project_root)"
   fi
 
-  # Resolve active targets
+  # Resolve active targets (priority: --targets flag > .agents/config > built-in defaults)
   if [[ -n "$custom_targets" ]]; then
     IFS=',' read -ra ACTIVE_TARGETS <<< "$custom_targets"
   else
-    ACTIVE_TARGETS=("${TARGETS[@]}")
+    local config_file="$PROJECT_ROOT/$AGENTS_DIR/config"
+    if [[ -f "$config_file" ]]; then
+      local config_targets
+      config_targets="$(sed -n 's/^targets *= *//p' "$config_file" | tr -d ' ')"
+      if [[ -n "$config_targets" ]]; then
+        IFS=',' read -ra ACTIVE_TARGETS <<< "$config_targets"
+      else
+        ACTIVE_TARGETS=("${TARGETS[@]}")
+      fi
+    else
+      ACTIVE_TARGETS=("${TARGETS[@]}")
+    fi
   fi
 
   # Dispatch command
@@ -556,6 +742,15 @@ main() {
     clean)
       cmd_clean
       ;;
+    watch)
+      cmd_watch
+      ;;
+    import)
+      cmd_import "$@"
+      ;;
+    hook)
+      cmd_hook
+      ;;
     "")
       usage
       exit 0