DOCSEARCHbyAlgolia
Submit Docs

OpenSpec

repository·main·Indexed 13 days ago

https://github.com/fission-ai/openspec

An AI-native system for spec-driven development designed to align human developers and AI coding assistants. OpenSpec uses an artifact-guided workflow—consisting of proposals, specs, designs, and tasks—to ensure requirements are agreed upon before code is written. Version 1.8.0 features a Git-native model for managing work via goals, roadmaps, and slices, as well as a CLI and AI slash commands (e.g., /opsx:explore, /opsx:propose) to reduce the unpredictability of AI-generated code.

Tokens
256.2K
Snippets
660
Records
1.2K
Agent score
93%

What's inside OpenSpec

  1. Overview of OpenSpec CLI commands

    main

    The openspec CLI provides terminal commands for project setup, validation, status inspection, and management. Commands are categorized by their purpose:

    • Setup: init, update (Initialize and update OpenSpec in your project)
    • Stores: store setup, store register, store unregister, store remove, store list, store doctor (Manage standalone OpenSpec repos)
    • Health: doctor (Report relationship health)
    • Working context: context (Assemble the working set)
    • Personal worksets: workset create, workset list, workset open, workset remove (Manage local working views)
    • Browsing: list, view, show (Explore changes and specs)
    • Validation: validate (Check changes and specs)
    • Lifecycle: archive (Finalize completed changes)
    • Workflow: new change, status, instructions, templates, schemas (Artifact-driven workflow support)
    • Schemas: schema init, schema fork, schema validate, schema which (Manage custom workflows)
    • Config: config (View/modify settings)
    • Utility: feedback, completion (Feedback and shell integration)

  2. What is OpenSpec?

    main

    OpenSpec is a spec-driven development workflow designed to align humans and AI coding assistants. It ensures that intent is locked and agreed upon before any code is written, providing deterministic and reviewable outputs. Unlike many AI-driven tools, OpenSpec requires no API keys and is designed to work effectively in 'brownfield' environments (modifying existing codebases) by separating the current source of truth from proposed changes.

    Key features include:

    • Structured Change Folders: Uses openspec/specs/ for the current source of truth and openspec/changes/ for proposed updates (proposals, tasks, and deltas).
    • Explicit Scope: Keeps changes auditable and manageable.
    • Tool Agnostic: Works with existing AI tools via custom slash commands or context rules.

  3. What is a spec and how should it be structured

    main

    An OpenSpec is a description of system behavior, not implementation. It must focus on what the system does rather than how it is built. A spec consists of two primary components:

    1. Requirements: Statements of behavior using RFC 2119 keywords (e.g., SHALL, MUST).
    2. Scenarios: Concrete GIVEN / WHEN / THEN examples that prove the requirements.

    Avoid implementation details: Do not include details like specific libraries, queue types, or database schemas in the spec. Those belong in a design.md file or the code itself. Mixing them makes requirements untestable and prone to becoming stale.

    ### Requirement: Session Timeout
The system SHALL expire a session after 30 minutes of inactivity.

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN the session is invalidated and the user must re-authenticate

  4. What is a spec in OpenSpec?

    main

    In OpenSpec, a spec is defined as a verifiable behavior contract at a boundary. It represents what users, integrators, or operators can observe and rely on, and what can be validated through tests, checks, or explicit review. Specs should remain stable even if the underlying internal implementation changes.

    What to include in a spec:

    • Observable behavior and outcomes.
    • Interface/data contracts (inputs, outputs, error conditions).
    • External non-functional constraints (privacy, security, reliability).
    • Compatibility guarantees required by downstream consumers.

    What to avoid in a spec:

    • Internal implementation details (e.g., class names, library choices, control flow).
    • Tooling mechanics that do not affect behavior.
    • Step-by-step execution plans (these belong in tasks or design).

  5. Overview of the cli-completion Specification

    main
    The cli-completion specification defines how shell completion scripts for the OpenSpec CLI are implemented. Its purpose is to enable tab-completion for commands, flags, and dynamic values (such as change IDs and spec IDs) across multiple shell environments, including Zsh, Bash, Fish, and PowerShell.

  6. What is an OpenSpec Store?

    main

    An OpenSpec store is a standalone Git repository dedicated to planning. While standard OpenSpec usage involves an openspec/ folder inside a code repository, a store allows you to centralize specs and changes that span multiple repositories (e.g., a feature affecting both an API and a Web App) or planning that occurs before code exists.

    Key Characteristics:

    • It is a Git repo: You manage it using standard git commands (commit, push, pull, branch). OpenSpec does not perform sync or push operations automatically.
    • Identity: Stores contain a .openspec-store/store.yaml file that identifies the store.
    • Decoupled Planning: You can register a store on your machine by name, allowing you to run OpenSpec commands against it from any directory using the --store <name> flag.

  7. Use resilient field-by-field parsing in OpenSpec config

    main

    OpenSpec employs resilient parsing for the configuration file. Instead of rejecting the entire file when a single field is invalid, the system parses each field independently. It collects all valid fields and logs warnings for invalid ones, allowing the rest of the configuration to be applied.

    Supported Fields and Validation Rules

    FieldTypeBehavior on Invalid Type/Value
    schemastringIf empty string or non-string, logs warning and excludes field.
    contextstringIf non-string or exceeds 50KB, logs warning and excludes field.
    rulesobjectParses valid sub-fields (e.g., proposal, specs) independently.

    Rules Field Details

    • Sub-field validation: If a sub-field like rules.proposal is not an array, a warning is logged, but other valid sub-fields (like rules.specs) are still included.
    • Array element validation: If a rules array contains non-string elements (e.g., ["Valid", 123]), only the valid string elements are included, and a warning is logged for the invalid ones.

  8. Sync delta specs to main specs

    main

    If your change produced delta specs (found in artifactPaths.specs.existingOutputPaths), you should sync them into the main specification files before archiving. This ensures that the changes made during the workflow are reflected in the project's primary documentation.

    The Sync Workflow

    1. Assessment: The system compares delta specs against the main spec at <planningHome.root>/openspec/specs/<capability-path>/spec.md.
    2. Prompt: You will be asked to "Sync now (recommended)" or "Archive without syncing".
    3. Instruction Fetch: If syncing, the system runs openspec instructions specs --change "<name>" --json to fetch rules for the merge. This command must return a zero exit status and valid JSON; otherwise, the process stops.
    4. Execution: The openspec-sync-specs workflow is run to perform an intelligent merge.
    5. Verification: The system re-verifies that the main specs now match the intended state (Additions, Modifications, Removals, or Renames).
    # Fetching instructions before a sync
openspec instructions specs --change "<name>" --json --store "<id>"

  9. Difference between a Spec and a Design

    main

    When creating artifacts, distinguish between these two concepts:

    • Spec: Describes observable behavior. It defines what the system does, its inputs, outputs, and error conditions. If the implementation changes but the behavior remains the same, the spec does not change.
    • Design: Describes how you build it. It covers technical approaches, architecture decisions, and specific file changes.

  10. Maintain OpenSpec spec integrity during initiatives

    main

    A core principle of managing initiatives in OpenSpec is the separation of current behavioral contracts from future product intent.

    When executing an initiative:

    1. Keep OpenSpec specs unchanged until the actual behavior of the system changes. Specs should represent the current state of the world.
    2. Use initiative artifacts (like tasks.md, decisions.md, and questions.md) to carry the documentation of future intent, roadmap implementation, and planned changes.
    3. Review historical artifacts to ensure no legacy language (e.g., old shipping queues or deferred tasks) misleads agents or developers about the current direction.
    4. Verify changes using git diff --check to confirm that no unintended modifications were made to the core OpenSpec specifications during a non-spec direction pass.

  11. Understand the OpenSpec Mental Model for Work Coordination

    main

    OpenSpec separates coordination from execution using three distinct layers. This separation allows agents to distinguish between what work is being discussed, where the planning lives, and which files are actually editable.

    • Context Stores: Remember shared truth and state.
    • Initiatives: Coordinate high-level work across teams or projects.
    • Workspaces: Provide a local lens over initiatives and repositories.
    • Repo-local Changes: Act as the executable implementation plans.

    Key Invariant: Work identity is not determined by storage location, and storage location does not dictate edit permissions.

  12. Use OPSX slash commands and the CLI

    main

    OpenSpec is driven by two distinct interfaces:

    OPSX (Slash Commands)

    These are commands typed into an AI assistant's chat interface to drive the workflow. They are not terminal commands.

    • /opsx:explore: A thinking-partner command that reads the codebase to clarify ideas into plans without creating artifacts or code. Recommended as a starting point.
    • /opsx:propose: Initiates a new change.
    • /opsx:apply: Executes implementation tasks.
    • /opsx:sync: Merges delta specs into main specs for long-running changes.
    • /opsx:archive: Finalizes a change.

    CLI (Terminal Commands)

    The openspec program run in the terminal for administrative tasks:

    • Project setup.
    • Listing and validating changes.
    • Opening the dashboard.
    • Archiving changes.
    • Configuring profiles (e.g., openspec config profile).
    • Updating delivery (e.g., openspec update).