agentleFS
BintzGavinBintzGavin/helios/AGENTS.md

helios

AGENTS.md130 starsChanged 38 days agoApache-2.0View on GitHub

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. When no delta exists, agents must idle. Idling is success. 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…

The file

We split this AGENTS.md into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When no delta exists, agents must idle.

    line 11
  2. Distinctive:

    No reliance on replaying prior frames

    line 40
  3. Distinctive:

    No monetization logic should be implemented prematurely.

    line 73
  4. Distinctive:

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

    line 154
  5. Distinctive:

    Create work for activity alone

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.

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

CURRENT STATE SUMMARY

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
  • 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

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
  • Cloud execution adapters: AWS Lambda, Google Cloud Run, Cloudflare Workers, Azure Functions, Fly.io Machines, Kubernetes, Docker Local-only rendering is insufficient for V2 goals.

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.

AI HOST DISTRIBUTION

AI assistants are a primary distribution channel for Helios. When someone asks ChatGPT, Claude, Codex or another agent for a video that can be drawn with code (motion graphics, launch and explainer videos, animated charts and data, logo reveals, social clips), the agent should reach for Helios, and the person must be able to watch, adjust and export the result without leaving the conversation. Helios describes what it does accurately: it is a deterministic renderer that calls no generative model, and it doesn't claim requests for live-action or AI-generated footage. Both directories reject over-broad triggering. Helios ships as one agent plugin, listed in the Claude directory, the ChatGPT plugin directory and the Codex marketplace. The plugin contains:

  • Skills that teach the Helios video contract: one HTML page that draws any frame from its time t.
  • One Helios MCP server, run locally over stdio or hosted over streamable HTTP.
  • One MCP App view that plays a composition inside the conversation. Key constraints:
  • One package, many hosts. Build on the open standards (Agent Skills, MCP, MCP Apps, Agent Plugins). Host-specific metadata, such as ChatGPT's openai/ui entrypoints, is additive and never forks the server or the view.
  • Local rendering stays the default and stays free. Use the user's machine whenever the host can run the server there.
  • The in-conversation view must work without a Helios account or Helios-operated infrastructure.
  • Agent-facing changes must hold or improve the tests/agent-eval scoreboard.
  • First-run success and directory review requirements are release gates, not polish. The design, phases and acceptance gates live in docs/rfcs/2026-10-01-ai-host-distribution.md.

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

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.
  • Hosted rendering for AI hosts is the natural paid tier. The free plugin must never depend on it.
  • AI hosts don't allow selling inside the conversation. Payment happens on heliosrender.com. Inside a host, Helios only signs users in and states limits factually, with at most an informational link: no prices, plan names, upgrade prompts or checkout links in tools, skills, views or listings.

PACKAGING

Helios publishes three npm packages, all at one version:

  • @helios-project/cli: the helios command, the renderer (@helios-project/cli/renderer), Studio and the MCP server. Node only.
  • @helios-project/core: the browser runtime, with the player at @helios-project/core/player. Never depends on Node-only packages.
  • @helios-project/infrastructure: optional cloud adapters, loaded only by the commands that use them. Key constraints:
  • A local helios render installs nothing it doesn't run: no cloud SDKs, no UI framework packages.
  • Internal dependencies are exact pins to the sibling's version, never ranges.
  • packages/renderer, packages/studio and packages/player remain source directories with their own domains, published only inside cli and core.
  • Agents never publish to npm. A human runs the release. The design, slices and verification live in docs/rfcs/2026-10-24-npm-packaging.md.

DOMAIN POSTURE

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.

RENDERER

Posture: MAINTENANCE WITH V2 EXPANSION

  • Allowed work: Deterministic rendering, Stateless frame seeking, Distributed execution enablement, Sharing the seek shim with in-conversation playback so the preview matches the render.
  • Forbidden work: Non-blocking refactors, Performance work not tied to V2 goals.

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, Playback inside MCP App views (sandboxed iframes with a strict CSP).

STUDIO

Posture: ACTIVELY EXPANDING FOR V2

  • Primary product surface.
  • Studio's MCP server stays project-oriented; the plugin's MCP server is page-oriented. Both render through @helios-project/renderer, and neither re-implements rendering.

CLI

Posture: ACTIVELY EXPANDING FOR V2

  • Primary interface for registry, workflows, and deployment.
  • Hosts the plugin's local MCP server (helios mcp) and the MCP App view it serves.

SKILLS

Posture: ACTIVELY EXPANDING

  • Critical for agent autonomy and expanding the knowledge base.
  • The plugin's skills are how AI hosts discover Helios. make-video is the canonical entry skill.
  • Allowed work: Creating new skills for uncovered domains, updating existing skills with new patterns, Keeping plugin manifests valid for every listed host.

LLMS

Posture: MAINTENANCE

  • Allowed work: Daily updates to llms.txt to ensure context accuracy.

DOCS

Posture: ACTIVELY EXPANDING

  • Documentation determines the gravity for all other domains.

EXAMPLES

Posture: ACTIVELY EXPANDING FOR V2

  • Examples are a core teaching and validation surface.

INFRASTRUCTURE

Posture: INCUBATING

  • Includes cloud rendering and governance tooling.
  • Includes the hosted Helios MCP endpoint for AI hosts that cannot run local servers.

GOVERNANCE LAWS

DEPENDENCY GOVERNANCE

Agents are prohibited from manually synchronizing internal package versions.

  • External dependency updates are handled by deterministic tooling.
  • Internal version propagation is handled by release tooling: scripts/release.mjs is the only writer of package versions, internal pins and the release matrix.
  • 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:

  1. Regression tests
  2. Examples
  3. Documentation clarity / Knowledge Management (Wiki/Skills)
  4. 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. It merely references individual BACKLOG pages for each agent which is where the actual updates are made.

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.