{"id":45260449,"url":"https://github.com/cortex-tms/cortex-tms","last_synced_at":"2026-02-21T12:01:25.976Z","repository":{"id":332133421,"uuid":"1132006405","full_name":"cortex-tms/cortex-tms","owner":"cortex-tms","description":"The Universal AI-Optimized Project Boilerplate. A Tiered Memory System (TMS) designed to maximize AI agent performance. Includes an interactive CLI tool and a high-signal documentation standard.","archived":false,"fork":false,"pushed_at":"2026-02-02T23:24:19.000Z","size":4774,"stargazers_count":150,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-02T23:31:39.536Z","etag":null,"topics":["ai","anthropic","architecture","best-practices","claude-code","cli","code-generation","cursor","developer-experience","developer-tools","devtools","documentation","github-copilot","governance","llm","project-scaffolding","task-management","typescipt","version-control","workflow-automation"],"latest_commit_sha":null,"homepage":"https://cortex-tms.org/","language":"MDX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cortex-tms.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T05:54:18.000Z","updated_at":"2026-02-02T19:09:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cortex-tms/cortex-tms","commit_stats":null,"previous_names":["jantonca/cortex-tms","cortex-tms/cortex-tms"],"tags_count":12,"template":true,"template_full_name":null,"purl":"pkg:github/cortex-tms/cortex-tms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cortex-tms%2Fcortex-tms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cortex-tms%2Fcortex-tms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cortex-tms%2Fcortex-tms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cortex-tms%2Fcortex-tms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cortex-tms","download_url":"https://codeload.github.com/cortex-tms/cortex-tms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cortex-tms%2Fcortex-tms/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29680147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T11:29:27.227Z","status":"ssl_error","status_checked_at":"2026-02-21T11:29:20.292Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","architecture","best-practices","claude-code","cli","code-generation","cursor","developer-experience","developer-tools","devtools","documentation","github-copilot","governance","llm","project-scaffolding","task-management","typescipt","version-control","workflow-automation"],"created_at":"2026-02-21T00:00:41.393Z","updated_at":"2026-02-21T12:01:25.956Z","avatar_url":"https://github.com/cortex-tms.png","language":"MDX","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"website/public/logo.svg\" alt=\"Cortex TMS Logo\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCortex TMS\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDocumentation Governance for AI Coding Agents\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  ⭐ 166+ GitHub Stars | Open source, community-driven\n\u003c/p\u003e\n\n[![npm version](https://img.shields.io/npm/v/cortex-tms.svg?style=flat-square)](https://www.npmjs.com/package/cortex-tms)\n[![npm downloads](https://img.shields.io/npm/dm/cortex-tms.svg?style=flat-square)](https://www.npmjs.com/package/cortex-tms)\n[![license](https://img.shields.io/npm/l/cortex-tms.svg?style=flat-square)](https://github.com/cortex-tms/cortex-tms/blob/main/LICENSE)\n[![node version](https://img.shields.io/node/v/cortex-tms.svg?style=flat-square)](https://nodejs.org)\n[![GitHub stars](https://img.shields.io/github/stars/cortex-tms/cortex-tms.svg?style=flat-square)](https://github.com/cortex-tms/cortex-tms/stargazers)\n\n---\n\n## What is Cortex TMS?\n\nCortex TMS scaffolds and validates governance documentation for AI coding agents. As AI models get more powerful and autonomous, they need clear, current governance docs to stay aligned with your project standards.\n\n**The Challenge**: Modern AI agents (Claude Opus 4.6, GPT-4, etc.) handle large context windows and can work autonomously—but without governance, they drift from your standards, overengineer solutions, and write inconsistent code.\n\n**The Solution**: Cortex TMS provides:\n- 📋 **Documentation scaffolding** - Templates for PATTERNS.md, ARCHITECTURE.md, CLAUDE.md\n- ✅ **Staleness detection** - Detects when governance docs go stale relative to code changes (v4.0)\n- 🔍 **Structure validation** - Automated health checks in CI or locally\n- 📦 **Archive management** - Keep task lists focused and maintainable\n\n---\n\n## Three Pillars\n\n### 1. 📋 Consistency - Document Your Standards\n\nScaffold governance docs that AI agents actually read:\n- `PATTERNS.md` - Code patterns and conventions\n- `CLAUDE.md` - Agent workflow rules (git protocol, scope discipline, human approval gates)\n- `ARCHITECTURE.md` - System design and tech stack\n- `DOMAIN-LOGIC.md` - Business rules and constraints\n\n**Result**: AI writes code that follows YOUR patterns, not random conventions from its training data.\n\n### 2. 🔍 Freshness - Detect Staleness\n\nNew in v4.0: Git-based staleness detection catches when docs go stale:\n\n```bash\ncortex-tms validate\n\n⚠️  Doc Staleness\n    PATTERNS.md may be outdated\n    Doc is 45 days older than code with 12 meaningful commits\n    Code: 2026-02-20\n    Doc:  2026-01-06\n\n    Review docs/core/PATTERNS.md to ensure it reflects current codebase\n```\n\n**How it works**: Compares doc modification dates vs code commit activity. Flags stale docs before they mislead AI agents.\n\n**Note**: Staleness v1 uses git timestamps (temporal comparison only). Cannot detect semantic misalignment. Future versions will add semantic analysis.\n\n### 3. 🛡️ Safety - Human Oversight\n\n`CLAUDE.md` governance rules require human approval for critical operations:\n- Git commits/pushes require approval\n- Scope discipline prevents overengineering\n- Pattern adherence enforced through validation\n\n**Result**: AI agents stay powerful but don't run wild.\n\n---\n\n## What Cortex Does (and Doesn't Do)\n\n### ✅ What Cortex Does\n\n- **Scaffolds governance docs** - Templates for common project documentation\n- **Validates doc health** - Checks structure, freshness, completeness\n- **Detects staleness** - Flags when docs are outdated relative to code (v4.0)\n- **Enforces size limits** - Keeps docs focused and scannable\n- **Archives completed tasks** - Maintains clean NEXT-TASKS.md\n- **Works in CI/CD** - GitHub Actions validation templates included\n\n### ❌ What Cortex Does NOT Do\n\n- **Not a token optimizer** - Modern models (200K+ contexts) make this less relevant\n- **Not code enforcement** - Validates DOCUMENTATION health, not code directly\n- **Not a replacement for code review** - Complements human review, doesn't replace it\n- **Not semantic analysis (yet)** - Staleness v1 uses timestamps, not AI-powered diff analysis\n\n---\n\n## Quick Start\n\n```bash\n# Initialize governance docs in your project\nnpx cortex-tms@latest init\n\n# Validate doc health (including staleness detection)\nnpx cortex-tms@latest validate\n\n# Strict mode (warnings = errors, for CI)\nnpx cortex-tms@latest validate --strict\n\n# Check project status\nnpx cortex-tms@latest status\n\n# Archive completed tasks\nnpx cortex-tms@latest archive --dry-run\n```\n\n**Installation**: No installation required with `npx`. For frequent use: `npm install -g cortex-tms@latest`\n\n---\n\n## CLI Commands\n\n### `cortex-tms init`\n\nScaffold TMS documentation structure with interactive scope selection.\n\n```bash\ncortex-tms init                    # Interactive mode\ncortex-tms init --scope standard   # Non-interactive\ncortex-tms init --dry-run          # Preview changes\n```\n\n### `cortex-tms validate`\n\nVerify project TMS health with automated checks.\n\n```bash\ncortex-tms validate         # Check project health\ncortex-tms validate --fix   # Auto-repair missing files\ncortex-tms validate --strict # Strict mode (warnings = errors)\n```\n\n**What it checks:**\n- ✅ Mandatory files exist (NEXT-TASKS.md, CLAUDE.md, copilot-instructions.md)\n- ✅ File size limits (Rule 4: HOT files \u003c 200 lines)\n- ✅ Placeholder completion (no `[Project Name]` markers left)\n- ✅ Archive status (completed tasks should be archived)\n- ✅ **Doc staleness** (NEW in v4.0) - governance docs current with code\n\n### `cortex-tms status`\n\nProject cockpit with health dashboard and sprint progress.\n\n```bash\ncortex-tms status  # Visual dashboard with progress bars\n```\n\nShows:\n- Project identity (name, scope, TMS version)\n- Health status (validation checks passed/failed)\n- Sprint progress (current tasks, completion %)\n- Backlog size (future enhancements)\n\n### `cortex-tms archive`\n\nArchive completed tasks and old content.\n\n```bash\ncortex-tms archive           # Archive completed tasks\ncortex-tms archive --dry-run # Preview what would be archived\n```\n\nArchives completed tasks from NEXT-TASKS.md to `docs/archive/` with timestamp.\n\n**Note**: `cortex-tms auto-tier` is deprecated—use `archive` instead.\n\n### `cortex-tms migrate`\n\nIntelligent version management—detect outdated templates and upgrade safely.\n\n```bash\ncortex-tms migrate                    # Analyze version status\ncortex-tms migrate --apply            # Auto-upgrade OUTDATED files\ncortex-tms migrate --rollback         # Restore from backup\n```\n\n### `cortex-tms prompt`\n\nAccess project-aware AI prompts from the Essential 7 library.\n\n```bash\ncortex-tms prompt              # Interactive selection\ncortex-tms prompt init-session # Auto-copies to clipboard\n```\n\n### `cortex-tms review` 🛡️\n\nGuardian: AI-powered semantic validation against project patterns.\n\n```bash\ncortex-tms review src/index.ts              # Validate against PATTERNS.md\ncortex-tms review src/index.ts --safe       # High-confidence violations only\n```\n\n### `cortex-tms tutorial`\n\nInteractive walkthrough teaching the Cortex Way.\n\n```bash\ncortex-tms tutorial  # 5-lesson guided tour (~15 minutes)\n```\n\n---\n\n## Documentation Structure\n\n| Folder / File                     | Purpose                                | Tier                      |\n| :-------------------------------- | :------------------------------------- | :------------------------ |\n| `NEXT-TASKS.md`                   | Active sprint and current focus        | **HOT** (Always Read)     |\n| `PROMPTS.md`                      | AI interaction templates (Essential 7) | **HOT** (Always Read)     |\n| `CLAUDE.md`                       | CLI commands \u0026 workflow config         | **HOT** (Always Read)     |\n| `.github/copilot-instructions.md` | Global guardrails and critical rules   | **HOT** (Always Read)     |\n| `FUTURE-ENHANCEMENTS.md`          | Living backlog (not current sprint)    | **PLANNING**              |\n| `docs/core/ARCHITECTURE.md`       | System design \u0026 tech stack             | **WARM** (Read on Demand) |\n| `docs/core/PATTERNS.md`           | Canonical code examples (Do/Don't)     | **WARM** (Read on Demand) |\n| `docs/core/DOMAIN-LOGIC.md`       | Immutable project rules                | **WARM** (Read on Demand) |\n| `docs/core/GIT-STANDARDS.md`      | Git \u0026 PM conventions                   | **WARM** (Read on Demand) |\n| `docs/core/DECISIONS.md`          | Architecture Decision Records          | **WARM** (Read on Demand) |\n| `docs/core/GLOSSARY.md`           | Project terminology                    | **WARM** (Read on Demand) |\n| `docs/archive/`                   | Historical changelogs                  | **COLD** (Ignore)         |\n\n**HOT/WARM/COLD System**: Organizes docs by access frequency (not token optimization). Helps AI find what's relevant for each task.\n\n---\n\n## Staleness Detection Configuration\n\nConfigure staleness thresholds in `.cortexrc`:\n\n```json\n{\n  \"version\": \"4.0.0\",\n  \"scope\": \"standard\",\n  \"staleness\": {\n    \"enabled\": true,\n    \"thresholdDays\": 30,\n    \"minCommits\": 3,\n    \"docs\": {\n      \"docs/core/PATTERNS.md\": [\"src/\"],\n      \"docs/core/ARCHITECTURE.md\": [\"src/\", \"infrastructure/\"],\n      \"docs/core/DOMAIN-LOGIC.md\": [\"src/\"]\n    }\n  }\n}\n```\n\n**How it works**:\n- Compares doc last modified date vs code commit activity\n- Flags stale if: `daysSinceDocUpdate \u003e thresholdDays AND meaningfulCommits \u003e= minCommits`\n- Excludes merge commits, test-only changes, lockfile-only changes\n\n**Limitations (v1)**:\n- Temporal comparison only (git timestamps)\n- Cannot detect semantic misalignment\n- Requires full git history (not shallow clones)\n\n**CI Setup**: Ensure `fetch-depth: 0` in GitHub Actions to enable staleness detection.\n\n---\n\n## CI/CD Integration\n\nAdd to `.github/workflows/validate.yml`:\n\n```yaml\nname: Cortex TMS Validation\n\non: [push, pull_request]\n\njobs:\n  validate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0  # Required for staleness detection\n\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n\n      - name: Validate TMS Health\n        run: npx cortex-tms@latest validate --strict\n```\n\n**Strict mode**: Warnings become errors, failing the build if:\n- Governance docs are stale\n- File size limits exceeded\n- Mandatory files missing\n- Placeholders not replaced\n\n---\n\n## What's New in v4.0\n\n**🎯 Strategic Repositioning**: Quality governance over token optimization\n\n**Context**: Modern AI models (GPT-4, Claude Opus 4.6) now handle large contexts (200K+ tokens). The bottleneck shifted from \"can AI see enough?\" to \"will AI stay aligned with project standards?\"\n\n### New Features\n\n**Staleness Detection** (v4.0):\n- ✅ Git-based freshness checks for governance docs\n- ✅ Configurable thresholds (days + commit count)\n- ✅ Per-doc watch directories\n- ✅ Exclude merges, test-only, lockfile-only commits\n- ✅ CI-ready (with `fetch-depth: 0`)\n\n**Archive Command**:\n- ✅ `cortex-tms archive` - Archive completed tasks\n- ✅ Replaces deprecated `auto-tier` command\n- ✅ Dry-run mode for previewing changes\n\n**Simplified Status**:\n- ✅ Removed `--tokens` flag (streamlined to governance focus)\n- ✅ Shows: project health, sprint progress, backlog\n\n### Breaking Changes\n\n**Removed**:\n- ❌ `cortex-tms status --tokens` flag\n- ❌ Token counting and cost analysis features\n\n**Deprecated**:\n- ⚠️ `cortex-tms auto-tier` → Use `cortex-tms archive` (still works with warning)\n\n**Migration**:\n- Status command: Use `cortex-tms status` (no flags needed)\n- Archive tasks: Use `cortex-tms archive` instead of `auto-tier`\n\nSee [CHANGELOG.md](CHANGELOG.md) for full version history.\n\n---\n\n## When to Use Cortex TMS\n\n### ✅ Good Fit\n\n- **Multi-file projects** - Complex codebases with established patterns\n- **Team projects** - Multiple developers + AI agents need consistency\n- **Long-running projects** - Documentation drift is a real risk\n- **AI-heavy workflows** - Using Claude Code, Cursor, Copilot extensively\n- **Quality-focused** - You value consistent code over speed\n\n### ⚠️ Maybe Not\n\n- **Single-file projects** - Overhead may outweigh benefits\n- **Throwaway prototypes** - Documentation governance not worth setup time\n- **Solo dev, simple project** - Mental model may be sufficient\n- **Pure exploration** - Constraints may slow discovery\n\n**Start simple**: Use `--scope nano` for minimal setup, expand as needed.\n\n---\n\n## Developer Experience\n\n- **Instant Setup**: `npx cortex-tms init` - 60 seconds to governance docs\n- **Zero Config**: Works out of the box with sensible defaults\n- **CI Ready**: GitHub Actions templates included\n- **Production Grade**: 316 tests (97% pass rate), enterprise-grade security (v3.2)\n- **Open Source**: MIT license, community-driven\n\n**Tested With**: Claude Code, GitHub Copilot (in VS Code). Architecture supports any AI tool.\n\n---\n\n## Community \u0026 Support\n\n### Get Help\n\n- **[GitHub Discussions](https://github.com/cortex-tms/cortex-tms/discussions)** - Ask questions, share ideas\n  - [Q\u0026A](https://github.com/cortex-tms/cortex-tms/discussions/categories/q-a) - Get help from community\n  - [Ideas](https://github.com/cortex-tms/cortex-tms/discussions/categories/ideas) - Suggest features\n  - [Show and Tell](https://github.com/cortex-tms/cortex-tms/discussions/categories/show-and-tell) - Share projects\n\n### Report Issues\n\n- **[Bug Reports](https://github.com/cortex-tms/cortex-tms/issues/new)** - Found a bug? Let us know\n- **[Security Issues](https://github.com/cortex-tms/cortex-tms/security/advisories/new)** - Responsible disclosure\n\n### Contributing\n\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute\n- **[Community Guide](docs/COMMUNITY.md)** - Community guidelines\n\n**Star us on GitHub** ⭐ if Cortex TMS helps your AI development workflow!\n\n---\n\n## Roadmap\n\n**v4.0** (Current - Feb 2026):\n- ✅ Staleness detection (git-based, v1)\n- ✅ Archive command\n- ✅ Validation-first positioning\n- ✅ Token claims removed\n\n**v4.1** (Planned - Mar 2026):\n- 🔄 Git hooks integration (`cortex-tms hooks install`)\n- 🔄 Staleness v2 (improved heuristics, fewer false positives)\n- 🔄 Incremental doc updates\n\n**v4.2+** (Future):\n- 📋 MCP Server (expose docs to any AI tool)\n- 📋 Multi-tool config generation (.cursorrules, .windsurfrules)\n- 📋 Skills integration\n\nSee [FUTURE-ENHANCEMENTS.md](FUTURE-ENHANCEMENTS.md) for full roadmap.\n\n---\n\n## License\n\nMIT - See [LICENSE](LICENSE) for details\n\n---\n\n## Status\n\n**Version**: 4.0.0 (In Development)\n**Last Updated**: 2026-02-21\n**Current Sprint**: v4.0 - \"Quality Governance \u0026 Staleness Detection\"\n\n\u003c!-- @cortex-tms-version 4.0.0 --\u003e\n","funding_links":[],"categories":["MDX"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcortex-tms%2Fcortex-tms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcortex-tms%2Fcortex-tms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcortex-tms%2Fcortex-tms/lists"}