fix(templates): start generated docs with H1 headings

[Pluviobyte]

Summary

Fixes #1138.

OpenSpec's built-in generated markdown templates currently start with second-level headings such as ## Why, ## ADDED Requirements, ## Context, and task group headings. Markdownlint's MD041 rule expects generated markdown files to start with a top-level heading.

This PR adds first-line H1 headings to generated proposal, specs, design, and tasks templates while preserving the existing section structure that OpenSpec parsers consume.

Changes

• Add # Proposal, # Specifications, # Design, and # Tasks to the built-in spec-driven templates.
• Add the same H1 headings to the built-in workspace-planning templates.
• Update schema init default template generation so newly scaffolded custom schemas also start generated docs with H1 headings.
• Add a regression test that checks built-in templates start with the expected top-level headings.

Verification

• pnpm exec vitest run test/core/artifact-graph/instruction-loader.test.ts test/core/parsers/markdown-parser.test.ts test/core/parsers/requirement-blocks.test.ts
• pnpm run build
• pnpm run lint
• pnpm test (89 files, 1656 tests)

Summary by CodeRabbit

• Documentation
  • Enhanced template structure for design documents, proposals, specifications, and task lists with consistent top-level formatting and organized section layouts across schema templates.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: acb6f044-5de1-4ed3-84b5-73b6411cf81c

📥 Commits

Reviewing files that changed from the base of the PR and between bc7ab26 and 9d4a84e.

📒 Files selected for processing (10)

• schemas/spec-driven/templates/design.md
• schemas/spec-driven/templates/proposal.md
• schemas/spec-driven/templates/spec.md
• schemas/spec-driven/templates/tasks.md
• schemas/workspace-planning/templates/design.md
• schemas/workspace-planning/templates/proposal.md
• schemas/workspace-planning/templates/spec.md
• schemas/workspace-planning/templates/tasks.md
• src/commands/schema.ts
• test/core/artifact-graph/instruction-loader.test.ts

---

📝 Walkthrough

Walkthrough

This PR adds top-level markdown headings to eight schema template files and their code-generation paths to comply with markdown linting rule MD041. Templates now begin with # Design, # Proposal, # Specifications, or # Tasks headers, mirroring updates to the default template generation logic and a new validation test.

Changes

Template heading standardization

Layer / File(s)	Summary
Template files with top-level headings schemas/spec-driven/templates/design.md, schemas/spec-driven/templates/proposal.md, schemas/spec-driven/templates/spec.md, schemas/spec-driven/templates/tasks.md, schemas/workspace-planning/templates/design.md, schemas/workspace-planning/templates/proposal.md, schemas/workspace-planning/templates/spec.md, schemas/workspace-planning/templates/tasks.md	Eight schema template files now begin with artifact-type headings (# Design, # Proposal, # Specifications, # Tasks) followed by their existing subsection structure.
Default template generation update src/commands/schema.ts	The createDefaultTemplate() function now generates template strings with top-level headings before existing subsections. The default case changes from ## ${artifactId} to # ${artifactId}.
Template heading validation test test/core/artifact-graph/instruction-loader.test.ts	A new loadTemplate test verifies that built-in templates across both schemas start with expected top-level headings for proposal, spec, design, and tasks template types.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• Fission-AI/OpenSpec#410: Both PRs involve the schema/template-loading workflow; this PR updates template headings and defaults while the other PR works with the instruction-loader that consumes these templates.
• Fission-AI/OpenSpec#414: This PR directly extends instruction-loader testing to validate the heading changes introduced in template generation.

Suggested reviewers

• TabishB
• alfred-openspec

Poem

🐰 A hop, skip, and jump through the templates we go,
With headings now first, as the linters do know,
Compliance is here, from the files to the code,
MD041 approved on this tidy new road! ✨

🚥 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 clearly and concisely describes the primary change: adding H1 headings to generated markdown templates to comply with markdown standards.
Linked Issues check	✅ Passed	The PR successfully implements all coding requirements from issue #1138: adds specified H1 headings (Proposal, Design, Specifications, Tasks) to all template files in both schema locations and updates schema init default template generation accordingly.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing H1 headings for templates. Test additions verify the implementation, and no unrelated modifications are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}