bb1f18c483
* 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: TabishB <tabishbidiwale@gmail.com> Co-authored-by: Tabish Bidiwale <30385142+TabishB@users.noreply.github.com>
7.5 KiB
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.
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/<name>/. 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.
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-<name>/. After archiving, your specs describe the new reality. See Concepts.
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.
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.
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.
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.
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.
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.
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.
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.
Coordination across repos (beta)
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.
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.
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.
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?"
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
- Core Concepts at a Glance: the five ideas, on one page
- Concepts: the long-form explanation
- How Commands Work: slash commands versus the CLI