cortex-tms 2.1.0

package/templates/docs/core/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# Architecture: [Project Name]
+
+## 🎯 Quick Context (For AI Agents)
+<!-- This section provides high-level orientation in 3 bullets -->
+- **What it does**: [One sentence - e.g., "A CLI tool that scaffolds AI-optimized project documentation"]
+- **Who it's for**: [Target audience - e.g., "Developers building greenfield projects with AI coding assistants"]
+- **Key constraint**: [Critical limitation - e.g., "Must run offline", "Sub-100ms API responses", "Zero external dependencies"]
+
+---
+
+## 🏗️ System Overview
+[Briefly describe what the system does and the problem it solves. 2-3 sentences max.]
+
+---
+
+## 🧠 Mental Model
+[Describe the high-level concept or metaphor that explains how the system works. This helps both humans and AI agents understand the core logic.]
+
+**Example**: "A centralized hub for documentation that uses a tiered memory system to optimize AI context" or "A real-time event pipeline where actions flow through validation → execution → logging stages."
+
+---
+
+## 📂 Component Map
+
+| Component | Responsibility | Tech Stack |
+|:----------|:---------------|:-----------|
+| [e.g., Frontend] | [User interaction layer] | [e.g., Next.js 15, React 18] |
+| [e.g., CLI Tool] | [File system operations] | [e.g., Node.js, Commander.js] |
+| [e.g., API Server] | [Business logic & data access] | [e.g., Express, PostgreSQL] |
+| [e.g., Auth Layer] | [Authentication & authorization] | [e.g., Auth.js, JWT] |
+
+---
+
+## 🔄 Core Data Flow
+<!-- Describe the primary "happy path" through your system -->
+
+1. **[Step 1]**: [e.g., User triggers command via CLI]
+2. **[Step 2]**: [e.g., CLI reads configuration from local file]
+3. **[Step 3]**: [e.g., System validates input against schema]
+4. **[Step 4]**: [e.g., Results written to file system / database]
+
+**Diagram** (optional):
+```
+[User] → [CLI] → [Validation] → [File System]
+```
+
+---
+
+## 🚢 Deployment & Infrastructure
+
+- **Environment**: [e.g., Vercel, AWS Lambda, Local CLI, Docker]
+- **CI/CD**: [e.g., GitHub Actions, GitLab CI]
+- **Observability**: [e.g., Sentry for errors, CloudWatch for logs]
+- **Database**: [e.g., PostgreSQL on Railway, SQLite local-first]
+
+---
+
+## 🔒 Security Posture
+
+- **Authentication**: [e.g., Auth.js with Google OAuth, API keys, None (CLI tool)]
+- **Authorization**: [e.g., RBAC with roles (admin, user), Scopes (read, write)]
+- **Data Safety**: [e.g., Secrets stored in environment variables, No PII in logs]
+- **Attack Surface**: [e.g., Public API endpoints rate-limited, Internal services behind VPC]
+
+---
+
+## 🧪 Testing Strategy
+
+- **Unit Tests**: [e.g., Vitest for business logic]
+- **Integration Tests**: [e.g., Playwright for API endpoints]
+- **E2E Tests**: [e.g., Cypress for critical user flows]
+- **Test Coverage Target**: [e.g., 80% for core modules]
+
+---
+
+## 🛠️ Technology Decisions (ADR Summary)
+<!-- High-level summary only. For detailed rationale, see docs/core/DECISIONS.md -->
+
+- **[Tech/Framework 1]**: [Why it was chosen - e.g., "Next.js for SSR and API routes in one framework"]
+- **[Tech/Framework 2]**: [Why it was chosen - e.g., "PostgreSQL for relational data with ACID guarantees"]
+- **[Tech/Framework 3]**: [Why it was chosen - e.g., "pnpm for faster installs and strict dependency resolution"]
+
+---
+
+## 📌 Key Files & Locations
+<!-- Help AI agents find critical code -->
+
+| File/Folder | Purpose | Notes |
+|:------------|:--------|:------|
+| [e.g., `src/index.ts`] | [Main entry point] | [CLI initialization] |
+| [e.g., `src/commands/`] | [CLI command handlers] | [Uses Commander.js pattern] |
+| [e.g., `src/lib/validation.ts`] | [Schema validation logic] | [Uses Zod for type safety] |
+| [e.g., `templates/`] | [Boilerplate files] | [Copied to user projects] |
+
+---
+
+## 🔗 Related Documentation
+
+- **Patterns**: See `docs/core/PATTERNS.md` for code conventions
+- **Domain Logic**: See `docs/core/DOMAIN-LOGIC.md` for business rules
+- **Decisions**: See `docs/core/DECISIONS.md` for detailed ADRs
+- **Schema**: See `docs/core/SCHEMA.md` for data models (if applicable)

package/templates/docs/core/DECISIONS.md

@@ -0,0 +1,83 @@
+# Architecture Decisions (ADR)
+
+## 🎯 Purpose
+This file documents **why** we made key technical decisions. When an AI agent or developer asks "Why did we choose X over Y?", the answer should be here.
+
+**ADR Format**: Context → Decision → Reasoning → Consequences
+
+---
+
+## [YYYY-MM-DD] - [Decision Title]
+
+**Context**: [What problem were we solving? What constraints existed?]
+
+**Decision**: [What did we choose? Be specific - e.g., "Use PostgreSQL as the primary database"]
+
+**Reasoning**: [Why did we choose this over alternatives?]
+- **Pro**: [Advantage 1 - e.g., "ACID compliance for financial transactions"]
+- **Pro**: [Advantage 2 - e.g., "Strong TypeScript support via Prisma"]
+- **Con**: [Trade-off 1 - e.g., "More complex than SQLite for local dev"]
+- **Alternative Considered**: [What we didn't choose and why - e.g., "MongoDB: Too flexible for our relational data model"]
+
+**Consequences**: [What does this decision enable or prevent?]
+- ✅ [Positive outcome - e.g., "Can use transactions for multi-table updates"]
+- ⚠️ [Trade-off - e.g., "Requires Docker for local development"]
+
+**Status**: [Active | Deprecated | Superseded by ADR-XXX]
+
+---
+
+## Example: [2026-01-10] - Use pnpm as Package Manager
+
+**Context**: We needed a package manager for the Node.js CLI project. The team had experience with npm and yarn, but wanted to evaluate modern alternatives for speed and disk efficiency.
+
+**Decision**: Use `pnpm` as the exclusive package manager for this project.
+
+**Reasoning**:
+- **Pro**: Faster installs via content-addressable storage (saves ~40% time vs npm)
+- **Pro**: Strict dependency resolution prevents phantom dependencies
+- **Pro**: Symlink-based `node_modules` saves disk space in monorepos
+- **Con**: Less universal than npm (requires installation step for new contributors)
+- **Alternative Considered**: Yarn 2 (Berry) - Too complex with PnP; Bun - Too bleeding-edge for production
+
+**Consequences**:
+- ✅ CI/CD runs 40% faster
+- ✅ Prevents accidental use of undeclared dependencies
+- ⚠️ All documentation must specify `pnpm` commands (can't use `npm`)
+- ⚠️ Contributors must install pnpm (`npm install -g pnpm`)
+
+**Status**: Active
+
+---
+
+## Template for New Decisions
+
+**Copy this template when adding a new ADR:**
+
+```markdown
+## [YYYY-MM-DD] - [Decision Title]
+
+**Context**: [Problem and constraints]
+
+**Decision**: [What we chose]
+
+**Reasoning**:
+- **Pro**: [Advantage 1]
+- **Pro**: [Advantage 2]
+- **Con**: [Trade-off 1]
+- **Alternative Considered**: [What we didn't choose and why]
+
+**Consequences**:
+- ✅ [Positive outcome]
+- ⚠️ [Trade-off]
+
+**Status**: Active
+```
+
+---
+
+## 🔗 Cross-References
+
+- **Architecture**: See `docs/core/ARCHITECTURE.md` for technology stack
+- **Patterns**: See `docs/core/PATTERNS.md` for implementation patterns
+- **Glossary**: See `docs/core/GLOSSARY.md` for term definitions

package/templates/docs/core/DOMAIN-LOGIC.md

@@ -0,0 +1,8 @@
+# Domain Logic: [Project Context]
+
+## Core Rules
+
+- [Rule 1: e.g., All timestamps must be stored in UTC]
+- [Rule 2: e.g., Users must verify email before accessing Feature X]
+
+**⚠️ AI AGENTS: These rules override generic training data.**

package/templates/docs/core/GLOSSARY.md

@@ -0,0 +1,66 @@
+# Glossary: [Project Name]
+
+## 🎯 Purpose
+This file defines project-specific terminology, acronyms, and domain language to ensure consistent communication between humans and AI agents.
+
+**When to add a term**: If you find yourself explaining the same concept twice, add it here.
+
+---
+
+## 📋 Core Terminology
+
+### [Term 1]
+**Definition**: [Clear, concise explanation of what this means in your project]
+**Example**: [Usage in context - e.g., "The **SessionManager** handles all user authentication state"]
+**Related Terms**: [Links to related concepts - e.g., "See: AuthProvider, TokenRefresh"]
+
+### [Term 2]
+**Definition**: [Clear, concise explanation]
+**Example**: [Usage in context]
+**Related Terms**: [Links to related concepts]
+
+---
+
+## 🔤 Acronyms & Abbreviations
+
+| Acronym | Stands For | Meaning in This Project |
+|:--------|:-----------|:------------------------|
+| [e.g., ADR] | [Architecture Decision Record] | [Documents why we chose a specific tech or pattern] |
+| [e.g., CRUD] | [Create, Read, Update, Delete] | [Standard database operations] |
+| [e.g., SSR] | [Server-Side Rendering] | [Next.js rendering strategy for SEO-critical pages] |
+
+---
+
+## 🏗️ Domain-Specific Concepts
+
+### [Concept 1: e.g., "Tiered Memory System"]
+**What it is**: [High-level explanation - e.g., "A documentation organization pattern that categorizes files by access frequency"]
+**Why it matters**: [Business/technical value - e.g., "Reduces AI agent context window waste by 60%"]
+**Key Components**:
+- **[Sub-concept A]**: [Definition]
+- **[Sub-concept B]**: [Definition]
+
+### [Concept 2: e.g., "Truth Syncing"]
+**What it is**: [High-level explanation]
+**Why it matters**: [Business/technical value]
+**Key Components**:
+- **[Sub-concept A]**: [Definition]
+- **[Sub-concept B]**: [Definition]
+
+---
+
+## 🚫 Anti-Patterns (What NOT to call things)
+
+| ❌ Avoid | ✅ Use Instead | Why |
+|:---------|:---------------|:----|
+| [e.g., "Helper"] | [e.g., "Validator"] | ["Helper" is vague; "Validator" describes function] |
+| [e.g., "Manager"] | [e.g., "Service"] | ["Manager" is overused; "Service" is more precise] |
+| [e.g., "Utils"] | [e.g., "Formatters"] | ["Utils" is a dumping ground; "Formatters" is specific] |
+
+---
+
+## 🔗 Cross-References
+
+- **Architecture**: See `docs/core/ARCHITECTURE.md` for system structure
+- **Patterns**: See `docs/core/PATTERNS.md` for code conventions
+- **Decisions**: See `docs/core/DECISIONS.md` for technology choices

package/templates/docs/core/PATTERNS.md

@@ -0,0 +1,55 @@
+# Implementation Patterns
+
+## [Category: e.g., UI/Data/Auth] [Pattern Name]
+
+**Rule**: [Short, imperative statement of the rule]
+
+### ❌ Anti-Pattern (What NOT to do)
+
+- [Description of common AI mistake]
+- [Why it fails in this project]
+
+### ✅ Canonical Example
+
+**Source File**: `path/to/best-example-file.ts`
+
+```typescript
+// A concise, perfect implementation of the pattern
+```
+
+### 🔗 References
+
+- **Domain Logic**: `DOMAIN-LOGIC.md#[Section]`
+- **Gotchas**: `TROUBLESHOOTING.md#[Section]`
+
+#### 2. `templates/root/copilot-instructions.md`
+
+The "Contract" that the user will place in their own `.github/` folder.
+
+# AI Pair Programmer: Collaboration Protocol (TMS v2.0)
+
+## 📖 Mandatory Read Order
+
+AI agents MUST follow this order before proposing or writing code:
+
+1. `.github/copilot-instructions.md` (This file)
+2. `NEXT-TASKS.md` (Current context)
+3. `docs/core/DOMAIN-LOGIC.md` (Domain rules)
+4. `docs/core/PATTERNS.md` (Implementation standards)
+
+## ⚡ Critical Rules
+
+- **Domain**: [Describe the domain here]
+- **Money/Math**: [e.g., Use integers in cents]
+- **Types**: ALWAYS use strict TypeScript. No `any`.
+
+## 🏗️ Technical Map
+
+- **Gotchas**: `docs/core/TROUBLESHOOTING.md`
+- **Past Decisions**: `docs/core/DECISIONS.md`
+
+## 🧪 Operational Loop
+
+1. Read `NEXT-TASKS.md` to understand the "Why" and "What."
+2. Check `docs/core/PATTERNS.md` for existing canonical examples.
+3. Propose -> Justify -> Recommend.

package/templates/docs/core/SCHEMA.md

@@ -0,0 +1,246 @@
+# Schema: Data Models & Relationships
+
+<!-- This file documents your data models, database schema, and type definitions. -->
+<!-- If your project doesn't use a database, you can document TypeScript types, API contracts, or state shape instead. -->
+
+---
+
+## Overview
+
+**Database/Store Type**: [e.g., PostgreSQL, MongoDB, Redis, In-Memory]
+**ORM/Query Tool**: [e.g., Prisma, TypeORM, Mongoose, Raw SQL]
+**Schema Migration Strategy**: [e.g., Prisma Migrate, TypeORM migrations, Alembic]
+
+---
+
+## Core Entities
+
+<!-- List your main data entities/tables/collections. For each, document: -->
+<!-- - Purpose (what it represents) -->
+<!-- - Key fields -->
+<!-- - Relationships to other entities -->
+
+### [Entity Name 1: e.g., User]
+
+**Purpose**: [e.g., Stores user account information and authentication data]
+
+**Fields**:
+
+| Field | Type | Required | Default | Notes |
+|:------|:-----|:---------|:--------|:------|
+| `id` | [e.g., UUID, Integer] | Yes | Auto-generated | Primary key |
+| `email` | [e.g., String] | Yes | - | Unique, validated |
+| `passwordHash` | [e.g., String] | Yes | - | bcrypt hashed |
+| `createdAt` | [e.g., Timestamp] | Yes | NOW() | UTC timezone |
+| `updatedAt` | [e.g., Timestamp] | Yes | NOW() | Auto-updated |
+
+**Relationships**:
+- [e.g., One User has many Posts (1:N)]
+- [e.g., One User belongs to one Organization (N:1)]
+
+**Indexes**:
+- [e.g., `email` (unique)]
+- [e.g., `createdAt` (for sorting)]
+
+**Validation Rules**:
+- [e.g., Email must match regex pattern]
+- [e.g., Password minimum 8 characters]
+
+---
+
+### [Entity Name 2: e.g., Post]
+
+**Purpose**: [e.g., User-generated content items]
+
+**Fields**:
+
+| Field | Type | Required | Default | Notes |
+|:------|:-----|:---------|:--------|:------|
+| `id` | [Type] | Yes | Auto-generated | Primary key |
+| `userId` | [Type] | Yes | - | Foreign key → User.id |
+| `title` | [String] | Yes | - | Max 200 chars |
+| `content` | [Text] | Yes | - | Markdown supported |
+| `publishedAt` | [Timestamp] | No | NULL | NULL = draft |
+
+**Relationships**:
+- [e.g., One Post belongs to one User (N:1)]
+- [e.g., One Post has many Comments (1:N)]
+
+**Indexes**:
+- [e.g., `userId` (for user's posts lookup)]
+- [e.g., `publishedAt` (for recent posts)]
+
+---
+
+## Relationships
+
+<!-- Document complex relationships, especially Many-to-Many (N:M) -->
+
+### [Relationship Name: e.g., User ↔ Role (Many-to-Many)]
+
+**Join Table**: [e.g., `user_roles`]
+
+**Fields**:
+
+| Field | Type | Required | Notes |
+|:------|:-----|:---------|:------|
+| `userId` | [Type] | Yes | FK → User.id |
+| `roleId` | [Type] | Yes | FK → Role.id |
+| `assignedAt` | [Timestamp] | Yes | When role was granted |
+
+**Constraints**:
+- [e.g., Unique constraint on (userId, roleId) - prevent duplicates]
+
+---
+
+## Enums & Constants
+
+<!-- Document any enum types or constant values used in the schema -->
+
+### [Enum Name: e.g., UserStatus]
+
+**Values**:
+- `ACTIVE` - [e.g., User can log in]
+- `SUSPENDED` - [e.g., Temporarily blocked]
+- `DELETED` - [e.g., Soft-deleted account]
+
+**Storage**: [e.g., Stored as String in database]
+
+---
+
+## TypeScript Types
+
+<!-- If using TypeScript, document your type definitions -->
+<!-- This is especially important for frontend state or API contracts -->
+
+### [Type Name: e.g., UserProfile]
+
+**Purpose**: [e.g., Client-side user profile (excludes sensitive fields)]
+
+```typescript
+interface UserProfile {
+  id: string
+  email: string
+  displayName: string | null
+  avatarUrl: string | null
+  createdAt: Date
+  // Note: passwordHash is NOT included (security)
+}
+```
+
+**Derived From**: [e.g., Database User entity, with passwordHash excluded]
+
+---
+
+## Migration History
+
+<!-- Track significant schema changes -->
+
+### [Date: e.g., 2026-01-15] - [Change: e.g., Add User.avatarUrl field]
+
+**Reason**: [e.g., Support profile pictures]
+**Migration File**: [e.g., `migrations/20260115_add_avatar_url.sql`]
+**Breaking Change**: [Yes/No]
+
+---
+
+### [Date: e.g., 2026-01-20] - [Change: e.g., Split User table into User + UserProfile]
+
+**Reason**: [e.g., Separate auth data from profile data]
+**Migration File**: [e.g., `migrations/20260120_split_user_profile.sql`]
+**Breaking Change**: Yes
+**Rollback Plan**: [e.g., Reverse migration available in same file]
+
+---
+
+## Data Flow Diagrams
+
+<!-- Optional: Visual representations of how data moves through the system -->
+
+### [Flow Name: e.g., User Registration]
+
+```
+1. User submits email + password
+   ↓
+2. Hash password with bcrypt
+   ↓
+3. INSERT into User table
+   ↓
+4. Send verification email
+   ↓
+5. Create UserProfile record
+```
+
+---
+
+## Validation Rules
+
+<!-- Document business logic constraints that aren't enforced at the DB level -->
+
+### [Rule: e.g., Post Publishing]
+
+**Condition**: User can only publish a post if:
+- Post.title length >= 10 characters
+- User.status === 'ACTIVE'
+- User has 'PUBLISHER' role
+
+**Enforcement Location**: [e.g., `src/services/postService.ts`]
+
+---
+
+## Performance Considerations
+
+### Query Patterns
+
+**Most Common Queries**:
+1. [e.g., `SELECT * FROM posts WHERE userId = ? ORDER BY publishedAt DESC LIMIT 20`]
+2. [e.g., `SELECT * FROM users WHERE email = ?`]
+
+**Indexes Supporting These**:
+- [e.g., Index on `posts.userId` + `posts.publishedAt`]
+- [e.g., Unique index on `users.email`]
+
+### Expected Scale
+
+**Projected Data Volume** (Year 1):
+- [e.g., Users: ~10,000]
+- [e.g., Posts: ~100,000]
+- [e.g., Comments: ~500,000]
+
+**Growth Strategy**: [e.g., Partition posts table by year after 1M records]
+
+---
+
+## Security Considerations
+
+### Sensitive Fields
+
+**Never expose in API responses**:
+- `User.passwordHash`
+- [e.g., `User.resetToken`]
+- [e.g., `Payment.cardNumber` (store only last 4 digits)]
+
+**Encryption at Rest**:
+- [e.g., `User.email` - encrypted in production DB]
+
+---
+
+## AI Agent Notes
+
+**When generating database queries**:
+- ⚠️ Always use parameterized queries (prevent SQL injection)
+- ⚠️ All timestamps are stored in UTC (convert to user timezone in frontend)
+- ⚠️ Soft deletes: Check `deletedAt IS NULL` in WHERE clauses
+
+**Common Mistakes to Avoid**:
+- ❌ Don't use `SELECT *` in production code (explicit columns only)
+- ❌ Don't expose `passwordHash` in any API response
+- ❌ Don't perform N+1 queries (use JOINs or eager loading)
+
+---
+
+## References
+
+- **ORM Documentation**: [Link to Prisma/TypeORM/etc. docs]
+- **Database Docs**: [Link to PostgreSQL/MongoDB/etc. docs]
+- **Migration Guide**: [Link to your migration strategy doc]