Demystifying the OpenSpec Propose Process: What Happens Behind the Scenes?

When we execute the proposal creation command (propose) in OpenSpec — for example, when starting the add-course-enrollment-module functionality —, the system works behind the scenes to generate a series of fundamental files for development success.

If you’ve ever wondered what each of these artifacts is for, this article is for you. Let’s explore the anatomy of each generated document and how they ensure team alignment: from business vision to coding.

1. The Proposal (proposal.md): The “Why” and the “What”

The proposal document is the starting point of your journey. It serves as the bridge between business and engineering.

• What it contains: Motivation for the functionality, exact scope of what will be built, and which new “capabilities” are being introduced to the system. In our example, it maps the impact on the project and introduces enrollment-management, payment-gateway-adapter, and enrollment-command-dispatch.
• What it’s for: Ensuring that everyone involved (developers, POs, stakeholders) has clarity about the value being delivered and the size of the change, even before we write the first line of code.

2. The Design Document (design.md): The “How” at High Level

If Proposal focuses on business, Design Document deepens into technical terrain. Here live architecture decisions and risk mitigation.

• What it contains: Documents the technical decisions that will guide development. For example, the decision to replicate the pattern already used in “students” in the frontend, the adoption of deterministic commands in BFF, payment adapter isolation, and ensuring idempotency via request_id based on polling.
• What it’s for: Preventing future headaches. By listing risks, their mitigations, and the migration plan, the technical team has a map of possible obstacles and how to circumvent them without hurting the application’s architecture.

3. The Specs (specs/*/spec.md): The Rules of the Game

One of OpenSpec’s great insights is dividing a complex problem into smaller “capabilities,” generating dedicated specifications for each system domain:

specs/enrollment-management/spec.md (Frontend)

Focused on user experience. Defines interface requirements: how the enrollments table should behave, rules for hiding sensitive data, allowed actions (edit, remove, open URL, trigger message modals), and non-functional requirements such as responsiveness and synchronization with backend.

specs/payment-gateway-adapter/spec.md (Integration)

Focused on communication with the partner. Defines the rules of the game with the Payment Gateway API: how to create, query, update, and cancel payments. In addition, it ensures correct mapping of third-party API statuses to the internal domain and formalizes security in credential handling.

specs/enrollment-command-dispatch/spec.md (Backend/BFF)

Focused on internal robustness. Defines responsibilities in BFF (Backend For Frontend), such as deterministic resolution of provider configurations, issuance of versioned commands, and strict application of idempotency and traceability in events.

4. The Action Plan (tasks.md): Getting Hands-On

The cherry on top of the entire planning process. After understanding context, architecture, and specific requirements, OpenSpec compiles all this into an actionable checklist.

• What it contains: A logical grouping of tasks. In the case of our enrollment functionality, 12 ordered groups were generated for implementation: ranging from initial setup, through domain modeling, use cases, infrastructure, screen/UI development, hook construction, route configuration, and observability, to closing with tests and final documentation.
• What it’s for: It’s the developer’s pocket guide. It allows the team to pick up independent tasks knowing exactly in what order they should be executed, making progress predictable and easy to track.

Conclusion

Having a brilliant idea is great, but transforming it into software running in production requires method.

With the OpenSpec Propose process, all the heavy lifting of planning, architectural organization, and task division is done fluidly. The result are extremely predictable development cycles (sprints), always living documentation, and an intelligently reduced time-to-market in a standardized way.

Next time OpenSpec generates these artifacts, you’ll know exactly the importance of each piece of this gear!