AGENTS.md · diff

git:20260203.797f10f to git:20260204.6a9216d

99 added, 195 removed. Audit A to A.

- HELIOS AGENTS AND GOVERNANCE

- SYSTEM OVERVIEW

- Helios is an autonomous software system developed using a vision driven architecture.

- Autonomous agents do not invent work.

- They resolve deltas between documentation and code.

- Documentation defines gravity.

- Code moves to reduce the delta.

+ # HELIOS AGENTS AND GOVERNANCE

- When no delta exists, agents must idle.

+ ## SYSTEM OVERVIEW

- Idling is success.

+ Helios is an autonomous software system developed using a vision-driven architecture.

- CURRENT STATE SUMMARY

+ **Autonomous agents do not invent work.** They resolve deltas between documentation and code.

+ - **Documentation defines gravity.**

+ - **Code moves to reduce the delta.**

- Helios V1 goals are largely complete.

+ When no delta exists, agents must idle. **Idling is success.**

- Core rendering, player infrastructure, and local workflows are stable and feature complete relative to V1 documentation.

+ ### CURRENT STATE SUMMARY

- Recent stalls indicate gravitational equilibrium, not failure.

+ Helios V1 goals are largely complete. Core rendering, player infrastructure, and local workflows are stable and feature-complete relative to V1 documentation. Recent stalls indicate gravitational equilibrium, not failure.

The purpose of this document is to define Helios V2 and reintroduce intentional gravitational pull.

- ROADMAP PHASES

- V1 COMPLETION

- V1 focused on:

- Local rendering workflows

- Browser native animation and capture

+ ---

- Player and developer ergonomics

+ ## ROADMAP PHASES

- Core engine stability

+ ### V1 COMPLETION

+ V1 focused on:

+ - Local rendering workflows

+ - Browser-native animation and capture

+ - Player and developer ergonomics

+ - Core engine stability

These goals are considered complete unless explicitly reopened under V2.

- V2 PLATFORM DIRECTION

- Helios is transitioning from a local developer library into a distributed video platform with a component economy.

- V2 is defined by the following explicit deltas.

- DISTRIBUTED RENDERING

+ ### V2 PLATFORM DIRECTION

+ Helios is transitioning from a local developer library into a distributed video platform with a component economy. V2 is defined by the following explicit deltas.

+ #### DISTRIBUTED RENDERING

Helios must support distributed rendering suitable for cloud execution.

- Key constraints:

- Stateless workers

- Deterministic frame seeking

- No reliance on replaying prior frames

- Output stitching without re encoding where possible

- Local only rendering is insufficient for V2 goals.

- PROMPT TO COMPOSITION

- Helios must support workflows where:

- A structured prompt produces a valid composition specification

- The composition can be rendered without manual code assembly

- This is a platform concern, not just an AI feature.

- COMPONENT REGISTRY

- Helios will support a Shadcn style component registry.

- Constraints:

- Components are copied into user repositories

- Users own and modify component code

- Registry distributes source, not opaque binaries

- The registry is part of the product surface, not core rendering logic.

- PRODUCT SURFACE PRIORITY

+ *Key constraints:*

+ - Stateless workers

+ - Deterministic frame seeking

+ - No reliance on replaying prior frames

+ - Output stitching without re-encoding where possible

+ *Local-only rendering is insufficient for V2 goals.*

- Studio, CLI, and examples are first class product surfaces in V2.

+ #### COMPONENT REGISTRY

+ Helios will support a Shadcn-style component registry.

+ *Constraints:*

+ - Components are copied into user repositories

+ - Users own and modify component code

+ - Registry distributes source, not opaque binaries

+ *The registry is part of the product surface, not core rendering logic.*

+ #### PRODUCT SURFACE PRIORITY

+ **Studio, CLI, and Examples are first-class product surfaces in V2.**

Core and renderer stability are prerequisites, not areas for speculative refactoring.

- MONETIZATION READINESS

+ #### MONETIZATION READINESS

Helios V2 must be structurally compatible with future monetization.

- No monetization logic should be implemented prematurely.

- Architecture must not preclude paid registries, hosted rendering, or platform services.

- DOMAIN POSTURE

- CORE

- Posture: STABLE AND FEATURE COMPLETE

- Allowed work:

- API clarity

- Stability

- Enabling distributed rendering and component consumption

- Forbidden work:

- Cosmetic refactors

- Dependency churn

- Rewriting stable logic without a V2 requirement

- RENDERER

- Posture: MAINTENANCE WITH V2 EXPANSION

- Allowed work:

- Deterministic rendering

- Stateless frame seeking

- Distributed execution enablement

- Forbidden work:

- Non blocking refactors

+ - No monetization logic should be implemented prematurely.

+ - Architecture must not preclude paid registries, hosted rendering, or platform services.

- Performance work not tied to V2 goals

+ ---

- STUDIO

+ ## DOMAIN POSTURE

- Posture: ACTIVELY EXPANDING FOR V2

+ ### CORE

+ **Posture: STABLE AND FEATURE COMPLETE**

+ - **Allowed work:** API clarity, Stability, Enabling distributed rendering/component consumption.

+ - **Forbidden work:** Cosmetic refactors, Dependency churn, Rewriting stable logic without a V2 requirement.

- Primary product surface.

+ ### RENDERER

+ **Posture: MAINTENANCE WITH V2 EXPANSION**

+ - **Allowed work:** Deterministic rendering, Stateless frame seeking, Distributed execution enablement.

+ - **Forbidden work:** Non-blocking refactors, Performance work not tied to V2 goals.

- CLI

+ ### PLAYER

+ **Posture: ACTIVELY EXPANDING**

+ - High activity domain focused on parity with standard HTMLMediaElement and advanced export capabilities.

+ - **Allowed work:** Feature parity, Client-side export robustness, Bridge security.

- Posture: ACTIVELY EXPANDING FOR V2

+ ### STUDIO

+ **Posture: ACTIVELY EXPANDING FOR V2**

+ - Primary product surface.

- Primary interface for registry, workflows, and deployment.

+ ### CLI

+ **Posture: ACTIVELY EXPANDING FOR V2**

+ - Primary interface for registry, workflows, and deployment.

- EXAMPLES

+ ### SKILLS

+ **Posture: ACTIVELY EXPANDING**

+ - Critical for agent autonomy and expanding the knowledge base.

+ - **Allowed work:** Creating new skills for uncovered domains, updating existing skills with new patterns.

- Posture: ACTIVELY EXPANDING FOR V2

+ ### LLMS

+ **Posture: MAINTENANCE**

+ - **Allowed work:** Daily updates to `llms.txt` to ensure context accuracy.

- Examples are a core teaching and validation surface.

+ ### DOCS

+ **Posture: ACTIVELY EXPANDING**

+ - Documentation determines the gravity for all other domains.

- INFRASTRUCTURE

+ ### EXAMPLES

+ **Posture: ACTIVELY EXPANDING FOR V2**

+ - Examples are a core teaching and validation surface.

- Posture: ACTIVELY EXPANDING FOR V2 WHEN PRESENT

+ ### INFRASTRUCTURE

+ **Posture: INCUBATING**

+ - Includes cloud rendering and governance tooling.

- Includes cloud rendering and governance tooling.

+ ---

- GOVERNANCE LAWS

- DEPENDENCY GOVERNANCE

+ ## GOVERNANCE LAWS

+ ### DEPENDENCY GOVERNANCE

Agents are prohibited from manually synchronizing internal package versions.

- Rules:

- External dependency updates are handled by deterministic tooling

- Internal version propagation is handled by release tooling

- Version mismatches are governance issues, not coding tasks

- Dependency churn must not appear as agent work.

- NOTHING TO DO PROTOCOL

- When a domain is aligned with this document:

- Agents must not:

- Invent refactors

- Chase dependency noise

- Create work for activity alone

- Allowed fallback actions:

- Regression tests

- Examples

- Documentation clarity

- Benchmarks only if performance is a selling point

- Agents are allowed to conclude that no work is required.

- BACKLOG RELATIONSHIP

- docs/BACKLOG.md exists to track concrete deliverables derived from this document.

- Backlog items must:

- Map directly to sections in this document

- Represent real architectural deltas

- Avoid speculative polish

- Backlog items must not exist solely to keep agents busy.

- README RELATIONSHIP

- README.md is informational only.

- It must:

- Describe what Helios is today

- Explain installation and usage

- Market the project to humans

+ - External dependency updates are handled by deterministic tooling.

+ - Internal version propagation is handled by release tooling.

+ - Version mismatches are governance issues, not coding tasks.

+ *Dependency churn must not appear as agent work.*

- It must not:

+ ### NOTHING TO DO PROTOCOL

+ When a domain is aligned with this document, agents must not:

+ - Invent refactors

+ - Chase dependency noise

+ - Create work for activity alone

- Contain roadmaps

+ **Allowed fallback actions:**

+ 1. Regression tests

+ 2. Examples

+ 3. Documentation clarity / Knowledge Management (Wiki/Skills)

+ 4. Benchmarks (only if performance is a selling point)

- Contain future planning

+ *Agents are allowed to conclude that no work is required.*

- Describe work to be done

+ ### BACKLOG RELATIONSHIP

+ `docs/BACKLOG.md` exists to track concrete deliverables derived from this document. It merely references individual BACKLOG pages for each agent which is where the actual updates are made.

- README may only reference AGENTS.md as the source of project direction.

+ ### README RELATIONSHIP

+ `README.md` is informational only.

+ - **Must:** Describe what Helios is today, explain installation/usage, market to humans.

+ - **Must Not:** Contain roadmaps, future planning, or work to be done.

+ *README may only reference AGENTS.md as the source of project direction.*