docs: update README and cross-file-validation with new features

- Add diff-aware linting section (--staged, --diff)
- Add baseline support section (--baseline, --baseline-create)
- Add canonical formatting section (cclint fmt)
- Add circular dependency detection to cross-file validation
- Update GitHub Actions example with Go setup
- Update pre-commit hook to use --staged for speed

Author: Test User

README.md

@@ -10,7 +10,10 @@ cclint validates YAML frontmatter, checks structural patterns, and suggests impr
 - **YAML frontmatter parsing**: Validates required fields and data types
 - **CUE schema validation**: Embedded schemas for type-safe validation
 - **Quality scoring**: 0-100 scores with tier grading (A-F)
-- **Cross-file validation**: Detects missing skill references
+- **Cross-file validation**: Detects missing skill references and circular dependencies
+- **Diff-aware linting**: Lint only staged/changed files for fast pre-commit hooks
+- **Baseline support**: Gradual adoption for legacy projects with existing issues
+- **Canonical formatting**: `cclint fmt` for consistent component style
 - **Multiple output formats**: Console, JSON, Markdown
 - **CI/CD ready**: Exit codes and JSON output for automation
 
@@ -89,6 +92,66 @@ cclint --format json --output report.json
 cclint --format markdown --output report.md
 ```
 
+### Git Integration (Diff-aware Linting)
+
+Lint only changed files for fast pre-commit hooks:
+
+```bash
+# Lint only staged files (perfect for pre-commit)
+cclint --staged
+
+# Lint all uncommitted changes (staged + unstaged)
+cclint --diff
+```
+
+If not in a git repository, falls back to full lint with a warning.
+
+### Baseline Support (Gradual Adoption)
+
+For legacy projects with existing issues, use baseline mode to adopt cclint incrementally:
+
+```bash
+# Create baseline from current issues (accepts current state)
+cclint --baseline-create
+
+# Lint with baseline - only NEW issues fail the build
+cclint --baseline
+
+# Use custom baseline file
+cclint --baseline --baseline-path .baseline-legacy.json
+```
+
+**Workflow:**
+1. Run `cclint --baseline-create` to snapshot current issues into `.cclintbaseline.json`
+2. Commit the baseline file to version control
+3. Run `cclint --baseline` in CI/CD — only new issues fail
+4. Fix issues incrementally, update baseline as needed
+
+### Canonical Formatting
+
+Format components with consistent style using `cclint fmt`:
+
+```bash
+# Preview formatting (stdout)
+cclint fmt agents/my-agent.md
+
+# Format in place
+cclint fmt --write agents/my-agent.md
+cclint fmt -w agents/
+
+# Show diff of changes
+cclint fmt --diff agents/
+
+# CI mode: exit 1 if formatting needed
+cclint fmt --check
+```
+
+**Formatting rules:**
+- Frontmatter field order: `name`, `description`, `model`, `tools`/`allowed-tools`, then alphabetically
+- Exactly one blank line after frontmatter
+- Trailing whitespace removed
+- File ends with single newline
+
 ### Exit Codes
 
 | Code | Meaning |
@@ -105,9 +168,12 @@ cclint validates references between components:
 | Check | Description |
 |-------|-------------|
 | **Skill existence** | Agents referencing non-existent skills produce errors |
+| **Circular dependencies** | Detects cycles in agent → skill → agent delegation chains |
 | **Orphan detection** | Skills not referenced by any agent/command show as suggestions |
 | **Tool permissions** | Commands using undeclared tools produce warnings |
 
+To disable circular dependency detection: `cclint --no-cycle-check`
+
 Skill references are detected in multiple formats:
 - `Skill: name` - Plain format (including inside code blocks)
 - `**Skill**: name` - Bold format
@@ -311,13 +377,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
       - name: Install cclint
-        run: |
-          go install github.com/dotcommander/cclint@latest
+        run: go install github.com/dotcommander/cclint@latest
 
       - name: Run cclint
-        run: |
-          cclint --format json --output cclint-report.json
+        run: cclint --format json --output cclint-report.json
 
       - name: Upload results
         if: always()
@@ -327,6 +396,13 @@ jobs:
           path: cclint-report.json
 ```
 
+**With baseline support (gradual adoption):**
+
+```yaml
+      - name: Run cclint with baseline
+        run: cclint --baseline --format json --output cclint-report.json
+```
+
 ### GitLab CI
 
 ```yaml
@@ -349,17 +425,19 @@ Create `.git/hooks/pre-commit`:
 
 ```bash
 #!/bin/bash
-# Run cclint on commit
-cclint || exit 1
+# Run cclint on staged files only (fast!)
+cclint --staged || exit 1
 ```
 
 Or with [husky](https://github.com/typicode/husky):
 
 ```bash
 npm install --save-dev husky
-npx husky set .husky/pre-commit "cclint"
+npx husky set .husky/pre-commit "cclint --staged"
 ```
 
+Using `--staged` makes pre-commit hooks fast by only linting changed files.
+
 ## File Discovery
 
 cclint searches the following locations:

docs/cross-file-validation.md

@@ -9,8 +9,9 @@ How cclint detects and validates references between components.
 cclint performs cross-file validation to ensure components reference each other correctly. This includes:
 
 1. **Skill Reference Validation** - Agents referencing skills that don't exist
-2. **Orphan Detection** - Skills not referenced by any agent/command
-3. **Tool Validation** - Commands using tools they haven't declared
+2. **Circular Dependency Detection** - Cycles in agent → skill → agent delegation chains
+3. **Orphan Detection** - Skills not referenced by any agent/command
+4. **Tool Validation** - Commands using tools they haven't declared
 
 ## Skill Reference Detection
 
@@ -58,6 +59,50 @@ Key components:
 
 **Important:** The `\n` exclusion is critical. Without it, Go's regex engine would greedily match across newlines, causing only the last skill in a block to be detected.
 
+## Circular Dependency Detection
+
+### What It Checks
+
+Circular dependencies occur when components form a loop in their reference chain:
+
+```
+agent-a → skill-b → agent-c → skill-d → agent-a  (cycle!)
+```
+
+These cycles can cause infinite loops in Claude Code when agents delegate to each other.
+
+### How It Works
+
+cclint uses DFS (Depth-First Search) with color marking to detect back edges in the component graph:
+
+1. **White (unvisited)** - Node not yet processed
+2. **Gray (in progress)** - Node is in current DFS path
+3. **Black (complete)** - Node fully processed
+
+A cycle is detected when we encounter a gray node while exploring.
+
+### Output
+
+Cycles are reported as errors on all involved agents:
+
+```bash
+$ cclint agents
+
+✗ agents/agent-a.md
+    ✘ Circular dependency detected: agent:agent-a → skill:shared-skill → agent:agent-a
+
+✗ agents/agent-c.md
+    ✘ Circular dependency detected: agent:agent-a → skill:shared-skill → agent:agent-a
+```
+
+### Disabling
+
+To disable circular dependency detection (not recommended):
+
+```bash
+cclint --no-cycle-check agents
+```
+
 ## Orphan Detection
 
 ### What It Checks