Feedback from production migration: branch validation bug and documentation inconsistencies

[jonshaffer]

Summary

We recently completed a production migration to spec-kit and received detailed feedback from GitHub Copilot during code review. This issue documents several bugs and inconsistencies found in the spec-kit templates and scripts.

Critical Issues

1. Branch Name Byte Length Validation Bug

Location: .specify/scripts/bash/create-new-feature.sh:279

Issue: The script uses ${#BRANCH_NAME} (character count) to enforce GitHub's 244-byte branch name limit, but this doesn't correctly handle multi-byte UTF-8 characters.

Impact: Branch names with non-ASCII characters could exceed GitHub's actual byte limit and cause failures.

Current Code:

if [ ${#BRANCH_NAME} -gt 244 ]; then

Suggested Fix:

if [ $(printf '%s' "$BRANCH_NAME" | wc -c) -gt 244 ]; then

Or update the comment to clarify it's a character limit, not a byte limit.

---

2. Branch Naming Convention Inconsistency

Location: Constitution template vs create-new-feature.sh

Issue: The constitution template (.specify/memory/constitution.md) specifies branch format as feat/###-feature-name, but the create-new-feature.sh script actually generates ###-feature-name (without the feat/ prefix).

Impact: Creates confusion for users adopting spec-kit about the expected branch naming pattern.

Suggested Fix: Either:

• Update the constitution template to match actual behavior: ###-feature-name
• Or update the script to add the feat/ prefix

---

Documentation Issues

3. Incorrect PowerShell Example

Location: .claude/commands/speckit.specify.md:59

Issue: PowerShell example shows incorrect parameter syntax:

-Json -Number 5 -ShortName "user-auth"

But the bash script uses GNU-style arguments:

--json --number 5 --short-name "user-auth"

Impact: PowerShell users following the documentation will get errors.

Suggested Fix: Either:

• Remove the PowerShell example entirely
• Correct it to show proper bash invocation from PowerShell
• Or create a separate PowerShell wrapper script

---

4. Agent Type Documentation Incomplete

Location: .specify/scripts/bash/update-agent-context.sh

Issue: Several locations are missing 'roo' and 'codebuddy' from agent type lists:

• Line 33 (header comment)
• Line 38 (usage comment)
• Line 630 (error message)
• Line 729 (usage summary)

Impact: Documentation doesn't reflect all supported agent types.

Suggested Fix: Add 'roo' and 'codebuddy' to all agent type documentation.

---

Minor Issues

5. Path Typo in Template

Location: .claude/commands/speckit.tasks.md:42

Issue: Shows .specify.specify/templates/ instead of .specify/templates/

Suggested Fix: Remove duplicate .specify in path.

---

6. Duplicate Flag in Example

Location: .claude/commands/speckit.specify.md:58

Issue: Bash example shows duplicate --json flag:

.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5

Suggested Fix: Remove the duplicate --json flag.

---

Context

• Migration project: https://github.com/systmms/gogetmy/pull/108
• All issues identified by GitHub Copilot during PR review
• We've fixed issues feat: implement in Japanese #5 and shell scripts in the scripts directory fail to execute #6 locally in our fork

Priority

1. Critical: Branch name byte validation bug (Add John Lam as contributor and release badge #1)
2. High: Branch naming inconsistency (Fix release workflow to work with repository rules #2)
3. Medium: PowerShell documentation (Update README.md #3)
4. Low: Agent type documentation (doco(spec-driven): Fix small typo in spec-driven.md #4), path typo (feat: implement in Japanese #5), duplicate flag (shell scripts in the scripts directory fail to execute #6)

Thank you for creating spec-kit! We're excited to use it for our React Native + Next.js project.