From c37253c48db60150ba0e022e8a8ef87840796ff2 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 22 Jun 2026 09:11:11 -0500 Subject: [PATCH 1/4] docs: comprehensive documentation overhaul (home, mental model, command location, FAQ, glossary, troubleshooting, recipes) Addresses #1228 (docs are fragmented and hard to discover). Additive, docs-only. The single sharpest gap from the issue thread was that nobody explains where slash commands run, hence the new "How Commands Work" page. New docs: - docs/README.md documentation home / index that maps every doc - docs/how-commands-work.md where /opsx:* (chat) vs openspec (terminal) run; "interactive mode" answered - docs/overview.md core concepts at a glance, one page - docs/faq.md consolidated common questions - docs/glossary.md every term in one place - docs/troubleshooting.md concrete fixes for concrete failures - docs/examples.md real changes start to finish (recipes) Small additive edits: - docs/getting-started.md "where do I type this?" callout + first-five-minutes + richer Next Steps - README.md Docs list points at the new home and key new pages Voice: warm, plain, bottom-line-up-front; no em-dashes in prose. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 8 +- docs/README.md | 97 +++++++++++++++++ docs/examples.md | 212 ++++++++++++++++++++++++++++++++++++++ docs/faq.md | 127 +++++++++++++++++++++++ docs/getting-started.md | 26 ++++- docs/glossary.md | 89 ++++++++++++++++ docs/how-commands-work.md | 154 +++++++++++++++++++++++++++ docs/overview.md | 87 ++++++++++++++++ docs/troubleshooting.md | 166 +++++++++++++++++++++++++++++ 9 files changed, 964 insertions(+), 2 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/examples.md create mode 100644 docs/faq.md create mode 100644 docs/glossary.md create mode 100644 docs/how-commands-work.md create mode 100644 docs/overview.md create mode 100644 docs/troubleshooting.md diff --git a/README.md b/README.md index dcf6586b4..158296a1d 100644 --- a/README.md +++ b/README.md @@ -105,14 +105,20 @@ If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/ ## Docs +**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`). + → **[Getting Started](docs/getting-started.md)**: first steps
+→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI
+→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page
+→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish
→ **[Workflows](docs/workflows.md)**: combos and patterns
→ **[Commands](docs/commands.md)**: slash commands & skills
→ **[CLI](docs/cli.md)**: terminal reference
→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths
→ **[Concepts](docs/concepts.md)**: how it all fits
→ **[Multi-Language](docs/multi-language.md)**: multi-language support
-→ **[Customization](docs/customization.md)**: make it yours +→ **[Customization](docs/customization.md)**: make it yours
+→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help ## Community schemas diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..1f4482034 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,97 @@ +# OpenSpec Documentation + +Welcome. This is the home for everything OpenSpec. + +OpenSpec helps you and your AI coding assistant **agree on what to build before any code is written.** You describe the change, the AI drafts a short spec and a task list, you both look at the same plan, and then the work happens. No more discovering halfway through that the AI built the wrong thing. + +If you read nothing else, read these two pages: + +1. [Getting Started](getting-started.md): install, initialize, and ship your first change. +2. [How Commands Work](how-commands-work.md): where you actually type `/opsx:propose` (hint: in your AI chat, not the terminal). This trips up almost everyone once. + +That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion. + +## Pick your path + +**I'm brand new.** Start with [Getting Started](getting-started.md), then skim the [Core Concepts at a Glance](overview.md). When something feels mysterious, the [FAQ](faq.md) and [Glossary](glossary.md) are nearby. + +**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place. + +**I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration. + +**I'm coming from the old workflow.** The [Migration Guide](migration-guide.md) explains what changed and why, and promises your existing work is safe. + +**I want to bend it to my team's process.** [Customization](customization.md) covers project config, custom schemas, and shared context. + +**Something's broken.** [Troubleshooting](troubleshooting.md) collects the failures people actually hit, with fixes. + +## The whole map + +### Start here + +| Doc | What it gives you | +|-----|-------------------| +| [Getting Started](getting-started.md) | Install, initialize, and run your first change end to end | +| [How Commands Work](how-commands-work.md) | Where slash commands run, what "interactive mode" means, terminal vs chat | +| [Core Concepts at a Glance](overview.md) | The whole mental model on one page: specs, changes, deltas, archive | +| [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, and how to verify it worked | + +### Use it day to day + +| Doc | What it gives you | +|-----|-------------------| +| [Workflows](workflows.md) | Common patterns and when to reach for each command | +| [Examples & Recipes](examples.md) | Full walkthroughs of real changes, copy-pasteable | +| [Commands](commands.md) | Reference for every `/opsx:*` slash command | +| [CLI](cli.md) | Reference for every `openspec` terminal command | + +### Understand it deeply + +| Doc | What it gives you | +|-----|-------------------| +| [Concepts](concepts.md) | The long-form explanation of specs, changes, artifacts, schemas, and archive | +| [OPSX Workflow](opsx.md) | Why the workflow is fluid instead of phase-locked, plus an architecture deep dive | +| [Glossary](glossary.md) | Every term defined in one place | + +### Make it yours + +| Doc | What it gives you | +|-----|-------------------| +| [Customization](customization.md) | Project config, custom schemas, shared context | +| [Multi-Language](multi-language.md) | Generate artifacts in languages other than English | +| [Supported Tools](supported-tools.md) | The 25+ AI tools OpenSpec integrates with, and where files land | + +### When you need help + +| Doc | What it gives you | +|-----|-------------------| +| [FAQ](faq.md) | Quick answers to the questions people ask most | +| [Troubleshooting](troubleshooting.md) | Concrete fixes for concrete failures | +| [Migration Guide](migration-guide.md) | Moving from the legacy workflow to OPSX | + +### Coordinate across repos (beta) + +| Doc | What it gives you | +|-----|-------------------| +| [Workspaces: User Guide](workspaces-beta/user-guide.md) | The smallest useful path for multi-repo coordination | +| [Workspaces: Agent Playbook](workspaces-beta/agent-cli-playbook.md) | How agents drive workspace and context-store commands | + +## The thirty-second version + +```text +1. Install npm install -g @fission-ai/openspec@latest +2. Initialize cd your-project && openspec init +3. Propose (in your AI chat) /opsx:propose add-dark-mode +4. Build (in your AI chat) /opsx:apply +5. Archive (in your AI chat) /opsx:archive +``` + +Steps 1 and 2 happen in your terminal. Steps 3 through 5 happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. + +## Where else to get help + +- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) for questions, ideas, and help. +- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) for bugs and feature requests. +- **`openspec feedback "your message"`** sends feedback straight from your terminal (it opens a GitHub issue). + +Found something in these docs that's wrong, stale, or confusing? That's a bug. Open an issue or a PR. Documentation improvements are some of the most valuable contributions you can make. diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 000000000..2d385e63f --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,212 @@ +# Examples & Recipes + +Real changes, start to finish. Each recipe shows the commands you'd type and what you'd see back, so you can match your situation to a pattern and copy it. These use the default **core** commands (`propose`, `explore`, `apply`, `sync`, `archive`); where the expanded set helps, it's noted. + +A reminder before you start: slash commands like `/opsx:propose` go in your **AI assistant's chat**, and `openspec` commands go in your **terminal**. If that's new, read [How Commands Work](how-commands-work.md) first. In the transcripts below, `You:` and `AI:` are the chat, and lines starting with `$` are the terminal. + +## Recipe 1: A small feature, the fast path + +**When to use it:** you know what you want, and it's a contained piece of work. This is the most common recipe. + +The whole thing is three commands. Propose, build, archive. + +```text +You: /opsx:propose add-logout-button + +AI: Created openspec/changes/add-logout-button/ + ✓ proposal.md — why and what + ✓ specs/ — the new requirement and its scenarios + ✓ design.md — technical approach + ✓ tasks.md — implementation checklist + Ready for implementation. Run /opsx:apply. +``` + +Now read the plan. Open the proposal and the delta spec. This is the moment OpenSpec is built for: catching a wrong assumption while it's still one paragraph, not 400 lines of code. Edit any artifact directly if something's off, then continue. + +```text +You: /opsx:apply + +AI: Working through tasks... + ✓ 1.1 Add logout button to header + ✓ 1.2 Clear session on click + ✓ 1.3 Add confirmation dialog + All tasks complete! + +You: /opsx:archive + +AI: Archiving add-logout-button... + ✓ Merged specs into openspec/specs/auth/spec.md + ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/ + Done. Ready for the next change. +``` + +That's it. The logout behavior is now part of your specs, and the change is filed away with its full context. + +## Recipe 2: A bug fix + +**When to use it:** something is broken and you want the fix recorded as a deliberate change to behavior, not a mystery commit. + +Bug fixes work exactly like features. The difference is in how you frame the proposal: describe the *correct* behavior, not just "fix the bug." + +```text +You: /opsx:propose fix-login-redirect-loop + +AI: Created openspec/changes/fix-login-redirect-loop/ + The proposal captures the current broken behavior and the + intended behavior. The delta spec MODIFIES the redirect + requirement so it's now precise and testable. + Ready for implementation. +``` + +Because the fix lands as a `MODIFIED` requirement with a fresh scenario, the next person (or the next AI session) sees not just that you fixed it, but what "correct" means. Then `/opsx:apply` and `/opsx:archive` as usual. + +Tip: for a fix, a good scenario is the regression test in prose. "GIVEN a logged-out user, WHEN they submit valid credentials, THEN they land on the dashboard and are not redirected again." Write that, and the implementation has a clear target. + +## Recipe 3: Exploring before you commit + +**When to use it:** you have a problem but not yet a plan. You're not sure what to build, or which approach is right. + +Start with `/opsx:explore`. It's a thinking partner with no structure and no artifacts created. It reads your codebase and helps you decide. + +```text +You: /opsx:explore + +AI: What would you like to explore? + +You: Page loads feel slow but I don't know where the time goes. + +AI: Let me look... I found three likely culprits: + 1. Large unoptimized images on the product list + 2. Synchronous data fetching that blocks render + 3. Re-renders triggered by context changes + Which should we tackle first? + +You: The data fetching one. + +You: /opsx:propose optimize-product-list-fetching + +AI: Created the change, with a proposal informed by what we just + found. Ready for implementation. +``` + +Exploration clarifies your thinking *before* you spend a change on it. When the insight crystallizes, propose, and the AI carries the context forward. + +## Recipe 4: Juggling two changes at once + +**When to use it:** you're mid-feature and an urgent fix jumps the queue. + +Changes are independent folders, so parallel work doesn't conflict. Start the fix, ship it, then return to the feature right where you left off. + +```text +You: I'm partway through add-dark-mode, but I need to fix a login bug now. + +You: /opsx:propose fix-login-redirect + +AI: Created openspec/changes/fix-login-redirect/. Ready for implementation. + +You: /opsx:apply + +AI: Implemented the fix. All tasks complete. + +You: /opsx:archive + +AI: ✓ Archived fix-login-redirect. + +You: Back to dark mode. + +You: /opsx:apply add-dark-mode + +AI: Resuming add-dark-mode. Picking up at task 2.3: Update Header... +``` + +Naming the change in `/opsx:apply add-dark-mode` is how you point the AI at a specific change when more than one is active. Because tasks track completion in `tasks.md`, the AI knows exactly where you stopped. + +When several changes are done at once, the expanded `/opsx:bulk-archive` files them together and resolves spec conflicts by checking what's actually implemented. See [Workflows](workflows.md#parallel-changes). + +## Recipe 5: A refactor with no behavior change + +**When to use it:** you're restructuring code, and externally visible behavior should stay identical. + +This is the interesting case, because a pure refactor has *nothing to add to your specs*. The behavior contract doesn't change; only the implementation does. So the work lives in the design and tasks, and the spec delta is empty or absent. + +```text +You: /opsx:propose refactor-payment-module + +AI: Created the change. The proposal states the goal (split the + payment module, no behavior change) and the design captures + the new structure. No spec changes, since behavior is identical. + Ready for implementation. +``` + +When you archive a change that doesn't touch specs, you can tell the terminal command to skip the spec step: + +```bash +$ openspec archive refactor-payment-module --skip-specs +``` + +The same flag is handy for tooling, CI, and docs-only changes. The principle: specs describe behavior, so if behavior didn't change, the spec shouldn't either. See [Concepts](concepts.md#what-a-spec-is-and-is-not). + +## Recipe 6: Step-by-step control (expanded commands) + +**When to use it:** a complex or risky change where you want to review each artifact before moving on. + +The core `/opsx:propose` drafts everything at once. When you'd rather go one step at a time, turn on the expanded commands: + +```bash +$ openspec config profile # select the expanded workflows +$ openspec update # apply them to this project +``` + +Now you can scaffold and build incrementally: + +```text +You: /opsx:new add-2fa + +AI: Created openspec/changes/add-2fa/. Ready to create: proposal. + +You: /opsx:continue + +AI: Created proposal.md. Now available: specs, design. + +You: /opsx:continue + +AI: Created specs/auth/spec.md. Now available: design. +``` + +Review each artifact as it lands, edit freely, and continue when you're happy. When you want the rest drafted in one go, `/opsx:ff` fast-forwards through the remaining planning artifacts. Before archiving, `/opsx:verify` checks that the implementation actually matches the specs. See [Workflows](workflows.md#opsxff-vs-opsxcontinue). + +## Recipe 7: Learning the whole loop hands-on + +**When to use it:** you've installed OpenSpec and want to *feel* the workflow on your own code, not a toy example. + +Turn on the expanded commands (see Recipe 6), then: + +```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... +``` + +`/opsx:onboard` finds a real (small) improvement, creates a change for it, implements it, and archives it, narrating every step. It takes 15 to 30 minutes and leaves you with a real change you can keep or discard. It's the gentlest way to learn. See [Commands](commands.md#opsxonboard). + +## Checking your work from the terminal + +Any time, from your terminal, you can inspect the state of things: + +```bash +$ openspec list # active changes +$ openspec show add-dark-mode # one change in detail +$ openspec validate add-dark-mode # check structure +$ openspec view # interactive dashboard +``` + +These are read-and-inspect tools. The proposing and building still happen through slash commands in chat. Full details in the [CLI reference](cli.md). + +## Where to go next + +- [Workflows](workflows.md): the patterns above, with decision guidance on when to use each +- [Commands](commands.md): every slash command in detail +- [Getting Started](getting-started.md): the canonical first-change walkthrough +- [Concepts](concepts.md): why the pieces fit together the way they do diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..ad457a5e1 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,127 @@ +# FAQ + +Quick answers to the questions people ask most. If your question is really a "something is broken" question, [Troubleshooting](troubleshooting.md) is the better page. If you want a term defined, see the [Glossary](glossary.md). + +## The basics + +### What is OpenSpec, in one sentence? + +A lightweight layer that gets you and your AI coding assistant to agree on what to build, in writing, before any code is written. + +### Why would I want that? + +Because AI assistants are confident even when they're wrong. When the requirements live only in a chat thread, the AI fills gaps with guesses, and you find out after the code exists. OpenSpec moves the agreement earlier, where mistakes are cheap to fix. See [Core Concepts at a Glance](overview.md) for the full case. + +### Do I have to use it for everything? + +No. Use it where agreement matters, which is most non-trivial work. For a one-character typo fix, the ceremony probably isn't worth it, and that's fine. + +### Is it tied to one AI tool? + +No. OpenSpec works with 25+ assistants, including Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, and more. The full list and per-tool details are in [Supported Tools](supported-tools.md). + +## Running commands + +### Where do I type `/opsx:propose`? + +In your AI assistant's chat, not your terminal. This is the single most common point of confusion, so it has its own page: [How Commands Work](how-commands-work.md). Short version: `openspec ...` runs in the terminal, `/opsx:...` runs in chat. + +### How do I "start interactive mode"? + +There isn't a separate mode to start. You open your AI assistant like normal and type a slash command into its chat. The slash command is how you "enter" OpenSpec. (The one genuinely interactive terminal feature is `openspec view`, a dashboard for browsing specs and changes.) Full explanation in [How Commands Work](how-commands-work.md). + +### I typed a slash command and nothing happened. Why? + +Most likely you typed it in the terminal instead of your AI chat, or the commands aren't installed yet. Run `openspec update` in your project, restart your assistant, then try typing `/opsx` in chat and watch for autocomplete. [Troubleshooting](troubleshooting.md#commands-dont-show-up) has the full checklist. + +### Why is the syntax `/opsx:propose` in one tool and `/opsx-propose` in another? + +Each AI tool surfaces custom commands a little differently. The intent is identical; only the punctuation changes. Type a slash in your chat and the autocomplete shows you the form your tool expects. The per-tool table is in [How Commands Work](how-commands-work.md#slash-command-syntax-by-tool). + +### What's the difference between a skill and a command? + +Both are files OpenSpec writes so your assistant can run the workflow. Skills (`.../skills/openspec-*/SKILL.md`) are the newer cross-tool standard; commands (`.../commands/opsx-*`) are the older per-tool slash files. You don't need to pick. You just type the slash command, and OpenSpec installs whichever your tool uses. + +## The workflow + +### What's the simplest possible flow? + +```text +/opsx:propose then /opsx:apply then /opsx:archive +``` + +Propose drafts the plan, apply builds it, archive files it away. That's the whole loop. + +### What's the difference between `/opsx:propose` and `/opsx:new`? + +`/opsx:propose` is the default one-step command: it creates the change and drafts all the planning artifacts at once. `/opsx:new` is part of the expanded command set and only scaffolds an empty change, leaving you to create artifacts one at a time with `/opsx:continue` (or all at once with `/opsx:ff`). Use propose unless you want step-by-step control. See [Commands](commands.md). + +### What are `core` and expanded profiles? + +A profile decides which slash commands get installed. **Core** (the default) gives you `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, and `onboard` for finer control. Switch with `openspec config profile`, then apply with `openspec update`. + +### Do I need to run `/opsx:sync`? + +Usually not. Sync merges a change's delta specs into your main specs, and `/opsx:archive` will offer to do it for you. Run sync manually only when you want the specs merged before archiving, for example on a long-running change. See [Commands](commands.md#opsxsync). + +### When should I update an existing change versus start a new one? + +Update when it's the same work, refined. Start fresh when the intent fundamentally changed or the scope exploded into different work. There's a decision flowchart and examples in [Workflows](workflows.md#when-to-update-vs-start-fresh). + +### Should I commit the `openspec/` folder to git? + +Yes. Your specs, active changes, and archive are part of your project's history. Commit them like any other source. The archive in particular becomes a durable record of why your system works the way it does. + +## Specs and changes + +### What goes in a spec versus a design? + +A spec describes observable behavior: what the system does, its inputs, outputs, and error conditions. A design describes how you'll build it: the technical approach, architecture decisions, file changes. If implementation could change without changing externally visible behavior, it belongs in the design, not the spec. [Concepts](concepts.md#what-a-spec-is-and-is-not) goes deeper. + +### What's a delta spec? + +A spec that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMOVED` sections, rather than restating the whole spec. It's how OpenSpec handles edits to existing systems cleanly. See [Concepts](concepts.md#delta-specs). + +### Where do archived changes go? + +To `openspec/changes/archive/YYYY-MM-DD-/`, with all artifacts preserved. Nothing is deleted; the change just moves out of your active list. + +## Configuration and customization + +### How do I tell the AI about my tech stack? + +Put it in `openspec/config.yaml` under `context:`. That text is injected into every planning request, so the AI always knows your stack and conventions. See [Customization](customization.md#project-configuration). + +### Can I generate specs in a language other than English? + +Yes. Add a language instruction to your config's `context:`. [Multi-Language](multi-language.md) has copy-paste snippets for several languages. + +### Can I change the workflow itself? + +Yes, with custom schemas. A schema defines which artifacts exist and how they depend on each other. Fork the default with `openspec schema fork spec-driven my-workflow`, then edit it. See [Customization](customization.md#custom-schemas). + +## Models, privacy, and upgrades + +### Which AI model should I use? + +OpenSpec works best with high-reasoning models. The README recommends models like Codex 5.5 and Opus 4.7 for both planning and implementation. Also keep your context window clean: clear it before implementation for best results. + +### Does OpenSpec collect data? + +It collects anonymous usage stats: command names and version only. No arguments, paths, content, or personal data, and it's off automatically in CI. Opt out with `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`. + +### How do I upgrade? + +Two steps. Upgrade the package (`npm install -g @fission-ai/openspec@latest`), then run `openspec update` inside each project to refresh the generated skills and commands. + +## Getting help + +### Where do I ask questions or report bugs? + +- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) +- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) +- **From your terminal:** `openspec feedback "your message"` opens a GitHub issue for you. + +### These docs are wrong or confusing. What do I do? + +Tell us, or fix it. Documentation PRs are welcome and valued. Open an issue or send a pull request. diff --git a/docs/getting-started.md b/docs/getting-started.md index 3d0e9e95b..590ca92e8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,27 @@ # Getting Started -This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start). +This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start) or the [Installation guide](installation.md). New to the whole docs set? The [documentation home](README.md) maps everything. + +> **Where do I type these commands?** Two places, and mixing them up is the most common early stumble. +> +> - `openspec ...` commands (like `openspec init`) run in your **terminal**. +> - `/opsx:...` commands (like `/opsx:propose`) run in your **AI assistant's chat**, the same box where you'd ask it to write code. +> +> There's no separate "interactive mode" to start. You just type the slash command in chat and your assistant takes it from there. Full explanation: [How Commands Work](how-commands-work.md). + +## Your First Five Minutes + +The whole loop, with each step labeled by where it happens: + +```text +TERMINAL $ npm install -g @fission-ai/openspec@latest +TERMINAL $ cd your-project && openspec init +AI CHAT /opsx:propose add-dark-mode (AI drafts the plan; you review it) +AI CHAT /opsx:apply (AI builds it) +AI CHAT /opsx:archive (specs updated, change filed away) +``` + +Two terminal steps to set up, then you live in chat. The rest of this guide unpacks what each step does and what you'll see. ## How It Works @@ -247,7 +268,10 @@ openspec view ## Next Steps +- [Core Concepts at a Glance](overview.md) - The whole mental model on one page +- [Examples & Recipes](examples.md) - Real changes, start to finish - [Workflows](workflows.md) - Common patterns and when to use each command - [Commands](commands.md) - Full reference for all slash commands - [Concepts](concepts.md) - Deeper understanding of specs, changes, and schemas - [Customization](customization.md) - Make OpenSpec work your way +- [FAQ](faq.md) and [Troubleshooting](troubleshooting.md) - When you get stuck diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 000000000..fd45a4e38 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,89 @@ +# Glossary + +Every OpenSpec term in one place, defined in plain language. Skim it once and the rest of the docs read faster. + +Terms are grouped by topic, then alphabetized within each group. + +## The core nouns + +**Spec.** A document describing how part of your system behaves. Specs live in `openspec/specs/`, are organized by domain, and are made of requirements and scenarios. The spec is the agreed-upon answer to "what does this software do?" See [Concepts](concepts.md#specs). + +**Source of truth.** The `openspec/specs/` directory as a whole. It holds the current, agreed-upon behavior of your system. Changes propose edits to it; archiving applies them. + +**Change.** One unit of work, packaged as a folder under `openspec/changes//`. A change holds everything about that work: its proposal, design, tasks, and the spec edits it introduces. One change, one feature or fix. + +**Artifact.** A document inside a change. The standard artifacts are the proposal, the delta specs, the design, and the tasks. They're created in dependency order and feed into each other. + +**Delta spec.** A spec inside a change that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMOVED` sections, rather than restating the entire spec. This is what lets OpenSpec edit existing systems cleanly. See [Concepts](concepts.md#delta-specs). + +**Domain.** A logical grouping for specs, like `auth/`, `payments/`, or `ui/`. You choose domains that match how you think about your system. + +## Inside a spec + +**Requirement.** A single behavior the system must have, usually written with an RFC 2119 keyword: "The system SHALL expire sessions after 30 minutes." Requirements state the *what*, not the *how*. + +**Scenario.** A concrete, testable example of a requirement in action, typically in Given/When/Then form. Scenarios make a requirement verifiable: you could write an automated test from one. + +**RFC 2119 keywords.** The words MUST, SHALL, SHOULD, and MAY, which carry standardized meaning about how strict a requirement is. MUST and SHALL are absolute. SHOULD is recommended with room for exceptions. MAY is optional. The name comes from the internet standards document that defined them. + +## The artifacts + +**Proposal (`proposal.md`).** The *why* and *what* of a change: its intent, scope, and high-level approach. The first artifact you create. + +**Design (`design.md`).** The *how*: technical approach, architecture decisions, and the files you expect to touch. Optional for simple changes. + +**Tasks (`tasks.md`).** The implementation checklist, with checkboxes. The AI works through it during `/opsx:apply` and checks items off as it goes. + +## The lifecycle + +**Archive.** The act of finishing a change. Its delta specs merge into the main specs, and the change folder moves to `openspec/changes/archive/YYYY-MM-DD-/`. After archiving, your specs describe the new reality. See [Concepts](concepts.md#archive). + +**Sync.** Merging a change's delta specs into the main specs *without* archiving the change. Usually automatic (archive offers to do it), but available on its own as `/opsx:sync` for long-running changes. See [Commands](commands.md#opsxsync). + +## Workflow and commands + +**OPSX.** The current standard OpenSpec workflow, built around fluid actions instead of rigid phases. Its slash commands all start with `/opsx:`. See [OPSX Workflow](opsx.md). + +**Slash command.** A command you type into your AI assistant's chat, like `/opsx:propose`. Slash commands drive the workflow. They are not terminal commands. See [How Commands Work](how-commands-work.md). + +**CLI.** The `openspec` program you run in your terminal. It sets up projects, lists and validates changes, opens the dashboard, and archives. The terminal half of OpenSpec. See [CLI](cli.md). + +**Skill.** A folder of instructions (`.../skills/openspec-*/SKILL.md`) that your AI assistant auto-detects and follows. Skills are the emerging cross-tool standard for delivering the OpenSpec workflow to your assistant. + +**Command file.** A per-tool slash command file (`.../commands/opsx-*`). The older delivery mechanism, still supported alongside skills. You rarely touch these directly. + +**Profile.** The set of slash commands installed in your project. **Core** (the default) is `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`. Change it with `openspec config profile`. + +**Delivery.** Whether OpenSpec installs skills, command files, or both for your tools. Configured globally and applied with `openspec update`. + +## Customization + +**Schema.** The definition of which artifacts a workflow has and how they depend on one another. The built-in default is `spec-driven` (proposal → specs → design → tasks). You can fork it or write your own. See [Customization](customization.md#custom-schemas). + +**Template.** A Markdown file inside a schema that shapes what the AI generates for a given artifact. Editing a template changes the AI's output immediately, with no rebuild. + +**Project config (`openspec/config.yaml`).** Per-project settings: the default schema, the `context:` injected into every planning request, and per-artifact `rules:`. The easiest way to teach OpenSpec about your stack and conventions. See [Customization](customization.md#project-configuration). + +**Context injection.** Putting project background in `config.yaml`'s `context:` field so it's automatically added to every artifact the AI generates. More reliable than hoping the AI reads a separate file. + +**Dependency graph.** The directed graph formed by artifact `requires:` relationships. It's a DAG (directed acyclic graph: arrows only point forward, never in a loop), and OpenSpec uses it to know what you can create next. + +**Enablers, not gates.** The principle that artifact dependencies show what becomes *possible* next, not what's *required* next. You can revisit and edit any artifact at any time. See [Core Concepts at a Glance](overview.md#enablers-not-gates). + +## Coordination across repos (beta) + +These terms apply only if you're using OpenSpec's multi-repo workspace features, which are in beta. Most users can ignore them. See the [Workspaces User Guide](workspaces-beta/user-guide.md). + +**Workspace.** A machine-local view that ties together several linked repos or folders so you can coordinate work that spans them. It is not a repo and doesn't hold specs itself. + +**Link.** A stable name (like `api` or `web`) that a workspace maps to a local repo or folder path. + +**Context store.** A durable, usually Git-backed folder that holds shared context across repos. Registered locally so OpenSpec can find it. + +**Initiative.** Shared coordination context that lives inside a context store. Repo-local changes can link to an initiative without copying the shared plan into every repo. + +## See also + +- [Core Concepts at a Glance](overview.md): the five ideas, on one page +- [Concepts](concepts.md): the long-form explanation +- [How Commands Work](how-commands-work.md): slash commands versus the CLI diff --git a/docs/how-commands-work.md b/docs/how-commands-work.md new file mode 100644 index 000000000..45824bd2a --- /dev/null +++ b/docs/how-commands-work.md @@ -0,0 +1,154 @@ +# How Commands Work + +**The one thing to know: OpenSpec has two kinds of commands, and they run in two different places.** + +- `openspec ...` commands run in your **terminal**. (Example: `openspec init`.) +- `/opsx:...` commands run in your **AI assistant's chat**. (Example: `/opsx:propose`.) + +If you ever type `/opsx:propose` into your terminal and nothing happens, this page is why. You are talking to the wrong half of OpenSpec. Slash commands are not terminal commands. They are instructions you give to your AI coding assistant, in the same chat box where you'd normally type "add a login form." + +That single distinction is the most common stumbling block for new users, so let's make it crystal clear. + +## The two halves + +OpenSpec is one project wearing two hats. + +**The CLI (terminal half).** A program named `openspec` that you install and run from your shell. It sets up your project, lists and validates changes, shows a dashboard, and archives finished work. You type these into iTerm, the VS Code terminal, PowerShell, anywhere you'd run `git` or `npm`. + +```bash +openspec init # set up OpenSpec in this project +openspec list # see active changes +openspec view # open the interactive dashboard +``` + +**The slash commands (chat half).** Short commands like `/opsx:propose` and `/opsx:apply` that you type into your AI assistant. These tell the AI to follow the OpenSpec workflow: draft a proposal, write specs, build from the task list, archive when done. You type these into Claude Code, Cursor, Windsurf, Copilot, or whichever assistant you use. + +```text +/opsx:propose add-dark-mode (typed in your AI chat) +/opsx:apply (typed in your AI chat) +/opsx:archive (typed in your AI chat) +``` + +Here's the mental model in one picture: + +```text + YOUR TERMINAL YOUR AI ASSISTANT'S CHAT + ┌──────────────────────┐ ┌──────────────────────────────┐ + │ $ openspec init │ installs │ /opsx:propose add-dark-mode │ + │ $ openspec list │ ──────────► │ /opsx:apply │ + │ $ openspec view │ commands │ /opsx:archive │ + └──────────────────────┘ & skills └──────────────────────────────┘ + run openspec here run /opsx:* here +``` + +Notice the arrow. Running `openspec init` in your terminal is what *installs* the slash commands into your AI tool. The terminal half sets up the chat half. After that, day-to-day driving mostly happens in chat. + +## "How do I start interactive mode?" + +**There is no separate interactive mode to start.** This question comes up a lot, so it deserves a plain answer. + +You don't enter a special OpenSpec mode. You just open your AI coding assistant like you always do, and type a slash command into the chat. The slash command *is* how you "enter" OpenSpec. Your assistant recognizes it, loads the matching OpenSpec skill, and starts following the workflow. + +So the real instructions are: + +1. Open your AI coding assistant (Claude Code, Cursor, Windsurf, and so on) in your project. +2. Type `/opsx:propose` in its chat, the same place you type any other request. +3. Watch the autocomplete: if OpenSpec is installed, you'll see `/opsx:propose`, `/opsx:apply`, and friends appear as you type the slash. + +That's it. No mode to toggle, no daemon to launch, no separate window. + +One thing that *is* genuinely interactive lives in the terminal: `openspec view`. It opens a dashboard for browsing your specs and changes. But that's a viewer, not the thing you propose and build with. The building happens through slash commands in chat. + +## Why this split exists + +It's worth understanding, because it explains why OpenSpec works with 25+ different AI tools. + +The CLI is the **engine**. It knows the rules: what a change folder looks like, which artifacts depend on which, how to merge a delta spec into your source of truth. It's the same everywhere. + +The slash commands are the **steering wheel**, and every AI tool has a slightly different one. Claude Code calls them commands. Cursor and Windsurf have their own formats. Some tools call them skills. When you run `openspec init`, OpenSpec generates the right kind of file for each tool you selected, so the same `/opsx:propose` intent works no matter which assistant you prefer. + +The strength of this design: you learn the workflow once and carry it across tools. The tradeoff: the exact syntax of a command can differ slightly between tools, which is the next section. + +## Slash command syntax by tool + +The intent is identical everywhere. The punctuation differs. Use the form that matches your assistant. + +| Tool | How you type it | +|------|-----------------| +| Claude Code | `/opsx:propose`, `/opsx:apply` | +| Cursor | `/opsx-propose`, `/opsx-apply` | +| Windsurf | `/opsx-propose`, `/opsx-apply` | +| GitHub Copilot (IDE) | `/opsx-propose`, `/opsx-apply` | +| Kimi CLI | skill-style, e.g. `/skill:openspec-propose` | +| Trae | skill-style, e.g. `/openspec-propose` | + +Most tools use either the colon form (`/opsx:propose`) or the dash form (`/opsx-propose`). A few tools surface OpenSpec as named skills instead of slash commands; for those you invoke the skill by name. The full per-tool list, including exactly which files get written where, lives in [Supported Tools](supported-tools.md). + +When in doubt, type a slash in your AI chat and look at the autocomplete. Your tool will show you the form it expects. + +## How the commands got there: skills and commands + +When you run `openspec init` (or `openspec update`), OpenSpec writes small files into your project so your AI tool can find the workflow. Depending on your tool and settings, these are **skills**, **commands**, or both. + +- **Skills** live in places like `.claude/skills/openspec-*/SKILL.md`. They're the emerging cross-tool standard: a folder of instructions your assistant auto-detects. +- **Commands** live in places like `.claude/commands/opsx/.md`. They're the older per-tool slash command files. + +You don't have to care which one your tool uses. You just type the slash command and it works. But knowing these files exist helps when something goes wrong: if your commands vanish, it usually means these files are missing or stale, and `openspec update` regenerates them. + +See [Supported Tools](supported-tools.md) for the exact paths per tool, and [Migration Guide](migration-guide.md) for how skills replaced the older command-only approach. + +## Confirming it's installed + +Quick checks, fastest first: + +1. **Type a slash in your AI chat.** Start typing `/opsx` and watch for autocomplete suggestions. If they appear, you're set. +2. **Look for the files.** For Claude Code, check that `.claude/skills/` contains `openspec-*` folders. Other tools use their own directories ([Supported Tools](supported-tools.md) lists them). +3. **Re-run setup.** From your project root, run `openspec update`. This regenerates the skill and command files for whatever tools you configured. +4. **Restart your assistant.** Many tools scan for skills and commands at startup, so a fresh window can be the missing step. + +## Which commands do I even have? + +By default, OpenSpec installs the **core** set of slash commands: + +- `/opsx:propose`: create a change and draft all its planning artifacts in one step +- `/opsx:explore`: think through an idea before committing to a change +- `/opsx:apply`: build the change by working through its task list +- `/opsx:sync`: merge a change's spec updates into your main specs (usually automatic) +- `/opsx:archive`: finish a change and file it away + +There's also an **expanded** set for people who want finer control (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`). You turn it on with `openspec config profile`, then apply it with `openspec update`. + +New to all of this? `/opsx:onboard` (in the expanded set) walks you through a complete change on your own codebase, narrating each step. It's the friendliest possible introduction. + +For what each command does in detail, see [Commands](commands.md). For when to reach for which, see [Workflows](workflows.md). + +## A clean first run + +Putting it together, here is the whole sequence with each step labeled by where it happens. + +```text +TERMINAL $ npm install -g @fission-ai/openspec@latest +TERMINAL $ cd your-project +TERMINAL $ openspec init + (installs slash commands into your AI tool) + +AI CHAT /opsx:propose add-dark-mode + (AI drafts proposal, specs, design, tasks) + +AI CHAT /opsx:apply + (AI builds it, checking off tasks) + +AI CHAT /opsx:archive + (change is merged into your specs and filed away) +``` + +Two terminal steps to set up. Then you live in chat. That's the rhythm. + +## Related + +- [Getting Started](getting-started.md): the full first-change walkthrough +- [Commands](commands.md): every slash command in detail +- [CLI](cli.md): every terminal command in detail +- [Supported Tools](supported-tools.md): per-tool syntax and file locations +- [FAQ](faq.md): more quick answers +- [Troubleshooting](troubleshooting.md): fixes when commands don't show up diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 000000000..0eab5e7bf --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,87 @@ +# Core Concepts at a Glance + +**OpenSpec is a lightweight agreement layer between you and your AI.** You write down what a change should do, the AI drafts the details, you both look at the same plan, and only then does code get written. This page is the whole mental model on one screen. When you want the long version, [Concepts](concepts.md) has it. + +Here's the entire idea in five words: **agree first, then build confidently.** + +## The five ideas + +Everything in OpenSpec is built from five concepts. Learn these and the rest is detail. + +**1. Specs are the truth.** A spec describes how your system behaves *right now*. It lives in `openspec/specs/`, organized by domain (`auth/`, `payments/`, `ui/`). Specs are made of requirements ("the system SHALL expire sessions after 30 minutes") and scenarios (concrete given/when/then examples). Think of specs as the single agreed-upon answer to "what does this software do?" + +**2. A change is one unit of work.** When you want to add, modify, or remove behavior, you create a change: a folder in `openspec/changes/` holding everything about that work in one place. A proposal, a design, a task list, and the spec edits. One change, one folder, one feature. + +**3. Delta specs describe what's changing, not the whole world.** Inside a change, you don't rewrite the entire spec. You write a small delta: `ADDED` this requirement, `MODIFIED` that one, `REMOVED` this other one. This is the trick that makes OpenSpec good at editing existing systems, not just green-field ones. You describe the diff, not the destination. + +**4. Artifacts build on each other.** A change contains a few documents, created in a natural order, each feeding the next: + +```text +proposal ──► specs ──► design ──► tasks ──► implement + why what how steps do it +``` + +You can revisit any of them at any time. They're enablers, not gates. (More on that below.) + +**5. Archiving folds the change back into the truth.** When the work is done, you archive the change. Its delta specs merge into your main specs, and the change folder moves to `changes/archive/` with a date stamp. Now your specs describe the new reality, and you're ready for the next change. The cycle closes. + +## The picture + +```text +┌─────────────────────────────────────────────────────────────────┐ +│ openspec/ │ +│ │ +│ ┌──────────────────┐ ┌──────────────────────────┐ │ +│ │ specs/ │ │ changes/ │ │ +│ │ │ ◄───── │ │ │ +│ │ source of truth │ merge │ one folder per change │ │ +│ │ how things work │ on │ proposal · design · │ │ +│ │ today │ archive │ tasks · delta specs │ │ +│ └──────────────────┘ └──────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +Two folders. `specs/` is what's true. `changes/` is what you're proposing. Archiving moves a proposal into truth. + +## The loop you'll actually run + +In the default setup, your day looks like this. The first command drafts the plan; you read it; the second builds it; the third files it away. + +```text +/opsx:propose add-dark-mode → AI drafts proposal, specs, design, tasks + (you read and adjust the plan) +/opsx:apply → AI builds it, checking off tasks +/opsx:archive → specs updated, change archived +``` + +Those are slash commands, typed in your AI assistant's chat. Setup (`openspec init`) happens in your terminal. If that split is new to you, read [How Commands Work](how-commands-work.md) first; it's the most common point of confusion. + +## "Enablers, not gates" + +This phrase shows up everywhere in OpenSpec, so here's what it means in plain terms. + +Old-school spec processes are waterfalls: finish planning, *then* you're allowed to implement, and going back is painful. OpenSpec refuses that. The order `proposal → specs → design → tasks` shows what becomes *possible* next, not what you're *forced* to do next. + +Discover during implementation that the design was wrong? Edit `design.md` and keep going. Realize the scope should shrink? Update the proposal. Nothing locks. The dependencies exist only so the AI has the context it needs (you can't write good tasks without specs to base them on), not to box you in. + +The strength here is honesty: real work is messy and iterative, and OpenSpec lets it be. The tradeoff is discipline: because nothing forces you forward, it's on you to keep a change focused rather than letting it sprawl. The [Workflows](workflows.md) guide has good habits for that. + +## Why this is worth the small overhead + +Plain truth: OpenSpec adds a step. You write a short plan before building. So what do you get for it? + +- **You catch wrong turns before they cost you.** Fixing a misunderstanding in a one-paragraph proposal is free. Fixing it after the AI wrote 400 lines is not. +- **The plan and the code stay in the same repo.** Six months later, the spec tells you (and the next AI session) why the system works the way it does. +- **Changes are reviewable.** A change folder is a tidy package: read the proposal, skim the deltas, check the tasks. No archaeology through chat history. +- **It fits existing codebases.** Deltas mean you can specify a change to a 50,000-line app without first documenting the whole thing. + +And the honest tradeoff: for a truly trivial one-line fix, the ceremony may not pay off, and that's fine. OpenSpec is designed to be lightweight, but it isn't free. Use it where agreement matters, which turns out to be most of the time once you're working with an AI that will confidently build whatever you vaguely asked for. + +## Where to go next + +- New here? [Getting Started](getting-started.md) walks the first change in full. +- Confused about where commands run? [How Commands Work](how-commands-work.md). +- Want the deep version of everything above? [Concepts](concepts.md). +- Learn by example? [Examples & Recipes](examples.md). +- Need a term defined? [Glossary](glossary.md). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 000000000..07b5bb725 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,166 @@ +# Troubleshooting + +Concrete fixes for concrete problems. Each entry names a symptom, explains the likely cause in a sentence, and gives you the fix. If you don't see your issue here, the [FAQ](faq.md) may help, and the [Discord](https://discord.gg/YctCnvvshC) definitely will. + +## Installation and setup + +### `openspec: command not found` + +The CLI isn't installed, or your shell can't find it. Install it globally and check: + +```bash +npm install -g @fission-ai/openspec@latest +openspec --version +``` + +If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm bin -g` to see where global binaries live, and make sure that path is in your shell profile. + +### "Requires Node.js 20.19.0 or higher" + +OpenSpec runs on Node 20.19.0+. Check your version and upgrade if needed: + +```bash +node --version +``` + +If you use bun to install OpenSpec, note that OpenSpec still *runs* on Node, so you need Node 20.19.0+ available on your `PATH` regardless. See [Installation](installation.md). + +### `openspec init` didn't configure my AI tool + +Init asks which tools to set up. If you skipped your tool or want to add another, just run it again, or use the non-interactive form: + +```bash +openspec init --tools claude,cursor +``` + +The full list of tool IDs is in [Supported Tools](supported-tools.md). Use `--tools all` for everything, `--tools none` to skip tool setup. + +## Commands don't show up + +If `/opsx:propose` (or your tool's equivalent) doesn't appear or doesn't do anything, work down this list. They're ordered fastest-to-check first. + +1. **You may be in the wrong place.** Slash commands go in your AI assistant's chat, not your terminal. If you typed `/opsx:propose` into your shell, that's the issue. See [How Commands Work](how-commands-work.md). + +2. **Regenerate the files.** From your project root: + + ```bash + openspec update + ``` + + This rewrites the skill and command files for every tool you've configured. + +3. **Restart your assistant.** Most tools scan for skills and commands at startup. A fresh window often does it. + +4. **Confirm the files exist.** For Claude Code, check that `.claude/skills/` contains `openspec-*` folders. Other tools use their own directories, all listed in [Supported Tools](supported-tools.md). + +5. **Check you initialized this project.** Skills are written per project. If you cloned a repo or switched folders, run `openspec init` (or `openspec update`) there. + +6. **Confirm your tool supports command files.** A few tools (Kimi CLI, Trae, ForgeCode, Mistral Vibe) don't get generated `opsx-*` command files; they use skill-based invocations instead. The forms differ per tool: see [Supported Tools](supported-tools.md) and [How Commands Work](how-commands-work.md#slash-command-syntax-by-tool). + +## Working with changes + +### "Change not found" + +The command couldn't tell which change you meant. Name it explicitly, or check what exists: + +```bash +openspec list # see active changes +/opsx:apply add-dark-mode # name the change in chat +``` + +Also confirm you're in the right project directory. + +### "No artifacts ready" + +Every artifact is either already created or blocked waiting on a dependency. See what's blocking: + +```bash +openspec status --change +``` + +Then create the missing dependency first. Remember the order: proposal enables specs and design; specs and design together enable tasks. + +### `openspec validate` reports warnings or errors + +Validation checks your specs and changes for structural problems. Read the message: it names the file and the issue. + +```bash +openspec validate # validate one item +openspec validate --all # validate everything +openspec validate --all --strict # stricter checks, good for CI +``` + +Common causes are a missing required section (like a spec with no scenarios) or a malformed delta header. Fix the file and re-run. The [CLI reference](cli.md#openspec-validate) documents the output format. + +### The AI created incomplete or wrong artifacts + +The AI didn't have enough context. A few levers help: + +- Add project context in `openspec/config.yaml` so your stack and conventions are injected into every request. See [Customization](customization.md#project-configuration). +- Add per-artifact `rules:` for guidance that only applies to, say, specs. +- Give a more detailed description when you propose. +- Use the expanded `/opsx:continue` to create one artifact at a time and review each, instead of `/opsx:ff` doing them all at once. + +### Archive won't finish, or warns about incomplete tasks + +Archive won't *block* on incomplete tasks, but it warns you, because archiving usually means the work is done. If tasks remain on purpose (you're filing a partial change), proceed. Otherwise finish the tasks first. Archive will also offer to sync your delta specs into the main specs if you haven't synced yet; say yes unless you have a reason not to. + +## Configuration + +### My `config.yaml` isn't being applied + +Three usual suspects: + +1. **Wrong filename.** It must be `openspec/config.yaml`, not `.yml`. +2. **Invalid YAML.** Run it through any YAML validator; the CLI also reports syntax errors with line numbers. +3. **You expected a restart.** You don't need one. Config changes take effect immediately. + +### "Unknown artifact ID in rules: X" + +A key under `rules:` doesn't match any artifact in your schema. For the default `spec-driven` schema the valid IDs are `proposal`, `specs`, `design`, `tasks`. To see the IDs for any schema: + +```bash +openspec schemas --json +``` + +### "Context too large" + +The `context:` field is capped at 50KB, on purpose, because it's injected into every request. Summarize it, or link out to longer docs instead of pasting them. Lean context also produces better, faster results. + +### "Schema not found" + +The schema name you referenced doesn't exist. List what's available and check spelling: + +```bash +openspec schemas # list available schemas +openspec schema which # see where a schema resolves from +openspec schema init # create a custom one +``` + +See [Customization](customization.md#custom-schemas). + +## Migration from the legacy workflow + +### "Legacy files detected in non-interactive mode" + +You're in CI or a non-interactive shell, and OpenSpec found old files to clean up but can't prompt you. Approve automatically: + +```bash +openspec init --force +``` + +### Commands didn't appear after migrating + +Restart your IDE. Skills are detected at startup. If they still don't appear, run `openspec update` and check the file locations in [Supported Tools](supported-tools.md). + +### My old `project.md` wasn't migrated + +That's intentional. OpenSpec never deletes `project.md` automatically because it may hold context you wrote. Move the useful parts into `config.yaml`'s `context:` section, then delete it yourself. The [Migration Guide](migration-guide.md#migrating-projectmd-to-configyaml) walks through this, including a prompt you can hand to your AI to do the distilling. + +## Still stuck? + +- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) +- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) +- **From your terminal:** `openspec feedback "what went wrong"` opens an issue for you. + +When you report a problem, include your OpenSpec version (`openspec --version`), your Node version (`node --version`), your AI tool, and the exact command and output. It makes help much faster. From ec0a78b107b80246daa34e52c4d15f389b9e973f Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 22 Jun 2026 09:25:11 -0500 Subject: [PATCH 2/4] docs: make /opsx:explore front and center, plus general polish Per maintainer feedback (Tabish): "the docs in general need some work, alongside making the explore option a lot more front and center." explore ships in the default core profile but every doc led with propose and treated explore as a footnote for "unclear requirements." This reframes the canonical loop as explore -> propose -> apply -> archive and gives explore real prominence. - docs/explore.md (new): dedicated "Explore First" guide. When to use it, what it does/doesn't, a full transcript, handoff to propose, tradeoffs. - getting-started.md: explore added to the flow and first-five-minutes, with a featured callout and Next Steps entry. - overview.md: explore featured in the loop and next-links. - docs/README.md: explore in the opening, pick-your-path, 30-second version, and the doc map. - how-commands-work.md: explore leads the command list with a "good rhythm" note and an optional step in the clean-first-run example. - workflows.md: new first-class "Start by exploring" pattern in the default section (was buried under expanded mode); quick-reference row strengthened. - commands.md / faq.md / glossary.md: explore featured as the place to start. - examples.md: top callout pointing at the explore recipe. - README.md: explore opens the "See it in action" demo and Quick Start, and is added to the Docs list. Docs-only and additive. No em-dashes in prose; links verified. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 16 ++++- docs/README.md | 14 +++-- docs/commands.md | 2 + docs/examples.md | 3 + docs/explore.md | 121 ++++++++++++++++++++++++++++++++++++++ docs/faq.md | 8 ++- docs/getting-started.md | 9 ++- docs/glossary.md | 2 + docs/how-commands-work.md | 7 ++- docs/overview.md | 6 +- docs/workflows.md | 33 ++++++++++- 11 files changed, 207 insertions(+), 14 deletions(-) create mode 100644 docs/explore.md diff --git a/README.md b/README.md index 158296a1d..3dfd0e522 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,14 @@ Our philosophy: ## See it in action ```text +You: /opsx:explore +AI: What would you like to explore? +You: I want dark mode but I'm not sure how to do it cleanly. +AI: Let me look at your styling setup... + Cleanest path here: CSS variables + a small theme context, + with system-preference detection. No new dependencies. Scope it? +You: Yes, let's do it. + You: /opsx:propose add-dark-mode AI: Created openspec/changes/add-dark-mode/ ✓ proposal.md — why we're doing this, what's changing @@ -94,9 +102,12 @@ cd your-project openspec init ``` -Now tell your AI: `/opsx:propose ` +Now talk to your AI: + +- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md)) +- **Already know what you want?** Go straight to `/opsx:propose `. -If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`. +Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`. > [!NOTE] > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing. @@ -108,6 +119,7 @@ If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/ **Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`). → **[Getting Started](docs/getting-started.md)**: first steps
+→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit
→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI
→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page
→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish
diff --git a/docs/README.md b/docs/README.md index 1f4482034..92bf1daee 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,10 +11,14 @@ If you read nothing else, read these two pages: That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion. +> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any artifact or code exists. The [Explore First](explore.md) guide makes the case. + ## Pick your path **I'm brand new.** Start with [Getting Started](getting-started.md), then skim the [Core Concepts at a Glance](overview.md). When something feels mysterious, the [FAQ](faq.md) and [Glossary](glossary.md) are nearby. +**I have a problem but not a plan.** This is the common case, and it has a dedicated answer: [Explore First](explore.md). Use `/opsx:explore` to think it through with the AI before committing to anything. + **I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place. **I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration. @@ -32,6 +36,7 @@ That second one matters more than it looks. OpenSpec has two halves: a command l | Doc | What it gives you | |-----|-------------------| | [Getting Started](getting-started.md) | Install, initialize, and run your first change end to end | +| [Explore First](explore.md) | Use `/opsx:explore` to think through an idea before you commit | | [How Commands Work](how-commands-work.md) | Where slash commands run, what "interactive mode" means, terminal vs chat | | [Core Concepts at a Glance](overview.md) | The whole mental model on one page: specs, changes, deltas, archive | | [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, and how to verify it worked | @@ -81,12 +86,13 @@ That second one matters more than it looks. OpenSpec has two halves: a command l ```text 1. Install npm install -g @fission-ai/openspec@latest 2. Initialize cd your-project && openspec init -3. Propose (in your AI chat) /opsx:propose add-dark-mode -4. Build (in your AI chat) /opsx:apply -5. Archive (in your AI chat) /opsx:archive +3. Explore (in your AI chat) /opsx:explore ← optional, but a great habit +4. Propose (in your AI chat) /opsx:propose add-dark-mode +5. Build (in your AI chat) /opsx:apply +6. Archive (in your AI chat) /opsx:archive ``` -Steps 1 and 2 happen in your terminal. Steps 3 through 5 happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. +Steps 1 and 2 happen in your terminal. The rest happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. Step 3 is optional, but starting with `/opsx:explore` when you're unsure is the habit most worth forming. ## Where else to get help diff --git a/docs/commands.md b/docs/commands.md index 8b0d81839..5d52c056c 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -72,6 +72,8 @@ AI: Created openspec/changes/add-dark-mode/ ### `/opsx:explore` +> **Start here when you're unsure.** Explore is a no-stakes thinking partner: it reads your codebase, compares options, and sharpens a fuzzy idea into a concrete plan before any change exists. It ships in the default profile. For the full case and more examples, see the [Explore First](explore.md) guide. + Think through ideas, investigate problems, and clarify requirements before committing to a change. **Syntax:** diff --git a/docs/examples.md b/docs/examples.md index 2d385e63f..cedf85c37 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -4,6 +4,8 @@ Real changes, start to finish. Each recipe shows the commands you'd type and wha A reminder before you start: slash commands like `/opsx:propose` go in your **AI assistant's chat**, and `openspec` commands go in your **terminal**. If that's new, read [How Commands Work](how-commands-work.md) first. In the transcripts below, `You:` and `AI:` are the chat, and lines starting with `$` are the terminal. +> **Not sure what you're building yet?** Most of these recipes are sharper if you start with `/opsx:explore` to think it through first. [Recipe 3](#recipe-3-exploring-before-you-commit) shows it in action, and the [Explore First](explore.md) guide makes the full case. + ## Recipe 1: A small feature, the fast path **When to use it:** you know what you want, and it's a contained piece of work. This is the most common recipe. @@ -206,6 +208,7 @@ These are read-and-inspect tools. The proposing and building still happen throug ## Where to go next +- [Explore First](explore.md): the recommended way to start when you're unsure - [Workflows](workflows.md): the patterns above, with decision guidance on when to use each - [Commands](commands.md): every slash command in detail - [Getting Started](getting-started.md): the canonical first-change walkthrough diff --git a/docs/explore.md b/docs/explore.md new file mode 100644 index 000000000..6b9493f20 --- /dev/null +++ b/docs/explore.md @@ -0,0 +1,121 @@ +# Explore First + +**`/opsx:explore` is your thinking partner. Reach for it whenever you have a problem but not yet a plan.** It investigates your codebase, weighs options with you, and clarifies what you actually want, all before a single artifact or line of code is created. When the picture is clear, it hands off to `/opsx:propose`. + +If you take one habit from these docs, take this one: **when you're not sure, explore before you propose.** + +Here's why that matters. AI coding assistants are eager. Ask vaguely and they'll confidently build *something*, just maybe not the thing you needed. Explore is the cure. It's a no-stakes conversation where you and the AI figure out the right move together, so that by the time you propose, you're proposing the right thing. + +## When to explore + +Explore is the right first step more often than people expect. Use it when any of these is true: + +- You know the *problem* but not the *solution*. ("Pages feel slow." "Auth is a mess." "We keep getting duplicate orders.") +- You're choosing between approaches and want the tradeoffs laid out against your actual code. +- You're new to a codebase and need to understand how something works before you change it. +- The requirements are fuzzy and you want to sharpen them before committing. +- You suspect the work is bigger or smaller than it looks and want to scope it honestly. + +Skip explore only when you already know exactly what you want and how. In that case go straight to [`/opsx:propose`](commands.md#opsxpropose). + +## What it does (and doesn't) + +Explore is a **conversation**, not a generator. + +**It does:** +- Read and search your codebase to answer real questions. +- Compare options and name the tradeoffs of each. +- Draw diagrams to make a design legible. +- Help you narrow a vague idea into a concrete, buildable scope. +- Transition to `/opsx:propose` when you're ready. + +**It does not:** +- Create a change folder. +- Write any artifacts (no proposal, specs, design, or tasks). +- Write or modify code. + +That's the point. Exploring costs you nothing and commits you to nothing. You can explore three dead ends, learn something from each, and only then propose the path that survived. + +## It's already installed + +Good news: `/opsx:explore` ships in the default **core** profile, right alongside `propose`, `apply`, `sync`, and `archive`. You don't need to enable anything. If OpenSpec is set up in your project, explore is ready in your AI chat. (As with all `/opsx:*` commands, you type it in your assistant's chat, not the terminal. See [How Commands Work](how-commands-work.md).) + +## A full example + +Watch how a vague worry becomes a sharp, buildable change. + +```text +You: /opsx:explore + +AI: What would you like to explore? + +You: Our checkout sometimes creates duplicate orders. I don't know why + and I don't know how to fix it safely. + +AI: Let me dig into the checkout path... + [reads the order service, the payment webhook handler, and the + client submit logic] + + Here's what I found. There are two ways a duplicate can happen: + + 1. The client can submit twice (double-click, retry on slow network). + Nothing debounces it. + 2. The payment webhook can fire more than once, and the handler + creates an order each time. There's no idempotency key. + + Cause #2 is the dangerous one: it can charge and fulfill twice. + + Three ways to fix it, roughly in order of robustness: + - Idempotency key on the order-creation endpoint (handles both causes) + - Dedup on the webhook by payment-intent id (handles #2 only) + - Client-side debounce (handles #1 only, papers over the real bug) + + Given your code already stores the payment-intent id, the + idempotency-key approach is a small change with the biggest payoff. + Want me to scope that? + +You: Yes, let's do the idempotency key. + +You: /opsx:propose add-order-idempotency-key + +AI: Created openspec/changes/add-order-idempotency-key/, with a proposal + and delta spec grounded in what we just found. Ready for implementation. +``` + +Notice what happened. The starting point was "something is wrong and I'm scared to touch it." Twenty seconds of exploration turned that into a named root cause, three ranked options, a recommendation tied to the existing code, and a precise change. The proposal that follows is sharp because the thinking happened first. + +## Handing off to propose + +Explore doesn't archive into anything. When you're ready, you simply start a change, and the AI carries the context from your conversation into the artifacts. + +```text +explore ──► propose ──► apply ──► archive + (think) (agree) (build) (record) +``` + +You can say it in plain language ("let's turn this into a change") or run `/opsx:propose ` directly. Either way, the exploration you just did becomes the foundation of the proposal, not throwaway chat. + +If you use the expanded command set, explore can hand off to `/opsx:new` instead, for step-by-step artifact creation. See [Workflows](workflows.md). + +## Tips for a good exploration + +- **Bring the problem, not the solution.** "Logins feel slow" gives the AI room to investigate. "Add a Redis cache" pre-commits you to an answer you haven't tested yet. +- **Ask for the tradeoffs out loud.** "What are the downsides of each option?" gets you a more honest comparison. +- **Let it read first.** The best explorations start with the AI actually looking at your code, not guessing. Point it at the relevant area if it helps. +- **It's okay to bail.** If exploration reveals the idea isn't worth it, that's a win. You learned it cheaply. +- **Explore again mid-change.** Stuck during `/opsx:apply`? You can step back and explore a sub-problem, then return. + +## The honest tradeoffs + +**What you gain:** explore catches wrong turns at the cheapest possible moment, before any artifact exists. It's especially powerful in unfamiliar code, where the AI's ability to read and summarize the system saves you an afternoon of spelunking. + +**What it costs:** a little patience. Explore is a conversation, so it's slower than firing off `/opsx:propose` and hoping. For work you genuinely understand already, that extra step is pure overhead, and you should skip it. + +The rule of thumb: the fuzzier the task, the more explore pays off. The clearer the task, the more you can skip straight to proposing. + +## Where to go next + +- [Commands: `/opsx:explore`](commands.md#opsxexplore): the precise reference +- [Workflows](workflows.md): explore as part of the everyday loop +- [Examples & Recipes](examples.md#recipe-3-exploring-before-you-commit): explore in a full walkthrough +- [Getting Started](getting-started.md): the first-change guide, exploration included diff --git a/docs/faq.md b/docs/faq.md index ad457a5e1..9c0c11685 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -44,13 +44,17 @@ Both are files OpenSpec writes so your assistant can run the workflow. Skills (` ## The workflow +### Where should I start if I'm not sure what to build? + +With `/opsx:explore`. It's a no-stakes thinking partner that reads your codebase, lays out options, and turns a fuzzy problem into a concrete plan, all before any change or code exists. It's in the default profile, so it's always available. When the plan is clear, it hands off to `/opsx:propose`. This is the single best habit to form, because it stops an eager AI from confidently building the wrong thing. See [Explore First](explore.md). + ### What's the simplest possible flow? ```text -/opsx:propose then /opsx:apply then /opsx:archive +/opsx:explore (optional) then /opsx:propose then /opsx:apply then /opsx:archive ``` -Propose drafts the plan, apply builds it, archive files it away. That's the whole loop. +Explore to think it through, propose to draft the plan, apply to build it, archive to file it away. Skip explore when you already know exactly what you want. ### What's the difference between `/opsx:propose` and `/opsx:new`? diff --git a/docs/getting-started.md b/docs/getting-started.md index 590ca92e8..685b1b0c8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -16,6 +16,7 @@ The whole loop, with each step labeled by where it happens: ```text TERMINAL $ npm install -g @fission-ai/openspec@latest TERMINAL $ cd your-project && openspec init +AI CHAT /opsx:explore (optional: think it through first) AI CHAT /opsx:propose add-dark-mode (AI drafts the plan; you review it) AI CHAT /opsx:apply (AI builds it) AI CHAT /opsx:archive (specs updated, change filed away) @@ -23,6 +24,8 @@ AI CHAT /opsx:archive (specs updated, change filed away) Two terminal steps to set up, then you live in chat. The rest of this guide unpacks what each step does and what you'll see. +> **Not sure what to build yet? Start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your codebase, weighs options, and sharpens a fuzzy idea into a concrete plan, all before any artifact or code exists. When the picture is clear, it hands off to `/opsx:propose`. This is the single best habit for working with an AI that will otherwise confidently build the wrong thing. See the [Explore guide](explore.md). + ## How It Works OpenSpec helps you and your AI coding assistant agree on what to build before any code is written. @@ -30,9 +33,12 @@ OpenSpec helps you and your AI coding assistant agree on what to build before an **Default quick path (core profile):** ```text -/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive +/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive + (optional) ``` +Start with `/opsx:explore` when you're figuring out what to do, or jump straight to `/opsx:propose` when you already know. Explore is in the default profile, so it's always there when you want it. + **Expanded path (custom workflow selection):** ```text @@ -268,6 +274,7 @@ openspec view ## Next Steps +- [Explore First](explore.md) - Use `/opsx:explore` to think through an idea before you commit - [Core Concepts at a Glance](overview.md) - The whole mental model on one page - [Examples & Recipes](examples.md) - Real changes, start to finish - [Workflows](workflows.md) - Common patterns and when to use each command diff --git a/docs/glossary.md b/docs/glossary.md index fd45a4e38..7478929dd 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -46,6 +46,8 @@ Terms are grouped by topic, then alphabetized within each group. **Slash command.** A command you type into your AI assistant's chat, like `/opsx:propose`. Slash commands drive the workflow. They are not terminal commands. See [How Commands Work](how-commands-work.md). +**Explore (`/opsx:explore`).** The thinking-partner command. It reads your codebase, compares options, and clarifies a fuzzy idea into a concrete plan, creating no artifacts and writing no code. The recommended starting point whenever you have a problem but not yet a plan. See [Explore First](explore.md). + **CLI.** The `openspec` program you run in your terminal. It sets up projects, lists and validates changes, opens the dashboard, and archives. The terminal half of OpenSpec. See [CLI](cli.md). **Skill.** A folder of instructions (`.../skills/openspec-*/SKILL.md`) that your AI assistant auto-detects and follows. Skills are the emerging cross-tool standard for delivering the OpenSpec workflow to your assistant. diff --git a/docs/how-commands-work.md b/docs/how-commands-work.md index 45824bd2a..e60c9a761 100644 --- a/docs/how-commands-work.md +++ b/docs/how-commands-work.md @@ -110,12 +110,14 @@ Quick checks, fastest first: By default, OpenSpec installs the **core** set of slash commands: +- `/opsx:explore`: think through an idea with the AI before committing to a change (great first step when you're unsure) - `/opsx:propose`: create a change and draft all its planning artifacts in one step -- `/opsx:explore`: think through an idea before committing to a change - `/opsx:apply`: build the change by working through its task list - `/opsx:sync`: merge a change's spec updates into your main specs (usually automatic) - `/opsx:archive`: finish a change and file it away +A good default rhythm: `explore` when you're figuring out what to do, then `propose`, `apply`, `archive`. The [Explore First](explore.md) guide explains why that opening step pays off. + There's also an **expanded** set for people who want finer control (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`). You turn it on with `openspec config profile`, then apply it with `openspec update`. New to all of this? `/opsx:onboard` (in the expanded set) walks you through a complete change on your own codebase, narrating each step. It's the friendliest possible introduction. @@ -132,6 +134,9 @@ TERMINAL $ cd your-project TERMINAL $ openspec init (installs slash commands into your AI tool) +AI CHAT /opsx:explore + (optional: think the idea through with the AI first) + AI CHAT /opsx:propose add-dark-mode (AI drafts proposal, specs, design, tasks) diff --git a/docs/overview.md b/docs/overview.md index 0eab5e7bf..6321a3439 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -46,15 +46,18 @@ Two folders. `specs/` is what's true. `changes/` is what you're proposing. Archi ## The loop you'll actually run -In the default setup, your day looks like this. The first command drafts the plan; you read it; the second builds it; the third files it away. +In the default setup, your day looks like this. Optionally think it through first; then one command drafts the plan, you read it, the next builds it, and the last files it away. ```text +/opsx:explore → (optional) think it through with the AI first /opsx:propose add-dark-mode → AI drafts proposal, specs, design, tasks (you read and adjust the plan) /opsx:apply → AI builds it, checking off tasks /opsx:archive → specs updated, change archived ``` +**When in doubt, start by exploring.** `/opsx:explore` is a no-stakes thinking partner: it reads your code, lays out options, and turns a fuzzy idea into a concrete plan before any artifact exists. It's the best antidote to an AI that will otherwise build *something* from a vague prompt. Already know exactly what you want? Skip straight to `/opsx:propose`. Either way, explore ships in the default profile, so it's always there. See the [Explore guide](explore.md). + Those are slash commands, typed in your AI assistant's chat. Setup (`openspec init`) happens in your terminal. If that split is new to you, read [How Commands Work](how-commands-work.md) first; it's the most common point of confusion. ## "Enablers, not gates" @@ -81,6 +84,7 @@ And the honest tradeoff: for a truly trivial one-line fix, the ceremony may not ## Where to go next - New here? [Getting Started](getting-started.md) walks the first change in full. +- Not sure what to build yet? [Explore First](explore.md) is the place to start. - Confused about where commands run? [How Commands Work](how-commands-work.md). - Want the deep version of everything above? [Concepts](concepts.md). - Learn by example? [Examples & Recipes](examples.md). diff --git a/docs/workflows.md b/docs/workflows.md index 7e03b9655..e333ca6ef 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -33,8 +33,8 @@ OPSX (fluid actions): ### Default Quick Path (`core` profile) New installs default to `core`, which provides: -- `/opsx:propose` - `/opsx:explore` +- `/opsx:propose` - `/opsx:apply` - `/opsx:sync` - `/opsx:archive` @@ -42,9 +42,36 @@ New installs default to `core`, which provides: Typical flow: ```text -/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive +/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive + (optional) ``` +#### Start by exploring (the habit worth forming) + +`/opsx:explore` is part of the default profile, not an advanced add-on. It's the move to make whenever you have a problem but not yet a plan, which, with an AI assistant, is most of the time. + +```text +You: /opsx:explore + +AI: What would you like to explore? + +You: Our search results feel stale. I'm not sure if it's caching, + indexing, or the query itself. + +AI: Let me look... [reads the search service and cache layer] + It's the index: it only rebuilds nightly, so edits don't show + up until the next day. Two options: rebuild on write (simple, + more load) or a short-TTL cache invalidation (more moving parts, + less load). Given your write volume is low, rebuild-on-write is + the cleaner fix. Want to scope it? + +You: Yes. + +You: /opsx:propose rebuild-search-index-on-write +``` + +Explore creates no artifacts and writes no code. It's a free, no-stakes conversation that turns a vague worry into a precise change, so the proposal that follows is sharp. Already know exactly what you want? Skip it and go straight to `/opsx:propose`. Full guide: [Explore First](explore.md). + ### Expanded/Full Workflow (custom selection) If you want explicit scaffold-and-build commands (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), enable them with: @@ -435,7 +462,7 @@ For full command details and options, see [Commands](commands.md). | Command | Purpose | When to Use | |---------|---------|-------------| | `/opsx:propose` | Create change + planning artifacts | Fast default path (`core` profile) | -| `/opsx:explore` | Think through ideas | Unclear requirements, investigation | +| `/opsx:explore` | Think through ideas with the AI | Start here when unsure: unclear requirements, investigation, comparing options | | `/opsx:new` | Start a change scaffold | Expanded mode, explicit artifact control | | `/opsx:continue` | Create next artifact | Expanded mode, step-by-step artifact creation | | `/opsx:ff` | Create all planning artifacts | Expanded mode, clear scope | From 7552233ecbc5a1f826d75c11da61f372a17e197e Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 22 Jun 2026 09:33:52 -0500 Subject: [PATCH 3/4] docs: close recurring gaps (existing projects, editing changes, uninstall, context limits) + sync tool list Sweep of open issues and discussions surfaced several questions good docs should answer but didn't. This adds the missing guides and fixes a stale list. New guides: - docs/existing-projects.md: adopting OpenSpec on a large brownfield codebase without documenting everything up front (addresses #510, #1100, #176). Delta-first framing, first-change walkthrough, onboard, importing existing requirements docs, domain organization, monorepo/workspace pointers. - docs/editing-changes.md: how to edit any artifact, update a proposal/spec after starting, go back after implementing, and reconcile manual code edits (addresses #684, #976, #355, #1188, #169, #1206). Enhancements: - installation.md: Updating + Uninstalling sections (addresses #308). - faq.md: new entries for existing codebases, editing artifacts, going back, reconciling manual edits, context limits / long sessions, and uninstalling (addresses #257 among others). - cli.md: --tools list now includes `vibe` and matches AI_TOOLS in src/core/config.ts, with a note pointing at the source (fixes #1213). - Wired the new guides into the docs home, getting-started, and the README. Docs-only and additive. No em-dashes in prose; links and section anchors verified. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 2 + docs/README.md | 4 ++ docs/cli.md | 4 +- docs/editing-changes.md | 90 +++++++++++++++++++++++++ docs/existing-projects.md | 134 ++++++++++++++++++++++++++++++++++++++ docs/faq.md | 24 +++++++ docs/getting-started.md | 2 + docs/installation.md | 33 ++++++++++ 8 files changed, 292 insertions(+), 1 deletion(-) create mode 100644 docs/editing-changes.md create mode 100644 docs/existing-projects.md diff --git a/README.md b/README.md index 3dfd0e522..523918f50 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,8 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`, → **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page
→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish
→ **[Workflows](docs/workflows.md)**: combos and patterns
+→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase
+→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits
→ **[Commands](docs/commands.md)**: slash commands & skills
→ **[CLI](docs/cli.md)**: terminal reference
→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths
diff --git a/docs/README.md b/docs/README.md index 92bf1daee..728cfbd0d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,8 @@ That second one matters more than it looks. OpenSpec has two halves: a command l **I have a problem but not a plan.** This is the common case, and it has a dedicated answer: [Explore First](explore.md). Use `/opsx:explore` to think it through with the AI before committing to anything. +**I have a big existing codebase.** You don't document all of it. [Using OpenSpec in an Existing Project](existing-projects.md) shows how to start on real, brownfield code without boiling the ocean. + **I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place. **I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration. @@ -47,6 +49,8 @@ That second one matters more than it looks. OpenSpec has two halves: a command l |-----|-------------------| | [Workflows](workflows.md) | Common patterns and when to reach for each command | | [Examples & Recipes](examples.md) | Full walkthroughs of real changes, copy-pasteable | +| [Using OpenSpec in an Existing Project](existing-projects.md) | Adopting OpenSpec on a large brownfield codebase | +| [Editing & Iterating on a Change](editing-changes.md) | Update artifacts, go back, reconcile manual edits | | [Commands](commands.md) | Reference for every `/opsx:*` slash command | | [CLI](cli.md) | Reference for every `openspec` terminal command | diff --git a/docs/cli.md b/docs/cli.md index 103dd7d4f..57d954d4b 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -107,7 +107,9 @@ openspec init [path] [options] `--profile custom` uses whatever workflows are currently selected in global config (`openspec config profile`). -**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `opencode`, `pi`, `qoder`, `lingma`, `qwen`, `roocode`, `trae`, `windsurf` +**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `vibe`, `windsurf` + +> This list mirrors `AI_TOOLS` in `src/core/config.ts`. See [Supported Tools](supported-tools.md) for each tool's skill and command paths. **Examples:** diff --git a/docs/editing-changes.md b/docs/editing-changes.md new file mode 100644 index 000000000..dedeeb578 --- /dev/null +++ b/docs/editing-changes.md @@ -0,0 +1,90 @@ +# Editing & Iterating on a Change + +**Every artifact in a change is just a Markdown file you can edit at any time.** There is no locked "planning phase," no approval gate, no special edit mode to enter. Want to change the proposal after you've started building? Open `proposal.md` and change it. Realized the design is wrong mid-implementation? Fix `design.md` and keep going. That's the whole answer, and it's by design. + +This page is for the moment you think "wait, can I go back and change that?" Yes. Here's how, for each common case. + +## Two ways to edit anything + +You always have both: + +1. **Edit the file directly.** Artifacts are plain Markdown in `openspec/changes//`. Open `proposal.md`, `design.md`, `tasks.md`, or a delta spec under `specs/` in your editor and change it. Nothing else is required. + +2. **Ask your AI to revise it.** In chat, just say what you want: "Update the proposal to drop the caching idea and add a rate-limit section," or "the design should use a queue, not polling." The AI edits the artifact for you, using the rest of the change as context. + +Use whichever fits the moment. Small wording tweak? Edit the file. Substantive rethink? Let the AI revise with full context. + +## "How do I update the proposal (or specs) after I've started?" + +Just update it. Same change, refined. + +If you're using the expanded commands, the natural flow is: edit the artifact, then run `/opsx:continue` to pick up from the new state, or `/opsx:apply` to keep implementing against the updated plan. If you're on the default `core` commands, edit the artifact and run `/opsx:apply`; it reads the current files, so it builds against whatever the artifacts now say. + +The mental model: artifacts are the live plan, not a signed contract. The AI always works from their current contents, so editing them steers the work. + +```text +You: I want to change the approach in this change. + +You: [edit design.md, or tell the AI:] + Update design.md to use a background job instead of a synchronous call. + +AI: Updated design.md. The task list still fits; want me to continue applying? + +You: /opsx:apply +``` + +This answers a very common question: there's no separate "update proposal" command because you don't need one. The file is the source of truth, and editing it (by hand or via the AI) is the update. + +## "How do I go back to review after implementing?" + +You don't have to "go back," because you never left. The workflow is fluid: review, edit, and implementation aren't sequential phases you're trapped in. + +Concretely, after some `/opsx:apply` work: + +- Want to re-examine the plan? Open the artifacts and read them, or run `openspec show ` in your terminal for a consolidated view. +- Found something to change? Edit the artifact (or ask the AI to), then continue. +- Want a structured check that the code matches the plan? Run `/opsx:verify` (expanded command). It reports completeness, correctness, and coherence without blocking anything. See [Workflows: Verify](workflows.md#verify-check-your-work). + +There's no "review phase" to return to, because review is something you can do at any point, including after implementation. + +## "I edited the code by hand. How do I reconcile that with OpenSpec?" + +This happens constantly and it's fine. You tweaked something in your editor, and now the code and the artifacts disagree. Bring them back in sync in whichever direction is true: + +- **The code is now correct, the spec is stale.** Update the delta spec (and tasks, if relevant) to describe the behavior you actually shipped. The spec should match reality before you archive, because archiving merges the spec into your source of truth. +- **The spec is correct, the code drifted.** Keep building or fixing until the code matches the spec. + +A fast way to surface mismatches is `/opsx:verify`: it reads your artifacts and your code and tells you where they diverge. Treat its output as a to-do list for reconciliation, then archive once they agree. + +The principle: at archive time, your specs become the truth of record. So before you archive, make the specs honest about what the code does. Manual edits are welcome; just don't let them quietly desync the spec. + +## Refining a proposal you're not happy with + +If a generated proposal misses the mark, you have three good moves: + +- **Iterate in place.** Tell the AI what's off ("the scope is too broad, drop the admin features") and let it revise. Cheapest and usually right. +- **Explore first, then re-propose.** If the problem is that the idea itself is unclear, step back to `/opsx:explore`, think it through, and let a sharper proposal come out of that. See [Explore First](explore.md). +- **Start fresh.** If the intent has fundamentally changed, a new change can be clearer than patching the old one. + +That last move has its own decision guide, next. + +## When to update vs. start a new change + +Short version: **update when it's the same work refined; start new when the intent fundamentally changed or the scope exploded into different work.** + +- Same goal, better approach? Update. +- Scope narrowing (ship the MVP now, more later)? Update, then archive, then a new change for phase two. +- The problem itself changed ("add dark mode" became "build a full theming system")? New change. + +There's a full flowchart and worked examples in [Workflows: When to Update vs Start Fresh](workflows.md#when-to-update-vs-start-fresh) and a deeper treatment in [OPSX: When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh). + +## A note on tasks + +`tasks.md` is a living checklist, not a frozen plan. As you implement, you can add tasks you discover, remove ones that turned out unnecessary, or reorder them. The AI checks items off as it completes them during `/opsx:apply`, and it resumes from the first unchecked task if you come back later. Editing the list mid-flight is expected. + +## Where to go next + +- [Workflows](workflows.md) - patterns, plus the update-vs-new decision guide +- [Explore First](explore.md) - the place to step back to when an idea needs rethinking +- [Commands](commands.md) - `/opsx:continue`, `/opsx:apply`, and `/opsx:verify` in detail +- [Concepts: Artifacts](concepts.md#artifacts) - what each artifact is for diff --git a/docs/existing-projects.md b/docs/existing-projects.md new file mode 100644 index 000000000..d4d27e623 --- /dev/null +++ b/docs/existing-projects.md @@ -0,0 +1,134 @@ +# Using OpenSpec in an Existing Project + +**You do not document your whole codebase to start. You write specs only for what you're about to change.** That's the single most important thing to know about adopting OpenSpec on an existing project, and it's why OpenSpec is built brownfield-first. + +A common worry sounds like this: "My app is 80,000 lines old. Do I have to write specs for all of it before OpenSpec is useful?" No. You'd hate that, and so would we. OpenSpec grows your specs one change at a time. Your first change documents the slice it touches, the next change documents its slice, and over months your specs fill in naturally around the work you actually do. + +This guide shows how to start on day one without boiling the ocean. + +## The thirty-second version + +```bash +$ cd your-existing-project +$ openspec init # adds openspec/ and your AI tool's commands +``` + +Then, in your AI chat: + +```text +/opsx:explore # optional: have the AI read the area you'll touch +/opsx:propose +/opsx:apply +/opsx:archive +``` + +Your specs now describe exactly the part of the system that change touched, and nothing more. That's correct. You're done worrying about the other 80,000 lines. + +## Why delta-first is the whole trick + +OpenSpec changes are written as **deltas**: `ADDED`, `MODIFIED`, `REMOVED`. A delta describes what's changing relative to current behavior, not the entire system. + +This is exactly what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it. + +So your `openspec/specs/` directory doesn't start full and complete. It starts nearly empty and accumulates. Each archived change merges its delta in. The spec for `auth/` becomes thorough only after you've made several auth changes, which is exactly when you want it thorough. + +If you want the deeper mechanics, see [Concepts: Delta Specs](concepts.md#delta-specs). + +## Your first change on a real codebase + +Pick something small and real. Not a toy, not a rewrite. A change you were going to make this week anyway. Small first changes teach you the workflow with low stakes. + +**Step 1: Let the AI read the relevant area.** This is where `/opsx:explore` earns its keep on an unfamiliar or large codebase. Point it at the part you're about to touch and let it map how things work before proposing anything. + +```text +You: /opsx:explore + +AI: What would you like to explore? + +You: I need to add rate limiting to our public API, but I'm not sure + how requests currently flow through the middleware. + +AI: Let me trace it... [reads the router, middleware stack, and config] + Requests hit Express, pass through auth middleware, then your + controllers. There's no rate-limiting layer today. The cleanest + insertion point is a middleware right after auth. Want me to scope it? +``` + +Notice the AI now understands your actual structure, so the proposal it writes will fit your code, not a generic template. On a big codebase, this single habit saves the most pain. See [Explore First](explore.md). + +**Step 2: Propose the change.** The proposal and its delta spec capture just this change. + +```text +You: /opsx:propose add-api-rate-limiting +``` + +**Step 3: Build and archive** with `/opsx:apply` and `/opsx:archive`, same as any change. After archiving, you have a real spec for your rate-limiting behavior, born from a change you needed anyway. + +## Prefer a guided tour? Use onboard + +If you'd rather watch the whole loop happen on your own code with narration, the expanded command `/opsx:onboard` does exactly that: it scans your codebase for a small, safe improvement, then walks you through proposing, building, and archiving it, explaining each step. + +Turn on the expanded commands first: + +```bash +$ openspec config profile # select the expanded workflows +$ openspec update # apply them to this project +``` + +Then in chat: + +```text +/opsx:onboard +``` + +It's the gentlest possible introduction on a real project, and it leaves you with a genuine (small) change you can keep or discard. See [Commands: `/opsx:onboard`](commands.md#opsxonboard). + +## "But I already have requirements docs" + +Maybe you have a PRD, an SRS, a formal spec, even TLA+ models. Good. You don't import them wholesale, and you don't throw them away either. + +Treat existing docs as **source material for exploration**, not as specs to convert. When you start a change, paste or point the AI at the relevant section, and let it shape a focused OpenSpec delta from it. The delta captures the behavior you're changing now, in OpenSpec's testable requirement-and-scenario form. Your original documents stay where they are as background. + +The honest reason: OpenSpec specs are deliberately behavior-first and scoped to changes. A 40-page PRD is a different artifact with a different job. Forcing a one-time bulk conversion tends to produce a large, stale spec nobody trusts. Letting specs grow from real changes keeps them accurate. + +```text +You: /opsx:explore +You: Here's the section of our PRD about checkout. I'm implementing the + "guest checkout" requirement next. + [paste the relevant requirement] +AI: [reads it, asks clarifying questions, then helps scope a change] +You: /opsx:propose add-guest-checkout +``` + +## Organizing specs in a big codebase + +Specs live under `openspec/specs/`, grouped by **domain**: a logical area that matches how your team thinks about the system. You don't have to design the whole taxonomy up front. Create a domain folder when your first change in that area needs one. + +Common ways to slice domains: + +- **By feature area:** `auth/`, `payments/`, `search/` +- **By component:** `api/`, `frontend/`, `workers/` +- **By bounded context:** `ordering/`, `fulfillment/`, `inventory/` + +Pick whatever makes a newcomer nod. You can refine later. See [Concepts: Specs](concepts.md#specs). + +## Monorepos and work that spans repos + +For a monorepo, the simplest model is one `openspec/` directory at the repo root, with domains that map to your packages or services. That covers most teams. + +If your work genuinely spans **multiple repositories** (or several packages you treat as separate), OpenSpec has a beta **coordination workspace** feature: a machine-local view that links several repos or folders so you can plan across them. It's beta, so treat its commands and state as evolving. Start with the [Workspaces User Guide](workspaces-beta/user-guide.md), and see [Concepts: Coordination Workspaces](concepts.md#coordination-workspaces) for the mental model. + +## A few honest cautions + +- **Resist the urge to back-fill everything.** Writing specs for code you aren't changing feels productive and usually isn't. Those specs go stale, because nothing forces them to track reality. Let real changes drive your specs. +- **Keep early changes small.** Your first few changes are as much about learning the rhythm as shipping. A tight scope makes the loop fast and the lessons cheap. +- **Commit `openspec/` to git.** Your specs and archive belong in version control alongside the code they describe. +- **Give the AI context.** On a large codebase with strong conventions, fill in `openspec/config.yaml`'s `context:` so every proposal respects your stack and patterns. See [Customization](customization.md#project-configuration). + +## Where to go next + +- [Explore First](explore.md) - the key habit for understanding code before you change it +- [Getting Started](getting-started.md) - the full first-change walkthrough +- [Editing & Iterating on a Change](editing-changes.md) - adjusting a change as you learn +- [Concepts: Delta Specs](concepts.md#delta-specs) - why deltas make brownfield work clean +- [Customization](customization.md) - teach OpenSpec your project's conventions diff --git a/docs/faq.md b/docs/faq.md index 9c0c11685..9b9198fd3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -16,6 +16,10 @@ Because AI assistants are confident even when they're wrong. When the requiremen No. Use it where agreement matters, which is most non-trivial work. For a one-character typo fix, the ceremony probably isn't worth it, and that's fine. +### Can I use it on a big existing codebase, or only new projects? + +Existing codebases are the main event. OpenSpec is brownfield-first: you do not document your whole app up front. You write specs only for what each change touches, and your specs fill in over time around the work you actually do. There's a dedicated guide: [Using OpenSpec in an Existing Project](existing-projects.md). + ### Is it tied to one AI tool? No. OpenSpec works with 25+ assistants, including Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, and more. The full list and per-tool details are in [Supported Tools](supported-tools.md). @@ -68,10 +72,26 @@ A profile decides which slash commands get installed. **Core** (the default) giv Usually not. Sync merges a change's delta specs into your main specs, and `/opsx:archive` will offer to do it for you. Run sync manually only when you want the specs merged before archiving, for example on a long-running change. See [Commands](commands.md#opsxsync). +### How do I edit a proposal, spec, or task after I've started? + +Just edit the file. Every artifact is plain Markdown in `openspec/changes//`, and there's no locked phase or special edit mode. Change it by hand, or ask your AI to revise it ("update the design to use a queue"), then keep going. The AI always works from the current file contents. Full guide: [Editing & Iterating on a Change](editing-changes.md). + +### Can I go back and change the plan after implementing some of it? + +Yes, at any time. The workflow is fluid, so review and editing aren't phases you get locked out of. Edit the artifact, then continue. If you want a structured check that the code still matches the plan, run `/opsx:verify`. See [Editing & Iterating on a Change](editing-changes.md#how-do-i-go-back-to-review-after-implementing). + +### I edited the code by hand. How do I reconcile it with the spec? + +Bring them back in sync before you archive, since archiving makes your specs the record of truth. If the code is now correct, update the delta spec to match what you shipped; if the spec is correct, keep building until the code agrees. `/opsx:verify` surfaces the mismatches. See [Editing & Iterating on a Change](editing-changes.md#i-edited-the-code-by-hand-how-do-i-reconcile-that-with-openspec). + ### When should I update an existing change versus start a new one? Update when it's the same work, refined. Start fresh when the intent fundamentally changed or the scope exploded into different work. There's a decision flowchart and examples in [Workflows](workflows.md#when-to-update-vs-start-fresh). +### What if my session runs out of context, or requirements change mid-implementation? + +This is where specs earn their keep. Because the plan lives in files (not only in chat history), you can clear your context, start a fresh AI session, and pick up with `/opsx:apply`; it reads the artifacts and resumes from the first unchecked task. If requirements change, edit the artifacts to match the new reality and continue. Keeping a clean context window also produces better results; clear it before implementation. + ### Should I commit the `openspec/` folder to git? Yes. Your specs, active changes, and archive are part of your project's history. Commit them like any other source. The archive in particular becomes a durable record of why your system works the way it does. @@ -118,6 +138,10 @@ It collects anonymous usage stats: command names and version only. No arguments, Two steps. Upgrade the package (`npm install -g @fission-ai/openspec@latest`), then run `openspec update` inside each project to refresh the generated skills and commands. +### How do I uninstall OpenSpec? + +There's no uninstall command, because it's just a global package plus files in your project. Remove the package (`npm uninstall -g @fission-ai/openspec`), and optionally delete the `openspec/` directory and the generated tool files. Step-by-step, including what's safe to keep, is in [Installation: Uninstalling](installation.md#uninstalling). + ## Getting help ### Where do I ask questions or report bugs? diff --git a/docs/getting-started.md b/docs/getting-started.md index 685b1b0c8..af3b02b57 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -275,6 +275,8 @@ openspec view ## Next Steps - [Explore First](explore.md) - Use `/opsx:explore` to think through an idea before you commit +- [Using OpenSpec in an Existing Project](existing-projects.md) - Start on a large brownfield codebase +- [Editing & Iterating on a Change](editing-changes.md) - Update artifacts, go back, reconcile manual edits - [Core Concepts at a Glance](overview.md) - The whole mental model on one page - [Examples & Recipes](examples.md) - Real changes, start to finish - [Workflows](workflows.md) - Common patterns and when to use each command diff --git a/docs/installation.md b/docs/installation.md index 8c13c2203..3714f187b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -70,6 +70,39 @@ Or add to your development environment in `flake.nix`: openspec --version ``` +## Updating + +Upgrade the package, then refresh each project's generated files: + +```bash +npm install -g @fission-ai/openspec@latest # or pnpm/yarn/bun equivalent +openspec update # run inside each project +``` + +`openspec update` regenerates the skill and command files for the tools you've configured, so your slash commands stay current with the installed version. + +## Uninstalling + +There's no `openspec uninstall` command, because OpenSpec is just a global package plus some files in your project. Removing it is a few manual steps, and nothing here touches your source code. + +**1. Remove the global package:** + +```bash +npm uninstall -g @fission-ai/openspec # or: pnpm rm -g / yarn global remove / bun rm -g +``` + +**2. Remove OpenSpec from a project (optional).** Delete the `openspec/` directory if you no longer want its specs and changes: + +```bash +rm -rf openspec/ +``` + +Think before you do this: `openspec/specs/` and `openspec/changes/archive/` are your record of how the system behaves and why it changed. If you might want that history, keep the folder (or keep it in git) even after uninstalling. + +**3. Remove generated AI tool files (optional).** OpenSpec writes skill and command files into per-tool directories like `.claude/skills/openspec-*/`, `.cursor/commands/opsx-*`, and so on. Delete the `openspec-*` skills and `opsx-*` commands for whichever tools you configured. The exact paths per tool are listed in [Supported Tools](supported-tools.md). + +If you also have OpenSpec marker blocks in files like `CLAUDE.md` or `AGENTS.md`, remove those blocks by hand; your own content in those files is yours to keep. + ## Next Steps After installing, initialize OpenSpec in your project: From 7ad51b069d170369314f2e07b903044a3798cb39 Mon Sep 17 00:00:00 2001 From: TabishB Date: Wed, 24 Jun 2026 16:37:46 +1000 Subject: [PATCH 4/4] docs: reconcile coordinate-across-repos docs with the stores model The merge with main pulled in the stores rename (#1190), which retired the workspaces/initiatives/context-store vocabulary and deleted docs/workspaces-beta/. This updates the three docs still describing the old model so they match the new stores model, fixing the vocabulary-sweep test and dead links: - glossary.md: Workspace/Link/Context store/Initiative -> Store/Reference/ Working context/Workset; link to stores-beta/user-guide.md - README.md: replace deleted workspaces-beta/* links with the Stores User Guide and Agent Contract - existing-projects.md: reframe the multi-repo section as stores; drop the dead concepts.md#coordination-workspaces anchor Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/README.md | 4 ++-- docs/existing-projects.md | 2 +- docs/glossary.md | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index 728cfbd0d..627d76e31 100644 --- a/docs/README.md +++ b/docs/README.md @@ -82,8 +82,8 @@ That second one matters more than it looks. OpenSpec has two halves: a command l | Doc | What it gives you | |-----|-------------------| -| [Workspaces: User Guide](workspaces-beta/user-guide.md) | The smallest useful path for multi-repo coordination | -| [Workspaces: Agent Playbook](workspaces-beta/agent-cli-playbook.md) | How agents drive workspace and context-store commands | +| [Stores: User Guide](stores-beta/user-guide.md) | Plan in its own repo when your work spans repos or teams | +| [Agent Contract](agent-contract.md) | The machine-readable CLI surfaces agents drive | ## The thirty-second version diff --git a/docs/existing-projects.md b/docs/existing-projects.md index d4d27e623..8e879d440 100644 --- a/docs/existing-projects.md +++ b/docs/existing-projects.md @@ -116,7 +116,7 @@ Pick whatever makes a newcomer nod. You can refine later. See [Concepts: Specs]( For a monorepo, the simplest model is one `openspec/` directory at the repo root, with domains that map to your packages or services. That covers most teams. -If your work genuinely spans **multiple repositories** (or several packages you treat as separate), OpenSpec has a beta **coordination workspace** feature: a machine-local view that links several repos or folders so you can plan across them. It's beta, so treat its commands and state as evolving. Start with the [Workspaces User Guide](workspaces-beta/user-guide.md), and see [Concepts: Coordination Workspaces](concepts.md#coordination-workspaces) for the mental model. +If your work genuinely spans **multiple repositories** (or several packages you treat as separate), OpenSpec has a beta **stores** feature: planning lives in its own standalone repo that any of your code repos can reference, so the plan does not have to live inside one repo's `openspec/` folder. It's beta, so treat its commands and state as evolving. Start with the [Stores User Guide](stores-beta/user-guide.md) for the mental model and the smallest useful path. ## A few honest cautions diff --git a/docs/glossary.md b/docs/glossary.md index 7478929dd..397cbe36d 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -74,15 +74,15 @@ Terms are grouped by topic, then alphabetized within each group. ## Coordination across repos (beta) -These terms apply only if you're using OpenSpec's multi-repo workspace features, which are in beta. Most users can ignore them. See the [Workspaces User Guide](workspaces-beta/user-guide.md). +These terms apply only if your planning spans more than one repo. They're in beta. Most users can ignore them. See the [Stores User Guide](stores-beta/user-guide.md). -**Workspace.** A machine-local view that ties together several linked repos or folders so you can coordinate work that spans them. It is not a repo and doesn't hold specs itself. +**Store.** A standalone repo whose whole job is planning. It has the same `openspec/` shape you already know (specs and changes) plus a small identity file. You register it on your machine once, by name, and then any OpenSpec command can work in it from anywhere. -**Link.** A stable name (like `api` or `web`) that a workspace maps to a local repo or folder path. +**Reference.** A declaration, in a code repo's `openspec/config.yaml`, of a store that repo draws on. References are read-only: the repo keeps its own root, and `openspec instructions` gains an index of the referenced store's specs, each with the exact command to fetch it. -**Context store.** A durable, usually Git-backed folder that holds shared context across repos. Registered locally so OpenSpec can find it. +**Working context.** What `openspec context` assembles for the current repo: its OpenSpec root plus every store it references, each with how to fetch it. The answer to "what am I working with?" -**Initiative.** Shared coordination context that lives inside a context store. Repo-local changes can link to an initiative without copying the shared plan into every repo. +**Workset.** A personal, machine-local set of folders you open together (a store alongside the code repos you work on). Created explicitly with `openspec workset create`; nothing about those local paths is committed to the shared planning repo. ## See also