I’m building an architecture-first CLI because AI agents were wasting my tokens fixing preventable mistakes
Hey Indie Hackers 👋
I’m a freelance developer, and over the last year AI coding agents have changed how I build.
Projects that previously needed a small team are now possible to build solo. That part is exciting.
But I kept running into the same problem: when I began with unclear requirements, scope, or technical decisions, the coding agent did what I asked—but then I spent many more iterations and tokens correcting assumptions, fixing errors, and changing decisions that should have been made before implementation.
The bottleneck was not code generation.
It was the lack of a clear project plan before asking the agent to build.
So I built Archseed: a CLI-first, architecture-first workflow for new software projects.
Instead of generating the application code, Archseed asks practical questions about the project, such as:
- What is the smallest useful scope?
- Who are the users and core flows?
- What are the key constraints and non-goals?
- Which technical decisions must be made before implementation?
- How should the project be tested and reviewed?
It then creates Markdown files that I can use myself or pass to a coding agent:
The idea is simple: improve the context before coding so the implementation agent makes fewer wrong assumptions.
The CLI is working, and I’m opening a small free beta for developers who are about to start a SaaS, MVP, web app, or client project using tools like Cursor, Claude Code, Codex, or Gemini.
I’m not looking for compliments. I want to learn:
- Which planning question is most important before you let an AI agent start coding?
- Would you use a CLI for this, or would a web workflow be less friction?
- What would make these generated files genuinely useful instead of “more documentation”?
- Is this most useful for greenfield projects, client work, or existing codebases?
If you would like to test it, leave a comment with the kind of project you’re building or send me a message.
Website: https://www.archseed.co/
Thanks — I’ll share everything I learn from the beta.
How do you handle decisions that change halfway through implementation? The initial plan seems useful, but I’d want a way to update it without regenerating everything or overwriting decisions already made in the code.
That is a great question, and I agree that a static plan would become a problem as soon as implementation reveals new constraints.
My current thinking is that Archseed should not regenerate or overwrite the whole plan when a decision changes.
Instead, it should support a small change workflow:
For example, if a project switches from one auth provider to another, Archseed should preserve the original decision and rationale, record why it changed, flag the affected tasks and integrations, and update the relevant plan sections rather than starting from scratch.
This is not fully built in the beta yet, but it is an important part of the workflow I want to validate. I want the plan to be a living source of context, not a document that becomes obsolete after the first week of implementation.
Would you expect this as a CLI command such as
archseed change, or would you prefer a review workflow before applying the update?Great framing â the bottleneck is context quality, not code generation.
One thing I'd add from auditing my own agent stack: planning context is only half of it. The other half is the tool manifest. I connected 7 MCP servers (Stripe, Supabase, Resend, PostHog, Linear, GitHub, Brave Search â 35 tools) to a support agent, and tokenized the outgoing payload with tiktoken: 4,785 tokens of raw JSON Schema were being re-sent on every single turn before any conversation happened. Pruning the schema boilerplate got it to 3,474, and repacking into a compact pipe notation got it to 3,160 (-34%), with all 35 tools still calling correctly.
So when Archseed generates architecture.md / implementation-plan.md, it might be worth also emitting a "tool-manifest budget" file: which servers the agent may connect, and the turn-zero token cost of each. A lean plan plus a bloated tool list can still burn a third of the context window.
To your question â the most valuable planning question for me has been "which technical decisions must be locked before implementation." Wrong framework choices were my single biggest token sink. (I eventually packaged my audit into a tiny open-source utility called mcptoon, but the measurement habit matters more than the tool.)
Good luck with the beta!
This is a great point. I was initially focused on planning quality, but a clean plan can still become expensive if the agent starts with an oversized tool surface.
I do not want Archseed to become an MCP schema optimizer, but I like the idea of generating a lightweight tool and integration policy: which services are required for v1, which ones should be deferred, and when each tool group should be enabled.
That fits the product’s goal of reducing unnecessary context and preventing the agent from making technical assumptions too early.
The question about locking technical decisions before implementation is especially useful. I’m adding that as a core part of the planning flow. Thanks for sharing the concrete numbers and the mcptoon example.
Make them commit first. Ask for the flip condition before you show the answer, not after.
I build quant strategies. The rule I keep is that the pass mark gets written down before I look at the backtest. An explanation read after the answer almost never changes a decision. It gets used to justify the one already made.
So: before the agents' output appears, ask the reader for one line, "what number would make me drop this?" Then show the answer. Now you can see whether that line moves. If it never moves, the extra detail is buying trust, not judgement.
The premise is solid. Coding agents do not waste tokens because of syntax errors. They burn tokens by making plausible architectural assumptions that conflict with the rest of the stack.
To answer your core questions from building production systems with agent workflows:
First, the most important planning question is defining explicit negative constraints. Agents rarely fail from lack of ambition. They fail because they pull in third party packages for simple logic, mutate shared state unpredictably, or rewrite working database models. Having a dedicated non goals and banned patterns section in the context brief prevents eighty percent of agent derailments.
Second, what prevents generated files from becoming dead documentation is machine validation. Natural language in markdown easily gets diluted across large context windows. If Archseed outputs executable boundaries alongside the text, such as zod schemas, database migration contracts, or automated test stubs, the agent receives instant compiler feedback when it violates the architectural plan.
Third, a CLI is definitely lower friction than a web app. Developers want this inside their terminal where git hooks and agent prompts live. Running a simple command that updates the architecture brief directly in the repository feels like part of the developer loop rather than a context switch to a browser.
Focusing on boundaries and machine readable contracts will make this indispensable.
This is extremely helpful — thank you.
I agree that positive requirements alone are not enough. AI agents often go off track because they fill gaps with reasonable-looking assumptions: adding unnecessary dependencies, changing a working data model, or expanding the scope beyond what was agreed.
I’m adding a first-class “Non-goals and Banned Patterns” section to the architecture brief, so the agent receives explicit boundaries such as:
I also agree that Markdown alone can become passive documentation. The longer-term direction I see is to let Archseed generate machine-readable contracts and validation stubs for the decisions that matter most — for example Zod schemas, acceptance-test stubs, API contracts, and architecture checks.
I do not want to generate every possible artifact automatically in the MVP. The beta should help me learn which boundaries developers actually want enforced first.
And yes, this is why I’m keeping it CLI-first: the architecture brief should live in the repository, evolve through Git, and be available in the same loop where agents and developers are working.
Which executable boundary would be most valuable for you on a new SaaS project: dependency restrictions, database/schema change checks, API contracts, or acceptance-test stubs?
The useful idea is to catch unclear decisions before they turn into code. I do a lightweight version with DictaFlow. I talk through the user flow out loud, then turn the recording into a short list of assumptions and edge cases before I open the IDE. That costs far less than finding out halfway through that the feature only made sense in my head. I'd make Archseed opinionated enough to force those decisions, rather than just create nicer project docs.
The one question: what result would make me throw this away? Written before the agent starts.
I build quant strategies with a coding agent. The expensive failure was never bad code. It was that I had not fixed the pass mark before I saw the numbers. When the bar comes after the result, everything passes.
So the file I want is not architecture.md. It is a one-page kill criteria file, written first. Scope and constraints can be recovered later. A pass mark cannot, once you have seen the answer.
That is a strong idea. I agree that success and failure criteria should be written before implementation, not invented after seeing the result.
I had been treating scope and architecture as the main planning outputs, but a lightweight validation criteria section may be just as important: what must be true for the project to continue, and what result would make the developer narrow scope, pivot, or stop.
For the MVP, I’m going to test adding that question before the agent generates the plan. I may call it “Validation Criteria” rather than “kill criteria,” but the principle is the same.
Thank you — this is exactly the kind of feedback I was hoping to get.
Enforcing architectural boundaries before AI agents generate code directly addresses the hidden financial drain of runaway token burn caused by iterative bug fixing. By shifting the agent's focus from guessing system design to executing within strict structural constraints, an architecture-first CLI transforms AI from an expensive, error-prone trial-and-error loop into a precise, cost-effective development engine.
The measurement problem you're trying to solve is actually upstream: what measurement of "saved iterations" can be trusted? You could count agent corrections before/after planning, but that measures process noise, not impact. The real signal is whether developers end up rewriting less code downstream - but that lagging signal only shows up weeks later across multiple projects. Archseed answers "does planning reduce chaos" but the measurement that proves tokens are saved sits days in the future. Early testers will feel faster, but that's confidence in the process. What metric would actually prove it on the first project, measured while the developer still remembers the unplanned baseline?
Yes, you’re right. Token savings alone are not enough to measure the real impact.
For this MVP, I want to use it as a simple early signal while I collect feedback from real projects and look for stronger metrics, such as major implementation changes, architectural rewrites, and time to a working first version.
The real validation seems downstream of the generated docs: do developers actually see fewer agent iterations, wasted tokens, or architectural rewrites after using Archseed?
That’s exactly what I want to measure. I need to understand whether planning a project upfront actually helps developers save a meaningful number of tokens.
I’m not trying to compete with AI IDEs like Gravity, Cursor, or OpenCode.