|
| 1 | +# Upstream Sync Policy |
| 2 | + |
| 3 | +**Language:** **English** | [한국어](ko-KR/README.md) | [简体中文](zh-CN/README.md) |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | +EGC (Everything Gemini Code) is an **ecosystem port** of [ECC (Everything Claude Code)](https://github.com/affaan-m/everything-claude-code) by [@affaan-m](https://github.com/affaan-m). It is not an official ECC release and does not claim API or behavioral compatibility with ECC. Harness-specific behavior is verified inside Gemini CLI itself, not by reference to ECC's Claude Code behavior. |
| 10 | + |
| 11 | +This document records how EGC tracks the upstream ECC repository and what was changed during the port. |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Upstream baseline |
| 16 | + |
| 17 | +- **Upstream repository**: [`affaan-m/everything-claude-code`](https://github.com/affaan-m/everything-claude-code) |
| 18 | +- **Last-synced upstream commit**: [`9db98673d054f5ed0991ba9d67ff4c883c81a42f`](https://github.com/affaan-m/everything-claude-code/commit/9db98673d054f5ed0991ba9d67ff4c883c81a42f) |
| 19 | +- **Last-synced date**: 2026-02-09 |
| 20 | +- **Initial EGC commit**: [`ff331996a061c2bbd17ffaa23d4eed2dcdd6ad35`](https://github.com/Jamkris/everything-gemini-code/commit/ff331996a061c2bbd17ffaa23d4eed2dcdd6ad35) (2026-02-09) |
| 21 | + |
| 22 | +A machine-readable copy of this state lives at [`.upstream-sync.json`](./.upstream-sync.json). A follow-up CI validator will assert the two files agree on the SHA; until then the maintainer keeps them in sync by hand at sync time. |
| 23 | + |
| 24 | +--- |
| 25 | + |
| 26 | +## Sync policy |
| 27 | + |
| 28 | +EGC syncs with ECC on a **best-effort basis**. There is no committed sync cadence — a solo maintainer cannot reliably promise one, and a missed promise is itself the kind of drift this policy is meant to prevent. |
| 29 | + |
| 30 | +Instead, drift is made **mechanically visible**: |
| 31 | + |
| 32 | +- The last-synced commit SHA is recorded above and in `.upstream-sync.json`. |
| 33 | +- A scheduled GitHub Action (planned) compares the recorded SHA against `affaan-m/everything-claude-code` HEAD on a weekly cadence and maintains a single rolling tracking issue labelled `upstream-sync` when there is drift. |
| 34 | +- When a sync round happens, the maintainer advances the SHA, the tracker closes the issue, and the cycle repeats. |
| 35 | + |
| 36 | +This way the *commitment* is to surface drift, not to fix it on a schedule. |
| 37 | + |
| 38 | +### What is eligible for backport from ECC to EGC |
| 39 | + |
| 40 | +- Skill content, rule content, and workflow ideas that are harness-agnostic. |
| 41 | +- Bug fixes in shared logic (validators, scoring rubrics, deterministic engines). |
| 42 | +- New agents whose intent translates cleanly to Gemini CLI's tool model. |
| 43 | +- Documentation improvements. |
| 44 | + |
| 45 | +### What is intentionally divergent |
| 46 | + |
| 47 | +- Anything tied to Claude Code's runtime model (Claude-specific tool names, `model: opus/sonnet` selectors, `~/.claude/` paths, `CLAUDE.md` filenames). |
| 48 | +- ECC features built on Claude Code APIs that have no equivalent in Gemini CLI. |
| 49 | +- Native Gemini CLI features that have no ECC equivalent (Gemini extension manifest, `.gemini/` path layout, `gemini-extension.json`). |
| 50 | + |
| 51 | +### Conflict resolution |
| 52 | + |
| 53 | +When an upstream change touches surface area that EGC has already adapted for Gemini CLI — command/agent file formats, the path layout, install scripts, the Gemini extension manifest, the Antigravity flow, or the Gemini-specific validators — **Gemini CLI native behavior stability takes precedence over upstream alignment**. Adopt the spirit of the ECC change but reshape it to the Gemini conventions documented in [`CONTRIBUTING.md`](../CONTRIBUTING.md). When in doubt, prefer a verifiable Gemini CLI behavior over a closer textual match to ECC. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## What was copied vs. changed vs. removed vs. added |
| 58 | + |
| 59 | +This is a category-level summary. The repository itself is the source of truth — see the file tree for the exhaustive list. |
| 60 | + |
| 61 | +### Copied (with format/path translation only) |
| 62 | + |
| 63 | +| Category | Notes | |
| 64 | +|---|---| |
| 65 | +| Skills | Content largely preserved; frontmatter and references retargeted to Gemini conventions. | |
| 66 | +| Rules | Language-specific rule files copied as-is where the rule is language-, not harness-, specific. | |
| 67 | +| Workflow ideas | Workflow names and step structures preserved; tool invocations retranslated. | |
| 68 | + |
| 69 | +### Changed (translated to Gemini CLI conventions) |
| 70 | + |
| 71 | +| Category | Change | |
| 72 | +|---|---| |
| 73 | +| Commands | Migrated from Claude Code's command format to Gemini CLI's `commands/*.toml` format. | |
| 74 | +| Agents | Tool names migrated to Gemini equivalents (`Read` → `read_file`, `Bash` → `run_shell_command`, etc.). See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full mapping. | |
| 75 | +| Agent frontmatter | `model: opus/sonnet` field removed (Gemini CLI does not support model selection at the agent level). | |
| 76 | +| Paths | `~/.claude/` → `~/.gemini/`; `CLAUDE.md` → `GEMINI.md`. | |
| 77 | +| MCP configs | Adapted to Gemini CLI's MCP server registration format. | |
| 78 | +| Install scripts | Rewritten for Gemini CLI / Antigravity installation flow. | |
| 79 | +| Branding | "Claude" → "Gemini" in user-facing strings where the reference is to the harness, not to Anthropic's model. | |
| 80 | + |
| 81 | +### Removed (no Gemini equivalent or intentionally dropped) |
| 82 | + |
| 83 | +| Category | Reason | |
| 84 | +|---|---| |
| 85 | +| Legacy Claude Code install scripts (`ecc.js`, `claw.js`, `install-plan.js`) | Gemini CLI manages installation natively via its Extension architecture. | |
| 86 | +| Claude-API-specific skills that hard-code Anthropic SDK usage | Out of scope for a Gemini CLI port. | |
| 87 | + |
| 88 | +### Added (net-new in EGC, not in ECC) |
| 89 | + |
| 90 | +| Category | Notes | |
| 91 | +|---|---| |
| 92 | +| Gemini extension manifest | `gemini-extension.json` and `.gemini-plugin/plugin.json` to register EGC as a Gemini CLI extension. | |
| 93 | +| Antigravity-specific install paths | Antigravity (VS Code / Cursor) flow in `scripts/install.sh`. | |
| 94 | +| Multilingual docs | Korean and Simplified Chinese mirrors under `docs/ko-KR/`, `docs/zh-CN/`, and this folder's `ko-KR/` and `zh-CN/` subdirectories. | |
| 95 | +| `/egc-grok` | Repo-wide audit command leveraging Gemini's 1M context window — no ECC analogue. | |
| 96 | +| Validators | `scripts/ci/validate-{agents,commands,hooks,skills,workflow-security}.js` enforce the Gemini-specific frontmatter rules introduced by the port. | |
| 97 | + |
| 98 | +--- |
| 99 | + |
| 100 | +## Backporting to ECC |
| 101 | + |
| 102 | +When a contribution to EGC is harness-agnostic and would also benefit ECC users: |
| 103 | + |
| 104 | +1. Land it in EGC first (faster review cycle, you control the merge). |
| 105 | +2. Open a corresponding PR against `affaan-m/everything-claude-code`, porting out the Gemini-specific parts (file format, tool names, paths). |
| 106 | +3. Cross-link the two PRs in their descriptions so reviewers on either side can see the upstream/downstream pair. |
| 107 | +4. If ECC accepts the upstream version, note it in your EGC PR description for traceability. |
| 108 | + |
| 109 | +The maintainer of EGC is not affiliated with the maintainer of ECC; backports are a contributor-driven activity. |
| 110 | + |
| 111 | +--- |
| 112 | + |
| 113 | +## Open questions and known drift |
| 114 | + |
| 115 | +This section is honest about gaps. Resolve and prune items as they go away. |
| 116 | + |
| 117 | +- The adapter surface (commands, agents, hooks, validators) has not been end-to-end reviewed by the ECC maintainer. EGC's behavior is verified against Gemini CLI; ECC compatibility is not asserted. |
| 118 | +- Skill counts and command counts will drift over time as both repos evolve independently. The `/egc-grok` audit can produce a current inventory on demand. |
| 119 | +- Translation drift: when ECC adds new agents/skills, the Korean and Chinese mirrors are updated on a follow-up cycle, not in lockstep with the English docs. |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +## Recording a sync |
| 124 | + |
| 125 | +When upstream is reviewed and the baseline advances: |
| 126 | + |
| 127 | +1. Update `lastSyncedSha`, `lastSyncedAt`, and optionally `notes` in [`.upstream-sync.json`](./.upstream-sync.json). |
| 128 | +2. Bring the **Upstream baseline** section above into agreement with the JSON. |
| 129 | +3. If any item in **Open questions and known drift** is resolved, remove it. |
| 130 | +4. Run `npm run lint && npm test`. |
| 131 | +5. Commit with a `docs: sync upstream baseline to <short-sha>` message. |
| 132 | + |
| 133 | +**This procedure is open to community contributors** — anyone can propose a sync update via a PR, not just the maintainer. The validator (once landed) plus normal code review will check that the SHAs and the recorded date are consistent. |
| 134 | + |
| 135 | +A follow-up PR will add a CI validator that asserts the SHAs in this document and in `.upstream-sync.json` agree; once that lands, a mismatch will block the PR automatically. |
0 commit comments