create-ai-context

🤖 Generate AI-optimized project documentation and context files for better AI-assisted development.

Create structured templates with version control, architectural documentation, and clear guidelines for AI tools like Claude Code, GitHub Copilot, and ChatGPT.

✨ Features

• 🎯 Smart Project Detection - Auto-detects project types (new, empty, minimal, existing)
• 📁 Organized File Structure - Separates workflow files (root) from documentation (docs/)
• 🔄 Version Control - Track changes to strategic documents over time
• 🤖 AI-Optimized - Templates designed specifically for AI assistant context
• 🧠 AI-Guided Templates - Templates that help AI tools analyze and populate themselves
• 🔧 Multi-Agent Support - Optimized for Claude Code, Cursor, and GitHub Copilot
• ⚡ Automation Ready - Supports non-interactive mode for CI/CD
• 🛡️ Safe Overwrites - Protects existing files with confirmation prompts

🚀 Quick Start

# Interactive mode - prompts for directory and AI agent
npx create-ai-context

# Direct mode - no prompts, perfect for automation
npx create-ai-context --agent cursor --path ./my-project

📁 Generated Files

Root Directory

• DEVELOPMENT_PLAN.md - Project roadmap and phases (versioned)
• PROJECT_RULES.md - Development constraints and guidelines (versioned)
• README.md - Project documentation
• ai-instructions.md - Step-by-step AI guidance and tasks

docs/ Directory

• ARCHITECTURE.md - Technical architecture and patterns (versioned)
• DEVELOPER_GUIDE.md - Human developer workflows

🛠️ CLI Modes

Interactive Mode

npx create-ai-context

• Prompts for target directory (default: current)
• Prompts for AI agent selection (claude as default)
• Prompts for project configuration

Direct Mode

npx create-ai-context --agent <name> --path <directory>

• Requires both --agent and --path
• No prompts, uses smart defaults
• Perfect for automation

Options

| Option | Description | |--------|-------------| | --agent <name> | AI agent: claude, cursor, codex (required for direct mode) | | --path <directory> | Target directory (required for direct mode) | | --help | Show help message | | --version | Show version number |

🤖 AI Tool Integration

Claude Code

/memory add DEVELOPMENT_PLAN.md
/memory add PROJECT_RULES.md
/memory add docs/ARCHITECTURE.md

# Use AI instructions for guided setup
cat ai-instructions.md

Cursor

# Reference context files with @mentions
@DEVELOPMENT_PLAN.md @docs/ARCHITECTURE.md

# Use AI instructions for project analysis
@ai-instructions.md

GitHub Copilot

• Workspace automatically includes project rules
• Architecture documentation provides context
• Reference ai-instructions.md for structured tasks

📖 Documentation

📚 Full Documentation

• Template Reference
• Examples & Use Cases

💡 Use Cases

New Projects

mkdir my-new-app && cd my-new-app
npm init -y
npx create-ai-context  # Interactive: confirm directory, choose agent

Existing Projects

cd existing-project
npx create-ai-context  # Interactive: safe mode, prompts before overwriting

CI/CD Automation

- name: Setup AI Context
  run: npx create-ai-context --agent claude --path .

Team Onboarding

git clone project-repo
cd project-repo
npx create-ai-context --agent cursor --path .  # Direct mode for consistent setup

🔍 Smart Detection

The tool automatically detects:

• Project Type - new, empty (just initialized), minimal, or existing
• Development Stage - planning, foundation, development, or production
• Tech Stack from dependencies and project structure
• Language from dependencies and configuration
• Codebase Size to customize templates appropriately
• Existing Files to prevent accidental overwrites

⚡ Examples

# Interactive setup - choose directory and agent
npx create-ai-context

# Direct setup for Claude Code
npx create-ai-context --agent claude --path ./my-project

# Direct setup for Cursor
npx create-ai-context --agent cursor --path ./react-app

# Empty project (npm init, cargo new, etc.)
cd my-empty-project && npx create-ai-context

# Automation in CI/CD
npx create-ai-context --agent claude --path ./project

🏗️ Project Structure

your-project/
├── DEVELOPMENT_PLAN.md    # 📋 Project roadmap (versioned)
├── PROJECT_RULES.md       # 📏 Development guidelines (versioned)
├── README.md              # 📖 Project documentation
├── ai-instructions.md     # 🧠 Step-by-step AI guidance
├── src/                   # 💻 Your source code
└── docs/                  # 📚 Technical documentation
    ├── ARCHITECTURE.md    # 🏛️ System architecture (versioned)
    └── DEVELOPER_GUIDE.md # 👥 Developer workflows

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📋 Requirements

• Node.js 14.0.0 or higher
• npm or yarn

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

• 📋 Issues
• 💬 Discussions
• 📖 Documentation

⭐ Star History

If this tool helps your AI-assisted development workflow, please consider giving it a star! ⭐

Made with ❤️ for AI-assisted development