reliquary/docs/workpad/brainstorm/2026-10-16-22-grotto-plan-structure.md

Grotto: plans need code structure — user's thoughts after the headless-forks build

Date: 2026-10-16 22:41 Source: the user, written out after reading the headless-forks prototype (4,155 lines in one file). Recorded by Igor, session 2026-10-15-21-grotto-work. These are the user's thoughts, kept close to their words; they are not yet decisions.

The thoughts

• The gremlin would have helped here. A trained implementer that knows the code, forked per block, is exactly what this build lacked: every block was a cold-start agent re-reading 5–6k lines of plans, digests, run log and code.
• Grotto should go back to putting some code in the plan. Not super sophisticated, but at least the structure of the code: modules, the data model, the main interfaces. Plans without code (Spire 0.2.x) left the architecture to whoever built each block, and per-phase contract digests then invented it piecemeal.
• How to approach a problem:
  1. Make the happy path work first.
  2. Then build proper abstractions around the problem.
  3. Iterate over it.
  4. Trust that an Opus agent can easily throw out lots of code. Deleting is cheap; don't protect what was written.
• Open question: how much code can an Opus agent write in one go? (The user wants to know. Worth measuring, e.g. by having one agent write the minimal gremlins version from a structure-fixing spec.)
• Abstraction is also about sidestepping. More side effects and special cases need space to grow into, and a good abstraction gives them that space instead of letting them spread through if-chains.
• "Could all this not be expressed simpler?" For example, resolve complex ifs into a simple, elegant match, or move a class up a layer because that decouples the whole structure. Simplification is design work, and no stage of the current cycle does it: reviews hunt bugs, fixes add, nothing removes.
• The user wonders whether this is partly their own fault, for being chaotic and having too many thoughts at once. (Igor's note: the build's failure modes — no structure in the plan, cold starts, review loops that only add — are process failures, not the user's.)

Answer: how much code can Opus 5.5 produce in one go?

(Igor, 2026-10-16, from the claude-api skill's model table)

• One response can hold up to 128K output tokens (Opus 5.5's cap; values that large need streaming). Thinking tokens count against the same cap.
• At a rough 10 tokens per line of Python, that is a ceiling of about 10–12k lines in one response. In practice it's less: the thinking share, Claude Code's own output limit (configurable, possibly lower than the API cap; not checked here), and quality, which drops over very long single outputs.
• All of gremlins.py (4,155 lines, ~45–50k tokens) would fit into a single response, or two.
• Across a session, "one go" is effectively unbounded: an agent writes file after file over many turns within its 1M context.
• So output volume was never the bottleneck. The day went to orientation, coordination and verification, not to typing.

Related

• Journal open threads: "Process lessons to accrete" (budgets, a design/size criterion in reviews, cutting unrequested additions, a plan that fixes structure, re-planning when a premise falls).
• goals/drop-superpowers-0.2.2.md: grotto carries the design → plan → handoff procedure.
• reports/2026-10-15-22-spire-vs-superpowers-plan-and-build-experiment.md: "code in the plan adds nothing" was measured on correctness and merge choice, not on design quality.
• Code verdict on the prototype: reports/2026-10-16-22-gremlins-code-verdict.md (pending).