From 3034b90a0e036860e0cb4302b9ac4270578bd81e Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Wed, 1 Oct 2025 08:41:28 +0200
Subject: [PATCH] feat: Implement Issue #55 - Schema-based draft generation
 with content instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This implementation enhances the existing generate-stub command to utilize
content field instructions from schemas, providing guided document generation
with specific placeholder text instead of generic "TODO" messages.

## Key Features Added:

### Enhanced Schema-Based Generation
- Content instructions from schemas (x-markitect-content-instructions) are now used
- Schema reference metadata included in generated drafts for traceability
- Intelligent fallback to generic placeholders for schemas without instructions
- Full integration with existing generate-stub CLI command and options

### StubGenerator Enhancements
- New _extract_content_instruction_from_heading_schema method for instruction parsing
- Enhanced _get_placeholder_content method with schema-aware content generation
- Updated method signatures to support schema_file_path parameter throughout
- Robust handling of both content instruction and legacy schema formats

### CLI Integration
- Updated generate-stub command documentation with content instruction examples
- Enhanced help text explaining automatic content instruction usage
- Fixed output file generation to include schema references correctly
- Maintained full backward compatibility with existing usage patterns

### Technical Implementation
- Schema reference comments (<!-- Generated from schema: path -->) in generated drafts
- Content instruction text extracted from x-markitect-content-instructions fields
- Support for all instruction types (description, example, constraint, template)
- Integration with existing heading hierarchy and placeholder style systems

## Integration and Compatibility:
- Seamless integration with Issue #54 content field instructions
- Full backward compatibility with existing schemas and usage
- Works with outline mode schemas and heading text capture features
- Comprehensive error handling and graceful degradation

## Testing and Validation:
- Comprehensive test suite covering all acceptance criteria
- Integration tests with schema-generate → generate-stub workflow
- Validation of schema reference metadata and content instruction usage
- Backward compatibility testing with legacy schemas

This completes Issue #55 with full feature implementation, comprehensive testing,
and enhanced documentation for schema-based draft generation capabilities.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 markitect/cli.py                              |  21 +-
 markitect/stub_generator.py                   |  92 ++-
 ..._issue_55_schema_based_draft_generation.py | 632 ++++++++++++++++++
 3 files changed, 730 insertions(+), 15 deletions(-)
 create mode 100644 tests/test_issue_55_schema_based_draft_generation.py

diff --git a/markitect/cli.py b/markitect/cli.py
index ffa3242a..ce68c171 100644
--- a/markitect/cli.py
+++ b/markitect/cli.py
@@ -1984,7 +1984,9 @@ def generate_stub(config, schema_file, output, style, title):
     Generate a markdown stub/template from a JSON schema.
 
     Creates a markdown document with proper heading hierarchy and placeholder
-    content based on the structural definitions in the JSON schema.
+    content based on the structural definitions in the JSON schema. When schemas
+    include content instructions (x-markitect-content-instructions), the generated
+    stub will use specific guidance text instead of generic placeholders.
 
     SCHEMA_FILE: Path to the JSON schema file
 
@@ -1992,6 +1994,19 @@ def generate_stub(config, schema_file, output, style, title):
         markitect generate-stub blog_schema.json
         markitect generate-stub schema.json --output template.md
         markitect generate-stub schema.json --style detailed --title "My Document"
+
+        # Content instructions will be used automatically when present in schema
+        markitect generate-stub schema_with_instructions.json
+
+    Content Instructions:
+        When a schema contains x-markitect-content-instructions-enabled: true,
+        the generated stub will include specific content guidance from the schema
+        instead of generic "TODO" placeholders. This is especially useful with
+        schemas created using the --include-content-instructions option.
+
+    Schema Reference:
+        Generated stubs include a comment referencing the source schema file
+        for validation and traceability purposes.
     """
     try:
         if config.get('verbose'):
@@ -2009,7 +2024,7 @@ def generate_stub(config, schema_file, output, style, title):
             schema = json.load(f)
 
         stub_content = generator.generate_stub_from_schema(
-            schema, placeholder_style=style, title=title
+            schema, placeholder_style=style, title=title, schema_file_path=schema_file
         )
 
         # Mode-based output logic
@@ -2021,7 +2036,7 @@ def generate_stub(config, schema_file, output, style, title):
 
         # Output to file or stdout
         if output:
-            generator.generate_stub_to_file(schema, output, style, title)
+            generator.generate_stub_to_file(schema, output, style, title, schema_file)
             click.echo(f"✅ Stub generated: {output}")
 
             if config.get('verbose'):
diff --git a/markitect/stub_generator.py b/markitect/stub_generator.py
index 319bfdb2..5e0a16de 100644
--- a/markitect/stub_generator.py
+++ b/markitect/stub_generator.py
@@ -34,7 +34,8 @@ class StubGenerator:
 
     def generate_stub_from_schema(self, schema: Dict[str, Any],
                                 placeholder_style: str = 'default',
-                                title: Optional[str] = None) -> str:
+                                title: Optional[str] = None,
+                                schema_file_path: Optional[str] = None) -> str:
         """
         Generate a markdown stub from a JSON schema dictionary.
 
@@ -42,6 +43,7 @@ class StubGenerator:
             schema: JSON schema as dictionary
             placeholder_style: Style of placeholder content ('default', 'custom', 'detailed')
             title: Custom title for the document (overrides schema title)
+            schema_file_path: Optional path to schema file for reference metadata
 
         Returns:
             Generated markdown content as string
@@ -49,9 +51,17 @@ class StubGenerator:
         # Extract title
         doc_title = title or schema.get('title', DEFAULT_TITLE)
 
+        # Check if schema has content instructions enabled
+        content_instructions_enabled = schema.get('x-markitect-content-instructions-enabled', False)
+
         # Start building the markdown content
         lines = []
 
+        # Add schema reference metadata if schema file path is provided
+        if schema_file_path:
+            lines.append(f"<!-- Generated from schema: {schema_file_path} -->")
+            lines.append("")
+
         # Extract heading structure from schema
         headings_schema = schema.get('properties', {}).get('headings', {})
         heading_properties = headings_schema.get('properties', {})
@@ -60,12 +70,12 @@ class StubGenerator:
             # Create a minimal document if no heading structure is defined
             lines.append(f"# {doc_title}")
             lines.append("")
-            lines.append(self._get_placeholder_content(placeholder_style, "main"))
+            lines.append(self._get_placeholder_content(placeholder_style, "main", schema=schema))
             lines.append("")
         else:
             # Generate content based on heading structure
             lines.extend(self._generate_content_from_headings(
-                heading_properties, doc_title, placeholder_style
+                heading_properties, doc_title, placeholder_style, schema=schema
             ))
 
         return '\n'.join(lines)
@@ -90,12 +100,13 @@ class StubGenerator:
         with open(schema_file, 'r', encoding='utf-8') as f:
             schema = json.load(f)
 
-        return self.generate_stub_from_schema(schema)
+        return self.generate_stub_from_schema(schema, schema_file_path=str(schema_file))
 
     def generate_stub_to_file(self, schema: Dict[str, Any],
                             output_file: Path,
                             placeholder_style: str = 'default',
-                            title: Optional[str] = None) -> None:
+                            title: Optional[str] = None,
+                            schema_file_path: Optional[str] = None) -> None:
         """
         Generate a markdown stub and save it to a file.
 
@@ -104,8 +115,9 @@ class StubGenerator:
             output_file: Path where to save the generated markdown
             placeholder_style: Style of placeholder content
             title: Custom title for the document
+            schema_file_path: Optional path to schema file for reference metadata
         """
-        content = self.generate_stub_from_schema(schema, placeholder_style, title)
+        content = self.generate_stub_from_schema(schema, placeholder_style, title, schema_file_path)
 
         # Ensure parent directory exists
         output_file.parent.mkdir(parents=True, exist_ok=True)
@@ -114,7 +126,7 @@ class StubGenerator:
             f.write(content)
 
     def _generate_content_from_headings(self, heading_properties: Dict[str, Any],
-                                      doc_title: str, placeholder_style: str) -> List[str]:
+                                      doc_title: str, placeholder_style: str, schema: Optional[Dict[str, Any]] = None) -> List[str]:
         """Generate markdown content from heading structure."""
         lines = []
 
@@ -129,7 +141,14 @@ class StubGenerator:
             # Start with H1
             lines.append(f"# {doc_title}")
             lines.append("")
-            lines.append(self._get_placeholder_content(placeholder_style, "introduction"))
+            # Get the heading schema for level 1
+            level_1_heading_schema = heading_properties.get('level_1', {})
+            lines.append(self._get_placeholder_content(
+                placeholder_style,
+                "introduction",
+                schema=schema,
+                heading_schema=level_1_heading_schema
+            ))
             lines.append("")
 
             # Generate H2+ headings
@@ -144,7 +163,17 @@ class StubGenerator:
 
                     lines.append(f"{heading_prefix} {section_name}")
                     lines.append("")
-                    lines.append(self._get_placeholder_content(placeholder_style, f"section_level_{level}"))
+
+                    # Get the heading schema for this level
+                    level_key = f"level_{level}"
+                    heading_schema = heading_properties.get(level_key, {})
+
+                    lines.append(self._get_placeholder_content(
+                        placeholder_style,
+                        f"section_level_{level}",
+                        schema=schema,
+                        heading_schema=heading_schema
+                    ))
                     lines.append("")
         else:
             # No H1, start with whatever level is available
@@ -159,7 +188,17 @@ class StubGenerator:
 
                     lines.append(f"{heading_prefix} {section_name}")
                     lines.append("")
-                    lines.append(self._get_placeholder_content(placeholder_style, f"section_level_{level}"))
+
+                    # Get the heading schema for this level
+                    level_key = f"level_{level}"
+                    heading_schema = heading_properties.get(level_key, {})
+
+                    lines.append(self._get_placeholder_content(
+                        placeholder_style,
+                        f"section_level_{level}",
+                        schema=schema,
+                        heading_schema=heading_schema
+                    ))
                     lines.append("")
 
         return lines
@@ -194,8 +233,15 @@ class StubGenerator:
         else:
             return f"Section {index}"
 
-    def _get_placeholder_content(self, style: str, section_type: str) -> str:
+    def _get_placeholder_content(self, style: str, section_type: str, schema: Optional[Dict[str, Any]] = None, heading_schema: Optional[Dict[str, Any]] = None) -> str:
         """Get placeholder content based on style and section type."""
+        # Check if we have content instructions from schema
+        if schema and heading_schema and schema.get('x-markitect-content-instructions-enabled', False):
+            content_instruction = self._extract_content_instruction_from_heading_schema(heading_schema)
+            if content_instruction:
+                return content_instruction
+
+        # Fall back to standard placeholder generation
         generator = self.placeholder_styles.get(style, self.placeholder_styles['default'])
         return generator(section_type)
 
@@ -250,4 +296,26 @@ TODO: Add detailed content for this subsection.""",
         return detailed_placeholders.get(
             section_type,
             f"<!-- {section_type.title()} Section -->\nTODO: Add content for {section_type}."
-        )
\ No newline at end of file
+        )
+
+    def _extract_content_instruction_from_heading_schema(self, heading_schema: Dict[str, Any]) -> Optional[str]:
+        """
+        Extract content instruction from a heading schema items definition.
+
+        Args:
+            heading_schema: The schema definition for a heading level
+
+        Returns:
+            Content instruction text if found, None otherwise
+        """
+        # Navigate through the schema structure to find content instructions
+        # Schema structure: heading_schema -> items -> properties -> x-markitect-content-instructions -> const
+        items_schema = heading_schema.get('items', {})
+        if isinstance(items_schema, dict):
+            properties = items_schema.get('properties', {})
+            if isinstance(properties, dict):
+                instruction_schema = properties.get('x-markitect-content-instructions', {})
+                if isinstance(instruction_schema, dict):
+                    return instruction_schema.get('const')
+
+        return None
\ No newline at end of file
diff --git a/tests/test_issue_55_schema_based_draft_generation.py b/tests/test_issue_55_schema_based_draft_generation.py
new file mode 100644
index 00000000..37c71966
--- /dev/null
+++ b/tests/test_issue_55_schema_based_draft_generation.py
@@ -0,0 +1,632 @@
+"""
+Tests for Issue #55: Schema-based draft generation
+
+This test module implements comprehensive tests for enhanced schema-based draft
+generation that utilizes content field instructions and schema metadata.
+
+Following TDD8 methodology - these tests are written before implementation.
+"""
+
+import json
+import pytest
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from click.testing import CliRunner
+
+from markitect.cli import cli
+from markitect.stub_generator import StubGenerator
+
+
+class TestIssue55SchemaBasedDraftGeneration:
+    """Test suite for enhanced schema-based draft generation functionality."""
+
+    def setup_method(self):
+        """Set up test fixtures."""
+        self.stub_generator = StubGenerator()
+        self.runner = CliRunner()
+
+    def test_generate_stub_uses_content_instructions_from_schema(self):
+        """Test that generate-stub uses content instructions instead of generic placeholders."""
+        # Arrange
+        schema_with_instructions = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "API Documentation",
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "level": {"type": "integer"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Write the main API documentation title"
+                                    },
+                                    "x-markitect-instruction-type": {
+                                        "type": "string",
+                                        "enum": ["description"]
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        },
+                        "level_2": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "level": {"type": "integer"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Describe each API endpoint section"
+                                    },
+                                    "x-markitect-instruction-type": {
+                                        "type": "string",
+                                        "enum": ["description"]
+                                    }
+                                }
+                            },
+                            "minItems": 2,
+                            "maxItems": 2
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema_with_instructions, f, indent=2)
+            schema_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file)
+            ])
+
+            # Assert
+            assert result.exit_code == 0
+            output = result.output
+
+            # Should use specific content instructions, not generic placeholders
+            assert "Write the main API documentation title" in output
+            assert "Describe each API endpoint section" in output
+
+            # Should NOT contain generic placeholder text
+            assert "TODO: Add content for" not in output
+            assert "section_level_2 section" not in output
+
+        finally:
+            schema_file.unlink()
+
+    def test_generate_stub_includes_schema_reference_metadata(self):
+        """Test that generated drafts include reference to their source schema."""
+        # Arrange
+        schema = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Requirements Document",
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Provide the document title"
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema, f, indent=2)
+            schema_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file)
+            ])
+
+            # Assert
+            assert result.exit_code == 0
+            output = result.output
+
+            # Should include schema reference metadata
+            assert "<!-- Generated from schema:" in output or "Source schema:" in output
+            assert str(schema_file.name) in output or schema_file.name in output
+
+        finally:
+            schema_file.unlink()
+
+    def test_generate_stub_supports_different_instruction_types(self):
+        """Test that generate-stub handles different instruction types appropriately."""
+        # Arrange
+        schema_with_example_instructions = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Tutorial Guide",
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Example: Getting Started with Our API"
+                                    },
+                                    "x-markitect-instruction-type": {
+                                        "type": "string",
+                                        "enum": ["example"]
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema_with_example_instructions, f, indent=2)
+            schema_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file)
+            ])
+
+            # Assert
+            assert result.exit_code == 0
+            output = result.output
+
+            # Should use the example-type instruction
+            assert "Example: Getting Started with Our API" in output
+
+        finally:
+            schema_file.unlink()
+
+    def test_generate_stub_handles_schemas_without_content_instructions(self):
+        """Test that generate-stub gracefully handles schemas without content instructions."""
+        # Arrange - Schema without content instructions (backward compatibility)
+        schema_without_instructions = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Basic Document",
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "level": {"type": "integer"}
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema_without_instructions, f, indent=2)
+            schema_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file)
+            ])
+
+            # Assert - Should still work with generic placeholders
+            assert result.exit_code == 0
+            output = result.output
+
+            # Should fall back to generic placeholder behavior
+            assert "Basic Document" in output  # Should use schema title
+            assert len(output) > 0  # Should generate some content
+
+        finally:
+            schema_file.unlink()
+
+    def test_generate_stub_supports_output_file_with_schema_reference(self):
+        """Test that generate-stub writes to output file with schema reference."""
+        # Arrange
+        schema = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Project Plan",
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Provide the project name and overview"
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema, f, indent=2)
+            schema_file = Path(f.name)
+
+        with NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+            output_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file),
+                '--output', str(output_file)
+            ])
+
+            # Assert
+            assert result.exit_code == 0
+            assert output_file.exists()
+
+            content = output_file.read_text()
+            assert "Provide the project name and overview" in content
+            assert "Project Plan" in content
+
+        finally:
+            schema_file.unlink()
+            if output_file.exists():
+                output_file.unlink()
+
+    def test_generate_stub_validates_generated_draft_against_schema(self):
+        """Test that generated drafts can be validated against their source schema."""
+        # Arrange
+        schema = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Meeting Notes",
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Meeting title and date"
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema, f, indent=2)
+            schema_file = Path(f.name)
+
+        with NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+            draft_file = Path(f.name)
+
+        try:
+            # Act - Generate draft
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file),
+                '--output', str(draft_file)
+            ])
+
+            assert result.exit_code == 0
+
+            # Act - Validate generated draft against schema
+            validate_result = self.runner.invoke(cli, [
+                'validate',
+                str(draft_file),
+                str(schema_file)
+            ])
+
+            # Assert - Generated draft should be valid against its source schema
+            assert validate_result.exit_code == 0
+
+        finally:
+            schema_file.unlink()
+            if draft_file.exists():
+                draft_file.unlink()
+
+    def test_stub_generator_class_supports_content_instructions_directly(self):
+        """Test that StubGenerator class can be used directly with content instruction schemas."""
+        # Arrange
+        schema = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Architecture Document",
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "System architecture overview title"
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        # Act
+        stub_content = self.stub_generator.generate_stub_from_schema(schema)
+
+        # Assert
+        assert "System architecture overview title" in stub_content
+        assert "Architecture Document" in stub_content
+
+    def test_generate_stub_with_outline_mode_schema_integration(self):
+        """Test that generate-stub works with schemas created by outline mode + content instructions."""
+        # Arrange - Schema that would be generated by outline mode with content instructions
+        outline_schema_with_instructions = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Schema from user_guide.md",
+            "x-markitect-outline-mode": True,
+            "x-markitect-outline-depth": 2,
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Provide content for the 'level 1 heading' section"
+                                    },
+                                    "x-markitect-instruction-type": {
+                                        "type": "string",
+                                        "enum": ["description"]
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        },
+                        "level_2": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Provide content for the 'level 2 heading' section"
+                                    },
+                                    "x-markitect-instruction-type": {
+                                        "type": "string",
+                                        "enum": ["description"]
+                                    }
+                                }
+                            },
+                            "minItems": 3,
+                            "maxItems": 3
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(outline_schema_with_instructions, f, indent=2)
+            schema_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file)
+            ])
+
+            # Assert
+            assert result.exit_code == 0
+            output = result.output
+
+            # Should use content instructions from outline mode schema
+            assert "Provide content for the 'level 1 heading' section" in output
+            assert "Provide content for the 'level 2 heading' section" in output
+
+            # Should respect outline mode structure (depth limited to 2)
+            assert output.count('##') >= 3  # Should have multiple level 2 headings
+
+        finally:
+            schema_file.unlink()
+
+    def test_generate_stub_with_heading_text_capture_schema_integration(self):
+        """Test that generate-stub works with schemas that have heading text capture."""
+        # Arrange - Schema with both heading text capture and content instructions
+        schema_with_heading_capture = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Schema from api_docs.md",
+            "x-markitect-heading-text-capture": True,
+            "x-markitect-content-instructions-enabled": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {
+                                        "type": "string",
+                                        "enum": ["API Reference"]  # From heading text capture
+                                    },
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Complete API reference documentation"
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema_with_heading_capture, f, indent=2)
+            schema_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file)
+            ])
+
+            # Assert
+            assert result.exit_code == 0
+            output = result.output
+
+            # Should use the specific heading text from enum constraint
+            assert "# API Reference" in output
+
+            # Should use content instructions
+            assert "Complete API reference documentation" in output
+
+        finally:
+            schema_file.unlink()
+
+    def test_generate_stub_preserves_schema_metadata_in_output(self):
+        """Test that important schema metadata is preserved in the generated draft."""
+        # Arrange
+        schema_with_metadata = {
+            "$schema": "http://json-schema.org/draft-07/schema#",
+            "type": "object",
+            "title": "Design Document",
+            "description": "Template for system design documents",
+            "x-markitect-content-instructions-enabled": True,
+            "x-markitect-outline-mode": True,
+            "properties": {
+                "headings": {
+                    "type": "object",
+                    "properties": {
+                        "level_1": {
+                            "type": "array",
+                            "items": {
+                                "type": "object",
+                                "properties": {
+                                    "content": {"type": "string"},
+                                    "x-markitect-content-instructions": {
+                                        "type": "string",
+                                        "const": "Design document title and scope"
+                                    }
+                                }
+                            },
+                            "minItems": 1,
+                            "maxItems": 1
+                        }
+                    }
+                }
+            }
+        }
+
+        with NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump(schema_with_metadata, f, indent=2)
+            schema_file = Path(f.name)
+
+        try:
+            # Act
+            result = self.runner.invoke(cli, [
+                'generate-stub',
+                str(schema_file)
+            ])
+
+            # Assert
+            assert result.exit_code == 0
+            output = result.output
+
+            # Should include schema metadata information
+            assert any(marker in output.lower() for marker in [
+                "generated from", "source schema", "template for", "schema:", "outline mode"
+            ])
+
+        finally:
+            schema_file.unlink()
\ No newline at end of file