Usage of particular documents for external feedback loops?

[devTS123]

I plan to introduce Spec-Driven Development into our processes. As we extend an existing product with new or modified features in response to customer "change requests", I prefer Open-Spec because of its focus on brownfield projects.

I would like to ask for your advice on a specific issue I have in my mind:

We have established processes of writing a very detailed internal specification as the basis for development. For this I plan to use Open-Spec.
In parallel, the external client receives an "abstracted" solution description (i.e. background, problem, solution design without internal or highly technical details) as a Word document or PDF. The client can then annotate this with his feedback and return it to us. The feedback loop may occur once or multiple times.
Later, the final solution description is then part of the contract with the client. So, he would never get in touch with the Open-Spec files.

Does anyone have any ideas on how best to handle this in the scope of Open-Spec?

My preference would be to generate the initial client-facing solution description from the open-spec information, then reconcile any feedback received from the client with the open-spec information and modify only the changed sections in the open-spec files as well as in the client solution description; without completely regenerating the external description (as that could lead to a substantially different text/wording).

Thank you very much for your help and advice in advance!

[Joaquincuevas]

You can make the client document a first-class artifact with a custom schema, so it lives next to the specs and gets updated section by section instead of regenerated.

1. Fork the default schema (Customization docs):

bash
openspec schema fork spec-driven client-facing

2. Add a client-brief artifact in openspec/schemas/client-facing/schema.yaml:

yaml

• id: client-brief
  generates: client-brief.md
  description: Customer-facing solution description (no technical detail)
  template: client-brief.md
  instruction: |
  Write for the customer: Background, Problem, High-level solution.
  No code, file names or internal specs.
  When updating, change only the sections affected by the change;
  keep all other wording exactly as it is.
  requires:
  • proposal

and create templates/client-brief.md with your fixed headings (Background / Problem / Solution).

3. Feedback loop:

Export client-brief.md to Word/PDF with Pandoc (pandoc client-brief.md -o brief.docx --reference-doc=your-template.docx) and send it.
When annotations come back, apply them to client-brief.md and to the affected spec/design sections in the same pass. Ask the agent to edit only the commented sections; the instruction above reinforces that. Git diffs then show exactly what changed between rounds.
The version the client signs is a commit, which makes it easy to reference in the contract.

Keeping both documents in one change means they’re reviewed and archived together, and the client never sees the internal specs.

If this helps, please mark it as the answer.

[devTS123]

Thank you, Joaquincuevas, for your comprehensive description and detailed guidance. That is very helpful!
I will try it out using this 'recipe' :-)