fix(agents): add context budget, file discovery, and capability guardrails

.agent/AGENTS.md

@@ -109,6 +109,9 @@ Run pre-edit-check.sh in `~/Git/aidevops/` BEFORE any changes to either location
 
 **Critical Rules**:
 - **Git check before edits**: See "MANDATORY: Pre-Edit Git Check" section above
+- **File discovery**: Use `git ls-files` or `fd`, NOT `mcp_glob` (see File Discovery below)
+- **Context budget**: Never consume >100K tokens on a single operation; for remote repos: fetch README first, check size with `gh api`, use `includePatterns`
+- **Agent capability check**: Before edits, verify you have Edit/Write/Bash tools; if not, suggest switching to Build+
 - NEVER create files in `~/` root - use `~/.aidevops/.agent-workspace/work/[project]/` for files needed only with the current task.
 - NEVER expose credentials in output/logs
 - Confirm destructive operations before execution
@@ -117,13 +120,18 @@ Run pre-edit-check.sh in `~/Git/aidevops/` BEFORE any changes to either location
 
 **Quality Standards**: SonarCloud A-grade, ShellCheck zero violations
 
-**File Discovery** (fastest to slowest):
-1. `git ls-files '*.md'` - Instant, git-tracked files only
-2. `fd -e md` or `fd -g '*.md'` - Fast, respects .gitignore, Rust-based
-3. `rg --files -g '*.md'` - Fast, respects .gitignore (ripgrep)
-4. `mcp_glob` tool - Fallback when bash unavailable or for complex patterns
+**File Discovery** (STOP before using `mcp_glob`):
 
-Use `git ls-files` for tracked files (most common). Use `fd` for untracked files or system-wide searches (e.g., `~/.config/`). The `mcp_glob` tool is CPU-intensive on large codebases.
+Self-check: "Am I about to use `mcp_glob`?" If yes, use these instead:
+
+| Use Case | Command | Why |
+|----------|---------|-----|
+| Git-tracked files | `git ls-files '*.md'` | Instant, most common case |
+| Untracked/system files | `fd -e md` or `fd -g '*.md'` | Fast, respects .gitignore |
+| Content + file list | `rg --files -g '*.md'` | Fast, respects .gitignore |
+| **Bash unavailable only** | `mcp_glob` tool | Last resort - CPU intensive |
+
+**Default**: `git ls-files` for any repo. `fd` for `~/.config/` or untracked files.
 
 **Localhost Standards** (for any local service setup):
 - **Always check port first**: `localhost-helper.sh check-port <port>` before starting services

.agent/scripts/linters-local.sh

@@ -348,6 +348,103 @@ check_secrets() {
 }
 
 # Check AI-Powered Quality CLIs integration
+check_markdown_lint() {
+    print_info "Checking Markdown Style..."
+
+    local md_files
+    local violations=0
+    local markdownlint_cmd=""
+
+    # Find markdownlint command
+    if command -v markdownlint &> /dev/null; then
+        markdownlint_cmd="markdownlint"
+    elif [[ -f "node_modules/.bin/markdownlint" ]]; then
+        markdownlint_cmd="node_modules/.bin/markdownlint"
+    fi
+
+    # Get markdown files to check:
+    # 1. Uncommitted changes (staged + unstaged)
+    # 2. If no uncommitted, check files changed in current branch vs main
+    # 3. Fallback to all tracked .md files in .agent/
+    if git rev-parse --git-dir > /dev/null 2>&1; then
+        # First try uncommitted changes
+        md_files=$(git diff --name-only --diff-filter=ACMR HEAD -- '*.md' 2>/dev/null)
+
+        # If no uncommitted, check branch diff vs main
+        if [[ -z "$md_files" ]]; then
+            local base_branch
+            base_branch=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null || echo "")
+            if [[ -n "$base_branch" ]]; then
+                md_files=$(git diff --name-only "$base_branch" HEAD -- '*.md' 2>/dev/null)
+            fi
+        fi
+
+        # Fallback: check all .agent/*.md files
+        if [[ -z "$md_files" ]]; then
+            md_files=$(git ls-files '.agent/**/*.md' 2>/dev/null)
+        fi
+    else
+        md_files=$(find . -name "*.md" -type f 2>/dev/null | grep -v node_modules)
+    fi
+
+    if [[ -z "$md_files" ]]; then
+        print_success "Markdown: No markdown files to check"
+        return 0
+    fi
+
+    if [[ -n "$markdownlint_cmd" ]]; then
+        # Run markdownlint and capture output
+        local lint_output
+        lint_output=$($markdownlint_cmd $md_files 2>&1) || true
+
+        if [[ -n "$lint_output" ]]; then
+            # Count violations (each line is a violation)
+            violations=$(echo "$lint_output" | grep -c "MD[0-9]" || echo "0")
+
+            if [[ $violations -gt 0 ]]; then
+                print_warning "Markdown: $violations style issues found"
+                echo "$lint_output" | head -10
+                if [[ $violations -gt 10 ]]; then
+                    echo "... and $((violations - 10)) more"
+                fi
+                print_info "Run: markdownlint --fix .agent/**/*.md to auto-fix"
+                # Non-blocking for now - many pre-existing issues
+                # TODO: Make blocking after fixing existing issues
+                return 0
+            fi
+        fi
+        print_success "Markdown: No style issues found"
+    else
+        # Fallback: basic checks without markdownlint
+        local issues=0
+
+        # Check for fenced code blocks without language (MD040)
+        # Pattern: line starts with optional whitespace, then ``` with nothing after (or just whitespace)
+        for file in $md_files; do
+            local count
+            # Use grep -E for extended regex (portable across macOS/Linux)
+            count=$(grep -cE '^[[:space:]]*```[[:space:]]*$' "$file" 2>/dev/null || echo "0")
+            if [[ $count -gt 0 ]]; then
+                print_warning "$file: $count fenced code blocks without language specifier"
+                grep -nE '^[[:space:]]*```[[:space:]]*$' "$file" 2>/dev/null | head -3
+                issues=$((issues + count))
+            fi
+        done
+
+        if [[ $issues -gt 0 ]]; then
+            print_warning "Markdown: $issues issues found (install markdownlint for full checks)"
+            print_info "Install: npm install -g markdownlint-cli"
+            # Non-blocking for now - many pre-existing issues
+            # TODO: Make blocking after fixing existing issues
+            return 0
+        fi
+
+        print_success "Markdown: Basic checks passed (install markdownlint for full checks)"
+    fi
+
+    return 0
+}
+
 check_remote_cli_status() {
     print_info "Remote Audit CLIs Status (use /code-audit-remote for full analysis)..."
 
@@ -418,12 +515,10 @@ main() {
     check_secrets || exit_code=1
     echo ""
 
-    check_remote_cli_status
-
+    check_markdown_lint || exit_code=1
     echo ""
-    print_info "Markdown Formatting Tools Available:"
-    print_info "Run: bash .agent/scripts/markdown-lint-fix.sh manual . (for quick fixes)"
-    print_info "Run: bash .agent/scripts/markdown-formatter.sh format . (for comprehensive formatting)"
+
+    check_remote_cli_status
     echo ""
 
     # Final summary

.agent/tools/build-agent/build-agent.md

@@ -636,6 +636,27 @@ This protocol should also be reviewed when:
 - User feedback indicates protocol is too aggressive/passive
 - Duplicate detection fails to catch conflicts
 
+### Tool Selection Checklist
+
+Before using tools, verify you're using the optimal choice:
+
+| Task | Preferred Tool | Avoid | Why |
+|------|---------------|-------|-----|
+| Find files by pattern | `git ls-files` or `fd` | `mcp_glob` | CLI is 10x faster |
+| Search file contents | `rg` (ripgrep) | `mcp_grep` | CLI is more powerful |
+| Read file contents | `mcp_read` | `cat` via bash | Better error handling |
+| Edit files | `mcp_edit` | `sed` via bash | Safer, atomic |
+| Web content | `mcp_webfetch` | `curl` via bash | Handles redirects |
+| Remote repo research | `mcp_webfetch` README first | `mcp_repomix_pack_remote_repository` | Prevents context overload |
+
+**Self-check prompt**: Before calling any MCP tool, ask:
+> "Is there a faster CLI alternative I should use via Bash?"
+
+**Context budget check**: Before context-heavy operations, ask:
+> "Could this return >50K tokens? Have I checked the size first?"
+
+See `tools/context/context-guardrails.md` for detailed guardrails.
+
 ### Agent File Structure Convention
 
 All agent files should follow this structure:

.agent/tools/context/context-builder.md

@@ -8,7 +8,7 @@ tools:
   bash: true
   glob: true
   grep: true
-  webfetch: false
+  webfetch: true
   task: true
 ---
 
@@ -64,6 +64,30 @@ tools:
 - Import/export statements
 - Omits: implementation details, comments, empty lines
 
+## CRITICAL: Remote Repository Guardrails
+
+**NEVER blindly pack a remote repository.** Follow this escalation:
+
+1. **Fetch README first** - `webfetch "https://github.com/{user}/{repo}"` (~1-5K tokens)
+2. **Check repo size** - `gh api repos/{user}/{repo} --jq '.size'` (size in KB)
+3. **Apply size thresholds**:
+
+| Repo Size (KB) | Est. Tokens | Action |
+|----------------|-------------|--------|
+| < 500 | < 50K | Safe for compressed pack |
+| 500-2000 | 50-200K | Use `includePatterns` only |
+| > 2000 | > 200K | **NEVER full pack** - targeted files only |
+
+4. **Use patterns** - `mcp_repomix_pack_remote_repository(..., includePatterns="README.md,src/**/*.ts")`
+
+**What NOT to do:**
+```bash
+# DANGEROUS - packs entire repo without size check
+mcp_repomix_pack_remote_repository(remote="https://github.com/some/large-repo")
+```
+
+See `tools/context/context-guardrails.md` for full workflow and recovery procedures.
+
 <!-- AI-CONTEXT-END -->
 
 ## Overview