diff --git a/.gitignore b/.gitignore index abea4d16e..3a952f090 100644 --- a/.gitignore +++ b/.gitignore @@ -153,3 +153,6 @@ result # OpenCode .opencode/ opencode.json + +# Codex +.codex/ diff --git a/README.md b/README.md index c43d3e933..b8af8ca15 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Our philosophy: > [!TIP] > **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow. > -> Run `/opsx:onboard` to get started. → [Learn more here](docs/opsx.md) +> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)

Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions. @@ -46,17 +46,14 @@ Our philosophy: Using OpenSpec in a team? [Email here](mailto:teams@openspec.dev) for access to our Slack channel. - + ## See it in action ```text -You: /opsx:new add-dark-mode +You: /opsx:propose add-dark-mode AI: Created openspec/changes/add-dark-mode/ - Ready to create: proposal - -You: /opsx:ff # "fast-forward" - generate all planning docs -AI: ✓ proposal.md — why we're doing this, what's changing + ✓ proposal.md — why we're doing this, what's changing ✓ specs/ — requirements and scenarios ✓ design.md — technical approach ✓ tasks.md — implementation checklist @@ -101,7 +98,9 @@ cd your-project openspec init ``` -Now tell your AI: `/opsx:new ` +Now tell your AI: `/opsx:propose ` + +If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:sync`, `/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 20+ tools and growing. diff --git a/docs/cli.md b/docs/cli.md index df12fe1ca..fea903988 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,6 +1,6 @@ # CLI Reference -The OpenSpec CLI (`openspec`) provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands (like `/opsx:new`) documented in [Commands](commands.md). +The OpenSpec CLI (`openspec`) provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands (like `/opsx:propose`) documented in [Commands](commands.md). ## Summary @@ -67,6 +67,8 @@ These options work with all commands: Initialize OpenSpec in your project. Creates the folder structure and configures AI tool integrations. +Default behavior uses global config defaults: profile `core`, delivery `both`, workflows `propose, explore, apply, archive`. + ``` openspec init [path] [options] ``` @@ -83,8 +85,11 @@ openspec init [path] [options] |--------|-------------| | `--tools ` | Configure AI tools non-interactively. Use `all`, `none`, or comma-separated list | | `--force` | Auto-cleanup legacy files without prompting | +| `--profile ` | Override global profile for this init run (`core` or `custom`) | + +`--profile custom` uses whatever workflows are currently selected in global config (`openspec config profile`). -**Supported tools:** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codex`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `opencode`, `qoder`, `qwen`, `roocode`, `windsurf` +**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codex`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `kiro`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf` **Examples:** @@ -101,6 +106,9 @@ openspec init --tools claude,cursor # Configure for all supported tools openspec init --tools all +# Override profile for this run +openspec init --profile core + # Skip prompts and auto-cleanup legacy files openspec init --force ``` @@ -113,8 +121,9 @@ openspec/ ├── changes/ # Proposed changes └── config.yaml # Project configuration -.claude/skills/ # Claude Code skill files (if claude selected) -.cursor/rules/ # Cursor rules (if cursor selected) +.claude/skills/ # Claude Code skills (if claude selected) +.cursor/skills/ # Cursor skills (if cursor selected) +.cursor/commands/ # Cursor OPSX commands (if delivery includes commands) ... (other tool configs) ``` @@ -122,7 +131,7 @@ openspec/ ### `openspec update` -Update OpenSpec instruction files after upgrading the CLI. Re-generates AI tool configuration files. +Update OpenSpec instruction files after upgrading the CLI. Re-generates AI tool configuration files using your current global profile, selected workflows, and delivery mode. ``` openspec update [path] [options] @@ -920,7 +929,7 @@ openspec completion uninstall ## Related Documentation -- [Commands](commands.md) - AI slash commands (`/opsx:new`, `/opsx:apply`, etc.) +- [Commands](commands.md) - AI slash commands (`/opsx:propose`, `/opsx:apply`, etc.) - [Workflows](workflows.md) - Common patterns and when to use each command - [Customization](customization.md) - Create custom schemas and templates - [Getting Started](getting-started.md) - First-time setup guide diff --git a/docs/commands.md b/docs/commands.md index 9bc59b4b8..fd4bb7fe1 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -6,23 +6,70 @@ For workflow patterns and when to use each command, see [Workflows](workflows.md ## Quick Reference +### Default Quick Path (`core` profile) + | Command | Purpose | |---------|---------| +| `/opsx:propose` | Create a change and generate planning artifacts in one step | | `/opsx:explore` | Think through ideas before committing to a change | -| `/opsx:new` | Start a new change | +| `/opsx:apply` | Implement tasks from the change | +| `/opsx:archive` | Archive a completed change | + +### Expanded Workflow Commands (custom workflow selection) + +| Command | Purpose | +|---------|---------| +| `/opsx:new` | Start a new change scaffold | | `/opsx:continue` | Create the next artifact based on dependencies | | `/opsx:ff` | Fast-forward: create all planning artifacts at once | -| `/opsx:apply` | Implement tasks from the change | | `/opsx:verify` | Validate implementation matches artifacts | | `/opsx:sync` | Merge delta specs into main specs | -| `/opsx:archive` | Archive a completed change | | `/opsx:bulk-archive` | Archive multiple changes at once | | `/opsx:onboard` | Guided tutorial through the complete workflow | +The default global profile is `core`. To enable expanded workflow commands, run `openspec config profile`, select workflows, then run `openspec update` in your project. + --- ## Command Reference +### `/opsx:propose` + +Create a new change and generate planning artifacts in one step. This is the default start command in the `core` profile. + +**Syntax:** +```text +/opsx:propose [change-name-or-description] +``` + +**Arguments:** +| Argument | Required | Description | +|----------|----------|-------------| +| `change-name-or-description` | No | Kebab-case name or plain-language change description | + +**What it does:** +- Creates `openspec/changes//` +- Generates artifacts needed before implementation (for `spec-driven`: proposal, specs, design, tasks) +- Stops when the change is ready for `/opsx:apply` + +**Example:** +```text +You: /opsx:propose add-dark-mode + +AI: Created openspec/changes/add-dark-mode/ + ✓ proposal.md + ✓ specs/ui/spec.md + ✓ design.md + ✓ tasks.md + Ready for implementation. Run /opsx:apply. +``` + +**Tips:** +- Use this for the fastest end-to-end path +- If you want step-by-step artifact control, enable expanded workflows and use `/opsx:new` + `/opsx:continue` + +--- + ### `/opsx:explore` Think through ideas, investigate problems, and clarify requirements before committing to a change. @@ -42,7 +89,7 @@ Think through ideas, investigate problems, and clarify requirements before commi - Investigates the codebase to answer questions - Compares options and approaches - Creates visual diagrams to clarify thinking -- Can transition to `/opsx:new` when insights crystallize +- Can transition to `/opsx:propose` (default) or `/opsx:new` (expanded workflow) when insights crystallize **Example:** ```text @@ -66,7 +113,7 @@ AI: Let me investigate your current auth setup... You: Let's go with JWT. Can we start a change for that? -AI: Ready when you are. Run /opsx:new add-jwt-auth to begin. +AI: Ready when you are. Run /opsx:propose add-jwt-auth to begin. ``` **Tips:** @@ -79,7 +126,9 @@ AI: Ready when you are. Run /opsx:new add-jwt-auth to begin. ### `/opsx:new` -Start a new change. Creates the change folder structure and scaffolds it with the selected schema. +Start a new change scaffold. Creates the change folder and waits for you to generate artifacts with `/opsx:continue` or `/opsx:ff`. + +This command is part of the expanded workflow set (not included in the default `core` profile). **Syntax:** ``` @@ -565,13 +614,13 @@ Different AI tools use slightly different command syntax. Use the format that ma | Tool | Syntax Example | |------|----------------| -| Claude Code | `/opsx:new`, `/opsx:apply` | -| Cursor | `/opsx-new`, `/opsx-apply` | -| Windsurf | `/opsx-new`, `/opsx-apply` | -| Copilot (IDE) | `/opsx-new`, `/opsx-apply` | -| Trae | `/openspec-new-change`, `/openspec-apply-change` | +| Claude Code | `/opsx:propose`, `/opsx:apply` | +| Cursor | `/opsx-propose`, `/opsx-apply` | +| Windsurf | `/opsx-propose`, `/opsx-apply` | +| Copilot (IDE) | `/opsx-propose`, `/opsx-apply` | +| Trae | Skill-based invocations such as `/openspec-propose`, `/openspec-apply-change` (no generated `opsx-*` command files) | -The functionality is identical regardless of syntax. +The intent is the same across tools, but how commands are surfaced can differ by integration. > **Note:** GitHub Copilot commands (`.github/prompts/*.prompt.md`) are only available in IDE extensions (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompt files — see [Supported Tools](supported-tools.md) for details and workarounds. diff --git a/docs/concepts.md b/docs/concepts.md index 2784ac305..c2f2ff778 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -562,13 +562,13 @@ openspec/ │ OPENSPEC FLOW │ │ │ │ ┌────────────────┐ │ -│ │ 1. START │ /opsx:new creates a change folder │ +│ │ 1. START │ /opsx:propose (core) or /opsx:new (expanded) │ │ │ CHANGE │ │ │ └───────┬────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────┐ │ -│ │ 2. CREATE │ /opsx:ff or /opsx:continue │ +│ │ 2. CREATE │ /opsx:ff or /opsx:continue (expanded workflow) │ │ │ ARTIFACTS │ Creates proposal → specs → design → tasks │ │ │ │ (based on schema dependencies) │ │ └───────┬────────┘ │ diff --git a/docs/getting-started.md b/docs/getting-started.md index e3912722c..6f4b88862 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,33 +4,22 @@ This guide explains how OpenSpec works after you've installed and initialized it ## How It Works -OpenSpec helps you and your AI coding assistant agree on what to build before any code is written. The workflow follows a simple pattern: +OpenSpec helps you and your AI coding assistant agree on what to build before any code is written. +**Default quick path (core profile):** + +```text +/opsx:propose ──► /opsx:apply ──► /opsx:archive ``` -┌────────────────────┐ -│ Start a Change │ /opsx:new -└────────┬───────────┘ - │ - ▼ -┌────────────────────┐ -│ Create Artifacts │ /opsx:ff or /opsx:continue -│ (proposal, specs, │ -│ design, tasks) │ -└────────┬───────────┘ - │ - ▼ -┌────────────────────┐ -│ Implement Tasks │ /opsx:apply -│ (AI writes code) │ -└────────┬───────────┘ - │ - ▼ -┌────────────────────┐ -│ Archive & Merge │ /opsx:archive -│ Specs │ -└────────────────────┘ + +**Expanded path (custom workflow selection):** + +```text +/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive ``` +The default global profile is `core`, which includes `propose`, `explore`, `apply`, and `archive`. You can enable the expanded workflow commands with `openspec config profile` and then `openspec update`. + ## What OpenSpec Creates After running `openspec init`, your project has this structure: @@ -131,23 +120,12 @@ The change folder moves to `openspec/changes/archive/` for audit history. Let's walk through adding dark mode to an application. -### 1. Start the Change +### 1. Start the Change (Default) -``` -You: /opsx:new add-dark-mode +```text +You: /opsx:propose add-dark-mode AI: Created openspec/changes/add-dark-mode/ - Ready to create: proposal -``` - -### 2. Create Artifacts - -Use `/opsx:ff` (fast-forward) to create all planning artifacts at once: - -``` -You: /opsx:ff - -AI: Creating artifacts for add-dark-mode... ✓ proposal.md — why we're doing this, what's changing ✓ specs/ — requirements and scenarios ✓ design.md — technical approach @@ -155,7 +133,9 @@ AI: Creating artifacts for add-dark-mode... Ready for implementation! ``` -### 3. What Gets Created +If you've enabled the expanded workflow profile, you can also do this as two steps: `/opsx:new` then `/opsx:ff` (or `/opsx:continue` incrementally). + +### 2. What Gets Created **proposal.md** - Captures the intent: @@ -218,7 +198,7 @@ The system SHALL allow users to choose between light and dark themes. - [ ] 3.2 Update components to use CSS variables ``` -### 4. Implement +### 3. Implement ``` You: /opsx:apply @@ -234,7 +214,7 @@ AI: Working through tasks... During implementation, if you discover the design needs adjustment, just update the artifact and continue. -### 5. Archive +### 4. Archive ``` You: /opsx:archive diff --git a/docs/migration-guide.md b/docs/migration-guide.md index 970b6b1d1..5091ce438 100644 --- a/docs/migration-guide.md +++ b/docs/migration-guide.md @@ -8,7 +8,7 @@ OPSX replaces the old phase-locked workflow with a fluid, action-based approach. | Aspect | Legacy | OPSX | |--------|--------|------| -| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `/opsx:new`, `/opsx:continue`, `/opsx:apply`, and more | +| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:apply`, `/opsx:archive` (expanded workflow commands optional) | | **Workflow** | Create all artifacts at once | Create incrementally or all at once—your choice | | **Going back** | Awkward phase gates | Natural—update any artifact anytime | | **Customization** | Fixed structure | Schema-driven, fully hackable | @@ -84,6 +84,9 @@ Don't worry about getting it perfect. We're still learning what works best here, Both `openspec init` and `openspec update` detect legacy files and guide you through the same cleanup process. Use whichever fits your situation: +- New installs default to profile `core` (`propose`, `explore`, `apply`, `archive`). +- Migrated installs preserve your previously installed workflows by writing a `custom` profile when needed. + ### Using `openspec init` Run this if you want to add new tools or reconfigure which tools are set up: @@ -141,7 +144,7 @@ Run this if you just want to migrate and refresh your existing tools to the late openspec update ``` -The update command also detects and cleans up legacy artifacts, then refreshes your skills to the latest version. +The update command also detects and cleans up legacy artifacts, then refreshes generated skills/commands to match your current profile and delivery settings. ### Non-Interactive / CI Environments @@ -275,30 +278,43 @@ The AI will help you identify what's essential vs. what can be trimmed. ## The New Commands -After migration, you have 9 OPSX commands instead of 3: +Command availability is profile-dependent: + +**Default (`core` profile):** | Command | Purpose | |---------|---------| +| `/opsx:propose` | Create a change and generate planning artifacts in one step | | `/opsx:explore` | Think through ideas with no structure | -| `/opsx:new` | Start a new change | -| `/opsx:continue` | Create the next artifact (one at a time) | -| `/opsx:ff` | Fast-forward—create all planning artifacts at once | | `/opsx:apply` | Implement tasks from tasks.md | -| `/opsx:verify` | Validate implementation matches specs | -| `/opsx:sync` | Preview spec merge (optional—archive prompts if needed) | | `/opsx:archive` | Finalize and archive the change | + +**Expanded workflow (custom selection):** + +| Command | Purpose | +|---------|---------| +| `/opsx:new` | Start a new change scaffold | +| `/opsx:continue` | Create the next artifact (one at a time) | +| `/opsx:ff` | Fast-forward—create planning artifacts at once | +| `/opsx:verify` | Validate implementation matches specs | +| `/opsx:sync` | Preview/spec-merge without archiving | | `/opsx:bulk-archive` | Archive multiple changes at once | +| `/opsx:onboard` | Guided end-to-end onboarding workflow | + +Enable expanded commands with `openspec config profile`, then run `openspec update`. ### Command Mapping from Legacy | Legacy | OPSX Equivalent | |--------|-----------------| -| `/openspec:proposal` | `/opsx:new` then `/opsx:ff` | +| `/openspec:proposal` | `/opsx:propose` (default) or `/opsx:new` then `/opsx:ff` (expanded) | | `/openspec:apply` | `/opsx:apply` | | `/openspec:archive` | `/opsx:archive` | ### New Capabilities +These capabilities are part of the expanded workflow command set. + **Granular artifact creation:** ``` /opsx:continue @@ -542,9 +558,10 @@ project/ │ └── config.yaml # NEW: Project configuration ├── .claude/ │ └── skills/ # NEW: OPSX skills +│ ├── openspec-propose/ # default core profile │ ├── openspec-explore/ -│ ├── openspec-new-change/ -│ └── ... +│ ├── openspec-apply-change/ +│ └── ... # expanded profile adds new/continue/ff/etc. ├── CLAUDE.md # OpenSpec markers removed, your content preserved └── AGENTS.md # OpenSpec markers removed, your content preserved ``` @@ -558,12 +575,15 @@ project/ ### Command Cheatsheet -``` -/opsx:new Start a change -/opsx:continue Create next artifact -/opsx:ff Create all planning artifacts +```text +/opsx:propose Start quickly (default core profile) /opsx:apply Implement tasks /opsx:archive Finish and archive + +# Expanded workflow (if enabled): +/opsx:new Scaffold a change +/opsx:continue Create next artifact +/opsx:ff Create planning artifacts ``` --- diff --git a/docs/opsx.md b/docs/opsx.md index 4d26005c4..9607b7d06 100644 --- a/docs/opsx.md +++ b/docs/opsx.md @@ -65,6 +65,8 @@ openspec init This creates skills in `.claude/skills/` (or equivalent) that AI coding assistants auto-detect. +By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `archive`). If you want the expanded workflow commands (`new`, `continue`, `ff`, `verify`, `sync`, `bulk-archive`, `onboard`), configure them with `openspec config profile` and apply with `openspec update`. + During setup, you'll be prompted to create a **project config** (`openspec/config.yaml`). This is optional but recommended. ## Project Configuration @@ -155,13 +157,17 @@ rules: | Command | What it does | |---------|--------------| +| `/opsx:propose` | Create a change and generate planning artifacts in one step (default quick path) | | `/opsx:explore` | Think through ideas, investigate problems, clarify requirements | -| `/opsx:new` | Start a new change | -| `/opsx:continue` | Create the next artifact (based on what's ready) | -| `/opsx:ff` | Fast-forward — create all planning artifacts at once | +| `/opsx:new` | Start a new change scaffold (expanded workflow) | +| `/opsx:continue` | Create the next artifact (expanded workflow) | +| `/opsx:ff` | Fast-forward planning artifacts (expanded workflow) | | `/opsx:apply` | Implement tasks, updating artifacts as needed | -| `/opsx:sync` | Sync delta specs to main (optional—archive prompts if needed) | +| `/opsx:verify` | Validate implementation against artifacts (expanded workflow) | +| `/opsx:sync` | Sync delta specs to main (expanded workflow, optional) | | `/opsx:archive` | Archive when done | +| `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) | +| `/opsx:onboard` | Guided walkthrough of an end-to-end change (expanded workflow) | ## Usage @@ -169,13 +175,21 @@ rules: ``` /opsx:explore ``` -Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:new` or `/opsx:ff`. +Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:propose` (default) or `/opsx:new`/`/opsx:ff` (expanded). ### Start a new change ``` -/opsx:new +/opsx:propose +``` +Creates the change and generates planning artifacts needed before implementation. + +If you've enabled expanded workflows, you can instead use: + +```text +/opsx:new # scaffold only +/opsx:continue # create one artifact at a time +/opsx:ff # create all planning artifacts at once ``` -You'll be asked what you want to build and which workflow schema to use. ### Create artifacts ``` @@ -299,6 +313,7 @@ Think of it like git branches: ## Architecture Deep Dive This section explains how OPSX works under the hood and how it compares to the legacy workflow. +Examples in this section use the expanded command set (`new`, `continue`, etc.); default `core` users can map the same flow to `propose → apply → archive`. ### Philosophy: Phases vs Actions @@ -356,7 +371,7 @@ This section explains how OPSX works under the hood and how it compares to the l │ Hardcoded Templates (TypeScript strings) │ │ │ │ │ ▼ │ -│ Configurators (18+ classes, one per editor) │ +│ Tool-specific configurators/adapters │ │ │ │ │ ▼ │ │ Generated Command Files (.claude/commands/openspec/*.md) │ @@ -604,7 +619,7 @@ artifacts: | **State** | Phase-based mental model | Filesystem existence | | **Customization** | Edit source, rebuild | Create schema.yaml | | **Iteration** | Phase-locked | Fluid, edit anything | -| **Editor Support** | 18+ configurator classes | Single skills directory | +| **Editor Support** | Tool-specific configurator/adapters | Single skills directory | ## Schemas diff --git a/docs/supported-tools.md b/docs/supported-tools.md index 6c1a5a4a1..2d7e10975 100644 --- a/docs/supported-tools.md +++ b/docs/supported-tools.md @@ -1,50 +1,58 @@ # Supported Tools -OpenSpec works with 20+ AI coding assistants. When you run `openspec init`, you'll be prompted to select which tools you use, and OpenSpec will configure the appropriate integrations. +OpenSpec works with many AI coding assistants. When you run `openspec init`, OpenSpec configures selected tools using your active profile/workflow selection and delivery mode. ## How It Works -For each tool you select, OpenSpec installs: +For each selected tool, OpenSpec can install: -1. **Skills** — Reusable instruction files that power the `/opsx:*` workflow commands -2. **Commands** — Tool-specific slash command bindings +1. **Skills** (if delivery includes skills): `.../skills/openspec-*/SKILL.md` +2. **Commands** (if delivery includes commands): tool-specific `opsx-*` command files + +By default, OpenSpec uses the `core` profile, which includes: +- `propose` +- `explore` +- `apply` +- `archive` + +You can enable expanded workflows (`new`, `continue`, `ff`, `verify`, `sync`, `bulk-archive`, `onboard`) via `openspec config profile`, then run `openspec update`. ## Tool Directory Reference -| Tool | Skills Location | Commands Location | -|------|-----------------|-------------------| -| Amazon Q Developer | `.amazonq/skills/` | `.amazonq/prompts/` | -| Antigravity | `.agent/skills/` | `.agent/workflows/` | -| Auggie (Augment CLI) | `.augment/skills/` | `.augment/commands/` | -| Claude Code | `.claude/skills/` | `.claude/commands/opsx/` | -| Cline | `.cline/skills/` | `.clinerules/workflows/` | -| CodeBuddy | `.codebuddy/skills/` | `.codebuddy/commands/opsx/` | -| Codex | `.codex/skills/` | `~/.codex/prompts/`\* | -| Continue | `.continue/skills/` | `.continue/prompts/` | -| CoStrict | `.cospec/skills/` | `.cospec/openspec/commands/` | -| Crush | `.crush/skills/` | `.crush/commands/opsx/` | -| Cursor | `.cursor/skills/` | `.cursor/commands/` | -| Factory Droid | `.factory/skills/` | `.factory/commands/` | -| Gemini CLI | `.gemini/skills/` | `.gemini/commands/opsx/` | -| GitHub Copilot | `.github/skills/` | `.github/prompts/`\*\* | -| iFlow | `.iflow/skills/` | `.iflow/commands/` | -| Kilo Code | `.kilocode/skills/` | `.kilocode/workflows/` | -| Kiro | `.kiro/skills/` | `.kiro/prompts/` | -| OpenCode | `.opencode/skills/` | `.opencode/command/` | -| Pi | `.pi/skills/` | `.pi/prompts/` | -| Qoder | `.qoder/skills/` | `.qoder/commands/opsx/` | -| Qwen Code | `.qwen/skills/` | `.qwen/commands/` | -| RooCode | `.roo/skills/` | `.roo/commands/` | -| Trae | `.trae/skills/` | `.trae/skills/` (via `/openspec-*`) | -| Windsurf | `.windsurf/skills/` | `.windsurf/workflows/` | - -\* Codex commands are installed to the global home directory (`~/.codex/prompts/` or `$CODEX_HOME/prompts/`), not the project directory. - -\*\* GitHub Copilot's `.github/prompts/*.prompt.md` files are recognized as custom slash commands in **IDE extensions only** (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompts from this directory — see [github/copilot-cli#618](https://github.com/github/copilot-cli/issues/618). If you use Copilot CLI, you may need to manually set up [custom agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents) in `.github/agents/` as a workaround. +| Tool (ID) | Skills path pattern | Command path pattern | +|-----------|---------------------|----------------------| +| Amazon Q Developer (`amazon-q`) | `.amazonq/skills/openspec-*/SKILL.md` | `.amazonq/prompts/opsx-.md` | +| Antigravity (`antigravity`) | `.agent/skills/openspec-*/SKILL.md` | `.agent/workflows/opsx-.md` | +| Auggie (`auggie`) | `.augment/skills/openspec-*/SKILL.md` | `.augment/commands/opsx-.md` | +| Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/.md` | +| Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-.md` | +| CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/.md` | +| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-.md`\* | +| Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-.prompt` | +| CoStrict (`costrict`) | `.cospec/skills/openspec-*/SKILL.md` | `.cospec/openspec/commands/opsx-.md` | +| Crush (`crush`) | `.crush/skills/openspec-*/SKILL.md` | `.crush/commands/opsx/.md` | +| Cursor (`cursor`) | `.cursor/skills/openspec-*/SKILL.md` | `.cursor/commands/opsx-.md` | +| Factory Droid (`factory`) | `.factory/skills/openspec-*/SKILL.md` | `.factory/commands/opsx-.md` | +| Gemini CLI (`gemini`) | `.gemini/skills/openspec-*/SKILL.md` | `.gemini/commands/opsx/.toml` | +| GitHub Copilot (`github-copilot`) | `.github/skills/openspec-*/SKILL.md` | `.github/prompts/opsx-.prompt.md`\*\* | +| iFlow (`iflow`) | `.iflow/skills/openspec-*/SKILL.md` | `.iflow/commands/opsx-.md` | +| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilocode/workflows/opsx-.md` | +| Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-.prompt.md` | +| OpenCode (`opencode`) | `.opencode/skills/openspec-*/SKILL.md` | `.opencode/command/opsx-.md` | +| Pi (`pi`) | `.pi/skills/openspec-*/SKILL.md` | `.pi/prompts/opsx-.md` | +| Qoder (`qoder`) | `.qoder/skills/openspec-*/SKILL.md` | `.qoder/commands/opsx/.md` | +| Qwen Code (`qwen`) | `.qwen/skills/openspec-*/SKILL.md` | `.qwen/commands/opsx-.toml` | +| RooCode (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-.md` | +| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) | +| Windsurf (`windsurf`) | `.windsurf/skills/openspec-*/SKILL.md` | `.windsurf/workflows/opsx-.md` | + +\* Codex commands are installed in the global Codex home (`$CODEX_HOME/prompts/` if set, otherwise `~/.codex/prompts/`), not your project directory. + +\*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly. ## Non-Interactive Setup -For CI/CD or scripted setup, use the `--tools` flag: +For CI/CD or scripted setup, use `--tools` (and optionally `--profile`): ```bash # Configure specific tools @@ -55,34 +63,40 @@ openspec init --tools all # Skip tool configuration openspec init --tools none + +# Override profile for this init run +openspec init --profile core ``` -**Available tool IDs:** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codebuddy`, `codex`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `kiro`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf` +**Available tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codex`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `kiro`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf` + +## Workflow-Dependent Installation -## What Gets Installed +OpenSpec installs workflow artifacts based on selected workflows: -For each tool, OpenSpec generates 10 skill files that power the OPSX workflow: +- **Core profile (default):** `propose`, `explore`, `apply`, `archive` +- **Custom selection:** any subset of all workflow IDs: + `propose`, `explore`, `new`, `continue`, `apply`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard` -| Skill | Purpose | -|-------|---------| -| `openspec-explore` | Thinking partner for exploring ideas | -| `openspec-new-change` | Start a new change | -| `openspec-continue-change` | Create the next artifact | -| `openspec-ff-change` | Fast-forward through all planning artifacts | -| `openspec-apply-change` | Implement tasks | -| `openspec-verify-change` | Verify implementation completeness | -| `openspec-sync-specs` | Sync delta specs to main (optional—archive prompts if needed) | -| `openspec-archive-change` | Archive a completed change | -| `openspec-bulk-archive-change` | Archive multiple changes at once | -| `openspec-onboard` | Guided onboarding through a complete workflow cycle | +In other words, skill/command counts are profile-dependent and delivery-dependent, not fixed. -These skills are invoked via slash commands like `/opsx:new`, `/opsx:apply`, etc. See [Commands](commands.md) for the full list. +## Generated Skill Names -## Adding a New Tool +When selected by profile/workflow config, OpenSpec generates these skills: -Want to add support for another AI coding assistant? Check out the [command adapter pattern](../CONTRIBUTING.md) or open an issue on GitHub. +- `openspec-propose` +- `openspec-explore` +- `openspec-new-change` +- `openspec-continue-change` +- `openspec-apply-change` +- `openspec-ff-change` +- `openspec-sync-specs` +- `openspec-archive-change` +- `openspec-bulk-archive-change` +- `openspec-verify-change` +- `openspec-onboard` ---- +See [Commands](commands.md) for command behavior and [CLI](cli.md) for `init`/`update` options. ## Related diff --git a/docs/workflows.md b/docs/workflows.md index 8aac9df12..6cfd7e063 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -28,7 +28,32 @@ OPSX (fluid actions): > **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas. -## Workflow Patterns +## Two Modes + +### Default Quick Path (`core` profile) + +New installs default to `core`, which provides: +- `/opsx:propose` +- `/opsx:explore` +- `/opsx:apply` +- `/opsx:archive` + +Typical flow: + +```text +/opsx:propose ──► /opsx:apply ──► /opsx:archive +``` + +### Expanded/Full Workflow (custom selection) + +If you want explicit scaffold-and-build commands (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:sync`, `/opsx:bulk-archive`, `/opsx:onboard`), enable them with: + +```bash +openspec config profile +openspec update +``` + +## Workflow Patterns (Expanded Mode) ### Quick Feature @@ -408,15 +433,16 @@ 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:new` | Start a change | Beginning any new work | -| `/opsx:continue` | Create next artifact | Step-by-step artifact creation | -| `/opsx:ff` | Create all planning artifacts | Clear scope, ready to build | +| `/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 | | `/opsx:apply` | Implement tasks | Ready to write code | -| `/opsx:verify` | Validate implementation | Before archiving, catch mismatches | -| `/opsx:sync` | Merge delta specs | Optional—archive prompts if needed | +| `/opsx:verify` | Validate implementation | Expanded mode, before archiving | +| `/opsx:sync` | Merge delta specs | Expanded mode, optional | | `/opsx:archive` | Complete the change | All work finished | -| `/opsx:bulk-archive` | Archive multiple changes | Parallel work, batch completion | +| `/opsx:bulk-archive` | Archive multiple changes | Expanded mode, parallel work | ## Next Steps