Skip to content
Cortex TMS Logo Cortex TMS Logo Cortex TMS

cortex-tms auto-tier

The cortex-tms auto-tier command analyzes your git repository’s commit history and file patterns to automatically suggest and apply tier tags to documentation files. It uses a scoring system to prioritize high-value documentation while capping HOT files to prevent context bloat, keeping your tiering system aligned with actual work patterns.

Synopsis

Section titled “Synopsis”
Terminal window
cortex-tms auto-tier [options]

Description

Section titled “Description”

Automatic tier management using git history and intelligent scoring. Auto-tier solves the problem of manually deciding which files should be HOT, WARM, or COLD by combining multiple signals: file importance (canonical docs, core patterns), location (docs structure), and recency (when last modified).

Think of it as intelligent memory management for your documentation. Critical reference docs stay HOT, high-value documentation is prioritized, and a hard cap prevents HOT tier explosion. Files are scored and ranked to ensure AI agents see the most relevant context without bloat.

Typical usage:

Terminal window
# Preview what would change
cortex-tms auto-tier --dry-run


# Apply tier tags
cortex-tms auto-tier


# Use custom thresholds for your workflow
cortex-tms auto-tier --hot 14 --warm 60

Options

Section titled “Options”
OptionDefaultDescription
--hot <days>7Files modified within N days get recency bonus in scoring
--warm <days>30Files modified within N days → WARM tier
--cold <days>90Files older than N days → COLD tier
--max-hot <count>10Maximum number of HOT files (prevents context bloat)
--dry-run, -dfalsePreview tier suggestions without applying changes
--force, -ffalseOverwrite existing tier tags (default: respect explicit tags)
--verbose, -vfalseShow detailed reasons for each tier assignment

How It Works

Section titled “How It Works”

  1. Repository Scan

    Finds all *.md files in your repository (excluding **/node_modules/**, .git/**, **/dist/**)

  2. Git History Analysis

    For each tracked file, runs git log --follow to find the last commit timestamp

    • Uses --follow to track files across renames
    • Untracked files are skipped (not in git history)

  3. Score Calculation

    Assigns points to each file based on value signals:

    • +100 points: Canonical HOT files (NEXT-TASKS.md, CLAUDE.md, etc.) - highest priority
    • +40 points: Documentation files (docs/ directory)
    • +10 points: Core reference docs (docs/core/ directory)
    • +15 points: Recently modified (≤ 7 days by default)
    • -60 points: Archive files (docs/archive/ → always COLD)

  4. Tier Assignment with Strict Cap

    Sorts files by score and applies tiering:

    • Sort by score: All files ranked (canonical=100, docs/core/+recent=65, etc.)
    • Apply strict cap: Top N files (default: 10) become HOT, including canonical
    • Canonical priority: Score 100 ensures canonical files naturally fill HOT slots first
    • Directory conventions: Non-HOT files use directory rules: docs/guides/ → WARM, examples/ → COLD
    • Time-based fallback: Unclassified files use modification time
    • Explicit tags: Respected unless --force used (except canonical files which can be re-tagged)

  5. Tag Insertion

    Adds <!-- @cortex-tms-tier TIER --> comment at file beginning (or after front matter)

Example Output

Section titled “Example Output”

Dry run on cortex-tms repository (145 files analyzed):

Terminal window
$ cortex-tms auto-tier --dry-run


🔄 Git-Based Auto-Tiering


🔍 DRY RUN MODE: No files will be modified.


✔ Analyzed 145 files


📊 Tier Suggestions:


🔥 HOT (10 files)
  ✨ docs/core/GLOSSARY.md
  ✨ docs/core/PATTERNS.md
  ✨ .github/copilot-instructions.md
  ✨ CLAUDE.md
  ✨ NEXT-TASKS.md
  ✨ docs/core/AI-COLLABORATION-POLICY.md
  ✨ docs/core/ARCHITECTURE.md
  ✨ docs/core/CONTENT-STANDARDS.md
  ✨ docs/core/DECISIONS.md
  ✨ docs/core/DOMAIN-LOGIC.md


📚 WARM (69 files)
  ✨ docs/core/GIT-STANDARDS.md
  ✨ docs/core/INFRASTRUCTURE.md
  ✨ docs/core/SCHEMA.md
  ✨ docs/core/SECURITY.md
  ✨ docs/core/TROUBLESHOOTING.md
  ✨ docs/COMMUNITY.md
  ✨ docs/guides/CLI-USAGE.md
  ✨ docs/guides/MIGRATION-GUIDE.md
  ... and 61 more


❄️  COLD (22 files)
  ✨ docs/archive/bootstrap-v3.0-strategy-plan.md
  ✨ docs/archive/sprint-v2.5-guidance-growth.md
  ✨ docs/archive/sprint-v2.6-integrity-atomicity.md
  ... and 19 more


📈 Summary:
  ✨ CREATE: 101 new tier tags
  🔄 UPDATE: 0 tier changes

Performance: ~300ms for 145 files

Tier Assignment Logic

Section titled “Tier Assignment Logic”

Scoring System

Section titled “Scoring System”

Files are scored based on multiple signals (higher score = higher priority for HOT):

SignalPointsDescription
Canonical HOT+100Must-have files (NEXT-TASKS.md, CLAUDE.md, etc.) - highest priority
Documentation+40Files in docs/ directory
Core docs+10Additional boost for docs/core/
Recent changes+15Modified within --hot days (default: 7)
Archive penalty-60Files in docs/archive/ (always COLD)

HOT Tier Cap (Strict)

Section titled “HOT Tier Cap (Strict)”

Maximum HOT files: Default 10 (configurable via --max-hot)

Strict cap enforcement: Total HOT files (including canonical) never exceeds —max-hot. Files are sorted by score, and the top N become HOT. Canonical files have highest scores (100), ensuring they naturally fill HOT slots first.

Special Cases

Section titled “Special Cases”

Canonical HOT Files (always HOT, never demoted):

  • NEXT-TASKS.md - Current sprint tasks
  • CLAUDE.md - Agent instructions
  • .github/copilot-instructions.md - GitHub Copilot config
  • docs/core/PATTERNS.md - Code patterns and conventions
  • docs/core/GLOSSARY.md - Project terminology

Untracked Files (not in git):

  • Skipped entirely (not scored or tiered)

Explicit Tier Tags:

  • Always respected unless --force is used

Renamed Files:

  • git log --follow tracks history across renames

Usage Examples

Section titled “Usage Examples”

First-Time Setup

Section titled “First-Time Setup”
Terminal window
# Safe: preview tier suggestions
cortex-tms auto-tier --dry-run --verbose


# Review output, ensure it makes sense
# Then apply:
cortex-tms auto-tier

Custom Thresholds for Your Workflow

Section titled “Custom Thresholds for Your Workflow”
Terminal window
# Daily commits → tight windows
cortex-tms auto-tier --hot 3 --warm 7 --cold 30


# Only last 3 days are HOT
# Files from 4-7 days ago are WARM
# Anything older than 30 days is COLD

Use case: Active startup, daily feature releases, rapid iteration

Weekly Maintenance

Section titled “Weekly Maintenance”
Terminal window
# Run at start of each sprint
cortex-tms auto-tier --force


# Updates all tier tags based on current state
# Ensures tiers stay aligned with work patterns

Why --force?

  • Without --force: Skips files with existing tier tags
  • With --force: Overwrites all tier tags
  • Use weekly to keep tiers current as project evolves

Integration with Token Analysis

Section titled “Integration with Token Analysis”
Terminal window
# Step 1: Apply tier tags
cortex-tms auto-tier


# Step 2: Check tier assignments
cortex-tms status


# Output shows tier distribution and file organization
# COLD files: Excluded from analysis
#
# Context Reduction: 85% (70K instead of 82K)

Result: AI agents read only what matters, costs less, fewer hallucinations

Exit Codes

Section titled “Exit Codes”
CodeMeaningScenario
0SuccessTier tags analyzed/applied successfully
1ErrorNot a git repository, invalid options, git command failed

Examples:

Terminal window
# Success (git repo, valid options)
$ cortex-tms auto-tier --dry-run
$ echo $?
0


# Error (not a git repo)
$ cortex-tms auto-tier
❌ Error: Not a git repository
$ echo $?
1


# Error (invalid threshold)
$ cortex-tms auto-tier --hot foo
❌ Error: --hot must be a positive number
$ echo $?
1

Detailed Examples

Section titled “Detailed Examples”

Verbose Output

Section titled “Verbose Output”
Terminal window
$ cortex-tms auto-tier --dry-run --verbose


🔄 Git-Based Auto-Tiering


🔍 DRY RUN MODE: No files will be modified.


✔ Analyzed 131 files


📊 Tier Suggestions:


🔥 HOT (10 files)
  ✨ NEXT-TASKS.md
      Canonical HOT file
  ✨ CLAUDE.md
      Canonical HOT file
  ✨ docs/core/PATTERNS.md
      Canonical HOT file
  ✨ docs/core/TROUBLESHOOTING.md
      High-value doc (score: 65)
  ... (detailed reasons for each file)

Use case: Understanding why files are tiered the way they are (shows scoring results)

Force Update

Section titled “Force Update”
Terminal window
# First run
cortex-tms auto-tier
# ✨ CREATE: 81 new tier tags


# Second run (files already have tags)
cortex-tms auto-tier
# ✓ No changes to apply (existing tags preserved)

Behavior: Respects existing tier tags

CI/CD Automation

Section titled “CI/CD Automation”
.github/workflows/update-tiers.yml
name: Weekly Tier Update


on:
  schedule:
    - cron: '0 0 * * 1'  # Every Monday at midnight
  workflow_dispatch:  # Manual trigger


jobs:
  update-tiers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full git history needed


      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'


      - name: Update Tier Tags
        run: npx cortex-tms@latest auto-tier --force


      - name: Commit Changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -u
          git commit -m "chore: weekly tier update" || echo "No changes"
          git push

Benefit: Tiers stay current automatically, no manual work

Requirements

Section titled “Requirements”

Git Repository Required

Auto-tier must be run in a git-initialized project. It uses git history to determine file recency.

Terminal window
# Check if git repo
git status


# If not, initialize
git init
git add .
git commit -m "Initial commit"


# Now auto-tier will work
cortex-tms auto-tier

Other requirements:

  • Git installed and in PATH
  • Files must be committed for accurate history
  • Markdown (.md) files only

Limitations and Edge Cases

Section titled “Limitations and Edge Cases”

Current Limitations

Section titled “Current Limitations”

Subdirectory Detection (coming soon):

Terminal window
# Currently: Must run from repo root
cd /path/to/repo
cortex-tms auto-tier  # ✅ Works


cd /path/to/repo/docs
cortex-tms auto-tier  # ❌ Error: Not a git repository

Workaround: Always run from repository root

Untracked Files:

Terminal window
# Untracked files are skipped (not scored or tiered)
echo "# New Doc" > new-file.md
cortex-tms auto-tier --dry-run


# Output: new-file.md won't appear
# (not in git history, so skipped)


# To tier it: commit first
git add new-file.md
git commit -m "Add new doc"
cortex-tms auto-tier --dry-run

Rationale: Only committed files have history to analyze

Binary Files:

Terminal window
# Only Markdown files are processed
# Images, PDFs, etc. are ignored

Performance:

~1.5s
# Linear scaling with file count
# 111 files: ~300ms (cortex-tms repo)
# 1000 files: ~3s

For very large repos (1000+ files), consider:

  • Running less frequently (monthly instead of weekly)
  • Using --dry-run to preview before applying

Edge Cases

Section titled “Edge Cases”

Empty Git Repository:

Terminal window
git init
cortex-tms auto-tier


# No files tiered (no committed files to analyze)
# Must commit files first for auto-tier to work

Renamed Files:

Terminal window
# git log --follow tracks renames
git mv OLD.md NEW.md
git commit -m "Rename file"


cortex-tms auto-tier --dry-run
# NEW.md gets proper age (tracks history through rename)

Submodules:

Terminal window
# Analyzes within submodule context
# Each submodule has its own git history

Troubleshooting

Section titled “Troubleshooting”

”Not a git repository” Error

Section titled “”Not a git repository” Error”

Symptom:

Terminal window
$ cortex-tms auto-tier
❌ Error: Not a git repository
   Run this command in a git-initialized project.

Causes:

  1. Not in a git repository
  2. Running from subdirectory (limitation - must run from repo root)

Solutions:

Terminal window
git init
git add .
git commit -m "Initial commit"
cortex-tms auto-tier

Invalid Threshold Errors

Section titled “Invalid Threshold Errors”

Symptom:

Terminal window
$ cortex-tms auto-tier --hot foo
❌ Error: --hot must be a positive number


$ cortex-tms auto-tier --hot 50 --warm 30
❌ Error: --hot threshold must be ≤ --warm threshold
   Got: hot=50, warm=30

Solution: Use valid, ordered thresholds

Terminal window
# ✅ Correct: hot ≤ warm ≤ cold
cortex-tms auto-tier --hot 7 --warm 30 --cold 90

No Files Changed

Section titled “No Files Changed”

Symptom:

Terminal window
$ cortex-tms auto-tier
✔ Analyzed 50 files
✓ No changes to apply.

Causes:

  1. All files already have tier tags (use --force to update)
  2. No Markdown files in repository
  3. All files in ignored directories

Solutions:

Terminal window
# Overwrite existing tier tags
cortex-tms auto-tier --force

Best Practices

Section titled “Best Practices”

Start with Dry Run

Always preview tier suggestions before applying:

Terminal window
cortex-tms auto-tier --dry-run --verbose

Review the output to ensure thresholds make sense for your project.

Commit Tier Tags

Tier tags should be version-controlled:

Terminal window
cortex-tms auto-tier
git add -u
git commit -m "chore: update tier tags"

This keeps tiers consistent across the team.

Adjust Thresholds to Workflow

Match thresholds to your commit cadence:

  • Daily commits: --hot 3 --warm 7
  • Weekly commits: --hot 14 --warm 30
  • Monthly commits: --hot 30 --warm 90

Run Regularly

Update tiers periodically as work shifts:

Terminal window
# Weekly: Before sprint planning
cortex-tms auto-tier --force


# Or: Monthly maintenance
cortex-tms auto-tier --force

Integration with Other Commands

Section titled “Integration with Other Commands”

After Auto-Tier: Verify Token Distribution

Section titled “After Auto-Tier: Verify Token Distribution”
Terminal window
# Apply tier tags
cortex-tms auto-tier


# Verify tier assignments
cortex-tms status

Before AI Session: Refresh Tiers

Section titled “Before AI Session: Refresh Tiers”
Terminal window
# Update tiers before major AI coding session
cortex-tms auto-tier --force


# Ensures AI sees most relevant context
cortex-tms prompt init-session

With Validate: Check Tier Tag Format

Section titled “With Validate: Check Tier Tag Format”
Terminal window
# Apply tier tags
cortex-tms auto-tier


# Verify tags are valid
cortex-tms validate


# Should pass (tier tags don't affect validation)

Performance Characteristics

Section titled “Performance Characteristics”

Measured Performance

Section titled “Measured Performance”

Test repository: cortex-tms (145 markdown files)

OperationTimeFiles/Second
Dry run~300ms370 files/s
Apply tags~340ms325 files/s
Force update~350ms315 files/s

Scaling:

  • Linear with file count
  • Git log is dominant cost (~2-3ms per file)

Future optimizations (planned for v3.2+):

  • Batched git log for large repos
  • Parallel file processing
Section titled “Related Commands”

Learn More

Section titled “Learn More”