The sun is shining

My favorite thing about agents is that I can finally go back to just using Terminal + Sublime Text

Ok since I've accepted that I have to code in English now, is there like a "English framework" that makes this easier? Like if you have a big complex idea/spec in your head that you need to articulate so that an LLM can implement it, what does the workflow look like?

I struggled with this. So far the best thing I've come up is to start by writing an "index.md" that is like a high level summary/abstract containing a bunch of links pointing to other "<feature>.md" or "<concept>.md".

I just write free form exposition until the entire idea is rendered into English, and then I tell the LLM to read it and ask me clarifying questions about anything it does not understand. I don't shy away from "pitching" the idea in these design documents. I want the LLM to grasp the *why* just as well as the *what* because I think that helps it make better implementation decisions in certain cases.

Then, once I've got the whole thing from my brain into English and I feel like it makes sense *to me*, we iterate. I tell it to read the whole thing and ask me questions. I answer its questions and update the markdown files as necessary to include details that I may not have specified or that it thinks are ambiguous.

At some point just based on vibes this matrix of markdown files (the "English source") feels comprehensive-ish and I tell the LLM "ok crawl these interlinked design docs, read them all, and create a todo.md file". This todo.md is like a persistent roadmap or task list (also containing tasks marked as complete and descriptions of the task) that gets committed to git along with all the other markdown files.

Then we go into the implementation phase. At this point you can pretty much just say "ok do it" and walk away, have some coffee. I tell the LLM (in the index.md file) that whenever it does something it needs to update todo.md (Claude leaving messages for future amnesiac Claude). And also I have to create or update tests because why not.

One way I've been thinking about this is that /src is no longer the first step in the pipeline. There is now a /design folder containing English that gets (effectively) transpiled by the LLM into the source code. But it's not a pure transpilation. There is path-dependence because of the notes that the LLM leaves itself in the todo.md file about what it did and why. (sometimes I've head to clean these up manually when it goes off the rails to avoid contaminating subsequent context)

I've realized a couple things:

The *good part* of coding in English is that you get to maintain your high-level designer headspace the whole time without getting bogged down by implementation details. Honestly this is the best part.

The *bad part* of coding in English (and this is why I'm like the last dev in nostr to let Claude take the wheel) is that, at least for me, trying and failing to implement something has very often been *how I discovered* certain information about the problem domain.

Without trying to implement something myself I often don't feel confident enough that my designer guy persona is not full of shit (this I feel is parallel to the writing process - there's that line about how "writing is thinking", the point of writing being to reveal to *yourself* inconsistencies in your own thought. Anyway).

I feel like in last few months I've finally started to make this work for me. The learning forgone by not encountering low level reality is being counterbalanced by spending more time iterating in English.

Still, I have the feeling that I'm leaving something on the table. For example I have no idea how to really take advantage of sub-agent orchestration. I also have no clue what happens if/when my markdown files become too big to always have in context.

Maybe my whole concept of a markdown-based pipeline is retarded and I should just use <foo> (yes I know about Obsidian)

As an engineer, I don't think I've ever felt more *and* less capable as at the same time.

I am curious what you guys are doing. Anyone have a similar process?