Update README.md and CONTRIBUTING.md to enhance project visibility and support for new contributors. Added PyPI version and download badges, build status, and latest release information to README.md. Introduced a section in CONTRIBUTING.md for finding good first issues, providing guidance for beginners on how to contribute effectively.

2026-04-24 16:26:35 +02:00 · 2026-01-13 21:39:50 +08:00 · 2026-01-13 21:39:50 +08:00 · 2f4f2270b5
commit 2f4f2270b5
parent d1aaa626c9
7 changed files with 266 additions and 0 deletions
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@ -0,0 +1,45 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Description
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+1. Go to '...'
+2. Run command '...'
+3. See error
+
+## Expected Behavior
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+A clear and concise description of what actually happened.
+
+## Environment
+- **flakestorm version**: (e.g., 0.9.0)
+- **Python version**: (e.g., 3.10.5)
+- **Operating System**: (e.g., Windows 10, macOS 14.0, Ubuntu 22.04)
+- **Ollama version** (if applicable): (e.g., 0.1.0)
+
+## Configuration
+If applicable, include relevant parts of your `flakestorm.yaml` configuration (remove any sensitive information):
+
+```yaml
+# Your configuration here
+```
+
+## Error Messages / Logs
+```
+Paste any error messages or logs here
+```
+
+## Additional Context
+Add any other context about the problem here. Include:
+- Screenshots if applicable
+- Related issues
+- Workarounds you've tried
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://flakestorm.dev/docs
+    about: Check our documentation for usage guides and examples
+  - name: Community Discussions
+    url: https://github.com/flakestorm/flakestorm/discussions
+    about: Ask questions and share ideas with the community
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@ -0,0 +1,30 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+A clear and concise description of the feature you'd like to see.
+
+## Problem Statement
+What problem does this feature solve? What use case does it address?
+
+## Proposed Solution
+Describe how you envision this feature working. Include:
+- User-facing changes (CLI, config, etc.)
+- Technical approach (if you have ideas)
+- Examples of how it would be used
+
+## Alternatives Considered
+Describe any alternative solutions or features you've considered.
+
+## Additional Context
+- Is this feature related to a specific use case?
+- Would this be better suited for the cloud version?
+- Any related issues or discussions?
+
+## Implementation Notes (Optional)
+If you're planning to implement this yourself, outline your approach here.
--- a/.github/ISSUE_TEMPLATE/question.md
+++ b/.github/ISSUE_TEMPLATE/question.md
@ -0,0 +1,24 @@
+---
+name: Question
+about: Ask a question about flakestorm
+title: '[QUESTION] '
+labels: question
+assignees: ''
+---
+
+## Question
+What would you like to know?
+
+## Context
+Provide any relevant context:
+- What are you trying to accomplish?
+- What have you tried so far?
+- What documentation have you reviewed?
+
+## Environment (if relevant)
+- **flakestorm version**: (e.g., 0.9.0)
+- **Python version**: (e.g., 3.10.5)
+- **Operating System**: (e.g., Windows 10, macOS 14.0, Ubuntu 22.04)
+
+## Additional Information
+Any other information that might help answer your question.
--- a/README.md
+++ b/README.md
@ -12,6 +12,18 @@
  <a href="https://github.com/flakestorm/flakestorm">
    <img src="https://img.shields.io/github/stars/flakestorm/flakestorm?style=social" alt="GitHub Stars">
  </a>
+  <a href="https://pypi.org/project/flakestorm/">
+    <img src="https://img.shields.io/pypi/v/flakestorm.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/flakestorm/">
+    <img src="https://img.shields.io/pypi/dm/flakestorm.svg" alt="PyPI downloads">
+  </a>
+  <a href="https://github.com/flakestorm/flakestorm/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/flakestorm/flakestorm/ci.yml?branch=main" alt="Build Status">
+  </a>
+  <a href="https://github.com/flakestorm/flakestorm/releases">
+    <img src="https://img.shields.io/github/v/release/flakestorm/flakestorm" alt="Latest Release">
+  </a>
 </p>

 ---
@ -162,6 +174,13 @@ That's it! You'll get a robustness score and detailed report showing how your ag



+## Roadmap
+
+See what's coming next! Check out our [Roadmap](ROADMAP.md) for upcoming features including:
+- 🚀 Pattern Engine Upgrade with 110+ Prompt Injection Patterns and 52+ PII Detection Patterns
+- ☁️ Cloud Version enhancements (scalable runs, team collaboration, continuous testing)
+- 🏢 Enterprise features (on-premise deployment, custom patterns, compliance certifications)
+
 ## Documentation

 ### Getting Started
--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -0,0 +1,120 @@
+# Flakestorm Roadmap
+
+This roadmap outlines the exciting features and improvements coming to Flakestorm. We're building the most comprehensive chaos engineering platform for production AI agents.
+
+## 🚀 Upcoming Features
+
+### Pattern Engine Upgrade (Q1 2026)
+
+We're upgrading Flakestorm's core detection engine with a high-performance Rust implementation featuring pre-configured pattern databases.
+
+#### **110+ Prompt Injection Patterns**
+- **10 Categories**: Direct Override, Role Manipulation, DAN/Jailbreak, Context Injection, Instruction Override, System Prompt Leakage, Output Format Manipulation, Multi-turn Attacks, Encoding Bypasses, and Advanced Evasion Techniques
+- **Hybrid Detection**: Aho-Corasick algorithm + Regex matching for <50ms detection latency
+- **Pattern Database**: Comprehensive collection from `veraxiv-core/patterns/prompt-injection-patterns.toml`
+- **Real-time Updates**: Pattern database updates without engine restarts
+
+#### **52+ PII Detection Patterns**
+- **8 Categories**: Identification (SSN, Passport, Driver's License), Financial (Credit Cards, Bank Accounts, IBAN), Contact (Email, Phone, Address), Health (Medical Records, Insurance IDs), Location (GPS, IP Addresses), Biometric (Fingerprints, Face Recognition), Credentials (Passwords, API Keys, Tokens), and Sensitive Data (Tax IDs, Social Security Numbers)
+- **Severity-Weighted Scoring**: Each pattern includes severity levels (Critical, High, Medium, Low) with validation functions
+- **Pattern Database**: From `veraxiv-core/patterns/pii-detection-patterns.toml`
+- **Compliance Ready**: GDPR, HIPAA, PCI-DSS pattern coverage
+
+#### **Performance Improvements**
+- **Sub-50ms Detection**: Rust-native implementation for ultra-fast pattern matching
+- **Zero-Copy Processing**: Efficient memory handling for large-scale mutation runs
+- **Parallel Pattern Matching**: Multi-threaded detection for concurrent mutation analysis
+
+### Cloud Version Enhancements (Q1-Q2 2026)
+
+#### **Enterprise-Grade Infrastructure**
+- **Scalable Mutation Runs**: Process thousands of mutations in parallel
+- **Distributed Architecture**: Multi-region deployment for global teams
+- **High Availability**: 99.9% uptime SLA with automatic failover
+- **Enterprise SSO**: SAML, OAuth, and LDAP integration
+
+#### **Advanced Analytics & Reporting**
+- **Historical Trend Analysis**: Track robustness scores over time
+- **Comparative Reports**: Compare agent versions side-by-side
+- **Custom Dashboards**: Build team-specific views with drag-and-drop widgets
+- **Export Capabilities**: PDF, CSV, JSON exports for compliance and reporting
+
+#### **Team Collaboration**
+- **Shared Workspaces**: Organize agents by team, project, or environment
+- **Role-Based Access Control**: Fine-grained permissions for teams and individuals
+- **Comment Threads**: Discuss failures and improvements directly in reports
+- **Notification System**: Slack, Microsoft Teams, email integrations
+
+#### **Continuous Chaos Testing**
+- **Scheduled Runs**: Automated chaos tests on cron schedules
+- **Git Integration**: Automatic testing on commits, PRs, and releases
+- **CI/CD Plugins**: Native integrations for GitHub Actions, GitLab CI, Jenkins
+- **Webhook Support**: Trigger chaos tests from external systems
+
+### Enterprise Version Features (Q2-Q3 2026)
+
+#### **Advanced Security & Compliance**
+- **On-Premise Deployment**: Self-hosted option for air-gapped environments
+- **Audit Logging**: Complete audit trail of all chaos test activities
+- **Data Residency**: Control where your test data is stored and processed
+- **Compliance Certifications**: SOC 2, ISO 27001, GDPR-ready
+
+#### **Custom Pattern Development**
+- **Pattern Builder UI**: Visual interface for creating custom detection patterns
+- **Pattern Marketplace**: Share and discover community patterns
+- **ML-Based Pattern Learning**: Automatically learn new attack patterns from failures
+- **Pattern Versioning**: Track pattern changes and rollback if needed
+
+#### **Advanced Mutation Strategies**
+- **Industry-Specific Mutations**: Healthcare, Finance, Legal domain patterns
+- **Regulatory Compliance Testing**: HIPAA, PCI-DSS, GDPR-specific mutation sets
+- **Custom Mutation Engines**: Plugin architecture for domain-specific mutations
+- **Adversarial ML Attacks**: Gradient-based and black-box attack strategies
+
+#### **Enterprise Support**
+- **Dedicated Support Channels**: Priority support with SLA guarantees
+- **Professional Services**: Custom implementation and training
+- **White-Glove Onboarding**: Expert-guided setup and configuration
+- **Quarterly Business Reviews**: Strategic planning sessions
+
+### Open Source Enhancements (Ongoing)
+
+#### **Core Engine Improvements**
+- **Additional Mutation Types**: Expanding beyond 22+ core types
+- **Better Invariant Assertions**: More sophisticated validation rules
+- **Enhanced Reporting**: More detailed failure analysis and recommendations
+- **Performance Optimizations**: Faster mutation generation and execution
+
+#### **Developer Experience**
+- **Better Documentation**: More examples, tutorials, and guides
+- **SDK Development**: Python SDK for programmatic chaos testing
+- **Plugin System**: Extensible architecture for custom mutations and assertions
+- **Debugging Tools**: Better error messages and troubleshooting guides
+
+#### **Community Features**
+- **Example Gallery**: Curated collection of real-world test scenarios
+- **Community Patterns**: Share and discover mutation patterns
+- **Contributor Recognition**: Highlighting community contributions
+- **Monthly Office Hours**: Live Q&A sessions with the team
+
+## 📅 Timeline
+
+- **Q1 2026**: Pattern Engine Upgrade, Cloud Beta Launch
+- **Q2 2026**: Cloud General Availability, Enterprise Beta
+- **Q3 2026**: Enterprise General Availability, Advanced Features
+- **Ongoing**: Open Source Improvements, Community Features
+
+## 🤝 Contributing
+
+Want to help us build these features? Check out our [Contributing Guide](docs/CONTRIBUTING.md) and look for issues labeled `good first issue` to get started!
+
+## 💬 Feedback
+
+Have ideas or suggestions? We'd love to hear from you:
+- Open an issue with the `enhancement` label
+- Join our [Discussions](https://github.com/flakestorm/flakestorm/discussions)
+- Reach out to the team directly
+
+---
+
+**Note**: This roadmap is subject to change based on community feedback and priorities. We're committed to building the best chaos engineering platform for AI agents, and your input shapes our direction.
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@ -140,6 +140,26 @@ flakestorm/

 ## How to Contribute

+### Finding Good First Issues
+
+New to contributing? Look for issues labeled `good first issue` on GitHub. These are specifically curated for beginners and include:
+- Clear problem statements
+- Well-defined scope
+- Helpful guidance in the issue description
+- Good learning opportunities
+
+To find them:
+1. Go to [Issues](https://github.com/flakestorm/flakestorm/issues)
+2. Filter by label: `good first issue`
+3. Read the issue description and ask questions if needed
+4. Comment on the issue to let others know you're working on it
+
+**Note for Maintainers**: To add `good first issue` labels to beginner-friendly issues:
+- Look for issues that are well-scoped and have clear acceptance criteria
+- Add the `good first issue` label via GitHub's web interface
+- Ensure the issue description includes context and guidance for new contributors
+- Consider 5-10 issues at a time to give beginners options
+
 ### Reporting Bugs

 1. Check existing issues first