@brickhouse-tech/sync-agents 0.1.5 → 0.1.6

package/README.md

@@ -63,6 +63,9 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
 | `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 |
+| `inherit <label> <path>` | Add an inheritance link to AGENTS.md |
+| `inherit --list` | List current inheritance links |
+| `inherit --remove <label>` | Remove an inheritance link by label |
 | `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/` |
@@ -79,6 +82,150 @@ AGENTS.md is also symlinked to CLAUDE.md so that Claude reads the index natively
 | `--dry-run` | Show what would be done without making changes |
 | `--force` | Overwrite existing files and symlinks |
 
+## Inheritance
+
+Projects can inherit agent rules from parent directories (org, team, global) using a convention-based approach. This enables hierarchical rule sharing without duplicating files.
+
+### How It Works
+
+Add an `## Inherits` section to your project's `AGENTS.md` that links to parent-level agent configs:
+
+```markdown
+## Inherits
+- [global](../../AGENTS.md)
+- [team](../AGENTS.md)
+```
+
+AI agents (Claude, Codex, etc.) follow markdown links natively — when they read your project's `AGENTS.md`, they'll traverse the inheritance chain and apply rules from all levels.
+
+### Hierarchy Example
+
+```
+~/code/                     # Global: security norms, universal rules
+  ├── .agents/
+  ├── AGENTS.md
+  └── org/                  # Org-level: coding standards, shared workflows
+      ├── .agents/
+      ├── AGENTS.md
+      └── team/             # Team-level: language-specific rules
+          ├── .agents/
+          ├── AGENTS.md
+          └── project/      # Project: project-specific rules + inherits
+              ├── .agents/
+              └── AGENTS.md  → ## Inherits links to team, org, global
+```
+
+**Inheritance is upward-only.** A project declares what it inherits from. Parent directories don't need to know about their children — when an agent works at the org level, it already has access to org-level rules.
+
+### Managing Inheritance
+
+```bash
+# Add an inheritance link
+sync-agents inherit global ../../AGENTS.md
+sync-agents inherit team ../AGENTS.md
+
+# List current inheritance links
+sync-agents inherit --list
+
+# Remove an inheritance link
+sync-agents inherit --remove global
+```
+
+The `## Inherits` section is preserved across `sync-agents index` regenerations.
+
+### Full Example
+
+Set up a three-level hierarchy: global rules → org standards → project config.
+
+```bash
+# 1. Create global rules (e.g. ~/code/.agents/)
+cd ~/code
+sync-agents init
+sync-agents add rule security
+cat > .agents/rules/security.md << 'EOF'
+---
+trigger: always_on
+---
+# Security
+- Never commit secrets or API keys
+- Validate all external input
+- Use parameterized queries for database access
+EOF
+
+# 2. Create org-level rules (e.g. ~/code/myorg/.agents/)
+cd ~/code/myorg
+sync-agents init
+sync-agents add rule go-standards
+cat > .agents/rules/go-standards.md << 'EOF'
+---
+trigger: always_on
+---
+# Go Standards
+- Use `gofmt` and `golangci-lint` on all Go files
+- Prefer table-driven tests
+- Export only what consumers need
+EOF
+
+# 3. Create project with inheritance
+cd ~/code/myorg/api-service
+sync-agents init
+sync-agents add rule api-conventions
+
+# Link to parent levels
+sync-agents inherit org ../AGENTS.md
+sync-agents inherit global ../../AGENTS.md
+
+# Sync to agent directories
+sync-agents sync
+```
+
+The project's `AGENTS.md` now looks like:
+
+```markdown
+## Inherits
+- [org](../AGENTS.md)
+- [global](../../AGENTS.md)
+
+## Rules
+- [api-conventions](.agents/rules/api-conventions.md)
+
+## Skills
+_No skills defined yet._
+
+## Workflows
+_No workflows defined yet._
+```
+
+When an AI agent reads this file, it follows the `## Inherits` links and applies rules from all three levels — project-specific API conventions, org-wide Go standards, and global security rules.
+
+### Verifying Inheritance
+
+```bash
+# Check what's inherited
+sync-agents inherit --list
+# Output:
+# - [org](../AGENTS.md)
+# - [global](../../AGENTS.md)
+
+# Remove a link if no longer needed
+sync-agents inherit --remove global
+
+# Re-add with a different path
+sync-agents inherit global ../../AGENTS.md
+```
+
+## Examples
+
+The [`examples/`](examples/) directory contains ready-to-use rules, skills, and workflows. Import them directly:
+
+```bash
+sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/rules/no-secrets.md
+sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/skills/code-review.md
+sync-agents import https://raw.githubusercontent.com/brickhouse-tech/sync-agents/main/examples/workflows/pr-checklist.md
+```
+
+See [examples/README.md](examples/README.md) for the full list.
+
 ## Usage
 
 ```bash

package/package.json

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

package/src/sh/sync-agents.sh

@@ -75,6 +75,9 @@ ${BOLD}COMMANDS${RESET}
   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
+  inherit <label> <path>        Add an inheritance link to AGENTS.md (convention-based)
+  inherit --list                List current inheritance links
+  inherit --remove <label>      Remove an inheritance link by label
 
 ${BOLD}OPTIONS${RESET}
   -h, --help                    Show this help message
@@ -526,6 +529,198 @@ cmd_clean() {
   info "Clean complete."
 }
 
+# --------------------------------------------------------------------------
+# Inherit
+# --------------------------------------------------------------------------
+
+cmd_inherit() {
+  local action="${1:-}"
+
+  # --list: show current inherits
+  if [[ "$action" == "--list" ]]; then
+    if [[ ! -f "$PROJECT_ROOT/$AGENTS_MD" ]]; then
+      info "No AGENTS.md found."
+      return 0
+    fi
+    local in_section="false"
+    while IFS= read -r line; do
+      if [[ "$line" =~ ^##[[:space:]]+Inherits ]]; then
+        in_section="true"
+        continue
+      fi
+      if [[ "$in_section" == "true" ]] && [[ "$line" =~ ^## ]]; then
+        break
+      fi
+      if [[ "$in_section" == "true" ]] && [[ "$line" =~ ^-[[:space:]]+\[ ]]; then
+        echo "$line"
+      fi
+    done < "$PROJECT_ROOT/$AGENTS_MD"
+    return 0
+  fi
+
+  # --remove <label>: remove an inherit entry
+  if [[ "$action" == "--remove" ]]; then
+    local label="${2:-}"
+    if [[ -z "$label" ]]; then
+      error "Usage: sync-agents inherit --remove <label>"
+      exit 1
+    fi
+    if [[ ! -f "$PROJECT_ROOT/$AGENTS_MD" ]]; then
+      error "No AGENTS.md found."
+      exit 1
+    fi
+    # Remove the line matching [label](...) from the Inherits section
+    local tmp
+    tmp="$(mktemp)"
+    local in_section="false"
+    local removed="false"
+    while IFS= read -r line; do
+      if [[ "$line" =~ ^##[[:space:]]+Inherits ]]; then
+        in_section="true"
+        echo "$line" >> "$tmp"
+        continue
+      fi
+      if [[ "$in_section" == "true" ]] && [[ "$line" =~ ^## ]]; then
+        in_section="false"
+      fi
+      if [[ "$in_section" == "true" ]] && [[ "$line" == *"[$label]("* ]]; then
+        removed="true"
+        continue
+      fi
+      echo "$line" >> "$tmp"
+    done < "$PROJECT_ROOT/$AGENTS_MD"
+    mv "$tmp" "$PROJECT_ROOT/$AGENTS_MD"
+    if [[ "$removed" == "true" ]]; then
+      info "Removed inherit: $label"
+    else
+      warn "No inherit found with label: $label"
+    fi
+    return 0
+  fi
+
+  # Default: add <label> <path>
+  local label="$action"
+  local path="${2:-}"
+
+  if [[ -z "$label" ]] || [[ -z "$path" ]]; then
+    error "Usage: sync-agents inherit <label> <path>"
+    error "       sync-agents inherit --list"
+    error "       sync-agents inherit --remove <label>"
+    exit 1
+  fi
+
+  # Validate the path exists (resolve relative to PROJECT_ROOT)
+  local resolved_path
+  if [[ "$path" == /* ]] || [[ "$path" == ~* ]]; then
+    resolved_path="${path/#\~/$HOME}"
+  else
+    resolved_path="$PROJECT_ROOT/$path"
+  fi
+
+  if [[ ! -f "$resolved_path" ]] && [[ ! -d "$resolved_path" ]]; then
+    warn "Path does not exist: $path (link will be added anyway)"
+  fi
+
+  # Check if AGENTS.md exists
+  if [[ ! -f "$PROJECT_ROOT/$AGENTS_MD" ]]; then
+    error "No AGENTS.md found. Run 'sync-agents init' first."
+    exit 1
+  fi
+
+  # Check if Inherits section exists; if not, add it after the header
+  if ! grep -q "^## Inherits" "$PROJECT_ROOT/$AGENTS_MD"; then
+    # Insert Inherits section right after the header block (after first blank line following description)
+    local tmp
+    tmp="$(mktemp)"
+    local header_done="false"
+    local inherits_written="false"
+    while IFS= read -r line; do
+      echo "$line" >> "$tmp"
+      # Write inherits section after the description paragraph (first line starting with "This file")
+      if [[ "$header_done" == "false" ]] && [[ "$line" == "This file indexes"* ]]; then
+        header_done="true"
+        {
+          echo ""
+          echo "## Inherits"
+          echo ""
+          echo "- [$label]($path)"
+        } >> "$tmp"
+        inherits_written="true"
+      fi
+    done < "$PROJECT_ROOT/$AGENTS_MD"
+    # Fallback: if header pattern wasn't found, append at the end before ## Rules
+    if [[ "$inherits_written" == "false" ]]; then
+      rm "$tmp"
+      tmp="$(mktemp)"
+      while IFS= read -r line; do
+        if [[ "$line" == "## Rules" ]] && [[ "$inherits_written" == "false" ]]; then
+          {
+            echo "## Inherits"
+            echo ""
+            echo "- [$label]($path)"
+            echo ""
+          } >> "$tmp"
+          inherits_written="true"
+        fi
+        echo "$line" >> "$tmp"
+      done < "$PROJECT_ROOT/$AGENTS_MD"
+    fi
+    mv "$tmp" "$PROJECT_ROOT/$AGENTS_MD"
+  else
+    # Inherits section exists — check for duplicate label
+    if grep -q "\[$label\](" "$PROJECT_ROOT/$AGENTS_MD"; then
+      warn "Inherit with label '$label' already exists. Use --remove first to update."
+      return 1
+    fi
+    # Append to existing Inherits section (after last inherit entry or section header)
+    local tmp
+    tmp="$(mktemp)"
+    local in_section="false"
+    local added="false"
+    while IFS= read -r line; do
+      if [[ "$line" =~ ^##[[:space:]]+Inherits ]]; then
+        in_section="true"
+        echo "$line" >> "$tmp"
+        continue
+      fi
+      # When we hit the next section or blank line after entries, insert
+      if [[ "$in_section" == "true" ]] && [[ "$added" == "false" ]]; then
+        if [[ "$line" =~ ^## ]] || [[ -z "$line" ]]; then
+          # Check if previous content had entries; add after them
+          if [[ "$line" =~ ^## ]]; then
+            {
+              echo "- [$label]($path)"
+              echo ""
+            } >> "$tmp"
+            added="true"
+            in_section="false"
+          fi
+        fi
+        if [[ "$line" =~ ^-[[:space:]]+\[ ]]; then
+          echo "$line" >> "$tmp"
+          continue
+        fi
+        if [[ -z "$line" ]] && [[ "$added" == "false" ]]; then
+          echo "- [$label]($path)" >> "$tmp"
+          added="true"
+          in_section="false"
+          echo "$line" >> "$tmp"
+          continue
+        fi
+      fi
+      echo "$line" >> "$tmp"
+    done < "$PROJECT_ROOT/$AGENTS_MD"
+    # If we never added (section was at end of file)
+    if [[ "$added" == "false" ]]; then
+      echo "- [$label]($path)" >> "$tmp"
+      echo "" >> "$tmp"
+    fi
+    mv "$tmp" "$PROJECT_ROOT/$AGENTS_MD"
+  fi
+
+  info "Added inherit: [$label]($path)"
+}
+
 # --------------------------------------------------------------------------
 # Index generator
 # --------------------------------------------------------------------------
@@ -534,6 +729,25 @@ generate_agents_md() {
   local outfile="$PROJECT_ROOT/$AGENTS_MD"
   local agents_dir="$PROJECT_ROOT/$AGENTS_DIR"
 
+  # Preserve existing Inherits section before regenerating
+  local inherits_block=""
+  if [[ -f "$outfile" ]]; then
+    local in_section="false"
+    while IFS= read -r line; do
+      if [[ "$line" =~ ^##[[:space:]]+Inherits ]]; then
+        in_section="true"
+        inherits_block+="$line"$'\n'
+        continue
+      fi
+      if [[ "$in_section" == "true" ]] && [[ "$line" =~ ^## ]]; then
+        break
+      fi
+      if [[ "$in_section" == "true" ]]; then
+        inherits_block+="$line"$'\n'
+      fi
+    done < "$outfile"
+  fi
+
   cat > "$outfile" <<'HEADER'
 
 ---
@@ -550,6 +764,11 @@ This file indexes all rules, skills, and workflows defined in `.agents/`.
 HEADER
 
   {
+    # Inherits (preserved from previous AGENTS.md)
+    if [[ -n "$inherits_block" ]]; then
+      printf '%s\n' "$inherits_block"
+    fi
+
     # Rules
     echo "## Rules"
     echo ""
@@ -681,6 +900,10 @@ main() {
         shift
         ;;
       -*)
+        if [[ -n "$command" ]]; then
+          # Unknown flag after command — pass to subcommand
+          break
+        fi
         error "Unknown option: $1"
         usage
         exit 1
@@ -751,6 +974,9 @@ main() {
     hook)
       cmd_hook
       ;;
+    inherit)
+      cmd_inherit "$@"
+      ;;
     "")
       usage
       exit 0