Skip to content

Commit 98d56bd

Browse files
docs: align roadmap and explore ux with initiatives
1 parent 4e46997 commit 98d56bd

File tree

2 files changed

+29
-12
lines changed

2 files changed

+29
-12
lines changed

openspec/explorations/explore-workflow-ux.md

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ The explore workflow is part of the core loop (`propose`, `explore`, `apply`, `a
66

77
Currently, explore references `/opsx:new` and `/opsx:ff` which are being replaced with `/opsx:propose`. But beyond just updating references, there are deeper UX questions about how explore should work.
88

9+
This exploration is also affected by the emerging workspace direction: for larger cross-team or cross-repo work, OpenSpec may need to treat the **initiative** as the first-class planning object and repo-local changes as execution artifacts. That means explore may sometimes be seeding an initiative, not just a single change.
10+
911
## Open Questions
1012

1113
### Exploration Artifacts
@@ -17,6 +19,7 @@ Currently, explore references `/opsx:new` and `/opsx:ff` which are being replace
1719
2. **Where should exploration files live?**
1820
- `openspec/explorations/<name>.md`?
1921
- `openspec/changes/<change>/explorations/`?
22+
- `.openspec-workspace/initiatives/<initiative>/explorations/` for coordinated work?
2023
- Somewhere else?
2124

2225
3. **What should the format be?**
@@ -30,15 +33,17 @@ Currently, explore references `/opsx:new` and `/opsx:ff` which are being replace
3033
- e.g., exploring auth approaches separately from UI approaches
3134
- How would these relate to each other?
3235

33-
5. **How do explorations relate to changes?**
36+
5. **How do explorations relate to changes or initiatives?**
3437
- Before change exists: standalone exploration
35-
- After change exists: exploration linked to change?
38+
- After repo-local change exists: exploration linked to change?
39+
- For coordinated work: exploration linked to initiative first, then optionally referenced by repo-local changes?
3640

3741
### Lifecycle & Transitions
3842

3943
6. **What happens before a change proposal exists?**
4044
- Exploration is standalone
4145
- When ready, user runs `/opsx:propose`
46+
- For coordinated work, should exploration context seed an initiative first?
4247
- Should exploration context automatically seed the proposal?
4348

4449
7. **What happens after a change proposal exists?**
@@ -90,11 +95,19 @@ Currently, explore references `/opsx:new` and `/opsx:ff` which are being replace
9095
- **Pro:** Clear relationship to changes
9196
- **Con:** Where do pre-change explorations go?
9297

98+
### Approach E: Initiative-First Explorations for Coordinated Work
99+
- Local work can stay standalone or change-linked
100+
- Coordinated work saves exploration notes under an initiative in the coordination workspace
101+
- Repo-local changes can reference the shared exploration when execution starts
102+
- **Pro:** Matches the emerging split between shared planning and repo-local execution
103+
- **Con:** Adds another context where exploration artifacts may live
104+
93105
## Next Steps
94106

95107
- [ ] User research: How do people actually use explore today?
96108
- [ ] Prototype: Try saving explorations and see if propose benefits
97109
- [ ] Decide: Pick an approach based on findings
110+
- [ ] Reconcile explore UX with initiative-first coordinated planning
98111
- [ ] Implement: Update explore workflow accordingly
99112

100113
## Related

openspec/explorations/workspace-roadmap.md

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -47,18 +47,19 @@ OpenSpec needs a better way to organize:
4747

4848
References help agents and humans navigate related specs without requiring OpenSpec to build a dependency graph system on day one.
4949

50-
### 3. Linked per-repo changes are the right primitive
50+
### 3. Initiatives plus linked per-repo changes are the right primitive
5151

5252
For true multi-repo work, the likely durable primitive is:
5353

54-
- one linked change per owning repo
54+
- one initiative as the shared planning object
55+
- one linked change per owning repo as the execution artifact
5556
- stable identifiers connecting them
5657

5758
### 4. Cross-repo work needs a neutral planning location
5859

5960
For multi-repo work, a single repo is not an honest home for the whole planning artifact.
6061

61-
Some form of coordination workspace or coordination repo is needed.
62+
Some form of coordination workspace or coordination repo is needed for the initiative-level plan.
6263

6364
### 5. Team-shared coordination is a real requirement
6465

@@ -124,8 +125,8 @@ Support real multi-repo planning demand with the thinnest credible coordination
124125

125126
### Ship
126127

127-
1. Linked per-repo changes using stable project identifiers
128-
2. A neutral coordination workspace or coordination repo for planning
128+
1. Initiative artifacts for shared planning in a neutral coordination workspace or coordination repo
129+
2. Linked per-repo changes using stable project identifiers
129130
3. Explicit repo linking via project IDs
130131
4. Resolution through:
131132
- explicit input
@@ -137,6 +138,7 @@ Support real multi-repo planning demand with the thinnest credible coordination
137138

138139
- users have an honest place to stand for multi-repo work
139140
- cross-repo plans are no longer buried in one repo
141+
- shared planning and repo-local execution are clearly separated
140142
- ownership stays with the real repos
141143
- agents can be told what roots matter
142144

@@ -157,6 +159,7 @@ This phase should feel like:
157159

158160
- local planning by default
159161
- upgrade to a coordinated initiative when needed
162+
- initiative-level planning in the coordination workspace
160163
- linked repo-local changes underneath
161164

162165
Not like:
@@ -257,7 +260,7 @@ Because demand is already real, some things should not be treated as purely futu
257260

258261
- nested spec paths
259262
- references
260-
- linked change primitive
263+
- initiative artifact + linked change primitive
261264
- stable project identifiers
262265
- thin coordination layer for multi-repo planning
263266

@@ -310,10 +313,11 @@ If this roadmap were translated into actual change proposals, the sequence would
310313

311314
1. nested spec paths + references
312315
2. monorepo scope filtering and multi-area planning improvements
313-
3. linked change metadata across repos
314-
4. thin coordination workspace / repo for multi-repo planning
315-
5. team-shared coordination hardening
316-
6. optional shared contract maturity features
316+
3. initiative artifact for shared planning
317+
4. linked change metadata across repos
318+
5. thin coordination workspace / repo for multi-repo planning
319+
6. team-shared coordination hardening
320+
7. optional shared contract maturity features
317321

318322
---
319323

0 commit comments

Comments
 (0)