ace-handbook 0.19.0

data/handbook/guides/atom-pattern.g.md

@@ -0,0 +1,371 @@
+---
+doc-type: guide
+title: ATOM Component Classification House Rules
+purpose: Documentation for ace-handbook/handbook/guides/atom-pattern.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# ATOM Component Classification House Rules
+
+## Overview
+
+This guide provides practical rules and decision-making tools for correctly classifying components within the ATOM architecture used in the Coding Agent Tools project. Understanding these rules is crucial for maintaining code organization, ensuring proper separation of concerns, and preventing architectural drift.
+
+The ATOM architecture organizes code into distinct layers based on complexity and responsibility:
+
+- **Models**: Pure data carriers
+- **Molecules**: Behavior-oriented helpers
+- **Organisms**: Complex business logic units
+- **Atoms**: Basic utilities (foundation layer)
+- **Ecosystems**: Cohesive groupings of organisms
+
+## Why This Matters
+
+Proper component classification ensures:
+
+- **Maintainability**: Clear separation of concerns makes code easier to understand and modify
+- **Reusability**: Components at the right abstraction level can be reused effectively
+- **Testability**: Isolated responsibilities make unit testing straightforward
+- **Architectural Consistency**: Prevents technical debt from accumulating due to misplaced code
+
+## Quick Decision Flowchart
+
+```
+Start: I need to create a new class
+    ↓
+Is it ONLY data with no behavior?
+    ↓ YES                           ↓ NO
+Use Models/                    Does it perform I/O operations?
+(Pure data structures)              ↓ YES                    ↓ NO
+                              Does it orchestrate multiple    Is it a focused utility
+                              components for business logic?  or helper function?
+                                   ↓ YES          ↓ NO            ↓
+                              Use Organisms/  Use Molecules/  Use Atoms/
+                              (Business logic) (I/O helpers)  (Utilities)
+```
+
+## Component Classification Rules
+
+### Models (`lib/coding_agent_tools/models/`)
+
+**Purpose**: Pure data carriers with no external dependencies or side effects.
+
+**Characteristics**:
+
+- Typically implemented as `Struct` classes
+- No I/O operations (no file access, no network calls, no database queries)
+- No external gem dependencies beyond Ruby standard library
+- Focus solely on data representation and basic data manipulation
+- Immutable when possible
+
+**Good Examples**:
+
+```ruby
+# ✅ Good: Pure data structure
+LlmModelInfo = Struct.new(:id, :name, :description, :default, keyword_init: true) do
+  def default?
+    default
+  end
+
+  def to_h
+    {id: id, name: name, description: description, default: default}
+  end
+end
+```
+
+**Bad Examples**:
+
+```ruby
+# ❌ Bad: Contains I/O operations
+class UserProfile < Struct.new(:name, :email)
+  def save_to_file
+    File.write("profile.json", to_json)  # I/O operation!
+  end
+end
+
+# ❌ Bad: Has external dependencies
+class ApiResponse < Struct.new(:data, :status)
+  def parse_with_nokogiri
+    Nokogiri::XML(data)  # External gem dependency!
+  end
+end
+```
+
+### Molecules (`lib/coding_agent_tools/molecules/`)
+
+**Purpose**: Behavior-oriented helpers that encapsulate focused, reusable logic.
+
+**Characteristics**:
+
+- Single responsibility principle
+- May perform I/O operations
+- Compose atoms and other basic utilities
+- Stateless or minimal state
+- Can have external dependencies
+- Focused on "how" to do something
+
+**Good Examples**:
+
+```ruby
+# ✅ Good: Focused helper with specific responsibility
+class HTTPRequestBuilder
+  def initialize(timeout: 30)
+    @timeout = timeout
+  end
+
+  def build_get_request(url, headers = {})
+    # Focused logic for building HTTP requests
+  end
+end
+
+# ✅ Good: Reusable wrapper functionality
+class ExecutableWrapper
+  def initialize(command_path:, registration_method:)
+    @command_path = command_path
+    @registration_method = registration_method
+  end
+
+  def call
+    setup_bundler
+    execute_cli
+  end
+end
+```
+
+**Bad Examples**:
+
+```ruby
+# ❌ Bad: Too much business logic (should be Organism)
+class OrderProcessor
+  def process_order(order)
+    validate_inventory(order)
+    calculate_shipping(order)
+    charge_payment(order)
+    send_confirmation_email(order)
+    update_analytics(order)
+  end
+end
+
+# ❌ Bad: Pure data (should be Model)
+class UserSettings
+  attr_accessor :theme, :language, :notifications
+
+  def initialize(theme:, language:, notifications:)
+    @theme = theme
+    @language = language
+    @notifications = notifications
+  end
+end
+```
+
+### Organisms (`lib/coding_agent_tools/organisms/`)
+
+**Purpose**: Complex units that orchestrate molecules and atoms to achieve business goals.
+
+**Characteristics**:
+
+- Handle complete business use cases
+- Orchestrate multiple components
+- May maintain state across operations
+- Focus on "what" business value to deliver
+- Can be complex and feature-rich
+
+**Good Examples**:
+
+```ruby
+# ✅ Good: Orchestrates multiple components for business purpose
+class GeminiClient
+  def initialize(api_key:)
+    @request_builder = Molecules::HTTPRequestBuilder.new
+    @response_parser = Molecules::APIResponseParser.new
+    @credentials = Molecules::APICredentials.new(api_key)
+  end
+
+  def generate_text(prompt, **options)
+    # Orchestrates request building, API calling, and response parsing
+  end
+
+  def list_models
+    # Complete business operation
+  end
+end
+
+# ✅ Good: Complex business logic coordination
+class PromptProcessor
+  def process_prompt(template, context)
+    # Coordinates template parsing, variable substitution, validation
+  end
+end
+```
+
+**Bad Examples**:
+
+```ruby
+# ❌ Bad: Simple utility (should be Molecule or Atom)
+class StringFormatter
+  def self.capitalize_first(text)
+    text.capitalize
+  end
+end
+
+# ❌ Bad: Pure data structure (should be Model)
+class ConfigurationSettings
+  attr_reader :api_endpoint, :timeout, :retry_count
+
+  def initialize(api_endpoint:, timeout:, retry_count:)
+    @api_endpoint = api_endpoint
+    @timeout = timeout
+    @retry_count = retry_count
+  end
+end
+```
+
+## Decision Checklist
+
+When creating a new class, ask yourself:
+
+### For Models
+
+- [ ] Does this class only hold data?
+- [ ] Are there no I/O operations (file, network, database)?
+- [ ] Are there no external gem dependencies?
+- [ ] Could this be implemented as a Struct?
+- [ ] Does it focus on "what" the data represents?
+
+### For Molecules
+
+- [ ] Does this class perform a specific, focused operation?
+- [ ] Does it compose simpler components (atoms)?
+- [ ] Is it reusable across different contexts?
+- [ ] Does it encapsulate "how" to do something?
+- [ ] Is the responsibility clear and single-focused?
+
+### For Organisms
+
+- [ ] Does this class handle a complete business use case?
+- [ ] Does it orchestrate multiple molecules/atoms?
+- [ ] Is it complex enough to warrant the organism level?
+- [ ] Does it focus on "what" business value to deliver?
+- [ ] Would breaking it down lose important context?
+
+## Common Mistakes and Solutions
+
+### Mistake 1: Data Objects in Wrong Location
+
+**Problem**: Placing pure data structures in `molecules/` or `organisms/`
+
+**Example**:
+
+```ruby
+# ❌ Wrong location: molecules/model.rb
+class Model < Struct.new(:id, :name)
+  def to_s
+    "#{id}: #{name}"
+  end
+end
+```
+
+**Solution**: Move to `models/` and rename appropriately
+
+```ruby
+# ✅ Correct location: models/llm_model_info.rb
+LlmModelInfo = Struct.new(:id, :name, :description, :default, keyword_init: true)
+```
+
+**Teaching Example**: The `LlmModelInfo` class was originally misplaced in `molecules/` but was correctly refactored to `models/` because it's a pure data structure with no I/O operations or external dependencies.
+
+### Mistake 2: Business Logic in Molecules
+
+**Problem**: Putting complex orchestration logic in molecules
+
+**Example**:
+
+```ruby
+# ❌ Wrong: Complex business logic in molecule
+class OrderHandler
+  def process_complete_order(order)
+    validate_order(order)
+    reserve_inventory(order)
+    process_payment(order)
+    ship_order(order)
+    send_notifications(order)
+  end
+end
+```
+
+**Solution**: Move to organisms for complex business coordination
+
+```ruby
+# ✅ Correct: Business orchestration in organism
+class OrderProcessor
+  def initialize
+    @validator = Molecules::OrderValidator.new
+    @inventory = Molecules::InventoryManager.new
+    @payment = Molecules::PaymentProcessor.new
+  end
+end
+```
+
+### Mistake 3: Simple Utilities in Organisms
+
+**Problem**: Over-engineering simple utilities as organisms
+
+**Example**:
+
+```ruby
+# ❌ Wrong: Simple utility as organism
+class TextFormatter
+  def format_currency(amount)
+    "$#{amount.round(2)}"
+  end
+end
+```
+
+**Solution**: Use appropriate level (Atom or Molecule)
+
+```ruby
+# ✅ Correct: Simple utility as atom or molecule
+module Atoms
+  module TextFormatter
+    def self.format_currency(amount)
+      "$#{amount.round(2)}"
+    end
+  end
+end
+```
+
+## Future Enforcement Mechanisms
+
+To maintain these standards as the project grows, consider implementing:
+
+### Automated Checks
+
+- **RuboCop Rules**: Custom cops to detect misplaced components
+- **CI Pipeline Checks**: Automated validation during pull requests
+- **File Naming Conventions**: Enforce naming patterns that reflect component type
+
+### Code Review Guidelines
+
+- **Classification Review**: Every new class should be reviewed for proper placement
+- **Architecture Review**: Periodic reviews of component boundaries
+- **Refactoring Guidelines**: Clear process for moving misplaced components
+
+### Documentation Integration
+
+- **ADR Updates**: Keep Architecture Decision Records synchronized
+- **Cross-References**: Link to this guide from README and CONTRIBUTING files
+- **Examples**: Maintain current examples as the codebase evolves
+
+## Cross-References
+
+- [Architecture Documentation](docs/architecture.md) - Overall system architecture
+- [Coding Standards](./coding-standards.g.md) - General coding practices
+- [Testing Guidelines](guide://testing) - Testing patterns for each component type
+
+## Conclusion
+
+Following these ATOM classification rules ensures our codebase remains maintainable, testable, and architecturally consistent. When in doubt, err on the side of simpler classification (Models before Molecules, Molecules before Organisms) and refactor up in complexity only when the additional abstraction provides clear value.
+
+Remember: The goal is not perfect classification, but consistent and logical organization that serves the team's long-term productivity and code quality goals.

data/handbook/guides/changelog.g.md

@@ -0,0 +1,333 @@
+---
+doc-type: guide
+title: Changelog Writing Guide
+purpose: Documentation for ace-handbook/handbook/guides/changelog.g.md
+ace-docs:
+  last-updated: 2026-03-08
+  last-checked: 2026-03-21
+---
+
+# Changelog Writing Guide
+
+## Goal
+
+This guide provides standards and best practices for writing and maintaining changelogs that effectively communicate project changes to users, contributors, and stakeholders. It ensures consistency, clarity, and usefulness of release documentation.
+
+## Changelog Format
+
+We follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format with project-specific adaptations. All changelogs should be written in Markdown and stored in `CHANGELOG.md` at the project root.
+
+### Standard Structure
+
+```markdown
+# Changelog
+
+All notable changes to this project 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).
+
+## [Unreleased]
+
+### Added
+- New features that have been added
+
+### Changed
+- Changes in existing functionality
+
+### Deprecated
+- Soon-to-be removed features
+
+### Removed
+- Now removed features
+
+### Fixed
+- Any bug fixes
+
+### Security
+- In case of vulnerabilities
+
+## [1.0.0] - 2024-01-15
+
+### Added
+- Initial release with core functionality
+- Basic API endpoints
+- User authentication system
+
+[Unreleased]: https://github.com/user/repo/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0
+```
+
+## Change Categories
+
+Use the following categories to organize changes:
+
+### Added
+
+- New features
+- New API endpoints
+- New configuration options
+- New documentation sections
+- New dependencies
+
+**Example:**
+
+```markdown
+### Added
+- Dark mode toggle in user preferences
+- Support for bulk operations in API
+- Integration with external authentication providers
+```
+
+### Changed
+
+- Changes in existing functionality
+- Updated dependencies
+- Modified default behaviors
+- Improved performance
+- Enhanced user interface
+
+**Example:**
+
+```markdown
+### Changed
+- Improved loading performance by 40%
+- Updated user interface for better accessibility
+- Changed default timeout from 30s to 60s
+```
+
+### Deprecated
+
+- Features that are still available but will be removed
+- API endpoints marked for removal
+- Configuration options being phased out
+
+**Example:**
+
+```markdown
+### Deprecated
+- Legacy authentication API (use v2 endpoints instead)
+- Configuration option `old_setting` (replaced by `new_setting`)
+```
+
+### Removed
+
+- Features that have been completely removed
+- Deleted API endpoints
+- Removed configuration options
+- Dropped support for versions/platforms
+
+**Example:**
+
+```markdown
+### Removed
+- Support for Node.js v14 (minimum version is now v16)
+- Deprecated `/api/v1/legacy` endpoints
+```
+
+### Fixed
+
+- Bug fixes
+- Security patches
+- Performance improvements that fix issues
+- Documentation corrections
+
+**Example:**
+
+```markdown
+### Fixed
+- Memory leak in background processing
+- Incorrect validation error messages
+- Race condition in concurrent requests
+```
+
+### Security
+
+- Security vulnerability fixes
+- Security enhancements
+- Important security-related changes
+
+**Example:**
+
+```markdown
+### Security
+- Fixed XSS vulnerability in user input handling
+- Enhanced password encryption algorithm
+- Updated dependencies to address security advisories
+```
+
+## Writing Guidelines
+
+### 1. Use Clear, Action-Oriented Language
+
+**Good:**
+
+- "Added user authentication system"
+- "Fixed memory leak in data processing"
+- "Improved API response time by 25%"
+
+**Avoid:**
+
+- "Some changes to auth"
+- "Fixed stuff"
+- "Performance improvements"
+
+### 2. Include Context and Impact
+
+**Good:**
+
+```markdown
+### Changed
+- Updated password requirements to include special characters for enhanced security
+- Increased default session timeout from 30 minutes to 2 hours based on user feedback
+```
+
+**Avoid:**
+
+```markdown
+### Changed
+- Password validation
+- Session timeout
+```
+
+### 3. Reference Issues and Pull Requests
+
+When applicable, link to relevant issues, pull requests, or task documentation:
+
+```markdown
+### Fixed
+- Resolved database connection timeout issue ([#123](https://github.com/user/repo/issues/123))
+- Fixed user profile update validation ([PR #145](https://github.com/user/repo/pull/145))
+- Corrected task workflow documentation inconsistencies (Task v.0.3.0+task.14)
+```
+
+### 4. Group Related Changes
+
+```markdown
+### Added
+- User management dashboard with the following features:
+  - Create and edit user accounts
+  - Assign roles and permissions
+  - View user activity logs
+  - Export user data
+```
+
+### 5. Use Consistent Formatting
+
+- Start each item with a capital letter
+- Use present tense ("Add" not "Added")
+- End with a period for complete sentences
+- Use bullet points for lists
+- Maintain consistent indentation
+
+## Process Guidelines
+
+### When to Update the Changelog
+
+1. **During Development:**
+   - Add entries to the `[Unreleased]` section as features are completed
+   - Update immediately after merging significant changes
+   - Include changelog updates in the same commit/PR as the feature
+
+2. **Before Release:**
+   - Review all `[Unreleased]` entries for accuracy and completeness
+   - Move entries from `[Unreleased]` to the new version section
+   - Add release date and version links
+   - Ensure all significant changes are documented
+
+3. **After Release:**
+   - Verify the changelog accurately reflects the released version
+   - Start a new `[Unreleased]` section for future changes
+
+### Who Is Responsible
+
+- **Developers:** Add changelog entries for their own changes
+- **Release Manager:** Review and finalize changelog before release
+- **Project Lead:** Ensure changelog standards are followed
+
+### Integration with Release Process
+
+The changelog should be updated as part of the standard release workflow:
+
+1. **During Development:** Maintain `[Unreleased]` section
+2. **Pre-Release:** Review and organize entries
+3. **Version Bump:** Move entries to versioned section
+4. **Release:** Publish changelog with release notes
+5. **Post-Release:** Verify accuracy and completeness
+
+## Version Linking
+
+Include comparison links at the bottom of the changelog:
+
+```markdown
+[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/user/repo/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0
+```
+
+For projects without public repositories, use internal tracking systems or omit links if not applicable.
+
+## Common Mistakes to Avoid
+
+1. **Overly Technical Language:** Write for users, not just developers
+2. **Missing Context:** Explain why changes were made when relevant
+3. **Inconsistent Categories:** Use the standard categories consistently
+4. **Burying Important Changes:** Put breaking changes and security fixes prominently
+5. **Incomplete Information:** Include all user-facing changes
+6. **Late Updates:** Don't wait until release to update the changelog
+
+## Examples
+
+### Good Changelog Entry
+
+```markdown
+## [2.1.0] - 2024-03-15
+
+### Added
+- Real-time notifications for task updates with configurable preferences
+- Bulk task operations (mark complete, assign, delete) in project dashboard
+- Export functionality for project reports in CSV and PDF formats
+- Integration with external calendar systems (Google Calendar, Outlook)
+
+### Changed
+- Improved task loading performance by implementing pagination (loads 50% faster)
+- Enhanced user interface with improved accessibility features and keyboard navigation
+- Updated email templates for better mobile responsiveness
+
+### Fixed
+- Resolved issue where task assignments were not triggering notifications ([#234](link))
+- Fixed memory leak in real-time update system that occurred during long sessions
+- Corrected timezone handling in deadline calculations for international teams
+
+### Security
+- Updated authentication library to address potential session fixation vulnerability
+- Enhanced input validation to prevent XSS attacks in task descriptions
+```
+
+### Poor Changelog Entry
+
+```markdown
+## [2.1.0] - 2024-03-15
+
+### Added
+- Notifications
+- Bulk operations
+- Export stuff
+
+### Changed
+- Performance improvements
+- UI updates
+
+### Fixed
+- Various bugs
+- Memory issues
+```
+
+## Related Documentation
+
+- [Version Control Message Guide](./version-control-system-message.g.md) (Commit message standards)
+- [Project Management Guide](./project-management.g.md) (Release workflow integration)
+- [Publish Release Workflow](wfi://release/publish) (Release process overview and step-by-step actions)
+- [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) (External reference)
+- [Semantic Versioning](https://semver.org/) (Versioning standards)