This page provides an honest, transparent view of Cortex TMS’s current limitations, known issues, and planned improvements. Understanding these constraints will help you make informed decisions and set appropriate expectations.
Cortex TMS v2.6.0 (Latest Stable Release) Release Date: January 18, 2026 Status: Production Ready Node.js Requirement: 18.0.0 or higher
If you discover a critical issue, please report it immediately via GitHub Issues with the “critical” label.
Symlink Creation Requires Admin
Symptom: EPERM: operation not permitted, symlink errors during npm link testing.
Cause: Windows requires administrator privileges or Developer Mode for symlink creation.
Workaround:
Path Separator Differences
Symptom: Template paths using forward slashes (/) may not resolve correctly.
Status: Cortex TMS uses path.join() internally, so this is largely resolved.
Edge Case: If you manually construct file paths in custom scripts, use path.join() or path.resolve().
Line Ending Inconsistencies (CRLF vs LF)
Symptom: Git reports file changes when no actual content changed.
Cause: Windows uses CRLF (\r\n) while Unix uses LF (\n).
Solution: Configure Git to auto-convert line endings:
git config --global core.autocrlf true # Windowsgit config --global core.autocrlf input # macOS/LinuxCase-Sensitive File Systems (Optional)
PATTERNS.md and patterns.md are different filesPATTERNS.md, ARCHITECTURE.md)Snap-Installed Node.js Permissions
nvm (Node Version Manager) or install Node.js via your distribution’s package managercortex-tms init
No Multi-Project Batch Initialization: You cannot initialize multiple projects in one command. You must run cortex-tms init in each project directory individually.
Workaround (Bash):
for dir in project1 project2 project3; do cd $dir && cortex-tms init --scope standard && cd ..doneCannot Re-initialize Without Overwriting: If you run cortex-tms init in a project that already has TMS files, you’ll be prompted to overwrite. There’s no “merge” mode.
Workaround: Use cortex-tms migrate to upgrade existing files.
Interactive Prompts Require TTY: Non-interactive environments (CI/CD pipelines) must use --scope flag explicitly.
# ✅ Works in CI/CDcortex-tms init --scope standard
# ❌ Fails in CI/CD (no TTY for prompts)cortex-tms initcortex-tms validate
Line Count Enforcement is Static: The default line limits (200 for NEXT-TASKS.md, 100 for copilot-instructions.md) are hardcoded. While you can override them in .cortexrc, you cannot disable line limit checking entirely.
Workaround: Set extremely high limits in .cortexrc if you truly need unlimited files:
{ "lineLimits": { "NEXT-TASKS.md": 999999 }}No Partial Validation: You cannot validate only specific files; cortex-tms validate always checks all mandatory files.
Archive Detection Heuristic: The archive warning (when docs/archive/ has more than 5 files) is a heuristic, not a strict rule. Some projects legitimately need many archived documents.
cortex-tms migrate
Cannot Customize Template Source: The migration system always pulls templates from the installed cortex-tms package. You cannot specify a custom template directory.
Roadmap: Custom template directories planned for v2.7.
Backup Pruning is Automatic: Backups older than the 10 most recent are automatically deleted. You cannot configure retention policy.
Workaround: Manually copy .cortex/backups/ to a separate location for long-term archival.
No Selective File Migration: When you run migrate --apply, you cannot choose which specific files to upgrade. It upgrades all OUTDATED files in batch.
Workaround: Manually copy individual templates from node_modules/cortex-tms/templates/.
cortex-tms status
No JSON Output: The status dashboard is designed for human readability only. There’s no --json flag for programmatic consumption.
Use Case: If you need to parse project status in scripts, directly read NEXT-TASKS.md and parse the markdown.
Progress Bar is Approximate: The sprint progress percentage is calculated from task status markers (✅ Done, ⬜ Todo). If tasks have uneven complexity, the visual bar may not reflect true completion.
cortex-tms prompt
Clipboard Integration Fails in Headless Environments: SSH sessions and Docker containers without X11 forwarding cannot access the clipboard.
Workaround: The prompt text is still printed to stdout. Manually copy it or redirect to a file:
cortex-tms prompt init-session > /tmp/prompt.txtPrompt Library is Static: The Essential 7 prompts are embedded in the CLI. While you can customize PROMPTS.md in your project, the CLI doesn’t read from it.
Why: Ensures consistency across installations. Custom prompts are for AI agents to read directly from PROMPTS.md.
Hard Limits
File Names Must Use Exact Casing: Template files expect uppercase naming (e.g., PATTERNS.md, not patterns.md). The validation system is case-sensitive.
Placeholder Syntax is Required: If you want the validation system to detect unfilled templates, use [Description] syntax. Other placeholder styles (like TODO, FIXME, <placeholder>) are not recognized.
Archive Directory Must Be Named archive/: The validation system specifically checks for docs/archive/. Renaming it to historical/ or old/ will break archive detection.
Version Comments Must Match Format: Files use <!-- @cortex-tms-version 2.6.0 --> for version tracking. Deviating from this format (e.g., <!-- Version: 2.6.0 -->) breaks migration detection.
Soft Limits (Configurable)
Default Line Limits:
NEXT-TASKS.md: 200 lines.github/copilot-instructions.md: 100 linesdocs/core/ files: 1000 lines (configurable via .cortexrc)Maximum Files in Archive: No hard limit, but validation warns if docs/archive/ exceeds 5 files (suggests cleanup).
Framework Compatibility
Cortex TMS templates are framework-agnostic by design, meaning:
Example: Cortex TMS won’t auto-populate your ARCHITECTURE.md with your Next.js routes or database schema. You must fill those in manually.
Template Customization
Cannot Override Individual Template Sections: When you run migrate --apply, the entire file is replaced. You cannot selectively upgrade just the header or footer.
No Template Inheritance: You cannot create a “child” template that inherits from a “parent” template. Each template file is standalone.
Placeholder Replacement is Manual: The CLI does not auto-replace placeholders like [Project Name] with your actual project name from package.json. This is intentional—AI agents handle replacement during sessions.
Edge Cases in AI Behavior
File Size Affects Token Budget: Even though Cortex TMS keeps files small (200 lines for NEXT-TASKS.md), AI agents may still struggle with dense technical content.
Best Practice: Use bullet points, not paragraphs, in task descriptions.
Agents May Skip WARM Tier Files: If you don’t explicitly prompt the agent to read docs/core/PATTERNS.md, it might not discover it on its own.
Mitigation: Use cortex-tms prompt feature to generate prompts that reference PATTERNS.md explicitly.
Historical Noise in Git Commits: Even with aggressive archiving, AI agents sometimes read old Git commit messages. This is outside Cortex TMS’s control.
Workaround: Use conventional commits (enforced by Git Guardian in v2.6.0) to make commit history more parseable.
Placeholder Detection Failures: If you write [TODO: Add description], the validation system sees [TODO as a placeholder and flags it. Use TODO without brackets or [Add description] instead.
Multi-Agent Conflicts
If multiple AI agents (Claude + Copilot) work on the same project simultaneously:
NEXT-TASKS.mdNEXT-TASKS.md as single-writer (one AI agent at a time). Use Git branches for parallel work.Pre-Commit Validation Scope
MDX Syntax Errors Not Caught Pre-Commit: Website documentation syntax errors (MDX, JSX) pass through pre-commit validation.
Impact: Low - Errors surface immediately during local development preview or website build.
Example: Using <200 instead of <200 in MDX files passes pre-commit but fails build.
Workaround:
npm run build from website directory before committing documentation changesnpm run dev)Why Not Fixed: Adding website build to pre-commit adds 15-30 seconds to every documentation commit. Current manual validation is sufficient given:
Future Enhancement: Will implement automated build validation if MDX errors become recurring (threshold: 3+ errors in a sprint). Deferred to v2.9+ unless frequency increases.
No Automated Test Runs Pre-Commit: Test suite (74 tests) runs on-demand, not automatically before commit.
Rationale: Tests take ~500ms but run frequently during development. Auto-running adds friction without proportional benefit.
Workaround: Run npm test manually before commits that touch core logic.
CI/CD Safety Net: All tests run in GitHub Actions before merge to main.
Trade-off Philosophy: Cortex TMS prioritizes fast iteration over perfect automation. Pre-commit hooks enforce critical rules (Git protocol) while trusting developers for quality checks (tests, builds).
Custom Template Directories
Status: Planned
Goal: Allow users to specify custom template sources via .cortexrc
Use Case: Organizations can maintain internal template libraries
User-Defined Pattern Sets
Status: Planned Goal: Extend validation rules with custom pattern matching
Use Case: Enforce company-specific conventions (e.g., ticket ID format)
Telemetry (Opt-In)
Status: Under Consideration Goal: Anonymous usage metrics to prioritize features
Privacy: Fully opt-in, no data collection by default
Problem: You’ve customized PATTERNS.md heavily, but a new template version has important updates.
Solution (3-way merge):
# 1. Backup your current filecp docs/core/PATTERNS.md docs/core/PATTERNS.md.backup
# 2. Get the new templatecortex-tms migrate --apply
# 3. Compare and merge manuallygit diff --no-index docs/core/PATTERNS.md.backup docs/core/PATTERNS.mdUse a merge tool like meld, vimdiff, or VS Code’s diff viewer to selectively apply changes.
Problem: You maintain 10 projects with Cortex TMS and want to validate all at once.
Solution (Shell Script):
#!/bin/bashfor project in ~/projects/*; do if [ -f "$project/.cortexrc" ]; then echo "Validating $project..." cd "$project" && cortex-tms validate --strict fidoneProblem: You want strict limits in production but relaxed limits during development.
Solution (Multiple .cortexrc files):
{ "lineLimits": { "NEXT-TASKS.md": 500 }}
# .cortexrc.prod{ "lineLimits": { "NEXT-TASKS.md": 200 }}
# Use via symlink or environment variableln -sf .cortexrc.dev .cortexrc # Developmentln -sf .cortexrc.prod .cortexrc # ProductionProblem: You want to display TMS status on a dashboard.
Solution (Parse Markdown):
import fs from 'fs';
const tasks = fs.readFileSync('NEXT-TASKS.md', 'utf-8');const doneCount = (tasks.match(/✅ Done/g) || []).length;const todoCount = (tasks.match(/⬜ Todo/g) || []).length;
console.log(JSON.stringify({ done: doneCount, todo: todoCount }));cortex-tms --version should show 2.6.0 or higher)Environment Information
node --version)cortex-tms --version)Reproduction Steps
Context
.cortexrc configuration?cortex-tms validate --verboseUse the appropriate GitHub Issue template:
Many of these limitations are open for community contribution! If you’re interested in helping:
Popular contribution areas:
Git Line Endings in Mixed Environments
If your team uses both Windows and Unix-based systems:
Problem: Files show changes in Git even when content is identical.
Root Cause: Windows uses \r\n (CRLF), while Unix uses \n (LF).
Complete Solution:
Global Git Configuration:
# Windows developersgit config --global core.autocrlf true
# macOS/Linux developersgit config --global core.autocrlf inputAdd .gitattributes to Repository:
# Ensure consistent line endings across platforms* text=auto
# Force LF for specific files*.md text eol=lf*.ts text eol=lf*.js text eol=lf*.json text eol=lf
# Force CRLF for Windows scripts (if any)*.bat text eol=crlf*.ps1 text eol=crlf
# Binary files (no line ending conversion)*.png binary*.jpg binary*.ico binaryNormalize Existing Repository:
# After adding .gitattributesgit add --renormalize .git commit -m "chore: normalize line endings"Verification:
# Check line endings in a file (Unix)file NEXT-TASKS.md# Should output: ASCII text, with LF line terminators
# Or use hexdumphexdump -C NEXT-TASKS.md | grep "0d 0a"# Should return nothing if LF-onlyWindows MAX_PATH Constraint (260 characters)
Symptom: Errors when creating deeply nested backup directories:
Error: ENAMETOOLONG: name too longCortex TMS Impact: Backup paths like .cortex/backups/2026-01-19_143022/docs/archive/sprint-v2.5-very-long-name.md may exceed 260 characters.
Workaround (Windows 10+):
Enable long path support (requires admin):
# Run in PowerShell as AdministratorNew-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" ` -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -ForceUpdate Git configuration:
git config --system core.longpaths trueRestart your terminal/IDE
Alternative: Use WSL2 for development (no path length limitations).
macOS APFS vs HFS+
Impact: PATTERNS.md and patterns.md are treated as the same file.
Edge Case:
# This silently overwrites the first file on macOStouch PATTERNS.mdtouch patterns.md
# List filesls -l# Shows only PATTERNS.md (last write wins)Cortex TMS Convention: Always use uppercase for template files (e.g., PATTERNS.md, ARCHITECTURE.md).
Linux (Case-Sensitive by Default)
If you develop on Linux and deploy to macOS, be aware:
# Linux: These are different filestouch README.mdtouch readme.md
# macOS: These collide# May cause unexpected behavior when cloning repoBest Practice: Use consistent casing across all platforms (follow Cortex TMS uppercase convention).
Batch Operations Across Multiple Projects
Limitation: Cortex TMS commands operate on one project at a time. There’s no built-in support for batch operations.
Use Case: You maintain 20 microservices, all using Cortex TMS, and want to upgrade templates in all projects simultaneously.
Workaround (Shell Script):
#!/bin/bashPROJECTS=( ~/projects/api-gateway ~/projects/auth-service ~/projects/user-service ~/projects/notification-service)
for project in "${PROJECTS[@]}"; do echo "Upgrading $project..." cd "$project" || exit
# Check if TMS is initialized if [ ! -f .cortexrc ]; then echo " ⚠️ Skipping (no .cortexrc found)" continue fi
# Run migration cortex-tms migrate --apply --force
# Commit changes git add . git commit -m "chore: upgrade Cortex TMS templates to v2.6.0"
echo " ✅ Upgraded successfully"done
echo "🎉 All projects upgraded!"Future Enhancement (v2.7+): Consider proposing a cortex-tms batch command for multi-project operations.
No Environment-Specific Configuration
Limitation: .cortexrc is a single file with no support for environment overrides (dev, staging, production).
Use Case: You want stricter line limits in production but relaxed limits during development.
Current Workaround:
Approach A: Multiple Config Files:
# Store configs in version control.cortexrc.dev.cortexrc.prod
# Symlink based on environmentln -sf .cortexrc.dev .cortexrc # Developmentln -sf .cortexrc.prod .cortexrc # ProductionApproach B: CI/CD Override:
- name: Validate with Strict Rules run: | # Temporarily replace .cortexrc mv .cortexrc .cortexrc.backup cp .cortexrc.ci .cortexrc cortex-tms validate --strict mv .cortexrc.backup .cortexrcProposed Enhancement: Environment variable overrides:
CORTEX_LINE_LIMIT_NEXT_TASKS=500 cortex-tms validateCustom Validation Rules Cannot Be Added
Limitation: The validation engine has hardcoded rules. You cannot add custom validators without modifying Cortex TMS source code.
Use Case: Your organization requires all task descriptions to include a Jira ticket ID (e.g., [PROJ-123]).
Current Workaround (External Script):
#!/bin/bash# Check for Jira ticket IDs in NEXT-TASKS.mdif ! grep -E '\[PROJ-[0-9]+\]' NEXT-TASKS.md > /dev/null; then echo "❌ NEXT-TASKS.md must include Jira ticket IDs" exit 1fi
# Run Cortex TMS validationcortex-tms validate --strict
echo "✅ Custom validation passed!"Add to CI/CD:
- name: Run Custom Validation run: ./scripts/custom-validate.shRoadmap (v2.7): Plugin system for custom validators:
export function validateJiraTicket(file: string): ValidationResult { const content = fs.readFileSync(file, 'utf-8'); const hasTicket = /\[PROJ-\d+\]/.test(content); return { valid: hasTicket, message: hasTicket ? 'Jira ticket found' : 'Missing Jira ticket ID' };}File Validation is Content-Based, Not Schema-Based
Limitation: Cortex TMS validates file existence, line counts, and placeholders. It does NOT validate markdown structure, frontmatter schema, or content semantics.
Example: The following is considered “valid” even though it’s nonsensical:
# NEXT: Upcoming Tasks
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
[Placeholder that doesn't describe anything useful]Why This Design: Cortex TMS is framework-agnostic and intentionally permissive. Enforcing strict schemas would limit flexibility.
When You Need Stricter Validation:
Use a markdown linter like markdownlint:
npm install -g markdownlint-cli
# Lint all markdown filesmarkdownlint '**/*.md' --ignore node_modulesCreate .markdownlint.json:
{ "MD013": { "line_length": 120 }, "MD033": false, "MD041": false}Cannot Migrate Files Modified Outside Standard Templates
Scenario: You created a custom file docs/core/INTEGRATION-TESTS.md in your project (not part of standard templates).
Problem: cortex-tms migrate doesn’t track or manage custom files.
Impact: If Cortex TMS later adds INTEGRATION-TESTS.md as a standard template, there’s no automatic merge—manual resolution required.
Best Practice: Prefix custom files with your project name or convention:
docs/core/MYPROJECT-INTEGRATION-TESTS.md (less likely to conflict)docs/project/ (separate from docs/core/)Backup Restore Overwrites All Files in Scope
Limitation: cortex-tms migrate --rollback restores the ENTIRE backup directory, not selective files.
Use Case: You want to restore only PATTERNS.md from a backup but keep other updated files.
Workaround (Manual Selective Restore):
# 1. List available backupsls -la .cortex/backups/
# 2. Navigate to backupcd .cortex/backups/2026-01-19_143022/
# 3. Manually copy specific filecp docs/core/PATTERNS.md ~/your-project/docs/core/PATTERNS.md
# 4. Verifycd ~/your-projectgit diff docs/core/PATTERNS.mdFuture Enhancement: Add --files flag for selective rollback:
cortex-tms migrate --rollback --files "PATTERNS.md,GLOSSARY.md"Large Projects Exceed Context Limits
Symptom: Claude Code or GitHub Copilot becomes slow or unresponsive in large codebases, even with Cortex TMS.
Cause: AI agents read not just TMS files but also source code, node_modules metadata, Git history, etc.
Metrics (typical context usage):
Mitigation Strategies:
Use .gitignore Aggressively:
# Reduce noise for AI agentsnode_modules/dist/build/coverage/.cache/.next/.DS_Store*.logExplicitly Prompt Tier Awareness:
Read NEXT-TASKS.md (HOT tier) first.Only read docs/core/ files if you need domain logic or patterns.NEVER read docs/archive/ unless explicitly asked.Use Focused Sessions:
# Good: Specific, bounded taskcortex-tms prompt feature"Implement user authentication following PATTERNS.md section 4"
# Bad: Open-ended, requires full codebase scan"Review the entire project and suggest improvements"Leverage Status Command:
# Generate concise summary for AIcortex-tms status
# Share output with AI instead of asking it to scan files"Here's the current status: [paste status output]"AI Agents Sometimes Miss Placeholders
Symptom: AI generates code referencing [Project Name] literally instead of replacing it with the actual project name.
Example:
// AI-generated code (incorrect)console.log('Welcome to [Project Name]');
// Expectedconsole.log('Welcome to My Todo App');Root Cause: Some LLMs interpret [Bracket Text] as markdown link syntax or code comments, not placeholders.
Best Practice in Templates:
<!-- ✅ Clear Placeholder -->**Project Name**: [Replace with your project name, e.g., "My Todo App"]
<!-- ❌ Ambiguous Placeholder -->**Project Name**: [Project Name]Mitigation: Use descriptive placeholders with examples:
[Your API base URL, e.g., https://api.example.com]Effective Prompts for AI Agents:
# 📊 GOOD: Explicit, Bounded, References TMS Files"Read NEXT-TASKS.md and docs/core/PATTERNS.md.Implement the authentication feature following Pattern 3 (JWT Auth).Use the task description in NEXT-TASKS.md line 23."
# ❌ BAD: Vague, No File References"Add authentication to the project."Template for Feature Implementation:
Context:- Current Sprint: [sprint name from NEXT-TASKS.md]- Architecture: [relevant section from ARCHITECTURE.md]- Patterns: [specific pattern from PATTERNS.md]
Task:[Detailed task description]
Constraints:- Follow existing patterns in PATTERNS.md- Update NEXT-TASKS.md when complete- Add tests following examples in src/__tests__/
Definition of Done:[Checklist from NEXT-TASKS.md]Issue: Projects with hundreds of archived files (e.g., 6 months of sprint retrospectives) may experience slow validation.
Current Behavior: cortex-tms validate scans all files in docs/archive/ to count them.
Impact:
Mitigation:
Compress Old Archives:
# Compress archives older than 3 monthstar -czf docs/archive-2025-Q4.tar.gz docs/archive/2025-10-* docs/archive/2025-11-* docs/archive/2025-12-*rm -rf docs/archive/2025-10-* docs/archive/2025-11-* docs/archive/2025-12-*Move to External Storage:
# Move to separate repo or S3 bucketaws s3 cp docs/archive/ s3://my-project-archives/ --recursiveDisable Archive Check (if really needed):
{ "validation": { "skipArchiveCheck": true }}Issue: Copying templates on cortex-tms init is slow on networked file systems (NFS, Samba).
Metrics:
Why: Multiple small file I/O operations are slow on network filesystems.
Mitigation:
# Copy templates to local cachemkdir -p ~/.cortex-cache/templatescp -r /path/to/cortex-tms/templates/* ~/.cortex-cache/templates/Risk: Accidentally committing sensitive data in placeholder fields.
Example:
Impact: If pushed to public GitHub, secrets are exposed.
Best Practice:
Use Generic Placeholder Examples:
**Database URL**: [e.g., postgres://user:password@localhost:5432/dbname]Add Pre-commit Hook (check for secrets):
# .github/pre-commit (using gitleaks)#!/bin/bashgitleaks detect --source . --no-git --verboseUse .env Files for Secrets:
**Database URL**: [Load from .env file, see .env.example]# .env.example (safe to commit)DATABASE_URL=postgres://user:password@localhost:5432/dbname
# .env (never commit, add to .gitignore)Risk: Backup directories (.cortex/backups/) may contain old versions of files with hardcoded secrets.
Scenario:
ARCHITECTURE.mdcortex-tms migrate --apply creates backup with old version containing keyMitigation:
Add to .gitignore:
# Cortex TMS backups (may contain sensitive data).cortex/backups/Audit Backups Before Committing:
# Search for potential secretsgrep -r "password\|secret\|api_key" .cortex/backups/Encrypted Backups (future enhancement):
cortex-tms migrate --apply --encrypt# Encrypts backups with GPG keyHard Requirement: Node.js 18.0.0 or higher
Why: Cortex TMS uses ES modules, which are stable in Node.js 18+.
Impact on Older Projects:
If your project uses Node.js 16 or 14:
Option 1: Upgrade Node.js:
nvm install 18nvm use 18Option 2: Use npx with Specific Node Version:
npx -p node@18 -c 'cortex-tms init'Option 3: Docker:
FROM node:18-alpineWORKDIR /appRUN npm install -g cortex-tmsCMD ["cortex-tms", "validate"]Tested With:
Known Issues:
Yarn 2+ (Berry):
nodeLinker: node-modules in .yarnrc.yml:
nodeLinker: node-modulesnpm < 7:
--legacy-peer-deps:
npm install -g cortex-tms --legacy-peer-depsCortex TMS Uses: TypeScript 5.7.3
Potential Conflict: Your project uses TypeScript 4.x or different 5.x minor version.
Impact: Type definitions may be incompatible if you import Cortex TMS types directly (rare).
Mitigation:
Don’t Import Cortex TMS Types (recommended):
Version Pinning:
{ "devDependencies": { "typescript": "5.7.3" }}Limitation: The CLI doesn’t provide interactive tutorials or code playgrounds.
Use Case: New users want to try Cortex TMS commands without affecting their projects.
Workaround (Sandbox Environment):
# Create temporary test directorymkdir /tmp/cortex-sandboxcd /tmp/cortex-sandbox
# Initialize TMSnpx cortex-tms init --scope standard
# Experiment freelycortex-tms statuscortex-tms validate --verbosecortex-tms migrate
# Clean up when donecd ~rm -rf /tmp/cortex-sandboxFuture Enhancement: cortex-tms demo command that creates a pre-configured sandbox.
Current State: Documentation is text-based only (markdown, code examples).
Gap: Visual learners may prefer video walkthroughs.
Community Contribution Opportunity:
Template for Video Tutorials:
To set expectations, here are features explicitly not planned:
Why These Decisions:
Last Updated: January 19, 2026 (for Cortex TMS v2.6.0) Maintained By: Cortex TMS Contributors Feedback: Open an issue or submit a PR to improve this page