Add comprehensive project documentation

README.md

@@ -0,0 +1,89 @@
+# Codingbuddy
+
+[![CI](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/dev.yml/badge.svg)](https://github.com/Codingbuddydev/codingbuddy/actions/workflows/dev.yml)
+[![npm version](https://img.shields.io/npm/v/codingbuddy.svg)](https://www.npmjs.com/package/codingbuddy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**One source of truth for AI coding rules across all AI assistants.**
+
+Codingbuddy provides a unified rules system that works with Cursor, Claude Code, GitHub Copilot, and more—so your entire team follows the same coding standards, regardless of which AI tool they use.
+
+## Why Codingbuddy?
+
+- **Consistency**: All AI tools follow identical coding standards
+- **Single Source of Truth**: Update rules once, all tools benefit
+- **No Vendor Lock-in**: AI-agnostic rules work with any assistant
+- **Structured Workflow**: PLAN → ACT → EVAL development cycle
+
+## Quick Start
+
+```bash
+# Initialize your project (analyzes codebase and creates config)
+npx codingbuddy init
+
+# Add to your AI tool (example: Claude Desktop)
+# See docs/supported-tools.md for other AI tools
+```
+
+Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["codingbuddy-mcp"]
+    }
+  }
+}
+```
+
+[Full Getting Started Guide →](docs/getting-started.md)
+
+## Supported AI Tools
+
+| Tool | Status |
+|------|--------|
+| Claude Code | ✅ Full MCP support |
+| Cursor | ✅ Supported |
+| GitHub Copilot | ✅ Supported |
+| Antigravity | ✅ Supported |
+| Amazon Q | ✅ Supported |
+| Kiro | ✅ Supported |
+
+[Setup Guides →](docs/supported-tools.md)
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Getting Started](docs/getting-started.md) | Installation and quick setup |
+| [Philosophy](docs/philosophy.md) | Vision and design principles |
+| [Supported Tools](docs/supported-tools.md) | AI tool integration guides |
+| [Configuration](docs/config-schema.md) | Config file options |
+| [API Reference](docs/api.md) | MCP server capabilities |
+| [Development](docs/development.md) | Contributing and local setup |
+
+## How It Works
+
+```
+.ai-rules/                 ← Shared rules (single source of truth)
+├── rules/                 ← Core rules (workflow, quality)
+├── agents/                ← Specialist expertise (security, performance, etc.)
+└── adapters/              ← Tool-specific integration guides
+
+.cursor/                   ← Cursor references .ai-rules/
+.claude/                   ← Claude Code references .ai-rules/
+.codex/                    ← GitHub Copilot references .ai-rules/
+...
+```
+
+All AI tool configurations reference the same `.ai-rules/` directory. Change the rules once, and every tool follows the updated standards.
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT © [Codingbuddy](https://github.com/Codingbuddydev)

docs/getting-started.md

@@ -0,0 +1,211 @@
+# Getting Started
+
+Get up and running with Codingbuddy in minutes.
+
+## Prerequisites
+
+- **Node.js**: v18 or higher
+- **AI Tool**: Any supported AI coding assistant ([see full list](./supported-tools.md))
+
+## Quick Start
+
+### Step 1: Initialize Your Project
+
+```bash
+# Set your Anthropic API key (required for project analysis)
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Initialize Codingbuddy in your project
+npx codingbuddy init
+```
+
+This command analyzes your project and creates a `codingbuddy.config.js` file with:
+
+- Detected tech stack (languages, frameworks, tools)
+- Architecture patterns
+- Coding conventions
+- Testing strategy
+
+### Step 2: Configure Your AI Tool
+
+Add Codingbuddy to your AI assistant. Here's an example for Claude Desktop:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "codingbuddy": {
+      "command": "npx",
+      "args": ["codingbuddy-mcp"]
+    }
+  }
+}
+```
+
+For other AI tools, see [Supported Tools](./supported-tools.md).
+
+### Step 3: Start Coding
+
+Your AI assistant now has access to:
+
+- **Project context**: Tech stack, architecture, conventions
+- **Workflow modes**: PLAN → ACT → EVAL
+- **Specialist agents**: Security, performance, accessibility experts
+
+Try it:
+
+```
+You: PLAN Create a user authentication feature
+
+AI: # Mode: PLAN
+    I'll design an authentication feature following your project's patterns...
+```
+
+## Configuration
+
+### Generated Config File
+
+The `codingbuddy.config.js` file customizes AI behavior:
+
+```javascript
+module.exports = {
+  // AI responds in this language
+  language: 'en',
+
+  // Project metadata
+  projectName: 'my-app',
+
+  // Technology stack
+  techStack: {
+    languages: ['TypeScript'],
+    frontend: ['React', 'Next.js'],
+    backend: ['Node.js'],
+  },
+
+  // Architecture pattern
+  architecture: {
+    pattern: 'feature-sliced-design',
+  },
+
+  // Coding conventions
+  conventions: {
+    naming: {
+      files: 'kebab-case',
+      components: 'PascalCase',
+    },
+  },
+
+  // Testing approach
+  testStrategy: {
+    approach: 'tdd',
+    coverage: 80,
+  },
+};
+```
+
+See [Configuration Schema](./config-schema.md) for all options.
+
+### Additional Context
+
+Add project-specific documentation that AI should know about:
+
+```
+my-project/
+├── codingbuddy.config.js
+└── .codingbuddy/
+    └── context/
+        ├── architecture.md    # System architecture docs
+        └── api-conventions.md # API design guidelines
+```
+
+### Ignore Patterns
+
+Create `.codingignore` to exclude files from AI analysis:
+
+```gitignore
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+.next/
+
+# Sensitive files
+.env*
+*.pem
+```
+
+## Using Workflow Modes
+
+### PLAN Mode (Default)
+
+Start with planning before making changes:
+
+```
+You: PLAN Add dark mode support
+
+AI: # Mode: PLAN
+
+    ## Implementation Plan
+    1. Create theme context...
+    2. Add toggle component...
+    3. Persist preference...
+```
+
+### ACT Mode
+
+Execute the plan with code changes:
+
+```
+You: ACT
+
+AI: # Mode: ACT
+
+    Creating theme context...
+    [Makes code changes following TDD]
+```
+
+### EVAL Mode
+
+Review and improve implementation:
+
+```
+You: EVAL
+
+AI: # Mode: EVAL
+
+    ## Code Review
+    - ✅ Theme context properly typed
+    - ⚠️ Consider adding system preference detection
+```
+
+## Using Specialist Agents
+
+Activate domain experts for specific tasks:
+
+```
+You: Activate the security-specialist agent to review authentication
+
+AI: [Activates security-specialist]
+
+    ## Security Review
+    - Password hashing: ✅ Using bcrypt
+    - Session management: ⚠️ Consider shorter token expiry
+    ...
+```
+
+Available specialists:
+
+- `security-specialist` - Security audits
+- `performance-specialist` - Optimization
+- `accessibility-specialist` - WCAG compliance
+- `code-reviewer` - Code quality
+- And [other specialists](../.ai-rules/agents/README.md)
+
+## Next Steps
+
+- [Supported Tools](./supported-tools.md) - Setup guides for each AI tool
+- [Philosophy](./philosophy.md) - Understanding the design principles
+- [API Reference](./api.md) - MCP server capabilities
+- [Development Guide](./development.md) - Contributing to Codingbuddy