### Install and Run Development Server

Source: https://github.com/fission-ai/openspec/blob/main/website/README.md

Navigate to the website directory, install dependencies, and start the local development server for hot-reloading.

```bash
cd website
pnpm install
pnpm run dev      # http://localhost:3000
```

--------------------------------

### Human Output for context-store setup

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/slices/store-root-parity/plan.md

Example of the expected human-readable output after successfully setting up a context store.

```text
Context store ready

ID: team-context
Location: /Users/me/src/team-context
OpenSpec root: ready
Registry: registered

Next: use normal OpenSpec specs and changes in this store.
```

--------------------------------

### OpenSpec Onboarding Interactive Example

Source: https://github.com/fission-ai/openspec/blob/main/docs/commands.md

This example illustrates the interactive dialogue during the `/opsx:onboard` process, showing user input and AI responses during the guided workflow.

```text
You: /opsx:onboard

AI:  Welcome to OpenSpec!

     I'll walk you through the complete workflow using your actual codebase.
     We'll find something small to improve, create a proper change for it,
     implement it, and archive it.

     Let me scan your codebase for opportunities...

     [Analyzes codebase]

     I found a few things we could work on:
     1. Add input validation to the contact form
     2. Improve error messages in the auth flow
     3. Add loading states to async buttons

     Which interests you? (or suggest something else)
```

--------------------------------

### Context Store Setup Success Output

Source: https://github.com/fission-ai/openspec/blob/main/openspec/initiatives/context-store-and-initiatives/work-items/06-add-minimal-context-store-ux/plan.md

Example output after successfully setting up a new context store. It confirms the ID, location, metadata file, registry location, and Git initialization status.

```text
Context store setup complete

ID: team-context
Location: /Users/me/work/team-context
Metadata: /Users/me/work/team-context/.openspec-store/store.yaml
Registry: /Users/me/.local/share/openspec/context-stores/registry.yaml
Git: initialized
```

--------------------------------

### Interactive Setup Prompts

Source: https://github.com/fission-ai/openspec/blob/main/openspec/initiatives/context-store-and-initiatives/work-items/12-context-store-first-run-and-cleanup-ux/plan.md

Illustrates the expected prompts for an interactive context store setup. These prompts guide the user through providing necessary information for store creation.

```text
Store id
Target path, defaulting to the managed OpenSpec context-store location
Whether to initialize Git
```

--------------------------------

### First-Run UX Sketch Example

Source: https://github.com/fission-ai/openspec/blob/main/openspec/initiatives/context-store-and-initiatives/work-items/10-let-workspaces-open-initiatives/plan.md

This sketch illustrates a potential human interactive flow for creating a local workspace view. The initial implementation may use explicit flags and structured errors instead of a full guided setup wizard.

```text
Found initiative: platform/billing-launch
No local workspace view exists for this runtime.

Create a local view?
> Open context only
  Link existing local repos/folders
  Cancel
```

--------------------------------

### Start Guided Tour with Onboard Command

Source: https://github.com/fission-ai/openspec/blob/main/docs/existing-projects.md

Begin a guided tour of the AI development loop on your own code using the `/opsx:onboard` command after enabling expanded workflows.

```text
/opsx:onboard
```

--------------------------------

### Install Dependencies

Source: https://github.com/fission-ai/openspec/blob/main/README.md

Run this command to install all necessary project dependencies.

```bash
pnpm install
```

--------------------------------

### Day-Zero Setup Commands

Source: https://github.com/fission-ai/openspec/blob/main/openspec/explorations/workspace-user-journeys.md

Commands for initializing OpenSpec in different repository environments.

```bash
cd repo
openspec init
open agent in repo
run /opsx:propose
```

```bash
cd monorepo
openspec init
optionally add scope markers for major owned areas
run openspec update
open agent in monorepo root
```

```bash
each repo independently runs openspec init
user creates a coordination workspace only when cross-repo work arises
user links repo IDs to local clones as needed
user opens the agent in the coordination workspace for planning
```

--------------------------------

### Install and Initialize OpenSpec

Source: https://github.com/fission-ai/openspec/blob/main/docs/README.md

Install OpenSpec globally using npm and then initialize it within your project directory. These are terminal-based commands.

```bash
npm install -g @fission-ai/openspec@latest
```

```bash
cd your-project && openspec init
```

--------------------------------

### Initialize OpenSpec in a Project

Source: https://github.com/fission-ai/openspec/blob/main/docs/installation.md

Starts the OpenSpec initialization process within your project directory.

```bash
cd your-project
openspec init
```

--------------------------------

### Example User Prompt for Initiative Linking

Source: https://github.com/fission-ai/openspec/blob/main/openspec/initiatives/context-store-and-initiatives/work-items/08-connect-repo-local-changes-to-initiatives/plan.md

This is an example of a user prompt that can be used to initiate the creation of a repo-local change linked to a specific initiative.

```text
Using initiative billing-launch, create a proposal for API work.
```

--------------------------------

### Artifact Instructions JSON Example

Source: https://github.com/fission-ai/openspec/blob/main/docs/opsx.md

Example JSON output from the 'openspec instructions' command, detailing the artifact template, its dependencies, and what artifacts it unlocks.

```json
{
  "template": "# Specification\n\n## ADDED Requirements...",
  "dependencies": [{"id": "proposal", "path": "...", "done": true}],
  "unlocks": ["tasks"]
}
```

--------------------------------

### Context Store Structure after Setup

Source: https://github.com/fission-ai/openspec/blob/main/openspec/initiatives/context-store-and-initiatives/work-items/15-context-store-project-roots-and-schema-led-initiatives/plan.md

Depicts the expected directory structure for a context store after its initial setup. It highlights the '.openspec-store' directory for configuration and the 'openspec/' directory for shared configurations and schemas.

```text
context-store/
  .openspec-store/
    store.yaml
  openspec/
    config.yaml
    schemas/
  initiatives/
```

--------------------------------

### Setup and List Stores

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/slices/store-rename-and-guidance/spec.md

Commands to set up a new team context store and list available stores.

```bash
openspec store setup team-context --path ~/src/team-context
openspec store list
openspec store doctor
```

--------------------------------

### Setup OpenSpec Store and Create New Change

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/capstone/release-readiness.md

These two commands demonstrate the complete new user journey for setting up an OpenSpec store and creating the first change. They are the initial steps for any new user.

```bash
openspec store setup team-plans --path ~/openspec/team-plans
```

```bash
openspec new change my-first-change --store team-plans
```

--------------------------------

### Decision Heuristic for Updating vs. Starting New

Source: https://github.com/fission-ai/openspec/blob/main/docs/opsx.md

A visual flowchart to guide decisions on whether to update an existing change or start a new one. It considers factors like intent, scope overlap, and completion of the original work.

```text
                        ┌─────────────────────────────────────┐
                        │     Is this the same work?          │
                        └──────────────┬──────────────────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
                    ▼                  ▼                  ▼
             Same intent?      >50% overlap?      Can original
             Same problem?     Same scope?        be "done" without
                    │                  │          these changes?
                    │                  │                  │
          ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
          │                 │  │             │   │               │
         YES               NO YES           NO  NO              YES
          │                 │  │             │   │               │
          ▼                 ▼  ▼             ▼   ▼               ▼
       UPDATE            NEW  UPDATE       NEW  UPDATE          NEW
```

--------------------------------

### Onboard to OpenSpec for Hands-on Learning

Source: https://github.com/fission-ai/openspec/blob/main/docs/examples.md

Use the '/opsx:onboard' command to learn the OpenSpec workflow hands-on by making a real, small improvement to your actual codebase. This process narrates every step and takes approximately 15 to 30 minutes.

```text
You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...
```

--------------------------------

### Multi-repo Structure with Dedicated Contracts Repo

Source: https://github.com/fission-ai/openspec/blob/main/openspec/explorations/workspace-architecture.md

An example of a multi-repo setup where shared specifications are housed in a dedicated 'contracts' repository, while individual services and clients manage their own specs locally.

```treeview
~/work/
├── billing-service/
│   └── openspec/specs/billing/
├── web-client/
│   └── openspec/specs/checkout/
├── ios-client/
│   └── openspec/specs/checkout/
└── contracts/                    # Dedicated repo for shared specs?
    └── openspec/specs/
        └── checkout-contract/
```

--------------------------------

### Setup Planning Store

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/capstone/journeys.md

Initializes a new standalone planning store for a project. This includes setting up specs, changes, configuration, and store metadata with its own Git history.

```bash
openspec store setup billing-app-planning
```

--------------------------------

### Exploratory Workflow Example Conversation

Source: https://github.com/fission-ai/openspec/blob/main/docs/workflows.md

Demonstrates an exploratory workflow conversation, starting with an exploration command, followed by AI analysis, user decision, and subsequent change creation and continuation.

```text
You: /opsx:explore

AI:  What would you like to explore?

You: I want to improve page load performance but I'm not sure
     where the bottlenecks are.

AI:  Let me help investigate...
     [Analyzes bundle sizes, identifies slow queries, reviews
     component render patterns]

     I found three main bottlenecks:
     1. Large unoptimized images
     2. Synchronous data fetching in ProductList
     3. Re-renders from context changes

     Which would you like to address first?

You: Let's tackle the data fetching issue.

You: /opsx:new optimize-product-list-fetching

AI:  Created change. Ready to create: proposal

You: /opsx:continue

AI:  Creating proposal based on our exploration...
     [Writes proposal incorporating investigation insights]

     Ready to create: specs, design
     Which would you like next?

You: /opsx:continue

AI:  Creating specs...
```

--------------------------------

### Verify OpenSpec Installation

Source: https://github.com/fission-ai/openspec/blob/main/docs/installation.md

Checks the installed version of OpenSpec to confirm successful installation.

```bash
openspec --version
```

--------------------------------

### Example User Flow with --store

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/roadmap.md

Demonstrates how to use the `--store` flag with various OpenSpec commands to target a specific registered repository.

```bash
openspec new change add-billing --store team-context
openspec status --store team-context
openspec instructions apply --store team-context
```

--------------------------------

### End-to-End Onboarding Flow

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/slices/store-canonical-remote/spec.md

This scenario demonstrates the end-to-end process of onboarding, starting from a fresh machine state. It involves executing printed clone and register commands from an app repository's reference, followed by a rerun of instructions.

```bash
openspec store register <home>/openspec/team-context --id team-context
```

--------------------------------

### Install and Verify OpenSpec CLI

Source: https://github.com/fission-ai/openspec/blob/main/docs/troubleshooting.md

Install the OpenSpec CLI globally and check its version. Ensure your shell can find the installed binary.

```bash
npm install -g @fission-ai/openspec@latest
openspec --version
```

--------------------------------

### Monorepo structure example

Source: https://github.com/fission-ai/openspec/blob/main/openspec/explorations/workspace-user-journeys.md

Example file layout for a monorepo project.

```text
platform/
  openspec/
  apps/web/
  services/api/
  packages/ui/
```

--------------------------------

### Build Project

Source: https://github.com/fission-ai/openspec/blob/main/README.md

Execute this command to build the project.

```bash
pnpm run build
```

--------------------------------

### OpenSpec Initial User Journey Example

Source: https://github.com/fission-ai/openspec/blob/main/openspec/changes/simplify-skill-installation/proposal.md

A timeline demonstrating a typical new user's first interaction with OpenSpec, highlighting the speed to reach an 'aha moment' with the 'propose' and 'apply' commands.

```text
0:00  $ openspec init
      ✓ Done. Run /opsx:propose "your idea"

0:15  /opsx:propose "add user authentication"

0:45  Agent creates proposal.md, design.md, tasks.md
      "Whoa, it planned the whole thing for me" ← AHA

1:00  /opsx:apply
```

--------------------------------

### Install OpenSpec to Nix profile

Source: https://github.com/fission-ai/openspec/blob/main/docs/installation.md

Installs OpenSpec to your Nix profile for system-wide availability.

```bash
nix profile install github:Fission-AI/OpenSpec
```

--------------------------------

### Install OpenSpec with yarn

Source: https://github.com/fission-ai/openspec/blob/main/docs/installation.md

Installs the latest version of OpenSpec globally using yarn.

```bash
yarn global add @fission-ai/openspec@latest
```

--------------------------------

### Install OpenSpec with pnpm

Source: https://github.com/fission-ai/openspec/blob/main/docs/installation.md

Installs the latest version of OpenSpec globally using pnpm.

```bash
pnpm add -g @fission-ai/openspec@latest
```

--------------------------------

### Initialize Git for Context Store Setup

Source: https://github.com/fission-ai/openspec/blob/main/openspec/initiatives/context-store-and-initiatives/work-items/11-manual-beta-reality-pass/notes.md

Use this command to set up a team context store and initialize it as a Git repository. This command creates the store in the default location if it doesn't exist.

```bash
openspec context-store setup team-context --init-git
```

--------------------------------

### Next Steps for Context Store

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/slices/store-lifecycle-proof/spec.md

Provides guidance on subsequent actions after setting up a context store, including running normal OpenSpec commands and sharing the store via Git.

```text
Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-context
To share this store, commit and push it like any Git repo.
```

--------------------------------

### Install OpenSpec with npm

Source: https://github.com/fission-ai/openspec/blob/main/docs/installation.md

Installs the latest version of OpenSpec globally using npm.

```bash
npm install -g @fission-ai/openspec@latest
```

--------------------------------

### Install Shell Completions

Source: https://github.com/fission-ai/openspec/blob/main/docs/cli.md

Installs shell completions for the OpenSpec CLI to improve command-line usability.

```bash
openspec completion install
```

--------------------------------

### Initialize OpenSpec Project Configuration

Source: https://github.com/fission-ai/openspec/blob/main/docs/customization.md

Run this command to interactively set up your openspec/config.yaml file. Alternatively, create the file manually.

```bash
openspec init
```

--------------------------------

### Initiative Metadata Example

Source: https://github.com/fission-ai/openspec/blob/main/openspec/initiatives/context-store-and-initiatives/work-items/09-add-initiative-resolve/plan.md

Example of how repo-local changes can reference initiatives through portable checked-in metadata.

```yaml
initiative:
  store: platform
  id: billing-launch
```

--------------------------------

### Define Install Scope Type

Source: https://github.com/fission-ai/openspec/blob/main/openspec/changes/add-global-install-scope/design.md

Defines the possible values for the install scope preference in the global configuration.

```typescript
type InstallScope = 'global' | 'project';
```

--------------------------------

### OpenSpec Initialization (Interactive)

Source: https://github.com/fission-ai/openspec/blob/main/openspec/changes/simplify-skill-installation/proposal.md

Demonstrates the interactive initialization process of OpenSpec, including tool detection and user confirmation. Defaults to 'core' profile and 'both' delivery.

```text
$ openspec init

Detected tools:
  [x] Claude Code
  [x] Cursor
  [ ] Windsurf

Press Enter to confirm, or Space to toggle

Setting up OpenSpec...
✓ Done

Start your first change:
  /opsx:propose "add dark mode"
```

--------------------------------

### OpenSpec Workspace Configuration Example

Source: https://github.com/fission-ai/openspec/blob/main/openspec/explorations/workspace-user-journeys.md

Example structure of OpenSpec workspace files within a shared coordination repository.

```yaml
initiatives/
  add-3ds/
    .openspec-workspace/
      workspace.yaml
      initiative.md
      links.yaml
      agents/
        claude.md
        codex.md
```

--------------------------------

### Project Configuration with Default Store

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/slices/declared-store-fallback/spec.md

Example of how to configure a project to use a specific store as its default planning context.

```yaml
# app-repo/openspec/config.yaml
store: team-context
```

--------------------------------

### CLI Help Output Example

Source: https://github.com/fission-ai/openspec/blob/main/openspec/work/simplify-context-and-workspace-model/slices/delete-legacy-command-groups/spec.md

Illustrates the help output of the OpenSpec CLI after legacy command groups have been removed. Shows the remaining available commands.

```text
$ openspec --help
  ... init, update, list, view, validate, show, archive, status,
  instructions, templates, schemas, new, store, completion ...
$ openspec workspace list
error: unknown command 'workspace'
$ openspec initiative list
error: unknown command 'initiative'
```

--------------------------------

### Install OpenSpec with bun

Source: https://github.com/fission-ai/openspec/blob/main/docs/installation.md

Installs the latest version of OpenSpec globally using bun. Requires Node.js 20.19.0 or higher.

```bash
bun add -g @fission-ai/openspec@latest
```

--------------------------------

### Agent Context File Example

Source: https://github.com/fission-ai/openspec/blob/main/openspec/explorations/workspace-user-journeys.md

Example of a claude.md file generated for coordination workspaces to provide deterministic context to the agent.

```markdown
You are working on initiative `add-3ds`.

Resolved roots:
- /Users/me/work/contracts
- /Users/me/work/web-client

Unresolved roots:
- github.com/Fission-AI/billing-service
- github.com/Fission-AI/ios-client

Ownership:
- contracts owns shared checkout contract
- web-client owns web checkout behavior

Rules:
- Canonical specs must be edited in owning roots
- Initiative-level notes live in this coordination workspace
- Cross-repo references are informational only
```