mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-03-30 13:43:26 +08:00
merge: dmux worktree (selective install, orchestration, observer fixes)
This commit is contained in:
Affaan Mustafa
322
docs/ECC-2.0-SESSION-ADAPTER-DISCOVERY.md
Normal file
322
docs/ECC-2.0-SESSION-ADAPTER-DISCOVERY.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# ECC 2.0 Session Adapter Discovery
|
||||
|
||||
## Purpose
|
||||
|
||||
This document turns the March 11 ECC 2.0 control-plane direction into a
|
||||
concrete adapter and snapshot design grounded in the orchestration code that
|
||||
already exists in this repo.
|
||||
|
||||
## Current Implemented Substrate
|
||||
|
||||
The repo already has a real first-pass orchestration substrate:
|
||||
|
||||
- `scripts/lib/tmux-worktree-orchestrator.js`
|
||||
provisions tmux panes plus isolated git worktrees
|
||||
- `scripts/orchestrate-worktrees.js`
|
||||
is the current session launcher
|
||||
- `scripts/lib/orchestration-session.js`
|
||||
collects machine-readable session snapshots
|
||||
- `scripts/orchestration-status.js`
|
||||
exports those snapshots from a session name or plan file
|
||||
- `commands/sessions.md`
|
||||
already exposes adjacent session-history concepts from Claude's local store
|
||||
- `scripts/lib/session-adapters/canonical-session.js`
|
||||
defines the canonical `ecc.session.v1` normalization layer
|
||||
- `scripts/lib/session-adapters/dmux-tmux.js`
|
||||
wraps the current orchestration snapshot collector as adapter `dmux-tmux`
|
||||
- `scripts/lib/session-adapters/claude-history.js`
|
||||
normalizes Claude local session history as a second adapter
|
||||
- `scripts/lib/session-adapters/registry.js`
|
||||
selects adapters from explicit targets and target types
|
||||
- `scripts/session-inspect.js`
|
||||
emits canonical read-only session snapshots through the adapter registry
|
||||
|
||||
In practice, ECC can already answer:
|
||||
|
||||
- what workers exist in a tmux-orchestrated session
|
||||
- what pane each worker is attached to
|
||||
- what task, status, and handoff files exist for each worker
|
||||
- whether the session is active and how many panes/workers exist
|
||||
- what the most recent Claude local session looked like in the same canonical
|
||||
snapshot shape as orchestration sessions
|
||||
|
||||
That is enough to prove the substrate. It is not yet enough to qualify as a
|
||||
general ECC 2.0 control plane.
|
||||
|
||||
## What The Current Snapshot Actually Models
|
||||
|
||||
The current snapshot model coming out of `scripts/lib/orchestration-session.js`
|
||||
has these effective fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"sessionName": "workflow-visual-proof",
|
||||
"coordinationDir": ".../.claude/orchestration/workflow-visual-proof",
|
||||
"repoRoot": "...",
|
||||
"targetType": "plan",
|
||||
"sessionActive": true,
|
||||
"paneCount": 2,
|
||||
"workerCount": 2,
|
||||
"workerStates": {
|
||||
"running": 1,
|
||||
"completed": 1
|
||||
},
|
||||
"panes": [
|
||||
{
|
||||
"paneId": "%95",
|
||||
"windowIndex": 1,
|
||||
"paneIndex": 0,
|
||||
"title": "seed-check",
|
||||
"currentCommand": "codex",
|
||||
"currentPath": "/tmp/worktree",
|
||||
"active": false,
|
||||
"dead": false,
|
||||
"pid": 1234
|
||||
}
|
||||
],
|
||||
"workers": [
|
||||
{
|
||||
"workerSlug": "seed-check",
|
||||
"workerDir": ".../seed-check",
|
||||
"status": {
|
||||
"state": "running",
|
||||
"updated": "...",
|
||||
"branch": "...",
|
||||
"worktree": "...",
|
||||
"taskFile": "...",
|
||||
"handoffFile": "..."
|
||||
},
|
||||
"task": {
|
||||
"objective": "...",
|
||||
"seedPaths": ["scripts/orchestrate-worktrees.js"]
|
||||
},
|
||||
"handoff": {
|
||||
"summary": [],
|
||||
"validation": [],
|
||||
"remainingRisks": []
|
||||
},
|
||||
"files": {
|
||||
"status": ".../status.md",
|
||||
"task": ".../task.md",
|
||||
"handoff": ".../handoff.md"
|
||||
},
|
||||
"pane": {
|
||||
"paneId": "%95",
|
||||
"title": "seed-check"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
This is already a useful operator payload. The main limitation is that it is
|
||||
implicitly tied to one execution style:
|
||||
|
||||
- tmux pane identity
|
||||
- worker slug equals pane title
|
||||
- markdown coordination files
|
||||
- plan-file or session-name lookup rules
|
||||
|
||||
## Gap Between ECC 1.x And ECC 2.0
|
||||
|
||||
ECC 1.x currently has two different "session" surfaces:
|
||||
|
||||
1. Claude local session history
|
||||
2. Orchestration runtime/session snapshots
|
||||
|
||||
Those surfaces are adjacent but not unified.
|
||||
|
||||
The missing ECC 2.0 layer is a harness-neutral session adapter boundary that
|
||||
can normalize:
|
||||
|
||||
- tmux-orchestrated workers
|
||||
- plain Claude sessions
|
||||
- Codex worktree sessions
|
||||
- OpenCode sessions
|
||||
- future GitHub/App or remote-control sessions
|
||||
|
||||
Without that adapter layer, any future operator UI would be forced to read
|
||||
tmux-specific details and coordination markdown directly.
|
||||
|
||||
## Adapter Boundary
|
||||
|
||||
ECC 2.0 should introduce a canonical session adapter contract.
|
||||
|
||||
Suggested minimal interface:
|
||||
|
||||
```ts
|
||||
type SessionAdapter = {
|
||||
id: string;
|
||||
canOpen(target: SessionTarget): boolean;
|
||||
open(target: SessionTarget): Promise<AdapterHandle>;
|
||||
};
|
||||
|
||||
type AdapterHandle = {
|
||||
getSnapshot(): Promise<CanonicalSessionSnapshot>;
|
||||
streamEvents?(onEvent: (event: SessionEvent) => void): Promise<() => void>;
|
||||
runAction?(action: SessionAction): Promise<ActionResult>;
|
||||
};
|
||||
```
|
||||
|
||||
### Canonical Snapshot Shape
|
||||
|
||||
Suggested first-pass canonical payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "ecc.session.v1",
|
||||
"adapterId": "dmux-tmux",
|
||||
"session": {
|
||||
"id": "workflow-visual-proof",
|
||||
"kind": "orchestrated",
|
||||
"state": "active",
|
||||
"repoRoot": "...",
|
||||
"sourceTarget": {
|
||||
"type": "plan",
|
||||
"value": ".claude/plan/workflow-visual-proof.json"
|
||||
}
|
||||
},
|
||||
"workers": [
|
||||
{
|
||||
"id": "seed-check",
|
||||
"label": "seed-check",
|
||||
"state": "running",
|
||||
"branch": "...",
|
||||
"worktree": "...",
|
||||
"runtime": {
|
||||
"kind": "tmux-pane",
|
||||
"command": "codex",
|
||||
"pid": 1234,
|
||||
"active": false,
|
||||
"dead": false
|
||||
},
|
||||
"intent": {
|
||||
"objective": "...",
|
||||
"seedPaths": ["scripts/orchestrate-worktrees.js"]
|
||||
},
|
||||
"outputs": {
|
||||
"summary": [],
|
||||
"validation": [],
|
||||
"remainingRisks": []
|
||||
},
|
||||
"artifacts": {
|
||||
"statusFile": "...",
|
||||
"taskFile": "...",
|
||||
"handoffFile": "..."
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregates": {
|
||||
"workerCount": 2,
|
||||
"states": {
|
||||
"running": 1,
|
||||
"completed": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This preserves the useful signal already present while removing tmux-specific
|
||||
details from the control-plane contract.
|
||||
|
||||
## First Adapters To Support
|
||||
|
||||
### 1. `dmux-tmux`
|
||||
|
||||
Wrap the logic already living in
|
||||
`scripts/lib/orchestration-session.js`.
|
||||
|
||||
This is the easiest first adapter because the substrate is already real.
|
||||
|
||||
### 2. `claude-history`
|
||||
|
||||
Normalize the data that
|
||||
`commands/sessions.md`
|
||||
and the existing session-manager utilities already expose:
|
||||
|
||||
- session id / alias
|
||||
- branch
|
||||
- worktree
|
||||
- project path
|
||||
- recency / file size / item counts
|
||||
|
||||
This provides a non-orchestrated baseline for ECC 2.0.
|
||||
|
||||
### 3. `codex-worktree`
|
||||
|
||||
Use the same canonical shape, but back it with Codex-native execution metadata
|
||||
instead of tmux assumptions where available.
|
||||
|
||||
### 4. `opencode`
|
||||
|
||||
Use the same adapter boundary once OpenCode session metadata is stable enough to
|
||||
normalize.
|
||||
|
||||
## What Should Stay Out Of The Adapter Layer
|
||||
|
||||
The adapter layer should not own:
|
||||
|
||||
- business logic for merge sequencing
|
||||
- operator UI layout
|
||||
- pricing or monetization decisions
|
||||
- install profile selection
|
||||
- tmux lifecycle orchestration itself
|
||||
|
||||
Its job is narrower:
|
||||
|
||||
- detect session targets
|
||||
- load normalized snapshots
|
||||
- optionally stream runtime events
|
||||
- optionally expose safe actions
|
||||
|
||||
## Current File Layout
|
||||
|
||||
The adapter layer now lives in:
|
||||
|
||||
```text
|
||||
scripts/lib/session-adapters/
|
||||
canonical-session.js
|
||||
dmux-tmux.js
|
||||
claude-history.js
|
||||
registry.js
|
||||
scripts/session-inspect.js
|
||||
tests/lib/session-adapters.test.js
|
||||
tests/scripts/session-inspect.test.js
|
||||
```
|
||||
|
||||
The current orchestration snapshot parser is now being consumed as an adapter
|
||||
implementation rather than remaining the only product contract.
|
||||
|
||||
## Immediate Next Steps
|
||||
|
||||
1. Add a third adapter, likely `codex-worktree`, so the abstraction moves
|
||||
beyond tmux plus Claude-history.
|
||||
2. Decide whether canonical snapshots need separate `state` and `health`
|
||||
fields before UI work starts.
|
||||
3. Decide whether event streaming belongs in v1 or stays out until after the
|
||||
snapshot layer proves itself.
|
||||
4. Build operator-facing panels only on top of the adapter registry, not by
|
||||
reading orchestration internals directly.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should worker identity be keyed by worker slug, branch, or stable UUID?
|
||||
2. Do we need separate `state` and `health` fields at the canonical layer?
|
||||
3. Should event streaming be part of v1, or should ECC 2.0 ship snapshot-only
|
||||
first?
|
||||
4. How much path information should be redacted before snapshots leave the local
|
||||
machine?
|
||||
5. Should the adapter registry live inside this repo long-term, or move into the
|
||||
eventual ECC 2.0 control-plane app once the interface stabilizes?
|
||||
|
||||
## Recommendation
|
||||
|
||||
Treat the current tmux/worktree implementation as adapter `0`, not as the final
|
||||
product surface.
|
||||
|
||||
The shortest path to ECC 2.0 is:
|
||||
|
||||
1. preserve the current orchestration substrate
|
||||
2. wrap it in a canonical session adapter contract
|
||||
3. add one non-tmux adapter
|
||||
4. only then start building operator panels on top
|
||||
286
docs/MEGA-PLAN-REPO-PROMPTS-2026-03-12.md
Normal file
286
docs/MEGA-PLAN-REPO-PROMPTS-2026-03-12.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Mega Plan Repo Prompt List — March 12, 2026
|
||||
|
||||
## Purpose
|
||||
|
||||
Use these prompts to split the remaining March 11 mega-plan work by repo.
|
||||
They are written for parallel agents and assume the March 12 orchestration and
|
||||
Windows CI lane is already merged via `#417`.
|
||||
|
||||
## Current Snapshot
|
||||
|
||||
- `everything-claude-code` has finished the orchestration, Codex baseline, and
|
||||
Windows CI recovery lane.
|
||||
- The next open ECC Phase 1 items are:
|
||||
- review `#399`
|
||||
- convert recurring discussion pressure into tracked issues
|
||||
- define selective-install architecture
|
||||
- write the ECC 2.0 discovery doc
|
||||
- `agentshield`, `ECC-website`, and `skill-creator-app` all have dirty
|
||||
`main` worktrees and should not be edited directly on `main`.
|
||||
- `applications/` is not a standalone git repo. It lives inside the parent
|
||||
workspace repo at `<ECC_ROOT>`.
|
||||
|
||||
## Repo: `everything-claude-code`
|
||||
|
||||
### Prompt A — PR `#399` Review and Merge Readiness
|
||||
|
||||
```text
|
||||
Work in: <ECC_ROOT>/everything-claude-code
|
||||
|
||||
Goal:
|
||||
Review PR #399 ("fix(observe): 5-layer automated session guard to prevent
|
||||
self-loop observations") against the actual loop problem described in issue
|
||||
#398 and the March 11 mega plan. Do not assume the old failing CI on the PR is
|
||||
still meaningful, because the Windows baseline was repaired later in #417.
|
||||
|
||||
Tasks:
|
||||
1. Read issue #398 and PR #399 in full.
|
||||
2. Inspect the observe hook implementation and tests locally.
|
||||
3. Determine whether the PR really prevents observer self-observation,
|
||||
automated-session observation, and runaway recursive loops.
|
||||
4. Identify any missing env-based bypass, idle gating, or session exclusion
|
||||
behavior.
|
||||
5. Produce a merge recommendation with findings ordered by severity.
|
||||
|
||||
Constraints:
|
||||
- Do not merge automatically.
|
||||
- Do not rewrite unrelated hook behavior.
|
||||
- If you make code changes, keep them tightly scoped to observe behavior and
|
||||
tests.
|
||||
|
||||
Deliverables:
|
||||
- review summary
|
||||
- exact findings with file references
|
||||
- recommended merge / rework decision
|
||||
- test commands run
|
||||
```
|
||||
|
||||
### Prompt B — Roadmap Issues Extraction
|
||||
|
||||
```text
|
||||
Work in: <ECC_ROOT>/everything-claude-code
|
||||
|
||||
Goal:
|
||||
Convert recurring discussion pressure from the mega plan into concrete GitHub
|
||||
issues. Focus on high-signal roadmap items that unblock ECC 1.x and ECC 2.0.
|
||||
|
||||
Create issue drafts or a ready-to-post issue bundle for:
|
||||
1. selective install profiles
|
||||
2. uninstall / doctor / repair lifecycle
|
||||
3. generated skill placement and provenance policy
|
||||
4. governance past the tool call
|
||||
5. ECC 2.0 discovery doc / adapter contracts
|
||||
|
||||
Tasks:
|
||||
1. Read the March 11 mega plan and March 12 handoff.
|
||||
2. Deduplicate against already-open issues.
|
||||
3. Draft issue titles, problem statements, scope, non-goals, acceptance
|
||||
criteria, and file/system areas affected.
|
||||
|
||||
Constraints:
|
||||
- Do not create filler issues.
|
||||
- Prefer 4-6 high-value issues over a large backlog dump.
|
||||
- Keep each issue scoped so it could plausibly land in one focused PR series.
|
||||
|
||||
Deliverables:
|
||||
- issue shortlist
|
||||
- ready-to-post issue bodies
|
||||
- duplication notes against existing issues
|
||||
```
|
||||
|
||||
### Prompt C — ECC 2.0 Discovery and Adapter Spec
|
||||
|
||||
```text
|
||||
Work in: <ECC_ROOT>/everything-claude-code
|
||||
|
||||
Goal:
|
||||
Turn the existing ECC 2.0 vision into a first concrete discovery doc focused on
|
||||
adapter contracts, session/task state, token accounting, and security/policy
|
||||
events.
|
||||
|
||||
Tasks:
|
||||
1. Use the current orchestration/session snapshot code as the baseline.
|
||||
2. Define a normalized adapter contract for Claude Code, Codex, OpenCode, and
|
||||
later Cursor / GitHub App integration.
|
||||
3. Define the initial SQLite-backed data model for sessions, tasks, worktrees,
|
||||
events, findings, and approvals.
|
||||
4. Define what stays in ECC 1.x versus what belongs in ECC 2.0.
|
||||
5. Call out unresolved product decisions separately from implementation
|
||||
requirements.
|
||||
|
||||
Constraints:
|
||||
- Treat the current tmux/worktree/session snapshot substrate as the starting
|
||||
point, not a blank slate.
|
||||
- Keep the doc implementation-oriented.
|
||||
|
||||
Deliverables:
|
||||
- discovery doc
|
||||
- adapter contract sketch
|
||||
- event model sketch
|
||||
- unresolved questions list
|
||||
```
|
||||
|
||||
## Repo: `agentshield`
|
||||
|
||||
### Prompt — False Positive Audit and Regression Plan
|
||||
|
||||
```text
|
||||
Work in: <ECC_ROOT>/agentshield
|
||||
|
||||
Goal:
|
||||
Advance the AgentShield Phase 2 workstream from the mega plan: reduce false
|
||||
positives, especially where declarative deny rules, block hooks, docs examples,
|
||||
or config snippets are misclassified as executable risk.
|
||||
|
||||
Important repo state:
|
||||
- branch is currently main
|
||||
- dirty files exist in CLAUDE.md and README.md
|
||||
- classify or park existing edits before broader changes
|
||||
|
||||
Tasks:
|
||||
1. Inspect the current false-positive behavior around:
|
||||
- .claude hook configs
|
||||
- AGENTS.md / CLAUDE.md
|
||||
- .cursor rules
|
||||
- .opencode plugin configs
|
||||
- sample deny-list patterns
|
||||
2. Separate parser behavior for declarative patterns vs executable commands.
|
||||
3. Propose regression coverage additions and the exact fixture set needed.
|
||||
4. If safe after branch setup, implement the first pass of the classifier fix.
|
||||
|
||||
Constraints:
|
||||
- do not work directly on dirty main
|
||||
- keep fixes parser/classifier-scoped
|
||||
- document any remaining ambiguity explicitly
|
||||
|
||||
Deliverables:
|
||||
- branch recommendation
|
||||
- false-positive taxonomy
|
||||
- proposed or landed regression tests
|
||||
- remaining edge cases
|
||||
```
|
||||
|
||||
## Repo: `ECC-website`
|
||||
|
||||
### Prompt — Landing Rewrite and Product Framing
|
||||
|
||||
```text
|
||||
Work in: <ECC_ROOT>/ECC-website
|
||||
|
||||
Goal:
|
||||
Execute the website lane from the mega plan by rewriting the landing/product
|
||||
framing away from "config repo" and toward "open agent harness system" plus
|
||||
future control-plane direction.
|
||||
|
||||
Important repo state:
|
||||
- branch is currently main
|
||||
- dirty files exist in favicon assets and multiple page/component files
|
||||
- branch before meaningful work and preserve existing edits unless explicitly
|
||||
classified as stale
|
||||
|
||||
Tasks:
|
||||
1. Classify the dirty main worktree state.
|
||||
2. Rewrite the landing page narrative around:
|
||||
- open agent harness system
|
||||
- runtime guardrails
|
||||
- cross-harness parity
|
||||
- operator visibility and security
|
||||
3. Define or update the next key pages:
|
||||
- /skills
|
||||
- /security
|
||||
- /platforms
|
||||
- /system or /dashboard
|
||||
4. Keep the page visually intentional and product-forward, not generic SaaS.
|
||||
|
||||
Constraints:
|
||||
- do not silently overwrite existing dirty work
|
||||
- preserve existing design system where it is coherent
|
||||
- distinguish ECC 1.x toolkit from ECC 2.0 control plane clearly
|
||||
|
||||
Deliverables:
|
||||
- branch recommendation
|
||||
- landing-page rewrite diff or content spec
|
||||
- follow-up page map
|
||||
- deployment readiness notes
|
||||
```
|
||||
|
||||
## Repo: `skill-creator-app`
|
||||
|
||||
### Prompt — Skill Import Pipeline and Product Fit
|
||||
|
||||
```text
|
||||
Work in: <ECC_ROOT>/skill-creator-app
|
||||
|
||||
Goal:
|
||||
Align skill-creator-app with the mega-plan external skill sourcing and audited
|
||||
import pipeline workstream.
|
||||
|
||||
Important repo state:
|
||||
- branch is currently main
|
||||
- dirty files exist in README.md and src/lib/github.ts
|
||||
- classify or park existing changes before broader work
|
||||
|
||||
Tasks:
|
||||
1. Assess whether the app should support:
|
||||
- inventorying external skills
|
||||
- provenance tagging
|
||||
- dependency/risk audit fields
|
||||
- ECC convention adaptation workflows
|
||||
2. Review the existing GitHub integration surface in src/lib/github.ts.
|
||||
3. Produce a concrete product/technical scope for an audited import pipeline.
|
||||
4. If safe after branching, land the smallest enabling changes for metadata
|
||||
capture or GitHub ingestion.
|
||||
|
||||
Constraints:
|
||||
- do not turn this into a generic prompt-builder
|
||||
- keep the focus on audited skill ingestion and ECC-compatible output
|
||||
|
||||
Deliverables:
|
||||
- product-fit summary
|
||||
- recommended scope for v1
|
||||
- data fields / workflow steps for the import pipeline
|
||||
- code changes if they are small and clearly justified
|
||||
```
|
||||
|
||||
## Repo: `ECC` Workspace (`applications/`, `knowledge/`, `tasks/`)
|
||||
|
||||
### Prompt — Example Apps and Workflow Reliability Proofs
|
||||
|
||||
```text
|
||||
Work in: <ECC_ROOT>
|
||||
|
||||
Goal:
|
||||
Use the parent ECC workspace to support the mega-plan hosted/workflow lanes.
|
||||
This is not a standalone applications repo; it is the umbrella workspace that
|
||||
contains applications/, knowledge/, tasks/, and related planning assets.
|
||||
|
||||
Tasks:
|
||||
1. Inventory what in applications/ is real product code vs placeholder.
|
||||
2. Identify where example repos or demo apps should live for:
|
||||
- GitHub App workflow proofs
|
||||
- ECC 2.0 prototype spikes
|
||||
- example install / setup reliability checks
|
||||
3. Propose a clean workspace structure so product code, research, and planning
|
||||
stop bleeding into each other.
|
||||
4. Recommend which proof-of-concept should be built first.
|
||||
|
||||
Constraints:
|
||||
- do not move large directories blindly
|
||||
- distinguish repo structure recommendations from immediate code changes
|
||||
- keep recommendations compatible with the current multi-repo ECC setup
|
||||
|
||||
Deliverables:
|
||||
- workspace inventory
|
||||
- proposed structure
|
||||
- first demo/app recommendation
|
||||
- follow-up branch/worktree plan
|
||||
```
|
||||
|
||||
## Local Continuation
|
||||
|
||||
The current worktree should stay on ECC-native Phase 1 work that does not touch
|
||||
the existing dirty skill-file changes here. The best next local tasks are:
|
||||
|
||||
1. selective-install architecture
|
||||
2. ECC 2.0 discovery doc
|
||||
3. PR `#399` review
|
||||
272
docs/PHASE1-ISSUE-BUNDLE-2026-03-12.md
Normal file
272
docs/PHASE1-ISSUE-BUNDLE-2026-03-12.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Phase 1 Issue Bundle — March 12, 2026
|
||||
|
||||
## Status
|
||||
|
||||
These issue drafts were prepared from the March 11 mega plan plus the March 12
|
||||
handoff. I attempted to open them directly in GitHub, but issue creation was
|
||||
blocked by missing GitHub authentication in the MCP session.
|
||||
|
||||
## GitHub Status
|
||||
|
||||
These drafts were later posted via `gh`:
|
||||
|
||||
- `#423` Implement manifest-driven selective install profiles for ECC
|
||||
- `#421` Add ECC install-state plus uninstall / doctor / repair lifecycle
|
||||
- `#424` Define canonical session adapter contract for ECC 2.0 control plane
|
||||
- `#422` Define generated skill placement and provenance policy
|
||||
- `#425` Define governance and visibility past the tool call
|
||||
|
||||
The bodies below are preserved as the local source bundle used to create the
|
||||
issues.
|
||||
|
||||
## Issue 1
|
||||
|
||||
### Title
|
||||
|
||||
Implement manifest-driven selective install profiles for ECC
|
||||
|
||||
### Labels
|
||||
|
||||
- `enhancement`
|
||||
|
||||
### Body
|
||||
|
||||
```md
|
||||
## Problem
|
||||
|
||||
ECC still installs primarily by target and language. The repo now has first-pass
|
||||
selective-install manifests and a non-mutating plan resolver, but the installer
|
||||
itself does not yet consume those profiles.
|
||||
|
||||
Current groundwork already landed in-repo:
|
||||
|
||||
- `manifests/install-modules.json`
|
||||
- `manifests/install-profiles.json`
|
||||
- `scripts/ci/validate-install-manifests.js`
|
||||
- `scripts/lib/install-manifests.js`
|
||||
- `scripts/install-plan.js`
|
||||
|
||||
That means the missing step is no longer design discovery. The missing step is
|
||||
execution: wire profile/module resolution into the actual install flow while
|
||||
preserving backward compatibility.
|
||||
|
||||
## Scope
|
||||
|
||||
Implement manifest-driven install execution for current ECC targets:
|
||||
|
||||
- `claude`
|
||||
- `cursor`
|
||||
- `antigravity`
|
||||
|
||||
Add first-pass support for:
|
||||
|
||||
- `ecc-install --profile <name>`
|
||||
- `ecc-install --modules <id,id,...>`
|
||||
- target-aware filtering based on module target support
|
||||
- backward-compatible legacy language installs during rollout
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Full uninstall/doctor/repair lifecycle in the same issue
|
||||
- Codex/OpenCode install targets in the first pass if that blocks rollout
|
||||
- Reorganizing the repository into separate published packages
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `install.sh` can resolve and install a named profile
|
||||
- `install.sh` can resolve explicit module IDs
|
||||
- Unsupported modules for a target are skipped or rejected deterministically
|
||||
- Legacy language-based install mode still works
|
||||
- Tests cover profile resolution and installer behavior
|
||||
- Docs explain the new preferred profile/module install path
|
||||
```
|
||||
|
||||
## Issue 2
|
||||
|
||||
### Title
|
||||
|
||||
Add ECC install-state plus uninstall / doctor / repair lifecycle
|
||||
|
||||
### Labels
|
||||
|
||||
- `enhancement`
|
||||
|
||||
### Body
|
||||
|
||||
```md
|
||||
## Problem
|
||||
|
||||
ECC has no canonical installed-state record. That makes uninstall, repair, and
|
||||
post-install inspection nondeterministic.
|
||||
|
||||
Today the repo can classify installable content, but it still cannot reliably
|
||||
answer:
|
||||
|
||||
- what profile/modules were installed
|
||||
- what target they were installed into
|
||||
- what paths ECC owns
|
||||
- how to remove or repair only ECC-managed files
|
||||
|
||||
Without install-state, lifecycle commands are guesswork.
|
||||
|
||||
## Scope
|
||||
|
||||
Introduce a durable install-state contract and the first lifecycle commands:
|
||||
|
||||
- `ecc list-installed`
|
||||
- `ecc uninstall`
|
||||
- `ecc doctor`
|
||||
- `ecc repair`
|
||||
|
||||
Suggested state locations:
|
||||
|
||||
- Claude: `~/.claude/ecc/install-state.json`
|
||||
- Cursor: `./.cursor/ecc-install-state.json`
|
||||
- Antigravity: `./.agent/ecc-install-state.json`
|
||||
|
||||
The state file should capture at minimum:
|
||||
|
||||
- installed version
|
||||
- timestamp
|
||||
- target
|
||||
- profile
|
||||
- resolved modules
|
||||
- copied/managed paths
|
||||
- source repo version or package version
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Rebuilding the installer architecture from scratch
|
||||
- Full remote/cloud control-plane functionality
|
||||
- Target support expansion beyond the current local installers unless it falls
|
||||
out naturally
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Successful installs write install-state deterministically
|
||||
- `list-installed` reports target/profile/modules/version cleanly
|
||||
- `doctor` reports missing or drifted managed paths
|
||||
- `repair` restores missing managed files from recorded install-state
|
||||
- `uninstall` removes only ECC-managed files and leaves unrelated local files
|
||||
alone
|
||||
- Tests cover install-state creation and lifecycle behavior
|
||||
```
|
||||
|
||||
## Issue 3
|
||||
|
||||
### Title
|
||||
|
||||
Define canonical session adapter contract for ECC 2.0 control plane
|
||||
|
||||
### Labels
|
||||
|
||||
- `enhancement`
|
||||
|
||||
### Body
|
||||
|
||||
```md
|
||||
## Problem
|
||||
|
||||
ECC now has real orchestration/session substrate, but it is still
|
||||
implementation-specific.
|
||||
|
||||
Current state:
|
||||
|
||||
- tmux/worktree orchestration exists
|
||||
- machine-readable session snapshots exist
|
||||
- Claude local session-history commands exist
|
||||
|
||||
What does not exist yet is a harness-neutral adapter boundary that can normalize
|
||||
session/task state across:
|
||||
|
||||
- tmux-orchestrated workers
|
||||
- plain Claude sessions
|
||||
- Codex worktrees
|
||||
- OpenCode sessions
|
||||
- later remote or GitHub-integrated operator surfaces
|
||||
|
||||
Without that adapter contract, any future ECC 2.0 operator shell will be forced
|
||||
to read tmux-specific and markdown-coordination details directly.
|
||||
|
||||
## Scope
|
||||
|
||||
Define and implement the first-pass canonical session adapter layer.
|
||||
|
||||
Suggested deliverables:
|
||||
|
||||
- adapter registry
|
||||
- canonical session snapshot schema
|
||||
- `dmux-tmux` adapter backed by current orchestration code
|
||||
- `claude-history` adapter backed by current session history utilities
|
||||
- read-only inspection CLI for canonical session snapshots
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Full ECC 2.0 UI in the same issue
|
||||
- Monetization/GitHub App implementation
|
||||
- Remote multi-user control plane
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- There is a documented canonical snapshot contract
|
||||
- Current tmux orchestration snapshot code is wrapped as an adapter rather than
|
||||
the top-level product contract
|
||||
- A second non-tmux adapter exists to prove the abstraction is real
|
||||
- Tests cover adapter selection and normalized snapshot output
|
||||
- The design clearly separates adapter concerns from orchestration and UI
|
||||
concerns
|
||||
```
|
||||
|
||||
## Issue 4
|
||||
|
||||
### Title
|
||||
|
||||
Define generated skill placement and provenance policy
|
||||
|
||||
### Labels
|
||||
|
||||
- `enhancement`
|
||||
|
||||
### Body
|
||||
|
||||
```md
|
||||
## Problem
|
||||
|
||||
ECC now has a large and growing skill surface, but generated/imported/learned
|
||||
skills do not yet have a clear long-term placement and provenance policy.
|
||||
|
||||
This creates several problems:
|
||||
|
||||
- unclear separation between curated skills and generated/learned skills
|
||||
- validator noise around directories that may or may not exist locally
|
||||
- weak provenance for imported or machine-generated skill content
|
||||
- uncertainty about where future automated learning outputs should live
|
||||
|
||||
As ECC grows, the repo needs explicit rules for where generated skill artifacts
|
||||
belong and how they are identified.
|
||||
|
||||
## Scope
|
||||
|
||||
Define a repo-wide policy for:
|
||||
|
||||
- curated vs generated vs imported skill placement
|
||||
- provenance metadata requirements
|
||||
- validator behavior for optional/generated skill directories
|
||||
- whether generated skills are shipped, ignored, or materialized during
|
||||
install/build steps
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Building a full external skill marketplace
|
||||
- Rewriting all existing skill content in one pass
|
||||
- Solving every content-quality issue in the same issue
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- A documented placement policy exists for generated/imported skills
|
||||
- Provenance requirements are explicit
|
||||
- Validators no longer produce ambiguous behavior around optional/generated
|
||||
skill locations
|
||||
- The policy clearly states what is publishable vs local-only
|
||||
- Follow-on implementation work is split into concrete, bounded PR-sized steps
|
||||
```
|
||||
59
docs/PR-399-REVIEW-2026-03-12.md
Normal file
59
docs/PR-399-REVIEW-2026-03-12.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# PR 399 Review — March 12, 2026
|
||||
|
||||
## Scope
|
||||
|
||||
Reviewed `#399`:
|
||||
|
||||
- title: `fix(observe): 5-layer automated session guard to prevent self-loop observations`
|
||||
- head: `e7df0e588ceecfcd1072ef616034ccd33bb0f251`
|
||||
- files changed:
|
||||
- `skills/continuous-learning-v2/hooks/observe.sh`
|
||||
- `skills/continuous-learning-v2/agents/observer-loop.sh`
|
||||
|
||||
## Findings
|
||||
|
||||
### Medium
|
||||
|
||||
1. `skills/continuous-learning-v2/hooks/observe.sh`
|
||||
|
||||
The new `CLAUDE_CODE_ENTRYPOINT` guard uses a finite allowlist of known
|
||||
non-`cli` values (`sdk-ts`, `sdk-py`, `sdk-cli`, `mcp`, `remote`).
|
||||
|
||||
That leaves a forward-compatibility hole: any future non-`cli` entrypoint value
|
||||
will fall through and be treated as interactive. That reintroduces the exact
|
||||
class of automated-session observation the PR is trying to prevent.
|
||||
|
||||
The safer rule is:
|
||||
|
||||
- allow only `cli`
|
||||
- treat every other explicit entrypoint as automated
|
||||
- keep the default fallback as `cli` when the variable is unset
|
||||
|
||||
Suggested shape:
|
||||
|
||||
```bash
|
||||
case "${CLAUDE_CODE_ENTRYPOINT:-cli}" in
|
||||
cli) ;;
|
||||
*) exit 0 ;;
|
||||
esac
|
||||
```
|
||||
|
||||
## Merge Recommendation
|
||||
|
||||
`Needs one follow-up change before merge.`
|
||||
|
||||
The PR direction is correct:
|
||||
|
||||
- it closes the ECC self-observation loop in `observer-loop.sh`
|
||||
- it adds multiple guard layers in the right area of `observe.sh`
|
||||
- it already addressed the cheaper-first ordering and skip-path trimming issues
|
||||
|
||||
But the entrypoint guard should be generalized before merge so the automation
|
||||
filter does not silently age out when Claude Code introduces additional
|
||||
non-interactive entrypoints.
|
||||
|
||||
## Residual Risk
|
||||
|
||||
- There is still no dedicated regression test coverage around the new shell
|
||||
guard behavior, so the final merge should include at least one executable
|
||||
verification pass for the entrypoint and skip-path cases.
|
||||
355
docs/PR-QUEUE-TRIAGE-2026-03-13.md
Normal file
355
docs/PR-QUEUE-TRIAGE-2026-03-13.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# PR Review And Queue Triage — March 13, 2026
|
||||
|
||||
## Snapshot
|
||||
|
||||
This document records a live GitHub triage snapshot for the
|
||||
`everything-claude-code` pull-request queue as of `2026-03-13T08:33:31Z`.
|
||||
|
||||
Sources used:
|
||||
|
||||
- `gh pr view`
|
||||
- `gh pr checks`
|
||||
- `gh pr diff --name-only`
|
||||
- targeted local verification against the merged `#399` head
|
||||
|
||||
Stale threshold used for this pass:
|
||||
|
||||
- `last updated before 2026-02-11` (`>30` days before March 13, 2026)
|
||||
|
||||
## PR `#399` Retrospective Review
|
||||
|
||||
PR:
|
||||
|
||||
- `#399` — `fix(observe): 5-layer automated session guard to prevent self-loop observations`
|
||||
- state: `MERGED`
|
||||
- merged at: `2026-03-13T06:40:03Z`
|
||||
- merge commit: `c52a28ace9e7e84c00309fc7b629955dfc46ecf9`
|
||||
|
||||
Files changed:
|
||||
|
||||
- `skills/continuous-learning-v2/hooks/observe.sh`
|
||||
- `skills/continuous-learning-v2/agents/observer-loop.sh`
|
||||
|
||||
Validation performed against merged head `546628182200c16cc222b97673ddd79e942eacce`:
|
||||
|
||||
- `bash -n` on both changed shell scripts
|
||||
- `node tests/hooks/hooks.test.js` (`204` passed, `0` failed)
|
||||
- targeted hook invocations for:
|
||||
- interactive CLI session
|
||||
- `CLAUDE_CODE_ENTRYPOINT=mcp`
|
||||
- `ECC_HOOK_PROFILE=minimal`
|
||||
- `ECC_SKIP_OBSERVE=1`
|
||||
- `agent_id` payload
|
||||
- trimmed `ECC_OBSERVE_SKIP_PATHS`
|
||||
|
||||
Behavioral result:
|
||||
|
||||
- the core self-loop fix works
|
||||
- automated-session guard branches suppress observation writes as intended
|
||||
- the final `non-cli => exit` entrypoint logic is the correct fail-closed shape
|
||||
|
||||
Remaining findings:
|
||||
|
||||
1. Medium: skipped automated sessions still create homunculus project state
|
||||
before the new guards exit.
|
||||
`observe.sh` resolves `cwd` and sources project detection before reaching the
|
||||
automated-session guard block, so `detect-project.sh` still creates
|
||||
`projects/<id>/...` directories and updates `projects.json` for sessions that
|
||||
later exit early.
|
||||
2. Low: the new guard matrix shipped without direct regression coverage.
|
||||
The hook test suite still validates adjacent behavior, but it does not
|
||||
directly assert the new `CLAUDE_CODE_ENTRYPOINT`, `ECC_HOOK_PROFILE`,
|
||||
`ECC_SKIP_OBSERVE`, `agent_id`, or trimmed skip-path branches.
|
||||
|
||||
Verdict:
|
||||
|
||||
- `#399` is technically correct for its primary goal and was safe to merge as
|
||||
the urgent loop-stop fix.
|
||||
- It still warrants a follow-up issue or patch to move automated-session guards
|
||||
ahead of project-registration side effects and to add explicit guard-path
|
||||
tests.
|
||||
|
||||
## Open PR Inventory
|
||||
|
||||
There are currently `4` open PRs.
|
||||
|
||||
### Queue Table
|
||||
|
||||
| PR | Title | Draft | Mergeable | Merge State | Updated | Stale | Current Verdict |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| `#292` | `chore(config): governance and config foundation (PR #272 split 1/6)` | `false` | `MERGEABLE` | `UNSTABLE` | `2026-03-13T07:26:55Z` | `No` | `Best current merge candidate` |
|
||||
| `#298` | `feat(agents,skills,rules): add Rust, Java, mobile, DevOps, and performance content` | `false` | `CONFLICTING` | `DIRTY` | `2026-03-11T04:29:07Z` | `No` | `Needs changes before review can finish` |
|
||||
| `#336` | `Customisation for Codex CLI - Features from Claude Code and OpenCode` | `true` | `MERGEABLE` | `UNSTABLE` | `2026-03-13T07:26:12Z` | `No` | `Needs manual review and draft exit` |
|
||||
| `#420` | `feat: add laravel skills` | `true` | `MERGEABLE` | `UNSTABLE` | `2026-03-12T22:57:36Z` | `No` | `Low-risk draft, review after draft exit` |
|
||||
|
||||
No currently open PR is stale by the `>30 days since last update` rule.
|
||||
|
||||
## Per-PR Assessment
|
||||
|
||||
### `#292` — Governance / Config Foundation
|
||||
|
||||
Live state:
|
||||
|
||||
- open
|
||||
- non-draft
|
||||
- `MERGEABLE`
|
||||
- merge state `UNSTABLE`
|
||||
- visible checks:
|
||||
- `CodeRabbit` passed
|
||||
- `GitGuardian Security Checks` passed
|
||||
|
||||
Scope:
|
||||
|
||||
- `.env.example`
|
||||
- `.github/ISSUE_TEMPLATE/copilot-task.md`
|
||||
- `.github/PULL_REQUEST_TEMPLATE.md`
|
||||
- `.gitignore`
|
||||
- `.markdownlint.json`
|
||||
- `.tool-versions`
|
||||
- `VERSION`
|
||||
|
||||
Assessment:
|
||||
|
||||
- This is the cleanest merge candidate in the current queue.
|
||||
- The branch was already refreshed onto current `main`.
|
||||
- The currently visible bot feedback is minor/nit-level rather than obviously
|
||||
merge-blocking.
|
||||
- The main caution is that only external bot checks are visible right now; no
|
||||
GitHub Actions matrix run appears in the current PR checks output.
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Mergeable after one final owner pass.`
|
||||
- If you want a conservative path, do one quick human review of the remaining
|
||||
`.env.example`, PR-template, and `.tool-versions` nitpicks before merge.
|
||||
|
||||
### `#298` — Large Multi-Domain Content Expansion
|
||||
|
||||
Live state:
|
||||
|
||||
- open
|
||||
- non-draft
|
||||
- `CONFLICTING`
|
||||
- merge state `DIRTY`
|
||||
- visible checks:
|
||||
- `CodeRabbit` passed
|
||||
- `GitGuardian Security Checks` passed
|
||||
- `cubic · AI code reviewer` passed
|
||||
|
||||
Scope:
|
||||
|
||||
- `35` files
|
||||
- large documentation and skill/rule expansion across Java, Rust, mobile,
|
||||
DevOps, performance, data, and MLOps
|
||||
|
||||
Assessment:
|
||||
|
||||
- This PR is not ready for merge.
|
||||
- It conflicts with current `main`, so it is not even mergeable at the branch
|
||||
level yet.
|
||||
- cubic identified `34` issues across `35` files in the current review.
|
||||
Those findings are substantive and technical, not just style cleanup, and
|
||||
they cover broken or misleading examples across several new skills.
|
||||
- Even without the conflict, the scope is large enough that it needs a deliberate
|
||||
content-fix pass rather than a quick merge decision.
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Needs changes.`
|
||||
- Rebase or restack first, then resolve the substantive example-quality issues.
|
||||
- If momentum matters, split by domain rather than carrying one very large PR.
|
||||
|
||||
### `#336` — Codex CLI Customization
|
||||
|
||||
Live state:
|
||||
|
||||
- open
|
||||
- draft
|
||||
- `MERGEABLE`
|
||||
- merge state `UNSTABLE`
|
||||
- visible checks:
|
||||
- `CodeRabbit` passed
|
||||
- `GitGuardian Security Checks` passed
|
||||
|
||||
Scope:
|
||||
|
||||
- `scripts/codex-git-hooks/pre-commit`
|
||||
- `scripts/codex-git-hooks/pre-push`
|
||||
- `scripts/codex/check-codex-global-state.sh`
|
||||
- `scripts/codex/install-global-git-hooks.sh`
|
||||
- `scripts/sync-ecc-to-codex.sh`
|
||||
|
||||
Assessment:
|
||||
|
||||
- This PR is no longer conflicting, but it is still draft-only and has not had
|
||||
a meaningful first-party review pass.
|
||||
- It modifies user-global Codex setup behavior and git-hook installation, so the
|
||||
operational blast radius is higher than a docs-only PR.
|
||||
- The visible checks are only external bots; there is no full GitHub Actions run
|
||||
shown in the current check set.
|
||||
- Because the branch comes from a contributor fork `main`, it also deserves an
|
||||
extra sanity pass on what exactly is being proposed before changing status.
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Needs changes before merge readiness`, where the required changes are process
|
||||
and review oriented rather than an already-proven code defect:
|
||||
- finish manual review
|
||||
- run or confirm validation on the global-state scripts
|
||||
- take it out of draft only after that review is complete
|
||||
|
||||
### `#420` — Laravel Skills
|
||||
|
||||
Live state:
|
||||
|
||||
- open
|
||||
- draft
|
||||
- `MERGEABLE`
|
||||
- merge state `UNSTABLE`
|
||||
- visible checks:
|
||||
- `CodeRabbit` passed
|
||||
- `GitGuardian Security Checks` passed
|
||||
|
||||
Scope:
|
||||
|
||||
- `README.md`
|
||||
- `examples/laravel-api-CLAUDE.md`
|
||||
- `rules/php/patterns.md`
|
||||
- `rules/php/security.md`
|
||||
- `rules/php/testing.md`
|
||||
- `skills/configure-ecc/SKILL.md`
|
||||
- `skills/laravel-patterns/SKILL.md`
|
||||
- `skills/laravel-security/SKILL.md`
|
||||
- `skills/laravel-tdd/SKILL.md`
|
||||
- `skills/laravel-verification/SKILL.md`
|
||||
|
||||
Assessment:
|
||||
|
||||
- This is content-heavy and operationally lower risk than `#336`.
|
||||
- It is still draft and has not had a substantive human review pass yet.
|
||||
- The visible checks are external bots only.
|
||||
- Nothing in the live PR state suggests a merge blocker yet, but it is not ready
|
||||
to be merged simply because it is still draft and under-reviewed.
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Review next after the highest-priority non-draft work.`
|
||||
- Likely a good review candidate once the author is ready to exit draft.
|
||||
|
||||
## Mergeability Buckets
|
||||
|
||||
### Mergeable Now Or After A Final Owner Pass
|
||||
|
||||
- `#292`
|
||||
|
||||
### Needs Changes Before Merge
|
||||
|
||||
- `#298`
|
||||
- `#336`
|
||||
|
||||
### Draft / Needs Review Before Any Merge Decision
|
||||
|
||||
- `#420`
|
||||
|
||||
### Stale `>30 Days`
|
||||
|
||||
- none
|
||||
|
||||
## Recommended Order
|
||||
|
||||
1. `#292`
|
||||
This is the cleanest live merge candidate.
|
||||
2. `#420`
|
||||
Low runtime risk, but wait for draft exit and a real review pass.
|
||||
3. `#336`
|
||||
Review carefully because it changes global Codex sync and hook behavior.
|
||||
4. `#298`
|
||||
Rebase and fix the substantive content issues before spending more review time
|
||||
on it.
|
||||
|
||||
## Bottom Line
|
||||
|
||||
- `#399`: safe bugfix merge with one follow-up cleanup still warranted
|
||||
- `#292`: highest-priority merge candidate in the current open queue
|
||||
- `#298`: not mergeable; conflicts plus substantive content defects
|
||||
- `#336`: no longer conflicting, but not ready while still draft and lightly
|
||||
validated
|
||||
- `#420`: draft, low-risk content lane, review after the non-draft queue
|
||||
|
||||
## Live Refresh
|
||||
|
||||
Refreshed at `2026-03-13T22:11:40Z`.
|
||||
|
||||
### Main Branch
|
||||
|
||||
- `origin/main` is green right now, including the Windows test matrix.
|
||||
- Mainline CI repair is not the current bottleneck.
|
||||
|
||||
### Updated Queue Read
|
||||
|
||||
#### `#292` — Governance / Config Foundation
|
||||
|
||||
- open
|
||||
- non-draft
|
||||
- `MERGEABLE`
|
||||
- visible checks:
|
||||
- `CodeRabbit` passed
|
||||
- `GitGuardian Security Checks` passed
|
||||
- highest-signal remaining work is not CI repair; it is the small correctness
|
||||
pass on `.env.example` and PR-template alignment before merge
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Next actionable PR.`
|
||||
- Either patch the remaining doc/config correctness issues, or do one final
|
||||
owner pass and merge if you accept the current tradeoffs.
|
||||
|
||||
#### `#420` — Laravel Skills
|
||||
|
||||
- open
|
||||
- draft
|
||||
- `MERGEABLE`
|
||||
- visible checks:
|
||||
- `CodeRabbit` skipped because the PR is draft
|
||||
- `GitGuardian Security Checks` passed
|
||||
- no substantive human review is visible yet
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Review after the non-draft queue.`
|
||||
- Low implementation risk, but not merge-ready while still draft and
|
||||
under-reviewed.
|
||||
|
||||
#### `#336` — Codex CLI Customization
|
||||
|
||||
- open
|
||||
- draft
|
||||
- `MERGEABLE`
|
||||
- visible checks:
|
||||
- `CodeRabbit` passed
|
||||
- `GitGuardian Security Checks` passed
|
||||
- still needs a deliberate manual review because it touches global Codex sync
|
||||
and git-hook installation behavior
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Manual-review lane, not immediate merge lane.`
|
||||
|
||||
#### `#298` — Large Content Expansion
|
||||
|
||||
- open
|
||||
- non-draft
|
||||
- `CONFLICTING`
|
||||
- still the hardest remaining PR in the queue
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- `Last priority among current open PRs.`
|
||||
- Rebase first, then handle the substantive content/example corrections.
|
||||
|
||||
### Current Order
|
||||
|
||||
1. `#292`
|
||||
2. `#420`
|
||||
3. `#336`
|
||||
4. `#298`
|
||||
933
docs/SELECTIVE-INSTALL-ARCHITECTURE.md
Normal file
933
docs/SELECTIVE-INSTALL-ARCHITECTURE.md
Normal file
@@ -0,0 +1,933 @@
|
||||
# ECC 2.0 Selective Install Discovery
|
||||
|
||||
## Purpose
|
||||
|
||||
This document turns the March 11 mega-plan selective-install requirement into a
|
||||
concrete ECC 2.0 discovery design.
|
||||
|
||||
The goal is not just "fewer files copied during install." The actual target is
|
||||
an install system that can answer, deterministically:
|
||||
|
||||
- what was requested
|
||||
- what was resolved
|
||||
- what was copied or generated
|
||||
- what target-specific transforms were applied
|
||||
- what ECC owns and may safely remove or repair later
|
||||
|
||||
That is the missing contract between ECC 1.x installation and an ECC 2.0
|
||||
control plane.
|
||||
|
||||
## Current Implemented Foundation
|
||||
|
||||
The first selective-install substrate already exists in-repo:
|
||||
|
||||
- `manifests/install-modules.json`
|
||||
- `manifests/install-profiles.json`
|
||||
- `schemas/install-modules.schema.json`
|
||||
- `schemas/install-profiles.schema.json`
|
||||
- `schemas/install-state.schema.json`
|
||||
- `scripts/ci/validate-install-manifests.js`
|
||||
- `scripts/lib/install-manifests.js`
|
||||
- `scripts/lib/install/request.js`
|
||||
- `scripts/lib/install/runtime.js`
|
||||
- `scripts/lib/install/apply.js`
|
||||
- `scripts/lib/install-targets/`
|
||||
- `scripts/lib/install-state.js`
|
||||
- `scripts/lib/install-executor.js`
|
||||
- `scripts/lib/install-lifecycle.js`
|
||||
- `scripts/ecc.js`
|
||||
- `scripts/install-apply.js`
|
||||
- `scripts/install-plan.js`
|
||||
- `scripts/list-installed.js`
|
||||
- `scripts/doctor.js`
|
||||
|
||||
Current capabilities:
|
||||
|
||||
- machine-readable module and profile catalogs
|
||||
- CI validation that manifest entries point at real repo paths
|
||||
- dependency expansion and target filtering
|
||||
- adapter-aware operation planning
|
||||
- canonical request normalization for legacy and manifest install modes
|
||||
- explicit runtime dispatch from normalized requests into plan creation
|
||||
- legacy and manifest installs both write durable install-state
|
||||
- read-only inspection of install plans before any mutation
|
||||
- unified `ecc` CLI routing install, planning, and lifecycle commands
|
||||
- lifecycle inspection and mutation via `list-installed`, `doctor`, `repair`,
|
||||
and `uninstall`
|
||||
|
||||
Current limitation:
|
||||
|
||||
- target-specific merge/remove semantics are still scaffold-level for some modules
|
||||
- legacy `ecc-install` compatibility still points at `install.sh`
|
||||
- publish surface is still broad in `package.json`
|
||||
|
||||
## Current Code Review
|
||||
|
||||
The current installer stack is already much healthier than the original
|
||||
language-first shell installer, but it still concentrates too much
|
||||
responsibility in a few files.
|
||||
|
||||
### Current Runtime Path
|
||||
|
||||
The runtime flow today is:
|
||||
|
||||
1. `install.sh`
|
||||
thin shell wrapper that resolves the real package root
|
||||
2. `scripts/install-apply.js`
|
||||
user-facing installer CLI for legacy and manifest modes
|
||||
3. `scripts/lib/install/request.js`
|
||||
CLI parsing plus canonical request normalization
|
||||
4. `scripts/lib/install/runtime.js`
|
||||
runtime dispatch from normalized requests into install plans
|
||||
5. `scripts/lib/install-executor.js`
|
||||
argument translation, legacy compatibility, operation materialization,
|
||||
filesystem mutation, and install-state write
|
||||
6. `scripts/lib/install-manifests.js`
|
||||
module/profile catalog loading plus dependency expansion
|
||||
7. `scripts/lib/install-targets/`
|
||||
target root and destination-path scaffolding
|
||||
8. `scripts/lib/install-state.js`
|
||||
schema-backed install-state read/write
|
||||
9. `scripts/lib/install-lifecycle.js`
|
||||
doctor/repair/uninstall behavior derived from stored operations
|
||||
|
||||
That is enough to prove the selective-install substrate, but not enough to make
|
||||
the installer architecture feel settled.
|
||||
|
||||
### Current Strengths
|
||||
|
||||
- install intent is now explicit through `--profile` and `--modules`
|
||||
- request parsing and request normalization are now split from the CLI shell
|
||||
- target root resolution is already adapterized
|
||||
- lifecycle commands now use durable install-state instead of guessing
|
||||
- the repo already has a unified Node entrypoint through `ecc` and
|
||||
`install-apply.js`
|
||||
|
||||
### Current Coupling Still Present
|
||||
|
||||
1. `install-executor.js` is smaller than before, but still carrying too many
|
||||
planning and materialization layers at once.
|
||||
The request boundary is now extracted, but legacy request translation,
|
||||
manifest-plan expansion, and operation materialization still live together.
|
||||
2. target adapters are still too thin.
|
||||
Today they mostly resolve roots and scaffold destination paths. The real
|
||||
install semantics still live in executor branches and path heuristics.
|
||||
3. the planner/executor boundary is not clean enough yet.
|
||||
`install-manifests.js` resolves modules, but the final install operation set
|
||||
is still partly constructed in executor-specific logic.
|
||||
4. lifecycle behavior depends on low-level recorded operations more than on
|
||||
stable module semantics.
|
||||
That works for plain file copy, but becomes brittle for merge/generate/remove
|
||||
behaviors.
|
||||
5. compatibility mode is mixed directly into the main installer runtime.
|
||||
Legacy language installs should behave like a request adapter, not as a
|
||||
parallel installer architecture.
|
||||
|
||||
## Proposed Modular Architecture Changes
|
||||
|
||||
The next architectural step is to separate the installer into explicit layers,
|
||||
with each layer returning stable data instead of immediately mutating files.
|
||||
|
||||
### Target State
|
||||
|
||||
The desired install pipeline is:
|
||||
|
||||
1. CLI surface
|
||||
2. request normalization
|
||||
3. module resolution
|
||||
4. target planning
|
||||
5. operation planning
|
||||
6. execution
|
||||
7. install-state persistence
|
||||
8. lifecycle services built on the same operation contract
|
||||
|
||||
The main idea is simple:
|
||||
|
||||
- manifests describe content
|
||||
- adapters describe target-specific landing semantics
|
||||
- planners describe what should happen
|
||||
- executors apply those plans
|
||||
- lifecycle commands reuse the same plan/state model instead of reinventing it
|
||||
|
||||
### Proposed Runtime Layers
|
||||
|
||||
#### 1. CLI Surface
|
||||
|
||||
Responsibility:
|
||||
|
||||
- parse user intent only
|
||||
- route to install, plan, doctor, repair, uninstall
|
||||
- render human or JSON output
|
||||
|
||||
Should not own:
|
||||
|
||||
- legacy language translation
|
||||
- target-specific install rules
|
||||
- operation construction
|
||||
|
||||
Suggested files:
|
||||
|
||||
```text
|
||||
scripts/ecc.js
|
||||
scripts/install-apply.js
|
||||
scripts/install-plan.js
|
||||
scripts/doctor.js
|
||||
scripts/repair.js
|
||||
scripts/uninstall.js
|
||||
```
|
||||
|
||||
These stay as entrypoints, but become thin wrappers around library modules.
|
||||
|
||||
#### 2. Request Normalizer
|
||||
|
||||
Responsibility:
|
||||
|
||||
- translate raw CLI flags into a canonical install request
|
||||
- convert legacy language installs into a compatibility request shape
|
||||
- reject mixed or ambiguous inputs early
|
||||
|
||||
Suggested canonical request:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "manifest",
|
||||
"target": "cursor",
|
||||
"profile": "developer",
|
||||
"modules": [],
|
||||
"legacyLanguages": [],
|
||||
"dryRun": false
|
||||
}
|
||||
```
|
||||
|
||||
or, in compatibility mode:
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "legacy-compat",
|
||||
"target": "claude",
|
||||
"profile": null,
|
||||
"modules": [],
|
||||
"legacyLanguages": ["typescript", "python"],
|
||||
"dryRun": false
|
||||
}
|
||||
```
|
||||
|
||||
This lets the rest of the pipeline ignore whether the request came from old or
|
||||
new CLI syntax.
|
||||
|
||||
#### 3. Module Resolver
|
||||
|
||||
Responsibility:
|
||||
|
||||
- load manifest catalogs
|
||||
- expand dependencies
|
||||
- reject conflicts
|
||||
- filter unsupported modules per target
|
||||
- return a canonical resolution object
|
||||
|
||||
This layer should stay pure and read-only.
|
||||
|
||||
It should not know:
|
||||
|
||||
- destination filesystem paths
|
||||
- merge semantics
|
||||
- copy strategies
|
||||
|
||||
Current nearest file:
|
||||
|
||||
- `scripts/lib/install-manifests.js`
|
||||
|
||||
Suggested split:
|
||||
|
||||
```text
|
||||
scripts/lib/install/catalog.js
|
||||
scripts/lib/install/resolve-request.js
|
||||
scripts/lib/install/resolve-modules.js
|
||||
```
|
||||
|
||||
#### 4. Target Planner
|
||||
|
||||
Responsibility:
|
||||
|
||||
- select the install target adapter
|
||||
- resolve target root
|
||||
- resolve install-state path
|
||||
- expand module-to-target mapping rules
|
||||
- emit target-aware operation intents
|
||||
|
||||
This is where target-specific meaning should live.
|
||||
|
||||
Examples:
|
||||
|
||||
- Claude may preserve native hierarchy under `~/.claude`
|
||||
- Cursor may sync bundled `.cursor` root children differently from rules
|
||||
- generated configs may require merge or replace semantics depending on target
|
||||
|
||||
Current nearest files:
|
||||
|
||||
- `scripts/lib/install-targets/helpers.js`
|
||||
- `scripts/lib/install-targets/registry.js`
|
||||
|
||||
Suggested evolution:
|
||||
|
||||
```text
|
||||
scripts/lib/install/targets/registry.js
|
||||
scripts/lib/install/targets/claude-home.js
|
||||
scripts/lib/install/targets/cursor-project.js
|
||||
scripts/lib/install/targets/antigravity-project.js
|
||||
```
|
||||
|
||||
Each adapter should eventually expose more than `resolveRoot`.
|
||||
It should own path and strategy mapping for its target family.
|
||||
|
||||
#### 5. Operation Planner
|
||||
|
||||
Responsibility:
|
||||
|
||||
- turn module resolution plus adapter rules into a typed operation graph
|
||||
- emit first-class operations such as:
|
||||
- `copy-file`
|
||||
- `copy-tree`
|
||||
- `merge-json`
|
||||
- `render-template`
|
||||
- `remove`
|
||||
- attach ownership and validation metadata
|
||||
|
||||
This is the missing architectural seam in the current installer.
|
||||
|
||||
Today, operations are partly scaffold-level and partly executor-specific.
|
||||
ECC 2.0 should make operation planning a standalone phase so that:
|
||||
|
||||
- `plan` becomes a true preview of execution
|
||||
- `doctor` can validate intended behavior, not just current files
|
||||
- `repair` can rebuild exact missing work safely
|
||||
- `uninstall` can reverse only managed operations
|
||||
|
||||
#### 6. Execution Engine
|
||||
|
||||
Responsibility:
|
||||
|
||||
- apply a typed operation graph
|
||||
- enforce overwrite and ownership rules
|
||||
- stage writes safely
|
||||
- collect final applied-operation results
|
||||
|
||||
This layer should not decide *what* to do.
|
||||
It should only decide *how* to apply a provided operation kind safely.
|
||||
|
||||
Current nearest file:
|
||||
|
||||
- `scripts/lib/install-executor.js`
|
||||
|
||||
Recommended refactor:
|
||||
|
||||
```text
|
||||
scripts/lib/install/executor/apply-plan.js
|
||||
scripts/lib/install/executor/apply-copy.js
|
||||
scripts/lib/install/executor/apply-merge-json.js
|
||||
scripts/lib/install/executor/apply-remove.js
|
||||
```
|
||||
|
||||
That turns executor logic from one large branching runtime into a set of small
|
||||
operation handlers.
|
||||
|
||||
#### 7. Install-State Store
|
||||
|
||||
Responsibility:
|
||||
|
||||
- validate and persist install-state
|
||||
- record canonical request, resolution, and applied operations
|
||||
- support lifecycle commands without forcing them to reverse-engineer installs
|
||||
|
||||
Current nearest file:
|
||||
|
||||
- `scripts/lib/install-state.js`
|
||||
|
||||
This layer is already close to the right shape. The main remaining change is to
|
||||
store richer operation metadata once merge/generate semantics are real.
|
||||
|
||||
#### 8. Lifecycle Services
|
||||
|
||||
Responsibility:
|
||||
|
||||
- `list-installed`: inspect state only
|
||||
- `doctor`: compare desired/install-state view against current filesystem
|
||||
- `repair`: regenerate a plan from state and reapply safe operations
|
||||
- `uninstall`: remove only ECC-owned outputs
|
||||
|
||||
Current nearest file:
|
||||
|
||||
- `scripts/lib/install-lifecycle.js`
|
||||
|
||||
This layer should eventually operate on operation kinds and ownership policies,
|
||||
not just on raw `copy-file` records.
|
||||
|
||||
## Proposed File Layout
|
||||
|
||||
The clean modular end state should look roughly like this:
|
||||
|
||||
```text
|
||||
scripts/lib/install/
|
||||
catalog.js
|
||||
request.js
|
||||
resolve-modules.js
|
||||
plan-operations.js
|
||||
state-store.js
|
||||
targets/
|
||||
registry.js
|
||||
claude-home.js
|
||||
cursor-project.js
|
||||
antigravity-project.js
|
||||
codex-home.js
|
||||
opencode-home.js
|
||||
executor/
|
||||
apply-plan.js
|
||||
apply-copy.js
|
||||
apply-merge-json.js
|
||||
apply-render-template.js
|
||||
apply-remove.js
|
||||
lifecycle/
|
||||
discover.js
|
||||
doctor.js
|
||||
repair.js
|
||||
uninstall.js
|
||||
```
|
||||
|
||||
This is not a packaging split.
|
||||
It is a code-ownership split inside the current repo so each layer has one job.
|
||||
|
||||
## Migration Map From Current Files
|
||||
|
||||
The lowest-risk migration path is evolutionary, not a rewrite.
|
||||
|
||||
### Keep
|
||||
|
||||
- `install.sh` as the public compatibility shim
|
||||
- `scripts/ecc.js` as the unified CLI
|
||||
- `scripts/lib/install-state.js` as the starting point for the state store
|
||||
- current target adapter IDs and state locations
|
||||
|
||||
### Extract
|
||||
|
||||
- request parsing and compatibility translation out of
|
||||
`scripts/lib/install-executor.js`
|
||||
- target-aware operation planning out of executor branches and into target
|
||||
adapters plus planner modules
|
||||
- lifecycle-specific analysis out of the shared lifecycle monolith into smaller
|
||||
services
|
||||
|
||||
### Replace Gradually
|
||||
|
||||
- broad path-copy heuristics with typed operations
|
||||
- scaffold-only adapter planning with adapter-owned semantics
|
||||
- legacy language install branches with legacy request translation into the same
|
||||
planner/executor pipeline
|
||||
|
||||
## Immediate Architecture Changes To Make Next
|
||||
|
||||
If the goal is ECC 2.0 and not just “working enough,” the next modularization
|
||||
steps should be:
|
||||
|
||||
1. split `install-executor.js` into request normalization, operation planning,
|
||||
and execution modules
|
||||
2. move target-specific strategy decisions into adapter-owned planning methods
|
||||
3. make `repair` and `uninstall` operate on typed operation handlers rather than
|
||||
only plain `copy-file` records
|
||||
4. teach manifests about install strategy and ownership so the planner no
|
||||
longer depends on path heuristics
|
||||
5. narrow the npm publish surface only after the internal module boundaries are
|
||||
stable
|
||||
|
||||
## Why The Current Model Is Not Enough
|
||||
|
||||
Today ECC still behaves like a broad payload copier:
|
||||
|
||||
- `install.sh` is language-first and target-branch-heavy
|
||||
- targets are partly implicit in directory layout
|
||||
- uninstall, repair, and doctor now exist but are still early lifecycle commands
|
||||
- the repo cannot prove what a prior install actually wrote
|
||||
- publish surface is still broad in `package.json`
|
||||
|
||||
That creates the problems already called out in the mega plan:
|
||||
|
||||
- users pull more content than their harness or workflow needs
|
||||
- support and upgrades are harder because installs are not recorded
|
||||
- target behavior drifts because install logic is duplicated in shell branches
|
||||
- future targets like Codex or OpenCode require more special-case logic instead
|
||||
of reusing a stable install contract
|
||||
|
||||
## ECC 2.0 Design Thesis
|
||||
|
||||
Selective install should be modeled as:
|
||||
|
||||
1. resolve requested intent into a canonical module graph
|
||||
2. translate that graph through a target adapter
|
||||
3. execute a deterministic install operation set
|
||||
4. write install-state as the durable source of truth
|
||||
|
||||
That means ECC 2.0 needs two contracts, not one:
|
||||
|
||||
- a content contract
|
||||
what modules exist and how they depend on each other
|
||||
- a target contract
|
||||
how those modules land inside Claude, Cursor, Antigravity, Codex, or OpenCode
|
||||
|
||||
The current repo only had the first half in early form.
|
||||
The current repo now has the first full vertical slice, but not the full
|
||||
target-specific semantics.
|
||||
|
||||
## Design Constraints
|
||||
|
||||
1. Keep `everything-claude-code` as the canonical source repo.
|
||||
2. Preserve existing `install.sh` flows during migration.
|
||||
3. Support home-scoped and project-scoped targets from the same planner.
|
||||
4. Make uninstall/repair/doctor possible without guessing.
|
||||
5. Avoid per-target copy logic leaking back into module definitions.
|
||||
6. Keep future Codex and OpenCode support additive, not a rewrite.
|
||||
|
||||
## Canonical Artifacts
|
||||
|
||||
### 1. Module Catalog
|
||||
|
||||
The module catalog is the canonical content graph.
|
||||
|
||||
Current fields already implemented:
|
||||
|
||||
- `id`
|
||||
- `kind`
|
||||
- `description`
|
||||
- `paths`
|
||||
- `targets`
|
||||
- `dependencies`
|
||||
- `defaultInstall`
|
||||
- `cost`
|
||||
- `stability`
|
||||
|
||||
Fields still needed for ECC 2.0:
|
||||
|
||||
- `installStrategy`
|
||||
for example `copy`, `flatten-rules`, `generate`, `merge-config`
|
||||
- `ownership`
|
||||
whether ECC fully owns the target path or only generated files under it
|
||||
- `pathMode`
|
||||
for example `preserve`, `flatten`, `target-template`
|
||||
- `conflicts`
|
||||
modules or path families that cannot coexist on one target
|
||||
- `publish`
|
||||
whether the module is packaged by default, optional, or generated post-install
|
||||
|
||||
Suggested future shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "hooks-runtime",
|
||||
"kind": "hooks",
|
||||
"paths": ["hooks", "scripts/hooks"],
|
||||
"targets": ["claude", "cursor", "opencode"],
|
||||
"dependencies": [],
|
||||
"installStrategy": "copy",
|
||||
"pathMode": "preserve",
|
||||
"ownership": "managed",
|
||||
"defaultInstall": true,
|
||||
"cost": "medium",
|
||||
"stability": "stable"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Profile Catalog
|
||||
|
||||
Profiles stay thin.
|
||||
|
||||
They should express user intent, not duplicate target logic.
|
||||
|
||||
Current examples already implemented:
|
||||
|
||||
- `core`
|
||||
- `developer`
|
||||
- `security`
|
||||
- `research`
|
||||
- `full`
|
||||
|
||||
Fields still needed:
|
||||
|
||||
- `defaultTargets`
|
||||
- `recommendedFor`
|
||||
- `excludes`
|
||||
- `requiresConfirmation`
|
||||
|
||||
That lets ECC 2.0 say things like:
|
||||
|
||||
- `developer` is the recommended default for Claude and Cursor
|
||||
- `research` may be heavy for narrow local installs
|
||||
- `full` is allowed but not default
|
||||
|
||||
### 3. Target Adapters
|
||||
|
||||
This is the main missing layer.
|
||||
|
||||
The module graph should not know:
|
||||
|
||||
- where Claude home lives
|
||||
- how Cursor flattens or remaps content
|
||||
- which config files need merge semantics instead of blind copy
|
||||
|
||||
That belongs to a target adapter.
|
||||
|
||||
Suggested interface:
|
||||
|
||||
```ts
|
||||
type InstallTargetAdapter = {
|
||||
id: string;
|
||||
kind: "home" | "project";
|
||||
supports(target: string): boolean;
|
||||
resolveRoot(input?: string): Promise<string>;
|
||||
planOperations(input: InstallOperationInput): Promise<InstallOperation[]>;
|
||||
validate?(input: InstallOperationInput): Promise<ValidationIssue[]>;
|
||||
};
|
||||
```
|
||||
|
||||
Suggested first adapters:
|
||||
|
||||
1. `claude-home`
|
||||
writes into `~/.claude/...`
|
||||
2. `cursor-project`
|
||||
writes into `./.cursor/...`
|
||||
3. `antigravity-project`
|
||||
writes into `./.agent/...`
|
||||
4. `codex-home`
|
||||
later
|
||||
5. `opencode-home`
|
||||
later
|
||||
|
||||
This matches the same pattern already proposed in the session-adapter discovery
|
||||
doc: canonical contract first, harness-specific adapter second.
|
||||
|
||||
## Install Planning Model
|
||||
|
||||
The current `scripts/install-plan.js` CLI proves the repo can resolve requested
|
||||
modules into a filtered module set.
|
||||
|
||||
ECC 2.0 needs the next layer: operation planning.
|
||||
|
||||
Suggested phases:
|
||||
|
||||
1. input normalization
|
||||
- parse `--target`
|
||||
- parse `--profile`
|
||||
- parse `--modules`
|
||||
- optionally translate legacy language args
|
||||
2. module resolution
|
||||
- expand dependencies
|
||||
- reject conflicts
|
||||
- filter by supported targets
|
||||
3. adapter planning
|
||||
- resolve target root
|
||||
- derive exact copy or generation operations
|
||||
- identify config merges and target remaps
|
||||
4. dry-run output
|
||||
- show selected modules
|
||||
- show skipped modules
|
||||
- show exact file operations
|
||||
5. mutation
|
||||
- execute the operation plan
|
||||
6. state write
|
||||
- persist install-state only after successful completion
|
||||
|
||||
Suggested operation shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "copy",
|
||||
"moduleId": "rules-core",
|
||||
"source": "rules/common/coding-style.md",
|
||||
"destination": "/Users/example/.claude/rules/common/coding-style.md",
|
||||
"ownership": "managed",
|
||||
"overwritePolicy": "replace"
|
||||
}
|
||||
```
|
||||
|
||||
Other operation kinds:
|
||||
|
||||
- `copy`
|
||||
- `copy-tree`
|
||||
- `flatten-copy`
|
||||
- `render-template`
|
||||
- `merge-json`
|
||||
- `merge-jsonc`
|
||||
- `mkdir`
|
||||
- `remove`
|
||||
|
||||
## Install-State Contract
|
||||
|
||||
Install-state is the durable contract that ECC 1.x is missing.
|
||||
|
||||
Suggested path conventions:
|
||||
|
||||
- Claude target:
|
||||
`~/.claude/ecc/install-state.json`
|
||||
- Cursor target:
|
||||
`./.cursor/ecc-install-state.json`
|
||||
- Antigravity target:
|
||||
`./.agent/ecc-install-state.json`
|
||||
- future Codex target:
|
||||
`~/.codex/ecc-install-state.json`
|
||||
|
||||
Suggested payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "ecc.install.v1",
|
||||
"installedAt": "2026-03-13T00:00:00Z",
|
||||
"lastValidatedAt": "2026-03-13T00:00:00Z",
|
||||
"target": {
|
||||
"id": "claude-home",
|
||||
"root": "/Users/example/.claude"
|
||||
},
|
||||
"request": {
|
||||
"profile": "developer",
|
||||
"modules": ["orchestration"],
|
||||
"legacyLanguages": ["typescript", "python"]
|
||||
},
|
||||
"resolution": {
|
||||
"selectedModules": [
|
||||
"rules-core",
|
||||
"agents-core",
|
||||
"commands-core",
|
||||
"hooks-runtime",
|
||||
"platform-configs",
|
||||
"workflow-quality",
|
||||
"framework-language",
|
||||
"database",
|
||||
"orchestration"
|
||||
],
|
||||
"skippedModules": []
|
||||
},
|
||||
"source": {
|
||||
"repoVersion": "1.9.0",
|
||||
"repoCommit": "git-sha",
|
||||
"manifestVersion": 1
|
||||
},
|
||||
"operations": [
|
||||
{
|
||||
"kind": "copy",
|
||||
"moduleId": "rules-core",
|
||||
"destination": "/Users/example/.claude/rules/common/coding-style.md",
|
||||
"digest": "sha256:..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
State requirements:
|
||||
|
||||
- enough detail for uninstall to remove only ECC-managed outputs
|
||||
- enough detail for repair to compare desired versus actual installed files
|
||||
- enough detail for doctor to explain drift instead of guessing
|
||||
|
||||
## Lifecycle Commands
|
||||
|
||||
The following commands are the lifecycle surface for install-state:
|
||||
|
||||
1. `ecc list-installed`
|
||||
2. `ecc uninstall`
|
||||
3. `ecc doctor`
|
||||
4. `ecc repair`
|
||||
|
||||
Current implementation status:
|
||||
|
||||
- `ecc list-installed` routes to `node scripts/list-installed.js`
|
||||
- `ecc uninstall` routes to `node scripts/uninstall.js`
|
||||
- `ecc doctor` routes to `node scripts/doctor.js`
|
||||
- `ecc repair` routes to `node scripts/repair.js`
|
||||
- legacy script entrypoints remain available during migration
|
||||
|
||||
### `list-installed`
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- show target id and root
|
||||
- show requested profile/modules
|
||||
- show resolved modules
|
||||
- show source version and install time
|
||||
|
||||
### `uninstall`
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- load install-state
|
||||
- remove only ECC-managed destinations recorded in state
|
||||
- leave user-authored unrelated files untouched
|
||||
- delete install-state only after successful cleanup
|
||||
|
||||
### `doctor`
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- detect missing managed files
|
||||
- detect unexpected config drift
|
||||
- detect target roots that no longer exist
|
||||
- detect manifest/version mismatch
|
||||
|
||||
### `repair`
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- rebuild the desired operation plan from install-state
|
||||
- re-copy missing or drifted managed files
|
||||
- refuse repair if requested modules no longer exist in the current manifest
|
||||
unless a compatibility map exists
|
||||
|
||||
## Legacy Compatibility Layer
|
||||
|
||||
Current `install.sh` accepts:
|
||||
|
||||
- `--target <claude|cursor|antigravity>`
|
||||
- a list of language names
|
||||
|
||||
That behavior cannot disappear in one cut because users already depend on it.
|
||||
|
||||
ECC 2.0 should translate legacy language arguments into a compatibility request.
|
||||
|
||||
Suggested approach:
|
||||
|
||||
1. keep existing CLI shape for legacy mode
|
||||
2. map language names to module requests such as:
|
||||
- `rules-core`
|
||||
- target-compatible rule subsets
|
||||
3. write install-state even for legacy installs
|
||||
4. label the request as `legacyMode: true`
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"request": {
|
||||
"legacyMode": true,
|
||||
"legacyLanguages": ["typescript", "python"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This keeps old behavior available while moving all installs onto the same state
|
||||
contract.
|
||||
|
||||
## Publish Boundary
|
||||
|
||||
The current npm package still publishes a broad payload through `package.json`.
|
||||
|
||||
ECC 2.0 should improve this carefully.
|
||||
|
||||
Recommended sequence:
|
||||
|
||||
1. keep one canonical npm package first
|
||||
2. use manifests to drive install-time selection before changing publish shape
|
||||
3. only later consider reducing packaged surface where safe
|
||||
|
||||
Why:
|
||||
|
||||
- selective install can ship before aggressive package surgery
|
||||
- uninstall and repair depend on install-state more than publish changes
|
||||
- Codex/OpenCode support is easier if the package source remains unified
|
||||
|
||||
Possible later directions:
|
||||
|
||||
- generated slim bundles per profile
|
||||
- generated target-specific tarballs
|
||||
- optional remote fetch of heavy modules
|
||||
|
||||
Those are Phase 3 or later, not prerequisites for profile-aware installs.
|
||||
|
||||
## File Layout Recommendation
|
||||
|
||||
Suggested next files:
|
||||
|
||||
```text
|
||||
scripts/lib/install-targets/
|
||||
claude-home.js
|
||||
cursor-project.js
|
||||
antigravity-project.js
|
||||
registry.js
|
||||
scripts/lib/install-state.js
|
||||
scripts/ecc.js
|
||||
scripts/install-apply.js
|
||||
scripts/list-installed.js
|
||||
scripts/uninstall.js
|
||||
scripts/doctor.js
|
||||
scripts/repair.js
|
||||
tests/lib/install-targets.test.js
|
||||
tests/lib/install-state.test.js
|
||||
tests/lib/install-lifecycle.test.js
|
||||
```
|
||||
|
||||
`install.sh` can remain the user-facing entry point during migration, but it
|
||||
should become a thin shell around a Node-based planner and executor rather than
|
||||
keep growing per-target shell branches.
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
### Phase 1: Planner To Contract
|
||||
|
||||
1. keep current manifest schema and resolver
|
||||
2. add operation planning on top of resolved modules
|
||||
3. define `ecc.install.v1` state schema
|
||||
4. write install-state on successful install
|
||||
|
||||
### Phase 2: Target Adapters
|
||||
|
||||
1. extract Claude install behavior into `claude-home` adapter
|
||||
2. extract Cursor install behavior into `cursor-project` adapter
|
||||
3. extract Antigravity install behavior into `antigravity-project` adapter
|
||||
4. reduce `install.sh` to argument parsing plus adapter invocation
|
||||
|
||||
### Phase 3: Lifecycle
|
||||
|
||||
1. add stronger target-specific merge/remove semantics
|
||||
2. extend repair/uninstall coverage for non-copy operations
|
||||
3. reduce package shipping surface to the module graph instead of broad folders
|
||||
4. decide when `ecc-install` should become a thin alias for `ecc install`
|
||||
|
||||
### Phase 4: Publish And Future Targets
|
||||
|
||||
1. evaluate safe reduction of `package.json` publish surface
|
||||
2. add `codex-home`
|
||||
3. add `opencode-home`
|
||||
4. consider generated profile bundles if packaging pressure remains high
|
||||
|
||||
## Immediate Repo-Local Next Steps
|
||||
|
||||
The highest-signal next implementation moves in this repo are:
|
||||
|
||||
1. add target-specific merge/remove semantics for config-like modules
|
||||
2. extend repair and uninstall beyond simple copy-file operations
|
||||
3. reduce package shipping surface to the module graph instead of broad folders
|
||||
4. decide whether `ecc-install` remains separate or becomes `ecc install`
|
||||
5. add tests that lock down:
|
||||
- target-specific merge/remove behavior
|
||||
- repair and uninstall safety for non-copy operations
|
||||
- unified `ecc` CLI routing and compatibility guarantees
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Should rules stay language-addressable in legacy mode forever, or only during
|
||||
the migration window?
|
||||
2. Should `platform-configs` always install with `core`, or be split into
|
||||
smaller target-specific modules?
|
||||
3. Do we want config merge semantics recorded at the operation level or only in
|
||||
adapter logic?
|
||||
4. Should heavy skill families eventually move to fetch-on-demand rather than
|
||||
package-time inclusion?
|
||||
5. Should Codex and OpenCode target adapters ship only after the Claude/Cursor
|
||||
lifecycle commands are stable?
|
||||
|
||||
## Recommendation
|
||||
|
||||
Treat the current manifest resolver as adapter `0` for installs:
|
||||
|
||||
1. preserve the current install surface
|
||||
2. move real copy behavior behind target adapters
|
||||
3. write install-state for every successful install
|
||||
4. make uninstall, doctor, and repair depend only on install-state
|
||||
5. only then shrink packaging or add more targets
|
||||
|
||||
That is the shortest path from ECC 1.x installer sprawl to an ECC 2.0
|
||||
install/control contract that is deterministic, supportable, and extensible.
|
||||
489
docs/SELECTIVE-INSTALL-DESIGN.md
Normal file
489
docs/SELECTIVE-INSTALL-DESIGN.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# ECC Selective Install Design
|
||||
|
||||
## Purpose
|
||||
|
||||
This document defines the user-facing selective-install design for ECC.
|
||||
|
||||
It complements
|
||||
`docs/SELECTIVE-INSTALL-ARCHITECTURE.md`, which focuses on internal runtime
|
||||
architecture and code boundaries.
|
||||
|
||||
This document answers the product and operator questions first:
|
||||
|
||||
- how users choose ECC components
|
||||
- what the CLI should feel like
|
||||
- what config file should exist
|
||||
- how installation should behave across harness targets
|
||||
- how the design maps onto the current ECC codebase without requiring a rewrite
|
||||
|
||||
## Problem
|
||||
|
||||
Today ECC still feels like a large payload installer even though the repo now
|
||||
has first-pass manifest and lifecycle support.
|
||||
|
||||
Users need a simpler mental model:
|
||||
|
||||
- install the baseline
|
||||
- add the language packs they actually use
|
||||
- add the framework configs they actually want
|
||||
- add optional capability packs like security, research, or orchestration
|
||||
|
||||
The selective-install system should make ECC feel composable instead of
|
||||
all-or-nothing.
|
||||
|
||||
In the current substrate, user-facing components are still an alias layer over
|
||||
coarser internal install modules. That means include/exclude is already useful
|
||||
at the module-selection level, but some file-level boundaries remain imperfect
|
||||
until the underlying module graph is split more finely.
|
||||
|
||||
## Goals
|
||||
|
||||
1. Let users install a small default ECC footprint quickly.
|
||||
2. Let users compose installs from reusable component families:
|
||||
- core rules
|
||||
- language packs
|
||||
- framework packs
|
||||
- capability packs
|
||||
- target/platform configs
|
||||
3. Keep one consistent UX across Claude, Cursor, Antigravity, Codex, and
|
||||
OpenCode.
|
||||
4. Keep installs inspectable, repairable, and uninstallable.
|
||||
5. Preserve backward compatibility with the current `ecc-install typescript`
|
||||
style during rollout.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- packaging ECC into multiple npm packages in the first phase
|
||||
- building a remote marketplace
|
||||
- full control-plane UI in the same phase
|
||||
- solving every skill-classification problem before selective install ships
|
||||
|
||||
## User Experience Principles
|
||||
|
||||
### 1. Start Small
|
||||
|
||||
A user should be able to get a useful ECC install with one command:
|
||||
|
||||
```bash
|
||||
ecc install --target claude --profile core
|
||||
```
|
||||
|
||||
The default experience should not assume the user wants every skill family and
|
||||
every framework.
|
||||
|
||||
### 2. Build Up By Intent
|
||||
|
||||
The user should think in terms of:
|
||||
|
||||
- "I want the developer baseline"
|
||||
- "I need TypeScript and Python"
|
||||
- "I want Next.js and Django"
|
||||
- "I want the security pack"
|
||||
|
||||
The user should not have to know raw internal repo paths.
|
||||
|
||||
### 3. Preview Before Mutation
|
||||
|
||||
Every install path should support dry-run planning:
|
||||
|
||||
```bash
|
||||
ecc install --target cursor --profile developer --with lang:typescript --with framework:nextjs --dry-run
|
||||
```
|
||||
|
||||
The plan should clearly show:
|
||||
|
||||
- selected components
|
||||
- skipped components
|
||||
- target root
|
||||
- managed paths
|
||||
- expected install-state location
|
||||
|
||||
### 4. Local Configuration Should Be First-Class
|
||||
|
||||
Teams should be able to commit a project-level install config and use:
|
||||
|
||||
```bash
|
||||
ecc install --config ecc-install.json
|
||||
```
|
||||
|
||||
That allows deterministic installs across contributors and CI.
|
||||
|
||||
## Component Model
|
||||
|
||||
The current manifest already uses install modules and profiles. The user-facing
|
||||
design should keep that internal structure, but present it as four main
|
||||
component families.
|
||||
|
||||
Near-term implementation note: some user-facing component IDs still resolve to
|
||||
shared internal modules, especially in the language/framework layer. The
|
||||
catalog improves UX immediately while preserving a clean path toward finer
|
||||
module granularity in later phases.
|
||||
|
||||
### 1. Baseline
|
||||
|
||||
These are the default ECC building blocks:
|
||||
|
||||
- core rules
|
||||
- baseline agents
|
||||
- core commands
|
||||
- runtime hooks
|
||||
- platform configs
|
||||
- workflow quality primitives
|
||||
|
||||
Examples of current internal modules:
|
||||
|
||||
- `rules-core`
|
||||
- `agents-core`
|
||||
- `commands-core`
|
||||
- `hooks-runtime`
|
||||
- `platform-configs`
|
||||
- `workflow-quality`
|
||||
|
||||
### 2. Language Packs
|
||||
|
||||
Language packs group rules, guidance, and workflows for a language ecosystem.
|
||||
|
||||
Examples:
|
||||
|
||||
- `lang:typescript`
|
||||
- `lang:python`
|
||||
- `lang:go`
|
||||
- `lang:java`
|
||||
- `lang:rust`
|
||||
|
||||
Each language pack should resolve to one or more internal modules plus
|
||||
target-specific assets.
|
||||
|
||||
### 3. Framework Packs
|
||||
|
||||
Framework packs sit above language packs and pull in framework-specific rules,
|
||||
skills, and optional setup.
|
||||
|
||||
Examples:
|
||||
|
||||
- `framework:react`
|
||||
- `framework:nextjs`
|
||||
- `framework:django`
|
||||
- `framework:springboot`
|
||||
- `framework:laravel`
|
||||
|
||||
Framework packs should depend on the correct language pack or baseline
|
||||
primitives where appropriate.
|
||||
|
||||
### 4. Capability Packs
|
||||
|
||||
Capability packs are cross-cutting ECC feature bundles.
|
||||
|
||||
Examples:
|
||||
|
||||
- `capability:security`
|
||||
- `capability:research`
|
||||
- `capability:orchestration`
|
||||
- `capability:media`
|
||||
- `capability:content`
|
||||
|
||||
These should map onto the current module families already being introduced in
|
||||
the manifests.
|
||||
|
||||
## Profiles
|
||||
|
||||
Profiles remain the fastest on-ramp.
|
||||
|
||||
Recommended user-facing profiles:
|
||||
|
||||
- `core`
|
||||
minimal baseline, safe default for most users trying ECC
|
||||
- `developer`
|
||||
best default for active software engineering work
|
||||
- `security`
|
||||
baseline plus security-heavy guidance
|
||||
- `research`
|
||||
baseline plus research/content/investigation tools
|
||||
- `full`
|
||||
everything classified and currently supported
|
||||
|
||||
Profiles should be composable with additional `--with` and `--without` flags.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
ecc install --target claude --profile developer --with lang:typescript --with framework:nextjs --without capability:orchestration
|
||||
```
|
||||
|
||||
## Proposed CLI Design
|
||||
|
||||
### Primary Commands
|
||||
|
||||
```bash
|
||||
ecc install
|
||||
ecc plan
|
||||
ecc list-installed
|
||||
ecc doctor
|
||||
ecc repair
|
||||
ecc uninstall
|
||||
ecc catalog
|
||||
```
|
||||
|
||||
### Install CLI
|
||||
|
||||
Recommended shape:
|
||||
|
||||
```bash
|
||||
ecc install [--target <target>] [--profile <name>] [--with <component>]... [--without <component>]... [--config <path>] [--dry-run] [--json]
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
ecc install --target claude --profile core
|
||||
ecc install --target cursor --profile developer --with lang:typescript --with framework:nextjs
|
||||
ecc install --target antigravity --with capability:security --with lang:python
|
||||
ecc install --config ecc-install.json
|
||||
```
|
||||
|
||||
### Plan CLI
|
||||
|
||||
Recommended shape:
|
||||
|
||||
```bash
|
||||
ecc plan [same selection flags as install]
|
||||
```
|
||||
|
||||
Purpose:
|
||||
|
||||
- produce a preview without mutation
|
||||
- act as the canonical debugging surface for selective install
|
||||
|
||||
### Catalog CLI
|
||||
|
||||
Recommended shape:
|
||||
|
||||
```bash
|
||||
ecc catalog profiles
|
||||
ecc catalog components
|
||||
ecc catalog components --family language
|
||||
ecc catalog show framework:nextjs
|
||||
```
|
||||
|
||||
Purpose:
|
||||
|
||||
- let users discover valid component names without reading docs
|
||||
- keep config authoring approachable
|
||||
|
||||
### Compatibility CLI
|
||||
|
||||
These legacy flows should still work during migration:
|
||||
|
||||
```bash
|
||||
ecc-install typescript
|
||||
ecc-install --target cursor typescript
|
||||
ecc typescript
|
||||
```
|
||||
|
||||
Internally these should normalize into the new request model and write
|
||||
install-state the same way as modern installs.
|
||||
|
||||
## Proposed Config File
|
||||
|
||||
### Filename
|
||||
|
||||
Recommended default:
|
||||
|
||||
- `ecc-install.json`
|
||||
|
||||
Optional future support:
|
||||
|
||||
- `.ecc/install.json`
|
||||
|
||||
### Config Shape
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "./schemas/ecc-install-config.schema.json",
|
||||
"version": 1,
|
||||
"target": "cursor",
|
||||
"profile": "developer",
|
||||
"include": [
|
||||
"lang:typescript",
|
||||
"lang:python",
|
||||
"framework:nextjs",
|
||||
"capability:security"
|
||||
],
|
||||
"exclude": [
|
||||
"capability:media"
|
||||
],
|
||||
"options": {
|
||||
"hooksProfile": "standard",
|
||||
"mcpCatalog": "baseline",
|
||||
"includeExamples": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Field Semantics
|
||||
|
||||
- `target`
|
||||
selected harness target such as `claude`, `cursor`, or `antigravity`
|
||||
- `profile`
|
||||
baseline profile to start from
|
||||
- `include`
|
||||
additional components to add
|
||||
- `exclude`
|
||||
components to subtract from the profile result
|
||||
- `options`
|
||||
target/runtime tuning flags that do not change component identity
|
||||
|
||||
### Precedence Rules
|
||||
|
||||
1. CLI arguments override config file values.
|
||||
2. config file overrides profile defaults.
|
||||
3. profile defaults override internal module defaults.
|
||||
|
||||
This keeps the behavior predictable and easy to explain.
|
||||
|
||||
## Modular Installation Flow
|
||||
|
||||
The user-facing flow should be:
|
||||
|
||||
1. load config file if provided or auto-detected
|
||||
2. merge CLI intent on top of config intent
|
||||
3. normalize the request into a canonical selection
|
||||
4. expand profile into baseline components
|
||||
5. add `include` components
|
||||
6. subtract `exclude` components
|
||||
7. resolve dependencies and target compatibility
|
||||
8. render a plan
|
||||
9. apply operations if not in dry-run mode
|
||||
10. write install-state
|
||||
|
||||
The important UX property is that the exact same flow powers:
|
||||
|
||||
- `install`
|
||||
- `plan`
|
||||
- `repair`
|
||||
- `uninstall`
|
||||
|
||||
The commands differ in action, not in how ECC understands the selected install.
|
||||
|
||||
## Target Behavior
|
||||
|
||||
Selective install should preserve the same conceptual component graph across all
|
||||
targets, while letting target adapters decide how content lands.
|
||||
|
||||
### Claude
|
||||
|
||||
Best fit for:
|
||||
|
||||
- home-scoped ECC baseline
|
||||
- commands, agents, rules, hooks, platform config, orchestration
|
||||
|
||||
### Cursor
|
||||
|
||||
Best fit for:
|
||||
|
||||
- project-scoped installs
|
||||
- rules plus project-local automation and config
|
||||
|
||||
### Antigravity
|
||||
|
||||
Best fit for:
|
||||
|
||||
- project-scoped agent/rule/workflow installs
|
||||
|
||||
### Codex / OpenCode
|
||||
|
||||
Should remain additive targets rather than special forks of the installer.
|
||||
|
||||
The selective-install design should make these just new adapters plus new
|
||||
target-specific mapping rules, not new installer architectures.
|
||||
|
||||
## Technical Feasibility
|
||||
|
||||
This design is feasible because the repo already has:
|
||||
|
||||
- install module and profile manifests
|
||||
- target adapters with install-state paths
|
||||
- plan inspection
|
||||
- install-state recording
|
||||
- lifecycle commands
|
||||
- a unified `ecc` CLI surface
|
||||
|
||||
The missing work is not conceptual invention. The missing work is productizing
|
||||
the current substrate into a cleaner user-facing component model.
|
||||
|
||||
### Feasible In Phase 1
|
||||
|
||||
- profile + include/exclude selection
|
||||
- `ecc-install.json` config file parsing
|
||||
- catalog/discovery command
|
||||
- alias mapping from user-facing component IDs to internal module sets
|
||||
- dry-run and JSON planning
|
||||
|
||||
### Feasible In Phase 2
|
||||
|
||||
- richer target adapter semantics
|
||||
- merge-aware operations for config-like assets
|
||||
- stronger repair/uninstall behavior for non-copy operations
|
||||
|
||||
### Later
|
||||
|
||||
- reduced publish surface
|
||||
- generated slim bundles
|
||||
- remote component fetch
|
||||
|
||||
## Mapping To Current ECC Manifests
|
||||
|
||||
The current manifests do not yet expose a true user-facing `lang:*` /
|
||||
`framework:*` / `capability:*` taxonomy. That should be introduced as a
|
||||
presentation layer on top of the existing modules, not as a second installer
|
||||
engine.
|
||||
|
||||
Recommended approach:
|
||||
|
||||
- keep `install-modules.json` as the internal resolution catalog
|
||||
- add a user-facing component catalog that maps friendly component IDs to one or
|
||||
more internal modules
|
||||
- let profiles reference either internal modules or user-facing component IDs
|
||||
during the migration window
|
||||
|
||||
That avoids breaking the current selective-install substrate while improving UX.
|
||||
|
||||
## Suggested Rollout
|
||||
|
||||
### Phase 1: Design And Discovery
|
||||
|
||||
- finalize the user-facing component taxonomy
|
||||
- add the config schema
|
||||
- add CLI design and precedence rules
|
||||
|
||||
### Phase 2: User-Facing Resolution Layer
|
||||
|
||||
- implement component aliases
|
||||
- implement config-file parsing
|
||||
- implement `include` / `exclude`
|
||||
- implement `catalog`
|
||||
|
||||
### Phase 3: Stronger Target Semantics
|
||||
|
||||
- move more logic into target-owned planning
|
||||
- support merge/generate operations cleanly
|
||||
- improve repair/uninstall fidelity
|
||||
|
||||
### Phase 4: Packaging Optimization
|
||||
|
||||
- narrow published surface
|
||||
- evaluate generated bundles
|
||||
|
||||
## Recommendation
|
||||
|
||||
The next implementation move should not be "rewrite the installer."
|
||||
|
||||
It should be:
|
||||
|
||||
1. keep the current manifest/runtime substrate
|
||||
2. add a user-facing component catalog and config file
|
||||
3. add `include` / `exclude` selection and catalog discovery
|
||||
4. let the existing planner and lifecycle stack consume that model
|
||||
|
||||
That is the shortest path from the current ECC codebase to a real selective
|
||||
install experience that feels like ECC 2.0 instead of a large legacy installer.
|
||||
Reference in New Issue
Block a user