# https://github.com/Fission-AI/OpenSpec 项目说明书 生成时间：2026-05-18 02:52:58 UTC ## 目录 - [Introduction to OpenSpec](#introduction) - [Getting Started](#getting-started) - [System Architecture](#architecture) - [Slash Commands](#slash-commands) - [Workflows](#workflows) - [Artifact Graph System](#artifact-graph) - [Schemas](#schemas) - [Configuration](#configuration) - [Validation System](#validation-system) - [Supported AI Tools](#supported-tools) ## Introduction to OpenSpec ### 相关页面 相关主题：[Getting Started](#getting-started), [System Architecture](#architecture)
Relevant Source Files 以下源码文件用于生成本页说明： - [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) - [CHANGELOG.md](https://github.com/Fission-AI/OpenSpec/blob/main/CHANGELOG.md) - [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md) - [docs/concepts.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md) - [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md) - [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md) - [docs/supported-tools.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/supported-tools.md)
# Introduction to OpenSpec OpenSpec is a lightweight specification framework designed to bring structure and alignment to AI-assisted software development. It establishes a shared understanding between human developers and AI coding assistants before any code is written, reducing unpredictability and improving project organization. ## Purpose and Scope AI coding assistants are powerful but often unpredictable when project requirements exist only in chat history. OpenSpec adds a lightweight spec layer that ensures human and AI align on specifications before code gets written. The framework operates under a core philosophy: ```text → fluid not rigid → iterative not waterfall → easy not complex → built for brownfield not just greenfield → scalable from personal projects to enterprises ``` **资料来源：** [README.md:1-20]() ## Core Features OpenSpec provides several key capabilities: | Feature | Description | |---------|-------------| | **Agree Before Build** | Human and AI align on specs before code gets written | | **Stay Organized** | Each change gets its own folder with proposal, specs, design, and tasks | | **Work Fluidly** | Update any artifact anytime, no rigid phase gates | | **Tool Integration** | Works with 25+ AI assistants via slash commands | **资料来源：** [README.md:21-30]() ## Architecture Overview OpenSpec uses an artifact-guided workflow where changes are organized into structured folders. The system tracks dependencies between artifacts and automatically manages state transitions. ```mermaid graph TD A[User Request] --> B[Proposal] B --> C[Specs] C --> D[Design] D --> E[Tasks] E --> F[Implementation] F --> G[Archive] G --> C H[Config.yaml] --> A H --> B H --> C style A fill:#e1f5fe style G fill:#c8e6c9 ``` **资料来源：** [CHANGELOG.md:1-30]() ## The Change Structure Every change in OpenSpec follows a consistent folder structure: ``` openspec/ ├── specs/ # Source-of-truth specifications │ └── / │ └── spec.md ├── changes/ │ ├── / # Active change folder │ │ ├── proposal.md # Why and what changes │ │ ├── tasks.md # Implementation checklist │ │ ├── design.md # Technical decisions (optional) │ │ └── specs/ │ │ └── / │ │ └── spec.md # Delta showing additions/modifications │ └── archive/ # Completed changes │ └── YYYY-MM-DD-/ └── config.yaml # Project configuration ``` **资料来源：** [README.md:200-230]() ## Workflow System OpenSpec supports multiple workflow approaches: ### Standard Workflow The traditional linear approach: 1. **Propose** - Create a change proposal that captures spec updates 2. **Review** - Review the proposal with AI assistant until agreement 3. **Implement** - Implement tasks that reference agreed specs 4. **Archive** - Archive the change to merge approved updates back into source specs ### Experimental Workflow The new artifact-guided workflow using slash commands: | Command | Purpose | |---------|---------| | `/opsx:propose` | Start a new change | | `/opsx:new` | Start a new change (alternative) | | `/opsx:continue` | Create one artifact at a time (step-through) | | `/opsx:ff` | Fast-forward to completion | | `/opsx:verify` | Verify artifact integrity | | `/opsx:bulk-archive` | Archive multiple changes | | `/opsx:onboard` | Initialize OpenSpec in a project | **资料来源：** [README.md:150-170]() ## Instruction System OpenSpec dynamically assembles instructions from three layers: ```mermaid graph LR A[Context] --> D[Enriched Instruction] B[Rules] --> D C[Template] --> D A1[project.yaml] --> A B1[Artifact-specific] --> B C1[Schema template] --> C ``` ### Context Layer Project background from `config.yaml` including tech stack and conventions. Applied to **all artifacts**. ### Rules Layer Artifact-specific constraints (e.g., "propose spike tasks for unknowns"). Applied only to **matching artifacts**. ### Template Layer The actual structure for the output file, sourced from schemas. **资料来源：** [CHANGELOG.md:40-70]() ## Supported AI Tools OpenSpec integrates with 25+ AI coding assistants through slash commands or natural language: ### Native Slash Commands | Tool | Commands | Configuration Path | |------|----------|-------------------| | **Claude Code** | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | Built-in | | **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` | | **CodeBuddy Code** | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | `.codebuddy/commands/` | | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` | | **Roo Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` | ### Workflow-Based Tools | Tool | Workflow Location | |------|-------------------| | **Cline** | `.clinerules/workflows/` | | **Windsurf** | `.windsurf/workflows/` | | **Kilo Code** | `.kilocode/workflows/` | **资料来源：** [README.md:80-120]() ## Installation and Setup ### Prerequisites - **Node.js >= 20.19.0** - Check with `node --version` ### Installation Methods **Option A: npm (Global)** ```bash npm install -g @fission-ai/openspec@latest ``` **Option B: nix (NixOS)** ```bash nix run github:Fission-AI/OpenSpec -- init ``` Or install to profile: ```bash nix profile install github:Fission-AI/OpenSpec ``` **资料来源：** [README.md:50-80]() ### Quick Start ```bash # Navigate to project cd your-project # Initialize OpenSpec openspec init # Start a new change /opsx:propose # Or use CLI directly openspec new ``` **资料来源：** [README.md:40-55]() ## Command Reference | Command | Description | |---------|-------------| | `openspec list` | View active change folders | | `openspec view` | Interactive dashboard of specs and changes | | `openspec show ` | Display change details | | `openspec validate ` | Check spec formatting and structure | | `openspec archive [--yes]` | Archive completed change | | `openspec config profile` | Select workflow profile | **资料来源：** [README.md:180-200]() ## Telemetry OpenSpec collects anonymous usage statistics to understand usage patterns: - **Collected:** Command names and version only - **NOT collected:** Arguments, paths, content, or PII - **Auto-disabled:** In CI environments **Opt-out:** ```bash export OPENSPEC_TELEMETRY=0 # or export DO_NOT_TRACK=1 ``` **资料来源：** [README.md:220-240]() ## Contributing to OpenSpec ```bash # Install dependencies pnpm install # Build pnpm run build # Test pnpm test # Develop CLI locally pnpm run dev pnpm run dev:cli ``` **Commit convention:** ```text type(scope): subject ``` **资料来源：** [README.md:250-260]() ## License OpenSpec is released under the **MIT License**. --- ## Getting Started ### 相关页面 相关主题：[Introduction to OpenSpec](#introduction), [Slash Commands](#slash-commands)
Relevant Source Files 以下源码文件用于生成本页说明： - [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) - [docs/getting-started.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md) - [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md) - [docs/cli.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md) - [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md) - [docs/installation.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/installation.md) - [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md)
# Getting Started ## Overview OpenSpec is a lightweight specification framework designed to help development teams align on requirements before writing code. It provides a structured approach to capturing proposals, specifications, designs, and implementation tasks in organized change folders that integrate seamlessly with AI coding assistants. The "Getting Started" documentation serves as the entry point for new users, covering prerequisites, installation methods, project initialization, and the fundamental workflows that define how OpenSpec operates. This guide ensures users can quickly set up OpenSpec in their development environment and begin using its artifact-guided workflow for managing changes systematically. ## Prerequisites ### System Requirements OpenSpec has specific version requirements that must be met before installation: | Requirement | Minimum Version | Notes | |------------|-----------------|-------| | Node.js | 20.19.0 or higher | Check with `node --version` | | Package Managers | npm, pnpm, yarn, bun, or nix | Alternative installation options available | 资料来源：[README.md:1]() To verify your Node.js installation, run: ```bash node --version ``` If the version is below 20.19.0, you must upgrade Node.js before proceeding with OpenSpec installation. ## Installation OpenSpec can be installed through multiple methods depending on your development environment and preferences. ### Method 1: npm (Global Installation) The standard installation method uses npm to install OpenSpec globally: ```bash npm install -g @fission-ai/openspec@latest ``` After installation, verify the installation by checking the version: ```bash openspec --version ``` 资料来源：[README.md:1]() ### Method 2: Nix Package Manager For NixOS or Nix package manager users, OpenSpec can be run directly without explicit installation: ```bash nix run github:Fission-AI/OpenSpec -- init ``` Alternatively, install to your user profile: ```bash nix profile install github:Fission-AI/OpenSpec ``` Or add to your Nix configuration for persistent access. ### Method 3: Development Installation For contributors or those who want to work with the source code: ```bash # Clone the repository git clone https://github.com/Fission-AI/OpenSpec.git cd OpenSpec # Install dependencies pnpm install # Build the project pnpm run build # Run tests pnpm test # Develop CLI locally pnpm run dev ``` 资料来源：[README.md:1]() ## Project Initialization Once OpenSpec is installed, navigate to your project directory and initialize the OpenSpec structure: ```bash cd your-project openspec init ``` The initialization process creates the necessary directory structure for OpenSpec artifacts: ```text openspec/ ├── config.yaml # Project configuration and context ├── specs/ # Schema definitions and templates └── changes/ # Individual change proposals ``` ### What `openspec init` Creates | Artifact | Purpose | |----------|---------| | `config.yaml` | Project context, tech stack, conventions | | `openspec/schemas/` | Schema definitions (spec-driven, etc.) | | `openspec/changes/` | Directory for change proposals | ### Legacy Cleanup When running `openspec init` in an existing project that previously used OpenSpec, the initialization process detects and handles legacy artifacts: - Old slash command directories (`.claude/commands/openspec/`) - Config files with OpenSpec markers (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`) - Legacy `openspec/AGENTS.md` files Users are prompted for confirmation before removing these legacy artifacts. 资料来源：[README.md:1]() 资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md:1]() ## Core Workflow: Artifact-Guided Approach OpenSpec uses an experimental artifact-guided workflow centered on creating structured changes. The workflow revolves around four key artifacts that capture different aspects of a change: ```mermaid graph TD A[Propose Change] --> B[Create Proposal] B --> C[Write Specs] C --> D[Design Solution] D --> E[Define Tasks] E --> F[Implement] F --> G[Verify] G --> H[Archive] I[Iterate on Any Artifact] -.-> A I -.-> B I -.-> C I -.-> D I -.-> E ``` ### The Four Core Artifacts | Artifact | Purpose | Generated By | |----------|---------|--------------| | **Proposal** | Why the change is needed, what's changing | `/opsx:propose` | | **Specs** | Requirements and acceptance scenarios | Sequential creation | | **Design** | Technical approach and architecture | Sequential creation | | **Tasks** | Implementation checklist | Sequential creation | Each change folder under `openspec/changes//` contains these artifacts organized in a predictable structure. 资料来源：[README.md:1]() ## Supported AI Coding Assistants OpenSpec integrates with over 25 AI coding assistants through slash commands. The supported tools include: | Tool Category | Examples | |--------------|----------| | Claude Code | `/openspec/proposal`, `/openspec/apply`, `/openspec/archive` | | Cursor | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | | CodeBuddy | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | | Codex | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | | RooCode | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | | Kilo Code | `.kilocode/workflows/` with `/openspec-proposal.md` | | Windsurf | `.windsurf/workflows/` with `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | | Continue | `.continue/` with custom configuration | | Cline | `CLAUDE.md` compatible | | Other | Works with natural language requests | To check if your tool is supported, view the [full list of supported tools](docs/supported-tools.md). 资料来源：[README.md:1]() 资料来源 [docs/supported-tools.md]() ## Essential Commands ### Quick Command Reference | Command | Description | |---------|-------------| | `openspec list` | View active change folders | | `openspec view` | Interactive dashboard of specs and changes | | `openspec show ` | Display change details | | `openspec update` | Refresh slash command files | | `openspec config profile` | Switch between standard and experimental workflows | | `openspec archive ` | Archive a completed change | 资料来源：[README.md:1]() 资料来源 [docs/cli.md]() ## The Experimental Workflow OpenSpec offers an experimental artifact-guided workflow that provides a more flexible, iterative approach to managing changes. ### Enabling Experimental Features ```bash openspec experimental ``` ### Experimental Slash Commands | Command | Purpose | |---------|---------| | `/opsx:propose` | Start a new change | | `/opsx:new` | Create a new change folder | | `/opsx:continue` | Create the next artifact in sequence | | `/opsx:ff` | Fast-forward through completed tasks | | `/opsx:verify` | Verify implementation against specs | | `/opsx:bulk-archive` | Archive multiple completed changes | | `/opsx:onboard` | Set up OpenSpec in a new project | | `/opsx:explore` | Think through ideas before committing | 资料来源 [docs/opsx.md]() ### Workflow Comparison | Aspect | Standard Workflow | Experimental Workflow | |--------|------------------|----------------------| | Artifact creation | Manual/guided | Sequential with dependencies | | State tracking | File-based | Dynamic artifact graph | | Flexibility | Phase-locked | Action-based | | Iteration | Limited | Full iteration support | ## Telemetry OpenSpec collects anonymous usage statistics to understand usage patterns. Only command names and version numbers are collected—no arguments, paths, content, or personally identifiable information. **To opt out:** ```bash export OPENSPEC_TELEMETRY=0 ``` Or set the `DO_NOT_TRACK` environment variable: ```bash export DO_NOT_TRACK=1 ``` Telemetry is automatically disabled in CI environments. 资料来源：[README.md:1]() ## Next Steps After completing the initial setup: 1. **Review Documentation** - [Workflows](docs/workflows.md) - Combos and patterns - [Commands](docs/commands.md) - Slash commands & skills - [Concepts](docs/concepts.md) - How OpenSpec fits together 2. **Try the Workflow** - Create your first proposal using `/opsx:propose` - Work through the artifact sequence - Archive and review the result 3. **Configure Your Tool** - Set up slash commands for your preferred AI assistant - Run `openspec update` to refresh command files 4. **Explore Advanced Features** - Multi-language support: [docs/multi-language.md](docs/multi-language.md) - Customization options: [docs/customization.md](docs/customization.md) - Community schemas: Browse the catalog in customization docs ## Troubleshooting ### Common Issues | Issue | Solution | |-------|----------| | Node.js version too low | Upgrade to 20.19.0 or higher | | Command not found | Verify installation with `openspec --version` | | Legacy artifacts remain | Run `openspec init` with `--force` flag | | Tool not responding | Check supported tools list and use natural language | ### Getting Help - Join the [OpenSpec Discord](https://discord.gg/YctCnvvshC) for questions - Follow [@0xTab on X](https://x.com/0xTab) for updates - Review archived changes in `openspec/changes/archive/` for examples --- ## System Architecture ### 相关页面 相关主题：[Introduction to OpenSpec](#introduction), [Artifact Graph System](#artifact-graph), [Workflows](#workflows)
相关源码文件 以下源码文件用于生成本页说明： - [openspec/changes/archive/2026-02-17-project-config/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/design.md) - [openspec/changes/archive/2025-12-28-add-instruction-loader/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-12-28-add-instruction-loader/design.md) - [openspec/changes/archive/2026-02-17-project-local-schemas/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-local-schemas/design.md) - [schemas/spec-driven/schema.yaml](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/schema.yaml) - [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md) - [openspec/changes/archive/2025-08-06-add-init-command/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-08-06-add-init-command/design.md)
# System Architecture OpenSpec is a lightweight specification framework designed to add a spec layer between human-AI alignment and code implementation. The system architecture enables teams to agree on what to build before any code is written, maintaining organization through structured change folders and dynamic instruction generation. ## Architecture Overview OpenSpec follows a modular architecture with clear separation between CLI interface, core business logic, and artifact management. The framework is designed to be tool-agnostic, supporting 25+ AI assistants through slash commands and natural language processing. ```mermaid graph TD subgraph "CLI Layer" CLI[CLI Entry Point] Commands[Slash Commands] end subgraph "Core Layer" Config[Project Config] Schemas[Schema System] Artifacts[Artifact Graph] Instructions[Instruction Loader] end subgraph "Change Management" Changes[Change Folders] Proposals[Proposals] Specs[Specs] Designs[Designs] Tasks[Tasks] end CLI --> Commands Commands --> Artifacts Artifacts --> Instructions Instructions --> Config Instructions --> Schemas Artifacts --> Changes Changes --> Proposals Changes --> Specs Changes --> Designs Changes --> Tasks ``` ## Core Components ### CLI Interface The CLI serves as the entry point for all OpenSpec operations. It handles initialization, change management, and command execution across supported tools. | Command | Purpose | |---------|---------| | `openspec init` | Initialize OpenSpec in a project directory | | `openspec update` | Refresh generated instruction files | | `openspec list` | View active change folders | | `openspec show ` | Display change details | | `openspec archive ` | Archive completed changes | 资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:1-50]() ### Schema System Schemas define the workflow structure and artifact templates for OpenSpec changes. The system supports three schema sources: | Source | Path | Priority | |--------|------|----------| | Project | `openspec/schemas//` | Highest | | User | `~/.local/share/openspec/schemas//` | Middle | | Package | Built-in `@fission-ai/openspec` | Lowest | 资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:1-30]() **Schema Resolution Order:** 1. CLI `--schema` flag (explicit override) 2. `.openspec.yaml` in change directory (change-specific binding) 3. `openspec/config.yaml` schema field (project default) 4. `"spec-driven"` (hardcoded fallback) The default `spec-driven` schema includes artifacts: proposal, specs, design, and tasks. 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:1-50]() ## Artifact Graph System The artifact graph tracks dependencies between different artifacts and manages their creation state. This system replaces the old phase-locked workflow with a flexible action-based model. ### Artifact Types | Artifact | Generates | Dependencies | |----------|-----------|--------------| | proposal | proposal.md | None | | specs | specs/*.md | proposal | | design | design.md | proposal | | tasks | tasks.md | specs, design | ### Instruction Loading Instructions are dynamically assembled from three layers: ```mermaid graph LR A[Context] --> D[Enriched Instruction] B[Rules] --> D C[Template] --> D subgraph "Instruction Components" A B C end ``` 资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:1-30]() **Instruction Structure:** ```xml [Project context from config.yaml] - Rule 1 for specific artifact - Rule 2 for specific artifact ``` Rules only appear for the **specific artifact** they're configured for. Artifacts without rules (e.g., design, tasks) don't get a `` section. 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:50-100]() ## Project Configuration Project configuration is stored in `openspec/config.yaml` and provides shared context and rules across the entire project. ### Configuration Structure ```yaml context: | Tech stack: TypeScript, React Key conventions: ... schema: spec-driven rules: proposal: - Include rollback plan specs: - Use Given/When/Then format for scenarios ``` 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:100-150]() ### Design Decisions 1. **Config file location**: `openspec/config.yaml` in project root - Mirrors structure used by other tools (e.g., `.github/`) - Keeps OpenSpec-related files under one directory 2. **XML tags vs Markdown sections**: Use XML-style tags `` and `` - Clear delimiters that don't conflict with Markdown - Agents can easily parse structure 3. **Rules validation**: Warn on unknown artifact IDs, don't error - Future-proof for new artifact types - Non-breaking change for existing configs 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:150-200]() ## Command Workflow ### Modern Workflow (opsx) The new artifact-guided workflow provides flexible action-based interactions: | Command | What it does | |---------|--------------| | `/opsx:propose` | Start a new change with proposal | | `/opsx:continue` | Create one artifact at a time | | `/opsx:ff` | Fast-forward to next ready artifact | | `/opsx:verify` | Verify specs and update tasks | | `/opsx:bulk-archive` | Archive multiple changes | | `/opsx:onboard` | Initialize project for OpenSpec | 资料来源：[README.md:1-50]() ### Legacy Commands The legacy slash commands have been removed: - `/openspec:proposal` - **Removed** - `/openspec:apply` - **Removed** - `/openspec:archive` - **Removed** Tool-specific instruction files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `project.md`) are no longer generated. 资料来源：[CHANGELOG.md:1-30]() ## Change Lifecycle ```mermaid graph TD A[Create Change] --> B[Write Proposal] B --> C[Create Specs] C --> D[Write Design] D --> E[Implement Tasks] E --> F[Archive Change] G[Explore Ideas] -.-> A style A fill:#e1f5fe style F fill:#fff3e0 ``` ### Change Directory Structure ``` openspec/ ├── config.yaml # Project configuration ├── schemas/ # Project-local schemas │ └── / │ └── templates/ └── changes/ ├── / │ ├── proposal.md │ ├── specs/ │ │ └── *.md │ ├── design.md │ ├── tasks.md │ └── .openspec.yaml └── archive/ └── -/ ``` 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-30]() ## Data Flow Architecture ### Instruction Generation Flow ```mermaid sequenceDiagram participant User participant CLI participant Config participant Schema participant Loader participant Output User->>CLI: openspec instructions CLI->>Config: readProjectConfig() Config-->>CLI: context + rules CLI->>Schema: resolveSchemaForChange() Schema-->>CLI: schema name CLI->>Loader: loadInstructions(change, artifact) Loader->>Schema: getTemplate(artifact) Schema-->>Loader: baseInstructions Loader->>Config: getRulesForArtifact(artifact) Config-->>Loader: artifactRules Loader->>Output: enrichInstruction(context, rules, template) Output-->>User: Enriched instruction with XML sections ``` 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:200-250]() ### Schema Loading Priority When loading schemas, the system checks multiple locations in order: ```mermaid graph TD A[Schema Request] --> B{Project schemas dir?} B -->|Yes| C[Return project-local schema] B -->|No| D{User schemas dir?} D -->|Yes| E[Return user schema] D -->|No| F[Return package schema] C --> G[Schema found] E --> G F --> G ``` 资料来源：[openspec/changes/archive/2026-02-17-project-local-schemas/design.md:50-80]() ## Extensibility Points ### Slash Command Configuration Slash commands are managed through a `SlashCommandConfigurator` that handles multiple files per tool: - `getTargets()`: Expose targets with path and kind - `generateAll(projectPath, openspecDir)`: For init - `updateExisting(projectPath, openspecDir)`: For update 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:50-80]() ### Template System Templates are brief, actionable, and sourced from `openspec/README.md`. Each command body includes: - Guardrails: Ask 1-2 clarifying questions if needed - Step list tailored to workflow stage - Pointers to troubleshooting tips 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:30-50]() ## Security Considerations The implementation includes several security measures: | Concern | Mitigation | |---------|------------| | Path Traversal | Sanitize all user-provided paths | | File Permissions | Check write permissions before operations | | Existing Files | Never overwrite without explicit `--force` flag | | Template Injection | Sanitize user inputs in templates | 资料来源：[openspec/changes/archive/2025-08-06-add-init-command/design.md:50-70]() ## Performance and Caching Project config is read multiple times during a single command execution: 1. **Schema resolution** - To know which schema to use 2. **Instruction loading** - To inject context and rules Rules are validated lazily during instruction loading (not at config load time) because: - Schema isn't known at config load time (circular dependency) - Warnings shown when user actually uses the feature (better UX) - Validation warnings cached per session to avoid spam 资料来源：[openspec/changes/archive/2026-02-17-project-config/design.md:250-280]() ## Technology Stack | Component | Technology | |-----------|------------| | Runtime | Node.js 20.19.0+ | | Package Manager | npm, pnpm, yarn, bun, nix | | License | MIT | | Package | `@fission-ai/openspec` | 资料来源：[README.md:50-80]() --- ## Slash Commands ### 相关页面 相关主题：[Workflows](#workflows), [Getting Started](#getting-started), [Supported AI Tools](#supported-tools)
相关源码文件 以下源码文件用于生成本页说明： - [docs/commands.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md) - [docs/opsx.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md) - [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) - [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md) - [openspec/changes/archive/2025-09-29-add-slash-command-support/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/design.md) - [openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md)
# Slash Commands Slash Commands provide a convenient shorthand mechanism for invoking OpenSpec workflows directly from AI coding assistants. Instead of typing verbose natural language instructions, users can trigger specific OpenSpec actions through a single slash command invocation, streamlining the specification-driven development workflow. ## Overview OpenSpec integrates with over 20 AI coding assistants through native slash command support. These commands serve as shortcuts that invoke predefined workflow templates, allowing AI assistants to execute OpenSpec operations without requiring manual CLI invocation. The slash command system is built on two fundamental principles: 1. **Centralized Templates**: Command bodies are defined once and reused across all supported tools, ensuring consistency while allowing minimal per-tool adaptations. 2. **Per-Tool Organization**: Each AI assistant receives its commands in the format and location that tool natively recognizes. 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:1-20]() ## Supported Tools and Command Formats Different AI coding assistants use varying conventions for slash command naming and organization. The following table summarizes the supported tools and their respective command formats. | Tool | Commands | Storage Location | |------|----------|------------------| | **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.claude/commands/openspec/` | | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` | | **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.amazonq/prompts/` | | **CodeBuddy Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` | | **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` | | **Auggie** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.augment/commands/` | | **Roo Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.roo/commands/` | | **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` | | **Cline** | Workflows with `openspec-*` prefix | `.clinerules/workflows/` | 资料来源：[README.md:1-80]() ## Core Commands OpenSpec defines three primary slash commands that cover the essential workflow stages. ### Proposal Command The proposal command initiates a new change specification. When invoked, the AI assistant creates a dedicated change folder with the necessary artifact structure. ``` You: /openspec:propose add-dark-mode AI: Created openspec/changes/add-dark-mode/ ✓ proposal.md — why we're doing this, what's changing ✓ specs/ — requirements and scenarios ✓ design.md — technical approach ✓ tasks.md — implementation checklist Ready for implementation! ``` 资料来源：[README.md:1-30]() ### Apply Command The apply command transitions the workflow from specification to implementation. It reads the tasks from the change folder and executes them in sequence, marking each task as complete. ``` You: /opsx:apply AI: Implementing tasks... ✓ 1.1 Add theme context provider ✓ 1.2 Create toggle component ✓ 2.1 Add CSS variables ✓ 2.2 Wire up localStorage All tasks complete! ``` 资料来源：[README.md:1-30]() ### Archive Command The archive command finalizes a completed change by moving it to the archive directory and updating the source-of-truth specifications. ``` You: /openspec:archive AI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/ Specs updated. Ready for the next feature. ``` 资料来源：[README.md:1-30]() ## Command File Structure ### File Format and Metadata Slash command files are stored as Markdown with optional YAML frontmatter for tool-specific metadata. The frontmatter, when supported, includes fields such as `name`, `description`, and `category` or `tags`. ```yaml --- name: openspec-proposal description: Create a new OpenSpec change proposal category: OpenSpec --- ...command body content... ``` ### Marker Placement Rules The OpenSpec system uses marker comments (`` and ``) to delineate command bodies. These markers must adhere to strict placement rules: | Rule | Description | |------|-------------| | **Outside Frontmatter** | Markers must never appear inside YAML frontmatter | | **Body Delimitation** | Markers wrap only the visible command body content | | **Recovery Behavior** | Missing or duplicated markers trigger specific recovery behaviors | 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:30-45]() ### Naming Consistency To ensure predictable behavior across tools, the following naming elements must remain aligned: | Element | Example | |---------|---------| | Visible Slash Name | `proposal`, `apply`, `archive` | | File Name | `proposal.md`, `apply.md`, `archive.md` | | Frontmatter `name`/`id` | `id: openspec-proposal` | This alignment prevents user confusion and ensures the AI assistant can correctly invoke commands regardless of the tool being used. 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:50-70]() ## Architecture ### SlashCommandConfigurator The `SlashCommandConfigurator` is the core component responsible for managing slash command files across multiple tools. It abstracts the differences between tool-specific command formats and provides a unified interface for command generation and updates. ```typescript interface SlashCommandConfigurator { getTargets(): Array<{ path: string; kind: 'slash'; id: string; }>; generateAll(projectPath: string, openspecDir: string): void; updateExisting(projectPath: string, openspecDir: string): void; } ``` 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:80-95]() ### Design Principles The architecture follows several key principles that guide slash command implementation across all supported tools. ```mermaid graph TD A[Centralized Template Definition] --> B[Tool-Specific Adapter] B --> C[Claude Code Commands] B --> D[Cursor Commands] B --> E[Amazon Q Commands] B --> F[Other Tool Commands] G[Init Command] --> H[generateAll] G --> I[Creates All Tool Directories] J[Update Command] --> K[updateExisting] J --> L[Refreshes Only Existing Files] style A fill:#e1f5fe style G fill:#fff3e0 style J fill:#fff3e0 ``` 1. **Centralized Templates**: Command bodies are defined once in shared template files and applied across all tools with minimal per-tool wrappers. 2. **Per-File Refresh on Update**: During `openspec update`, the system refreshes only existing slash command files on a per-file basis. It does not create missing files or add support for new tools. 3. **Tool-Specific Directories**: Each AI assistant receives commands stored in its native configuration directory structure. 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:60-75]() ## Command Templates ### Template Content Structure Each slash command template contains several key sections that guide the AI assistant's behavior. | Section | Purpose | |---------|---------| | **Guardrails** | 1-2 clarifying questions if needed; minimal complexity rules; tool usage preferences | | **Step List** | Tailored workflow steps for the specific command stage | | **Pointers** | References to `openspec show`, `openspec list`, and troubleshooting tips | ### Claude Code Naming Convention Claude Code uses namespacing within the slash command itself for better readability and natural grouping: ``` /openspec/proposal /openspec/apply /openspec/archive ``` 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:20-35]() ### Other Tools Convention Most other tools use a flat naming convention with an `openspec-` prefix: ``` /openspec-proposal /openspec-apply /openspec-archive ``` Grouping is achieved through category metadata where supported (e.g., `category: OpenSpec`). ## Initialization and Updates ### Init Command Behavior When running `openspec init`, the system creates slash command directories for all supported tools: | Tool | Directory Created | |------|-------------------| | Claude Code | `.claude/commands/openspec/` | | Cursor | `.cursor/commands/` | | Amazon Q | `.amazonq/prompts/` | | Cline | `.clinerules/workflows/` | 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:25-30]() ### Update Command Behavior The `openspec update` command implements a conservative update strategy: 1. **Detection Phase**: Identify which tools already have slash command files installed 2. **Refresh Phase**: Update only the files that exist, refreshing both frontmatter and body content 3. **Preservation Phase**: Do not create missing files or add support for tools not already present ```mermaid graph LR A[openspec update] --> B{Detect Existing Tools} B --> C[Tool A: 2 files exist] B --> D[Tool B: 0 files exist] C --> E[Refresh Tool A Files] D --> F[Skip Tool B] E --> G[Update Frontmatter + Body] F --> H[No Changes] style E fill:#c8e6c9 style F fill:#ffcdd2 ``` 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/design.md:100-120]() ### Migration Handling When updating from legacy versions, the system handles backward compatibility: - **Old slash command directories** (`.claude/commands/openspec/`): The entire directory may be removed during cleanup - **Config files with markers**: Markers are removed; files are deleted if empty afterward - **Migration hints**: Users are informed about manual migration steps when needed 资料来源：[openspec/changes/archive/2026-02-17-merge-init-experimental/design.md:30-50]() ## Testing Strategy The slash command system employs a comprehensive testing approach to ensure reliability across all supported tools. ### Golden Snapshots Generated files are validated against expected outputs for each tool: - Frontmatter structure and content - Marker placement (never inside frontmatter) - Body content matches centralized templates ### Partial Presence Tests When only some files exist, the update behavior is tested: ```typescript // If 1-2 files exist, update should only refresh those files // and should not create missing files test('update refreshes only existing files', async () => { await createPartialSetup(); await runUpdate(); expect(existingFiles).toHaveUpdatedContent(); expect(missingFiles).toBeUndefined(); }); ``` 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md:100-115]() ### Marker Placement Tests Specific tests ensure markers never appear inside frontmatter and cover recovery behavior for missing or duplicated markers. ### Logging Tests Update operations report per-file status, enabling verification that each tool's files are processed correctly. ## Additional Commands (Opsx Workflow) Beyond the core three commands, the `/opsx` prefix provides access to an extended experimental workflow: | Command | Purpose | |---------|---------| | `/opsx:explore` | Explore ideas before committing to a change | | `/opsx:new` | Start a new change with a specific artifact structure | | `/opsx:continue` | Create artifacts one at a time (step-through mode) | | `/opsx:ff` | Fast-forward through completed tasks | | `/opsx:verify` | Verify artifact completeness and dependencies | | `/opsx:bulk-archive` | Archive multiple changes at once | | `/opsx:onboard` | Onboard new team members to the project | 资料来源：[README.md:1-30]() To enable these commands, run: ```bash openspec experimental ``` 资料来源：[docs/opsx.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md) ## Tool-Specific Implementations ### Claude Code Claude Code stores commands in nested directories with namespaced slash names: ``` .claude/commands/openspec/ ├── proposal.md ├── apply.md └── archive.md ``` Invocation: `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` ### Cursor Cursor uses flat naming with a prefix: ``` .cursor/commands/ ├── openspec-proposal.md ├── openspec-apply.md └── openspec-archive.md ``` Invocation: `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` ### Codex Codex commands are written to the global prompts directory: ```bash ~/.codex/prompts/ # or $CODEX_HOME/prompts ``` The system supports both local and global installation paths, with commands refreshed during `openspec update` when they already exist. 资料来源：[openspec/changes/archive/2025-10-14-add-codex-slash-command-support/proposal.md:15-30]() ## Configuration and Customization ### Tool Registry The `ToolRegistry` manages discovery and configuration for supported AI coding assistants, enabling the system to: - Detect which tools are installed in a project - Determine appropriate command storage locations - Handle tool-specific format variations ### Context Injection Slash command templates support dynamic context injection, prepending project-specific information: ```markdown --- change: add-auth artifact: proposal schema: spec-driven output: openspec/changes/add-auth/proposal.md --- ## Dependencies - [x] (none - this is a root artifact) ## Next Steps After creating this artifact, you can work on: design, specs --- [original template content...] ``` 资料来源：[openspec/changes/archive/2025-12-28-add-instruction-loader/design.md:1-30]() ## Related Documentation - [Getting Started](docs/getting-started.md) — First steps with OpenSpec - [Workflows](docs/workflows.md) — Combos and patterns for using slash commands - [Commands Reference](docs/commands.md) — Detailed slash command documentation - [Supported Tools](docs/supported-tools.md) — Full list of supported AI assistants - [Opsx Workflow](docs/opsx.md) — Extended experimental workflow commands --- ## Workflows ### 相关页面 相关主题：[Slash Commands](#slash-commands), [Artifact Graph System](#artifact-graph)
相关源码文件 以下源码文件用于生成本页说明： - [docs/workflows.md](https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md) - [README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) - [src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts) - [openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md) - [openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md) - [WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md) - [openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md)
# Workflows ## Overview Workflows in OpenSpec define the ordered sequence of artifacts that get created during a change's lifecycle. They provide a structured approach to capturing requirements, design decisions, and implementation tasks before any code is written. **Purpose**: Workflows ensure that human and AI assistants align on what to build through a consistent, repeatable process that captures the "why," "what," and "how" of each change. **Scope**: A workflow determines which artifacts need to be created, in what order, and what dependencies exist between them. 资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## Core Concepts ### Artifacts Artifacts are the files created during a change lifecycle. OpenSpec supports the following artifact types: | Artifact | Description | Output File | |----------|-------------|-------------| | proposal | Why and what changes | `proposal.md` | | specs | Requirements and scenarios | `specs/*.md` | | design | Technical approach | `design.md` | | tasks | Implementation checklist | `tasks.md` | 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md) ### Workflow Stages Each workflow progresses through distinct stages: ```mermaid graph LR A[Propose] --> B[Design] B --> C[Specs] C --> D[Tasks] D --> E[Apply] E --> F[Archive] style A fill:#e1f5fe style E fill:#fff3e0 style F fill:#f3e5f5 ``` | Stage | Purpose | Key Question | |-------|---------|--------------| | **Proposal** | Capture the reason for the change | "Why are we doing this?" | | **Design** | Document technical approach | "How will we build it?" | | **Specs** | Define requirements and scenarios | "What should it do?" | | **Tasks** | Break down implementation | "What are the steps?" | | **Apply** | Execute implementation | "Make it happen" | | **Archive** | Finalize and merge | "Clean up" | 资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## Workflow Templates OpenSpec ships with predefined workflow templates located in `src/core/templates/workflows/`. ### The New Change Workflow The new change workflow (`new-change.ts`) scaffolds a complete change structure: ```typescript export const newChangeWorkflow = { name: "New Change", description: "Scaffold a new OpenSpec change and validate strictly.", async execute(params) { // 1. Validate change name (kebab-case) // 2. Check if change already exists // 3. Create change directory // 4. Show artifact status // 5. Output first artifact template } }; ``` 资料来源：[src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts) ### Workflow Execution Steps When initiating a new change, the workflow performs these steps in order: 1. **Validate the change name** - Must be kebab-case (e.g., `add-dark-mode`) - If invalid, prompt for a valid name 2. **Check for existing changes** - If a change with the same name exists, suggest using `continue-change` instead 3. **Create the scaffold** - Run `openspec init --change ""` with `--schema ` if a specific workflow is requested - Creates `openspec/changes//` with the selected schema 4. **Show artifact status** ```bash openspec status --change "" ``` This displays which artifacts need creation and which are ready (dependencies satisfied). 5. **Output first artifact template** ```bash openspec instructions --change "" ``` This outputs the template and context for creating the first artifact. 6. **STOP and wait for user direction** 资料来源：[src/core/templates/workflows/new-change.ts:1-60](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts) ### Guardrails The new change workflow includes important guardrails: - **Do NOT create any artifacts yet** — only show the instructions - **Do NOT advance beyond showing the first artifact template** - **Pass `--schema`** only if using a non-default workflow - Changes with invalid names (not kebab-case) trigger a prompt for correction - Existing changes suggest using `/continue` instead 资料来源：[src/core/templates/workflows/new-change.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/new-change.ts) ## Workflow Patterns ### Spec-Driven Workflow The spec-driven workflow emphasizes design-first approach: ```mermaid graph TD P[proposal] --> D[design] D --> S[specs] S --> T[tasks] P -.->|blocking| S P -.->|blocking| T D -.->|blocking| T ``` | Artifact | Generates | Dependencies | |----------|-----------|--------------| | proposal | `proposal.md` | None (root) | | design | `design.md` | proposal | | specs | `specs/*.md` | proposal, design | | tasks | `tasks.md` | specs | ### Artifact Flow ``` ┌────────────────────┐ │ Archive & Update │ │ Specs (source) │ └────────────────────┘ │ ▼ ┌────────────────────┐ │ 1. Draft proposal │ └────────────────────┘ │ ▼ ┌────────────────────┐ │ 2. Review proposal │ └────────────────────┘ │ ▼ ┌────────────────────┐ │ 3. Implement tasks │ └────────────────────┘ │ ▼ ┌────────────────────┐ │ 4. Archive change │ └────────────────────┘ │ ▼ ┌────────────────────┐ │ Specs updated │ └────────────────────┘ ``` 资料来源：[openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-10-14-add-windsurf-workflows/proposal.md) ## Workflows with Slash Commands OpenSpec integrates with multiple AI coding assistants through slash command workflows. Each tool has its own command structure and file format. ### Supported Tools and Commands | Tool | Slash Commands | File Location | |------|----------------|---------------| | Claude Code | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Built-in | | CodeBuddy | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `.codebuddy/commands/` | | Cursor | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.cursor/commands/` | | Windsurf | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.windsurf/workflows/` | | Kilo Code | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` | `.kilocode/workflows/` | | Cline | Workflows | `.clinerules/workflows/` | | GitHub Copilot | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` | `.github/prompts/` | | Continue | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.continue/prompts/` | | Antigravity | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | `.agent/workflows/` | 资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ### Slash Command File Structure Slash command files follow a consistent pattern: ```markdown --- name: openspec-proposal description: Create an OpenSpec proposal category: OpenSpec --- ...command body from shared template... ``` **Template Content Structure:** - Guardrails: 1–2 clarifying questions - Minimal-complexity rules - Step list tailored to workflow stage - Pointers to `openspec show`, `openspec list` - Troubleshooting tips 资料来源：[openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2025-09-29-add-slash-command-support/proposal.md) ## CLI Commands for Workflows OpenSpec provides CLI commands to interact with workflows: ```bash # List active change folders openspec list # Interactive dashboard of specs and changes openspec view # Display change details openspec show # Check spec formatting and structure openspec validate # Move completed change to archive openspec archive [--yes|-y] # Show artifact status openspec status --change "" # Get instructions for artifact creation openspec instructions --change "" ``` 资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## Workflow Example ### Create and Execute a Change ```text You: /openspec:propose add-dark-mode AI: Created openspec/changes/add-dark-mode/ ✓ proposal.md — why we're doing this, what's changing ✓ specs/ — requirements and scenarios ✓ design.md — technical approach ✓ tasks.md — implementation checklist Ready for implementation! You: /openspec:apply AI: Implementing tasks... ✓ 1.1 Add theme context provider ✓ 1.2 Create toggle component ✓ 2.1 Add CSS variables ✓ 2.2 Wire up localStorage All tasks complete! You: /openspec:archive AI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/ Specs updated. Ready for the next feature. ``` 资料来源：[README.md](https://github.com/Fission-AI/OpenSpec/blob/main/README.md) ## Project Configuration Workflows can be customized per project through configuration: | Configuration Option | Description | |---------------------|-------------| | schema | Selected workflow/schema (e.g., "spec-driven") | | projectContext | Multi-line context (tech stack, conventions) | | artifactRules | Per-artifact custom rules | ### Config Section Prompts When running `openspec init`, the setup command displays: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 Project Configuration (Optional) Configure project defaults for OpenSpec workflows. ``` Steps: 1. **Create config?** — Yes/No prompt (default "Yes") 2. **Schema selection** — List schemas with descriptions 3. **Project context** — Multi-line input for tech stack info 4. **Per-artifact rules** — Optional rules for specific artifacts 5. **Validate and write** — Save to `openspec/config.yaml` 资料来源：[openspec/changes/archive/2026-02-17-project-config/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/openspec/changes/archive/2026-02-17-project-config/proposal.md) ## Workspace Workflow Extensions The OpenSpec workspace feature extends workflows across multiple repositories: ```mermaid graph TD W[Workspace] --> L[Links] L --> P[Proposal] P --> R[Repo Slices] R --> A[Apply] A --> V[Verify] V --> C[Archive] ``` ### Workspace Workflow Sequence | Step | Capability | |------|------------| | 1 | Set up the workspace | | 2 | See linked repos or folders | | 3 | Explore repos with agent | | 4 | Capture a proposal | | 5 | Check status | | 6 | Implement one repo slice | | 7 | Verify | | 8 | Archive | ### Apply One Repo Slice The `/apply` command for workspaces: ```text User: /apply integrate-docs for landing ``` **Agent behavior:** 1. Ask OpenSpec for apply context 2. Read proposal, design, tasks, and relevant specs 3. Confirm the target repo checkout 4. Edit only that repo 5. Update workspace tasks 6. Run relevant checks **What `/apply` means:** - Implement the planned slice for one repo - Does NOT copy planning files - Does NOT materialize repo-local OpenSpec state - Does NOT create proposal files for the first time 资料来源：[WORKSPACE_REIMPLEMENTATION_DIRECTION.md](https://github.com/Fission-AI/OpenSpec/blob/main/WORKSPACE_REIMPLEMENTATION_DIRECTION.md) ## Related Documentation - [Getting Started](docs/getting-started.md) — First steps with workflows - [Commands](docs/commands.md) — Slash commands & skills reference - [CLI](docs/cli.md) — Terminal command reference - [Supported Tools](docs/supported-tools.md) — Tool integrations & install paths - [Concepts](docs/concepts.md) — How it all fits together - [Customization](docs/customization.md) — Make workflows yours --- ## Artifact Graph System ### 相关页面 相关主题：[System Architecture](#architecture), [Workflows](#workflows), [Schemas](#schemas)
相关源码文件 以下源码文件用于生成本页说明： - [src/core/artifact-graph/graph.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/graph.ts) - [src/core/artifact-graph/state.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/state.ts) - [src/core/artifact-graph/resolver.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/resolver.ts) - [src/core/artifact-graph/schema.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/schema.ts) - [src/core/artifact-graph/outputs.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/outputs.ts) - [src/core/artifact-graph/instruction-loader.ts](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/artifact-graph/instruction-loader.ts)
# Artifact Graph System ## Overview The Artifact Graph System is the core module of OpenSpec that manages artifact dependencies, workflow state detection, and schema-driven instruction generation. It provides a declarative way to define artifact relationships through YAML schemas and enables intelligent workflow progression based on filesystem state. ### Purpose The system solves several key problems in AI-assisted development: 1. **Dependency Management** - Ensures artifacts are created in the correct order based on their dependencies 2. **State Detection** - Automatically detects which artifacts are completed, ready, or blocked based on filesystem presence 3. **Schema Resolution** - Supports both user-defined schemas (via XDG directories) and built-in package schemas 4. **Instruction Generation** - Enriches templates with project context, artifact-specific rules, and dependency status ### High-Level Architecture ```mermaid graph TB subgraph "Artifact Graph System" YAML[("Schema YAML")] GRAPH[("ArtifactGraph")] STATE[("State Detection")] INSTR[("Instruction Loader")] CTX[("ChangeContext")] end subgraph "Schema Sources" USER[("User Schemas
XDG_DATA_HOME")] BUILTIN[("Built-in Schemas
Package")] end YAML --> GRAPH GRAPH --> STATE GRAPH --> CTX STATE --> CTX CTX --> INSTR USER -->|resolveSchema| GRAPH BUILTIN -->|resolveSchema| GRAPH ``` ## Core Concepts ### Artifacts Artifacts are the fundamental units of work in OpenSpec. Each artifact has: | Property | Type | Description | |----------|------|-------------| | `id` | string | Unique identifier within the schema | | `generates` | string | File pattern generated by this artifact | | `template` | string | Template file path (relative to schema directory) | | `requires` | string[] | List of artifact IDs that must complete first | ### Schema Structure Schemas define the workflow for a change. They are YAML files with the following structure: ```yaml name: spec-driven version: 1 description: Specification-driven development workflow artifacts: - id: proposal generates: "proposal.md" template: "proposal.md" requires: [] - id: specs generates: "specs/*.md" template: "spec.md" requires: [proposal] - id: design generates: "design.md" template: "design.md" requires: [proposal] - id: tasks generates: "tasks.md" template: "tasks.md" requires: [specs, design] ``` ## ArtifactGraph Class The `ArtifactGraph` class is the central component that loads schemas and provides graph query operations. ### Class Structure ```typescript export class ArtifactGraph { private artifacts: Map; private schema: SchemaYaml; private constructor(schema: SchemaYaml) { this.schema = schema; this.artifacts = new Map(schema.artifacts.map(a => [a.id, a])); } } ``` ### Factory Methods | Method | Description | Source | |--------|-------------|--------| | `fromYaml(filePath)` | Load graph from a schema YAML file path | `graph.ts:18-21` | | `fromYamlContent(yamlContent)` | Parse graph from YAML content string | `graph.ts:27-29` | | `fromSchema(schema)` | Create graph from pre-validated SchemaYaml object | `graph.ts:35-37` | ### Query Methods | Method | Return Type | Description | |--------|-------------|--------------| | `getArtifact(id)` | `Artifact \| undefined` | Get a single artifact by ID | | `getAllArtifacts()` | `Artifact[]` | Get all artifacts in definition order | | `getName()` | `string` | Get the schema name | | `getSchema()` | `SchemaYaml` | Get the underlying schema object | ## State Detection The state detection module (`state.ts`) monitors the filesystem to determine the status of each artifact relative to a change directory. ### State Types | State | Description | |-------|-------------| | `completed` | All files matching the artifact's `generates` pattern exist | | `ready` | All dependencies are completed, can be worked on | | `blocked` | Dependencies are not yet completed | ### State Detection Logic ```typescript interface ArtifactGraphResult { completed: string[]; // Artifact IDs that are fully completed ready: string[]; // Artifact IDs ready to work on blocked: BlockedArtifacts; // Artifact IDs with their unmet dependencies buildOrder: string[]; // Topological order for creation } ``` The detection process: 1. For each artifact, check if files matching `generates` exist in the change directory 2. Collect all completed artifact IDs into a `CompletedSet` (a `Set`) 3. For each non-completed artifact, find which dependencies are unmet 4. Artifacts with all dependencies met are marked `ready` ## Topological Sorting The system uses Kahn's algorithm for topological sorting to determine the correct build order for artifacts. ### Algorithm Properties - **Cycle Detection**: Kahn's algorithm naturally fails on cyclic dependencies, providing natural cycle detection - **Stable Ordering**: Independent artifacts are returned in definition order - **Linear Time**: O(V + E) where V is artifacts and E is dependencies ### Error Format When a cycle is detected, the error message clearly identifies the cycle path: ``` Cyclic dependency detected: A → B → C → A ``` ## Schema Resolution The `resolver.ts` module handles loading schemas from multiple sources with a defined priority order. ### Resolution Order ```mermaid graph LR A[("Schema Name")] --> B{Global Override?} B -->|Yes| C["${XDG_DATA_HOME}/openspec/schemas/"] B -->|No| D{Package Built-in?} D -->|Yes| E["/schemas/"] D -->|No| F[("Error: Schema not found")] C --> G[("Loaded Schema")] E --> G ``` ### Resolution Paths | Priority | Location | Environment Variable | |----------|----------|----------------------| | 1 (User Override) | `${XDG_DATA_HOME}/openspec/schemas/` | `XDG_DATA_HOME` | | 2 (Built-in) | `/schemas/` | N/A | | 3 (Error) | Schema not found | N/A | **Fallback Behavior**: If `XDG_DATA_HOME` is not set, the system falls back to `~/.local/share` on Unix systems. ## Built-in Schemas OpenSpec ships with two built-in schemas: ### spec-driven Schema The default schema following a proposal → specs → design → tasks workflow: ```yaml name: spec-driven artifacts: - id: proposal generates: "proposal.md" requires: [] - id: specs generates: "specs/*.md" requires: [proposal] - id: design generates: "design.md" requires: [proposal] - id: tasks generates: "tasks.md" requires: [specs, design] ``` ### tdd Schema An alternative schema for test-driven development: ```yaml name: tdd artifacts: - id: tests generates: "tests/*.md" requires: [] - id: implementation generates: "implementation.md" requires: [tests] - id: docs generates: "docs.md" requires: [implementation] ``` ## Instruction Loading The `instruction-loader.ts` module enriches templates with change-specific context and project configuration. ### ChangeContext Interface ```typescript interface ChangeContext { changeName: string; changeDir: string; schemaName: string; graph: ArtifactGraph; completed: CompletedSet; } ``` ### Instruction Output Structure Instructions are formatted with XML-like sections for AI consumption: ```markdown [Project context from config] [Artifact-specific rules from config] ``` ### Context Injection Rules | Section | Applies To | Source | |---------|-----------|--------| | `` | All artifacts | Project config's `context` field | | `` | Specific artifacts only | Per-artifact rules in project config | | `