Skip to content

[codex] Add context stores and initiative views #1127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TabishB merged 12 commits into from
May 27, 2026
Merged

[codex] Add context stores and initiative views #1127

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
e1f888a
Document initiative-led workspace direction
TabishB May 25, 2026
2c6d8e1
Add context stores and initiative change links
TabishB May 25, 2026
5b15e3b
Let workspaces open initiative views
TabishB May 25, 2026
64fa35d
Add workspace root bundle artifacts
TabishB May 25, 2026
9f158d5
Support legacy workspace roots in planning resolution
TabishB May 25, 2026
120e765
Remove accidental workspace root bundle artifacts
TabishB May 26, 2026
9c0244e
Bundle workspace reimplementation docs into roadmap
TabishB May 26, 2026
f741ed4
Preserve workspace context store bindings
TabishB May 26, 2026
db0532c
Address review feedback for context store initiatives
TabishB May 26, 2026
892f6e2
test: canonicalize context store path assertions
TabishB May 26, 2026
cb9adee
Refine context store and workspace core boundaries
TabishB May 26, 2026
70aadce
Avoid initiative diagnostic regex backtracking
TabishB May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 0 additions & 68 deletions WORKSPACE_REIMPLEMENTATION_START_HERE.md
View file
Open in desktop

This file was deleted.

4 changes: 3 additions & 1 deletion bin/openspec.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
#!/usr/bin/env node

import '../dist/cli/index.js';
import { runCli } from '../dist/cli/index.js';

runCli();
194 changes: 183 additions & 11 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,12 @@ The OpenSpec CLI (`openspec`) provides terminal commands for project setup, vali
| Category | Commands | Purpose |
|----------|----------|---------|
| **Setup** | `init`, `update` | Initialize and update OpenSpec in your project |
| **Workspaces (beta)** | `workspace setup`, `workspace list`, `workspace ls`, `workspace link`, `workspace relink`, `workspace doctor`, `workspace update`, `workspace open` | Set up planning across linked repos or folders |
| **Workspaces (beta)** | `workspace setup`, `workspace list`, `workspace ls`, `workspace link`, `workspace relink`, `workspace doctor`, `workspace update`, `workspace open` | Set up local views over linked repos or folders |
| **Shared context (beta)** | `context-store setup`, `context-store register`, `context-store list`, `context-store doctor`, `initiative create`, `initiative show`, `initiative list` | Manage local context-store registrations and durable initiative context |
| **Browsing** | `list`, `view`, `show` | Explore changes and specs |
| **Validation** | `validate` | Check changes and specs for issues |
| **Lifecycle** | `archive` | Finalize completed changes |
| **Workflow** | `status`, `instructions`, `templates`, `schemas` | Artifact-driven workflow support |
| **Workflow** | `new change`, `set change`, `status`, `instructions`, `templates`, `schemas` | Artifact-driven workflow support |
| **Schemas** | `schema init`, `schema fork`, `schema validate`, `schema which` | Create and manage custom workflows |
| **Config** | `config` | View and modify settings |
| **Utility** | `feedback`, `completion` | Feedback and shell integration |
Expand Down Expand Up @@ -52,7 +53,13 @@ These commands support `--json` output for programmatic use by AI agents and scr
| `openspec workspace link` | Link a repo or folder | `--json` for structured link output |
| `openspec workspace relink` | Repair a linked path | `--json` for structured link output |
| `openspec workspace doctor` | Check one workspace | `--json` for structured status output |
| `openspec workspace update` | Refresh workspace-local agent skills | `--tools` selects agents; profile selects workflows |
| `openspec workspace update` | Refresh workspace-local guidance and agent skills | `--tools` selects agents; profile selects workflows |
| `openspec context-store list` | Browse registered context stores | `--json` for structured registrations |
| `openspec context-store doctor` | Check local store setup | `--json` for structured diagnostics |
| `openspec initiative list` | Browse shared initiatives | `--json` for structured initiative records |
| `openspec initiative show <id>` | Resolve an initiative | `--json` for canonical paths and metadata |
| `openspec new change <id>` | Create repo-local change scaffolding | `--json`, plus `--initiative` for shared coordination links |
| `openspec set change <id>` | Update checked-in change metadata | `--json`, plus `--initiative` for shared coordination links |

---

Expand Down Expand Up @@ -168,9 +175,9 @@ openspec update

## Workspace Commands

Workspace commands are under active development and are not ready for use yet. Do not build external automation, integrations, or long-lived workflows on top of this command surface; command behavior, state files, and JSON output can change at any point.
Workspace commands are in beta. The local-view model below is the current direction, but external automation, integrations, and long-lived workflows should still treat command behavior, state files, and JSON output as evolving.

Coordination workspaces are planning homes for work that spans multiple repos or folders. Workspace visibility is not change commitment: link the repos or folders OpenSpec should know about, then create changes when you are ready to plan specific work.
Coordination workspaces are machine-local views over linked repos or folders. Workspace visibility is not change commitment: link the repos or folders OpenSpec should know about, then create changes when you are ready to plan specific work.

### `openspec workspace setup`

Expand Down Expand Up @@ -269,7 +276,7 @@ JSON responses use typed objects plus `status` arrays. Primary data lives in `wo

### `openspec workspace update`

Refresh workspace-local OpenSpec skills from the active global profile.
Refresh workspace-local OpenSpec guidance and agent skills.

```bash
openspec workspace update [name] [options]
Expand All @@ -293,9 +300,9 @@ openspec workspace update --workspace platform --tools codex,claude
openspec workspace update --workspace platform --tools none
```

`workspace update` reuses the stored workspace skill agent selection when `--tools` is omitted. Passing `--tools` replaces that stored selection. It refreshes only OpenSpec-managed workflow skill directories in the workspace root, removes deselected managed workflow skills, and leaves linked repos and folders untouched.
`workspace update` refreshes the generated workspace guidance block and local open surface. For agent skills, it reuses the stored workspace skill agent selection when `--tools` is omitted. Passing `--tools` replaces that stored selection. It refreshes only OpenSpec-managed workflow skill directories in the workspace root, removes deselected managed workflow skills, and leaves linked repos and folders untouched.

Running `openspec update` from inside a workspace planning home redirects to `openspec workspace update`; run `openspec update` inside repo-local projects when you want repo-owned tool files updated.
Running `openspec update` from inside a workspace redirects to `openspec workspace update`; run `openspec update` inside repo-local projects when you want repo-owned tool files updated.

### `openspec workspace open`

Expand All @@ -310,6 +317,9 @@ openspec workspace open [name] [options]
| Option | Description |
|--------|-------------|
| `--workspace <name>` | Alias for the positional workspace name |
| `--initiative <id>` | Open an initiative as a local workspace view. Accepts `<id>` or `<store>/<id>` |
| `--store <id>` | Registered context store id for `--initiative` |
| `--store-path <path>` | Existing local context store root for `--initiative` |
| `--agent <tool>` | One-session agent override: `codex`, `claude`, or `github-copilot` |
| `--editor` | Open the maintained VS Code workspace file as a normal editor workspace |
| `--no-interactive` | Disable workspace and opener picker prompts |
Expand All @@ -322,15 +332,130 @@ openspec workspace open platform
openspec workspace open platform --agent github-copilot
openspec workspace open --agent codex
openspec workspace open --editor
openspec workspace open --initiative billing-launch --store platform
openspec workspace open --initiative platform/billing-launch
```

`workspace open` uses the current workspace when run inside one, auto-selects the only known workspace when run elsewhere, and asks the user to choose when multiple workspaces are known. `--agent` and `--editor` do not change the stored preferred opener. Passing both opener overrides is an error; choose either `--agent <tool>` or `--editor`.

When `--initiative` is used, OpenSpec prepares or selects a private local workspace view for that initiative. Registry-selected stores are stored by id; `--store-path` stores a runtime-local path selector because workspace views are private local state.

OpenSpec maintains `<workspace-name>.code-workspace` at the workspace root for VS Code editor and GitHub Copilot-in-VS-Code opens. That file is machine-local and ignored by default with a specific `<workspace-name>.code-workspace` `.gitignore` entry, so user-authored `*.code-workspace` files remain eligible for tracking.

The maintained VS Code workspace includes the coordination root as `.` plus valid linked repos or folders as additional roots. VS Code displays those entries as a multi-root workspace.

Root workspace open supports exploration and planning across linked repos or folders. Implementation edits should start only after an explicit user request and a normal OpenSpec implementation workflow.
Root workspace open makes linked repos or folders visible for exploration and context. Implementation edits should start only after an explicit user request and a normal OpenSpec implementation workflow.

---

## Shared Context Commands

Context stores and initiatives are beta coordination surfaces. A context store is a local registration for durable shared context, usually a Git-backed folder or clone. An initiative is shared coordination context inside a context store; repo-local changes can link to it without copying the shared plan into every repo.

### `openspec context-store setup`

Create and register a local context store.

```bash
openspec context-store setup [id] [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--path <path>` | Context store folder path; defaults to `./<id>` |
| `--init-git` | Initialize a Git repository in the context store |
| `--no-init-git` | Do not initialize a Git repository |
| `--json` | Output JSON |

Examples:

```bash
openspec context-store setup team-context
openspec context-store setup team-context --path /repos/team-context --no-init-git
openspec context-store setup team-context --json --no-init-git
```

### `openspec context-store register`

Register an existing local context store folder.

```bash
openspec context-store register [path] [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--id <id>` | Context store id; defaults to store metadata or folder name |
| `--json` | Output JSON |

### `openspec context-store list`

List locally registered context stores.

```bash
openspec context-store list [--json]
openspec context-store ls [--json]
```

### `openspec context-store doctor`

Check local context-store registration, metadata, and Git presence.

```bash
openspec context-store doctor [id] [--json]
```

Doctor is diagnostic-only; it reports missing roots, metadata mismatches, and invalid local registry state without modifying the store.

### `openspec initiative create`

Create an initiative in a context store.

```bash
openspec initiative create <id> --title <title> --summary <summary> [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--store <id>` | Context store id from the local registry |
| `--store-path <path>` | Existing local context store root |
| `--title <title>` | Initiative title |
| `--summary <summary>` | Initiative summary |
| `--json` | Output JSON |

### `openspec initiative list`

List initiatives. Without a selector, this searches all registered context stores and reports partial-read warnings in `status`.

```bash
openspec initiative list [options]
openspec initiative ls [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--store <id>` | List one registered context store |
| `--store-path <path>` | List one existing local context store root |
| `--json` | Output JSON |

### `openspec initiative show`

Resolve an initiative and print its canonical location.

```bash
openspec initiative show <id> [options]
openspec initiative show <store>/<id> [options]
```

Without `--store`, OpenSpec searches registered context stores. If the same initiative id exists in multiple stores, pass `--store <id>` or use the `<store>/<id>` form.

---

Expand Down Expand Up @@ -578,6 +703,53 @@ openspec archive update-ci-config --skip-specs

These commands support the artifact-driven OPSX workflow. They're useful for both humans checking progress and agents determining next steps.

### `openspec new change`

Create a repo-local change directory and optional checked-in metadata.

```bash
openspec new change <name> [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--description <text>` | Description to add to `README.md` |
| `--goal <text>` | Workspace product goal to store with the change |
| `--areas <names>` | Comma-separated affected workspace link names |
| `--initiative <id>` | Link the repo-local change to an initiative |
| `--store <id>` | Context store id for `--initiative` |
| `--store-path <path>` | Existing local context store root for `--initiative` |
| `--schema <name>` | Workflow schema to use |
| `--json` | Output JSON |

Examples:

```bash
openspec new change add-billing-api --initiative billing-launch --store platform
openspec new change add-billing-api --initiative platform/billing-launch --json
```

### `openspec set change`

Update checked-in repo-local change metadata without recreating the change.

```bash
openspec set change <name> [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--initiative <id>` | Link the repo-local change to an initiative |
| `--store <id>` | Context store id for `--initiative` |
| `--store-path <path>` | Existing local context store root for `--initiative` |
| `--json` | Output JSON |

`set change --initiative` is idempotent when the requested link already exists and refuses to replace a different existing initiative link.

### `openspec status`

Display artifact completion status for a change.
Expand Down Expand Up @@ -993,9 +1165,9 @@ openspec config profile core
- Keep current settings (exit)

If you keep current settings, no changes are written and no update prompt is shown.
If there are no config changes but the current project or workspace files are out of sync with your global profile/delivery, OpenSpec will show a warning and suggest `openspec update` for repo-local projects or `openspec workspace update` for workspace-local skills.
If there are no config changes but the current project or workspace files are out of sync with your global profile/delivery, OpenSpec will show a warning and suggest `openspec update` for repo-local projects or `openspec workspace update` for workspace-local guidance and skills.
Pressing `Ctrl+C` also cancels the flow cleanly (no stack trace) and exits with code `130`.
In the workflow checklist, `[x]` means the workflow is selected in global config. To apply those selections to project files, run `openspec update` (or choose `Apply changes to this project now?` when prompted inside a project). From inside a workspace, use `openspec workspace update` to refresh workspace-local skills; this remains skills-only and does not generate workspace slash commands.
In the workflow checklist, `[x]` means the workflow is selected in global config. To apply those selections to project files, run `openspec update` (or choose `Apply changes to this project now?` when prompted inside a project). From inside a workspace, use `openspec workspace update` to refresh workspace-local guidance and skills; this remains skills-only for generated agent workflow files and does not generate workspace slash commands.

**Interactive examples:**

Expand Down
Loading
Loading