Troubleshooting Guide

Welcome to the Cortex TMS troubleshooting guide. This page provides a systematic approach to diagnosing and resolving common issues you might encounter when using Cortex TMS. Whether you are experiencing installation problems, validation errors, or AI agent integration issues, this guide will help you identify and fix the problem quickly.

Quick Diagnostic Checklist

Use this quick checklist to identify the category of your issue. Click on the relevant category to jump to detailed troubleshooting steps.

Installation Problems

Symptoms:

• cortex-tms: command not found
• npm/pnpm installation failures
• Permission errors (EACCES)
• cortex-tms init failures

Go to Installation Issues →

Validation Errors

Symptoms:

• cortex-tms validate fails
• File size limit warnings
• Missing mandatory files
• Placeholder detection errors
• .cortexrc configuration issues

Go to Validation Errors →

AI Agent Issues

Symptoms:

• Claude Code not reading CLAUDE.md
• GitHub Copilot ignoring project patterns
• Cursor .cursorrules not detected
• AI generates code violating conventions
• Context window exceeded errors

Go to AI Agent Issues →

Git Integration

Symptoms:

• Git not detected during init
• Branch creation failures
• Commit hook errors
• .gitignore conflicts

Quick Fix: Check git is installed: git --version

---

Issue Categories

Installation Issues

Problems that occur when installing or initializing Cortex TMS.

Common issues:

• Command not found after npm install
• Permission denied errors
• Node.js version incompatibilities
• Package manager conflicts (npm vs pnpm vs yarn)
• Windows path and line ending issues
• Corporate proxy/firewall blocking npm

Full troubleshooting guide: Installation Issues →

---

Validation Errors

Problems that occur when running cortex-tms validate.

Common issues:

• Missing mandatory files (CLAUDE.md, NEXT-TASKS.md, .cortexrc)
• File size exceeds recommended limits
• Unreplaced placeholders detected
• Malformed JSON in .cortexrc
• Archive directory structure violations
• Zero-drift detection failures

Full troubleshooting guide: Validation Errors →

---

AI Agent Issues

Problems with Claude Code, GitHub Copilot, or Cursor integration.

Common issues:

• AI agents not reading documentation files
• Generated code violates documented patterns
• Security rules being ignored
• Context window limits exceeded
• Stale context (AI reading old files)
• Inconsistent suggestions across team members

Full troubleshooting guide: AI Agent Issues →

---

General Troubleshooting Workflow

Follow this systematic workflow to diagnose any Cortex TMS issue:

Step 1: Identify the Symptom

What exactly is failing? Be specific:

Good

• “Running cortex-tms init shows error: EACCES: permission denied”
• “cortex-tms validate reports: NEXT-TASKS.md exceeds 200 lines”
• “GitHub Copilot suggests localStorage for tokens despite .github/copilot-instructions.md forbidding it”

Vague

• “Install doesn’t work”
• “Validation fails”
• “Copilot is broken”

Tip

Copy the exact error message if possible. Error text helps identify the root cause faster.

---

Step 2: Check the Basics

Before diving into complex troubleshooting, verify these fundamentals:

Environment Check:

# Check Node.js version (requires 18.x or higher)
node --version

# Check npm version
npm --version

# Check cortex-tms installation
cortex-tms --version

# Check git installation (required for init)
git --version

# Verify you're in a project directory
pwd

Expected output:

v20.10.0
10.2.3
2.6.0
git version 2.43.0
/home/user/my-project

Caution

If Node.js version is below 18.x, upgrade Node.js before proceeding. Cortex TMS requires Node.js 18 or higher.

---

File System Check:

# Check if mandatory files exist
ls -la CLAUDE.md NEXT-TASKS.md .cortexrc

# Check file permissions
ls -l CLAUDE.md

# Check directory structure
tree -L 2 docs/

Expected output:

-rw-r--r--  1 user  staff  2048 Jan 15 10:30 CLAUDE.md
-rw-r--r--  1 user  staff  1024 Jan 15 10:30 NEXT-TASKS.md
-rw-r--r--  1 user  staff   512 Jan 15 10:30 .cortexrc

docs/
├── archive/
│   └── sprint-2025-01.md
└── core/
    ├── ARCHITECTURE.md
    ├── PATTERNS.md
    └── DECISIONS.md

---

Step 3: Enable Verbose Logging

Most Cortex TMS commands support a --verbose flag for detailed output:

# Verbose initialization
cortex-tms init --verbose

# Verbose validation
cortex-tms validate --verbose

# Verbose migration
cortex-tms migrate --verbose

Example verbose output:

$ cortex-tms validate --verbose

🔍 Cortex TMS Validation

Project Context:
  Git repository: Yes
  Package.json: Yes
  Package manager: pnpm
  Existing TMS files: NEXT-TASKS.md, CLAUDE.md, .cortexrc

Placeholder Replacements:
  [Project Name] → my-awesome-project
  [project-name] → my-awesome-project
  [Description] → A modern web application

📋 Mandatory Files
  ✓ NEXT-TASKS.md exists
  ✓ CLAUDE.md exists
  ✓ .github/copilot-instructions.md exists

⚙️  Configuration
  ✓ .cortexrc configuration exists

📏 File Size Limits (Rule 4)
  ✓ NEXT-TASKS.md is within size limits
    150/200 lines
  ⚠ ARCHITECTURE.md exceeds recommended line limit
    Current: 650 lines | Limit: 500 lines | Overage: 150 lines

📊 Summary

  Total Checks: 12
  ✓ Passed: 10
  ⚠ Warnings: 2
  ✗ Errors: 0

✨ Validation passed! Your TMS project is healthy.

Tip

Always use --verbose when filing bug reports. The detailed output helps maintainers diagnose issues faster.

---

Step 4: Consult the Specific Troubleshooting Guide

Once you’ve identified the issue category, consult the relevant guide:

Installation Issues

npm/pnpm/yarn installation, command not found, permission errors, Windows issues

Read Guide →

Validation Errors

File size limits, missing files, placeholder errors, .cortexrc issues

Read Guide →

AI Agent Issues

Claude Code, GitHub Copilot, Cursor integration problems

Read Guide →

---

Common Debugging Techniques

Technique 1: Check File Encoding

Cortex TMS requires UTF-8 encoding for all files. Some editors save files with different encodings, causing parsing errors.

# Check file encoding (Linux/macOS)
file CLAUDE.md

# Expected output:
# CLAUDE.md: UTF-8 Unicode text

# Convert to UTF-8 if needed
iconv -f ISO-8859-1 -t UTF-8 CLAUDE.md -o CLAUDE.md

macOS/Linux

# Check encoding
file *.md

# Convert all .md files to UTF-8
for f in *.md; do
  iconv -f ISO-8859-1 -t UTF-8 "$f" -o "$f.utf8"
  mv "$f.utf8" "$f"
done

Windows

# Check encoding in PowerShell
[System.Text.Encoding]::GetEncoding((Get-Content CLAUDE.md -Encoding Byte)[0..2])

# Convert to UTF-8 using VS Code
# File → Save with Encoding → UTF-8

---

Technique 2: Validate JSON Configuration

If .cortexrc is causing errors, validate its JSON syntax:

# Validate .cortexrc JSON syntax (Node.js)
node -e "console.log(JSON.parse(require('fs').readFileSync('.cortexrc', 'utf-8')))"

# Validate .cortexrc JSON syntax (Python)
python3 -m json.tool .cortexrc

# Validate .cortexrc JSON syntax (jq)
jq empty .cortexrc

Common JSON errors:

Trailing Comma

{
  "version": "1.0.0",
  "scope": "standard",
  "paths": {
    "docs": "docs/core"
  },  // ❌ Trailing comma not allowed in JSON
}

Fix: Remove the trailing comma:

{
  "version": "1.0.0",
  "scope": "standard",
  "paths": {
    "docs": "docs/core"
  }
}

Missing Quotes

{
  version: "1.0.0",  // ❌ Keys must be quoted
  scope: "standard"
}

Fix: Add quotes to all keys:

{
  "version": "1.0.0",
  "scope": "standard"
}

Unclosed Braces

{
  "version": "1.0.0",
  "paths": {
    "docs": "docs/core"
  // ❌ Missing closing brace
}

Fix: Close all braces:

{
  "version": "1.0.0",
  "paths": {
    "docs": "docs/core"
  }
}

Tip

Use a JSON linter like jq or an online validator to catch syntax errors quickly.

---

Technique 3: Check Line Endings (Windows)

Windows uses CRLF (\r\n) line endings while Linux/macOS use LF (\n). Git can auto-convert these, causing file size discrepancies.

# Check line endings
file NEXT-TASKS.md

# Output (Windows CRLF):
# NEXT-TASKS.md: ASCII text, with CRLF line terminators

# Output (Linux/macOS LF):
# NEXT-TASKS.md: ASCII text

Fix:

Configure Git

# Set Git to auto-convert CRLF to LF on commit
git config --global core.autocrlf true

# Re-checkout files to apply conversion
git rm --cached -r .
git reset --hard

EditorConfig

Create .editorconfig in your project root:

root = true

[*]
end_of_line = lf
insert_final_newline = true
charset = utf-8

[*.{js,ts,json,md}]
indent_style = space
indent_size = 2

Most editors respect EditorConfig automatically.

Manual Conversion

# Convert CRLF to LF (Linux/macOS)
dos2unix *.md

# Convert CRLF to LF (Windows Git Bash)
sed -i 's/\r$//' *.md

---

Technique 4: Clean Install

If Cortex TMS behaves erratically, perform a clean reinstall:

# Uninstall cortex-tms
npm uninstall -g cortex-tms

# Clear npm cache
npm cache clean --force

# Reinstall cortex-tms
npm install -g cortex-tms

# Verify installation
cortex-tms --version

Caution

This does NOT delete your project files (CLAUDE.md, NEXT-TASKS.md, etc.). It only reinstalls the CLI tool.

---

Getting Help

If you have exhausted all troubleshooting steps and still encounter issues, here is how to get help:

Before Filing a Bug Report

1. Search existing issues: Check GitHub Issues for similar problems
2. Verify you’re on the latest version: Run cortex-tms --version and compare to latest release
3. Test in a clean environment: Try reproducing the issue in a new, empty directory
4. Collect diagnostic information: Run cortex-tms validate --verbose and save the output

---

Filing a Bug Report

When filing a bug report, include:

Required information:

**Environment:**
- OS: macOS 14.2 (or Windows 11, Ubuntu 22.04, etc.)
- Node.js version: 20.10.0
- npm version: 10.2.3
- cortex-tms version: 2.6.0
- Package manager: npm (or pnpm, yarn)

**Steps to reproduce:**
1. Run `cortex-tms init --scope standard`
2. Edit CLAUDE.md to add custom content
3. Run `cortex-tms validate`
4. Error occurs

**Expected behavior:**
Validation should pass

**Actual behavior:**
Error: ENOENT: no such file or directory, open '.cortexrc'

**Full error output:**
(paste complete error message with stack trace)

**Additional context:**
- Using Git version 2.43.0
- Project is a TypeScript monorepo
- Using pnpm workspaces

Optional but helpful:

• Screenshots of error messages
• Minimal reproduction repository (GitHub repo demonstrating the issue)
• Output of cortex-tms validate --verbose
• Contents of .cortexrc (sanitize sensitive data)

Tip

The more information you provide, the faster maintainers can diagnose and fix the issue.

---

Community Support Channels

GitHub Discussions:

• Ask questions: github.com/cortex-tms/cortex-tms/discussions
• Share use cases and patterns
• Request new features

GitHub Issues:

• Report bugs: github.com/cortex-tms/cortex-tms/issues
• Security vulnerabilities: Email security reports directly (see SECURITY.md)

Documentation:

• Getting Started
• CLI Reference
• Guides

---

Preventive Maintenance

Avoid common issues by following these best practices:

Run Validation Regularly

Run cortex-tms validate before committing changes. Catch issues early before they compound.

# Add to pre-commit hook
cortex-tms validate --strict

Keep Files Under Limits

Archive completed tasks regularly. File size limits exist to keep AI context windows manageable.

Trigger: When NEXT-TASKS.md exceeds 150 lines, archive completed tasks.

Update Dependencies

Keep cortex-tms updated to get bug fixes and new features.

npm update -g cortex-tms

Use Version Control

Commit TMS files to Git. If something breaks, you can always revert to a working state.

git add CLAUDE.md NEXT-TASKS.md .cortexrc
git commit -m "docs: update TMS files"

Document Custom Patterns

Update docs/core/PATTERNS.md when you establish new conventions. AI agents will follow them automatically.

Test AI Integration

After updating documentation, test AI agents to ensure they read the new content correctly.

---

Diagnostic Commands Reference

Quick reference for diagnostic commands:

# Environment diagnostics
node --version                    # Node.js version
npm --version                     # npm version
git --version                     # Git version
cortex-tms --version              # Cortex TMS version

# File diagnostics
ls -la CLAUDE.md NEXT-TASKS.md    # Check files exist
file CLAUDE.md                    # Check file encoding
wc -l NEXT-TASKS.md               # Count lines

# Validation diagnostics
cortex-tms validate --verbose     # Detailed validation output
cortex-tms validate --strict      # Treat warnings as errors

# Configuration diagnostics
cat .cortexrc                     # View configuration
jq empty .cortexrc                # Validate JSON syntax
node -e "console.log(require('./.cortexrc'))"  # Parse config in Node

# Git diagnostics
git status                        # Check working tree
git log --oneline -5              # Recent commits
git config --list                 # Git configuration

# Package manager diagnostics
npm list -g cortex-tms            # Check global installation
npm cache clean --force           # Clear npm cache

---

Next Steps

Now that you understand the troubleshooting workflow:

• Installation Issues: Detailed npm, Node.js, and permission troubleshooting
• Validation Errors: Fix cortex-tms validate failures
• AI Agent Issues: Resolve Claude Code, Copilot, and Cursor problems

Tip

Bookmark this page for quick reference. Most issues can be resolved by following the systematic workflow above.