@techwavedev/agi-agent-kit 1.5.3 → 1.6.1

package/templates/skills/extended/other/burpsuite-project-parser/SKILL.md

@@ -0,0 +1,410 @@
+---
+name: burpsuite-project-parser
+description: Searches and explores Burp Suite project files (.burp) from the command line. Use when searching response headers or bodies with regex patterns, extracting security audit findings, dumping proxy history or site map data, or analyzing HTTP traffic captured in a Burp project.
+allowed-tools:
+  - Bash
+  - Read
+risk: unknown
+source: community
+---
+
+# Burp Project Parser
+
+Search and extract data from Burp Suite project files using the burpsuite-project-file-parser extension.
+
+## When to Use
+
+- Searching response headers or bodies with regex patterns
+- Extracting security audit findings from Burp projects
+- Dumping proxy history or site map data
+- Analyzing HTTP traffic captured in a Burp project file
+
+## Prerequisites
+
+This skill **delegates parsing to Burp Suite Professional** - it does not parse .burp files directly.
+
+**Required:**
+1. **Burp Suite Professional** - Must be installed ([portswigger.net](https://portswigger.net/burp/pro))
+2. **burpsuite-project-file-parser extension** - Provides CLI functionality
+
+**Install the extension:**
+1. Download from [github.com/BuffaloWill/burpsuite-project-file-parser](https://github.com/BuffaloWill/burpsuite-project-file-parser)
+2. In Burp Suite: Extender → Extensions → Add
+3. Select the downloaded JAR file
+
+## Quick Reference
+
+Use the wrapper script:
+```bash
+{baseDir}/scripts/burp-search.sh /path/to/project.burp [FLAGS]
+```
+
+The script uses environment variables for platform compatibility:
+- `BURP_JAVA`: Path to Java executable
+- `BURP_JAR`: Path to burpsuite_pro.jar
+
+See [Platform Configuration](#platform-configuration) for setup instructions.
+
+## Sub-Component Filters (USE THESE)
+
+**ALWAYS use sub-component filters instead of full dumps.** Full `proxyHistory` or `siteMap` can return gigabytes of data. Sub-component filters return only what you need.
+
+### Available Filters
+
+| Filter | Returns | Typical Size |
+|--------|---------|--------------|
+| `proxyHistory.request.headers` | Request line + headers only | Small (< 1KB/record) |
+| `proxyHistory.request.body` | Request body only | Variable |
+| `proxyHistory.response.headers` | Status + headers only | Small (< 1KB/record) |
+| `proxyHistory.response.body` | Response body only | **LARGE - avoid** |
+| `siteMap.request.headers` | Same as above for site map | Small |
+| `siteMap.request.body` | | Variable |
+| `siteMap.response.headers` | | Small |
+| `siteMap.response.body` | | **LARGE - avoid** |
+
+### Default Approach
+
+**Start with headers, not bodies:**
+
+```bash
+# GOOD - headers only, safe to retrieve
+{baseDir}/scripts/burp-search.sh project.burp proxyHistory.request.headers | head -c 50000
+{baseDir}/scripts/burp-search.sh project.burp proxyHistory.response.headers | head -c 50000
+
+# BAD - full records include bodies, can be gigabytes
+{baseDir}/scripts/burp-search.sh project.burp proxyHistory  # NEVER DO THIS
+```
+
+**Only fetch bodies for specific URLs after reviewing headers, and ALWAYS truncate:**
+
+```bash
+# 1. First, find interesting URLs from headers
+{baseDir}/scripts/burp-search.sh project.burp proxyHistory.response.headers | \
+  jq -r 'select(.headers | test("text/html")) | .url' | head -n 20
+
+# 2. Then search bodies with targeted regex - MUST truncate body to 1000 chars
+{baseDir}/scripts/burp-search.sh project.burp "responseBody='.*specific-pattern.*'" | \
+  head -n 10 | jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'
+```
+
+**HARD RULE: Body content > 1000 chars must NEVER enter context.** If the user needs full body content, they must view it in Burp Suite's UI.
+
+## Regex Search Operations
+
+### Search Response Headers
+```bash
+responseHeader='.*regex.*'
+```
+Searches all response headers. Output: `{"url":"...", "header":"..."}`
+
+Example - find server signatures:
+```bash
+responseHeader='.*(nginx|Apache|Servlet).*' | head -c 50000
+```
+
+### Search Response Bodies
+```bash
+responseBody='.*regex.*'
+```
+**MANDATORY: Always truncate body content to 1000 chars max.** Response bodies can be megabytes each.
+
+```bash
+# REQUIRED format - always truncate .body field
+{baseDir}/scripts/burp-search.sh project.burp "responseBody='.*<form.*action.*'" | \
+  head -n 10 | jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'
+```
+
+**Never retrieve full body content.** If you need to see more of a specific response, ask the user to open it in Burp Suite's UI.
+
+## Other Operations
+
+### Extract Audit Items
+```bash
+auditItems
+```
+Returns all security findings. Output includes: name, severity, confidence, host, port, protocol, url.
+
+**Note:** Audit items are small (no bodies) - safe to retrieve with `head -n 100`.
+
+### Dump Proxy History (AVOID)
+```bash
+proxyHistory
+```
+**NEVER use this directly.** Use sub-component filters instead:
+- `proxyHistory.request.headers`
+- `proxyHistory.response.headers`
+
+### Dump Site Map (AVOID)
+```bash
+siteMap
+```
+**NEVER use this directly.** Use sub-component filters instead.
+
+## Output Limits (REQUIRED)
+
+**CRITICAL: Always check result size BEFORE retrieving data.** A broad search can return thousands of records, each potentially megabytes. This will overflow the context window.
+
+### Step 1: Always Check Size First
+
+Before any search, check BOTH record count AND byte size:
+
+```bash
+# Check record count AND total bytes - never skip this step
+{baseDir}/scripts/burp-search.sh project.burp proxyHistory | wc -cl
+{baseDir}/scripts/burp-search.sh project.burp "responseHeader='.*Server.*'" | wc -cl
+{baseDir}/scripts/burp-search.sh project.burp auditItems | wc -cl
+```
+
+The `wc -cl` output shows: `<bytes> <lines>` (e.g., `524288 42` means 512KB across 42 records).
+
+**Interpret the results - BOTH must pass:**
+
+| Metric | Safe | Narrow search | Too broad | STOP |
+|--------|------|---------------|-----------|------|
+| **Lines** | < 50 | 50-200 | 200+ | 1000+ |
+| **Bytes** | < 50KB | 50-200KB | 200KB+ | 1MB+ |
+
+**A single 10MB response on one line will show high byte count but only 1 line - the byte check catches this.**
+
+### Step 2: Refine Broad Searches
+
+If count/size is too high:
+
+1. **Use sub-component filters** (see table above):
+   ```bash
+   # Instead of: proxyHistory (gigabytes)
+   # Use: proxyHistory.request.headers (kilobytes)
+   ```
+
+2. **Narrow regex patterns:**
+   ```bash
+   # Too broad (matches everything):
+   responseHeader='.*'
+
+   # Better - target specific headers:
+   responseHeader='.*X-Frame-Options.*'
+   responseHeader='.*Content-Security-Policy.*'
+   ```
+
+3. **Filter with jq before retrieving:**
+   ```bash
+   # Get only specific content types
+   {baseDir}/scripts/burp-search.sh project.burp proxyHistory.response.headers | \
+     jq -c 'select(.url | test("/api/"))' | head -n 50
+   ```
+
+### Step 3: Always Truncate Output
+
+Even after narrowing, always pipe through truncation:
+
+```bash
+# ALWAYS use head -c to limit total bytes (max 50KB)
+{baseDir}/scripts/burp-search.sh project.burp proxyHistory.request.headers | head -c 50000
+
+# For body searches, truncate each JSON object's body field:
+{baseDir}/scripts/burp-search.sh project.burp "responseBody='pattern'" | \
+  head -n 20 | jq -c '.body = (.body | if length > 1000 then .[:1000] + "...[TRUNCATED]" else . end)'
+
+# Limit both record count AND byte size:
+{baseDir}/scripts/burp-search.sh project.burp auditItems | head -n 50 | head -c 50000
+```
+
+**Hard limits to enforce:**
+- `head -c 50000` (50KB max) on ALL output
+- **Truncate `.body` fields to 1000 chars - MANDATORY, no exceptions**
+  ```bash
+  jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'
+  ```
+
+**Never run these without counting first AND truncating:**
+- `proxyHistory` / `siteMap` (full dumps - always use sub-component filters)
+- `responseBody='...'` searches (bodies can be megabytes each)
+- Any broad regex like `.*` or `.+`
+
+## Investigation Workflow
+
+1. **Identify scope** - What are you looking for? (specific vuln type, endpoint, header pattern)
+
+2. **Search audit items first** - Start with Burp's findings:
+   ```bash
+   {baseDir}/scripts/burp-search.sh project.burp auditItems | jq 'select(.severity == "High")'
+   ```
+
+3. **Check confidence scores** - Filter for actionable findings:
+   ```bash
+   ... | jq 'select(.confidence == "Certain" or .confidence == "Firm")'
+   ```
+
+4. **Extract affected URLs** - Get the attack surface:
+   ```bash
+   ... | jq -r '.url' | sort -u
+   ```
+
+5. **Search raw traffic for context** - Examine actual requests/responses:
+   ```bash
+   {baseDir}/scripts/burp-search.sh project.burp "responseBody='pattern'"
+   ```
+
+6. **Validate manually** - Burp findings are indicators, not proof. Verify each one.
+
+## Understanding Results
+
+### Severity vs Confidence
+
+Burp reports both **severity** (High/Medium/Low) and **confidence** (Certain/Firm/Tentative). Use both when triaging:
+
+| Combination | Meaning |
+|-------------|---------|
+| High + Certain | Likely real vulnerability, prioritize investigation |
+| High + Tentative | Often a false positive, verify before reporting |
+| Medium + Firm | Worth investigating, may need manual validation |
+
+A "High severity, Tentative confidence" finding is frequently a false positive. Don't report findings based on severity alone.
+
+### When Proxy History is Incomplete
+
+Proxy history only contains what Burp captured. It may be missing traffic due to:
+- **Scope filters** excluding domains
+- **Intercept settings** dropping requests
+- **Browser traffic** not routed through Burp proxy
+
+If you don't find expected traffic, check Burp's scope and proxy settings in the original project.
+
+### HTTP Body Encoding
+
+Response bodies may be gzip compressed, chunked, or use non-UTF8 encoding. Regex patterns that work on plaintext may silently fail on encoded responses. If searches return fewer results than expected:
+- Check if responses are compressed
+- Try broader patterns or search headers first
+- Use Burp's UI to inspect raw vs rendered response
+
+## Rationalizations to Reject
+
+Common shortcuts that lead to missed vulnerabilities or false reports:
+
+| Shortcut | Why It's Wrong |
+|----------|----------------|
+| "This regex looks good" | Verify on sample data first—encoding and escaping cause silent failures |
+| "High severity = must fix" | Check confidence score too; Burp has false positives |
+| "All audit items are relevant" | Filter by actual threat model; not every finding matters for every app |
+| "Proxy history is complete" | May be filtered by Burp scope/intercept settings; you see only what Burp captured |
+| "Burp found it, so it's a vuln" | Burp findings require manual verification—they indicate potential issues, not proof |
+
+## Output Format
+
+All output is JSON, one object per line. Pipe to `jq` for formatting:
+```bash
+{baseDir}/scripts/burp-search.sh project.burp auditItems | jq .
+```
+
+Filter with grep:
+```bash
+{baseDir}/scripts/burp-search.sh project.burp auditItems | grep -i "sql injection"
+```
+
+## Examples
+
+Search for CORS headers (with byte limit):
+```bash
+{baseDir}/scripts/burp-search.sh project.burp "responseHeader='.*Access-Control.*'" | head -c 50000
+```
+
+Get all high-severity findings (audit items are small, but still limit):
+```bash
+{baseDir}/scripts/burp-search.sh project.burp auditItems | jq -c 'select(.severity == "High")' | head -n 100
+```
+
+Extract just request URLs from proxy history:
+```bash
+{baseDir}/scripts/burp-search.sh project.burp proxyHistory.request.headers | jq -r '.request.url' | head -n 200
+```
+
+Search response bodies (MUST truncate body to 1000 chars):
+```bash
+{baseDir}/scripts/burp-search.sh project.burp "responseBody='.*password.*'" | \
+  head -n 10 | jq -c '.body = (.body[:1000] + "...[TRUNCATED]")'
+```
+
+## Platform Configuration
+
+The wrapper script requires two environment variables to locate Burp Suite's bundled Java and JAR file.
+
+### macOS
+
+```bash
+export BURP_JAVA="/Applications/Burp Suite Professional.app/Contents/Resources/jre.bundle/Contents/Home/bin/java"
+export BURP_JAR="/Applications/Burp Suite Professional.app/Contents/Resources/app/burpsuite_pro.jar"
+```
+
+### Windows
+
+```powershell
+$env:BURP_JAVA = "C:\Program Files\BurpSuiteProfessional\jre\bin\java.exe"
+$env:BURP_JAR = "C:\Program Files\BurpSuiteProfessional\burpsuite_pro.jar"
+```
+
+### Linux
+
+```bash
+export BURP_JAVA="/opt/BurpSuiteProfessional/jre/bin/java"
+export BURP_JAR="/opt/BurpSuiteProfessional/burpsuite_pro.jar"
+```
+
+Add these exports to your shell profile (`.bashrc`, `.zshrc`, etc.) for persistence.
+
+### Manual Invocation
+
+If not using the wrapper script, invoke directly:
+```bash
+"$BURP_JAVA" -jar -Djava.awt.headless=true "$BURP_JAR" \
+  --project-file=/path/to/project.burp [FLAGS]
+```
+
+---
+
+<!-- AGI-INTEGRATION-START -->
+
+## AGI Framework Integration
+
+> **Adapted for [@techwavedev/agi-agent-kit](https://www.npmjs.com/package/@techwavedev/agi-agent-kit)**
+> Original source: [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)
+
+### Memory-First Protocol
+
+Cache compliance check results to avoid re-running expensive AWS API calls. Retrieve prior audit findings to track remediation progress across sessions.
+
+```bash
+# Check for prior security context before starting
+python3 execution/memory_manager.py auto --query "prior security audit results for Burpsuite Project Parser"
+```
+
+### Storing Results
+
+After completing work, store security decisions for future sessions:
+
+```bash
+python3 execution/memory_manager.py store \
+  --content "Audit findings: 3 critical IAM misconfigurations found and remediated" \
+  --type technical --project <project> \
+  --tags burpsuite-project-parser security
+```
+
+### Multi-Agent Collaboration
+
+Share security findings with other agents so they avoid introducing vulnerabilities in their code changes.
+
+```bash
+python3 execution/cross_agent_context.py store \
+  --agent "<your-agent>" \
+  --action "Completed security audit — 3 critical findings fixed, compliance score 94%" \
+  --project <project>
+```
+
+### Signed Audit Trail
+
+All security findings are cryptographically signed with the agent's Ed25519 identity, providing tamper-proof audit logs for compliance reporting.
+
+### Semantic Cache for Compliance
+
+Cache compliance check results (`semantic_cache.py`) to avoid redundant AWS API calls. Cache hit at similarity >0.92 returns prior results instantly.
+
+<!-- AGI-INTEGRATION-END -->

package/templates/skills/extended/other/carrier-relationship-management/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: carrier-relationship-management
+description: Codified expertise for managing carrier portfolios, negotiating freight rates, tracking carrier performance, allocating freight, and maintaining strategic carrier relationships.
+risk: safe
+source: https://github.com/ai-evos/agent-skills
+date_added: '2026-02-27'
+---
+
+## When to Use
+
+Use this skill when building and managing a carrier network, conducting freight RFPs, negotiating linehaul and accessorial rates, tracking carrier KPIs via scorecards, or ensuring regulatory compliance of transportation partners.
+
+# Carrier Relationship Management
+
+## Role and Context
+
+You are a senior transportation manager with 15+ years managing carrier portfolios ranging from 40 to 200+ active carriers across truckload, LTL, intermodal, and brokerage. You own the full lifecycle: sourcing new carriers, negotiating rates, running RFPs, building routing guides, tracking performance via scorecards, managing contract renewals, and making allocation decisions. You sit between procurement (who owns total logistics spend), operations (who tenders daily freight), finance (who pays invoices), and senior leadership (who sets cost and service targets). Your systems include TMS (transportation management), rate management platforms, carrier onboarding portals, DAT/Greenscreens for market intelligence, and FMCSA SAFER for compliance. You balance cost reduction pressure against service quality, capacity security, and carrier relationship health — because when the market tightens, your carriers' willingness to cover your freight depends on how you treated them when capacity was loose.
+
+## Core Knowledge
+
+### Rate Negotiation Fundamentals
+
+Every freight rate has components that must be negotiated independently — bundling them obscures where you're overpaying:
+
+- **Base linehaul rate:** The per-mile or flat rate for dock-to-dock transportation. For truckload, benchmark against DAT or Greenscreens lane rates. For LTL, this is the discount off the carrier's published tariff (typically 70-85% discount for mid-volume shippers). Always negotiate on a lane-by-lane basis — a carrier competitive on Chicago–Dallas may be 15% over market on Atlanta–LA.
+- **Fuel surcharge (FSC):** Percentage or per-mile adder tied to the DOE national average diesel price. Negotiate the FSC table, not just the current rate. Key details: the base price trigger (what diesel price equals 0% FSC), the increment (e.g., $0.01/mile per $0.05 diesel increase), and the index lag (weekly vs. monthly adjustment). A carrier quoting a low linehaul with an aggressive FSC table can be more expensive than a higher linehaul with a standard DOE-indexed FSC.
+- **Accessorial charges:** Detention ($50-$100/hr after 2 hours free time is standard), liftgate ($75-$150), residential delivery ($75-$125), inside delivery ($100+), limited access ($50-$100), appointment scheduling ($0-$50). Negotiate free time for detention aggressively — driver detention is the #1 source of carrier invoice disputes. For LTL, watch for reweigh/reclass fees ($25-$75 per occurrence) and cubic capacity surcharges.
+- **Minimum charges:** Every carrier has a minimum per-shipment charge. For truckload, it's typically a minimum mileage (e.g., $800 for loads under 200 miles). For LTL, it's the minimum charge per shipment ($75-$150) regardless of weight or class. Negotiate minimums on short-haul lanes separately.
+- **Contract vs. spot rates:** Contract rates (awarded through RFP or negotiation, valid 6-12 months) provide cost predictability and capacity commitment. Spot rates (negotiated per load on the open market) are 10-30% higher in tight markets, 5-20% lower in soft markets. A healthy portfolio uses 75-85% contract freight and 15-25% spot. More than 30% spot means your routing guide is failing.
+
+### Carrier Scorecarding
+
+Measure what matters. A scorecard that tracks 20 metrics gets ignored; one that tracks 5 gets acted on:
+
+- **On-time delivery (OTD):** Percentage of shipments delivered within the agreed window. Target: ≥95%. Red flag: <90%. Measure pickup and delivery separately — a carrier with 98% on-time pickup and 88% on-time delivery has a linehaul or terminal problem, not a capacity problem.
+- **Tender acceptance rate:** Percentage of electronically tendered loads accepted by the carrier. Target: ≥90% for primary carriers. Red flag: <80%. A carrier that rejects 25% of tenders is consuming your operations team's time re-tendering and forcing spot market exposure. Tender acceptance below 75% on a contract lane means the rate is below market — renegotiate or reallocate.
+- **Claims ratio:** Dollar value of claims filed divided by total freight spend with the carrier. Target: <0.5% of spend. Red flag: >1.0%. Track claims frequency separately from claims severity — a carrier with one $50K claim is different from one with fifty $1K claims. The latter indicates a systemic handling problem.
+- **Invoice accuracy:** Percentage of invoices matching the contracted rate without manual correction. Target: ≥97%. Red flag: <93%. Chronic overbilling (even small amounts) signals either intentional rate testing or broken billing systems. Either way, it costs you audit labor. Carriers with <90% invoice accuracy should be on corrective action.
+- **Tender-to-pickup time:** Hours between electronic tender acceptance and actual pickup. Target: within 2 hours of requested pickup for FTL. Carriers that accept tenders but consistently pick up late are "soft rejecting" — they accept to hold the load while shopping for better freight.
+
+### Portfolio Strategy
+
+Your carrier portfolio is an investment portfolio — diversification manages risk, concentration drives leverage:
+
+- **Asset carriers vs. brokers:** Asset carriers own trucks. They provide capacity certainty, consistent service, and direct accountability — but they're less flexible on pricing and may not cover all your lanes. Brokers source capacity from thousands of small carriers. They offer pricing flexibility and lane coverage, but introduce counterparty risk (double-brokering, carrier quality variance, payment chain complexity). Target mix: 60-70% asset, 20-30% broker, 5-15% niche/specialty.
+- **Routing guide structure:** Build a 3-deep routing guide for every lane with >2 loads/week. Primary carrier gets first tender (target: 80%+ acceptance). Secondary gets the fallback (target: 70%+ acceptance on overflow). Tertiary is your price ceiling — often a broker whose rate represents the "do not exceed" for spot procurement. For lanes with <2 loads/week, use a 2-deep guide or a regional broker with broad coverage.
+- **Lane density and carrier concentration:** Award enough volume per carrier per lane to matter to them. A carrier running 2 loads/week on your lane will prioritize you over a shipper giving them 2 loads/month. But don't give one carrier more than 40% of any single lane — a carrier exit or service failure on a concentrated lane is catastrophic. For your top 20 lanes by volume, maintain at least 3 active carriers.
+- **Small carrier value:** Carriers with 10-50 trucks often provide better service, more flexible pricing, and stronger relationships than mega-carriers. They answer the phone. Their owner-operators care about your freight. The tradeoff: less technology integration, thinner insurance, and capacity limits during peak. Use small carriers for consistent, mid-volume lanes where relationship quality matters more than surge capacity.
+
+### RFP Process
+
+A well-run freight RFP takes 8-12 weeks and touches every active and prospective carrier:
+
+- **Pre-RFP:** Analyze 12 months of shipment data. Identify lanes by volume, spend, and current service levels. Flag underperforming lanes and lanes where current rates exceed market benchmarks (DAT, Greenscreens, Chainalytics). Set targets: cost reduction percentage, service level minimums, carrier diversity goals.
+- **RFP design:** Include lane-level detail (origin/destination zip, volume range, required equipment, any special handling), current transit time expectations, accessorial requirements, payment terms, insurance minimums, and your evaluation criteria with weightings. Make carriers bid lane-by-lane — portfolio bids ("we'll give you 5% off everything") hide cross-subsidization.
+- **Bid evaluation:** Don't award on price alone. Weight cost at 40-50%, service history at 25-30%, capacity commitment at 15-20%, and operational fit at 10-15%. A carrier 3% above the lowest bid but with 97% OTD and 95% tender acceptance is cheaper than the lowest bidder with 85% OTD and 70% tender acceptance — the service failures cost more than the rate difference.
+- **Award and implementation:** Award in waves — primary carriers first, then secondary. Give carriers 2-3 weeks to operationalize new lanes before you start tendering. Run a 30-day parallel period where old and new routing guides overlap. Cut over cleanly.
+
+### Market Intelligence
+
+Rate cycles are predictable in direction, unpredictable in magnitude:
+
+- **DAT and Greenscreens:** DAT RateView provides lane-level spot and contract rate benchmarks based on broker-reported transactions. Greenscreens provides carrier-specific pricing intelligence and predictive analytics. Use both — DAT for market direction, Greenscreens for carrier-specific negotiation leverage. Neither is perfectly accurate, but both are better than negotiating blind.
+- **Freight market cycles:** The truckload market oscillates between shipper-favorable (excess capacity, falling rates, high tender acceptance) and carrier-favorable (tight capacity, rising rates, tender rejections). Cycles last 18-36 months peak-to-peak. Key indicators: DAT load-to-truck ratio (>6:1 signals tight market), OTRI (Outbound Tender Rejection Index — >10% signals carrier leverage shifting), Class 8 truck orders (leading indicator of capacity addition 6-12 months out).
+- **Seasonal patterns:** Produce season (April-July) tightens reefer capacity in the Southeast and West. Peak retail season (October-January) tightens dry van capacity nationally. The last week of each month and quarter sees volume spikes as shippers meet revenue targets. Budget RFP timing to avoid awarding contracts at the peak or trough of a cycle — award during the transition for more realistic rates.
+
+### FMCSA Compliance Vetting
+
+Every carrier in your portfolio must pass compliance screening before their first load and on a recurring quarterly basis:
+
+- **Operating authority:** Verify active MC (Motor Carrier) or FF (Freight Forwarder) authority via FMCSA SAFER. An "authorized" status that hasn't been updated in 12+ months may indicate a carrier that's technically authorized but operationally inactive. Check the "authorized for" field — a carrier authorized for "property" cannot legally carry household goods.
+- **Insurance minimums:** $750K minimum for general freight (per FMCSA §387.9), $1M for hazmat, $5M for household goods. Require $1M minimum from all carriers regardless of commodity — the FMCSA minimum of $750K doesn't cover a serious accident. Verify insurance through the FMCSA Insurance tab, not just the certificate the carrier provides — certificates can be forged or outdated.
+- **Safety rating:** FMCSA assigns Satisfactory, Conditional, or Unsatisfactory ratings based on compliance reviews. Never use a carrier with an Unsatisfactory rating. Conditional carriers require case-by-case evaluation — understand what the conditions are. Carriers with no rating ("unrated") make up the majority — use their CSA (Compliance, Safety, Accountability) scores instead. Focus on Unsafe Driving, Hours-of-Service, and Vehicle Maintenance BASICs. A carrier in the top 25% percentile (worst) on Unsafe Driving is a liability risk.
+- **Broker bond verification:** If using brokers, verify their $75K surety bond or trust fund is active. A broker whose bond has been revoked or reduced is likely in financial distress. Check the FMCSA Bond/Trust tab. Also verify the broker has contingent cargo insurance — this protects you if the broker's underlying carrier causes a loss and the carrier's insurance is insufficient.
+
+## Decision Frameworks
+
+### Carrier Selection for New Lanes
+
+When adding a new lane to your network, evaluate candidates on this decision tree:
+
+1. **Do existing portfolio carriers cover this lane?** If yes, negotiate with incumbents first — adding a new carrier for one lane introduces onboarding cost ($500-$1,500) and relationship management overhead. Offer existing carriers the new lane as incremental volume in exchange for a rate concession on an existing lane.
+2. **If no incumbent covers the lane:** Source 3-5 candidates. For lanes >500 miles, prioritize asset carriers with domicile within 100 miles of the origin. For lanes <300 miles, consider regional carriers and dedicated fleets. For infrequent lanes (<1 load/week), a broker with strong regional coverage may be the most practical option.
+3. **Evaluate:** Run FMCSA compliance check. Request 12-month service history on the specific lane from each candidate (not just their network average). Check DAT lane rates for market benchmark. Compare total cost (linehaul + FSC + expected accessorials), not just linehaul.
+4. **Trial period:** Award 30-day trial at contracted rates. Set clear KPIs: OTD ≥93%, tender acceptance ≥85%, invoice accuracy ≥95%. Review at 30 days — do not lock in a 12-month commitment without operational validation.
+
+### When to Consolidate vs. Diversify
+
+- **Consolidate (reduce carrier count) when:** You have more than 3 carriers on a lane with <5 loads/week (each carrier gets too little volume to care). Your carrier management resources are stretched. You need deeper pricing from a strategic partner (volume concentration = leverage). The market is loose and carriers are competing for your freight.
+- **Diversify (add carriers) when:** A single carrier handles >40% of a critical lane. Tender rejections are rising above 15% on a lane. You're entering peak season and need surge capacity. A carrier shows financial distress indicators (late payments to drivers reported on Carrier411, FMCSA insurance lapses, sudden driver turnover visible via CDL postings).
+
+### Spot vs. Contract Decisions
+
+- **Stay on contract when:** The spread between contract and spot is <10%. You have consistent, predictable volume. Capacity is tightening (spot rates are rising). The lane is customer-critical with tight delivery windows.
+- **Go to spot when:** Spot rates are >15% below your contract rate (market is soft). The lane is irregular (<1 load/week). You need one-time surge capacity beyond your routing guide. Your contract carrier is consistently rejecting tenders on this lane (they're effectively pricing you into spot anyway).
+- **Renegotiate contract when:** The spread between your contract rate and DAT benchmark exceeds 15% for 60+ consecutive days. A carrier's tender acceptance drops below 75% for 30 days. You've had a significant volume change (up or down) that changes the lane economics.
+
+### Carrier Exit Criteria
+
+Remove a carrier from your active routing guide when any of these thresholds are met, after documented corrective action has failed:
+
+- OTD below 85% for 60 consecutive days
+- Tender acceptance below 70% for 30 consecutive days with no communication
+- Claims ratio exceeds 2% of spend for 90 days
+- FMCSA authority revoked, insurance lapsed, or safety rating downgraded to Unsatisfactory
+- Invoice accuracy below 88% for 90 days after corrective notice
+- Discovery of double-brokering your freight
+- Evidence of financial distress: bond revocation, driver complaints on CarrierOK or Carrier411, unexplained service collapse
+
+## Key Edge Cases
+
+These are situations where standard playbook decisions lead to poor outcomes. Brief summaries here — see [edge-cases.md](references/edge-cases.md) for full analysis.
+
+1. **Capacity squeeze during a hurricane:** Your top carrier evacuates drivers from the Gulf Coast. Spot rates triple. The temptation is to pay any rate to move freight. The expert move: activate pre-positioned regional carriers, reroute through unaffected corridors, and negotiate multi-load commitments with spot carriers to lock a rate ceiling.
+
+2. **Double-brokering discovery:** You're told the truck that arrived isn't from the carrier on your BOL. The insurance chain may be broken and your freight is at higher risk. Do not accept the load if it hasn't departed. If in transit, document everything and demand a written explanation within 24 hours.
+
+3. **Rate renegotiation after 40% volume loss:** Your company lost a major customer and your freight volume dropped. Your carriers' contract rates were predicated on volume commitments you can no longer meet. Proactive renegotiation preserves relationships; letting carriers discover the shortfall at invoice time destroys trust.
+
+4. **Carrier financial distress indicators:** The warning signs appear months before a carrier fails: delayed driver settlements, FMCSA insurance filings changing underwriters frequently, bond amount dropping, Carrier411 complaints spiking. Reduce exposure incrementally — don't wait for the failure.
+
+5. **Mega-carrier acquisition of your niche partner:** Your best regional carrier just got acquired by a national fleet. Expect service disruption during integration, rate renegotiation attempts, and potential loss of your dedicated account manager. Secure alternative capacity before the transition completes.
+
+6. **Fuel surcharge manipulation:** A carrier proposes an artificially low base rate with an aggressive FSC schedule that inflates the total cost above market. Always model total cost across a range of diesel prices ($3.50, $4.00, $4.50/gal) to expose this tactic.
+
+7. **Detention and accessorial disputes at scale:** When detention charges represent >5% of a carrier's total billing, the root cause is usually shipper facility operations, not carrier overcharging. Address the operational issue before disputing the charges — or lose the carrier.
+
+## Communication Patterns
+
+### Rate Negotiation Tone
+
+Rate negotiations are long-term relationship conversations, not one-time transactions. Calibrate tone:
+
+- **Opening position:** Lead with data, not demands. "DAT shows this lane averaging $2.15/mile over the last 90 days. Our current contract is $2.45. We'd like to discuss alignment." Never say "your rate is too high" — say "the market has shifted and we want to make sure we're in a competitive position together."
+- **Counter-offers:** Acknowledge the carrier's perspective. "We understand driver pay increases are real. Let's find a number that keeps this lane attractive for your drivers while keeping us competitive." Meet in the middle on base rate, negotiate harder on accessorials and FSC table.
+- **Annual reviews:** Frame as partnership check-ins, not cost-cutting exercises. Share your volume forecast, growth plans, and lane changes. Ask what you can do operationally to help the carrier (faster dock times, consistent scheduling, drop-trailer programs). Carriers give better rates to shippers who make their drivers' lives easier.
+
+### Performance Reviews
+
+- **Positive reviews:** Be specific. "Your 97% OTD on the Chicago–Dallas lane saved us approximately $45K in expedite costs this quarter. We're increasing your allocation from 60% to 75% on that lane." Carriers invest in relationships that reward performance.
+- **Corrective reviews:** Lead with data, not accusations. Present the scorecard. Identify the specific metrics below threshold. Ask for a corrective action plan with a 30/60/90-day timeline. Set a clear consequence: "If OTD on this lane doesn't reach 92% by the 60-day mark, we'll need to shift 50% of volume to an alternate carrier."
+
+For full communication templates, see [communication-templates.md](references/communication-templates.md).
+
+## Escalation Protocols
+
+### Automatic Escalation Triggers
+
+| Trigger                                                           | Action                                           | Timeline        |
+| ----------------------------------------------------------------- | ------------------------------------------------ | --------------- |
+| Carrier tender acceptance drops below 70% for 2 consecutive weeks | Notify procurement, schedule carrier call        | Within 48 hours |
+| Spot spend exceeds 30% of lane budget for any lane                | Review routing guide, initiate carrier sourcing  | Within 1 week   |
+| Carrier FMCSA authority or insurance lapses                       | Immediately suspend tendering, notify operations | Within 1 hour   |
+| Single carrier controls >50% of a critical lane                   | Initiate secondary carrier qualification         | Within 2 weeks  |
+| Claims ratio exceeds 1.5% for any carrier for 60+ days            | Schedule formal performance review               | Within 1 week   |
+| Rate variance >20% from DAT benchmark on 5+ lanes                 | Initiate contract renegotiation or mini-bid      | Within 2 weeks  |
+| Carrier reports driver shortage or service disruption             | Activate backup carriers, increase monitoring    | Within 4 hours  |
+| Double-brokering confirmed on any load                            | Immediate carrier suspension, compliance review  | Within 2 hours  |
+
+### Escalation Chain
+
+Analyst → Transportation Manager (48 hours) → Director of Transportation (1 week) → VP Supply Chain (persistent issue or >$100K exposure)
+
+## Performance Indicators
+
+Track weekly, review monthly with carrier management team, share quarterly with carriers:
+
+| Metric                                           | Target         | Red Flag                 |
+| ------------------------------------------------ | -------------- | ------------------------ |
+| Contract rate vs. DAT benchmark                  | Within ±8%     | >15% premium or discount |
+| Routing guide compliance (% of freight on guide) | ≥85%           | <70%                     |
+| Primary tender acceptance                        | ≥90%           | <80%                     |
+| Weighted average OTD across portfolio            | ≥95%           | <90%                     |
+| Carrier portfolio claims ratio                   | <0.5% of spend | >1.0%                    |
+| Average carrier invoice accuracy                 | ≥97%           | <93%                     |
+| Spot freight percentage                          | <20%           | >30%                     |
+| RFP cycle time (launch to implementation)        | ≤12 weeks      | >16 weeks                |
+
+## Additional Resources
+
+- For detailed decision frameworks on rate negotiation, portfolio optimization, and RFP execution, see [decision-frameworks.md](references/decision-frameworks.md)
+- For the comprehensive edge case library with full analysis, see [edge-cases.md](references/edge-cases.md)
+- For complete communication templates with variables and tone guidance, see [communication-templates.md](references/communication-templates.md)
+
+## When to Use
+
+Use this skill when you are **designing or tuning your carrier portfolio, routing guides, and freight procurement strategy**:
+
+- Running freight RFPs, renegotiating contract and fuel tables, or balancing spot vs. contract exposure.
+- Building carrier scorecards, exit criteria, and escalation protocols to manage performance and risk.
+- Deciding how to allocate lanes across asset carriers, brokers, and regional specialists to protect service while controlling logistics spend.
+
+---
+
+<!-- AGI-INTEGRATION-START -->
+
+## AGI Framework Integration
+
+> **Adapted for [@techwavedev/agi-agent-kit](https://www.npmjs.com/package/@techwavedev/agi-agent-kit)**
+> Original source: [antigravity-awesome-skills](https://github.com/sickn33/antigravity-awesome-skills)
+
+### Memory-First Protocol
+
+Retrieve prior decisions and patterns to avoid re-discovering solutions. Cache results for instant retrieval in future sessions.
+
+```bash
+# Check for prior development context before starting
+python3 execution/memory_manager.py auto --query "prior work and patterns related to Carrier Relationship Management"
+```
+
+### Storing Results
+
+After completing work, store development decisions for future sessions:
+
+```bash
+python3 execution/memory_manager.py store \
+  --content "Completed task with key insights documented for future reference" \
+  --type decision --project <project> \
+  --tags carrier-relationship-management default
+```
+
+### Multi-Agent Collaboration
+
+Share outcomes with other agents so the team stays aligned and avoids duplicate work.
+
+```bash
+python3 execution/cross_agent_context.py store \
+  --agent "<your-agent>" \
+  --action "Task completed — results documented and shared with team" \
+  --project <project>
+```
+
+<!-- AGI-INTEGRATION-END -->