From 99baa8250096f2d295583572399a5c9aba2ce312 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Tue, 2 Jun 2026 19:51:02 +0800 Subject: [PATCH] docs: define ECC platform value loop (#2119) --- docs/architecture/cross-harness.md | 4 + docs/architecture/platform-value-loop.md | 120 ++++++++++++++++ .../ito-prediction-market-skill-pack.md | 3 + .../2.0.0-rc.1/preview-pack-manifest.md | 6 + ...cc-2-hypergrowth-release-command-center.md | 21 +++ tests/docs/platform-value-loop.test.js | 130 ++++++++++++++++++ 6 files changed, 284 insertions(+) create mode 100644 docs/architecture/platform-value-loop.md create mode 100644 tests/docs/platform-value-loop.test.js diff --git a/docs/architecture/cross-harness.md b/docs/architecture/cross-harness.md index 9d0afd45..f0ac00c6 100644 --- a/docs/architecture/cross-harness.md +++ b/docs/architecture/cross-harness.md @@ -15,6 +15,8 @@ Claude Code, Codex, OpenCode, Cursor, Gemini, and future harnesses should adapt For the operator-facing support matrix and scorecard workflow, see [Harness Adapter Compliance Matrix](harness-adapter-compliance.md). +For the full-stack platform framing and product-integration loop, see +[ECC Platform Value Loop](platform-value-loop.md). ## Portability Model @@ -118,6 +120,8 @@ Still maturing: - release packaging for `ecc2/` - cross-harness session resume semantics - deeper memory and operator planning layers +- the full platform loop where external products contribute skill packs, + gated APIs, evals, and case studies back into ECC ## Rule For New Work diff --git a/docs/architecture/platform-value-loop.md b/docs/architecture/platform-value-loop.md new file mode 100644 index 00000000..0a61716e --- /dev/null +++ b/docs/architecture/platform-value-loop.md @@ -0,0 +1,120 @@ +# ECC Platform Value Loop + +ECC 2.0 is moving from a portable harness layer toward a full operator +system. The product direction is three layers: + +1. Meta-harness: portable skills, rules, hooks, MCP conventions, release gates, + evals, and security evidence. +2. Dedicated ECC agent: an agent that directly operates over ECC assets instead + of only reading them as static instructions. +3. Control pane / agentic IDE: a visible operator surface for sessions, queues, + skills, memory, evidence, releases, and team workflows. + +The control pane is still a release-candidate direction until it is backed by a +reproducible demo. The public claim is: + +```text +ECC can be used full-stack as a meta-harness + agent + control pane, or +selectively as the portable harness layer inside the AI coding tools teams +already use. +``` + +## OSS Platform Thesis + +The older open-source infrastructure playbook was distribution first: free +source and generous self-serve access created the default developer vocabulary, +then hosted infrastructure, managed teams, support, and enterprise features +captured value. Databases, app platforms, and edge platforms made this obvious: +developers adopted the free surface, teams standardized on the brand, and the +paid product made the workflow easier to run at scale. + +AI-agent infrastructure should follow the same shape, but the hosted value is +not just deployment. The paid or managed surface is: + +- team memory and session routing; +- observable queues, handoffs, and agent runs; +- managed evals, release gates, and evidence packs; +- security review, supply-chain findings, and policy enforcement; +- billing, entitlement, sponsor, and partner workflows; +- product-specific integrations that can become reusable ECC skills. + +The open repo stays useful on its own. The platform earns value when serious +teams want the same workflows managed, measured, secured, or connected to their +own products. + +## Product Integration Contract + +External products can build on ECC without becoming ECC-branded products. The +contract is: + +| Layer | Product contributes | ECC receives | +| --- | --- | --- | +| Skill pack | Public, non-secret workflows in `skills/*/SKILL.md` | New reusable agent behavior and install surface | +| Gated API | Optional product credentials such as `PRODUCT_API_KEY` | A clear upgrade/request path without leaking secrets | +| Fixtures and docs | Sanitized examples, no private accounts or live keys | Testable public proof instead of claims | +| Eval and risk gates | Advice, safety, data, and execution boundaries | Reusable release discipline and trust surface | +| Case study | A real product workflow that works through ECC | Distribution, sponsors, Pro interest, consulting demand | + +Every integration needs: + +- a public workflow that works without private credentials; +- a separate gated path for live product data or actions; +- a clear business boundary so billing and ownership are not blurred; +- tests or documented commands proving the integration surface; +- a support route that does not require public secrets or private account data. + +## Ito Example + +Ito is a separate prediction-market basket product. ECC can still distribute +Ito-shaped skills because the skill workflows are useful without making ECC +Tools an Ito product. + +The safe public surface is: + +- research market, underlier, venue, and liquidity context; +- compare baskets against a user's own notes, portfolio constraints, or thesis; +- draft non-advisory trade-planning worksheets for manual review; +- visualize market/concept relationships and backtesting outputs when data is + available; +- use prediction-market signals as one input into broader agent research. + +The gated surface is: + +- live Ito basket data; +- account-specific state; +- API-backed backtesting or visualization; +- any workflow requiring `ITO_API_KEY`. + +The boundary is strict: public ECC skills do not place trades, do not provide investment advice, do not expose private strategy, and do not merge ECC Tools billing with Ito billing. + +## Value Loop + +The platform loop should be explicit: + +1. A product team builds a useful workflow as an ECC skill pack. +2. The public skill pack works with public sources or local user-provided data. +3. Serious users request gated access for live product data or hosted features. +4. Product usage produces new operator patterns, failure modes, and examples. +5. Sanitized patterns become better ECC skills, evals, gates, or docs. +6. ECC gains distribution, maintainers, sponsors, Pro interest, and consulting leads. +7. The product gains adoption because agent users can operate it through an + already-installed harness. + +This is different from enterprise consulting alone. Consulting can fund the +work, but the platform goal is repeatable distribution: every useful product +integration becomes another reason to install ECC, and every serious ECC user +becomes a possible sponsor, Pro user, partner, or integration customer. + +## Release Lane + +Keep release claims separated: + +- `1.10.1`: stable reliability and docs patch for released users. +- `1.11.0`: public OSS workflow-catalog momentum that does not require the + control pane to be GA. +- `2.0.0-rc.x`: control-pane, dedicated-agent, platform, and release-evidence + work while the full operator system remains prerelease. + +Do not announce ORCA/CONDUCTOR-grade parity, marketplace billing, official +plugin-directory listing, live trading, or native-payments readiness without +fresh evidence and owner approval. diff --git a/docs/releases/2.0.0-rc.1/ito-prediction-market-skill-pack.md b/docs/releases/2.0.0-rc.1/ito-prediction-market-skill-pack.md index 3f49d1b7..e1a4ee08 100644 --- a/docs/releases/2.0.0-rc.1/ito-prediction-market-skill-pack.md +++ b/docs/releases/2.0.0-rc.1/ito-prediction-market-skill-pack.md @@ -51,6 +51,9 @@ not place trades. They can help a user: ## Growth Loop +For the general product-integration contract, see +[`docs/architecture/platform-value-loop.md`](../../architecture/platform-value-loop.md). + The loop is intentionally simple: 1. ECC users discover useful public prediction-market skills. diff --git a/docs/releases/2.0.0-rc.1/preview-pack-manifest.md b/docs/releases/2.0.0-rc.1/preview-pack-manifest.md index 46392752..4209aefc 100644 --- a/docs/releases/2.0.0-rc.1/preview-pack-manifest.md +++ b/docs/releases/2.0.0-rc.1/preview-pack-manifest.md @@ -14,6 +14,7 @@ tagging plugin surfaces, uploading video, or posting announcements. | `skills/hermes-imports/SKILL.md` | Sanitized Hermes-to-ECC import workflow | Includes import rules, sanitization checklist, conversion pattern, and output contract | | `docs/architecture/cross-harness.md` | Shared substrate model for Claude Code, Codex, OpenCode, Cursor, Gemini, Hermes, and terminal-only use | Names portability boundaries and does not claim unsupported native parity | | `docs/architecture/harness-adapter-compliance.md` | Adapter matrix and scorecard | Verified by `npm run harness:adapters -- --check` | +| `docs/architecture/platform-value-loop.md` | Product integration and full-stack platform thesis | Keeps external product skill packs, gated APIs, case studies, sponsorship, Pro, and consulting loops separate from unsupported GA/control-pane claims | | `docs/architecture/observability-readiness.md` | Local operator-readiness gate | Verified by `npm run observability:ready` | | `docs/architecture/progress-sync-contract.md` | GitHub, Linear, handoff, roadmap, and work-item sync boundary | Checked by `node scripts/platform-audit.js --json` | | `scripts/preview-pack-smoke.js` | Deterministic preview-pack smoke gate | Verified by `npm run preview-pack:smoke` | @@ -46,6 +47,11 @@ tagging plugin surfaces, uploading video, or posting announcements. ## Itô Skill Pack Boundary +The general product-integration contract is recorded in +`docs/architecture/platform-value-loop.md`. The Itô pack is the first worked +example: useful public workflows, separate gated API access, and sanitized +operator patterns feeding back into ECC without merging business ownership. + The preview pack includes six public teaser skills for prediction-market and Itô-adjacent workflows: diff --git a/docs/releases/2.0.0/ecc-2-hypergrowth-release-command-center.md b/docs/releases/2.0.0/ecc-2-hypergrowth-release-command-center.md index 79feb9e6..602ca8b3 100644 --- a/docs/releases/2.0.0/ecc-2-hypergrowth-release-command-center.md +++ b/docs/releases/2.0.0/ecc-2-hypergrowth-release-command-center.md @@ -66,6 +66,27 @@ The operating rhythm after launch should be weekly: 5. one measurable funnel readback covering repo traffic, sponsor clicks, Pro conversions, MRR movement, and inbound replies. +## Platform Value Loop + +The long-term platform thesis is recorded in +[`docs/architecture/platform-value-loop.md`](../../architecture/platform-value-loop.md). +ECC should stay useful as free OSS while the managed value accrues around team +memory, observable sessions, release gates, evals, security evidence, hosted +analysis, billing, partner workflows, and product-specific integrations. + +Product integrations should behave like repeatable distribution loops: + +1. ship a public skill pack that works without private credentials; +2. keep live product data or actions behind an explicit gated API path; +3. add fixtures, docs, evals, and risk gates so the workflow is testable; +4. convert sanitized product usage back into ECC skills, docs, or evidence; +5. route serious teams toward sponsors, Pro, partners, or consulting. + +Itô is the current example: prediction-market research, basket comparison, +manual non-advisory planning, and data-atlas workflows can be distributed +through ECC, while live Itô data and account-specific calls remain gated by +`ITO_API_KEY` and separate from ECC Tools billing. + ## Release Gates | Lane | Done when | Current action | diff --git a/tests/docs/platform-value-loop.test.js b/tests/docs/platform-value-loop.test.js new file mode 100644 index 00000000..2e2184a0 --- /dev/null +++ b/tests/docs/platform-value-loop.test.js @@ -0,0 +1,130 @@ +'use strict'; + +const assert = require('assert'); +const fs = require('fs'); +const path = require('path'); + +const repoRoot = path.resolve(__dirname, '..', '..'); + +let passed = 0; +let failed = 0; + +function test(name, fn) { + try { + fn(); + console.log(` ✓ ${name}`); + passed++; + } catch (error) { + console.log(` ✗ ${name}`); + console.log(` Error: ${error.message}`); + failed++; + } +} + +function read(relativePath) { + return fs.readFileSync(path.join(repoRoot, relativePath), 'utf8'); +} + +console.log('\n=== Testing ECC platform value loop docs ===\n'); + +test('platform value loop doc defines the three-layer ECC 2.0 direction', () => { + const source = read('docs/architecture/platform-value-loop.md'); + + for (const marker of [ + 'Meta-harness', + 'Dedicated ECC agent', + 'Control pane / agentic IDE', + 'reproducible demo', + 'ECC can be used full-stack as a meta-harness + agent + control pane', + ]) { + assert.ok(source.includes(marker), `platform value loop doc missing ${marker}`); + } +}); + +test('platform value loop doc records the OSS-to-managed value thesis', () => { + const source = read('docs/architecture/platform-value-loop.md'); + + for (const marker of [ + 'open-source infrastructure playbook', + 'team memory and session routing', + 'managed evals, release gates, and evidence packs', + 'security review, supply-chain findings, and policy enforcement', + 'sponsors', + 'Pro interest', + 'consulting leads', + ]) { + assert.ok(source.includes(marker), `platform value loop doc missing value marker ${marker}`); + } +}); + +test('product integration contract keeps external products useful but separate', () => { + const source = read('docs/architecture/platform-value-loop.md'); + + for (const marker of [ + 'Skill pack', + 'Gated API', + 'Fixtures and docs', + 'Eval and risk gates', + 'Case study', + 'a public workflow that works without private credentials', + 'a separate gated path for live product data or actions', + 'a clear business boundary so billing and ownership are not blurred', + ]) { + assert.ok(source.includes(marker), `platform value loop doc missing contract marker ${marker}`); + } +}); + +test('Ito example preserves non-advisory and gated-access boundaries', () => { + const source = read('docs/architecture/platform-value-loop.md'); + + for (const marker of [ + 'Ito is a separate prediction-market basket product', + 'visualize market/concept relationships and backtesting outputs', + 'ITO_API_KEY', + 'do not place trades', + 'do not provide investment advice', + 'do not merge ECC Tools billing with Ito billing', + ]) { + assert.ok(source.includes(marker), `platform value loop doc missing Ito boundary ${marker}`); + } +}); + +test('release docs link the platform value loop into the rc surface', () => { + const crossHarness = read('docs/architecture/cross-harness.md'); + const previewManifest = read('docs/releases/2.0.0-rc.1/preview-pack-manifest.md'); + const itoPack = read('docs/releases/2.0.0-rc.1/ito-prediction-market-skill-pack.md'); + const hypergrowth = read('docs/releases/2.0.0/ecc-2-hypergrowth-release-command-center.md'); + + for (const source of [crossHarness, previewManifest, itoPack, hypergrowth]) { + assert.ok( + source.includes('platform-value-loop.md'), + 'expected release/cross-harness surface to link platform-value-loop.md' + ); + } + + assert.ok(previewManifest.includes('Product integration and full-stack platform thesis')); + assert.ok(hypergrowth.includes('Product integrations should behave like repeatable distribution loops')); +}); + +test('platform value loop does not overclaim release status or trading ability', () => { + const source = read('docs/architecture/platform-value-loop.md'); + const forbidden = [ + 'ORCA/CONDUCTOR-grade parity is live', + 'control pane is GA', + 'native-payments readiness is live', + 'official plugin-directory listing is live', + 'public ECC skills place trades', + ]; + + for (const phrase of forbidden) { + assert.ok(!source.includes(phrase), `platform value loop should not include overclaim: ${phrase}`); + } +}); + +if (failed > 0) { + console.log(`\nFailed: ${failed}`); + process.exit(1); +} + +console.log(`\nPassed: ${passed}`); +