cortex-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yazan Ghafir
+
+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,68 @@
+# cortex-kit
+
+CLI tool that scaffolds AI-native projects with AGENTS.md specifications for AI coding assistants.
+
+## Features
+
+- Single command to initialize AI-native project structure
+- AGENTS.md template with software development best practices
+- Framework-agnostic (works with any tech stack)
+- Compatible with 20+ AI coding tools (Claude Code, GitHub Copilot, Cursor, etc.)
+- Zero dependencies
+
+## Installation
+
+```bash
+# Use with npx (no installation needed)
+npx cortex-kit init my-project
+
+# Or install globally
+npm install -g cortex-kit
+cortex-kit init my-project
+```
+
+## Usage
+
+### Create a new project
+```bash
+npx cortex-kit init my-awesome-project
+cd my-awesome-project
+```
+
+### Initialize in current directory
+```bash
+npx cortex-kit init .
+```
+
+## What Gets Generated
+
+- `AGENTS.md` - Project context for AI coding agents (workflows, testing, conventions)
+- `CLAUDE.md` - Reference to AGENTS.md for Claude Code
+- `README.md` - Setup instructions for your team
+- `docs/` - Empty directory for architecture documentation
+
+## Next Steps After Generation
+
+1. Customize `AGENTS.md` with your project details:
+   - Update project overview
+   - Add build and test commands
+   - Specify coding conventions
+   - Add project-specific guidelines
+
+2. Start coding with AI assistants (Claude Code, Copilot, Cursor, etc.)
+
+3. Document architecture decisions in `docs/`
+
+## Why AGENTS.md?
+
+AGENTS.md is an open standard used by 60,000+ projects to provide context to AI coding agents. It's like a README for AI - containing build steps, conventions, and practices that AI agents need to work effectively.
+
+Learn more: [agents.md](https://agents.md/)
+
+## Requirements
+
+- Node.js 18 or higher
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { init } from '../src/index.js';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+const projectName = args[1] || '.';
+
+// Simple argument validation
+if (!command) {
+  console.error('Error: No command provided');
+  console.log('Usage: cortex-kit init [project-name]');
+  console.log('       cortex-kit init .  (for current directory)');
+  process.exit(1);
+}
+
+if (command !== 'init') {
+  console.error(`Error: Unknown command "${command}"`);
+  console.log('Available commands: init');
+  process.exit(1);
+}
+
+// Execute init command
+try {
+  await init(projectName);
+} catch (error) {
+  console.error('Error:', error.message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cortex-kit",
+  "version": "1.0.0",
+  "description": "CLI tool that scaffolds AI-native projects with AGENTS.md specifications",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "cortex-kit": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "./tests/test.sh",
+    "prepublishOnly": "./tests/test.sh"
+  },
+  "keywords": [
+    "cli",
+    "agents.md",
+    "claude-code",
+    "ai-native",
+    "scaffold",
+    "ai-coding",
+    "copilot",
+    "cursor"
+  ],
+  "author": "Yazan Ghafir",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ]
+}

package/src/generator.js

@@ -0,0 +1,31 @@
+import { writeFile, readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Generate all template files in target directory
+ * @param {string} targetDir - Target directory path
+ */
+export async function generateFiles(targetDir) {
+  const templates = [
+    { name: 'AGENTS.md', dest: 'AGENTS.md' },
+    { name: 'CLAUDE.md', dest: 'CLAUDE.md' },
+    { name: 'README.md', dest: 'README.md' }
+  ];
+
+  for (const template of templates) {
+    const templatePath = join(__dirname, 'templates', template.name);
+    const destPath = join(targetDir, template.dest);
+
+    try {
+      const content = await readFile(templatePath, 'utf-8');
+      await writeFile(destPath, content, 'utf-8');
+      console.log(`✓ Generated ${template.dest}`);
+    } catch (error) {
+      throw new Error(`Failed to generate ${template.dest}: ${error.message}`);
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,59 @@
+import { resolve, join } from 'path';
+import { mkdir } from 'fs/promises';
+import { generateFiles } from './generator.js';
+
+/**
+ * Initialize a new AI-native project
+ * @param {string} projectName - Name of project or '.' for current directory
+ */
+export async function init(projectName) {
+  // Determine target directory
+  const targetDir = projectName === '.'
+    ? process.cwd()
+    : resolve(process.cwd(), projectName);
+
+  const isCurrentDir = projectName === '.';
+  const displayName = isCurrentDir ? 'current directory' : projectName;
+
+  console.log(`🚀 Initializing cortex-kit in ${displayName}...`);
+
+  // Create project directory if not current directory
+  if (!isCurrentDir) {
+    try {
+      await mkdir(targetDir, { recursive: true });
+      console.log(`✓ Created directory: ${projectName}`);
+    } catch (error) {
+      if (error.code === 'EEXIST') {
+        console.log(`✓ Directory exists: ${projectName}`);
+      } else {
+        throw new Error(`Failed to create directory: ${error.message}`);
+      }
+    }
+  }
+
+  // Create docs directory
+  const docsDir = join(targetDir, 'docs');
+  try {
+    await mkdir(docsDir, { recursive: true });
+    console.log('✓ Created docs/ directory');
+  } catch (error) {
+    throw new Error(`Failed to create docs directory: ${error.message}`);
+  }
+
+  // Generate all template files
+  await generateFiles(targetDir);
+
+  console.log('\n✨ Setup complete!');
+  console.log('\nNext steps:');
+  if (!isCurrentDir) {
+    console.log(`  cd ${projectName}`);
+  }
+  console.log('  1. Customize AGENTS.md with your project details');
+  console.log('  2. Add build and test commands to AGENTS.md');
+  console.log('  3. Open your project with Claude Code or other AI tools');
+  console.log('\nGenerated files:');
+  console.log('  - AGENTS.md: Project context for AI coding agents');
+  console.log('  - CLAUDE.md: Reference to AGENTS.md');
+  console.log('  - README.md: Setup instructions');
+  console.log('  - docs/: Architecture documentation folder');
+}

package/src/templates/AGENTS.md

@@ -0,0 +1,85 @@
+# Project Context for AI Agents
+
+## Development Workflow
+
+### Before Starting Work
+1. Understand the requirements and scope
+2. Check existing documentation in `docs/`
+3. Review relevant code and tests
+4. Plan the approach before implementing
+
+### Implementation Process
+1. Write clean, readable code with clear intent
+2. Follow existing patterns and conventions in the codebase
+3. Keep changes focused and atomic
+4. Add comments only for complex logic that isn't self-evident
+
+### Testing Requirements
+- **Always write tests** for new features and bug fixes
+- Run all tests before considering work complete
+- Include both positive and negative test cases
+- Ensure tests are deterministic and reliable
+- Test edge cases and error conditions
+
+### Development Testing
+- **Run tests after every change** to catch issues early
+- Fix failing tests immediately, don't accumulate technical debt
+- Verify tests pass locally before committing
+- Add regression tests for bugs to prevent recurrence
+
+## Code Quality Standards
+
+### General Principles
+- Write self-documenting code with meaningful names
+- Keep functions small and focused (single responsibility)
+- Avoid premature optimization
+- Prefer clarity over cleverness
+- Don't repeat yourself (DRY) but avoid premature abstraction
+
+### Error Handling
+- Handle errors gracefully and provide clear messages
+- Validate input at system boundaries
+- Don't swallow exceptions silently
+- Use appropriate error types for different scenarios
+
+### Security
+- Never commit secrets, API keys, or credentials
+- Validate and sanitize all external input
+- Follow security best practices for your tech stack
+- Consider security implications of changes
+
+## Documentation
+
+### Code Documentation
+- Document **why**, not **what** (code shows what)
+- Update documentation when changing behavior
+- Keep documentation close to the code it describes
+
+### Architecture Documentation
+- Document architectural decisions in `docs/architecture/`
+- Include context, decision, and consequences (ADR format)
+- Update architecture docs when making structural changes
+- Explain trade-offs and alternatives considered
+
+### API Documentation
+- Document public interfaces and APIs in `docs/api/`
+- Include usage examples
+- Document expected inputs, outputs, and error cases
+
+## Git Workflow
+
+### Commits
+- Write clear, descriptive commit messages
+- Keep commits focused on a single logical change
+- Commit message format: Brief summary, detailed explanation if needed
+- Don't commit broken code or failing tests
+
+### Before Committing
+- [ ] All tests pass
+- [ ] Code is clean and follows conventions
+- [ ] No debug code, console logs, or commented-out code
+- [ ] Documentation updated if needed
+
+---
+
+**Note**: Customize this file with project-specific details like build commands, test commands, and tech stack conventions as your project evolves.

package/src/templates/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

package/src/templates/README.md

@@ -0,0 +1,55 @@
+# AI-Native Project Setup
+
+This project is configured for AI-native development with AI coding assistants.
+
+## What's Included
+
+### AGENTS.md
+Project context and conventions for AI coding agents (Claude Code, GitHub Copilot, Cursor, etc.). This file contains:
+- Development workflow and best practices
+- Testing requirements and quality standards
+- Documentation guidelines
+- Project-specific build and test commands
+
+**This is the main file to customize** with your project's conventions, tech stack, and workflows.
+
+### CLAUDE.md
+A reference file that points to `AGENTS.md`, telling Claude Code to read the AGENTS.md file for project context.
+
+### docs/
+Empty directory for architecture documentation, design decisions, and API docs.
+
+## Getting Started
+
+### 1. Customize AGENTS.md
+Update the following sections in `AGENTS.md`:
+- **Project Overview**: Describe what your project does
+- **Build Commands**: Add your actual build commands (e.g., `npm run build`, `cargo build`)
+- **Test Commands**: Add your test commands (e.g., `npm test`, `pytest`)
+- **Project-Specific Guidelines**: Add any conventions specific to your project
+
+### 2. Use with AI Coding Tools
+AI coding assistants will automatically read `AGENTS.md` to understand:
+- How to build and test your project
+- Code quality standards to follow
+- Testing requirements
+- Documentation expectations
+
+### 3. Document Your Architecture
+Create subdirectories in `docs/` as needed:
+- `docs/architecture/` - Architectural decisions and design docs
+- `docs/api/` - API documentation
+- `docs/guides/` - Development guides
+
+## Why AGENTS.md?
+
+AGENTS.md is an open standard used by 60,000+ projects to provide context to AI coding agents. It's like a README for AI - containing build steps, conventions, and practices that AI agents need to work effectively on your codebase.
+
+## Learn More
+
+- [AGENTS.md Specification](https://agents.md/)
+- [Claude Code Documentation](https://code.claude.com/docs)
+
+---
+
+Generated with [cortex-kit](https://www.npmjs.com/package/cortex-kit)