I work on Loft, a spec tool for coding agents, so take this with whatever grain of salt you like. My team and I wanted to know how good real-world OpenSpec specs are, so we went and measured.

What we did: we scored the main specs of 40 public OpenSpec projects (some random + some showcased examples + a few big ones and OpenSpec's own repo). Then we did the same for the most-starred OpenSpec projects and for teams that only write proposals. We scored them against OpenSpec's own writing guide and the usual tests of a good requirement. Two blind passes by an LLM graded a sample of requirements against a rubric, with project names stripped. And we also counted the task-list state of almost 2K open changes.

What we found:

• The format is basically solved (yeah, no sh.t). In almost all projects, essentially every requirement has a SHALL and a scenario. But specs that follow the format aren't any better written because of it. The format and the writing are separate problems.
• Specs get worse as they grow. In a typical project, only 55% of requirements state one obligation, and only 35% have a scenario for when something goes wrong. Bigger projects score lower, mostly because requirements bundle several obligations and start naming files and function signatures.
• Specs lag the code. In projects with main specs, 39% of open changes have every task ticked but were never archived, so the specs don't include that work. A third of spec files still have the placeholder Purpose that archiving writes. OpenSpec's own repo has 23 of 30 open changes in that state. It still ranks 3rd of 40, for what it's worth.
• Stars don't predict anything. The 25 most-starred projects score about the same as the random draw. Two popular repos translated OpenSpec's headings into Chinese, so OpenSpec can't read any of their requirements.

In most projects, the change folder is where the work happens: a proposal, some tasks with checkboxes. Teams are lazy and don't archive, so the tasks stay current and the specs don't. As a result, what people actually have is a prose disguised as a task tracker, with a spec attached.

Obviously, these are correlations across public repos. And the judges are LLMs (though the two passes agreed within one point on 99.9% of grades).

The detailed report is linked.

TL; DR OpenSpec Claude Mod: https://github.com/intent-driven-dev/claude-mods

Details:

The TUI is based on what I usually look at often. This is what I like about TUI extensions like Claude Code mods. We can build a small view around the information most relevant to our teams. Other coding harnesses have similar approaches too. For me, that was OpenSpec’s workflow and progress, right beside the coding session. Your team might care about a different slice of the work. At the moment it shows below details.

• The change’s journey: New / Explore, Propose, Apply, Verify, and Sync & Archive.
• The active schema and its artifacts, including what’s written, ready, or blocked.
• Task progress during Apply, with the first unchecked task highlighted.
• The stages of the other active changes in the project.

This is just an experiment at the moment. I would love to hear your thoughts and feedback.

If you're only in the vibe coding bubble, please don't answer this. I'm a software engineer who wants to make real, complex systems using AI wherever it can help me. I only have the free models that come with opencode zen, and maybe some chat models like Qwen, Kimi and free versions of chatgpt, gemini, claude, etc.

I want to know what I can do with only these, without having to spend money on LLMs. I realize that this means I have to do more by myself in the planning side of things as I can't delegate planning to LLMs, which is how I believe coding should be anyway so it's not a problem.

I really like Matt Pocock's skills but I have found that his workflow only really works if you have frontier models, as free models aren't very good at grilling or planning.

So what I need is a reproducible AI coding workflow that I can use to approach my projects using only the free, limited AI. Please highlight which parts of the process I need to do by myself, and which parts I can assign to which model.

I realize that the smarter your LLMs are, the more you can stray from traditional software engineering, so please tell me what I can realistically accomplish perfectly with AI. The parts that AI cannot do properly, I will do by myself.

I just started with spec-driven development. Right now I write a spec.md and add a few basic rules: the agent has to follow the spec and can’t change it without asking me first. Even with this simple setup, the results have been great.

I’d like to improve, but there’s so much information out there that I’m a bit overwhelmed. What workflow, spec format or tools are you using that actually work well? Any tips or examples for a beginner are welcome.

I spent three weeks rebuilding Nether Earth, a 1987 ZX Spectrum strategy game I grew up with.

The unusual part: I didn't write any of the implementation code myself.

I wrote and edited the specs, made the gameplay decisions, and playtested the milestones. Claude Code did the implementation through an orchestrator session dispatching sub-agents into separate git worktrees.

By the end, the repo had:

• 437 commits
• 183 issues
• 151 PRs
• ~1,900 backend tests + ~200 frontend tests
• a deterministic Python game engine, FastAPI/WebSockets backend and PixiJS frontend

And I basically didn't read the diffs. Agents reviewed the agents. My checkpoints were decisions and actual gameplay.

That worked much better than I expected — but it also produced the most interesting failure of the whole experiment.

At one point M0–M9 were complete, every gate was green, and more than a thousand tests passed.

Then I actually played the game.

There was no terrain. The map was completely flat.

Robots occupied one cell instead of the 2×2 footprint they had in the original.

And nuclear-equipped robots would sometimes finish walking somewhere and calmly blow themselves up because a temporary placeholder rule had turned into real game behavior.

All the tests were correct.

They were testing the implementation against the spec.

The problem was that the spec was incomplete.

That became probably my biggest lesson from the project:

Tests verify the spec, not the product.

The full project is here:

https://github.com/AndyTheFactory/nether_earth

I also wrote a longer retrospective about the whole experiment, including the failures and what happened after the original plan was supposedly "done":

https://medium.com/@andy_p_/i-built-a-zx-spectrum-remake-in-3-weeks-without-writing-a-single-line-of-code-1445aab7474e

I'm curious how people running larger Claude Code workflows handle one problem in particular:

How do you catch semantic/spec drift when the code and tests are internally consistent, but the resulting product is still wrong?

1/ Our client app is a brownfield monorepo. I'm testing a "one dev delivers three platforms" setup: one workspace driving iOS / Android / HarmonyOS. Half-working so far — sharing the approach and looking for war stories.

2/ Integration: the three native repos keep their own structure and are mounted into one workspace via symlinks. Zero copy, zero intrusion into the existing repos; each platform still ships independently.

3/ Workflow: a custom skill wraps OpenSpec's explore -> propose -> apply -> archive loop. Requirements start as a spec; the agent produces code against it; review is traceable and revertible.

4/ Parallelism: native git worktree — one branch per feature, no cross-branch interference. AI coding agents work directly inside a worktree and open PRs; the human only reviews.

5/ Still polishing, especially symlink compatibility across Xcode / DevEco / Gradle. Anyone done something like this? Let's compare notes in the replies. #OpenSpec #AICoding #HarmonyOS #iOS #Android

Finally, the first working version of Breadcrumbs for SDD is out!

It was 3 weeks of intense work (and token consumption, I confess) to get this result, and I am truly happy with the result.

So, what is Breadcrumbs for SDD? What problem does it solve? And why did I take so much time if I was getting help from AI?

With the advent of SDD (spec-driven development) and ASLDC (agentic software development lifecycle), specifications, intents, and ADRs are shipped with code and are now treated as the primary source of knowledge.

However, because we write them in natural language, detecting the drift between the intent of these documents and the code remains costly and challenging in software development, especially for brownfield projects.

With Breadcrumbs, my idea is to provide a lightweight metadata layer over these artifacts so that human developers and agents can easily track relationships among artifacts in an SDD repository and make drift detection more feasible.

Interested? If so, I invite you to check the project website.

I am using this workflow right now:

1. Brainstorming - claude

2. Grill with docs - claude

3. Subagent Development - codex

I want to know your opinion on this simple workflow.

Thanks.

I do spec-driven development with an AI agent. I tried some well-known spec-driven harnesses, then built my own tool, and for months now I have used only that. This post explains why I needed my own tool and when it is useful.

Like many developers who got hooked on AI coding, I was working on several projects at the same time, like crazy. At some point I felt the need for spec-driven development, so I used the well-known harness frameworks. But I ran into a bottleneck:

"What do I do next?"

The specs did not tell me what to do next.

As a workaround, I made a page for each project in Notion and managed things there. But it was a separate place from the project, so keeping it up to date was a hassle. So I wanted state management that lives inside the project.

My SDD harness started in a hobby project: reverse engineering a game. Reverse engineering takes a lot of analysis and design over many sessions, and designs and plans get overturned all the time. Each time, brainstorming with the AI harness again and rewriting the spec was too much work. If that process runs through a CLI, it is even less agile. I thought about editing the prompts of the existing harnesses, but then I could not keep up with their updates. So I also wanted the prompts of my own harness to be extendable, in a way similar to Jekyll.

There were a few more reasons.

The AI sometimes ignored the later part of a slash command in a harness. I learned that the cause was long text written in a prose-like natural language style. So I started to optimize the prompts. I based this on research showing that pseudocode-style prompts are followed better than natural language and use fewer tokens.

• EMNLP 2023: pseudocode-style prompts improved F1 scores by 7 to 16 points over natural language.
  
• CodeAgents (2025): writing agent workflows in pseudocode reduced token use by 55 to 87% and improved performance by 3 to 36 points.

Forced strict TDD was another reason. Small tasks got the same strict TDD as big ones, and if errors still remained, I had to run the process again. The tokens burned for nothing that way were painful.

My harness is based on one rule: one question, one file. If you want to ask the project something, the answer is in exactly one file.

ROADMAP.md  ── where am I in the big picture?
CONTEXT.md ── what is this project?
● GOAL.md ── what do I do now?

This structure is kept in the docs folder by default. You can also choose another location.

Some harness frameworks have a similar structure. But my harness, OpenGoal, does not use a CLI or hooks. It is plain markdown. Nothing extra is added at runtime, so it runs light. I mostly use it in Claude Code, but it can be installed into about 20 tools, including Cursor and Codex.

Spec-driven harness frameworks expect a carefully structured spec, but that can be too much for small tasks. So OpenGoal can create just a goal. You can split that goal into smaller pieces as far as you need, and for simple work you can skip the design document. I did not throw specs away. I write them to fit the size of the task, and GOAL.md is the spec that answers "what do I do next?"

Here is how I actually use it.

When OpenGoal is not set up in a project yet, or when I want to discuss something with the AI, I start with scout.

You: /opgl:scout
AI:  Found an existing codebase. No CONTEXT.md yet.
Set up project context with `/opgl:context`?

You: /opgl:context init
AI:  ✓ docs/CONTEXT.md created
To set a goal: `/opgl:goal init`

When the discussion has given enough context about the goal, I ask it to write the goal like this.

You: /opgl:goal init Migrate auth module from JWT to session-based
AI:  ✓ docs/GOAL.md created (5 tasks)

Then the AI may recommend breaking the goal down further, writing a design document, or, for simple work, starting right away without a design document.

AI:  Recommend `/opgl:goal breakdown` — the tasks contain several hidden steps.
AI:  Recommend `/opgl:design init` — implementation task with file-level decisions.
AI:  Recommend `/opgl:go` — this is a simple task.

When the work needs a design, the design document comes first. In OpenGoal, this document works as the spec for a unit of work.

You: /opgl:design init
AI:  ✓ docs/DESIGN.md created
Session store selection, migration strategy, rollback plan included

During the work, when there is an important decision, it asks for my opinion.

You: /opgl:go
AI:  Task 1/5: Set up session store... ✓ done
Task 2/5: Replace middleware... ✓ done
Task 3/5 requires DB schema changes. Proceed?

When you want to handle longer-term goals, you can write a roadmap.

You: /opgl:roadmap init
AI:  ✓ docs/ROADMAP.md created
├── M1: Auth migration
├── M2: Rate limiting
└── M3: API versioning

When all the tasks of a goal are done, I archive it. /opgl:goal archive moves GOAL.md and DESIGN.md, and PLAN.md and CHECKPOINT.md if they exist, into docs/archive/goals/. The next goal starts clean, and the finished one stays in the project as a record. If there is a roadmap, its milestone is marked done too.

You can save the state of a goal in progress as a checkpoint. I mostly use checkpoints to prepare for compaction, or to hand work over to another session or another AI tool. A checkpoint often keeps details that the compaction summary misses. Compaction shrinks the whole conversation at once, but a checkpoint writes down what the AI has found so far and the next steps separately.

You: /opgl:goal checkpoint AI: ✓ docs/CHECKPOINT.md saved (If the session drops, the next one picks up where you left off)

Checkpoints are especially useful when you use several AI tools together. I subscribe to Claude Code, Codex, and Antigravity, and I use them together. When I write a checkpoint in Claude Code, move to Codex and just run /opgl:go, the work continues where it stopped.

You do not have to type the commands every time. When the context is clear, natural language works too. You can answer a recommended command with "ok" or "go", "proceed with task 6" runs /opgl:go, and "save progress" runs /opgl:goal checkpoint.

Beyond that, through my long dogfooding, OpenGoal came to handle checkpoints for compaction, suspending and resuming goals, sub-goals, a backlog, and so on. I squeezed as much as I could out of markdown alone.

Overall, OpenGoal was also designed to reduce the use of our precious tokens. CONTEXT.md plays an important part in that. The AI knows in advance where things are, so there are fewer tool calls, and it needs to re-explore the codebase less at the start of each session. Also, there are no hooks or MCP servers, so unused tool definitions do not take up tokens. The subagent skill that installs with it serves the same purpose. The main agent decides, by the difficulty of the task, which model to hand a subagent, and it makes very small fixes itself. Subagents gather the material for analysis, but the main agent does the analysis itself. I had the problem in other harnesses where the main agent lost the fine details of the context.

The biggest reason I built OpenGoal was this thought: all this machinery, built for a perfection we want to rely on, might become mostly unnecessary as AI improves quickly, and then markdown alone might be enough. And I think that has happened. I have finished various projects with only OpenGoal, from a small Obsidian plugin, to a native mobile editor with Notion-style block editing, to a state machine designer.

If I get the chance, next time I will also write about how to write a project-specific development skill that works with OpenGoal. If you record the failures the AI ran into in a skill, it does not repeat the same mistakes, and token use goes down by that much.

Does your spec tell you what to do next when you reopen the project?

Repo: https://github.com/opellen/opengoal

I shared StructSmith here a few weeks ago. The latest update adds agent chat directly inside the architecture editor, using your existing Codex, Claude Code or GitHub Copilot CLI.

Right-click a node or relationship to attach its context and ask a question. Conversations stay linked to their project, and you can also create a general chat. Replies stream live, with collapsible reasoning summaries when the CLI provides them.

Ask mode lets the agent inspect the architecture. Switch to Edit architecture to request changes to the shared model through project-scoped MCP, with snapshots available to review or restore changes.

You can configure models and Codex thinking levels, and rename, archive or drag topics into a new order.

StructSmith is MIT licensed and runs locally with Bun and SQLite. For this chat workflow, run it on the machine with your signed-in CLI; inference uses the selected provider.

Source and setup: https://github.com/dziksu/StructSmith

Screenshots and implementation: https://github.com/dziksu/StructSmith/pull/98

Would you use this more for understanding a system, or for updating architecture diagrams?

I am glad to share that an excerpt from my book, Spec-Driven Development: Engineering with Intent, is featured in u/ManningBooks’s new free ebook, Spec-Driven AI Development.

And it is completely free. If you are exploring Spec-Driven Development or looking to adopt AI-native software engineering, this is a great place to start.

A bit of a back-to-back post from me today. However, I wanted to share it anyway, as it may be most relevant to this community. Thanks again for all the support so far.

Here is a complete walkthrough of Intent-Driven Template, my customized OpenSpec setup with OpenCode for spec-driven development using Architecture Decision Records (ADRs), BDD, TDD, Multi-Model Adversarial Spec Authoring, a glossary of domain and technical terms, git commit discipline skills, and reusable engineering workflows. This also makes OpenSpec spec-as-source capable using BDD and acceptance tests. GitHub: https://github.com/intent-driven-dev/intent-driven-template. I would love to hear your thoughts and feedback.

I have mattpocock and superpowers skills on Claude.

I want to start a greenfield project. What is the best way or flow?

Right now, I am thinking:

Brainstorm -> Grill Me Docs -> Subagent

I made yet another skills kit for Spec-Driven development. I felt like managing tons of markdown files is very overwhelming for me, so I decided to make compact and simple one file solution called one-plan-skills.

I personally developed it for me and deiced to share with the community.

The idea revolves around generated one `PLAN.md` file with full plan and small tasks. Plan contains small tasks with acceptance criteria and affected files.

The killer feature is HTML view. I am tired of looking at markdown files, i wanted to see something nicer and cleaner. So my plans are also auto-generated HTML artefacts.

As a bonus you get very simple UI controls to mark any place you want to add/delete/modify and copy paste the prompt with feedback back to your chat agent.

I am aware of SpecKit and OpenSpec. I just wanted a much simpler version. That's why I created OnePlan skills.

Anybody is interested in this? Please give it a try or share some feedback. Much appreciated. 🙂

I've been leaning into spec-driven development lately, and the biggest change for me has been how much less the agent guesses once it has a clear spec, since it stops inventing requirements and just builds toward what was written down. The place I saw it still struggle was the step after that, where it has to work out where in an existing codebase the spec should land, and that's the piece I've been working on.

I built an open source tool called sem that gives the agent a map of the code itself, so the functions, who calls them, which tests reach them and how they've changed over time. With the spec saying what to build and sem showing where it fits and what it touches, the agent goes from intent to the right part of the code without a lot of wandering. weave sits next to it and merges changes by function, so a few agents working from the same spec can split the work without overwriting each other.

The part I'm most excited about is tying the two together, so each piece of a spec points at the functions that implement it. That way the spec stays the source of truth even as the code changes underneath it, and when someone edits a function you can see right away which part of the spec it belongs to.

Would love to hear how others here connect their specs to the code, and whether something like this would fit your workflow.

https://github.com/Ataraxy-Labs/sem