docs: propose OpenSpec operating model

[rohitkrai03]

Why

The Boost pilot exposed that implementation context is spread across Jira, OpenSpec, workspace documentation, GitHub, code, and tests. Ownership is unclear, information is duplicated and drifts, and the growing OpenSpec tree is difficult for people and agents to analyze before starting work.

This RFC proposes a simpler operating model with explicit boundaries.

Proposal

• Jira owns roadmap, priority, ownership, dependencies, and story status.
• OpenSpec contains actionable implementation contracts for work that benefits from an explicit contract, with one change representing one vertical slice.
• Agents receive the selected change and relevant references rather than scanning the full specification tree.
• Standard OpenSpec artifacts are used as needed; design.md is added only when new architectural decisions need to be recorded.
• Blocked or deferred work remains in Jira rather than in the active OpenSpec queue.
• Completed changes are reconciled with code and tests, then archived.
• Boost validates the model before repository-wide tooling is considered.

Scope

This PR adds the RFC. It does not change OpenSpec tooling or existing specifications.

Review focus

Please review whether the problem statement reflects the Boost experience, whether the ownership boundaries and lifecycle are practical, and whether the proposed Boost pilot is a useful next step.

[rhdh-qodo-merge]

PR Summary by Qodo

Propose a bounded OpenSpec operating model

📝 Documentation 🕐 20-40 Minutes

AI Description

• Defines authoritative ownership across Jira, OpenSpec, GitHub, code, tests, and durable
 documentation.
• Establishes bounded implementation contracts, focused agent context, reconciliation, validation,
 and archival.
• Proposes validating the corrected workflow in Boost before repository-wide tooling.

Diagram

graph TD
  JIRA["Jira planning"] --> READY{"Contract needed?"} -->|Yes| CHANGE["OpenSpec change"] --> REVIEW["PR review"] --> BUILD["Code and tests"] --> CHECK["Reconcile and validate"] --> ARCHIVE["Canonical specs"]
  READY -->|No| NORMAL["Normal pull request"] --> BUILD
  CHECK -->|Story status| JIRA

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use Jira-only implementation briefs

• ➕ Maintains one system for planning, status, and implementation context.
• ➕ Eliminates the possibility of a separate OpenSpec queue drifting from Jira.
• ➖ Loses a version-controlled implementation and behavior contract near the code.
• ➖ Provides weaker repository-local validation, archival, and agent context boundaries.

2. Use OpenSpec as the complete workflow system

• ➕ Centralizes specifications, implementation tasks, and progress in the repository.
• ➕ Makes the full workflow visible alongside code history.
• ➖ Duplicates Jira ownership and status tracking.
• ➖ Recreates the mixed-state queue and synchronization problems observed in the Boost pilot.

Recommendation: Adopt the proposed bounded model and validate it through Boost before adding repository-wide tooling. It preserves Jira as the planning authority while retaining OpenSpec's strongest benefit: a focused, version-controlled implementation contract with explicit validation and archival.

Files changed (1) +224 / -0

Documentation (1) +224 / -0

openspec-operating-model.mdDefine the bounded OpenSpec operating model +224/-0

Define the bounded OpenSpec operating model

• Adds an RFC defining information ownership, the OpenSpec lifecycle, implementation-ready criteria, and focused agent context. It documents Boost pilot evidence, establishes reconciliation and validation expectations, and proposes a Boost-first rollout with measurable success criteria.

docs/openspec-operating-model.md

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Draft plans appear as actionable work ✓ Resolved 🐞 Bug ≡ Correctness

Description

The RFC makes every direct child of openspec/changes/ actionable and requires blocked or deferred
work to be removed, without defining how existing draft changes and non-actionable tasks are
classified first. Boost currently marks its changes as draft and includes blocked, moved, and
explicitly non-implementable tasks, so adopting this rule would misrepresent the active queue until
a migration and status policy are applied.

Code

docs/openspec-operating-model.md[R113-116]

+Every change directly under `openspec/changes/` is actionable implementation
+work. Review readiness is established through pull-request review, while
+ownership and implementation progress are visible in Jira, branches, and pull
+requests. Completion is represented by archiving the change.

Relevance

●●● Strong

Accepted documentation precedent favors clarifying ambiguous operational guidance; transition policy
is needed before declaring all existing changes actionable.

PR-#3795

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The RFC defines directory placement as the lifecycle state, while the repository's current metadata
and documentation identify all Boost changes as drafts and its task breakdown contains work that is
explicitly blocked, moved, or not to be implemented. The configured validator only runs the standard
openspec validate --all --json command and does not provide the proposed active-queue filtering or
migration behavior.

docs/openspec-operating-model.md[111-127]
workspaces/boost/README.md[24-38]
workspaces/boost/openspec/changes/ai-catalog-entity-model/.openspec.yaml[1-3]
workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md[18-20]
workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md[49-64]
workspaces/boost/package.json[25-27]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The RFC says every direct child of `openspec/changes/` is actionable implementation work, but the current Boost workspace contains draft changes and tasks explicitly marked blocked, moved, or `DO NOT IMPLEMENT`. Without migration criteria, `openspec list` can expose planning material as actionable work.

## Issue Context
Define how existing `.openspec.yaml` statuses and non-actionable task sections are handled before the operating model is adopted. Clarify whether only approved/implementation-ready changes belong in the active queue and document the migration needed for current Boost changes.

## Fix Focus Areas
- docs/openspec-operating-model.md[111-127]
- workspaces/boost/README.md[24-38]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/.openspec.yaml[1-3]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md[18-20]
- workspaces/boost/openspec/changes/ai-catalog-entity-model/tasks.md[49-64]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 11 rules

✅ Cross-repo context — repo relationships

Review mode: 🚀 Fast: This is a single, self-contained documentation RFC with no runtime or configuration behavior changes, so a lightweight review is sufficient.

Tip of the day

💡 Did you know, you can switch off images and animations for a plain-text comment

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[rhdh-qodo-merge]

Important

The /generate_labels command by Qodo is sunsetting on the 1st of October 2026 and will no longer be available. We recommend switching to the latest Qodo review capabilities. Learn more

[durandom]

The problem statement matches what the Boost tree looks like in practice. Jira for roadmap/status and OpenSpec as a bounded implementation contract is the right split.

The missing control is openspec archive. Boost currently has 18 active changes, no openspec/specs/, and no archive. Almost every change is still status: draft, including ones with tens or hundreds of open tasks, so openspec list cannot tell planning material from implementable work. workspaces/ai-integrations/openspec/ has the same shape in this repo: no archive, no live specs, and at least one change (ai-model-server-api-kind) is fully checked and still sitting in the active queue.

That lifecycle should be the shared rule. The schema does not have to be. OpenSpec is already per-project: openspec/config.yaml, custom schemas, and per-change .openspec.yaml. rhdh-agentic uses that on purpose (schema: rhdh-spec-driven, journal, PRD/ADR split, always-on design.md) and already archives into openspec/specs/. Boost can stay on stock spec-driven and keep design.md optional, as this RFC says. Do not flatten those into one repo-wide schema.

Boost-first still looks right. The follow-up should archive completed or non-actionable Boost changes rather than leaving changes/ as the long-lived spec. Later repo-wide checks should validate artifact shape and archive hygiene, and leave each workspace's schema/config alone. ai-integrations will need the same queue hygiene once the Boost path is proven.

[rohitkrai03]

The problem statement matches what the Boost tree looks like in practice. Jira for roadmap/status and OpenSpec as a bounded implementation contract is the right split.

The missing control is openspec archive. Boost currently has 18 active changes, no openspec/specs/, and no archive. Almost every change is still status: draft, including ones with tens or hundreds of open tasks, so openspec list cannot tell planning material from implementable work. workspaces/ai-integrations/openspec/ has the same shape in this repo: no archive, no live specs, and at least one change (ai-model-server-api-kind) is fully checked and still sitting in the active queue.

That lifecycle should be the shared rule. The schema does not have to be. OpenSpec is already per-project: openspec/config.yaml, custom schemas, and per-change .openspec.yaml. rhdh-agentic uses that on purpose (schema: rhdh-spec-driven, journal, PRD/ADR split, always-on design.md) and already archives into openspec/specs/. Boost can stay on stock spec-driven and keep design.md optional, as this RFC says. Do not flatten those into one repo-wide schema.

Boost-first still looks right. The follow-up should archive completed or non-actionable Boost changes rather than leaving changes/ as the long-lived spec. Later repo-wide checks should validate artifact shape and archive hygiene, and leave each workspace's schema/config alone. ai-integrations will need the same queue hygiene once the Boost path is proven.

@durandom Thanks, I agree. PR #4613 addresses part of the current cleanup, but I think the follow-up should establish a clean Boost baseline: classify the remaining changes, keep only actionable work under openspec/changes/, archive completed behavior under openspec/specs/, and move blocked, deferred, or historical material out of the active queue. I also agree that the lifecycle should be shared while each workspace keeps its own schema and configuration. The RFC keeps design.md optional and does not propose a repo-wide schema.

[gabemontero]

The problem statement matches what the Boost tree looks like in practice. Jira for roadmap/status and OpenSpec as a bounded implementation contract is the right split.
The missing control is openspec archive. Boost currently has 18 active changes, no openspec/specs/, and no archive. Almost every change is still status: draft, including ones with tens or hundreds of open tasks, so openspec list cannot tell planning material from implementable work. workspaces/ai-integrations/openspec/ has the same shape in this repo: no archive, no live specs, and at least one change (ai-model-server-api-kind) is fully checked and still sitting in the active queue.
That lifecycle should be the shared rule. The schema does not have to be. OpenSpec is already per-project: openspec/config.yaml, custom schemas, and per-change .openspec.yaml. rhdh-agentic uses that on purpose (schema: rhdh-spec-driven, journal, PRD/ADR split, always-on design.md) and already archives into openspec/specs/. Boost can stay on stock spec-driven and keep design.md optional, as this RFC says. Do not flatten those into one repo-wide schema.
Boost-first still looks right. The follow-up should archive completed or non-actionable Boost changes rather than leaving changes/ as the long-lived spec. Later repo-wide checks should validate artifact shape and archive hygiene, and leave each workspace's schema/config alone. ai-integrations will need the same queue hygiene once the Boost path is proven.

@durandom This PR - #4613 is trying to clean up some of those things. But I would like to properly reset the boost workspace and keep only actionable items in /changes if we agree to ahead with this proposal.

@durandom @rohitkrai03

I concur with the notion of revisiting remaining post 2.1 openspec/changes content, both from the features perspective and the pre-feature use case bootstrapping, and resetting what remains as a viable foundation and what goes away

as I noted in slack, I'm also fine with moving the remaining post 2.1 changes content off to the side in some form or fashion, to allow reference to it to be done in parallel with clean room next iteration attempts on 1507/1508/1510/1513 etc. content as 2.2 moves past feature refinement, readout, etc.

top level preamble aside, will next perform my detailed read of @rohitkrai03 's proposal here

[gabemontero]

generally I like where this is going @rohitkrai03 @durandom @johnmcollier

I gather @rohitkrai03 that you wanted to isolate fullsend from openspec.

But at least from my perspective both citing its influence both with the prior boost forays and what we'll want to continue doing moving forward, the guardrails you are laying out need to get into that.

[gabemontero]

part of my review got left out

[gabemontero]

Good with your updates from my first set of review comments @rohitkrai03 - including what correlated to our video conf meeting wrt deferring on the how to integrate various agentic harnesses, including fullsend, into f/up work.

A few more clarifications on how the various pilots landed where they landed occurred to me after a second look. I provided suggested edits for thos.

One note - after our ai catalog sync meeting, I brought up in the agentic sdlc wg with @durandom the question of how we start socializing the best practices etc. put forth by your RFC.

@durandom was pretty clear that ultimately, proposals like this RFC, need to becomes skills imported from well know locations like redhat-developer/rhdh-skills that all of RHDH dev will do, vs expecting them to get pointed to or find doc like this.

I think perhaps then we might need a "next steps" section in this doc, perhaps even with RHIDP Jira items, that track the curation of your proposed operating model into one or more skills (new ones and/or existing ones in theory). We could also open Jiras for the how-to's of using various harnesses including fullsend with this model.

One bit of good news with that last point. @johnmcollier was able to show some really good progress with various Jira integration. Feels like we are close to the point of being able to trigger /fs-code / /fs-review / /fs-triage from Jira stories vs. having to create github issues to facilitate that.

WDYT

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rohitkrai03]

Thanks @gabemontero. I kept the pilot context concise and added a short “Next steps” section covering Boost validation and, if successful, curation into shared RHDH skills.
The RFC stays focused on the operating-model decision; detailed pilot history, Fullsend workflow mechanics, and Jira tracking can follow separately.

[gabemontero]

Thanks @gabemontero. I kept the pilot context concise and added a short “Next steps” section covering Boost validation and, if successful, curation into shared RHDH skills. The RFC stays focused on the operating-model decision; detailed pilot history, Fullsend workflow mechanics, and Jira tracking can follow separately.

I'm good with your condensing of my suggested edits @rohitkrai03 as well as your next steps.

I'm also good with the notion you introduce in the next steps of vetting things with upcoming work in boost before we pursue further socialization, including updates/additions to rhdh-skills

That said, before I officially approve, and in theory this gets merged, I'd like to have a live conversation with us, @durandom , and perhaps @yangcao77 and @johnmcollier (maybe culminating in next week's agentic sdlc meeting if you can swing it) to try and collection some suggestions and details on how we might work toward inclusion of skills.

I'll start that live conversation via a slack thread in the agentic sdlc channel to try to kick that ^^ off.

If it becomes difficult to get any traction wrt that discussion in the short term, I'll go ahead and approve/merge and we'll then try f/up separately.