Technical Design: phase-1-community-governance

Technical Design: phase-1-community-governance

Metadata

• Feature: phase-1-community-governance
• Status: DRAFT
• Created: 2026-02-07
• Author: Factory Design Mode
• Parent Epic: #179 (ZERG Public Release)
• Issues: #185, #186, #187, #188

1. Overview

1.1 Summary

Add standard open-source community infrastructure to the ZERG repository: GitHub issue templates (bug report, feature request, config), PR template, Code of Conduct, Dependabot configuration, README badges, GitHub topics, secret scanning + push protection, SECURITY.md version update, and CONTRIBUTING.md CoC link. All changes are static configuration files with no runtime code impact.

1.2 Goals

• Structured bug reports and feature requests via YAML form templates
• Consistent PR descriptions via template
• Clear community standards via Contributor Covenant v2.1
• Automated dependency vulnerability alerts via Dependabot
• At-a-glance project health via README badges
• GitHub discoverability via repository topics
• Secret leak prevention via secret scanning + push protection
• Accurate supported-versions table in SECURITY.md

1.3 Non-Goals

• CodeQL workflow (Phase 2, #189)
• mypy in CI (Phase 2, #189)
• mkdocs documentation site (Phase 2, #190)
• Making the repo public (separate decision)
• Terminal demo / social preview (Phase 3, #191)

2. Architecture

2.1 High-Level Design

This feature is entirely static configuration — no runtime components, no data flow, no services. The "architecture" is a file layout under .github/ and modifications to root-level docs.

.github/
├── ISSUE_TEMPLATE/
│   ├── bug_report.yml          # TASK-001 (new)
│   ├── feature_request.yml     # TASK-002 (new)
│   └── config.yml              # TASK-003 (new)
├── PULL_REQUEST_TEMPLATE.md    # TASK-004 (new)
└── dependabot.yml              # TASK-005 (new)

CODE_OF_CONDUCT.md              # TASK-006 (new)
README.md                       # TASK-007 (modify — badges)
SECURITY.md                     # TASK-008 (modify — versions)
CONTRIBUTING.md                 # TASK-009 (modify — CoC link)
CHANGELOG.md                    # TASK-010 (modify — Phase 1 entries)

2.2 Component Breakdown

2.3 Data Flow

N/A — static configuration files. No runtime data flow.

3. Detailed Design

3.1 Bug Report Template (FR-001)

.github/ISSUE_TEMPLATE/bug_report.yml — YAML form with fields:

• name: Bug Report
• description: Report a bug in ZERG
• labels: bug
• body fields: description (textarea, required), repro steps (textarea, required), expected behavior (textarea, required), actual behavior (textarea, required), ZERG version (input, required), Python version (input, required), OS (dropdown), logs (textarea, optional)

3.2 Feature Request Template (FR-002)

.github/ISSUE_TEMPLATE/feature_request.yml — YAML form with fields:

• name: Feature Request
• description: Suggest a new feature
• labels: enhancement
• body fields: problem statement (textarea, required), proposed solution (textarea, required), alternatives considered (textarea, optional), additional context (textarea, optional)

3.3 Issue Config (FR-003)

.github/ISSUE_TEMPLATE/config.yml:

• blank_issues_enabled: false
• Contact links: Discussions (questions), SECURITY.md (vulnerabilities)

3.4 PR Template (FR-004)

.github/PULL_REQUEST_TEMPLATE.md — Sections:

• Summary (what and why)
• Changes (bulleted list)
• Test Plan (how to verify)
• Checklist: tests pass, CHANGELOG updated, ruff/mypy clean

3.5 Code of Conduct (FR-005)

CODE_OF_CONDUCT.md — Contributor Covenant v2.1, enforcement contact via GitHub Security Advisories link (per Q-002 resolution).

3.6 Dependabot Config (FR-006)

.github/dependabot.yml:

• package-ecosystem: pip
• directory: "/"
• schedule.interval: weekly
• labels: ["dependencies"]
• reviewers: ["rocklambros"]

3.7 Secret Scanning + Push Protection (FR-007, FR-008)

Enable via gh api commands:

gh api repos/rocklambros/zerg -X PATCH -f security_and_analysis[secret_scanning][status]=enabled
gh api repos/rocklambros/zerg -X PATCH -f security_and_analysis[secret_scanning_push_protection][status]=enabled

3.8 README Badges (FR-009)

Add badge row after the logo block:

• PyPI version: https://img.shields.io/pypi/v/zerg-ai
• Python version: https://img.shields.io/pypi/pyversions/zerg-ai
• License: https://img.shields.io/github/license/rocklambros/zerg
• CI status: https://img.shields.io/github/actions/workflow/status/rocklambros/zerg/ci.yml?branch=main

3.9 GitHub Topics (FR-010)

Set via gh api:

gh api repos/rocklambros/zerg/topics -X PUT -f names='["claude-code","parallel-execution","ai-coding","cli","python","developer-tools","automation","code-generation","llm"]'

3.10 SECURITY.md Update (FR-012)

Add 0.2.x | Yes row, keep 0.1.x | Yes.

3.11 CONTRIBUTING.md Update

Add CoC reference in the introductory section, linking to CODE_OF_CONDUCT.md.

3.12 License Compatibility Audit (FR-011)

Verify all runtime dependencies are MIT/BSD/Apache compatible:

• click (BSD-3), pydantic (MIT), pyyaml (MIT), rich (MIT)
• Dev deps: pytest (MIT), ruff (MIT), mypy (MIT), pre-commit (MIT)

4. Key Decisions

Decision: YAML Form Templates vs Markdown Templates

Context: GitHub supports both markdown-based and YAML form-based issue templates.

Options Considered:

1. Markdown templates: Simpler, but users can ignore/delete fields
2. YAML forms: Renders as structured form in GitHub UI, fields can be required

Decision: YAML forms

Rationale: Required fields ensure bug reports include repro steps and version info. Forms provide better UX for non-technical reporters.

Consequences: Templates use .yml extension, require specific YAML schema.

Decision: Enforcement Contact for Code of Conduct

Context: Contributor Covenant requires an enforcement contact.

Options Considered:

1. Personal email: Exposes maintainer email publicly
2. GitHub Security Advisories link: Private, built-in to GitHub

Decision: GitHub Security Advisories link (per Q-002 resolution)

Rationale: No personal email exposure. GitHub provides private reporting infrastructure.

Consequences: Enforcement section links to https://github.com/rocklambros/zerg/security/advisories/new.

5. Implementation Plan

5.1 Phase Summary

5.2 File Ownership

5.3 Dependency Graph

graph TD
    T001[TASK-001: Bug report template] --> T010[TASK-010: CHANGELOG]
    T002[TASK-002: Feature request template] --> T010
    T003[TASK-003: Issue config] --> T010
    T004[TASK-004: PR template] --> T010
    T005[TASK-005: Dependabot config] --> T010
    T006[TASK-006: Code of Conduct] --> T009[TASK-009: CONTRIBUTING.md CoC link]
    T006 --> T010
    T007[TASK-007: README badges] --> T010
    T008[TASK-008: SECURITY.md update] --> T010
    T009 --> T010

6. Risk Assessment

7. Testing Strategy

7.1 Validation

• YAML syntax validation for all .yml files
• Markdown lint for .md files
• gh api response verification for topics/secret scanning
• CI passes on PR (existing quality, smoke, test, audit checks)

7.2 Verification Commands

Each task has a verification command that confirms correctness without relying on GitHub UI rendering.

8. Parallel Execution Notes

8.1 Safe Parallelization

• Level 1: 6 tasks with no dependencies, fully parallel
• Level 2: CONTRIBUTING.md depends on CoC (TASK-006)
• Level 3: CHANGELOG depends on all other tasks
• No two tasks modify the same file

8.2 Recommended Workers

• Minimum: 1 worker (sequential, ~20 min)
• Optimal: 6 workers (Level 1 fully parallel)
• Maximum: 6 workers (diminishing returns beyond — L2/L3 are narrow)

8.3 Estimated Duration

• Single worker: ~20 minutes
• With 6 workers: ~8 minutes
• Speedup: ~2.5x

9. Consumer Matrix

Note: All tasks are leaf or near-leaf. This is a static config feature — no production Python/JS modules are created, so integration tests are not applicable. Validation is via YAML/Markdown syntax checks and CI.

10. Approval