diff --git a/openspec/changes/add-multi-agent-init/proposal.md b/openspec/changes/add-multi-agent-init/proposal.md new file mode 100644 index 00000000..58a25e53 --- /dev/null +++ b/openspec/changes/add-multi-agent-init/proposal.md @@ -0,0 +1,35 @@ +# Allow Additional AI Tool Initialization After Setup + +## Summary +- Let `openspec init` configure new AI coding tools for projects that already contain an OpenSpec structure. +- Keep the initialization flow safe by skipping structure creation and only generating files for tools the user explicitly selects. +- Provide clear feedback so users know which tool files were added versus already present. + +## Motivation +Today `openspec init` exits with an error once an `openspec/` directory exists. That protects the directory layout, but it blocks +teams that start with one assistant (for example, Claude Code) and later want to add another such as Cursor. They have to create +those files by hand or rerun `init` in a clean clone, which undermines the "easy onboarding" promise. Letting the command extend +an existing installation keeps the workflow consistent and avoids manual file management. + +## Proposal +1. Detect an existing OpenSpec structure at the start of `openspec init` and branch into an "extend" mode instead of exiting. + - Announce that the base structure already exists and that the command will only manage AI tool configuration files. + - Keep the existing guard for directories or files we must not overwrite. +2. Present the usual AI tool selection prompt even in extend mode, showing which tools are already configured. + - Skip disabled options that remain "coming soon". + - Mark already configured tools as such so users know whether selecting them will refresh or add files. +3. When the user selects additional tools, generate the same initialization files that a fresh run would create (e.g., Cursor + workspace files) while leaving untouched tools intact apart from marker-managed sections. + - Do nothing when the user selects no new tools and keep the previous error messaging to avoid silently succeeding. +4. Summarize the outcome (created, refreshed, skipped) before exiting with code 0 when work was performed. + - Include friendly guidance that future updates to shared content still come from `openspec update`. + +## Out of Scope +- Changing how `openspec update` discovers or updates AI tool files. +- Supporting brand-new AI tools beyond those already wired into the CLI. +- Adding non-interactive flags for selecting multiple tools in one run (follow-up if needed). + +## Risks & Mitigations +- **User confusion about extend mode** → Explicitly log what will happen before prompting and summarise results afterward. +- **Accidental overwrites** → Continue using marker-based updates and skip files unless the user chooses that tool. +- **Inconsistent state if init fails mid-run** → Reuse existing rollback/transaction logic so partial writes clean up. diff --git a/openspec/changes/add-multi-agent-init/specs/cli-init/spec.md b/openspec/changes/add-multi-agent-init/specs/cli-init/spec.md new file mode 100644 index 00000000..4878d71f --- /dev/null +++ b/openspec/changes/add-multi-agent-init/specs/cli-init/spec.md @@ -0,0 +1,20 @@ +## MODIFIED Requirements +### Requirement: Safety Checks +The command SHALL perform safety checks to prevent overwriting existing structures and ensure proper permissions. + +#### Scenario: Detecting existing initialization +- **WHEN** the `openspec/` directory already exists +- **THEN** inform the user that OpenSpec is already initialized and skip recreating the base structure +- **AND** continue to the AI tool selection step so additional tools can be configured +- **AND** display the existing-initialization error message only when the user declines to add any AI tools + +## ADDED Requirements +### Requirement: Additional AI Tool Initialization +`openspec init` SHALL allow users to add configuration files for new AI coding assistants after the initial setup. + +#### Scenario: Configuring an extra tool after initial setup +- **GIVEN** an `openspec/` directory already exists and at least one AI tool file is present +- **WHEN** the user runs `openspec init` and selects a different supported AI tool +- **THEN** generate that tool's configuration files with OpenSpec markers the same way as during first-time initialization +- **AND** leave existing tool configuration files unchanged except for managed sections that need refreshing +- **AND** exit with code 0 and display a success summary highlighting the newly added tool files diff --git a/openspec/changes/add-multi-agent-init/tasks.md b/openspec/changes/add-multi-agent-init/tasks.md new file mode 100644 index 00000000..32a7e835 --- /dev/null +++ b/openspec/changes/add-multi-agent-init/tasks.md @@ -0,0 +1,16 @@ +# Implementation Tasks + +## 1. Extend Init Guard +- [ ] 1.1 Detect existing OpenSpec structures at the start of `openspec init` and enter an extend mode instead of failing. +- [ ] 1.2 Log that core scaffolding will be skipped while still protecting against missing write permissions. + +## 2. Update AI Tool Selection +- [ ] 2.1 Present AI tool choices even in extend mode, indicating which tools are already configured. +- [ ] 2.2 Ensure disabled "coming soon" tools remain non-selectable. + +## 3. Generate Additional Tool Files +- [ ] 3.1 Create configuration files for newly selected tools while leaving untouched tools unaffected apart from marker-managed sections. +- [ ] 3.2 Summarize created, refreshed, and skipped tools before exiting with the appropriate code. + +## 4. Verification +- [ ] 4.1 Add tests covering rerunning `openspec init` to add another tool and the scenario where the user declines to add anything.