repo gps for ai agents — spoolcast dev log 5

People talk about AI hallucinating facts. But my problem was weirder. The agent was hallucinating instructions. Not facts. Not names. Not dates. It was making up what it was supposed to do next. Imagine giving someone a recipe that says: choose chocolate or vanilla. And they come back asking if you want chocolate, vanilla, or lasagna. That is basically what was happening inside Spoolcast. A rule gave the agent two paths, and it invented a third one. At first, I thought the AI was ignoring me. Then I realized the more useful answer: it was lost. Quick context. This video was made with Spoolcast, my AI video pipeline. It can start from many kinds of source material: a chat, a transcript, a repo, notes, research, or a story idea. Agents help turn source material into the full video: story, script, visuals, narration, render, thumbnails, and shipping files. I still direct it with feedback and approvals. I am just not manually editing clips on a timeline. So while the process is more automated, the videos still feel personal, because they come from my judgment, my experiences, and my direction. Which makes this episode fitting, because the agents making Spoolcast started getting lost inside the repo. The frustrating part was that these were not random one-off mistakes. The mistakes had a pattern. A thumbnail prompt already existed on disk. The agent invented a new one for mobile instead of reusing it. One AI tool saw a setting that meant 'reuse this image,' then ignored it and only checked if a certain mobile file was there. Another agent said there was no reason for a legacy thumbnail script, without checking why it existed. The old script existed because the main renderer had already failed to draw that text correctly. So the pattern was not: AI bad, human good, please clap. The pattern was: when the project did not say which process owned the task, the agent filled in the blank. Spoolcast was built through trial and error. The rules were not designed perfectly upfront. They grew out of real production mistakes, which is a polite way of saying: I learned by stepping on rakes. At first, there was basically one main path: widescreen image chunks rendered with Remotion. Then mobile export came later as an extra branch after the widescreen video was approved. That branch needed its own checks: smart cropping, crop review, mobile thumbnails, and fixes only for scenes that failed. Very quickly, the side quest had side quests. Then news-anime-bot appeared, and it was not the same machine at all. It was mobile-first, made AI video clips per beat, used text-to-speech, and combined the final video with ffmpeg. Every time the AI made a mistake, I added a rule. That felt responsible. It also felt like progress, because the rule was always solving the thing that had just annoyed me. But each fix added another detail, another exception, another nearby path. I thought I was making the AI follow instructions better. I was actually creating rule debt. Some docs were active workflow. Some were historical rationale. Some were old specs. Some were show-specific. One old spec had to be marked archived, because it was history, not the current workflow. Eventually, the rules became the thing confusing the AI. And the more I looked at it, the more this felt bigger than AI. AI just made the failure obvious because it is so willing to keep walking. In a big shared codebase, someone can change one part and run the wrong command because the repo never tells them who owns that part. In a company, a ticket can bounce between teams because nobody knows who owns the workflow. In a checklist-heavy process, the checklist can exist and still fail if nobody knows which checklist applies. Same failure, different costume: the work starts before the route is known. The real bug was that Spoolcast did not have one pipeline with a few exceptions. It had multiple video formats pretending to be one pipeline. One process was trying to describe several kinds of videos. One format used a session file, a shot list, AI-generated images, and a Remotion widescreen render. Mobile export was a branch that should only start after the widescreen video is approved. The news show used a different route: a script file, AI video clips, text-to-speech, and ffmpeg stitching. The conflict became obvious when an agent saw both routes. One route said: use the standard Remotion session. The other said: use the show folder and stitch the clips with ffmpeg. The agent asked whether to migrate the news episode to Remotion, follow the show workflow, or do something else. Annoying? Yes. Useful? Also yes, unfortunately. That was the GPS moment: the agent was not malicious. It had no clear front door. The analogy that clicked for me was school. There is a school schedule. But every class has its own syllabus. Pipeline.md should be the school schedule. Each video format should be the class syllabus. This devlog series gets its own assignment notes. If those layers blur together, the agent does what a confused student does. It guesses what class it is in. So the fix was not another paragraph of reminders. The fix was routing. Pipeline.md became the school schedule: setup, inputs, story, assets, assembly, audit, variants, and publish. A schedule. Not a syllabus pretending to be a schedule. Each format manages its own files, scripts, rendering process, and checks. Engine docs became reference libraries: useful, but not execution guides. The devlog intro became a series rule, not a rule every public user has to inherit. Other people should be able to use the engine without inheriting my channel intro. That would be weird. Very branded. Very forced-intro energy. Most importantly, the first move became mechanical: run spoolcast-audit before producing work. Before assets. Before scripts. Before the agent gets emotionally attached to the wrong folder. At Stage 0, the agent now has three doors: use the existing Remotion video format, use the existing news format, or define a new format first. A new format has to name the basics first: who owns it, where it lives, what files it uses, and what the production pieces are. Then it names the rules for audio, visuals, assembly, review, publishing, and routing. If no existing tool fits, do not force the request into the nearest process. Define the route before production. Boring sentence. Expensive lesson. The proof is visible in the terminal. Run the auditor on a known news episode, and it routes to news-anime-bot. Run it on a devlog mobile target, and it picks the Remotion route. Then it blocks on the real mobile crop audit. Run it on a totally unknown format, and it does not guess. It says: no workflow owns this session yet. Define the format before making assets. Same for a big shared codebase: find who owns that part, run that workflow, and stop if no owner exists. Same for teams: identify the owner, follow the checklist, and stop if ownership is unclear. Same for checklist ambiguity: identify which checklist applies. If none applies, write the checklist before acting. The model is simple: task, owner, workflow, gate, next allowed step. In plain English: what is this, who owns it, what route applies, and what can happen next? That is why the outside examples are not side quests. They are the same bug wearing normal workplace clothes. AI agents are vulnerable because they keep going from context, even when the route is missing. And the dangerous part is that the wrong path can look productive. It has steps. It has confidence. It has files changing on disk. Gorgeous little disaster. But progress is not correctness. A lot of wasted AI work is just confident movement in the wrong workflow. That is what the mechanical gate changes. It is not there to make the agent smarter. It is there to make guessing harder. If the task is a news episode, it cannot use the wrong format. If it is a devlog, it cannot accidentally inherit the news workflow. And if something is new, the repo does not assume the closest process fits. That block feels slower in the moment. It is still cheaper than building ten assets for the wrong pipeline. For builders using AI coding tools, this is the part I would copy: write the router before the fifteenth reminder. Make ownership executable. Put it in scripts, checks, folder names, and commands that fail when the route is unclear. The docs still matter. They explain the route. But the gate decides whether the agent is allowed onto it. Routing creates a clear order for the docs: owner first, workflow second, references third. The cleanup separated the current steps, engine references, and historical context. The goal is not to remove all agent judgment. It is to remove the kind of uncertainty that happens when the project doesn't make a decision. Once the route is known, the agent can still help with the hard parts: story, tradeoffs, visuals, and implementation. That is the shift: stop asking the AI to infer the map. Make the repo hand it the map first. This does not mean prompts do not matter. Prompting helps. It does not mean prose docs are useless. Prose helps careful agents understand what matters. But automated checks protect you when the agent is moving fast, the docs are crowded, or the task sits between workflows. Sometimes hallucination is just the AI filling in routing information your system forgot to provide. First locate the task. Then follow the route. If no route exists, define one before moving. The real fix was making the repo answer the first question before the AI could work: where am I? The fix was not giving the AI more reminders. It was giving the repo GPS.