fix: openspec config template mixes sequence and mapping (invalid YAML)

[juansacdev]

🔗 Linked Issue

Closes #1007

---

🏷️ PR Type

What kind of change does this PR introduce?

• type:bug — Bug fix (non-breaking change that fixes an issue)
• type:feature — New feature (non-breaking change that adds functionality)
• type:docs — Documentation only
• type:refactor — Code refactoring (no functional changes)
• type:chore — Build, CI, or tooling changes
• type:breaking-change — Breaking change (fix or feature that changes existing behavior)

---

📝 Summary

internal/assets/skills/_shared/openspec-convention.md documents the openspec/config.yaml shape SDD phases read. The rules.apply example mixed a block sequence with sibling mapping keys under the same YAML node, which is invalid YAML — a node can't be both a sequence and a mapping. Any strict parser rejects it:

python3 -c "import yaml; yaml.safe_load(open('f.yaml'))"

Since sdd-init and this shared convention doc instruct agents to create real openspec/config.yaml files from this exact template, any project bootstrapped from it inherits a config file that fails to parse.

The fix nests the guideline bullet under a guidelines: key so tdd and test_command remain valid mapping siblings — the same shape the doc already uses for rules.verify:

apply:
  guidelines:
    - Follow existing code patterns
  tdd: false           # Set to true to enable RED-GREEN-REFACTOR
  test_command: ""

I checked internal/ Go source (rg -n "test_command|strict_tdd|rules" --type go) and confirmed no Go code parses openspec/config.yaml's rules section — it's prompt/documentation-consumed only, so this is a pure documentation-shape fix with no parser coupling. I also surveyed the rest of the repo (rg -n "apply:" --type md --type go) for the same mixing pattern; the analogous blocks in docs/openspec-config.md and the repo's own openspec/config.yaml already keep apply: as a pure sequence, so they don't hit this bug and were left untouched.

---

📂 Changes

File / Area	What Changed
internal/assets/skills/_shared/openspec-convention.md	Nested the rules.apply guideline bullet under a new guidelines: key so the block is valid YAML

---

🧪 Test Plan

Unit Tests

go test ./...

E2E Tests (Docker required)

cd e2e && ./docker-test.sh

• Unit tests pass (go test ./...)
• E2E tests pass (cd e2e && ./docker-test.sh) — not run; change is a docs/template-only markdown edit with no runtime code path
• Manually tested locally — validated the corrected YAML block with yaml.safe_load

---

🤖 Automated Checks

The following checks run automatically on this PR:

Check	Status	Description
Check PR Cognitive Load	⏳	PR should stay within 400 changed lines (additions + deletions) or use size:exception
Check Issue Reference	⏳	PR body must contain Closes/Fixes/Resolves #N
Check Issue Has status:approved	⏳	Linked issue must have been approved before work began
Check PR Has type:* Label	⏳	Exactly one type:* label must be applied
Unit Tests	⏳	go test ./... must pass
E2E Tests	⏳	cd e2e && ./docker-test.sh must pass

---

✅ Contributor Checklist

• PR is linked to an issue with status:approved
• PR stays within 400 changed lines, or I have requested/obtained maintainer-applied size:exception with rationale documented
• I have added the appropriate type:* label to this PR — I don't have write access to apply labels; type:docs requested above
• Unit tests pass (go test ./...)
• E2E tests pass (cd e2e && ./docker-test.sh) — not applicable, no runtime code touched
• I have updated documentation if necessary
• My commits follow Conventional Commits format
• My commits do not include Co-Authored-By trailers

---

💬 Notes for Reviewers

This is a 2-line, 1-file diff. Issue #1007 is freshly filed alongside this PR (I don't have write access to the repo, so I can't self-apply status:approved — flagging that the linked-issue CI check will stay pending until a maintainer approves it).

Summary by CodeRabbit

• Documentation
  • Updated the sample configuration rules to include a new guidelines section under apply.
  • Reorganized the existing “Follow existing code patterns” guidance into the new nested structure for clearer formatting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0b53b05f-54c0-493e-bf81-ae51ae7e2701

📥 Commits

Reviewing files that changed from the base of the PR and between ab184f2 and 9b1aaa6.

📒 Files selected for processing (1)

• internal/assets/skills/_shared/openspec-convention.md

---

📝 Walkthrough

Walkthrough

Modifies the sample YAML structure in openspec-convention.md, introducing a guidelines key under rules.apply and nesting the existing Follow existing code patterns bullet beneath it, correcting the YAML structure.

Changes

Documentation YAML fix

Layer / File(s)	Summary
Nest guidelines bullet under new key internal/assets/skills/_shared/openspec-convention.md	Adds a guidelines: mapping key under rules: apply: and nests the existing - Follow existing code patterns bullet as its child.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related issues

• openspec config template mixes sequence and mapping under rules.apply (invalid YAML) #1007: Addresses the same invalid sequence/mapping mix in the rules.apply YAML sample in this file.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the YAML template fix in the openspec config sample.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}