update-schema-docs — Schema-driven documentation synchronization

This skill ensures docs/front-matter-spec.md, docs/architecture.md, and the public docs site's landing/onboarding pages (docs/index.md, docs/getting-started.md) stay synchronized when src/azure_functions_agents/config/schema.py changes. docs/front-matter-reference.md is already auto-generated (via eng/scripts/generate_config_reference.py), but spec, architecture, and docs-site pages require intelligent example generation and contextual updates.

When to use

Use this skill during Phase 5 (Docs) of the medium+ feature pipeline when:

• schema.py has been modified (new fields, models, or validation logic)
• New public configuration surface was added
• After implementing config-related features
• When asked to synchronize documentation with schema changes

What this skill does

1. Detect changes: Compare current schema.py against the last commit or baseline to identify added/modified fields and models.
2. Update front-matter-spec.md:
   • Add usage examples for new fields
   • Update existing examples if field semantics changed
   • Add validation examples for new constraints
   • Ensure Examples section coverage matches the reference
3. Review architecture.md:
   • Flag if new models suggest pipeline stage changes
   • Check if module map needs updates
   • Verify configuration precedence rules still hold
4. Sync the docs site landing pages:
   • If the change introduces a new user-facing capability (new trigger type, new frontmatter field a typical user would reach for, new model provider), check whether docs/index.md's feature bullet list or docs/getting-started.md's walkthrough should mention it
   • Skip this step for internal-only or low-level schema changes (e.g. tightened validation, refactors) that don't change what a new user sees
5. Generate PR checklist: List all doc changes made + items needing human review

Prerequisites

• schema.py changes committed or staged
• Understanding of what the schema change enables (from the FRD)
• eng/scripts/generate_config_reference.py already run (reference up to date)

Workflow

Step 1: Analyze schema changes

1. Read the current src/azure_functions_agents/config/schema.py
2. Identify what changed:
   • New models (e.g., new trigger types, new capabilities)
   • New fields on existing models (e.g., GlobalConfig, AgentSpec)
   • Changed field types or validators
   • New Pydantic constraints or defaults
3. Categorize changes by impact:
   • Agent frontmatter surface: affects AgentSpec → needs examples in spec
   • Global config surface: affects GlobalConfig → needs global examples
   • Trigger surface: affects trigger models → needs trigger examples
   • Structural: new pipeline stage or module → needs architecture review

Step 2: Update front-matter-spec.md

For each new or changed field:

1. Locate the relevant section:
   • Agent fields → ### Agent Front Matter examples
   • Global fields → ### Global Configuration examples
   • Trigger fields → ### Triggers or ### Advanced Examples
2. Generate usage examples:
   • Start from the field's type, description, and default in schema.py
   • Create realistic YAML examples showing:
     • Basic usage (most common case)
     • Edge cases (if validation is complex)
     • Integration with related fields
   • Follow existing example style (concise, commented, realistic values)
3. Add validation examples if needed:
   • If the field has custom validators (e.g., CRON expressions, URL patterns)
   • Show valid and invalid examples with explanations
4. Cross-reference to the reference:
   • Link to front-matter-reference.md#<section> for full API details
   • Ensure the spec focuses on how to use, reference on what exists

Step 3: Review architecture.md

1. Check if module map needs updates:
   • New models in schema.py may indicate new modules in config/, discovery/, etc.
   • Verify the module map in §3 reflects reality
   • If discovery logic changed, update the discovery stage description
2. Check if pipeline stages changed:
   • New configuration may affect discover → translate → register → execute flow
   • Document new capabilities or constraints in the relevant stage
3. Check configuration precedence:
   • If new global/agent/env interactions exist, update §4 precedence rules
   • Ensure the precedence diagram (if present) is still accurate

Step 4: Sync docs-site landing pages

1. Decide if this change is docs-site-worthy:
   • New trigger type, new top-level frontmatter field, new model provider, or any change that adds a bullet-worthy capability → yes
   • Internal refactors, stricter validation, or field renames with no new capability → no, skip
2. Update docs/index.md (if worthy):
   • Add a concise bullet to the feature list matching the existing bullet style (bold lead-in, em dash, one sentence)
3. Update docs/getting-started.md (if worthy and walkthrough-relevant):
   • Only touch the quickstart steps if the new capability changes the minimal path to a working agent (e.g. a new required config file, a new provider env var). Don't pad the walkthrough with optional features.
4. Cross-check README.md: the docs site and README duplicate the same feature bullet list — if you update one, flag (or update) the other so they don't drift.

Step 5: Generate PR checklist

Create a checklist of:

• front-matter-reference.md updated (auto-generated via script)
• front-matter-spec.md examples added for: <list new fields>
• architecture.md module map verified
• docs/index.md and docs/getting-started.md checked (updated / not applicable)
• Human review needed for: <list architectural concerns>
• Validation examples added for: <list complex validators>

Example: Adding a new agent field

Scenario: AgentSpec gained a new field retry_policy: RetryPolicyConfig | None = None

Actions:

1. Analyze: New optional field on AgentSpec, type is a nested model
2. Update front-matter-spec.md:

   ---
   name: Resilient Agent
   description: Agent with automatic retry logic
   retry_policy:
     max_attempts: 3
     backoff_multiplier: 2
     initial_delay_ms: 1000
   trigger:
     type: http_trigger
     args:
       route: resilient
   ---

   Add to ### Agent Front Matter examples with commentary explaining retry behavior
3. Review architecture.md:
   • Check if runner stage (§3.4) mentions retry logic
   • If RetryPolicyConfig is in a new module, add to module map
   • No pipeline stage changes needed (execution detail)
4. Checklist:
   • front-matter-reference.md updated
   • front-matter-spec.md: added retry_policy example under Agent Front Matter
   • architecture.md: verified runner stage mentions retry (update if not)
   • docs/index.md, docs/getting-started.md: not applicable (advanced/optional field, not quickstart-worthy)
   • Human review: decide if retry belongs in runner or client_manager

Example: Adding a new trigger type

Scenario: New CosmosDbTrigger model added to schema.py

Actions:

1. Analyze: New trigger model → new public surface in trigger.type
2. Update front-matter-spec.md:

   ---
   name: Cosmos Change Feed Agent
   description: Responds to Cosmos DB document changes
   trigger:
     type: cosmosdb_trigger
     args:
       database_name: my-database
       container_name: my-container
       connection: CosmosDbConnection
       lease_container_name: leases
   ---

   Add to ### Triggers section with explanation of change feed behavior
3. Update docs/triggers.md (if it exists):
   • Add detailed CosmosDB trigger documentation
   • Explain lease container, change feed continuation, etc.
4. Review architecture.md:
   • Discovery stage: verify it mentions trigger discovery from schema
   • Registration stage: confirm it handles new binding type
   • Module map: ensure registration/triggers.py is listed
5. Checklist:
   • front-matter-reference.md updated (auto via TRIGGER_TYPES dict in script)
   • front-matter-spec.md: added cosmosdb_trigger example
   • docs/triggers.md: added detailed CosmosDB section
   • architecture.md: verified trigger registration flow
   • docs/index.md: added "Cosmos DB change feed" to trigger bullet examples; docs/getting-started.md: not applicable (not part of minimal quickstart path)
   • Human review: binding extension dependency (needs host.json update?)

Output format

When this skill completes, provide:

1. Summary of changes made:

   Schema changes detected:
   - Added field: AgentSpec.retry_policy (optional, nested config)
   - Modified field: GlobalConfig.timeout (type widened to int | str)
   
   Documentation updates:
   - front-matter-spec.md: Added retry_policy example (line 245)
   - front-matter-spec.md: Updated timeout example to show string format (line 89)
   - architecture.md: Verified runner stage docs (no changes needed)
   - docs/index.md, docs/getting-started.md: not applicable (advanced field, not quickstart-relevant)

2. PR checklist (markdown, ready to paste):

   ## Documentation Updates (Schema Changes)
   
   - [x] `front-matter-reference.md` regenerated via `generate_config_reference.py`
   - [x] `front-matter-spec.md` examples added for: `retry_policy`
   - [x] `front-matter-spec.md` timeout example updated to show string support
   - [x] `architecture.md` module map verified (no changes needed)
   - [x] `docs/index.md` / `docs/getting-started.md` checked (not applicable)
   - [ ] **Human review:** Retry logic placement (runner vs client_manager?)

3. Architectural concerns (if any):

   ⚠️ Human review needed:
   - New RetryPolicyConfig model suggests retry logic in the runner.
     Does this conflict with MAF's built-in retry? Check AgentClient docs.
   - If retry is per-request, should it live in client_manager instead?

Guardrails

• Do not auto-generate prose sections of architecture.md — only verify module map and flag inconsistencies. Design decisions require human judgment.
• Match the existing example style in front-matter-spec.md — concise, realistic, focused on common use cases.
• Link liberally — examples in spec should reference the reference for complete API details.
• Favor explicit over exhaustive — one good example > ten variations.
• This skill complements, does not replace, human review — complex architectural implications still need human sign-off in the FRD Decisions log.

Integration with AGENTS.md Phase 5

This skill is invoked during Phase 5 (Docs) of the medium+ pipeline, after eng/scripts/generate_config_reference.py has been run. The workflow becomes:

1. Run generate_config_reference.py → updates front-matter-reference.md
2. Run this skill → updates front-matter-spec.md examples, reviews architecture.md, and syncs docs/index.md / docs/getting-started.md when the change adds a new user-facing capability
3. Human reviews the PR checklist and architectural concerns
4. Commit documentation updates alongside implementation

Files touched

• Input (read):
  • src/azure_functions_agents/config/schema.py (detect changes)
  • docs/front-matter-reference.md (understand new API surface)
  • docs/frds/<NNNN>-<slug>.md (understand intent of schema changes)
• Output (write):
  • docs/front-matter-spec.md (add/update examples)
  • docs/triggers.md (if trigger surface changed)
  • docs/index.md (if a new user-facing capability warrants a feature bullet)
  • docs/getting-started.md (if the new capability changes the minimal quickstart path)
• Output (review/flag):
  • docs/architecture.md (flag inconsistencies, suggest updates)
  • README.md (flag if user-facing quickstart examples need updates)

Success criteria

• Every new field in schema.py has at least one usage example in front-matter-spec.md
• Existing examples updated if field semantics changed
• Architecture.md module map matches reality
• docs/index.md and docs/getting-started.md checked for every schema change that adds a new user-facing capability (bullet added or explicitly deemed not applicable)
• Clear PR checklist with human review items flagged
• No "orphaned" documentation (examples for removed fields)