CrowdCode needed comprehensive documentation enabling maintainers to understand and safely trial the vote-gated, AI-assisted development workflow with full awareness of security implications and control mechanisms.

Documentation Structure

Core Documentation (5 new files)

• docs/index.md - Glossary (Issue → PR → Vote → Promote), role definitions, navigation hub
• docs/setup.md - Installation (files, labels, permissions, secrets, schedules), verification checklist
• docs/workflows.md - All 4 GitHub Actions workflows with disable methods (4 per workflow)
• docs/governance.md - PatchPanel membership, vote counting (reactions vs reviews), conflict resolution
• docs/threat-model.md - 8 threat categories with mitigations (prompt injection, spam, malicious PRs, vote manipulation, dependency attacks, hallucinations, workflow compromise, privacy violations)

README Updates

• Quick trial path for test repositories
• Updated navigation to new documentation structure

Safety Emphasis

Every workflow has documented disable mechanisms:

# Option 1: Delete workflow
git rm .github/workflows/crowdcode-issue-to-pr.yml

# Option 2: Rename (easy re-enable)
mv .github/workflows/crowdcode-issue-to-pr.yml{,.disabled}

# Option 3: Disable AI generation only
ai_generation:
  enabled: false

# Option 4: Manual trigger only (remove schedule)

Data Privacy

Explicitly documents what data flows to model providers:

• ✅ Sent: Issue descriptions, repository context
• ❌ Never sent: Secrets, PII, vote tallies, PatchPanel membership

Role Definitions

Threat Analysis

Comprehensive security coverage with attack scenarios and mitigations:

• Malicious feature requests → Human review + vote threshold + CI gates
• Spam issues → Rate limiting (max 5/run) + interaction restrictions
• Vote manipulation → Membership file in Git + CODEOWNERS protection
• Dependency attacks → Dependency review action + package verification checklist

Total: ~3,400 lines covering installation, automation, governance, and security for safe trial adoption.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.