Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
122 lines (89 loc) · 3.05 KB

CONTRIBUTING.md

File metadata and controls

122 lines (89 loc) · 3.05 KB

Contributing to agentful

Thank you for your interest in contributing to agentful!

🎯 How to Contribute

Reporting Issues

  • Search existing issues first
  • Use the issue templates
  • Include: steps to reproduce, expected behavior, actual behavior
  • Add screenshots if applicable

Submitting Pull Requests

  1. Fork the repository
  2. Create a feature branch: git checkout -b my-feature
  3. Make your changes
  4. Test thoroughly
  5. Commit with clear messages
  6. Push and create a PR

Development Setup

# Clone your fork
git clone https://github.com/YOUR-USERNAME/agentful.git
cd agentful

# Install dependencies (if we add any)
npm install

# Test CLI locally
node bin/cli.js --help

Working with .claude/ Directory

Agentful uses a two-layer protection system for the .claude/ configuration:

template/.claude/ - Source of truth

  • Clean templates distributed via npm
  • Version controlled in git
  • Edit these files when making changes to agents, commands, or skills
  • Never modified by agentful itself

.claude/ - Working directory

  • Gitignored for testing/development
  • Auto-restored by post-merge hook if corrupted
  • Safe for experimenting without affecting templates

Development workflow:

# 1. Make changes to templates (source of truth)
vim template/.claude/agents/my-agent.md

# 2. Sync to working directory for testing
cp -r template/.claude/ .claude/

# 3. Test your changes
node bin/cli.js --help

Protection mechanism:

  • .git/hooks/post-merge automatically restores .claude/ after git operations
  • Prevents accidental deletion during merges/pulls
  • See CLAUDE_PROTECTION.md for full details

📁 Project Structure

agentful/
├── template/.claude/    # Source templates (version controlled, distributed via npm)
│   ├── agents/          # Specialist agents
│   ├── commands/        # Slash commands
│   ├── skills/          # Domain skills
│   └── settings.json    # Hooks and permissions
├── .claude/             # Working directory (gitignored, for testing)
├── bin/                 # CLI tool
├── template/            # Other template files for new projects
├── docs/                # Documentation site
└── README.md            # Main readme

🧪 Testing

When adding new agents or commands:

  1. Test in a fresh project
  2. Verify all quality gates pass
  3. Test with different tech stacks
  4. Document in README.md

📝 Documentation

Keep documentation in sync with code:

  • Update README.md for user-facing changes
  • Add inline comments in agent files
  • Update docs/ site for major features

🎨 Code Style

  • Use clear, descriptive names
  • Write for clarity first, cleverness second
  • Comment complex logic
  • Follow existing patterns

🤝 Community Guidelines

  • Be respectful and constructive
  • Welcome newcomers
  • Focus on what's best for the community
  • Show empathy

📧 Contact

  • GitHub Issues: For bugs and feature requests
  • Discussions: For questions and ideas

Thank you for contributing! 🎉