@esotech/contextuate 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexander David Conroy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# Contextuate Framework
+
+<p align="center">
+  <a href="https://contextuate.md">
+    <img src="assets/logo-black.png" alt="Contextuate Logo" width="200" />
+  </a>
+</p>
+
+
+**Standardized AI Context for Software Projects**
+
+Contextuate provides a structured "brain" for your project that AI coding assistants (like Claude, Copilot, Cursor) can understand. It standardizes how AI agents receive context, follow coding standards, and execute tasks.
+
+## Quick Start
+
+### One-Line Install (Recommended)
+
+```bash
+curl -fsSL https://contextuate.md/install.sh | sh
+```
+
+### Install via npm
+
+```bash
+npm install -g @esotech/contextuate
+```
+
+Or use directly with npx:
+
+```bash
+npx @esotech/contextuate init
+```
+
+### Install from Source
+
+Clone the repository and install globally:
+
+```bash
+git clone https://github.com/esotech/contextuate.git
+cd contextuate
+npm install
+npm run build
+npm link
+```
+
+### Initialize Your Project
+
+Navigate to your project directory and run:
+
+```bash
+contextuate init
+```
+
+The interactive installer will guide you through:
+1. Selecting which AI platforms to configure (Claude Code, Cursor, Copilot, Windsurf, etc.)
+2. Creating the `docs/ai/` directory structure with framework files
+3. Generating platform-specific configuration files
+4. Setting up symlinks for supported platforms (e.g., `.claude/` for Claude Code)
+
+## What is Contextuate?
+
+Contextuate is a directory structure and set of conventions that helps AI agents work more effectively. It turns implicit project knowledge into explicit, structured context.
+
+- **`docs/ai/.contextuate/contextuate.md`**: The framework bootstrap file. It links to everything else.
+- **`docs/ai/context.md`**: Your project-specific context (Identity, Tech Stack).
+- **`docs/ai/project-structure.md`**: Auto-generated file tree map (created by `contextuate index`).
+- **`docs/ai/agents/`**: Specialized "personas" for your AI (e.g., `documentation-expert`).
+- **`docs/ai/standards/`**: Explicit coding standards and behavioral guidelines.
+- **`docs/ai/quickrefs/`**: Condensed documentation optimized for AI token limits.
+- **`docs/ai/tasks/`**: A workflow for managing multi-session AI tasks.
+
+## How LLMs Use Contextuate
+
+1. **Discovery**: The AI reads `docs/ai/.contextuate/contextuate.md` first. This file maps the project and links to all other resources.
+2. **Specialization**: If acting as a specific agent, it reads `docs/ai/agents/<name>.md` to load specific capabilities and rules.
+3. **Execution**: The AI follows the linked standards in `docs/ai/standards/` and uses `docs/ai/quickrefs/` for technical lookups.
+4. **Memory**: If working on a long-running task, it tracks state in `docs/ai/tasks/<task-name>/` to maintain context across sessions.
+
+When using the `contextuate run` command, this context loading is automated based on the agent definition.
+
+## Repository Structure
+
+This repository contains the source for the Contextuate framework.
+
+- **`docs/ai/.contextuate/`**: The core framework files distributed to users.
+  - `agents/`: Base agent definitions.
+  - `templates/`: Templates for new projects.
+  - `tools/`: AI tool guides.
+
+
+## Usage
+
+Once installed, you customize the framework for your project:
+
+1. Edit **`docs/ai/context.md`** with your project details (Identity, Tech Stack).
+    *   *Note: `docs/ai/.contextuate/contextuate.md` is the framework entry point and typically shouldn't be edited.*
+2. Create custom agents in **`docs/ai/agents/`** (using the Agent Creator tool).
+3. Document coding standards in **`docs/ai/standards/`**.
+4. Generate quickrefs in **`docs/ai/quickrefs/`**.
+
+## CLI Usage
+
+### Global Options
+
+```bash
+contextuate --help     # Display all available commands
+contextuate --version  # Display the installed version
+contextuate -V         # Short form for version
+```
+
+### Command Reference
+
+| Command        | Description                              |
+| :------------- | :--------------------------------------- |
+| `init`         | Initialize Contextuate in a project      |
+| `install`      | Install templates (agents, standards)    |
+| `run`          | Execute an agent                         |
+| `create-agent` | Create a new agent definition            |
+| `index`        | Generate a project file tree             |
+| `add-context`  | Interactively add files to context       |
+| `remove`       | Clean up framework files                 |
+
+---
+
+### `contextuate init`
+
+Initialize Contextuate in the current project.
+
+```bash
+# Interactive mode - prompts for platforms and agents
+contextuate init
+
+# Non-interactive - specify platforms directly
+contextuate init claude cursor copilot
+contextuate init all  # Install all platforms
+
+# With agents
+contextuate init claude --agents archon base
+contextuate init claude --agents all
+
+# Force overwrite existing files
+contextuate init claude --force
+```
+
+**Options:**
+- `-f, --force` - Overwrite existing files
+- `-a, --agents <names...>` - Install specific agents (e.g., "base archon" or "all")
+
+**Available Platforms:** `agents`, `antigravity`, `claude`, `cline`, `cursor`, `gemini`, `copilot`, `windsurf`
+
+---
+
+### `contextuate install`
+
+Install templates from the global Contextuate repository. Supports both flag-style and subcommand-style usage.
+
+```bash
+# Interactive mode
+contextuate install
+
+# List available templates
+contextuate install --list
+
+# Install all templates
+contextuate install --all
+
+# Flag style - install specific items
+contextuate install --agents archon base canvas
+contextuate install --standards php javascript
+contextuate install --tools quickref
+
+# Subcommand style
+contextuate install agents archon base
+contextuate install agents --all
+contextuate install standards php javascript python
+contextuate install standards --all
+contextuate install tools --all
+
+# Force overwrite
+contextuate install agents --all --force
+```
+
+**Options:**
+- `-a, --agents <names...>` - Install specific agents
+- `-s, --standards <names...>` - Install language standards
+- `-t, --tools <names...>` - Install tools
+- `--all` - Install all available templates
+- `-l, --list` - List available templates
+- `-f, --force` - Overwrite existing files
+
+**Subcommands:**
+- `install agents [names...]` - Install agent templates
+- `install standards [names...]` - Install language standard templates
+- `install tools [names...]` - Install tool templates
+
+---
+
+### `contextuate run`
+
+Execute an agent definition with optional task context.
+
+```bash
+contextuate run documentation-expert
+contextuate run archon --goal "Review the codebase structure"
+contextuate run forge --task my-feature
+contextuate run nexus --dry-run
+```
+
+**Options:**
+- `--dry-run` - Simulate execution without running logic
+- `--isolation <mode>` - Isolation mode (`worktree`, `none`). Default: `none`
+- `--goal <text>` - Goal or instructions for the agent
+- `--task <name>` - Load a task context (scope and latest log)
+
+---
+
+### `contextuate create-agent`
+
+Create a new agent definition.
+
+```bash
+# Interactive mode
+contextuate create-agent
+
+# With name
+contextuate create-agent my-custom-agent
+contextuate new-agent my-custom-agent  # Alias
+
+# With description
+contextuate create-agent api-expert --description "Expert in REST API design"
+```
+
+**Options:**
+- `-d, --description <text>` - Description of the agent
+
+---
+
+### `contextuate index`
+
+Generate a project structure index for AI context.
+
+```bash
+contextuate index
+contextuate index --depth 3
+contextuate index --force
+```
+
+**Options:**
+- `-d, --depth <number>` - Maximum depth of the file tree. Default: `5`
+- `-f, --force` - Overwrite existing index
+
+---
+
+### `contextuate add-context`
+
+Interactively add files to `docs/ai/context.md`.
+
+```bash
+contextuate add-context
+```
+
+---
+
+### `contextuate remove`
+
+Remove unmodified platform jump files.
+
+```bash
+contextuate remove
+```
+
+## Documentation
+
+For full documentation, see [contextuate.md](https://contextuate.md) or browse the `docs/ai/.contextuate/` directory.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
+
+## License
+
+[MIT License](LICENSE)
+
+## Credits
+
+Powered by **Esotech**.
+Created by **Alexander Conroy** ([@geilt](https://github.com/geilt)).

package/dist/commands/context.js

@@ -0,0 +1,80 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addContextCommand = addContextCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const tokens_1 = require("../utils/tokens");
+async function addContextCommand() {
+    console.log(chalk_1.default.blue('[INFO] Interactive Context Creator'));
+    const contextFile = path_1.default.join(process.cwd(), 'docs/ai/context.md');
+    if (!await fs_extra_1.default.pathExists(contextFile)) {
+        console.error(chalk_1.default.red(`[ERROR] context.md not found at ${contextFile}`));
+        console.log(chalk_1.default.yellow('Run "contextuate init" first.'));
+        return;
+    }
+    // 1. Scan for files
+    // In a real app we'd need a more robust file picker or fuzzy search
+    // For now we will just list files in root and src (depth 2) to pick from
+    // or allow typing a path.
+    const { action } = await inquirer_1.default.prompt([
+        {
+            type: 'list',
+            name: 'action',
+            message: 'What would you like to do?',
+            choices: [
+                { name: 'Add specific file by path', value: 'path' },
+                // { name: 'Select from list (root)', value: 'select' }, // Hard to implement well without a huge list
+                { name: 'Cancel', value: 'cancel' }
+            ]
+        }
+    ]);
+    if (action === 'cancel')
+        return;
+    if (action === 'path') {
+        const { filePath } = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'filePath',
+                message: 'Enter relative path to file (e.g. src/index.ts):',
+                validate: async (input) => {
+                    if (!await fs_extra_1.default.pathExists(path_1.default.join(process.cwd(), input))) {
+                        return 'File does not exist';
+                    }
+                    return true;
+                }
+            }
+        ]);
+        await appendToContext(contextFile, filePath);
+    }
+}
+async function appendToContext(contextFile, targetFile) {
+    const content = await fs_extra_1.default.readFile(targetFile, 'utf-8');
+    const tokens = (0, tokens_1.estimateTokens)(content);
+    console.log(`Analyzing ${targetFile}... (~${tokens} tokens)`);
+    // Check if valid to add
+    if (tokens > 5000) {
+        const { confirm } = await inquirer_1.default.prompt([
+            {
+                type: 'confirm',
+                name: 'confirm',
+                message: `This file is large (~${tokens} tokens). Are you sure you want to add it?`,
+                default: false
+            }
+        ]);
+        if (!confirm)
+            return;
+    }
+    const docEntry = `
+## [File: ${targetFile}](file:///${path_1.default.resolve(targetFile)})
+\`\`\`${path_1.default.extname(targetFile).substring(1) || 'text'}
+${content}
+\`\`\`
+`;
+    await fs_extra_1.default.appendFile(contextFile, docEntry);
+    console.log(chalk_1.default.green(`[OK] Added ${targetFile} to context.md`));
+}

package/dist/commands/create.js

@@ -0,0 +1,93 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentCommand = createAgentCommand;
+const inquirer_1 = __importDefault(require("inquirer"));
+const chalk_1 = __importDefault(require("chalk"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function createAgentCommand(name, options) {
+    console.log(chalk_1.default.blue('╔════════════════════════════════════════╗'));
+    console.log(chalk_1.default.blue('║     Contextuate Agent Creator          ║'));
+    console.log(chalk_1.default.blue('╚════════════════════════════════════════╝'));
+    console.log('');
+    let agentName = name;
+    let agentDescription = options.description;
+    // Prompt for name if not provided
+    if (!agentName) {
+        const answers = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'name',
+                message: 'What is the name of the new agent? (kebab-case)',
+                validate: (input) => /^[a-z0-9-]+$/.test(input) || 'Name must be lowercase alphanumeric with hyphens',
+            },
+        ]);
+        agentName = answers.name;
+    }
+    // Prompt for description if not provided
+    if (!agentDescription) {
+        const answers = await inquirer_1.default.prompt([
+            {
+                type: 'input',
+                name: 'description',
+                message: 'Briefly describe what this agent does:',
+                default: 'A specialized agent for...',
+            },
+        ]);
+        agentDescription = answers.description;
+    }
+    const agentsDir = path_1.default.join(process.cwd(), 'docs/ai/agents');
+    const agentFile = path_1.default.join(agentsDir, `${agentName}.md`);
+    await fs_extra_1.default.ensureDir(agentsDir);
+    if (await fs_extra_1.default.pathExists(agentFile)) {
+        console.error(chalk_1.default.red(`[ERROR] Agent already exists: ${agentFile}`));
+        // Optional: Ask to overwrite
+        process.exit(1);
+    }
+    const template = `---
+name: "${agentName}"
+description: "${agentDescription}"
+version: "1.0.0"
+capabilities:
+  - "read_files"
+  - "search_files"
+context:
+  files:
+    - "docs/context.md"
+  directories:
+    - "src/"
+env: []
+---
+
+# ${agentName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')}
+
+> **Purpose:** ${agentDescription}
+> **Inherits:** [Base Agent](../.contextuate/agents/base.md)
+
+## Role
+
+Describe the specific role and improvements this agent provides.
+
+## Specialized Rules
+
+1. **Rule 1**: Description
+2. **Rule 2**: Description
+
+---
+`;
+    try {
+        await fs_extra_1.default.writeFile(agentFile, template);
+        console.log(chalk_1.default.green(`[OK] Created agent: ${agentFile}`));
+        console.log('');
+        console.log('Next steps:');
+        console.log(`1. Edit ${chalk_1.default.cyan(agentFile)} to refine rules and context.`);
+        console.log(`2. Run it with: ${chalk_1.default.yellow(`contextuate run ${agentName}`)}`);
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('[ERROR] Failed to write agent file:'), error);
+        process.exit(1);
+    }
+}

package/dist/commands/index.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexCommand = indexCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const tokens_1 = require("../utils/tokens");
+async function indexCommand(options) {
+    console.log(chalk_1.default.blue('[INFO] Generating project index...'));
+    const depth = options.depth ? parseInt(options.depth) : 5;
+    const projectRoot = process.cwd();
+    const destDir = path_1.default.join(projectRoot, 'docs/ai');
+    const destFile = path_1.default.join(destDir, 'project-structure.md');
+    // Ensure docs/ai exists
+    await fs_extra_1.default.ensureDir(destDir);
+    try {
+        const tree = await (0, tokens_1.generateFileTree)(projectRoot, depth);
+        const tokens = (0, tokens_1.estimateTokens)(tree);
+        const content = `# Project Structure Index
+<!-- 
+  GENERATED FILE - DO NOT EDIT MANUALLY
+  Generated by: contextuate index
+  Tokens: ~${tokens}
+-->
+
+\`\`\`
+${tree}
+\`\`\`
+`;
+        if (await fs_extra_1.default.pathExists(destFile) && !options.force) {
+            // Check if content is different? For now just overwrite if forced or tell user
+            // Actually, index is meant to be regenerated. We'll overwrite but log it.
+            // console.log(chalk.yellow(`[WARN] Overwriting existing index at ${destFile}`));
+        }
+        await fs_extra_1.default.writeFile(destFile, content);
+        console.log(chalk_1.default.green(`[OK] Generated index at: ${destFile}`));
+        console.log(`     Size: ${chalk_1.default.cyan(tokens + ' tokens')} (approx)`);
+        console.log(`     Use this file to give agents a high-level map of the codebase.`);
+    }
+    catch (e) {
+        console.error(chalk_1.default.red(`[ERROR] Failed to generate index: ${e.message}`));
+    }
+}