From 69b8ec4e0b050ff6ebcbc47c5230086477610600 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Wed, 29 Apr 2026 20:03:21 -0400 Subject: [PATCH] docs: add ecc2 rc1 quickstart path --- docs/architecture/cross-harness.md | 19 +++++++ docs/releases/2.0.0-rc.1/quickstart.md | 61 +++++++++++++++++++++++ docs/releases/2.0.0-rc.1/release-notes.md | 11 ++-- tests/docs/ecc2-release-surface.test.js | 24 +++++++++ 4 files changed, 110 insertions(+), 5 deletions(-) create mode 100644 docs/releases/2.0.0-rc.1/quickstart.md diff --git a/docs/architecture/cross-harness.md b/docs/architecture/cross-harness.md index 74df8aea..0839c2f3 100644 --- a/docs/architecture/cross-harness.md +++ b/docs/architecture/cross-harness.md @@ -78,6 +78,25 @@ Do not ship: - private datasets - local-only automation packs that have not been reviewed +## Worked Example + +Use `skills/hermes-imports/SKILL.md` as the same skill source across harnesses. + +The workflow is: + +1. Author the durable behavior once in `skills/hermes-imports/SKILL.md`. +2. Keep secrets, local paths, and raw operator memory out of the skill. +3. Let each harness adapt how the skill is loaded. +4. Test the source skill and the harness-facing metadata separately. + +Claude Code gets the skill through the Claude plugin surface and can enforce related hooks natively. + +Codex reads the repo instructions, `.codex-plugin/plugin.json`, and the MCP reference config. The same skill source still describes the workflow, but hook parity is instruction-backed unless Codex adds a native hook surface. + +OpenCode gets the skill through the OpenCode package/plugin surface. Event handling can reuse ECC hook logic through the adapter layer, while the skill text stays unchanged. + +If a change requires editing three harness copies of the same workflow, the shared source is in the wrong place. Put the workflow back in `skills/`, then adapt only loading, event shape, or command routing at the harness edge. + ## Today vs Later Supported today: diff --git a/docs/releases/2.0.0-rc.1/quickstart.md b/docs/releases/2.0.0-rc.1/quickstart.md new file mode 100644 index 00000000..63aa80ac --- /dev/null +++ b/docs/releases/2.0.0-rc.1/quickstart.md @@ -0,0 +1,61 @@ +# ECC v2.0.0-rc.1 Quickstart + +This path is for a new contributor who wants to verify the release surface before touching feature work. + +## Clone + +```bash +git clone https://github.com/affaan-m/everything-claude-code.git +cd everything-claude-code +``` + +Start from a clean checkout. Do not copy private operator state, raw workspace exports, tokens, or local Hermes files into the repo. + +## Install + +```bash +npm ci +``` + +This installs the Node-based validation and packaging toolchain used by the public release surface. + +## Verify + +```bash +node tests/run-all.js +``` + +Expected result: every test passes with zero failures. For release-specific drift, run the focused check: + +```bash +node tests/docs/ecc2-release-surface.test.js +``` + +## First Skill + +Read `skills/hermes-imports/SKILL.md` first. + +It shows the intended ECC 2.0 pattern: + +- take a repeated operator workflow +- remove credentials, private paths, raw workspace exports, and personal memory +- keep the durable workflow shape +- publish the sanitized result as a reusable `SKILL.md` + +Do not start by importing a private Hermes workflow wholesale. Start by distilling one reusable skill. + +## Switch Harness + +Use the same skill source across harnesses: + +- Claude Code consumes ECC through the Claude plugin and native hooks. +- Codex consumes ECC through `AGENTS.md`, `.codex-plugin/plugin.json`, and MCP reference config. +- OpenCode consumes ECC through the OpenCode package/plugin surface. + +The portable unit is still `skills/*/SKILL.md`. Harness-specific files should load or adapt that source, not redefine the workflow. + +## Next Docs + +- [Hermes setup](../../HERMES-SETUP.md) +- [Cross-harness architecture](../../architecture/cross-harness.md) +- [Release notes](release-notes.md) diff --git a/docs/releases/2.0.0-rc.1/release-notes.md b/docs/releases/2.0.0-rc.1/release-notes.md index fe1e5e62..3687a37e 100644 --- a/docs/releases/2.0.0-rc.1/release-notes.md +++ b/docs/releases/2.0.0-rc.1/release-notes.md @@ -47,8 +47,9 @@ What stays local: ## Upgrade Motion -1. Read the [Hermes setup guide](../../HERMES-SETUP.md). -2. Review the [cross-harness architecture](../../architecture/cross-harness.md). -3. Start with one workflow lane: engineering, research, content, or outreach. -4. Import only sanitized operator patterns into ECC skills. -5. Treat `ecc2/` as an alpha control plane until release packaging and installer behavior are finalized. +1. Follow the [rc.1 quickstart](quickstart.md). +2. Read the [Hermes setup guide](../../HERMES-SETUP.md). +3. Review the [cross-harness architecture](../../architecture/cross-harness.md). +4. Start with one workflow lane: engineering, research, content, or outreach. +5. Import only sanitized operator patterns into ECC skills. +6. Treat `ecc2/` as an alpha control plane until release packaging and installer behavior are finalized. diff --git a/tests/docs/ecc2-release-surface.test.js b/tests/docs/ecc2-release-surface.test.js index 771d71a1..1660a262 100644 --- a/tests/docs/ecc2-release-surface.test.js +++ b/tests/docs/ecc2-release-surface.test.js @@ -49,6 +49,7 @@ const expectedReleaseFiles = [ 'launch-checklist.md', 'telegram-handoff.md', 'demo-prompts.md', + 'quickstart.md', ]; test('release candidate directory includes the public launch pack', () => { @@ -120,6 +121,29 @@ test('release docs preserve the ECC/Hermes boundary', () => { assert.ok(releaseNotes.includes('Hermes as the operator shell')); }); +test('release notes route new contributors through the rc.1 quickstart', () => { + const releaseNotes = read('docs/releases/2.0.0-rc.1/release-notes.md'); + assert.ok(releaseNotes.includes('[rc.1 quickstart](quickstart.md)')); +}); + +test('rc.1 quickstart gives a clone-to-cross-harness path', () => { + const quickstart = read('docs/releases/2.0.0-rc.1/quickstart.md'); + for (const heading of ['Clone', 'Install', 'Verify', 'First Skill', 'Switch Harness']) { + assert.ok(quickstart.includes(`## ${heading}`), `Missing ${heading} section`); + } + assert.ok(quickstart.includes('node tests/run-all.js')); + assert.ok(quickstart.includes('skills/hermes-imports/SKILL.md')); +}); + +test('cross-harness doc includes a worked skill portability example', () => { + const source = read('docs/architecture/cross-harness.md'); + assert.ok(source.includes('## Worked Example')); + assert.ok(source.includes('same skill source')); + for (const harness of ['Claude Code', 'Codex', 'OpenCode']) { + assert.ok(source.includes(harness), `Expected worked example to mention ${harness}`); + } +}); + test('release docs use release-candidate wording consistently', () => { const releaseNotes = read('docs/releases/2.0.0-rc.1/release-notes.md'); assert.ok(releaseNotes.includes('## Release Candidate Boundaries'));