feat(enricher): enriched context, rewritten templates, custom prompts

[spencercjh]

Summary

• Enriched context passing: Pass OpenAPI spec metadata (format, enum, constraints, tags, existing descriptions) to prompt templates so LLMs generate more precise descriptions
• Rewritten built-in prompts: Type-specific system prompts with few-shot examples and quality guidelines for API, schema, param, and response templates
• Custom prompt support: Allow users to override built-in prompts via .spec-forge.yaml, with startup validation and warning on invalid keys

Closes #63

Changes

Area	Description
internal/enricher/prompt/templates.go	Rewritten 4 built-in prompts; added enriched fields to context types; added join FuncMap; template validation on Set()
internal/enricher/processor/schema.go	Exported BuildConstraintsString / BuildEnumStrings shared helpers
internal/enricher/processor/processor.go	Added enriched fields to FieldElement, ParamFieldItem, converters
internal/enricher/enricher.go	Populate tags/existing desc for API; warn on invalid custom prompt keys; deduplicated constraint helpers
internal/enricher/config.go	Added CustomPromptConfig, CustomPromptsFromMap helper
internal/config/config.go	Added CustomPrompts to EnrichConfig
cmd/enrich.go, cmd/generate.go	Wire custom prompts via shared helper
.spec-forge.example.yaml	Documented customPrompts section
docs/plans/	Design doc + implementation plan

Test plan

• make test — all tests pass
• make lint — 0 issues
• Unit tests for enriched context rendering, API tags, enum/constraint extraction
• Integration test for custom prompts (TestEnricher_CustomPrompts)
• E2E verified with DeepSeek API — descriptions leverage format/enum/constraint context

[Copilot]

Pull request overview

This PR improves the enricher’s prompt quality and flexibility by passing richer OpenAPI metadata into prompt templates, rewriting the built-in prompt templates, and adding .spec-forge.yaml support for user-defined prompt overrides.

Changes:

• Enrich prompt context with OpenAPI metadata (format, enums, constraints, tags, existing descriptions).
• Rewrite built-in prompt templates (API/schema/param/response) with clearer guidance and few-shot examples.
• Add customPrompts configuration plumbing (config → CLI → enricher) with template parse validation and warnings on invalid keys.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal/enricher/prompt/templates.go	Adds enriched context fields, join template func, rewrites built-in prompts, and validates custom templates in Set()
internal/enricher/prompt/templates_test.go	Adds tests ensuring enriched context renders across all template types and tags are included
internal/enricher/processor/schema.go	Populates schema field enriched metadata; exports enum/constraint helper builders
internal/enricher/processor/schema_test.go	Tests schema field enrichment for constraints/enum/format
internal/enricher/processor/processor.go	Extends FieldElement/ParamFieldItem and propagates enriched metadata into prompt contexts
internal/enricher/processor/batch.go	Adds a linter suppression comment for param range-copy behavior
internal/enricher/enricher.go	Applies custom prompts; passes API tags/existing docs; enriches parameter context with enum/constraints/format
internal/enricher/enricher_test.go	Adds tests for enriched param context, API tags propagation, and custom prompt overrides
internal/enricher/config.go	Introduces enricher-layer CustomPromptConfig and mapping helper from config-layer types
internal/config/config.go	Adds customPrompts to EnrichConfig and defines CustomPromptCfg
cmd/enrich.go	Wires customPrompts from loaded config into enricher config
cmd/generate.go	Wires customPrompts into the generate→enrich pipeline
.spec-forge.example.yaml	Documents enrich.customPrompts configuration
docs/plans/2026-03-31-p5-prompt-optimization-design.md	Design documentation for the prompt optimization work
docs/plans/2026-03-31-p5-prompt-optimization-implementation.md	Implementation plan / checklist for the prompt optimization work

Comments suppressed due to low confidence (1)

internal/enricher/enricher.go:322

• ParamFieldItem includes an ExistingDescription field (and the param prompt template renders it), but collectParameterGroups never populates it. In --force mode this means custom/built-in templates won't receive the existing parameter description from the spec, reducing the intended “rewrite/translate existing docs” behavior. Consider setting ExistingDescription from param.Description when building ParamFieldItem (and keep the SetValue closure writing back to param.Description).

				param := paramRef.Value
				fieldType := ""
				format := ""
				var enum []string
				var constraints string
				if param.Schema != nil && param.Schema.Value != nil {
					schemaVal := param.Schema.Value
					fieldType = getSchemaTypeString(schemaVal)
					format = schemaVal.Format
					enum = processor.BuildEnumStrings(schemaVal.Enum)
					constraints = processor.BuildConstraintsString(schemaVal)
				}

				// Capture for closure
				p := param
				params = append(params, processor.ParamFieldItem{
					ParamName:   param.Name,
					ParamIn:     param.In,
					FieldType:   fieldType,
					Required:    param.Required,
					Format:      format,
					Enum:        enum,
					Constraints: constraints,
					SetValue: func(desc string) {
						p.Description = desc
					},
				})

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.