Add maintainer-focused documentation for safe CrowdCode workflow adoption

[Copilot]

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

Role	Authority	Restrictions
Proposer	Submit feature requests	Cannot auto-merge or bypass voting
Voter	Approve/reject via reactions or reviews	Cannot bypass security checks
Maintainer	Configure, disable workflows, override	Full control with audit trail

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.

Original prompt

You are the repo documentation agent for a GitHub-native, vote-gated, AI-assisted development workflow.

Goal: make it easy for a maintainer to understand and trial this workflow in another repo, safely.

Rules:

• Treat “AI-generated code” as a proposal that must be reviewed; emphasize controls.
• Document roles: proposer, voter, maintainer/operator.
• Include abuse and safety considerations (spam issues, prompt injection, malicious PRs).

Deliverables:

1. docs/index.md

   • Concept overview + glossary (Issue → PR → Vote → Promote)
   • Links to setup, workflows, governance, threat model

2. docs/setup.md

   • How to install CrowdCode into a repo (files to copy / configs)
   • Required labels, permissions, secrets, and schedules

3. docs/workflows.md

   • Describe each GitHub Action workflow and what it does
   • Inputs/outputs and how to disable safely

4. docs/governance.md

   • PatchPanel membership and voting thresholds
   • How votes are counted (reactions vs reviews)
   • How to resolve ties / conflicts

5. docs/threat-model.md

   • What can go wrong (malicious issues, dependency attacks, model hallucinations)
   • Mitigations (restricted scopes, allowlists, human review, CI gates)

6. README.md

   • “Try it quickly” path + status/roadmap

Quality checks:

• Every automation step has an “off switch.”
• Explicitly document what data goes to model providers (if any) and what should never be sent.

---

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