Skip to content

Changes show as "Untitled Change" when following official proposal template #225

@virakngauv

Description

@virakngauv

TL;DR when running openspec show [change-id] --json --deltas-only, I get title as "Untitled Change" because the change template doesn't include a title by default.

$ openspec show update-game-rules-codenames-compliance --json --deltas-only
Warning: Ignoring flags not applicable to change: scenarios
{
  "id": "update-game-rules-codenames-compliance",
  "title": "Untitled Change",
  "deltaCount": 0,
  "deltas": []
}

Description

When users create change proposals following the official AGENTS.md template, the
openspec show command displays "Untitled Change" instead of the actual change title.

Reproduction Steps

  1. Initialize OpenSpec: openspec init
  2. Create a proposal following the template in AGENTS.md (without title header)
  3. Run: openspec show --json --deltas-only
  4. Observe: "title": "Untitled Change"

Root Cause

The issue is a mismatch between the proposal template and the title extraction logic:

Template location: src/core/templates/agents-template.ts (lines ~159-177) The template
shows this proposal structure:

## Why
[1-2 sentences on problem/opportunity]

## What Changes
- [Bullet list of changes]
- [Mark breaking changes with **BREAKING**]

## Impact
- Affected specs: [list capabilities]
- Affected code: [key files/systems]

Code location: src/commands/change.ts (line ~122) The extractTitle function expects:

private extractTitle(content: string): string {
  const match = content.match(/^#\s+(?:Change:\s+)?(.+)$/m);
  return match ? match[1].trim() : 'Untitled Change';
}

Expected Behavior

Changes should display their actual title instead of "Untitled Change" when users follow
the official template.

Proposed Fix

Update the proposal template in agents-template.ts to include the required title header:

# Change: [Name of change]

## Why
[1-2 sentences on problem/opportunity]

## What Changes
- [Bullet list of changes]
- [Mark breaking changes with **BREAKING**]

## Impact
- Affected specs: [list capabilities]
- Affected code: [key files/systems]

Alternative Solutions

  1. Update extractTitle to generate a title from the change ID if no header is found
  2. Make the title header optional and display the change directory name as fallback

Impact

• Severity: Medium (UX issue, doesn't break functionality)
• Scope: Template update only, no breaking changes
• Users affected: All new OpenSpec users following the official template

Additional Context

The regex supports both # Title and # Change: Title formats, but the template doesn't
include either, causing the fallback to "Untitled Change".

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions