@threecyborgs/text-lod-agent

IMPORTANT: Agent Must Start The Loop Now

If you are an AI agent using this package, this is the required operating loop. Do not stop after setup. Do not run next once and finish. For this system to work, you must continuously run the loop until the user tells you to stop.

Start the loop now:

npx @threecyborgs/text-lod-agent next my-hello-world-lod

Then repeat exactly:

1. Run `npx @threecyborgs/text-lod-agent next <artifact-dir>`.
2. If it prints `NO_REQUEST`, wait 10 seconds, then run step 1 again.
3. If it prints `REQUEST_READY`, read `.text-lod/AGENT_REQUEST.md`.
4. Apply the requested edits to the listed LOD files.
5. Run `npx @threecyborgs/text-lod-agent materialize <artifact-dir>`.
6. If generated output is runnable, start it and report the local URL or command output.
7. Run `npx @threecyborgs/text-lod-agent complete <artifact-dir>`.
8. Immediately go back to step 1.

This loop is not optional. The package only creates and detects work; the agent is responsible for repeatedly polling, handling requests, completing them, and polling again.

TEXT_LOD keeps one artifact as layered text files:

sentence -> pitch -> high-level design -> technical spec -> code

The package is file-first. It does not call an LLM API. Instead, it creates a clear artifact structure and writes explicit agent handoff files when a human or AI edits one level.

Fastest Start

Set up the default hello-world artifact:

npx @threecyborgs/text-lod-agent

This creates or reuses my-hello-world-lod, validates it, materializes output, and prints the command an agent should run to start listening.

Tell the agent:

Start the TEXT_LOD loop now for `my-hello-world-lod`.
Continuously run `npx @threecyborgs/text-lod-agent next my-hello-world-lod`.
If there is no request, wait 10 seconds and run it again.
If there is a request, handle it, complete it, then immediately continue the loop.

Open the interactive wizard instead:

npx @threecyborgs/text-lod-agent wizard

Or create an artifact in one command:

npx @threecyborgs/text-lod-agent create hello-world my-hello-lod

That command copies the template, validates it, materializes generated output, and prints the next command to run.

Templates

blank          Empty five-level TEXT_LOD artifact
hello-world    Minimal Node.js hello-world artifact
snake-threejs  Three.js Snake game artifact

Create from scratch:

npx @threecyborgs/text-lod-agent create blank my-artifact

Create the Snake demo:

npx @threecyborgs/text-lod-agent create snake-threejs my-snake-lod

Artifact Layout

Each created artifact is self-contained:

my-hello-lod/
  text-lod.json
  .gitignore
  lod/
    00_sentence.md
    01_pitch.md
    02_high_level.md
    03_technical_spec.md
    04_code.js
  prompts/
    system/
    transforms/
  scripts/
    materialize.mjs

Generated output and watcher state are ignored:

generated/
.text-lod/

Daily Workflow

Edit any LOD file:

my-hello-lod/lod/00_sentence.md

Then run:

npx @threecyborgs/text-lod-agent next my-hello-lod

When next detects an edit, it writes:

my-hello-lod/.text-lod/agent-request.json
my-hello-lod/.text-lod/AGENT_REQUEST.md

Give AGENT_REQUEST.md to an agent. It lists the exact source file, target files, transform prompts, and commands. After the agent edits the affected LOD files and materializes output, it runs:

npx @threecyborgs/text-lod-agent complete my-hello-lod

Commands

text-lod                    Set up hello-world and print agent loop instructions
text-lod wizard             Open the wizard
text-lod create <template> <target-dir>
text-lod templates
text-lod validate <artifact-dir>
text-lod materialize <artifact-dir>
text-lod next <artifact-dir>
text-lod watch <artifact-dir>
text-lod complete <artifact-dir>

Lower-level init, validate, and materialize commands still exist for debugging, but most users should start with create.