{"id":51499933,"url":"https://github.com/artemisia-absynthium/ai-guidelines-sync","last_synced_at":"2026-07-07T17:01:29.993Z","repository":{"id":348052489,"uuid":"1196072406","full_name":"artemisia-absynthium/ai-guidelines-sync","owner":"artemisia-absynthium","description":"Plugin to setup and sync centralized rules and skills across several projects","archived":false,"fork":false,"pushed_at":"2026-06-17T10:05:21.000Z","size":192,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T12:06:16.356Z","etag":null,"topics":["ai","ai-tools","claude-code"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artemisia-absynthium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T10:46:49.000Z","updated_at":"2026-06-17T10:05:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/artemisia-absynthium/ai-guidelines-sync","commit_stats":null,"previous_names":["artemisia-absynthium/claude-setup-plugin","artemisia-absynthium/claude-setup","artemisia-absynthium/ai-guidelines-sync"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/artemisia-absynthium/ai-guidelines-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artemisia-absynthium%2Fai-guidelines-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artemisia-absynthium%2Fai-guidelines-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artemisia-absynthium%2Fai-guidelines-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artemisia-absynthium%2Fai-guidelines-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artemisia-absynthium","download_url":"https://codeload.github.com/artemisia-absynthium/ai-guidelines-sync/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artemisia-absynthium%2Fai-guidelines-sync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35235818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-tools","claude-code"],"created_at":"2026-07-07T17:01:29.094Z","updated_at":"2026-07-07T17:01:29.983Z","avatar_url":"https://github.com/artemisia-absynthium.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ai-guidelines-sync\n\nCentral source of Claude Code rules and skills for Swift, iOS, visionOS, macOS, Android, and web\nprojects. Rules are synced into subscriber repos automatically via GitHub Actions; `setup.sh`\nscaffolds any new or existing repo in one command.\n\n## Quick start\n\nFrom the root of a repo (or from a directory containing multiple repos):\n\n```bash\nbash \u003c(curl -fsSL https://raw.githubusercontent.com/artemisia-absynthium/ai-guidelines-sync/main/setup.sh)\n```\n\n\u003e **Note:** The `\u003c()` form is required — it keeps `/dev/tty` open for the interactive pickers.\n\u003e `curl ... | bash` closes stdin and breaks arrow-key input.\n\n**Single-repo mode** (run from inside a git repo): detects project type, writes config, scaffolds sync workflow, pre-populates rules and skills from upstream.\n\n**Multi-repo mode** (run from a directory of repos): presents an interactive multi-select picker, then runs single-repo setup on each selected repo.\n\n### Requirements\n\n- macOS with Homebrew installed (`https://brew.sh/`)\n- `jq` — installed automatically if absent, removed when the script exits (requires Homebrew)\n\n---\n\n## What the script does\n\n1. **Checks out the default branch and pulls** — ensures setup runs on the latest remote state. Skipped gracefully when the repo has no commits or no upstream tracking branch.\n2. **Detects project type** — infers rule categories from `.xcodeproj`, `Package.swift`, `build.gradle`, `package.json`, `playwright.config.*`, `pyproject.toml`\n3. **Writes `.claude/rules-sync.txt`** — category config; skip if already exists (preserving user edits)\n4. **Writes `.github/workflows/sync-claude-rules.yml`** — thin wrapper calling the composite action; always overwritten; sync day is chosen interactively\n5. **Pre-populates rules and skills** from upstream via GitHub API (so teammates get them immediately on next clone)\n6. **Writes the guard hook** to `.claude/settings.json` — blocks accidental edits to sync-managed files\n7. **Migration** — renames `.claude/rules-sync` → `.claude/rules-sync.txt`, removes the retired `setup-project-ai` skill, cleans stale category directories\n\nRe-running the script is the update command — `rules-sync.txt` is preserved, everything else is refreshed. In multi-repo mode, per-repo failures are collected and printed as a summary at the end rather than aborting the run.\n\n---\n\n## How sync works\n\nSubscriber repos run a thin workflow that calls the composite action:\n\n```yaml\n# .github/workflows/sync-claude-rules.yml — written by setup.sh, never needs manual changes\non:\n  schedule:\n    - cron: '0 9 * * 1'   # chosen at setup time\n  workflow_dispatch:\njobs:\n  sync:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: write\n    steps:\n      - uses: actions/checkout@v6\n        with:\n          ssh-key: ${{ secrets.CLAUDE_RULES_DEPLOY_KEY }}\n      - uses: artemisia-absynthium/ai-guidelines-sync/.github/actions/sync@main\n```\n\nThe composite action at `.github/actions/sync/action.yml` in **this repo** contains all sync logic.\nWhen sync logic changes, only this repo is updated — subscriber workflow files never change.\n\n### What the action does\n\n1. Checks out this repo alongside the subscriber workspace\n2. Detects project type and auto-adds new categories to `rules-sync.txt` (skips commented-out ones — those are explicit exclusions)\n3. Deletes `synced/\u003ccategory\u003e/` directories for removed categories\n4. `rsync --delete` each active category from upstream into `.claude/rules/synced/\u003ccategory\u003e/`\n5. Syncs skills using a manifest (`.claude/skills/.synced-manifest`) to safely remove skills deleted upstream without touching local project skills\n6. Commits and pushes via the deploy key\n\n---\n\n## Selective sync — `.claude/rules-sync.txt`\n\nControls which rule categories a subscriber repo receives. One category per line. Comment out a line to explicitly exclude it (it won't be re-added automatically):\n\n```\n# Category names match directories under rules/ in ai-guidelines-sync.\n# Comment out a line to exclude that category from auto-detection.\nswift\nios\nvisionos\nxcode\n# mac   ← explicitly excluded; auto-detection won't add it back\n```\n\n**Available categories**: `swift`, `ios`, `mac`, `visionos`, `xcode`, `android`, `web`\n\nThe `workflow` category is always synced — do not add it to `rules-sync.txt`.\n\n---\n\n## Rules\n\n| File | Covers |\n|------|--------|\n| `rules/swift/analytics.md` | Firebase Analytics screen view tracking |\n| `rules/swift/assets.md` | `ImageResource` in SwiftUI — type-safe, non-optional asset loading |\n| `rules/swift/code-style.md` | Logger, file headers, import order, naming, SwiftLint |\n| `rules/swift/concurrency.md` | `@MainActor`, `@Observable`, async patterns, Task discipline |\n| `rules/swift/state-management.md` | `Loadable\u003cT\u003e` pattern, error surfacing, retry design |\n| `rules/swift/swiftui.md` | View structure, adaptive layouts, state ownership, previews |\n| `rules/swift/testing.md` | Swift Testing (`@Test`, `@Suite`, `#expect`, `#require`) |\n| `rules/ios/assets.md` | `UIImage(resource:)` — type-safe UIKit asset loading (iOS 17+) |\n| `rules/mac/affordances.md` | Menus, keyboard shortcuts, windows, native chrome |\n| `rules/visionos/realitykit.md` | RealityView lifecycle, entity rules, z-offset, attachments |\n| `rules/android/code-style.md` | No force non-null, `Result\u003cT\u003e` at boundaries, companion constants |\n| `rules/android/compose.md` | State management, lifecycle-aware collection, UI state coverage |\n| `rules/android/room.md` | Flow from DAOs, KSP, explicit migrations, schema export |\n| `rules/android/testing.md` | JUnit 4, Robolectric, MockK, Turbine for Flow assertions |\n| `rules/web/playwright.md` | Playwright test execution vs visual verification |\n| `rules/xcode/mcp-tools.md` | Xcode MCP tools for file ops, build, test, preview, code intelligence |\n| `rules/xcode/packages.md` | SPM only — no CocoaPods or Carthage |\n| `rules/xcode/warnings.md` | Zero-warning policy |\n| `rules/workflow/contributing.md` | Cross-project rule contribution — invoke `lift-to-shared-rules` |\n| `rules/workflow/synced-rules.md` | Synced-directory layout — where to put local rules, how to opt out |\n\n---\n\n## Skills\n\n| Skill | What it does |\n|-------|-------------|\n| `lift-to-shared-rules` | Generalizes a pattern found in a project and proposes it upstream via commit (owner) or PR (contributor) |\n\nAfter the first sync workflow run, skills are committed to `.claude/skills/\u003cname\u003e/` in each subscriber repo — available to all teammates automatically.\n\n---\n\n## Adding a deploy key to a subscriber repo\n\nThe sync workflow pushes directly to the default branch, bypassing branch protection, via a deploy key:\n\n1. `ssh-keygen -t ed25519 -C \"claude-rules-sync\" -f /tmp/claude_rules_deploy_key -N \"\"`\n2. Copy public key: `cat /tmp/claude_rules_deploy_key.pub | pbcopy`  \n   Subscriber repo → Settings → Deploy keys → Add → paste → enable **Allow write access**\n3. If the default branch has protection rules:  \n   Settings → Branches → edit rule → add the deploy key to the bypass list\n4. Copy private key: `cat /tmp/claude_rules_deploy_key | pbcopy`  \n   Subscriber repo → Settings → Secrets → Actions → `CLAUDE_RULES_DEPLOY_KEY` → paste\n5. `rm /tmp/claude_rules_deploy_key*`\n6. Trigger the workflow manually once: Actions → Sync Claude Rules and Skills → Run workflow\n\n---\n\n## Contributing rules\n\nUse the `lift-to-shared-rules` skill inside any Claude Code session to generalize a pattern and\npropose it upstream. The skill handles anonymization, coherence checks, and the commit/PR flow.\n\nTo run the test suite:\n\n```bash\nbats tests/\n```\n\nRequires [BATS](https://github.com/bats-core/bats-core): `brew install bats-core`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartemisia-absynthium%2Fai-guidelines-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartemisia-absynthium%2Fai-guidelines-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartemisia-absynthium%2Fai-guidelines-sync/lists"}