feat: change the frontmatter of the Codebuddy Slash Commands

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/proposal.md

@@ -0,0 +1,16 @@
+## Why
+
+CodeBuddy slash command configurator currently uses inconsistent frontmatter fields compared to other tools. It uses `category` and `tags` fields (like Crush) but should use `argument-hint` field (like Factory, Auggie, and Codex) for better consistency. Additionally, the `proposal` command is missing frontmatter fields entirely. After reviewing CodeBuddy's official documentation, the correct format should use `description` and `argument-hint` fields with square bracket parameter format.
+
+## What Changes
+
+- Replace `category` and `tags` fields with `argument-hint` field in CodeBuddy frontmatter
+- Add missing frontmatter fields to the `proposal` command
+- Use correct square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- Ensure consistency with CodeBuddy's official documentation
+
+## Impact
+
+- Affected specs: cli-init, cli-update
+- Affected code: `src/core/configurators/slash/codebuddy.ts`
+- CodeBuddy users will get proper argument hints in the correct format for slash commands

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/specs/cli-init/spec.md

@@ -0,0 +1,75 @@
+## MODIFIED Requirements
+
+### Requirement: Slash Command Configuration
+
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Antigravity
+- **WHEN** the user selects Antigravity during initialization
+- **THEN** create `.agent/workflows/openspec-proposal.md`, `.agent/workflows/openspec-apply.md`, and `.agent/workflows/openspec-archive.md`
+- **AND** ensure each file begins with YAML frontmatter that contains only a `description: <stage summary>` field followed by the shared OpenSpec workflow instructions wrapped in managed markers
+- **AND** populate the workflow body with the same proposal/apply/archive guidance used for other tools so Antigravity behaves like Windsurf while pointing to the `.agent/workflows/` directory
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for CodeBuddy Code
+- **WHEN** the user selects CodeBuddy Code during initialization
+- **THEN** create `.codebuddy/commands/openspec/proposal.md`, `.codebuddy/commands/openspec/apply.md`, and `.codebuddy/commands/openspec/archive.md`
+- **AND** populate each file from shared templates that include CodeBuddy-compatible YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** use square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cline
+- **WHEN** the user selects Cline during initialization
+- **THEN** create `.clinerules/workflows/openspec-proposal.md`, `.clinerules/workflows/openspec-apply.md`, and `.clinerules/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Crush
+- **WHEN** the user selects Crush during initialization
+- **THEN** create `.crush/commands/openspec/proposal.md`, `.crush/commands/openspec/apply.md`, and `.crush/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include Crush-specific frontmatter with OpenSpec category and tags
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Factory Droid
+- **WHEN** the user selects Factory Droid during initialization
+- **THEN** create `.factory/commands/openspec-proposal.md`, `.factory/commands/openspec-apply.md`, and `.factory/commands/openspec-archive.md`
+- **AND** populate each file from shared templates that include Factory-compatible YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** include the `$ARGUMENTS` placeholder in the template body so droid receives any user-supplied input
+- **AND** wrap the generated content in OpenSpec managed markers so `openspec update` can safely refresh the commands
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/specs/cli-update/spec.md

@@ -0,0 +1,56 @@
+## MODIFIED Requirements
+
+### Requirement: Slash Command Updates
+
+The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.
+
+#### Scenario: Updating slash commands for Antigravity
+- **WHEN** `.agent/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh the OpenSpec-managed portion of each file so the workflow copy matches other tools while preserving the existing single-field `description` frontmatter
+- **AND** skip creating any missing workflow files during update, mirroring the behavior for Windsurf and other IDEs
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for CodeBuddy Code
+- **WHEN** `.codebuddy/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using the shared CodeBuddy templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** use square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- **AND** preserve any user customizations outside the OpenSpec managed markers
+
+#### Scenario: Updating slash commands for Cline
+- **WHEN** `.clinerules/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Crush
+- **WHEN** `.crush/commands/` contains `openspec/proposal.md`, `openspec/apply.md`, and `openspec/archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Crush-specific frontmatter with OpenSpec category and tags
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Factory Droid
+- **WHEN** `.factory/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using the shared Factory templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** ensure the template body retains the `$ARGUMENTS` placeholder so user input keeps flowing into droid
+- **AND** update only the content inside the OpenSpec managed markers, leaving any unmanaged notes untouched
+- **AND** skip creating missing files during update
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+
+- [x] 1.1 Update CodeBuddy frontmatter to use `argument-hint` instead of `category` and `tags`
+- [x] 1.2 Add missing frontmatter fields to the `proposal` command
+- [x] 1.3 Ensure all three commands (proposal, apply, archive) have consistent frontmatter structure
+- [x] 1.4 Test the changes by running `openspec init` and `openspec update`

openspec/specs/cli-init/spec.md

@@ -187,7 +187,8 @@ The init command SHALL generate slash command files for supported editors using
 #### Scenario: Generating slash commands for CodeBuddy Code
 - **WHEN** the user selects CodeBuddy Code during initialization
 - **THEN** create `.codebuddy/commands/openspec/proposal.md`, `.codebuddy/commands/openspec/apply.md`, and `.codebuddy/commands/openspec/archive.md`
-- **AND** populate each file from shared templates so command text matches other tools
+- **AND** populate each file from shared templates that include CodeBuddy-compatible YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** use square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
 - **AND** each template includes instructions for the relevant OpenSpec workflow stage
 
 #### Scenario: Generating slash commands for Cline

openspec/specs/cli-update/spec.md

@@ -50,6 +50,7 @@ The update command SHALL always update the core OpenSpec files and display an AS
 - **AND** if a root-level stub exists, refresh it so it still directs contributors to `@/openspec/AGENTS.md`
 
 ### Requirement: Slash Command Updates
+
 The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.
 
 #### Scenario: Updating slash commands for Antigravity
@@ -64,8 +65,9 @@ The update command SHALL refresh existing slash command files for configured too
 
 #### Scenario: Updating slash commands for CodeBuddy Code
 - **WHEN** `.codebuddy/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
-- **THEN** refresh each file using shared templates
-- **AND** ensure templates include instructions for the relevant workflow stage
+- **THEN** refresh each file using the shared CodeBuddy templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** use square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- **AND** preserve any user customizations outside the OpenSpec managed markers
 
 #### Scenario: Updating slash commands for Cline
 - **WHEN** `.clinerules/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`

src/core/configurators/slash/codebuddy.ts

@@ -10,21 +10,18 @@ const FILE_PATHS: Record<SlashCommandId, string> = {
 const FRONTMATTER: Record<SlashCommandId, string> = {
   proposal: `---
 name: OpenSpec: Proposal
-description: Scaffold a new OpenSpec change and validate strictly.
-category: OpenSpec
-tags: [openspec, change]
+description: "Scaffold a new OpenSpec change and validate strictly."
+argument-hint: "[feature description or request]"
 ---`,
   apply: `---
 name: OpenSpec: Apply
-description: Implement an approved OpenSpec change and keep tasks in sync.
-category: OpenSpec
-tags: [openspec, apply]
+description: "Implement an approved OpenSpec change and keep tasks in sync."
+argument-hint: "[change-id]"
 ---`,
   archive: `---
 name: OpenSpec: Archive
-description: Archive a deployed OpenSpec change and update specs.
-category: OpenSpec
-tags: [openspec, archive]
+description: "Archive a deployed OpenSpec change and update specs."
+argument-hint: "[change-id]"
 ---`
 };
 

test/core/init.test.ts

@@ -1121,21 +1121,21 @@ describe('InitCommand', () => {
       const proposalContent = await fs.readFile(codeBuddyProposal, 'utf-8');
       expect(proposalContent).toContain('---');
       expect(proposalContent).toContain('name: OpenSpec: Proposal');
-      expect(proposalContent).toContain('description: Scaffold a new OpenSpec change and validate strictly.');
-      expect(proposalContent).toContain('category: OpenSpec');
+      expect(proposalContent).toContain('description: "Scaffold a new OpenSpec change and validate strictly."');
+      expect(proposalContent).toContain('argument-hint: "[feature description or request]"');
       expect(proposalContent).toContain('<!-- OPENSPEC:START -->');
       expect(proposalContent).toContain('**Guardrails**');
 
       const applyContent = await fs.readFile(codeBuddyApply, 'utf-8');
       expect(applyContent).toContain('---');
       expect(applyContent).toContain('name: OpenSpec: Apply');
-      expect(applyContent).toContain('description: Implement an approved OpenSpec change and keep tasks in sync.');
+      expect(applyContent).toContain('description: "Implement an approved OpenSpec change and keep tasks in sync."');
       expect(applyContent).toContain('Work through tasks sequentially');
 
       const archiveContent = await fs.readFile(codeBuddyArchive, 'utf-8');
       expect(archiveContent).toContain('---');
       expect(archiveContent).toContain('name: OpenSpec: Archive');
-      expect(archiveContent).toContain('description: Archive a deployed OpenSpec change and update specs.');
+      expect(archiveContent).toContain('description: "Archive a deployed OpenSpec change and update specs."');
       expect(archiveContent).toContain('openspec archive <id> --yes');
     });