codingbuddy-rules 0.0.0-canary.20251222065027.7844cd5

package/.ai-rules/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to the Multi-AI Coding Assistant Common Rules System will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-11-20
+
+### Added
+- **Common Rules Repository** (`.ai-rules/`)
+  - `rules/core.md`: Workflow modes (PLAN/ACT/EVAL), agent activation, communication rules
+  - `rules/project.md`: Tech stack, project structure, development rules, domain knowledge
+  - `rules/augmented-coding.md`: TDD principles, code quality standards, commit discipline
+- **Specialist Agents** (12 agents)
+  - Frontend Developer, Code Reviewer
+  - Architecture, Test Strategy, Performance, Security
+  - Accessibility, SEO, Design System, Documentation
+  - Code Quality, DevOps Engineer
+- **AI Tool Integrations** (6 tools)
+  - Cursor: `.cursor/rules/imports.mdc`
+  - Claude Code: `.claude/rules/custom-instructions.md`
+  - Antigravity: `.antigravity/rules/instructions.md`
+  - GitHub Copilot: `.github/copilot-instructions.md`
+  - Amazon Q: `.q/rules/customizations.md`
+  - Kiro: `.kiro/rules/guidelines.md`
+- **Integration Guides** (6 adapters)
+  - Detailed guides for each AI tool in `.ai-rules/adapters/`
+- **Validation System**
+  - `scripts/validate-rules.sh`: Automated structure and file validation
+- **Documentation**
+  - `.ai-rules/README.md`: Comprehensive guide (11KB)
+  - `implementation_plan.md`: Detailed implementation plan
+  - `task.md`: Task checklist
+  - `walkthrough.md`: Complete implementation walkthrough
+
+### Changed
+- Removed Cursor-specific paths from common rules
+  - Changed `.cursor/agents/` → `.ai-rules/agents/` in `core.md` and `project.md`
+  - Changed `.mdc` → `.md` references for consistency
+- Transformed Cursor rules to AI-agnostic format
+  - Removed frontmatter metadata (globs, alwaysApply) from common rules
+  - Maintained tool-specific features in individual tool directories
+
+### Fixed
+- Cursor path dependencies in common rule files
+- File extension references consistency
+
+## [Unreleased]
+
+### Added
+- **Clarification Phase** for PLAN mode (`rules/clarification-guide.md`)
+  - Optional phase triggered when AI detects ambiguous requirements
+  - Sequential Q&A with progress indicator (Question N/M format)
+  - Multiple-choice questions preferred for easy response
+  - Ambiguity assessment checklist (6 categories, triggers on 2+ unclear)
+  - Question count guidelines (2-7 questions based on complexity)
+  - Korean/English output format support
+  - Updated `rules/core.md` with Clarification Phase section
+
+### Planned
+- Real-world usage testing across all 6 AI tools
+- Performance metrics collection
+- User feedback integration
+- Advanced examples and use cases
+
+---
+
+## Version Numbering
+
+- **Major version** (X.0.0): Breaking changes to common rules structure
+- **Minor version** (0.X.0): New AI tool integrations, new specialist agents
+- **Patch version** (0.0.X): Bug fixes, documentation updates, minor improvements
+
+## Migration Guides
+
+### Upgrading from Cursor-only to Multi-AI (1.0.0)
+
+**Before (Cursor-only)**:
+```
+.cursor/rules/
+├── core.mdc
+├── project.mdc
+└── augmented-coding.mdc
+```
+
+**After (Multi-AI 1.0.0)**:
+```
+.ai-rules/rules/          # Common rules (all tools)
+├── core.md
+├── project.md
+└── augmented-coding.md
+
+.cursor/rules/
+├── imports.mdc           # References .ai-rules/
+├── core.mdc              # Kept for compatibility
+├── project.mdc
+└── augmented-coding.mdc
+```
+
+**Action Required**: None - backwards compatible. Cursor continues to work with existing `.mdc` files while also referencing common rules via `imports.mdc`.
+
+---
+
+## Maintenance
+
+When updating rules:
+1. Update `.ai-rules/rules/*.md` for changes affecting all AI tools
+2. Update this CHANGELOG with changes under `[Unreleased]`
+3. When releasing, move `[Unreleased]` items to new version section
+4. Tag the release: `git tag -a v1.0.0 -m "Release v1.0.0"`
+
+## Links
+
+- [Implementation Plan](../implementation_plan.md)
+- [Walkthrough](../walkthrough.md)
+- [README](.ai-rules/README.md)

package/.ai-rules/README.md

@@ -0,0 +1,232 @@
+# Common AI Coding Rules System
+
+This directory contains shared coding rules and guidelines used across multiple AI coding assistants (Cursor, Claude Code, Codex, Antigravity, Amazon Q, Kiro, etc.) for consistent development practices.
+
+## Directory Structure
+
+```
+.ai-rules/
+├── README.md              # This file - overview and usage guide
+├── rules/                 # Common coding rules (AI-agnostic)
+│   ├── core.md           # Workflow modes (PLAN/ACT/EVAL), communication
+│   ├── clarification-guide.md  # Clarification Phase guidelines for PLAN mode
+│   ├── project.md        # Tech stack, architecture, project context
+│   └── augmented-coding.md  # TDD principles, code quality standards
+├── agents/                # Specialist agent definitions (JSON)
+│   └── *.json            # Domain specialist agents
+└── adapters/              # AI tool-specific integration guides
+    └── *.md              # Integration guides per tool
+```
+
+## Purpose
+
+### Single Source of Truth
+
+All AI coding assistants share the same:
+- **Workflow modes** (PLAN/ACT/EVAL)
+- **Code quality standards** (TDD, SOLID, 90%+ test coverage)
+- **Project context** (tech stack, architecture, conventions)
+- **Specialist knowledge** (security, performance, accessibility, etc.)
+
+### Benefits
+
+- **Consistency**: All AI tools follow identical coding standards
+- **Maintainability**: Update rules once, all tools benefit
+- **Extensibility**: Easy to add new AI tools
+- **Flexibility**: Tool-specific customizations via adapters
+- **Team Alignment**: Everyone uses the same guidelines regardless of AI tool preference
+
+## Core Rules Overview
+
+### 1. `rules/core.md` - Workflow & Communication
+
+**Workflow Modes:**
+- **PLAN**: Define implementation plan (includes optional Clarification Phase)
+- **ACT**: Execute the plan and make code changes
+- **EVAL**: Analyze results and propose improvements
+
+**Clarification Phase (Optional in PLAN):**
+- Triggers when AI detects ambiguous requirements (2+ unclear items)
+- Sequential Q&A with progress indicator (Question N/M)
+- Multiple-choice questions preferred for easy response
+- See `rules/clarification-guide.md` for detailed guidelines
+
+**Key Principles:**
+- Start in PLAN mode by default
+- Move to ACT when user types `ACT`
+- Return to PLAN after ACT completes (automatic)
+- Enter EVAL only when explicitly requested
+
+### 2. `rules/project.md` - Project Setup
+
+**Purpose:** Define project-specific context that AI assistants need.
+
+**Contents (customize per project):**
+- Tech stack and dependencies
+- Project structure and architecture
+- Development rules and conventions
+- Code review checklist
+
+> **Note**: This file is a template. Each project should customize it based on their tech stack and architecture.
+
+### 3. `rules/augmented-coding.md` - TDD & Quality
+
+**TDD Cycle:**
+1. **Red**: Write failing test
+2. **Green**: Implement minimal code
+3. **Refactor**: Improve after tests pass
+
+**Code Quality:**
+- SOLID principles
+- DRY (Don't Repeat Yourself)
+- No mocking - test real behavior
+- TypeScript strict mode (no `any`)
+- Tidy First approach (separate structural vs behavioral changes)
+
+## Specialist Agents
+
+Specialist agents provide domain-specific expertise:
+
+| Agent | Expertise | Use Cases |
+|-------|-----------|-----------|
+| **Code Reviewer** | Quality evaluation, architecture | Code review, production readiness |
+| **Architecture Specialist** | Layer boundaries, dependencies | System design, refactoring |
+| **Test Strategy Specialist** | Test coverage, TDD workflow | Testing strategy, quality assurance |
+| **Performance Specialist** | Optimization, profiling | Performance tuning, bottleneck analysis |
+| **Security Specialist** | Authentication, vulnerabilities | Security audit, secure coding |
+| **Accessibility Specialist** | WCAG 2.1 AA, ARIA | A11y compliance, screen readers |
+| **Documentation Specialist** | Technical writing, clarity | Documentation quality |
+| **Code Quality Specialist** | SOLID, DRY, complexity | Code quality planning/review |
+| **DevOps Engineer** | CI/CD, containerization, monitoring | Infrastructure, deployment |
+
+See `agents/README.md` for detailed agent documentation.
+
+## AI Tool Integration
+
+Each AI tool has its own integration guide in `adapters/`:
+
+- **Cursor**: `adapters/cursor.md`
+- **Claude Code**: `adapters/claude-code.md`
+- **GitHub Copilot / Codex**: `adapters/codex.md`
+- **Antigravity**: `adapters/antigravity.md`
+- **Amazon Q**: `adapters/q.md`
+- **Kiro**: `adapters/kiro.md`
+
+## Getting Started
+
+### For New AI Tool
+
+1. **Read the adapter guide**: Check if your tool has a guide in `adapters/`
+2. **Create tool directory**: e.g., `.{tool}/rules/`
+3. **Reference common rules**: Link to `.ai-rules/` in your tool's config
+4. **Add tool-specific customizations**: Only what's unique to that tool
+
+### For Existing Tools
+
+1. **Update existing configs**: Add references to `.ai-rules/`
+2. **Remove duplicates**: Rely on common rules first
+3. **Keep tool-specific features**: Maintain what's unique to each tool
+
+## Usage Examples
+
+### Workflow Example
+
+```
+User: Create a new feature for user registration
+
+AI: # Mode: PLAN
+    [References .ai-rules/rules/core.md workflow]
+    [Uses .ai-rules/rules/project.md context]
+    [Applies .ai-rules/rules/augmented-coding.md TDD]
+
+User: ACT
+
+AI: # Mode: ACT
+    [Executes implementation]
+
+User: EVAL
+
+AI: # Mode: EVAL
+    [Evaluates with code-reviewer.json framework]
+```
+
+### Referencing Rules
+
+In any AI tool:
+- `@.ai-rules/rules/core.md` - Workflow guidance
+- `@.ai-rules/rules/project.md` - Project context
+- `@.ai-rules/agents/*.json` - Specialist expertise
+
+## Maintenance
+
+### Updating Rules
+
+**For changes affecting all AI tools:**
+1. Edit files in `.ai-rules/rules/` or `.ai-rules/agents/`
+2. Commit changes
+3. All AI tools automatically use updated rules
+
+**For tool-specific changes:**
+1. Edit only that tool's config (e.g., `.cursor/rules/`)
+2. Common rules remain unchanged
+
+### Update Checklist
+
+After modifying `.ai-rules/`:
+- [ ] Rules are AI-agnostic (no tool-specific syntax)
+- [ ] Rules are technology-agnostic (no framework-specific content)
+- [ ] All markdown files are valid
+- [ ] Agent JSON files are valid
+- [ ] Documentation updated if needed
+
+## Architecture Principles
+
+### Design Decisions
+
+1. **AI-Agnostic Format**: Use standard markdown and JSON
+2. **Technology-Agnostic**: No framework-specific examples in common rules
+3. **Modular Structure**: Separate concerns (workflow, project, quality)
+4. **Tool Adapters**: Each tool translates common rules to its format
+5. **Single Source of Truth**: `.ai-rules/` is authoritative
+
+### Override Hierarchy
+
+When rules conflict between common rules and tool-specific configurations:
+
+**Priority Order** (highest to lowest):
+1. **Tool-specific rules** (e.g., `.cursor/rules/`)
+2. **Common rules** (`.ai-rules/rules/*.md`)
+3. **Default AI behavior** (tool's built-in defaults)
+
+### File Format Choices
+
+- **Markdown (.md)**: Universal, readable, supported by all tools
+- **JSON (.json)**: Structured data for agent definitions
+- **Tool-specific**: Each tool keeps its native format
+
+## Contributing
+
+### Adding New Rules
+
+1. Determine scope: All tools or tool-specific?
+2. If all tools: Add to `.ai-rules/rules/`
+3. If tool-specific: Add to `.{tool}/rules/`
+4. Ensure content is technology-agnostic
+5. Update relevant documentation
+
+### Adding New AI Tools
+
+1. Create directory: `.{new-tool}/`
+2. Create adapter guide: `.ai-rules/adapters/{new-tool}.md`
+3. Create tool config: `.{new-tool}/rules/`
+4. Reference common rules from `.ai-rules/`
+5. Document tool-specific features
+
+## Further Reading
+
+- **Workflow Details**: `rules/core.md`
+- **Clarification Phase**: `rules/clarification-guide.md`
+- **Project Setup**: `rules/project.md`
+- **TDD & Quality**: `rules/augmented-coding.md`
+- **Agent System**: `agents/README.md`
+- **Tool Integration**: `adapters/*.md`

package/.ai-rules/adapters/antigravity.md

@@ -0,0 +1,195 @@
+# Antigravity Integration Guide
+
+This guide explains how to use the common AI rules (`.ai-rules/`) in Antigravity (Google Gemini-based coding assistant).
+
+## Overview
+
+Antigravity uses the `.antigravity/` directory for its custom instructions and configuration, referencing the common rules from `.ai-rules/`.
+
+## Integration Method
+
+### 1. Create Antigravity Configuration
+
+Create `.antigravity/rules/instructions.md` to reference common rules:
+
+```markdown
+# Antigravity Instructions
+
+## Common AI Rules Reference
+
+This project follows shared AI coding rules from `.ai-rules/` for consistency across all AI assistants (Cursor, Claude Code, Antigravity, etc.).
+
+### 📚 Core Workflow (PLAN/ACT/EVAL)
+
+**Source**: `.ai-rules/rules/core.md`
+
+#### Work Modes
+
+You have three modes of operation:
+
+1. **PLAN mode** - Define a plan without making changes
+2. **ACT mode** - Execute the plan and make changes  
+3. **EVAL mode** - Analyze results and propose improvements
+
+**Mode Flow**:
+- Start in PLAN mode by default
+- Move to ACT when user types `ACT`
+- Return to PLAN after ACT completes (automatic)
+- Move to EVAL only when user explicitly types `EVAL`
+
+**Mode Indicators**:
+- Print `# Mode: PLAN` in plan mode
+- Print `# Mode: ACT` in act mode
+- Print `# Mode: EVAL` in eval mode
+
+See full workflow details in `.ai-rules/rules/core.md`
+
+### 🏗️ Project Context
+
+**Source**: `.ai-rules/rules/project.md`
+
+#### Tech Stack
+
+프로젝트의 `package.json`을 참조하세요.
+
+#### Project Structure
+```
+src/
+├── app/          # Next.js App Router
+├── entities/     # Domain entities (business logic)
+├── features/     # Feature-specific UI components
+├── widgets/      # Composite widgets
+└── shared/       # Common modules
+```
+
+See full project setup in `.ai-rules/rules/project.md`
+
+### 🎯 Augmented Coding Principles
+
+**Source**: `.ai-rules/rules/augmented-coding.md`
+
+#### TDD Cycle
+1. **Red**: Write a failing test
+2. **Green**: Implement minimum code to pass
+3. **Refactor**: Improve structure after tests pass
+
+#### Core Principles
+- **TDD for core logic** (entities, shared/utils, hooks)
+- **Test-after for UI** (features, widgets)
+- **SOLID principles** and code quality standards
+- **90%+ test coverage** goal
+- **No mocking** - test real behavior
+
+See full augmented coding guide in `.ai-rules/rules/augmented-coding.md`
+
+### 🤖 Specialist Agents
+
+**Source**: `.ai-rules/agents/`
+
+Available specialist agents:
+- **Frontend Developer** - React/Next.js, TDD, design system
+- **Code Reviewer** - Quality evaluation, architecture analysis
+- **Architecture Specialist** - Layer boundaries, dependency direction
+- **Test Strategy Specialist** - Test coverage, TDD workflow
+- **Performance Specialist** - Bundle size, rendering optimization
+- **Security Specialist** - OAuth 2.0, JWT, XSS/CSRF protection
+- **Accessibility Specialist** - WCAG 2.1 AA compliance
+- **SEO Specialist** - Metadata API, structured data
+- **Design System Specialist** - Design system usage
+- **Documentation Specialist** - Documentation quality
+- **Code Quality Specialist** - SOLID, DRY, complexity
+- **DevOps Engineer** - Docker, Datadog, deployment
+
+See agent details in `.ai-rules/agents/README.md`
+
+## Antigravity-Specific Features
+
+### Task Boundaries
+
+Antigravity supports `task_boundary` tool for tracking progress:
+```python
+task_boundary(
+  TaskName="Implementing Feature",
+  Mode="EXECUTION",
+  TaskSummary="Created component with TDD",
+  TaskStatus="Writing tests",
+  PredictedTaskSize=10
+)
+```
+
+### Artifact Management
+
+Antigravity uses artifact files for:
+- Implementation plans: `implementation_plan.md`
+- Task tracking: `task.md`
+- Walkthroughs: `walkthrough.md`
+
+### Communication
+
+- **Always respond in Korean (한국어)** as specified in common rules
+- Use structured markdown formatting
+- Provide clear, actionable feedback
+
+## Directory Structure
+
+```
+.antigravity/
+├── rules/
+│   └── instructions.md  # This file - references .ai-rules
+└── config.json          # Antigravity configuration (if needed)
+
+.ai-rules/              # Common rules for all AI tools
+├── rules/
+│   ├── core.md          # Workflow modes
+│   ├── project.md       # Project setup
+│   └── augmented-coding.md  # TDD principles
+├── agents/
+│   └── *.json          # Specialist agents
+└── adapters/
+    └── antigravity.md  # This guide
+```
+
+## Usage in Antigravity
+
+### Reference Rules Directly
+
+When working with Antigravity, it automatically has access to:
+- `.ai-rules/rules/` for workflow and coding standards
+- `.ai-rules/agents/` for specialist domain knowledge
+- Project-specific configuration in `.antigravity/rules/`
+
+### Workflow Example
+
+```
+User: 새로운 뉴스레터 기능 만들어줘
+
+AI: # Mode: PLAN
+    ## 📋 Plan Overview
+    [Following .ai-rules/rules/core.md workflow]
+    [Using .ai-rules/rules/project.md tech stack]
+    [Applying .ai-rules/rules/augmented-coding.md TDD principles]
+    
+User: ACT
+
+AI: # Mode: ACT
+    [Execute with .ai-rules/agents/frontend-developer.json guidelines]
+
+User: EVAL
+
+AI: # Mode: EVAL
+    [Evaluate with .ai-rules/agents/code-reviewer.json framework]
+```
+
+## Benefits
+
+- ✅ Same rules as Cursor and other AI tools (consistency)
+- ✅ Leverage Antigravity's task tracking and artifacts
+- ✅ Access to all specialist agent knowledge
+- ✅ Easy to update: change `.ai-rules/` once, all tools benefit
+
+## Maintenance
+
+When updating rules:
+1. Update `.ai-rules/rules/*.md` for changes affecting all AI tools
+2. Update `.antigravity/rules/instructions.md` only for Antigravity-specific features
+3. Common rules propagate automatically to all sessions

package/.ai-rules/adapters/claude-code.md

@@ -0,0 +1,117 @@
+# Claude Code Integration Guide
+
+This guide explains how to use the common AI rules (`.ai-rules/`) in Claude Code (Claude.ai Projects / Claude Desktop).
+
+## Overview
+
+Claude Code uses the `.claude/` directory for project-specific custom instructions, referencing the common rules from `.ai-rules/`.
+
+## Integration Method
+
+### 1. Create Claude Configuration
+
+Create `.claude/rules/custom-instructions.md`:
+
+```markdown
+# Custom Instructions for Claude Code
+
+## Project Rules
+
+Follow the common rules defined in `.ai-rules/` for consistency across all AI coding assistants.
+
+### Core Workflow
+See `.ai-rules/rules/core.md` for:
+- PLAN/ACT/EVAL workflow modes
+- Agent activation rules
+- Mode indicators and transitions
+
+### Project Context
+See `.ai-rules/rules/project.md` for:
+- Tech stack (프로젝트의 package.json 참조)
+- Project structure (app → widgets → features → entities → shared)
+- Development rules and file naming conventions
+- Domain knowledge
+
+### Code Quality
+See `.ai-rules/rules/augmented-coding.md` for:
+- TDD cycle (Red → Green → Refactor)
+- SOLID principles and code quality standards
+- Testing best practices (90%+ coverage goal)
+- Commit discipline
+
+### Specialist Agents
+See `.ai-rules/agents/README.md` for available specialist agents and their expertise areas.
+
+## Claude Code Specific
+
+- Always respond in Korean (한국어)
+- Use structured markdown formatting
+- Provide clear, actionable feedback
+- Reference project context from `.ai-rules/rules/project.md`
+```
+
+### 2. Add to Claude Project
+
+**In Claude.ai Projects**:
+1. Create a new Project for this codebase
+2. Add "Custom Instructions" with content from `.claude/rules/custom-instructions.md`
+3. Attach relevant files from `.ai-rules/` as project knowledge
+
+**In Claude Desktop**:
+1. Set project-specific instructions
+2. Reference `.claude/rules/` directory
+
+## Directory Structure
+
+```
+.claude/
+├── rules/
+│   └── custom-instructions.md  # References .ai-rules
+└── config.json                 # Claude project config (optional)
+
+.ai-rules/
+├── rules/
+│   ├── core.md
+│   ├── project.md
+│   └── augmented-coding.md
+├── agents/
+│   └── *.json
+└── adapters/
+    └── claude-code.md  # This guide
+```
+
+## Usage
+
+### In Claude Chat
+
+```
+User: 새로운 기능 만들어줘
+
+Claude: # Mode: PLAN
+        [Following .ai-rules/rules/core.md workflow]
+        
+User: ACT
+
+Claude: # Mode: ACT
+        [Execute with .ai-rules guidelines]
+```
+
+### Referencing Rules
+
+Claude can directly read and reference:
+- `.ai-rules/rules/*.md` files
+- `.ai-rules/agents/*.json` files
+- Project-specific patterns from `.ai-rules/rules/project.md`
+
+## Benefits
+
+- ✅ Consistent rules across all AI tools
+- ✅ Claude's strong reasoning applied to your project standards  
+- ✅ Easy updates: modify `.ai-rules/` once
+- ✅ Project knowledge persists across sessions
+
+## Maintenance
+
+1. Update `.ai-rules/rules/*.md` for universal changes
+2. Update `.claude/rules/custom-instructions.md` for Claude-specific features
+3. Sync Claude Project instructions when rules change significantly