Epic: ruley v1.0.0 - Automated AI IDE Rules Generation

[unclesp1d3r]

Epic Brief: ruley v1.0.0 - Automated AI IDE Rules Generation

Summary

ruley is a Rust CLI tool that automatically generates AI IDE rule files from codebases, helping open-source maintainers provide better guidance to contributors using AI coding assistants. Instead of manually writing and maintaining separate rule files for Cursor, Claude, Copilot, and other AI IDEs, maintainers can run ruley to analyze their codebase and generate comprehensive, convention-aware rules in minutes. The tool uses LLMs (Anthropic Claude, OpenAI GPT) to understand project patterns, conventions, and architecture, then outputs properly formatted rules for multiple AI IDEs from a single analysis. This dramatically reduces the time and effort required to help AI assistants provide accurate, project-specific suggestions to contributors.

Context & Problem

Who's Affected:

• Individual developers adopting AI coding assistants for personal or professional projects
• Small development teams integrating AI tools into their workflow
• Open-source maintainers wanting to help contributors get better AI assistance
• Developers new to AI/prompt engineering who don't know how to write effective rules
• Experienced developers who don't want to spend time manually tuning rules files

This applies to both greenfield projects (starting fresh with AI assistance) and brownfield projects (adding AI assistance to existing codebases).

Current Pain Points:

1. Generic AI Suggestions: AI assistants provide generic code suggestions that don't match project-specific conventions, patterns, or architecture. Developers receive suggestions that violate style guides, use deprecated patterns, or ignore established conventions—especially problematic for those new to AI who don't know how to fix this.
2. Manual Rule Writing is Complex: Writing effective AI rules requires understanding both the codebase and prompt engineering. Developers must manually create and maintain separate rule files for each AI IDE (.cursor/rules/*.mdc, CLAUDE.md, .github/copilot-instructions.md). This is time-consuming, requires expertise many don't have, and quickly becomes outdated as codebases evolve.
3. Barrier to AI Adoption: Teams and individuals want to use AI coding assistants but are overwhelmed by the setup complexity. They either skip rules entirely (getting poor results) or spend hours learning prompt engineering and writing rules manually—a significant barrier to adoption, especially for those new to AI tools.

Current Workarounds:

• Manually write rules files for each AI IDE (hours of work, requires expertise)
• Copy-paste documentation into AI chat repeatedly (inefficient, doesn't scale)
• Accept generic AI suggestions and spend time correcting them (frustrating, slows development)
• Skip AI IDE features entirely (missed productivity opportunity)
• Hire consultants or spend time learning prompt engineering (expensive, time-consuming)

Why This Matters:

Developers and teams want to leverage AI coding assistants effectively without becoming prompt engineering experts. When AI assistants understand project conventions:

• Individual developers get accurate, context-aware suggestions without manual tuning
• Small teams can standardize AI assistance across team members
• Open-source maintainers lower the barrier to contribution
• Newcomers to AI can get great results without learning prompt engineering
• Everyone spends less time correcting AI suggestions and more time building features

The Opportunity:

ruley solves this by automating rule generation:

• Speed: Generate rules in minutes vs hours of manual work
• Comprehensiveness: Analyzes entire codebase, catches patterns humans miss
• Multi-format: One analysis produces rules for Cursor, Claude, and Copilot
• Maintainability: Easy to regenerate when conventions change or patterns emerge

Key Constraint: LLM costs must be managed carefully. The tool includes cost estimation, user confirmation, and tree-sitter compression (~70% token reduction) to keep costs reasonable for regular use.

Success Criteria

We'll know ruley is successful when:

1. Time Savings: Developers save significant time vs manual rule writing (minutes vs hours)
2. Adoption: Teams adopt ruley as standard practice for new projects
3. Quality: Generated rules are comprehensive and accurate enough to use as-is
4. Effectiveness: AI suggestions match project conventions without manual correction

Out of Scope (v1.0.0)

• Native git clone support (users handle repo checkout)
• Additional output formats beyond Cursor, Claude, Copilot
• Additional LLM providers beyond Anthropic and OpenAI
• Semantic search or caching mechanisms
• GUI or IDE plugins

[traycerai]

Plan

Observations

The ruley codebase has a solid foundation with Stages 1-4 (Init, Scanning, Compressing, Analyzing) fully implemented, including CLI parsing, file discovery, tree-sitter compression, LLM integration with chunking, and cost tracking. However, Stages 5-9 (Formatting, Writing, Validating, Finalizing, Reporting) are marked as TODO in file:src/lib.rs. The output formatters in file:src/output/ are stubbed, and the prompt templates referenced in file:src/generator/prompts.rs don't exist yet. The project has comprehensive test infrastructure and follows a well-defined 10-stage pipeline architecture.

Approach

The implementation will complete the remaining pipeline stages (5-9) to achieve v1.0.0 functionality. The approach follows the existing architecture: create prompt templates for each AI IDE format, implement output formatters using the OutputFormatter trait, add file writing logic, implement validation and reporting, and update documentation. This maintains consistency with the established patterns while completing the core feature set defined in the epic. The focus is on the three primary formats (Cursor, Claude, Copilot) as specified in the out-of-scope section.

Implementation Steps

1. Create Prompt Templates (Foundation)

Create the prompts/ directory structure with format-specific templates:

Files to create:

• prompts/base.md - Shared analysis prompt for all formats
• prompts/cursor.md - Cursor-specific instructions for .mdc format
• prompts/claude.md - Claude Code format instructions
• prompts/copilot.md - GitHub Copilot instructions format
• prompts/windsurf.md - Windsurf format instructions
• prompts/aider.md - Aider conventions format
• prompts/generic.md - Universal AI context format

Template structure:
Each template should instruct the LLM to analyze the codebase and extract:

• Project conventions (naming, structure, patterns)
• Tech stack and architecture
• Key files and their purposes
• Common tasks and workflows
• Anti-patterns to avoid
• Code examples (good/bad)

Reference the GeneratedRules structure in file:src/generator/rules.rs to ensure prompts guide the LLM to produce parseable output.

2. Implement Stage 5: Formatting (Output Formatters)

Complete the output formatter implementations in file:src/output/:

Cursor Formatter (file:src/output/cursor.rs):

• Implement format() method to generate .mdc format
• Structure: YAML frontmatter + Markdown body
• Include rule type (auto/manual/agent/always) from config
• Format conventions as bullet points with examples
• Add architecture overview and key files sections

Claude Formatter (file:src/output/claude.rs):

• Generate CLAUDE.md format for Claude Code
• Structure: Markdown with clear sections
• Include project context, conventions, and examples
• Focus on natural language instructions

Copilot Formatter (file:src/output/copilot.rs):

• Generate .github/copilot-instructions.md format
• Structure: Markdown optimized for GitHub Copilot
• Include coding standards and project-specific patterns

Additional Formatters:

• file:src/output/windsurf.rs - Windsurf .windsurfrules format
• file:src/output/aider.rs - Aider CONVENTIONS.md format
• file:src/output/generic.rs - Universal AI_CONTEXT.md format
• file:src/output/json.rs - JSON export of GeneratedRules structure

Helper function in file:src/output/mod.rs:
Add get_formatter(format: &str) -> Result<Box<dyn OutputFormatter>> to instantiate formatters based on format string.

3. Implement Rule Parsing from LLM Output

Update file:src/generator/rules.rs:

Add parsing function:

• parse_llm_output(analysis: &str) -> Result<GeneratedRules>
• Parse the LLM's analysis text into the GeneratedRules structure
• Handle both structured (JSON) and semi-structured (Markdown) responses
• Use regex or simple parsing to extract sections
• Provide sensible defaults for missing fields

Fallback strategy:
If parsing fails, create a minimal GeneratedRules with the raw analysis in the description field.

4. Implement Stage 6: Writing (File Output)

Add file writing logic in file:src/lib.rs at Stage 6:

Writing implementation:

• Iterate through config.format list
• For each format, get the appropriate formatter
• Call formatter.format(&rules, &metadata) to generate content
• Determine output path from config.output_paths or use defaults
• Create parent directories if needed
• Write formatted content to file
• Track written files for reporting

Default output paths (from PROJECT_SPEC.md):

• Cursor: .cursor/rules/{name}.rules.mdc
• Claude: CLAUDE.md
• Copilot: .github/copilot-instructions.md
• Windsurf: .windsurfrules
• Aider: CONVENTIONS.md
• Generic: AI_CONTEXT.md
• JSON: ai-rules.json

Error handling:

• Handle file write permissions errors
• Provide clear error messages with file paths
• Continue writing other formats if one fails (collect errors)

5. Implement Stage 7: Validating (Output Validation)

Add validation logic in file:src/lib.rs at Stage 7:

Validation checks:

• Verify all requested output files were created
• Check file sizes are non-zero
• For Cursor .mdc files, validate YAML frontmatter syntax
• For JSON output, validate JSON structure
• Log warnings for any validation issues

Validation helper:
Create validate_output_file(path: &Path, format: &str) -> Result<ValidationResult> in a new file:src/utils/validation.rs module.

6. Implement Stage 8: Finalizing (Post-processing)

Add finalization logic in file:src/lib.rs at Stage 8:

Finalization tasks:

• Set appropriate file permissions (readable by all)
• Add generation timestamp comments to output files
• Create a .ruley-metadata.json file with generation details:
  • Timestamp
  • ruley version
  • Provider and model used
  • Token counts and costs
  • Files generated

7. Implement Stage 9: Reporting (Summary Generation)

Add reporting logic in file:src/lib.rs at Stage 9:

Report structure:

✓ Analysis complete
✓ Generated rules for 3 formats:
  - .cursor/rules/myproject.rules.mdc (2.4 KB)
  - CLAUDE.md (1.8 KB)
  - .github/copilot-instructions.md (2.1 KB)

Cost Summary:
  - Input tokens: 45,230
  - Output tokens: 3,847
  - Total cost: $0.2341

Time: 12.3s

Implementation:

• Create file:src/utils/reporter.rs module
• Add Report struct to collect pipeline metrics
• Display summary unless --quiet flag is set
• Include file paths, sizes, token counts, costs, and timing

8. Add Integration Tests

Create test files in tests/:

tests/output_formatting_test.rs:

• Test each formatter with sample GeneratedRules
• Verify output format structure
• Test edge cases (empty rules, missing fields)

tests/end_to_end_test.rs:

• Test complete pipeline with mock LLM provider
• Verify files are created with correct content
• Test multiple format generation
• Test error handling paths

Test fixtures:

• Add sample LLM responses in tests/fixtures/llm_responses/
• Add expected output files in tests/fixtures/expected_outputs/

9. Update Documentation

Update file:README.md:

• Add usage examples for all supported formats
• Document output file locations
• Add troubleshooting section
• Update status from "Initial development" to "v1.0.0 Release Candidate"

Update file:CHANGELOG.md:

• Add v1.0.0 release notes with all implemented features
• List supported formats and providers
• Document breaking changes (if any)

Create CONTRIBUTING.md:

• Guidelines for adding new output formats
• Instructions for adding new LLM providers
• Testing requirements

10. Release Preparation

Version bump:

• Update version in file:Cargo.toml from "0.1.0" to "1.0.0"
• Update version references in documentation

CI/CD verification:

• Ensure file:.github/workflows/ci.yml runs all tests
• Verify file:.github/workflows/release.yml is configured for v1.0.0 tag
• Test binary builds for all platforms

Final validation:

• Run full test suite: cargo test --all-features
• Test CLI with real repositories
• Verify cost estimation accuracy
• Test all output formats with actual LLM providers

Architecture Diagram

sequenceDiagram
    participant User
    participant CLI
    participant Pipeline
    participant Packer
    participant LLM
    participant Generator
    participant Formatter
    participant Writer

    User->>CLI: ruley --format cursor,claude
    CLI->>Pipeline: Initialize (Stage 1)
    Pipeline->>Packer: Scan files (Stage 2)
    Packer-->>Pipeline: File entries
    Pipeline->>Packer: Compress (Stage 3)
    Packer-->>Pipeline: Compressed codebase
    Pipeline->>LLM: Analyze (Stage 4)
    LLM-->>Pipeline: Analysis result
    Pipeline->>Generator: Parse LLM output
    Generator-->>Pipeline: GeneratedRules
    Pipeline->>Formatter: Format (Stage 5)
    Formatter-->>Pipeline: Formatted content
    Pipeline->>Writer: Write files (Stage 6)
    Writer-->>Pipeline: Files written
    Pipeline->>Pipeline: Validate (Stage 7)
    Pipeline->>Pipeline: Finalize (Stage 8)
    Pipeline->>Pipeline: Report (Stage 9)
    Pipeline->>Pipeline: Cleanup (Stage 10)
    Pipeline-->>User: Success + Summary

Loading

Key Files Reference

Component	Files
Pipeline	file:src/lib.rs (Stages 5-9 implementation)
Prompts	prompts/base.md, prompts/cursor.md, prompts/claude.md, prompts/copilot.md
Formatters	file:src/output/cursor.rs, file:src/output/claude.rs, file:src/output/copilot.rs
Generator	file:src/generator/rules.rs (add parsing logic)
Utilities	file:src/utils/validation.rs, file:src/utils/reporter.rs (new files)
Tests	tests/output_formatting_test.rs, tests/end_to_end_test.rs (new files)
Config	file:Cargo.toml (version bump to 1.0.0)
Docs	file:README.md, file:CHANGELOG.md, CONTRIBUTING.md

Import In IDE

🤖 Prompt for AI Agents

## Observations

The ruley codebase has a solid foundation with Stages 1-4 (Init, Scanning, Compressing, Analyzing) fully implemented, including CLI parsing, file discovery, tree-sitter compression, LLM integration with chunking, and cost tracking. However, Stages 5-9 (Formatting, Writing, Validating, Finalizing, Reporting) are marked as TODO in `file:src/lib.rs`. The output formatters in `file:src/output/` are stubbed, and the prompt templates referenced in `file:src/generator/prompts.rs` don't exist yet. The project has comprehensive test infrastructure and follows a well-defined 10-stage pipeline architecture.

## Approach

The implementation will complete the remaining pipeline stages (5-9) to achieve v1.0.0 functionality. The approach follows the existing architecture: create prompt templates for each AI IDE format, implement output formatters using the `OutputFormatter` trait, add file writing logic, implement validation and reporting, and update documentation. This maintains consistency with the established patterns while completing the core feature set defined in the epic. The focus is on the three primary formats (Cursor, Claude, Copilot) as specified in the out-of-scope section.

## Implementation Steps

### 1. Create Prompt Templates (Foundation)

Create the `prompts/` directory structure with format-specific templates:

**Files to create:**
- `prompts/base.md` - Shared analysis prompt for all formats
- `prompts/cursor.md` - Cursor-specific instructions for `.mdc` format
- `prompts/claude.md` - Claude Code format instructions
- `prompts/copilot.md` - GitHub Copilot instructions format
- `prompts/windsurf.md` - Windsurf format instructions
- `prompts/aider.md` - Aider conventions format
- `prompts/generic.md` - Universal AI context format

**Template structure:**
Each template should instruct the LLM to analyze the codebase and extract:
- Project conventions (naming, structure, patterns)
- Tech stack and architecture
- Key files and their purposes
- Common tasks and workflows
- Anti-patterns to avoid
- Code examples (good/bad)

Reference the `GeneratedRules` structure in `file:src/generator/rules.rs` to ensure prompts guide the LLM to produce parseable output.

### 2. Implement Stage 5: Formatting (Output Formatters)

Complete the output formatter implementations in `file:src/output/`:

**Cursor Formatter (`file:src/output/cursor.rs`):**
- Implement `format()` method to generate `.mdc` format
- Structure: YAML frontmatter + Markdown body
- Include rule type (auto/manual/agent/always) from config
- Format conventions as bullet points with examples
- Add architecture overview and key files sections

**Claude Formatter (`file:src/output/claude.rs`):**
- Generate `CLAUDE.md` format for Claude Code
- Structure: Markdown with clear sections
- Include project context, conventions, and examples
- Focus on natural language instructions

**Copilot Formatter (`file:src/output/copilot.rs`):**
- Generate `.github/copilot-instructions.md` format
- Structure: Markdown optimized for GitHub Copilot
- Include coding standards and project-specific patterns

**Additional Formatters:**
- `file:src/output/windsurf.rs` - Windsurf `.windsurfrules` format
- `file:src/output/aider.rs` - Aider `CONVENTIONS.md` format
- `file:src/output/generic.rs` - Universal `AI_CONTEXT.md` format
- `file:src/output/json.rs` - JSON export of `GeneratedRules` structure

**Helper function in `file:src/output/mod.rs`:**
Add `get_formatter(format: &str) -> Result<Box<dyn OutputFormatter>>` to instantiate formatters based on format string.

### 3. Implement Rule Parsing from LLM Output

Update `file:src/generator/rules.rs`:

**Add parsing function:**
- `parse_llm_output(analysis: &str) -> Result<GeneratedRules>`
- Parse the LLM's analysis text into the `GeneratedRules` structure
- Handle both structured (JSON) and semi-structured (Markdown) responses
- Use regex or simple parsing to extract sections
- Provide sensible defaults for missing fields

**Fallback strategy:**
If parsing fails, create a minimal `GeneratedRules` with the raw analysis in the description field.

### 4. Implement Stage 6: Writing (File Output)

Add file writing logic in `file:src/lib.rs` at Stage 6:

**Writing implementation:**
- Iterate through `config.format` list
- For each format, get the appropriate formatter
- Call `formatter.format(&rules, &metadata)` to generate content
- Determine output path from `config.output_paths` or use defaults
- Create parent directories if needed
- Write formatted content to file
- Track written files for reporting

**Default output paths (from PROJECT_SPEC.md):**
- Cursor: `.cursor/rules/{name}.rules.mdc`
- Claude: `CLAUDE.md`
- Copilot: `.github/copilot-instructions.md`
- Windsurf: `.windsurfrules`
- Aider: `CONVENTIONS.md`
- Generic: `AI_CONTEXT.md`
- JSON: `ai-rules.json`

**Error handling:**
- Handle file write permissions errors
- Provide clear error messages with file paths
- Continue writing other formats if one fails (collect errors)

### 5. Implement Stage 7: Validating (Output Validation)

Add validation logic in `file:src/lib.rs` at Stage 7:

**Validation checks:**
- Verify all requested output files were created
- Check file sizes are non-zero
- For Cursor `.mdc` files, validate YAML frontmatter syntax
- For JSON output, validate JSON structure
- Log warnings for any validation issues

**Validation helper:**
Create `validate_output_file(path: &Path, format: &str) -> Result<ValidationResult>` in a new `file:src/utils/validation.rs` module.

### 6. Implement Stage 8: Finalizing (Post-processing)

Add finalization logic in `file:src/lib.rs` at Stage 8:

**Finalization tasks:**
- Set appropriate file permissions (readable by all)
- Add generation timestamp comments to output files
- Create a `.ruley-metadata.json` file with generation details:
  - Timestamp
  - ruley version
  - Provider and model used
  - Token counts and costs
  - Files generated

### 7. Implement Stage 9: Reporting (Summary Generation)

Add reporting logic in `file:src/lib.rs` at Stage 9:

**Report structure:**
```
✓ Analysis complete
✓ Generated rules for 3 formats:
  - .cursor/rules/myproject.rules.mdc (2.4 KB)
  - CLAUDE.md (1.8 KB)
  - .github/copilot-instructions.md (2.1 KB)

Cost Summary:
  - Input tokens: 45,230
  - Output tokens: 3,847
  - Total cost: $0.2341

Time: 12.3s
```

**Implementation:**
- Create `file:src/utils/reporter.rs` module
- Add `Report` struct to collect pipeline metrics
- Display summary unless `--quiet` flag is set
- Include file paths, sizes, token counts, costs, and timing

### 8. Add Integration Tests

Create test files in `tests/`:

**`tests/output_formatting_test.rs`:**
- Test each formatter with sample `GeneratedRules`
- Verify output format structure
- Test edge cases (empty rules, missing fields)

**`tests/end_to_end_test.rs`:**
- Test complete pipeline with mock LLM provider
- Verify files are created with correct content
- Test multiple format generation
- Test error handling paths

**Test fixtures:**
- Add sample LLM responses in `tests/fixtures/llm_responses/`
- Add expected output files in `tests/fixtures/expected_outputs/`

### 9. Update Documentation

**Update `file:README.md`:**
- Add usage examples for all supported formats
- Document output file locations
- Add troubleshooting section
- Update status from "Initial development" to "v1.0.0 Release Candidate"

**Update `file:CHANGELOG.md`:**
- Add v1.0.0 release notes with all implemented features
- List supported formats and providers
- Document breaking changes (if any)

**Create `CONTRIBUTING.md`:**
- Guidelines for adding new output formats
- Instructions for adding new LLM providers
- Testing requirements

### 10. Release Preparation

**Version bump:**
- Update `version` in `file:Cargo.toml` from "0.1.0" to "1.0.0"
- Update version references in documentation

**CI/CD verification:**
- Ensure `file:.github/workflows/ci.yml` runs all tests
- Verify `file:.github/workflows/release.yml` is configured for v1.0.0 tag
- Test binary builds for all platforms

**Final validation:**
- Run full test suite: `cargo test --all-features`
- Test CLI with real repositories
- Verify cost estimation accuracy
- Test all output formats with actual LLM providers

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Pipeline
    participant Packer
    participant LLM
    participant Generator
    participant Formatter
    participant Writer

    User->>CLI: ruley --format cursor,claude
    CLI->>Pipeline: Initialize (Stage 1)
    Pipeline->>Packer: Scan files (Stage 2)
    Packer-->>Pipeline: File entries
    Pipeline->>Packer: Compress (Stage 3)
    Packer-->>Pipeline: Compressed codebase
    Pipeline->>LLM: Analyze (Stage 4)
    LLM-->>Pipeline: Analysis result
    Pipeline->>Generator: Parse LLM output
    Generator-->>Pipeline: GeneratedRules
    Pipeline->>Formatter: Format (Stage 5)
    Formatter-->>Pipeline: Formatted content
    Pipeline->>Writer: Write files (Stage 6)
    Writer-->>Pipeline: Files written
    Pipeline->>Pipeline: Validate (Stage 7)
    Pipeline->>Pipeline: Finalize (Stage 8)
    Pipeline->>Pipeline: Report (Stage 9)
    Pipeline->>Pipeline: Cleanup (Stage 10)
    Pipeline-->>User: Success + Summary
```

## Key Files Reference

| Component | Files |
|-----------|-------|
| Pipeline | `file:src/lib.rs` (Stages 5-9 implementation) |
| Prompts | `prompts/base.md`, `prompts/cursor.md`, `prompts/claude.md`, `prompts/copilot.md` |
| Formatters | `file:src/output/cursor.rs`, `file:src/output/claude.rs`, `file:src/output/copilot.rs` |
| Generator | `file:src/generator/rules.rs` (add parsing logic) |
| Utilities | `file:src/utils/validation.rs`, `file:src/utils/reporter.rs` (new files) |
| Tests | `tests/output_formatting_test.rs`, `tests/end_to_end_test.rs` (new files) |
| Config | `file:Cargo.toml` (version bump to 1.0.0) |
| Docs | `file:README.md`, `file:CHANGELOG.md`, `CONTRIBUTING.md` |

---

Execution Information

Branch: main
Commit: 8ff2d91

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#1 - Develop [merged]
#5 - feat(packer): add repomix file parsing and compressed codebase structures [merged]

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!