Generating specs for existing app

[i102761]

For adopting OpenSpec with an existing application, is there value in somehow generating Specs on all of the current application features to baseline it before taking forward with the first change? Else the master specs will only start with just the new feature once done. If there is value in doing, what is the recommended prompt to use?

[harikrishnan83]

Hello @i102761 , here is my video on this.

Spec-Driven Development on Brownfield Projects - https://www.youtube.com/watch?v=gJvwn-nuSc8

Would love to hear you thoughts and feedback.

[thlandgraf]

Yes there's real value, and we built a feature specifically for brownfield adoption. Full disclosure: I'm the creator of SPECLAN, another VS Code extension in this space.

The flow: paste your existing README or PRD or user stories into an HLRD import dialog, the AI parses it and generates a Goal then Feature then Requirement then Acceptance Criterion tree in one pass. You review, edit, and you have a baseline. We tested it on a 15k LOC Flutter app recently — it caught ~80% of the major features from the README alone, the rest needed manual entries.

The reason to baseline is traceability: when the first change request lands you need something to change FROM. Starting only with change specs means you can never answer "why does the system do X?" — the pre-existing behavior is invisible. Even a partial baseline (just the features adjacent to the planned change) is better than nothing.

The prompt itself is less important than the parsing target — you want the AI to extract a tree, not a flat list. Hierarchical parent/child relationships are what make subsequent changes navigable.

[B2F]

Since you seem to be promoting a different tool, can you argue more about what each framework does / does not do ?

[thlandgraf]

Fair ask. Here's what I see as the real architectural differences — not "which is better" but "where each one makes different tradeoffs":

Spec structure:
OpenSpec uses a flat model — one spec.md + plan.md + tasks.md per feature, stored in a single directory. Simple, easy to reason about, low ceremony.
SPECLAN uses a hierarchical tree — Goal → Feature → Requirement → Acceptance Criterion, each as its own Markdown file with YAML frontmatter, nested in directories that mirror the decomposition. More structure, more files, but you can navigate parent/child relationships and cross-reference by ID.

Lifecycle and locking:
OpenSpec specs are directly editable at any time. Changes go through a changes/ directory, but there's no enforced gate that prevents someone from modifying a spec.
SPECLAN has a status lifecycle (draft → review → approved → locked). Once a spec reaches "approved," the editor makes it read-only. Modifications go through Change Request entities — separate files that reference the original spec by ID, describe what changes and why, and have their own review cycle. More friction, but the spec is trustworthy as a canonical record.

AI integration:
OpenSpec is CLI-first — agents interact with specs by reading/writing files. Works with any agent, any editor.
SPECLAN ships an MCP server with ~40 tools (get_feature_tree, create_requirement, move_feature, etc.). AI agents can read the hierarchy, create entities, and respect status gates programmatically. More opinionated, but the agent can't accidentally modify an approved spec.

Brownfield adoption:
OpenSpec doesn't have a dedicated import path — you'd prompt the agent to generate specs from existing code/docs.
SPECLAN has an HLRD Import dialog where you paste unstructured docs (README, PRD, user stories) and the AI generates the full Goal→Feature→Requirement tree in one pass. Tested on a 15k LOC Flutter app — caught ~80% of features from the README alone.

Where OpenSpec wins: simplicity, editor-agnosticism, lower learning curve, massive community (25K+ stars). If your workflow is "one developer, one feature at a time, ship fast," OpenSpec's flat model is less overhead.

Where SPECLAN adds value: multi-feature traceability (which requirement traces to which goal?), lifecycle enforcement (PO approves before dev implements), brownfield onboarding, and MCP-based AI governance. If you're managing 20+ specs across a team where multiple people own different parts, the hierarchy and status gates start paying for themselves.

Both tools store specs as Markdown files in Git. The philosophical split is: OpenSpec optimizes for developer speed, SPECLAN optimizes for organizational traceability. Neither is wrong — it depends on whether your bottleneck is "writing specs fast enough" or "keeping specs trustworthy as the codebase evolves."

[B2F]

The reason to baseline is traceability: when the first change request lands you need something to change FROM. Starting only with change specs means you can never answer "why does the system do X?" — the pre-existing behavior is invisible. Even a partial baseline (just the features adjacent to the planned change) is better than nothing.

From my understanding, changes are already including the "why" in proposal.md + design.md.
Pre-existing behavior will be seen in either changes/ or archive specs/. SO that if OpenSpec have been used from the start it is a non-issue.

If you want a oneshot baseline, I guess you could just prompt your agent to create archived specs for the whole existing project.

From my experience a well performing model like Codex 5.3 is able to pickup existing architecture and intent from any proposal, when called within an agentic coding tool (opencode in my case), but there is less guarantee that it will actually make the effort to do so if not explicitly prompted to.

So I agree that for browfield projects it is not clear which workflow should be followed.

[B2F]

I came along this interesting read: [https://medium.com/@addyosmani/stop-using-init-for-agents-md-3086a333f380](url). In short some studies highlighted that too much context can be counterproductive...

Which practical benefits did you get from establishing a full baseline ?

[thlandgraf]

Good reference — Addy's point about context bloat is exactly right, and it's the reason we don't dump the full baseline into the agent's context window.

The baseline lives in the file system as individual Markdown files, but the agent never sees all of it at once. When implementing a feature, we generate a plan file that pulls only the specs relevant to that task — typically the feature spec itself, its child requirements, and the ancestor chain up to the goal. On a project with 40+ spec files, the agent might see 3-5 of them for any given task. Small, focused context.

The practical benefit of having the full baseline is navigation and traceability, not context size. When a change request comes in, you can trace "this requirement belongs to this feature, which serves this goal" and immediately see what else might be affected. Without the baseline, you're guessing at impact scope every time.

So the baseline isn't "give the agent everything" — it's "have a map so you know which 3-5 files the agent actually needs."

[B2F]

@thlandgraf yes agreed, and this is where I think openspec is lacking. Too much focus on active changes, not enough reliance on files located in archives. But maybe I'm missing something ( #936 (reply in thread)) ...

[marcindulak]

For your information, there is a parallel discussion about the purpose of existing specs #921, and a discussion about constraining the agents obra/superpowers#895.

The problem is that discussions without public programmatic evaluations represent possibly non-repeatable experiences of individual users, and we don't know how representative are these experiences on average.

[B2F]

It's hard to make statements about nondeterministic agents that tend to ignore instructions, but it appears that today the value of maintaining the design documentation is mostly for humans to keep the agent on track.

Exactly this. When I asked the intent behind not listing archives at explore stage in another thread #955, it is because I see value in helping the human make more informed decision, and this has nothing to do with benchmarks ?

[clay-good]

The project's position is: no, don't baseline upfront.

From the FAQ — "Existing codebases are the main event. OpenSpec is brownfield-first: you do not document your whole app up front. You write specs only for what each change touches, and your specs fill in over time around the work you actually do."

You're right that specs/ starts nearly empty, but that's the design, not a gap. A generated baseline tends to be a large document nobody validated against the code, and it decays from day one. A spec born from a change you actually shipped doesn't.

There's now a dedicated guide: Using OpenSpec in an Existing Project.

If you still want a baseline, community tooling exists for it (see discussions #739 and #634) — it's just not the recommended starting point.

Closing as answered — reopen or comment if your case is different.