mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-10-04 14:38:54 +08:00
Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Clay Good
|
8fd1ad3d0e | ||
|
Tabish Bidiwale
|
bae58cf614 |
@@ -0,0 +1,5 @@
|
||||
---
|
||||
"@fission-ai/openspec": patch
|
||||
---
|
||||
|
||||
Clarify the Codex setup hint for CLI, IDE, and desktop app users.
|
||||
@@ -58,8 +58,6 @@ For example, with a `context` field and the rule from the top of this page, here
|
||||
|
||||
Your config arrives first, then OpenSpec's built-in instruction and template. Rules add to the built-ins and never replace them. Edits to config.yaml reach the agent on the next run.
|
||||
|
||||
[Workflow runs](../reference/architecture/workflow-runs.md) covers the full run, from invocation to written artifacts.
|
||||
|
||||
## The fields
|
||||
|
||||
Three fields shape what the agent receives. Each field's exact contract (types, limits, validation) is in [Project configuration (config.yaml)](../reference/configuration/config-yaml.md).
|
||||
|
||||
@@ -20,7 +20,7 @@ Each change keeps its metadata at `openspec/changes/<change-name>/.openspec.yaml
|
||||
|
||||
### schema
|
||||
|
||||
The workflow schema this change follows. It is set when the change is created and wins over the project config, so a change keeps its schema even if `openspec/config.yaml` changes afterwards. Valid names are listed in [Schemas](../schemas/index.md).
|
||||
The workflow schema this change follows. It is set when the change is created and wins over the project config, so a change keeps its schema even if `openspec/config.yaml` changes afterwards. Run [`openspec schemas`](../cli.md#openspec-schemas) to list the available schema names.
|
||||
|
||||
### initiative
|
||||
|
||||
@@ -36,11 +36,11 @@ Keys other than `store` and `id` are rejected. No command reads the link today.
|
||||
|
||||
### skip_specs
|
||||
|
||||
Declares the change intentionally makes no spec deltas: a pure refactor, tooling, or docs change. With it set, validation accepts zero deltas, and artifacts that would generate spec files count as complete. Setting it while spec files exist under specs/ is a validation error. Its effect on deltas and archive is on [spec-driven](../schemas/spec-driven/index.md).
|
||||
Declares the change intentionally makes no spec deltas: a pure refactor, tooling, or docs change. With it set, validation accepts zero deltas, and artifacts that would generate spec files count as complete. Setting it while spec files exist under specs/ is a validation error.
|
||||
|
||||
### retire_capabilities
|
||||
|
||||
Authorizes archive to retire a capability. When this change's REMOVED deltas take away the last requirement a capability has, archive deletes that capability's main spec instead of stopping. The flag exists because the deletion is only recoverable from git, so it stays the author's call. The archive behavior is on [spec-driven](../schemas/spec-driven/index.md).
|
||||
Authorizes archive to retire a capability. When this change's REMOVED deltas take away the last requirement a capability has, archive deletes that capability's main spec instead of stopping. The flag exists because the deletion is only recoverable from git, so it stays the author's call.
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ The CLI keeps its machine-level settings at `~/.config/openspec/config.json` on
|
||||
| `featureFlags` | map: flag → boolean | No | Boolean feature toggles |
|
||||
| `defaultStore` | string | No | Machine-level fallback store for root resolution |
|
||||
| `openers` | list | No | The tools worksets open in, and how each is launched |
|
||||
| `telemetry` | map | No | State the CLI keeps: anonymous id and notice-seen |
|
||||
| `telemetry` | map | No | Telemetry opt-out, anonymous id, and notice-seen state |
|
||||
|
||||
### profile
|
||||
|
||||
@@ -44,7 +44,7 @@ The tools a workset can open in, and how each is launched. Entries are hand-edit
|
||||
|
||||
### telemetry
|
||||
|
||||
State the CLI writes for telemetry: your anonymous id and whether the first-run notice was shown. It is not the opt-out. Disabling telemetry is an environment variable, on [Environment variables](environment-variables.md).
|
||||
The CLI stores your anonymous id and whether the first-run notice was shown. Set `telemetry.enabled` to `false` to disable telemetry. You can also opt out with `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` in your environment.
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ What to write in these fields is covered in [Project configuration](../../custom
|
||||
|
||||
### schema
|
||||
|
||||
The workflow schema every change in this project follows. Valid values are `spec-driven` or a schema name the project defines. The names are listed in [Schemas](../schemas/index.md).
|
||||
The workflow schema every change in this project follows. Valid values are `spec-driven` or a schema name the project defines. Run [`openspec schemas`](../cli.md#openspec-schemas) to list the available schema names.
|
||||
|
||||
### context
|
||||
|
||||
|
||||
@@ -7,5 +7,5 @@
|
||||
| [Project configuration (config.yaml)](config-yaml.md) | `openspec/config.yaml` | The schema, context, and rules this project plans with |
|
||||
| [Change metadata (.openspec.yaml)](change-metadata.md) | `openspec/changes/<name>/.openspec.yaml` | The workflow schema, goal, scope, and spec exceptions for one change |
|
||||
| [CLI settings (config.json)](config-json.md) | `~/.config/openspec/config.json` (Windows varies) | How the openspec CLI behaves on your machine |
|
||||
| [Environment variables](environment-variables.md) | Your shell or CI environment | Telemetry opt-out, and where the config and data directories live |
|
||||
| Environment variables | Your shell or CI environment | Telemetry opt-out, and where the config and data directories live |
|
||||
| Stores | `~/.local/share/openspec/stores/` (Windows varies) | The registry and metadata behind multi-repo stores |
|
||||
|
||||
@@ -2,26 +2,26 @@
|
||||
|
||||
> Every OpenSpec term, one line each.
|
||||
|
||||
OpenSpec reuses words that mean something else in git, CI, and agent tooling. Each row gives the OpenSpec meaning, and the last column links to the page that teaches the term.
|
||||
OpenSpec reuses words that mean something else in git, CI, and agent tooling. Each row gives the OpenSpec meaning. The last column links to more detail where available.
|
||||
|
||||
| Term | Definition | More |
|
||||
|---|---|---|
|
||||
| **Apply** | Implement the tasks in a change proposal. Skill: `openspec-apply-change`. | [Apply a change](../guides/apply.md) |
|
||||
| **Apply** | Implement the tasks in a change proposal. Skill: `openspec-apply-change`. | [Apply a change](skills.md#openspec-apply-change) |
|
||||
| **Archive** | Complete a change proposal: merge its deltas into the main specs and move its folder to `openspec/changes/archive/`. | [Quickstart](../start/quickstart.md) |
|
||||
| **Artifact** | A planning document inside a change proposal: `proposal.md`, delta specs, `design.md`, `tasks.md`. Not a build output. | [Concepts](../guides/concepts.md) |
|
||||
| **Capability** | One behavior area of your system. Each has one spec at `openspec/specs/<capability>/spec.md`. | [Concepts](../guides/concepts.md) |
|
||||
| **Change proposal** | One unit of work: a folder under `openspec/changes/<name>/` holding its planning artifacts. Often shortened to "change". Not a git commit. | [Concepts](../guides/concepts.md) |
|
||||
| **Artifact** | A planning document inside a change proposal: `proposal.md`, delta specs, `design.md`, `tasks.md`. Not a build output. | [Artifacts](schemas/spec-driven/index.md#artifacts) |
|
||||
| **Capability** | One behavior area of your system. Each has one spec at `openspec/specs/<capability>/spec.md`. | [Capabilities](schemas/spec-driven/index.md#proposalmd) |
|
||||
| **Change proposal** | One unit of work: a folder under `openspec/changes/<name>/` holding its planning artifacts. Often shortened to "change". Not a git commit. | [Propose](../start/quickstart.md#step-2-propose) |
|
||||
| **Command** | A typed entry point for a workflow. Spelling varies per tool (`/opsx:propose`, `/opsx-propose`). The docs name workflows by skill instead. | [Supported tools](supported-tools.md) |
|
||||
| **Continue** | Create the next planning artifact for an existing change proposal. Skill: `openspec-continue-change`. | [Skills](skills.md) |
|
||||
| **Delivery** | How workflows are installed: as skills, commands, or both. | [Set up your project](../start/setup.md) |
|
||||
| **Delta spec** | A spec inside a change proposal listing only what changes, under `ADDED`, `MODIFIED`, `REMOVED`, and `RENAMED` headers. | [Delta specs](schemas/spec-driven/index.md#delta-specs-specmd) |
|
||||
| **Explore** | Think an idea through with the agent before proposing. Writes no code. Skill: `openspec-explore`. | [Explore an idea](../guides/explore.md) |
|
||||
| **Explore** | Think an idea through with the agent before proposing. Writes no code. Skill: `openspec-explore`. | [Explore an idea](skills.md#openspec-explore) |
|
||||
| **Fast-forward** | Create a change proposal with every planning artifact in one pass, ready to implement. Skill: `openspec-ff-change`. Not a git fast-forward. | [Skills](skills.md) |
|
||||
| **Legacy workflow** | The pre-OPSX `/openspec:*` commands. | [Migration](../help/legacy/migration.md) |
|
||||
| **Legacy workflow** | The pre-OPSX `/openspec:*` commands. | |
|
||||
| **Loop** | The cycle a change proposal moves through: explore, propose, review, apply, archive. | [Quickstart](../start/quickstart.md) |
|
||||
| **Main specs** | The `openspec/specs/` tree: the current, agreed behavior of your system. Archiving merges deltas into it. A capability with no spec yet gets one from its `ADDED` requirements. | [Concepts](../guides/concepts.md) |
|
||||
| **Main specs** | The `openspec/specs/` tree: the current, agreed behavior of your system. Archiving merges deltas into it. A capability with no spec yet gets one from its `ADDED` requirements. | [Archive](../start/quickstart.md#step-5-archive) |
|
||||
| **OpenSpec root** | The `openspec/` tree a command resolves to and operates on: your repo's, or a store's. | [Stores](../multi-repo/stores.md#where-artifacts-get-created-when-using-stores) |
|
||||
| **OPSX** | The current OpenSpec workflow system, and the command prefix it installs (`/opsx:`). | [Architecture](architecture/index.md) |
|
||||
| **OPSX** | The current OpenSpec workflow system, and the command prefix it installs (`/opsx:`). | |
|
||||
| **Profile** | Which workflows init installs: `core` or `custom`. | [Profiles](../customize/profiles.md) |
|
||||
| **Propose** | Create a change proposal and generate all its planning artifacts in one step. Skill: `openspec-propose`. | [Quickstart](../start/quickstart.md) |
|
||||
| **Registry** | The machine-level list of registered stores, in `registry.yaml`. Not a package registry. | [CLI](cli.md#openspec-store) |
|
||||
@@ -29,12 +29,12 @@ OpenSpec reuses words that mean something else in git, CI, and agent tooling. Ea
|
||||
| **Scenario** | A testable example under a requirement, in WHEN/THEN form. | [Delta specs](schemas/spec-driven/index.md#delta-specs-specmd) |
|
||||
| **Schema** | The definition of which artifacts a change proposal produces, and in what order. Not JSON Schema. | [Schemas](schemas/index.md) |
|
||||
| **Skill** | A workflow's instructions, installed where your AI tool reads them (`.agents/skills/`, ...). | [Skills](skills.md) |
|
||||
| **Spec** | A file describing how one capability behaves today, at `openspec/specs/<capability>/spec.md`. | [Concepts](../guides/concepts.md) |
|
||||
| **Spec** | A file describing how one capability behaves today, at `openspec/specs/<capability>/spec.md`. | [Archive](../start/quickstart.md#step-5-archive) |
|
||||
| **spec-driven** | The default schema: proposal, then delta specs, then design, then tasks. | [spec-driven](schemas/spec-driven/index.md) |
|
||||
| **Store** | A standalone OpenSpec repo registered on your machine, for planning that spans repositories. Not a data store. | [Stores (beta)](../multi-repo/stores.md) |
|
||||
| **Sync** | Merge implemented deltas into the main specs without archiving. Skill: `openspec-sync-specs`. | [Skills](skills.md) |
|
||||
| **Template** | The starting content a schema gives each artifact. | [Schemas](../customize/schemas.md) |
|
||||
| **Update** | As a skill (`openspec-update-change`): revise a change proposal's planning artifacts. As a CLI command (`openspec update`): refresh OpenSpec's installed files. | [Change course](../guides/change-course.md), [CLI](cli.md) |
|
||||
| **Update** | As a skill (`openspec-update-change`): revise a change proposal's planning artifacts. As a CLI command (`openspec update`): refresh OpenSpec's installed files. | [Update a change](skills.md#openspec-update-change), [CLI](cli.md) |
|
||||
| **Verify** | Check the implementation matches a change proposal's artifacts before archiving. Skill: `openspec-verify-change`. | [Skills](skills.md) |
|
||||
| **Workflow** | A named OpenSpec action (propose, apply, archive, ...), installed into your AI tool as a skill or command. | [Set up your project](../start/setup.md) |
|
||||
| **Workset** | A personal, local group of folders opened together in one tool. Not a store, and nothing is shared. | [Worksets (beta)](../multi-repo/worksets.md) |
|
||||
|
||||
@@ -80,8 +80,12 @@ Skills stay in `.cline/skills/`.
|
||||
|
||||
### Codex
|
||||
|
||||
- **Invocation**: type `$openspec-<skill>`. Codex does not recognize the
|
||||
`/openspec-<skill>` form ([upstream issue](https://github.com/openai/codex/issues/11817)).
|
||||
- **CLI and IDE extension**: type `$openspec-<skill>` or run `/skills`. Codex does
|
||||
not recognize the `/openspec-<skill>` form
|
||||
([upstream issue](https://github.com/openai/codex/issues/11817)).
|
||||
- **Desktop app**: open Skills in the sidebar and select `openspec-<skill>`.
|
||||
[OpenAI's skills documentation](https://learn.chatgpt.com/docs/build-skills)
|
||||
describes both interfaces.
|
||||
- **No command files**: Codex runs skills directly, so init skips commands even when
|
||||
delivery includes them and prints `Commands skipped for: codex (uses skills)`.
|
||||
- **Shared folder**: Codex skills land in `.agents/skills/`, the same tree Antigravity,
|
||||
|
||||
@@ -146,14 +146,11 @@ Step through what archiving does:
|
||||
└── 2026-08-08-add-rate-limiting/
|
||||
```
|
||||
|
||||
Git is a separate concern. Commit the change folder with the code, and nothing else about your workflow changes. When to archive relative to a PR is a team convention; the [Teams](../guides/teams.md) guide has the tradeoff.
|
||||
Git is a separate concern. Commit the change folder with the code, and nothing else about your workflow changes.
|
||||
|
||||
## Going further
|
||||
|
||||
- [Concepts](../guides/concepts.md): what the two artifacts are, and how a delta describes a change.
|
||||
- [Explore](../guides/explore.md): getting more out of explore mode.
|
||||
- [Apply](../guides/apply.md): pacing, context windows, resuming long changes.
|
||||
- [Review the plan](../guides/review-the-plan.md): what to look for in specs before you build.
|
||||
- [Delta specs](../reference/schemas/spec-driven/index.md#delta-specs-specmd): how to write the behavior changes in a delta spec.
|
||||
- [Profiles](../customize/profiles.md): optional workflows beyond the core set (verify before archive, incremental planning).
|
||||
|
||||
## Advanced guides
|
||||
|
||||
@@ -41,7 +41,7 @@ Running init creates two things in your project:
|
||||
- An `openspec/` folder at the repo root
|
||||
- Workflow files (skills and commands) added to your AI tool's folder (`.agents/`, `.claude/`, etc.)
|
||||
|
||||
Commit all of it like the rest of your source ([FAQ](../help/faq.md) covers why). Init changes nothing else in your repo (if it finds leftovers from an older OpenSpec version, it asks before cleaning them up).
|
||||
Commit all of it like the rest of your source. Init changes nothing else in your repo (if it finds leftovers from an older OpenSpec version, it asks before cleaning them up).
|
||||
|
||||
### The `openspec/` folder
|
||||
|
||||
@@ -55,7 +55,7 @@ openspec/
|
||||
└── archive/ completed changes move here
|
||||
```
|
||||
|
||||
[Concepts](../guides/concepts.md) explains both artifacts; [Project config](../customize/project-config.md) covers `config.yaml`.
|
||||
[Project config](../customize/project-config.md) covers `config.yaml`.
|
||||
|
||||
### The workflow files (skills and commands)
|
||||
|
||||
|
||||
+7
-3
@@ -1360,9 +1360,13 @@ export class InitCommand {
|
||||
// Tools with no slash surface (e.g. Rovo Dev) reference skills as
|
||||
// prose ("the openspec-propose skill"); phrase the hint so it reads
|
||||
// as an instruction rather than a dead command with an argument.
|
||||
hint = usesNaturalLanguageSkillReferences(tool.value)
|
||||
? `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`
|
||||
: `Start your first change: ${skillReference} "your idea"`;
|
||||
if (usesNaturalLanguageSkillReferences(tool.value)) {
|
||||
hint = `Start your first change: ask ${tool.name} to use ${skillReference} with "your idea"`;
|
||||
} else if (tool.value === 'codex') {
|
||||
hint = `Start your first change: ${skillReference} "your idea" (Codex CLI or IDE); in the Codex desktop app, select ${skillReference.slice(1)} from Skills in the sidebar`;
|
||||
} else {
|
||||
hint = `Start your first change: ${skillReference} "your idea"`;
|
||||
}
|
||||
} else {
|
||||
continue;
|
||||
}
|
||||
|
||||
@@ -2303,6 +2303,8 @@ describe('InitCommand - profile and detection features', () => {
|
||||
const logCalls = (console.log as unknown as { mock: { calls: unknown[][] } }).mock.calls.flat().map(String);
|
||||
const startHint = logCalls.find((entry) => entry.includes('Start your first change'));
|
||||
expect(startHint).toContain('$openspec-propose');
|
||||
expect(startHint).toContain('(Codex CLI or IDE)');
|
||||
expect(startHint).toContain('in the Codex desktop app, select openspec-propose from Skills in the sidebar');
|
||||
expect(startHint).not.toContain('/openspec-propose');
|
||||
expect(startHint).not.toContain('/opsx:propose');
|
||||
|
||||
@@ -2352,6 +2354,8 @@ describe('InitCommand - profile and detection features', () => {
|
||||
const codexHint = startHints.find((entry) => entry.includes('(Codex)'));
|
||||
const vibeHint = startHints.find((entry) => entry.includes('Mistral Vibe'));
|
||||
expect(codexHint).toContain('$openspec-propose');
|
||||
expect(codexHint).toContain('(Codex CLI or IDE)');
|
||||
expect(codexHint).toContain('Skills in the sidebar');
|
||||
expect(codexHint).not.toContain('/openspec-propose');
|
||||
expect(vibeHint).toContain('/openspec-propose');
|
||||
for (const hint of startHints) {
|
||||
|
||||
Reference in New Issue
Block a user