feat(validation): allow numeric-prefixed change names for ordered/tiered workflows

[chrisgoddard]

Summary

The validateChangeName function in src/utils/change-utils.ts enforces that
change names must start with a lowercase letter:

if (/^[0-9]/.test(name)) {
  return { valid: false, error: 'Change name must start with a letter' };
}

This blocks alternative conventions users might want to use such as numeric prefixes to express
execution tier ordering in multi-agent or parallel-batch workflows.

Motivation

I use OpenSpec as part of an orchestrated, multi-agent development workflows and I
need to encode execution ordering semantics directly in change-ids:

• 100-audit-codebase, 200-implement-fixes, 300-validate -- sequential tiers
• 101-01-fix-auth, 101-02-fix-session, 101-03-fix-jwt -- parallel batch within tier 100
• 801-01-fix-contradiction, 801-02-fix-claim-origin -- versioned sub-changes

Without numeric prefix support, I have to maintain a fork OpenSpec and patch the
validation manually.

Current Behavior

$ openspec new change 100-add-feature
Error: Change name must start with a letter

Proposed Change

Option A (recommended): Remove or relax the must-start-with-letter restriction:

const kebabCasePattern = /^[a-z0-9][a-z0-9]*(-[a-z0-9]+)*$/;

Option B: Make the naming pattern configurable in openspec/config.yaml:

# openspec/config.yaml
schema: spec-driven
changeNamePattern: "^[a-z0-9][-a-z0-9]*$"   # override default

Option B is more conservative but requires additional infrastructure. Option A
is a minimal, backward-compatible change -- all currently-valid names still pass,
since they start with [a-z] which is a subset of [a-z0-9].

Security Consideration

The restriction appears to exist as a safety measure against hidden files (.name)
and path traversal (..). Numeric-start names pose no such risk -- 100-feature
is a perfectly safe directory name. The explicit dot/hyphen-start guards already
prevent those attack vectors independently.

Related

• PR feat(validation): allow dots in change names as valid separators #842: Allow dots as separators (currently open) -- a similar relaxation of the strict kebab-only rule

[lsmonki]

I think the use case makes sense (ordering phases, batching, multi-agent workflows), but I’m not convinced that allowing numeric-leading names is strictly necessary to support it.

Kebab-case works well as a neutral, general-purpose naming convention. Names remain readable and stable, without encoding execution semantics directly into the identifier.

Using prefixes like "100-01-*" effectively turns the name into a container for orchestration metadata (ordering, grouping, batching). That can be useful, but it also couples naming with execution concerns.

In this specific case, the same structure can already be achieved while keeping the current validation by using letter-prefixed conventions, for example:

• "s-001-audit-codebase"
• "s-002-implement-fixes"
• "p-100-01-fix-auth"
• "p-100-02-fix-cache"

This preserves compatibility with the existing rules and makes the intent (sequential vs parallel, grouping, etc.) more explicit.

So from a practical standpoint, I don’t think a fork is strictly required here — the workflow can be modeled with a slightly different naming convention.

That said, I agree the current restriction (“must start with a letter”) is somewhat arbitrary, and relaxing it could still make sense as a general improvement.

[BearGrass]

I can understand the use case, but personally I’m not convinced this needs to be added as a feature.
If the goal is to represent ordering, grouping, or batching, I think that can already be handled within the current validation rules by using a letter-prefixed convention like task100-, t100-, or similar naming patterns.
To me, change names seem most useful as simple and stable identifiers. Once numeric-leading names are added mainly to encode orchestration semantics, the identifier starts carrying workflow metadata, which may not be necessary for OpenSpec itself.
So my current view is that this feels more like a naming convention choice than a missing capability. A convention such as task100-* or t100-* seems sufficient in practice, so I’m not sure this is worth expanding the validator for.

[chrisgoddard]

Why can't that decision be left up to the user instead of the specification?

[chrisgoddard]

While I understand that number first might not be some people's preference, I've found it works well for ensuring specific ordering between specs is preserved across any bash/list operations. I've found LLMs quickly understand the structure - XXX-YY-name - where XXX is the sequencing and -YY- lets items be done in parallel. It's also easy for the LLM to quickly scan and find the next number to use.

Either way the restriction seems more the enforcement of preference more than anything else.