ego-lite-simplify

Simplify ego-lite

Reduce concepts and maintenance surface, not just line count. Prefer a few well-proven deletions over a long list of guesses.

Establish the contract

1. Read AGENTS.md and the design document that owns the affected behavior.
2. Inspect git status and preserve unrelated user changes.
3. Decide whether the request is an audit or an authorized implementation. Do not turn a cleanup into a product decision without making the behavior change explicit.
4. Identify the relevant boundary before judging code:
   • globalThis.ego is supplied by the closed-source app; docs/native-bindings-api.md documents that external contract.
   • The runtime has direct CLI and embedded SDK startup paths.
   • Public agent APIs must stay aligned across implementation, tests, help(), and skills/ego-browser/SKILL.md.
   • Browser state can outlive the short Node.js process.

Find strong candidates

Start with production areas carrying the most state, branching, or public surface. Look for:

• Exports, helpers, events, options, fallbacks, packages, or state fields with no production consumer.
• Tests or documentation that are the only consumers of behavior that is no longer required.
• Multiple representations of the same page, task-space, session, ref, lifecycle, or output state.
• Pass-through layers that add vocabulary but no policy, isolation, or test seam.
• Compatibility code that is unnecessary on an explicitly breaking branch.
• Generality with no current product use, such as unsupported concurrency modes or unused extension points.
• Special cases, rollback paths, or validation that exist only to protect a removable surface.
• Hand-written parsers, queues, retry logic, or utilities that a Node.js built-in or healthy dependency can replace with less total code.

Do not count moving logic into a wrapper as simplification. Estimate the net result: implementation, tests, docs, public names, state transitions, and special cases removed minus new glue and dependencies added.

Prove each candidate

Use rg first. Search exact symbols, method forms, event names, configuration keys, error codes, protocol strings, and dynamic registration points. Read the callers rather than relying only on static-analysis output.

Classify evidence as:

• Production: package/ego-browser/src, runtime scripts, build and loader paths, and shipped site learnings.
• Contract: public JSDoc consumed by help(), skills/ego-browser/SKILL.md, architecture documents, and native binding behavior.
• Non-production: tests, fixtures, snapshots, comments, and historical or draft documents.
• Ambiguous: examples and development scripts; inspect how they are invoked before deciding.

Reject or downgrade a candidate when a real production caller exists, the native contract is uncertain, the change merely relocates complexity, or the deletion requires unrelated churn. A small local cleanup may be implemented directly; a behavior or API decision belongs in the owning design document first.

Report before broad removal

For an audit, present each worthwhile candidate with:

• The surface to remove or fold.
• Call-site and contract evidence.
• The user-visible behavior change, or “none”.
• What complexity disappears and what replacement remains.
• Confidence, risks, and the smallest verification needed.

Call out candidates that require a user decision separately from behavior-preserving cleanups.

Implement safely

Follow spec-driven TDD when changing code:

1. Update or add a characterization test when existing behavior must remain.
2. Update the owning design or API contract before an intentional behavior change.
3. Remove the implementation and its now-obsolete tests, fixtures, exports, JSDoc, help entries, and skill documentation together.
4. Keep comments in English and explain only non-obvious constraints.
5. Prefer deleting a state or transition over adding another abstraction around it.

Run the narrowest relevant checks first. From package/ego-browser/, use npm test for runtime changes, npm run e2e for real task-space/browser behavior, and npm run validate:site-skills for learning changes. Finish with git diff --check and report any verification that could not run.

Never edit generated build output as the source of a simplification. Never remove a defensive path until its trust or lifecycle boundary is understood.