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.

[thlandgraf]

Fair point — if OpenSpec has been used from the start, the changes/ and archive/ trail does capture the evolution. My comment was more about the brownfield onboarding case, which is what the original question was asking about: you have a running app with zero specs and you want to adopt a spec-first workflow going forward.

The "prompt the agent to create archived specs" approach is interesting — I hadn't considered using the archive format as the container for a baseline. The risk I'd see is that the agent is reverse-engineering intent from code, which gets fuzzy for business logic that isn't obvious from the implementation. A method called calculateDiscount() might implement three different discount tiers with seasonal overrides that only the product owner knows about. The code tells you what it does, not why that specific behavior was chosen.

That said, even a partial baseline from code analysis is probably better than starting from zero. And you're right that models like Codex 5.3 can pick up a surprising amount of architecture from context — the question is whether you trust that enough to make it the canonical "this is what the system does" record. For high-stakes changes I'd still want a human to validate the baseline before the first CR lands against it.

[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."