Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
275 lines (185 loc) · 6.33 KB

CONTRIBUTING.md

File metadata and controls

275 lines (185 loc) · 6.33 KB

Contributing to AI-Agnostic Development Framework

First off, thank you for considering contributing to this project! 🎉

This framework was built by developers, for developers, and we welcome contributions from the community.

🤝 How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues. When creating a bug report, include:

  • Clear title and description
  • Steps to reproduce the issue
  • Expected behavior vs actual behavior
  • Your environment (OS, AI assistant, versions)
  • Screenshots if applicable

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

  • Use a clear and descriptive title
  • Provide detailed description of the suggested enhancement
  • Explain why this enhancement would be useful
  • Include examples of how it would work

Pull Requests

  1. Fork the repository
  2. Create a branch from main
  3. Make your changes
  4. Test your changes thoroughly
  5. Update documentation if needed
  6. Submit a pull request

📝 Development Guidelines

Agent Contributions

If you're adding a new agent:

  1. Place in appropriate phase directory

    • agents/00-planning/ - Planning phase agents
    • agents/01-documentation/ - Documentation phase agents
    • agents/02-implementation/ - Implementation phase agents
    • agents/03-validation/ - Validation phase agents

  2. Follow agent template structure:

    # Agent Name

**Role**: Brief description
**Phase**: Planning/Documentation/Implementation/Validation

## Agent Metadata
```yaml
name: agent-name
description: What this agent does
version: 1.0
category: planning|documentation|implementation|validation
tags: [tag1, tag2]

    Your Role

    [Detailed description]

    When to Invoke This Agent

    [Triggers and conditions]

    [Rest of agent definition]

  3. Update agents/README.md with new agent

  4. Update .cursorrules with routing logic if needed

Template Contributions

If you're adding templates:

  1. Place in templates/new-project/ or appropriate subdirectory
  2. Use clear variable names: [VARIABLE_NAME]
  3. Include usage instructions at the top
  4. Update templates/README.md

Script Contributions

If you're adding scripts:

  1. Place in scripts/ directory
  2. Make executable: chmod +x scripts/your-script.sh
  3. Include help text: your-script.sh --help
  4. Add error handling and validation
  5. Use consistent style (follow existing scripts)
  6. Update documentation

Documentation Contributions

  • Keep documentation clear and concise
  • Use examples where helpful
  • Update INDEX.md if adding new docs
  • Check for broken links

🎨 Style Guidelines

Markdown

  • Use ATX-style headers (#, ##, ###)
  • Use fenced code blocks with language identifiers
  • Keep lines under 120 characters where possible
  • Use tables for structured data

Shell Scripts

  • Use bash shebangs: #!/usr/bin/env bash
  • Set error handling: set -e
  • Include comments for complex logic
  • Use functions for reusability
  • Validate inputs

YAML

  • Use 2-space indentation
  • Quote strings with special characters
  • Keep structure consistent with existing files

🧪 Testing

Before submitting a PR:

  1. Test scripts in clean environment
  2. Validate templates can be instantiated
  3. Check agents work with AI assistant
  4. Run prerequisites check script
  5. Verify documentation accuracy

📚 Documentation Standards

Agent Documentation

  • Clear role description
  • Specific invocation triggers
  • Input/output specifications
  • Examples of usage
  • Integration with other agents

Template Documentation

  • Purpose and use case
  • Variable descriptions
  • Usage instructions
  • Examples

Script Documentation

  • Purpose and functionality
  • Usage examples
  • Command-line options
  • Exit codes

🏷️ Git Commit Messages

Use conventional commit format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples:

feat(agents): add Python backend engineer agent

Add specialized agent for Python/FastAPI backend development.
Includes SQLAlchemy and Pydantic support.

Closes #42

docs(readme): update quick start instructions

Clarify prerequisites checking step and add troubleshooting section.

🔍 Code Review Process

  1. Automated checks must pass
  2. Maintainer review required
  3. Changes requested addressed
  4. Approved by at least one maintainer
  5. Merged to main

📦 Release Process

Releases follow semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes

🤔 Questions?

📜 Code of Conduct

Our Pledge

We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Positive behavior:

  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members

Unacceptable behavior:

  • Trolling, insulting/derogatory comments, and personal attacks
  • Public or private harassment
  • Publishing others' private information without permission
  • Other conduct which could reasonably be considered inappropriate

Enforcement

Project maintainers will remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct.

🙏 Thank You!

Your contributions help make this framework better for everyone. We appreciate your time and effort!

Happy Contributing! 🚀