create-project-cortex-agent 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# create-project-cortex-agent
+
+A command-line tool to instantly initialize your workspace with the **Project Cortex** AI Agent directory structure.
+
+This package bootstraps the foundational architecture needed for long-term AI-assisted development by preventing context degradation. It sets up strict boundaries, rules, and calendar-based memory logs for AI coding agents (such as Claude, Gemini, ChatGPT, or IDEs like Cursor and Copilot).
+
+---
+
+## 🚀 Installation & Usage
+
+### Option 1: Using `npx` (Recommended)
+If this package is published to npm, you don't need to install anything globally. You can run it directly:
+
+```bash
+# Initialize into the current directory
+npx create-project-cortex-agent .
+
+# Initialize into a specific directory
+npx create-project-cortex-agent ./my-new-project
+```
+
+### Option 2: Global Install
+You can install the CLI globally and use it anywhere:
+
+```bash
+npm install -g create-project-cortex-agent
+
+# Run the initialization
+create-project-cortex-agent .
+```
+
+### Option 3: Local Development (from source)
+If you are developing this tool locally:
+
+```bash
+# 1. Clone the repository and navigate to this folder
+cd create-project-cortex-agent
+
+# 2. Install dependencies
+npm install
+
+# 3. Build the CLI
+npm run build
+
+# 4. Link or run directly via node
+node dist/cli.js /path/to/target/project
+```
+
+---
+
+## 📂 What it Scaffolds
+
+The CLI safely injects the necessary constraints and guidelines into your repository without destroying existing source code. It sets up the following structure:
+
+```text
+├── .agents/
+│   ├── rules/
+│   │   └── arch_hard_tech_stack.md      # Immutable tech stack rules for the AI
+│   └── workflows/
+│       ├── init.md                      # Workflow to start a new session
+│       └── save-memory.md               # Workflow template for memory operations
+├── code/
+│   └── README.md                        # Codebase operating rules for the AI
+└── memory/
+    └── README.md                        # Instructions on calendar-based long-term memory
+```
+
+---
+
+## ⚙️ Post-Initialization (Next Steps)
+
+After running the initializer, your project is ready for smart AI assistance, but you should take one final step:
+
+1. **Configure Your Stack:** Open `.agents/rules/arch_hard_tech_stack.md` and define the strict technologies (Language, Framework, DB) your AI should stick to.
+2. **Start Your Agent:** Whenever you start a *new* conversation window with your AI agent, you should trigger the initialization workflow so the agent loads up the necessary architectural context. You can do this by saying:
+
+    > "Run Cortex" / "hey cortex, lets start" / "hey cortex, lets continue"
+
+    *\*If your agent requires explicit file references (like Cursor), you can type `@init.md Run Cortex`.*
+3. **Log Your Sessions:** Simply use natural language like "that's it for today", "we are done", or "see ya later" to trigger the chronological summary in the `memory/` logs!
+
+---
+
+## 🛠 Features
+- **Idempotency**: Safe to run multiple times; it will not overwrite modified files if you already customized your configuration.
+- **Git Awareness**: Warns you if the target directory doesn't have a git repository initialized yet.

package/dist/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs-extra"));
+const fileops_1 = require("./utils/fileops");
+const program = new commander_1.Command();
+program
+    .name('create-project-cortex-agent')
+    .description('Initializes a clean directory structure and deploy Markdown-based instruction files into an existing project.')
+    .version('1.0.0');
+program
+    .argument('[target-directory]', 'The directory to initialize', '.')
+    .action(async (targetDirStr) => {
+    try {
+        const targetDir = path.resolve(targetDirStr);
+        console.log(`\nInitializing Project Cortex Agent Structure in: ${chalk_1.default.cyan(targetDir)}\n`);
+        // 1. Check Context
+        if (!(0, fileops_1.isGitRepo)(targetDir)) {
+            console.warn(chalk_1.default.yellow('⚠ Warning: The target directory does not appear to be inside a Git repository.'));
+        }
+        const spinner = (0, ora_1.default)('Creating directories...').start();
+        // 2. Ensure Directories
+        const dirs = [
+            path.join(targetDir, '.agents', 'rules'),
+            path.join(targetDir, '.agents', 'workflows'),
+            path.join(targetDir, 'code'),
+        ];
+        for (const dir of dirs) {
+            await (0, fileops_1.ensureDirectory)(dir);
+        }
+        spinner.succeed('Directories created.');
+        // 3. Inject Markdown Files & Special Handling (Workflows)
+        const injectSpinner = (0, ora_1.default)('Injecting Markdown files...').start();
+        const __dirnameLocal = __dirname;
+        const templatesDir = path.join(__dirnameLocal, '..', 'templates');
+        // Defining the template mapping
+        const filesToInject = [
+            {
+                src: path.join(templatesDir, '.agents', 'rules', 'arch_hard_tech_stack.md'),
+                dest: path.join(targetDir, '.agents', 'rules', 'arch_hard_tech_stack.md')
+            },
+            {
+                src: path.join(templatesDir, '.agents', 'workflows', 'save-memory.md'),
+                dest: path.join(targetDir, '.agents', 'workflows', 'save-memory.md')
+            },
+            {
+                src: path.join(templatesDir, '.agents', 'workflows', 'init.md'),
+                dest: path.join(targetDir, '.agents', 'workflows', 'init.md')
+            },
+            {
+                src: path.join(templatesDir, 'memory', 'README.md'),
+                dest: path.join(targetDir, 'memory', 'README.md')
+            },
+            {
+                src: path.join(templatesDir, 'code', 'README.md'),
+                dest: path.join(targetDir, 'code', 'README.md')
+            }
+        ];
+        injectSpinner.info('Checking for existing template files...');
+        let allSuccess = true;
+        for (const file of filesToInject) {
+            if (await fs.pathExists(file.src)) {
+                const copied = await (0, fileops_1.safeCopy)(file.src, file.dest);
+                if (copied) {
+                    console.log(chalk_1.default.green(`  ✔ Injected: ${path.relative(targetDir, file.dest)}`));
+                }
+                else {
+                    allSuccess = false;
+                }
+            }
+            else {
+                console.warn(chalk_1.default.yellow(`  ⚠ Template missing in package: ${path.relative(templatesDir, file.src)}`));
+            }
+        }
+        if (allSuccess) {
+            console.log(chalk_1.default.green('\n✔ Initialization Complete!'));
+        }
+        else {
+            console.log(chalk_1.default.yellow('\n⚠ Initialization Finished with skipped files.'));
+        }
+        // 4. Final Message
+        console.log();
+        console.log(chalk_1.default.green('Project Cortex Agent has been successfully initialized.'));
+        console.log();
+        console.log(chalk_1.default.yellow('Next Steps:'));
+        console.log(chalk_1.default.yellow('  1. Initialize Antigravity in this project: ag init.'));
+        console.log(chalk_1.default.yellow('  2. Edit .agents/rules/arch_hard_tech_stack.md to define your stack.'));
+        console.log(chalk_1.default.yellow('  3. Enjoy!'));
+        console.log();
+    }
+    catch (error) {
+        (0, fileops_1.handleError)(error);
+    }
+});
+program.parse(process.argv);

package/dist/utils/fileops.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGitRepo = isGitRepo;
+exports.ensureDirectory = ensureDirectory;
+exports.safeCopy = safeCopy;
+exports.handleError = handleError;
+const fs = __importStar(require("fs-extra"));
+const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
+const inquirer_1 = __importDefault(require("inquirer"));
+/**
+ * Checks if the current directory is within a Git repository.
+ */
+function isGitRepo(targetDir) {
+    try {
+        (0, child_process_1.execSync)('git rev-parse --is-inside-work-tree', { stdio: 'ignore', cwd: targetDir });
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Ensures a directory exists, creating it if necessary.
+ */
+async function ensureDirectory(dirPath) {
+    await fs.ensureDir(dirPath);
+}
+/**
+ * Safely copies a template file to the target location.
+ * Prompts for confirmation if the file already exists.
+ */
+async function safeCopy(src, dest) {
+    if (await fs.pathExists(dest)) {
+        const { overwrite } = await inquirer_1.default.prompt([
+            {
+                type: 'confirm',
+                name: 'overwrite',
+                message: `File ${chalk_1.default.cyan(dest)} already exists. Overwrite?`,
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log(chalk_1.default.yellow(`Skipped ${dest}`));
+            return false;
+        }
+    }
+    await fs.copy(src, dest);
+    return true;
+}
+/**
+ * Centralized error handler
+ */
+function handleError(error) {
+    console.error(chalk_1.default.red('\n✖ An error occurred during initialization:'));
+    if (error instanceof Error) {
+        console.error(chalk_1.default.red(error.message));
+    }
+    else {
+        console.error(chalk_1.default.red(String(error)));
+    }
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-project-cortex-agent",
+  "version": "1.0.0",
+  "description": "CLI tool to initialize the Project Cortex agent directory structure and rules",
+  "main": "dist/cli.js",
+  "bin": {
+    "create-project-cortex-agent": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "keywords": [
+    "cli",
+    "project-cortex",
+    "agent",
+    "init"
+  ],
+  "author": "Project Cortex",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^8.2.6",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/inquirer": "^8.2.10",
+    "@types/node": "^20.11.16",
+    "typescript": "^5.3.3"
+  }
+}

package/templates/.agents/rules/arch_hard_tech_stack.md

@@ -0,0 +1,21 @@
+# System Constraints & Architecture
+
+> **Important: [AI-ONLY SYSTEM INSTRUCTION]**
+> This file defines the immutable architectural rules, tech stack, and hard boundaries for Project Cortex. 
+> You MUST strictly adhere to these constraints in every task, code generation, and refactoring step. Do not alter these rules unless explicitly instructed by the human developer.
+
+## 1. Core Tech Stack
+* **Language:** [e.g., TypeScript strictly enforced. No generic `any` types.]
+* **Framework:** [e.g., Next.js 14 with App Router.]
+* **Styling:** [e.g., Tailwind CSS.]
+* **Database/ORM:** [e.g., PostgreSQL with Prisma ORM.]
+
+## 2. Hard Architectural Rules
+* **Rule 1: Component Paradigms:** [e.g., Default to Server Components in Next.js. Only use `"use client"` when DOM manipulation or React lifecycle hooks are strictly required.]
+* **Rule 2: State Management:** [e.g., Use React Context for localized state. Do not introduce Redux without permission.]
+* **Rule 3: Error Handling:** [e.g., All external API calls must be wrapped in try/catch blocks with proper error logging. Never silently swallow errors.]
+
+## 3. AI Operational Boundaries
+* **Dependency Rule:** Before installing any new third-party library or package (via npm/yarn/pnpm/pip), you MUST explicitly ask the user for permission. Provide the package name, size, and rationale.
+* **Destructive Actions:** Before running any commands that drop databases, delete non-temporary files, or force-push to git, you MUST halt and request human confirmation.
+* **Decision Tracking:** If you and the human user agree on a fundamental shift in architecture or a new core library, you must immediately update this file to reflect the new state, and log the change in the daily `log_` file using the `[ADR]` tag.

package/templates/.agents/workflows/init.md

@@ -0,0 +1,12 @@
+---
+description: Bootstraps the AI's context for a new coding session.
+---
+
+# Initialization Workflow
+
+When the human says something like "Run Cortex", "hey cortex, lets start", "hey cortex, lets continue", "hey, let's start a new session", "initialize", or directly referring to this file, you must strictly follow these steps before answering any other prompt or writing any code.
+
+1. **Read System Rules:** Read the AI-only documentation in `memory/README.md`, `.agents/rules/arch_hard_tech_stack.md`, and `code/README.md`.
+2. **Contextualize Memory:** Review the `memory/` directory to understand what was done in the previous session (read the most recent log or rolling summary).
+3. **Check for Ghost Changes:** Check the state of the `code/` directory (e.g., using `git status` or `git diff`). If there are undocumented code changes that occurred after the last recorded memory log, you MUST retroactively create a `log_*.md` file summarizing those changes in the proper week's folder.
+4. **Ready:** Acknowledge you have loaded the context and ask the user what they want to work on.

package/templates/.agents/workflows/save-memory.md

@@ -0,0 +1,19 @@
+---
+description: Trigger memory rollup on natural language '/save-memory' or 'thats it for today'
+---
+
+# Save Memory Workflow
+
+## Triggers
+The user signals the end of a chat session using phrases like:
+- `/save-memory`
+- `thats it for today`
+- `wrap it up`
+- `see ya later`
+
+## Execution
+When the above intent is detected:
+1. Generate an overview log of the current conversation.
+2. Store this log inside `memory/` or update `.agents/rules/` if an architecture rule changed.
+3. Archive older logs to ensure a maximum of 30 active files in the working directory.
+4. Announce that the session memory has been effectively committed.

package/templates/code/README.md

@@ -0,0 +1,17 @@
+# Codebase Operating Rules
+
+> **Important: [AI-ONLY SYSTEM INSTRUCTION]**
+> This file dictates how the AI agent should write, format, and manage code within the `code/` directory.
+
+## 1. Coding Standards
+* **Clean Code:** Write modular, highly cohesive, and loosely coupled code. Keep functions small and focused on a single responsibility.
+* **No Dead Code:** Do not leave commented-out code blocks, unused variables, or `console.log` statements in final production files unless explicitly asked for debugging.
+* **Self-Documenting:** Prefer descriptive variable and function names over inline comments. Write comments only to explain *why* something complex was done, not *what* the code does.
+
+## 2. File Organization
+* Keep the directory structure flat where possible, but group files by feature rather than type (e.g., `/features/auth/` instead of throwing everything into one massive `/components/` folder).
+* Ensure all files follow a consistent naming convention (e.g., `kebab-case` for file names, `PascalCase` for React components).
+
+## 3. Execution & Testing
+* **Do Not Guess:** If a piece of code requires a specific environment variable or a database migration to run, you must inform the human user before considering the task complete.
+* **Refactoring:** When modifying existing code, ensure you do not break the surrounding context. If in doubt, output the planned changes for human review before applying them directly to the file.

package/templates/memory/README.md

@@ -0,0 +1,39 @@
+# Memory Context
+
+> **Important: [AI-ONLY SYSTEM INSTRUCTION]**
+> This file establishes the operational requirements for AI agents managing the project's memory. Humans do not need to read or edit this file unless fundamentally changing the rules of the template.
+> This folder stores conversation logs organized into a nested calendar structure, acting as the long-term memory for the AI.
+
+## Folder Hierarchy
+
+* **`.agents/rules/`**: Holds system constraints, architectural rules, and core states that bypass all standard archiving rules. These files are permanently kept.
+* **`memory/[YYYY]/`**: The root folder for a given year.
+    * `year_[YYYY].md`: Annual summary of the months.
+    * **`[MM]/`**: Folder for the month (01 to 12).
+        * `month_[YYYY]-[MM].md`: Monthly summary of the weeks.
+        * **`W[WW]/`**: Folder for the week of the year (e.g., W14).
+            * `week_[YYYY]-W[WW].md`: Weekly summary of the days.
+            * `log_[YYYYMMDD]_[HHMM]_[Topic].md`: Up to 30 raw conversation logs for the active days inside this week.
+
+## Rules & Processing
+
+1.  **Today (Raw Logs):** Current work is stored directly in the active week's folder (`W[WW]`). A maximum of 30 log files are kept at any time.
+2.  **Week (Summarization):** At the week's end, the active week's `log_` files are synthesized into `week_[YYYY]-W[WW].md` and the raw log files are deleted.
+3.  **Month (Summarization):** At the month's end, the `week_` summaries are synthesized into `month_[YYYY]-[MM].md`.
+4.  **Year (Summarization):** At the year's end, the `month_` summaries are synthesized into `year_[YYYY].md`.
+5.  **Overrides:** Files in `.agents/rules/` are permanently kept and NEVER summarized or deleted by the calendar cleanup process.
+6.  **Session Termination Trigger:** Whenever the human user uses natural language indicating the end of a session (e.g., "that's it for today", "we are done", "wrap it up", "see ya later"), you MUST automatically initiate the memory rollup process, generating the required summaries and `log_` files in the `memory/` directory.
+7.  **Auto-Recovery (Missing Logs):** If you are initialized in a new session and detect that the `code/` directory contains updates, new files, or Git changes that are NOT documented in the most recent `log_` or `week_` file, you must assume the previous session ended without a proper rollup. You MUST immediately analyze the undocumented code changes and generate a retroactive `log_` file summarizing them before proceeding with new human requests.
+
+## Mandatory Formatting & Retention Rules
+
+To prevent knowledge loss and context degradation during the summarization process, you MUST strictly adhere to the following rules:
+
+* **Summary Structure:** All `week_`, `month_`, and `year_` summaries MUST be formatted using this exact Markdown structure:
+    * **Completed Goals:** High-level overview of what was built, fixed, or explored.
+    * **Technical Decisions:** Specific architectural choices, dependencies added/removed, or workarounds implemented (including the rationale).
+    * **Unresolved Issues & WIP:** Tasks started but not finished, known bugs, or blockers.
+    * **Context & Notes:** Any specific commands, environment variables, or quirks needed to run the current codebase.
+* **Critical Retention Tags:** If a raw daily log or a lower-level summary contains the tag `[CRITICAL_DECISION]` or `[ADR]`, the exact text associated with that tag MUST be copied verbatim into the higher-level summaries. Do not paraphrase or compress these points.
+* **Task Rollover:** Any incomplete tasks or open bugs mentioned in the active period MUST be explicitly listed under "Unresolved Issues & WIP" in the newly generated summary so the next AI session can immediately resume work.
+* **Knowledge Extraction:** While summarizing at the end of a week/month, if a core architectural pattern, tech stack, or global rule has changed, you MUST automatically update the relevant files in `.agents/rules/` to reflect the current state of the project.