Skip to content

docs: update README.md to reflect sync architecture #85

Description

@wcmchenry3-stack

Context

The current README.md contains misleading language suggesting community health files "auto-apply" to org repos. This is false — GitHub's auto-serving only works for public .github repos, and even then only serves files not present in the individual repo. The actual mechanism is the explicit sync-community-health.yml push workflow.

Additionally, the README does not document:

  • The 6 target repos that receive synced content
  • Which files are synced vs which remain meta-repo only
  • That the repo is intended to go private (and that sync is the reason it's safe to do so)

Implementation

Edit README.md to:

  1. Remove the false "auto-apply" claim — replace with accurate description of sync-community-health.yml as an explicit push workflow

  2. Add a "Sync Architecture" section listing:

    • The 6 target org repos (e.g., gaming_app, book_app, etc.)
    • What gets synced: community health files, Claude Code hooks and agents, settings.json merge
    • What does NOT get synced: .claude/policies/, CODEOWNERS, dependabot.yml, cloudflare/
    • How to trigger the sync: workflow_dispatch on sync-community-health.yml
  3. Update the "Removed workflows" section if stale entries exist

  4. Verify all existing sections for accuracy after Phase 2 changes (new files added, root files deleted)

Acceptance Criteria

  • No language in README claims files "auto-apply" to org repos
  • README accurately describes sync-community-health.yml as an explicit push workflow
  • "Sync Architecture" section lists all 6 target repos
  • README documents which files ARE and ARE NOT synced
  • File passes markdownlint
  • README reflects post-Phase-2 state (CODEOWNERS, dependabot.yml, CODE_OF_CONDUCT, CONTRIBUTING, SUPPORT mentioned)

Dependencies

None — can be worked in parallel with all other Phase 2 issues.
Recommend merging after or alongside other Phase 2 issues so README reflects final state.

Part of Epic

#77

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationrepo:allApplies to all repos in org

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions