fix(templates): start generated docs with H1 headings

schemas/spec-driven/templates/design.md

@@ -1,3 +1,5 @@
+# Design
+
 ## Context
 
 <!-- Background and current state -->

schemas/spec-driven/templates/proposal.md

@@ -1,3 +1,5 @@
+# Proposal
+
 ## Why
 
 <!-- Explain the motivation for this change. What problem does this solve? Why now? -->

schemas/spec-driven/templates/spec.md

@@ -1,3 +1,5 @@
+# Specifications
+
 ## ADDED Requirements
 
 ### Requirement: <!-- requirement name -->

schemas/spec-driven/templates/tasks.md

@@ -1,3 +1,5 @@
+# Tasks
+
 ## 1. <!-- Task Group Name -->
 
 - [ ] 1.1 <!-- Task description -->

schemas/workspace-planning/templates/design.md

@@ -1,3 +1,5 @@
+# Design
+
 ## Context
 
 Summarize the workspace planning context, relevant linked areas, and constraints.

schemas/workspace-planning/templates/proposal.md

@@ -1,3 +1,5 @@
+# Proposal
+
 ## Why
 
 Describe the shared product goal, problem, or opportunity that makes this workspace-level change worth planning.

schemas/workspace-planning/templates/spec.md

@@ -1,3 +1,5 @@
+# Specifications
+
 ## ADDED Requirements
 
 ### Requirement: <workspace requirement name>

schemas/workspace-planning/templates/tasks.md

@@ -1,3 +1,5 @@
+# Tasks
+
 ## 1. Workspace Planning
 
 - [ ] 1.1 Confirm the shared product goal and unresolved scope questions.

src/commands/schema.ts

@@ -928,7 +928,9 @@ export function registerSchemaCommand(program: Command): void {
 function createDefaultTemplate(artifactId: string): string {
   switch (artifactId) {
     case 'proposal':
-      return `## Why
+      return `# Proposal
+
+## Why
 
 <!-- Describe the motivation for this change -->
 
@@ -950,7 +952,9 @@ function createDefaultTemplate(artifactId: string): string {
 `;
 
     case 'specs':
-      return `## ADDED Requirements
+      return `# Specifications
+
+## ADDED Requirements
 
 ### Requirement: Example requirement
 
@@ -962,7 +966,9 @@ Description of the requirement.
 `;
 
     case 'design':
-      return `## Context
+      return `# Design
+
+## Context
 
 <!-- Background and context -->
 
@@ -989,15 +995,17 @@ Description and rationale.
 `;
 
     case 'tasks':
-      return `## Implementation Tasks
+      return `# Tasks
+
+## Implementation Tasks
 
 - [ ] Task 1
 - [ ] Task 2
 - [ ] Task 3
 `;
 
     default:
-      return `## ${artifactId}
+      return `# ${artifactId}
 
 <!-- Add content here -->
 `;

test/core/artifact-graph/instruction-loader.test.ts

@@ -20,6 +20,22 @@ describe('instruction-loader', () => {
       expect(template).toContain('## What Changes');
     });
 
+    it('should start built-in generated markdown templates with top-level headings', () => {
+      const expectedHeadings = [
+        ['proposal.md', '# Proposal'],
+        ['spec.md', '# Specifications'],
+        ['design.md', '# Design'],
+        ['tasks.md', '# Tasks'],
+      ] as const;
+
+      for (const schemaName of ['spec-driven', 'workspace-planning']) {
+        for (const [templatePath, heading] of expectedHeadings) {
+          const template = loadTemplate(schemaName, templatePath);
+          expect(template.split(/\r?\n/, 1)[0], `${schemaName}/${templatePath}`).toBe(heading);
+        }
+      }
+    });
+
     it('should throw TemplateLoadError for non-existent template', () => {
       expect(() => loadTemplate('spec-driven', 'nonexistent.md')).toThrow(
         TemplateLoadError