@dccxx/auggiegw 1.0.24 → 1.0.26

package/openspec/changes/archive/2026-02-01-add-kit-install-prompts/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-01

package/openspec/changes/archive/2026-02-01-add-kit-install-prompts/design.md

@@ -0,0 +1,113 @@
+## Context
+
+The current `kit` command in `src/cli.ts` automatically installs prompts and subagents to both Claude (`~/.claude/`) and Augment (`~/.augment/`) directories at the user level without any user interaction. This change introduces interactive prompts using `@clack/prompts` to give users control over:
+1. Which AI tool to install to (Claude, Augment, or Both)
+2. Whether to install at user level (home directory) or project level (current working directory)
+
+The existing implementation has hardcoded paths and dual-directory logic in `savePromptToFile()` and `saveSubagentToFile()` functions. These need to be refactored to support dynamic path resolution based on user selections.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add interactive CLI prompts for target AI tool and installation scope selection
+- Support optional `--target` and `--scope` flags for automation/scripting
+- Refactor file saving logic to support dynamic path resolution
+- Maintain existing file format specifications (YAML frontmatter + content)
+- Show exact installation paths in success messages
+- Auto-create directories if they don't exist
+
+**Non-Goals:**
+- Modifying the kit API endpoint or response format
+- Changing the file format for prompts or subagents
+- Adding .gitignore management for project-level installations
+- Modifying the model name mapping logic for Claude
+- Supporting additional AI tools beyond Claude and Augment
+- Adding validation for kit contents before installation
+
+## Decisions
+
+### Decision 1: Use @clack/prompts for interactive UI
+**Rationale**: @clack/prompts provides beautiful, modern CLI prompts with excellent UX. It's widely used in modern CLI tools (create-t3-app, create-next-app, etc.) and has a clean API.
+
+**Alternatives considered**:
+- `prompts` library: Lighter weight but less visually polished
+- `inquirer`: More mature but heavier and older API design
+- Custom implementation: Too much effort for standard functionality
+
+**Trade-off**: Adds ~500KB to dependencies, but the UX improvement justifies the cost.
+
+### Decision 2: Always prompt by default, no --yes flag
+**Rationale**: The prompts themselves ARE the interface. Users who want automation can use `--target` and `--scope` flags. Adding a `--yes` flag would be redundant since the prompts are the primary UX, not an obstacle.
+
+**Alternatives considered**:
+- Add `--yes` flag to skip prompts: Adds unnecessary complexity
+- Make prompts opt-in with `--interactive`: Breaks existing behavior more severely
+
+### Decision 3: Refactor save functions to accept paths as parameters
+**Rationale**: Current `savePromptToFile()` and `saveSubagentToFile()` have hardcoded paths. Refactoring them to accept paths as parameters makes them reusable and testable.
+
+**Approach**:
+- Create new functions: `savePromptToPath(prompt, dirPath)` and `saveSubagentToPath(subagent, dirPath, isClaudeTarget)`
+- Keep model mapping logic in `saveSubagentToPath()` - only apply when `isClaudeTarget` is true
+- Build path configuration object in `handleKit()` based on user selections
+
+**Alternatives considered**:
+- Pass full config object to save functions: More coupling, harder to test
+- Keep dual-directory logic in save functions: Doesn't support single-target installations
+
+### Decision 4: Project-level installations use current working directory
+**Rationale**: Using `process.cwd()` is the standard approach for project-level CLI tools. Users expect `./.augment/` and `./.claude/` to be created in the directory where they run the command.
+
+**Alternatives considered**:
+- Search for project root (package.json, git root): Too complex, not always desired
+- Use a config file to specify project directory: Overkill for this use case
+
+### Decision 5: CLI flags use exact values (no abbreviations)
+**Rationale**: Explicit values improve clarity and reduce errors.
+
+**Flag design**:
+- `--target <claude|augment|both>`: Exact match to prompt options
+- `--scope <user|project>`: Clear and unambiguous
+
+**Alternatives considered**:
+- Abbreviations like `--target c|a|b`: Less clear, error-prone
+- Different naming like `--ai-tool`: More verbose without added clarity
+
+## Risks / Trade-offs
+
+**[Risk] Breaking change for existing scripts** → Mitigation: Document the change clearly in release notes. Users can add `--target both --scope user` to maintain old behavior.
+
+**[Risk] @clack/prompts adds 500KB to bundle** → Mitigation: Acceptable trade-off for significantly improved UX. This is a CLI tool, not a web bundle.
+
+**[Risk] Project-level installations may clutter repositories** → Mitigation: Users are responsible for adding `.augment/` and `.claude/` to `.gitignore`. We explicitly decided not to auto-manage .gitignore.
+
+**[Risk] Path resolution complexity with multiple targets** → Mitigation: Clear separation of concerns - path resolution happens once in `handleKit()`, save functions are simple and focused.
+
+**[Risk] Users may not understand the difference between user and project level** → Mitigation: Use clear labels in prompts: "User level (~/.augment)" and "Project level (./.augment)" to show exact paths.
+
+## Migration Plan
+
+**Deployment**:
+1. Add `@clack/prompts` dependency via `bun add @clack/prompts`
+2. Implement new types and interfaces for configuration
+3. Create prompt functions using @clack/prompts
+4. Refactor save functions to accept paths
+5. Update `handleKit()` to orchestrate prompts and path resolution
+6. Update command definition to add `--target` and `--scope` options
+7. Run `bun run lint` and `bun run build` to verify
+8. Update version in package.json (breaking change - bump major version)
+9. Publish with clear release notes about breaking change
+
+**Rollback strategy**:
+- If critical issues arise, users can downgrade to previous version
+- No data migration needed - this only affects installation behavior
+- Existing installed kits are not affected
+
+**Breaking change communication**:
+- Document in CHANGELOG.md
+- Include migration guide: add `--target both --scope user` to scripts
+- Consider adding deprecation warning in previous version (if time permits)
+
+## Open Questions
+
+None - all design decisions have been made based on the exploration phase.

package/openspec/changes/archive/2026-02-01-add-kit-install-prompts/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+The current `kit` command automatically installs prompts and subagents to both Claude and Augment directories at the user level without any user choice. Users need control over which AI tool to install to (Claude, Augment, or both) and whether to install at user level or project level for better flexibility and project-specific configurations.
+
+## What Changes
+
+- Add interactive prompts using `@clack/prompts` to let users choose:
+  - Target AI tool: Claude, Augment, or Both
+  - Installation scope: User level (~/.augment, ~/.claude) or Project level (./.augment, ./.claude)
+- Add optional CLI flags `--target` and `--scope` for automation/scripting
+- Refactor file saving logic to support dynamic path resolution based on user selections
+- Update success messages to show exact installation paths
+- **BREAKING**: Default behavior changes from automatic installation to interactive prompts (users can use flags to maintain automation)
+
+## Capabilities
+
+### New Capabilities
+- `kit-install-prompts`: Interactive prompts for selecting AI tool target and installation scope when installing kits
+
+### Modified Capabilities
+- `kit-command`: Existing kit command behavior changes from automatic dual-directory installation to user-controlled installation with prompts
+
+## Impact
+
+- **Code**: `src/cli.ts` - `handleKit()`, `savePromptToFile()`, `saveSubagentToFile()` functions need refactoring
+- **Dependencies**: New dependency `@clack/prompts` for interactive CLI prompts
+- **Breaking Change**: Existing scripts using `auggiegw kit <id>` will now show prompts instead of auto-installing. Users need to add `--target both --scope user` flags to maintain old behavior
+- **User Experience**: More control and flexibility for users, better project-level kit management

package/openspec/changes/archive/2026-02-01-add-kit-install-prompts/specs/kit-command/spec.md

@@ -0,0 +1,107 @@
+## MODIFIED Requirements
+
+### Requirement: Command Invocation
+WHEN the user runs `auggiegw kit <kit-id>`, THE SYSTEM SHALL prompt the user to select target AI tool and installation scope, then fetch the kit from the public API endpoint.
+
+#### Scenario: User runs kit command without flags
+- **WHEN** user runs `auggiegw kit <kit-id>` without any flags
+- **THEN** system displays interactive prompt for target selection
+- **THEN** system displays interactive prompt for scope selection
+- **THEN** system fetches the kit from the public API endpoint
+
+#### Scenario: User runs kit command with flags
+- **WHEN** user runs `auggiegw kit <kit-id> --target claude --scope user`
+- **THEN** system skips prompts and uses provided flag values
+- **THEN** system fetches the kit from the public API endpoint
+
+#### Scenario: Missing kit-id argument
+- **WHEN** kit-id argument is missing
+- **THEN** system displays "Error: Kit ID is required" and usage message, and exits with code 1
+
+### Requirement: Prompt Installation
+WHEN processing prompts, THE SYSTEM SHALL create the target directories based on user selection and save markdown files with YAML frontmatter to the selected locations.
+
+#### Scenario: Install prompts to Claude user level
+- **WHEN** user selects target "Claude" and scope "User level"
+- **THEN** system creates directory `~/.claude/commands/` if it does not exist
+- **THEN** for each prompt in the kit, system saves a markdown file to `~/.claude/commands/{command}.md` with YAML frontmatter containing `description` and `type: "manual"` fields
+
+#### Scenario: Install prompts to Augment project level
+- **WHEN** user selects target "Augment" and scope "Project level"
+- **THEN** system creates directory `./.augment/commands/` if it does not exist
+- **THEN** for each prompt in the kit, system saves a markdown file to `./.augment/commands/{command}.md` with YAML frontmatter containing `description` and `type: "manual"` fields
+
+#### Scenario: Install prompts to both targets at user level
+- **WHEN** user selects target "Both" and scope "User level"
+- **THEN** system creates directories `~/.augment/commands/` and `~/.claude/commands/` if they do not exist
+- **THEN** for each prompt in the kit, system saves markdown files to both `~/.augment/commands/{command}.md` and `~/.claude/commands/{command}.md`
+
+#### Scenario: Overwrite existing prompt files
+- **WHEN** a prompt file with the same filename already exists
+- **THEN** system overwrites the existing file without confirmation
+
+#### Scenario: Prompt file save failure
+- **WHEN** a prompt file fails to save
+- **THEN** system throws an error with message "Failed to save prompt file for command '{command}': {error}"
+
+#### Scenario: Partial save failure with multiple targets
+- **WHEN** user selects "Both" targets and a prompt file fails to save to one directory
+- **THEN** system still attempts to save to the other directory before throwing an error
+
+### Requirement: Subagent Installation
+WHEN processing subagents, THE SYSTEM SHALL create the target directories based on user selection and save markdown files with YAML frontmatter to the selected locations.
+
+#### Scenario: Install subagents to Claude user level
+- **WHEN** user selects target "Claude" and scope "User level"
+- **THEN** system creates directory `~/.claude/agents/` if it does not exist
+- **THEN** for each subagent in the kit, system saves a markdown file to `~/.claude/agents/{name}.md` with YAML frontmatter containing `name`, `description`, `model`, and `color` fields
+
+#### Scenario: Install subagents to Augment project level
+- **WHEN** user selects target "Augment" and scope "Project level"
+- **THEN** system creates directory `./.augment/agents/` if it does not exist
+- **THEN** for each subagent in the kit, system saves a markdown file to `./.augment/agents/{name}.md` with YAML frontmatter containing `name`, `description`, `model`, and `color` fields
+
+#### Scenario: Install subagents to both targets at user level
+- **WHEN** user selects target "Both" and scope "User level"
+- **THEN** system creates directories `~/.augment/agents/` and `~/.claude/agents/` if they do not exist
+- **THEN** for each subagent in the kit, system saves markdown files to both `~/.augment/agents/{name}.md` and `~/.claude/agents/{name}.md`
+
+#### Scenario: Overwrite existing subagent files
+- **WHEN** a subagent file with the same filename already exists
+- **THEN** system overwrites the existing file without confirmation
+
+#### Scenario: Subagent file save failure
+- **WHEN** a subagent file fails to save
+- **THEN** system throws an error with message "Failed to save subagent file for '{name}': {error}"
+
+#### Scenario: Partial save failure with multiple targets
+- **WHEN** user selects "Both" targets and a subagent file fails to save to one directory
+- **THEN** system still attempts to save to the other directory before throwing an error
+
+### Requirement: User Feedback
+WHILE fetching and installing the kit, THE SYSTEM SHALL display progress information and show detailed success message with exact installation paths.
+
+#### Scenario: Display fetching progress
+- **WHEN** fetching the kit
+- **THEN** system displays a spinner with text "Fetching kit {kitId}..."
+
+#### Scenario: Display processing progress
+- **WHEN** processing the kit
+- **THEN** system updates the spinner text to "Processing kit \"{name}\"..."
+
+#### Scenario: Display saving prompts progress
+- **WHEN** saving prompts
+- **THEN** system updates the spinner text to "Saving {count} prompts..."
+
+#### Scenario: Display saving subagents progress
+- **WHEN** saving subagents
+- **THEN** system updates the spinner text to "Saving {count} subagents..."
+
+#### Scenario: Display success message with exact paths
+- **WHEN** installation completes successfully
+- **THEN** system displays "Successfully installed kit \"{name}\": {promptsCount} prompts, {subagentsCount} subagents"
+- **THEN** system displays exact installation paths showing where files were saved
+
+#### Scenario: Display error message
+- **WHEN** any error occurs during the process
+- **THEN** system displays "Kit fetch failed: {error}" and exits with code 1

package/openspec/changes/archive/2026-02-01-add-kit-install-prompts/specs/kit-install-prompts/spec.md

@@ -0,0 +1,90 @@
+## ADDED Requirements
+
+### Requirement: User can select target AI tool
+The system SHALL prompt the user to select which AI tool to install the kit to: Claude, Augment, or Both.
+
+#### Scenario: User selects Claude only
+- **WHEN** user runs `auggiegw kit <kit-id>` without `--target` flag
+- **THEN** system displays interactive prompt with options: Claude, Augment, Both
+- **WHEN** user selects "Claude"
+- **THEN** system installs kit files only to Claude directories
+
+#### Scenario: User selects Augment only
+- **WHEN** user runs `auggiegw kit <kit-id>` without `--target` flag
+- **THEN** system displays interactive prompt with options: Claude, Augment, Both
+- **WHEN** user selects "Augment"
+- **THEN** system installs kit files only to Augment directories
+
+#### Scenario: User selects Both
+- **WHEN** user runs `auggiegw kit <kit-id>` without `--target` flag
+- **THEN** system displays interactive prompt with options: Claude, Augment, Both
+- **WHEN** user selects "Both"
+- **THEN** system installs kit files to both Claude and Augment directories
+
+#### Scenario: User provides target via CLI flag
+- **WHEN** user runs `auggiegw kit <kit-id> --target claude`
+- **THEN** system skips the target prompt and uses "claude" as the target
+
+### Requirement: User can select installation scope
+The system SHALL prompt the user to select the installation scope: User level or Project level.
+
+#### Scenario: User selects user level installation
+- **WHEN** user runs `auggiegw kit <kit-id>` without `--scope` flag
+- **THEN** system displays interactive prompt with options: User level, Project level
+- **WHEN** user selects "User level"
+- **THEN** system installs kit files to home directory paths (~/.augment or ~/.claude)
+
+#### Scenario: User selects project level installation
+- **WHEN** user runs `auggiegw kit <kit-id>` without `--scope` flag
+- **THEN** system displays interactive prompt with options: User level, Project level
+- **WHEN** user selects "Project level"
+- **THEN** system installs kit files to current working directory paths (./.augment or ./.claude)
+
+#### Scenario: User provides scope via CLI flag
+- **WHEN** user runs `auggiegw kit <kit-id> --scope project`
+- **THEN** system skips the scope prompt and uses "project" as the scope
+
+### Requirement: System resolves installation paths based on selections
+The system SHALL resolve the correct installation paths based on the user's target and scope selections.
+
+#### Scenario: Claude target with user scope
+- **WHEN** user selects target "Claude" and scope "User level"
+- **THEN** system resolves paths to ~/.claude/commands/ and ~/.claude/agents/
+
+#### Scenario: Augment target with project scope
+- **WHEN** user selects target "Augment" and scope "Project level"
+- **THEN** system resolves paths to ./.augment/commands/ and ./.augment/agents/
+
+#### Scenario: Both targets with user scope
+- **WHEN** user selects target "Both" and scope "User level"
+- **THEN** system resolves paths to both ~/.augment/ and ~/.claude/ directories
+
+#### Scenario: Both targets with project scope
+- **WHEN** user selects target "Both" and scope "Project level"
+- **THEN** system resolves paths to both ./.augment/ and ./.claude/ directories
+
+### Requirement: System creates directories automatically
+The system SHALL automatically create target directories if they do not exist.
+
+#### Scenario: Target directory does not exist
+- **WHEN** system attempts to save files to a directory that does not exist
+- **THEN** system creates the directory recursively before saving files
+
+#### Scenario: Multiple target directories need creation
+- **WHEN** user selects "Both" targets and directories do not exist
+- **THEN** system creates all required directories for both Claude and Augment
+
+### Requirement: System displays installation paths in success message
+The system SHALL display the exact installation paths in the success message after kit installation completes.
+
+#### Scenario: Single target installation
+- **WHEN** kit installation completes successfully with single target
+- **THEN** success message includes exact paths where prompts and subagents were installed
+
+#### Scenario: Both targets installation
+- **WHEN** kit installation completes successfully with both targets
+- **THEN** success message includes exact paths for both Claude and Augment installations
+
+#### Scenario: Success message shows file counts per location
+- **WHEN** kit installation completes successfully
+- **THEN** success message shows the number of prompts and subagents installed to each location

package/openspec/changes/archive/2026-02-01-add-kit-install-prompts/tasks.md

@@ -0,0 +1,62 @@
+## 1. Add Dependencies
+
+- [x] 1.1 Add @clack/prompts dependency using `bun add @clack/prompts`
+
+## 2. Add Type Definitions
+
+- [x] 2.1 Add AITarget type: 'claude' | 'augment' | 'both'
+- [x] 2.2 Add InstallScope type: 'user' | 'project'
+- [x] 2.3 Add KitInstallConfig interface with targets, scope, and paths properties
+- [x] 2.4 Add KitOptions interface with optional target and scope properties
+
+## 3. Create Prompt Functions
+
+- [x] 3.1 Create promptAITarget() function using @clack/prompts select() with options: Claude, Augment, Both
+- [x] 3.2 Create promptInstallScope() function using @clack/prompts select() with options: User level, Project level
+
+## 4. Create Path Resolution Function
+
+- [x] 4.1 Create resolveInstallPaths() function that takes target and scope parameters
+- [x] 4.2 Implement logic to resolve base directory based on scope (os.homedir() for user, process.cwd() for project)
+- [x] 4.3 Implement logic to build paths object based on target selection (augment, claude, or both)
+- [x] 4.4 Return KitInstallConfig object with resolved paths
+
+## 5. Refactor File Saving Functions
+
+- [x] 5.1 Create savePromptToPath() function that accepts prompt and directory path parameters
+- [x] 5.2 Implement prompt file saving logic with YAML frontmatter to specified path
+- [x] 5.3 Create saveSubagentToPath() function that accepts subagent, directory path, and isClaudeTarget parameters
+- [x] 5.4 Implement subagent file saving logic with YAML frontmatter to specified path
+- [x] 5.5 Apply model name mapping only when isClaudeTarget is true in saveSubagentToPath()
+
+## 6. Update handleKit Function
+
+- [x] 6.1 Add options parameter to handleKit() function signature
+- [x] 6.2 Implement target selection logic: use options.target if provided, otherwise call promptAITarget()
+- [x] 6.3 Implement scope selection logic: use options.scope if provided, otherwise call promptInstallScope()
+- [x] 6.4 Call resolveInstallPaths() with selected target and scope to get installation config
+- [x] 6.5 Update prompt installation loop to iterate over config.paths and call savePromptToPath() for each target
+- [x] 6.6 Update subagent installation loop to iterate over config.paths and call saveSubagentToPath() for each target
+- [x] 6.7 Update success message to show exact installation paths from config
+
+## 7. Update Command Definition
+
+- [x] 7.1 Add --target option to kit command with description and valid values (claude, augment, both)
+- [x] 7.2 Add --scope option to kit command with description and valid values (user, project)
+- [x] 7.3 Update action handler to pass options to handleKit()
+
+## 8. Remove Old Functions
+
+- [x] 8.1 Remove old savePromptToFile() function (replaced by savePromptToPath())
+- [x] 8.2 Remove old saveSubagentToFile() function (replaced by saveSubagentToPath())
+
+## 9. Quality Assurance
+
+- [x] 9.1 Run `bun run lint` to check code quality
+- [x] 9.2 Fix any linting errors manually (no --unsafe flag)
+- [x] 9.3 Run `bun run build` to verify the build succeeds
+- [x] 9.4 Test kit command with interactive prompts (no flags)
+- [x] 9.5 Test kit command with --target flag only
+- [x] 9.6 Test kit command with --scope flag only
+- [x] 9.7 Test kit command with both --target and --scope flags
+- [x] 9.8 Verify files are created in correct locations for each scenario

package/openspec/changes/archive/2026-02-01-add-opencode-agent-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-01

package/openspec/changes/archive/2026-02-01-add-opencode-agent-support/design.md

@@ -0,0 +1,131 @@
+## Context
+
+The `auggiegw` CLI tool currently supports installing kits (prompts and subagents) to two AI tools: Claude and Augment. Both use similar directory structures (`~/.claude/` and `~/.augment/`) and identical YAML frontmatter formats.
+
+OpenCode is a third AI coding assistant that requires:
+- Different directory structure: `~/.config/opencode/` (user level) and `.opencode/` (project level)
+- Different YAML frontmatter for subagents: requires `mode: subagent` field, excludes `model` field
+
+The existing implementation in `src/cli.ts` has:
+- `AITarget` type: `'claude' | 'augment' | 'both'`
+- Path resolution logic in `resolveInstallPaths()`
+- Save functions: `savePromptToPath()` and `saveSubagentToPath()`
+- Interactive prompts using `@clack/prompts`
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add OpenCode as a supported installation target
+- Handle OpenCode's unique directory structure and YAML format
+- Maintain backward compatibility with existing `claude`, `augment`, and `both` options
+- Support installing to OpenCode alone or in combination with other targets
+- Provide clear user feedback showing OpenCode installation paths
+
+**Non-Goals:**
+- Changing the existing behavior of Claude and Augment installations
+- Supporting other AI tools beyond Claude, Augment, and OpenCode
+- Auto-detecting which AI tools are installed on the user's system
+- Validating OpenCode installation or configuration
+
+## Decisions
+
+### Decision 1: Target Selection UX
+**Choice:** Add `opencode` as a fourth option, keep `both` for backward compatibility, add multi-select capability
+
+**Rationale:**
+- `both` remains as legacy option (Claude + Augment) to avoid breaking existing scripts
+- Users can select individual targets: `claude`, `augment`, `opencode`
+- Users can select multiple targets via comma-separated flags: `--target claude,opencode`
+- Interactive mode shows all three individual options plus `both` for convenience
+
+**Alternatives considered:**
+- Replace `both` with `all` (BREAKING - rejected)
+- Always use multi-select UI (more complex UX - rejected)
+- Add `all` as fifth option (too many options - rejected)
+
+### Decision 2: AITarget Type Definition
+**Choice:** Extend type to `'claude' | 'augment' | 'opencode' | 'both'`
+
+**Rationale:**
+- Minimal change to existing type system
+- `both` continues to mean "Claude + Augment" for backward compatibility
+- Internal logic can expand `both` to `['claude', 'augment']` array
+- OpenCode is treated as a separate, equal target
+
+**Alternatives considered:**
+- Use array type `('claude' | 'augment' | 'opencode')[]` (requires refactoring all usages - rejected)
+- Add `all` value meaning all three (adds complexity without clear benefit - rejected)
+
+### Decision 3: Path Resolution Strategy
+**Choice:** Extend `resolveInstallPaths()` to handle OpenCode paths based on scope
+
+**Paths:**
+- User level: `~/.config/opencode/commands/` and `~/.config/opencode/agents/`
+- Project level: `./.opencode/commands/` and `./.opencode/agents/`
+
+**Rationale:**
+- Follows OpenCode's documented directory structure
+- Consistent with existing pattern for Claude and Augment
+- `~/.config/` is standard for user-level config on Unix-like systems
+
+### Decision 4: YAML Frontmatter Handling
+**Choice:** Modify `saveSubagentToPath()` to accept target type and conditionally format YAML
+
+**For OpenCode subagents:**
+```yaml
+---
+mode: subagent
+name: "Agent Name"
+description: "Description"
+color: "#FF5733"
+---
+```
+
+**For Claude/Augment subagents (unchanged):**
+```yaml
+---
+name: "Agent Name"
+description: "Description"
+model: "claude-sonnet-4"
+color: "#FF5733"
+---
+```
+
+**Rationale:**
+- OpenCode requires `mode: subagent` field
+- OpenCode does not use `model` field (model selection is handled by OpenCode itself)
+- Prompts/commands use identical format across all three tools (no changes needed)
+
+**Alternatives considered:**
+- Create separate `saveSubagentToOpenCode()` function (code duplication - rejected)
+- Always include both formats (invalid YAML for each tool - rejected)
+
+### Decision 5: Flag Support for Multiple Targets
+**Choice:** Support comma-separated values in `--target` flag: `--target claude,opencode`
+
+**Rationale:**
+- Enables automation scripts to install to multiple specific targets
+- More flexible than requiring `both` or adding new combined options
+- Follows common CLI pattern (e.g., `--include *.js,*.ts`)
+
+**Implementation:**
+- Parse comma-separated string into array
+- Validate each target value
+- Pass array to installation logic
+
+## Risks / Trade-offs
+
+**Risk:** OpenCode directory structure or YAML format changes in future versions
+→ **Mitigation:** Document the OpenCode version this implementation targets; add version detection in future if needed
+
+**Risk:** Users expect `both` to include OpenCode after this change
+→ **Mitigation:** Keep `both` as legacy (Claude + Augment only); document clearly in help text and error messages
+
+**Trade-off:** Adding fourth target option increases UI complexity
+→ **Accepted:** The benefit of OpenCode support outweighs the minor increase in option count
+
+**Trade-off:** Conditional YAML formatting in `saveSubagentToPath()` adds complexity
+→ **Accepted:** Keeps code DRY; alternative (separate functions) would duplicate more logic
+
+**Risk:** Project-level `.opencode/` directory conflicts with other tools
+→ **Mitigation:** This is OpenCode's documented structure; users who use OpenCode will expect this directory

package/openspec/changes/archive/2026-02-01-add-opencode-agent-support/proposal.md

@@ -0,0 +1,35 @@
+## Why
+
+The CLI tool currently supports installing kits (prompts and subagents) to Claude and Augment only. OpenCode is a popular AI coding assistant that uses a different directory structure and YAML format. Adding OpenCode support enables users to install kits to all three major AI tools from a single command.
+
+## What Changes
+
+- Add `opencode` as a new target option alongside `claude` and `augment`
+- Support OpenCode's unique directory structure (`~/.config/opencode/` for user level, `.opencode/` for project level)
+- Handle OpenCode's different YAML frontmatter format for subagents (requires `mode: subagent` field, no `model` field)
+- Update interactive prompts to include OpenCode as a target option
+- Update target selection to support combinations (claude, augment, opencode, or multiple selections)
+- Extend path resolution logic to handle OpenCode paths
+- Update success messages to show OpenCode installation paths
+
+## Capabilities
+
+### New Capabilities
+- `opencode-agent-support`: Support for installing kits to OpenCode AI tool with its specific directory structure and YAML format requirements
+
+### Modified Capabilities
+- `kit-command`: Extend target selection to include OpenCode as an installation target option
+
+## Impact
+
+**Affected Code:**
+- `src/cli.ts`: Type definitions (`AITarget`), path constants, prompt functions, save functions, path resolution logic, kit installation handler
+
+**User Experience:**
+- Users will see "OpenCode" as a new option when running `auggiegw kit <kit-id>`
+- Flag usage: `--target opencode` or `--target claude,augment,opencode` for multiple targets
+- Installation paths will include OpenCode directories in success messages
+
+**Backward Compatibility:**
+- Non-breaking: Existing `claude`, `augment`, and `both` options continue to work as before
+- New `opencode` option is additive