teachingai/openspec-initial

OpenSpec Initial Skill

Run openspec init to initialize OpenSpec in a project: creates the openspec/ directory (specs, changes, config) and configures AI tool integrations (skills and slash commands). This skill assumes the OpenSpec CLI is already installed; if not, direct the user to openspec-install first.

When to Use

• First time enabling OpenSpec in a project ("initialize OpenSpec", "set up OpenSpec here").
• Adding AI tool integrations (Claude, Cursor, Windsurf, etc.) to an existing project.
• Re-initializing after changing tool selections.

Prerequisites

• OpenSpec CLI installed (see openspec-install). If openspec is not in PATH, guide the user to run openspec-install before proceeding.

Workflow

1. Verify CLI

   • If the user reports "openspec command not found", direct them to openspec-install first.

2. Choose parameters

   • path (optional): Target directory; defaults to current directory.
   • --tools (optional): Configure AI tools non-interactively. Values: all, none, or comma-separated list (e.g. claude,cursor).
   • --force: Auto-cleanup legacy files without prompting.

3. Run the command

   • Interactive: openspec init
   • Non-interactive with specific tools: openspec init --tools claude,cursor
   • All tools: openspec init --tools all
   • Specific directory: openspec init ./my-project

4. Optionally create project config

   • During init, the user may be prompted to create openspec/config.yaml with project context, schema defaults, and per-artifact rules. This is optional but recommended. See openspec-config for details.

5. Confirm outputs

   • After success: openspec/ directory with specs/, changes/, and optionally config.yaml. Tool-specific directories (.claude/skills/, .cursor/rules/, etc.) are created based on selected tools.

Supported Tools

amazon-q, antigravity, auggie, claude, cline, codebuddy, codex, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, opencode, qoder, qwen, roocode, trae, windsurf

Outputs

• openspec/:
  • specs/ — Specifications (source of truth)
  • changes/ — Proposed changes
  • config.yaml — Project configuration (optional)
• Tool configs: .claude/skills/, .cursor/rules/, .windsurf/skills/, etc. based on selected tools.

Next Steps

• Use openspec-update after upgrading the CLI to regenerate tool configs.
• Use openspec-onboard for a guided walkthrough of the complete workflow.
• Or start working: openspec-explore to think through ideas, openspec-new to start a change.

Different Environments

| Scenario | Command | |----------|---------| | Interactive | openspec init | | Claude + Cursor | openspec init --tools claude,cursor | | All tools | openspec init --tools all | | Specific directory | openspec init ./my-project | | CI / non-interactive | openspec init --tools claude --force | | Skip tool config | openspec init --tools none |

Troubleshooting

• "openspec: command not found": Use openspec-install first.
• Legacy files detected: Use --force to auto-cleanup, or follow the interactive prompts.
• Tool not in list: Check the supported tools list for the correct ID.

References

• OpenSpec CLI: init
• OpenSpec Supported Tools