smithy-model-update

name	smithy-model-update
description	Use when the vendored AWS Smithy models under vendor/api-models-aws change, or when API coverage, README service tables, TODO unimplemented-service lists, generated model/wire files, or service dossiers need to be reconciled with the current Smithy checkout.

Smithy Model Update

Purpose

Coordinate the repo-wide response to vendor/api-models-aws changes. A model refresh can affect service discovery, generated model.rs / wire.rs, API coverage, README output, docs, service dossiers, and .agents/docs/TODO.md; handle those surfaces together so stale model state does not leak into later work.

Quick Audit

Run the bundled drift check first:

python3 .agents/skills/smithy-model-update/scripts/audit_smithy_model_update.py

Use --check for a gate and --json when another script or agent needs structured output. The audit compares:

• model directories in vendor/api-models-aws/models
• service crates under crates/winterbaume-*
• CRATE_TO_MODEL in .agents/skills/api-coverage/scripts/generate_coverage.py
• CRATE_DISPLAY_INFO in .agents/skills/update-readme/scripts/update_readme.py
• the flat ### Services Not Yet Implemented section in .agents/docs/TODO.md

If the audit reports drift, patch the affected files before regenerating derived docs.

Workflow

1. Identify what changed in the Smithy checkout:

   git diff -- vendor/api-models-aws
   find vendor/api-models-aws/models -maxdepth 1 -type d | sort
   

2. Reconcile service identity:

   • For every implemented service crate, ensure CRATE_TO_MODEL maps the crate package name to the exact model directory.
   • Add compact-name exceptions where the crate drops hyphens or AWS SDK naming differs, such as winterbaume-apigatewaymanagement -> apigatewaymanagementapi or winterbaume-costandusagereport -> cost-and-usage-report-service.
   • Ensure CRATE_DISPLAY_INFO has a human-readable name for every service crate that appears in coverage output.
   • Keep helper crates out of service coverage maps: winterbaume-core, winterbaume-server, winterbaume-terraform, winterbaume-tfstate, parser/evaluator helper crates, Redis adapters, and winterbaume-ec2-generated.

3. Reconcile TODO:

   • Update .agents/docs/TODO.md ### Services Not Yet Implemented to match Smithy models that have no service crate.
   • Keep richer service-specific work items out of the flat list when they already exist above it. Today pinpoint-sms-voice-v2 is tracked as a richer follow-up.
   • Preserve unrelated staged or user edits in TODO; only touch the service list unless the user asks for broader cleanup.

4. Regenerate derived reports when mappings change:

   python3 .agents/skills/api-coverage/scripts/generate_coverage.py
   python3 .agents/skills/update-readme/scripts/update_readme.py
   

   If remote moto/floci/kumo refresh fails because of network restrictions, rerun with approval or use the existing cache if the task only needs local Smithy/crate alignment.

5. If generated model.rs or wire.rs is stale, do not edit it manually. Edit tools/smithy-codegen/src/gen_serializers.rs only for generator bugs, rebuild through ./.agents/bin/cargo.sh, then regenerate the affected crate using the model directory from the service dossier or smithy-codegen list-services.

6. For service-specific behaviour changes, read .agents/docs/services/INDEX.md and the matching service dossier before editing handlers, state, Terraform converters, or tests. Update the dossier if the new model adds durable facts that future agents need.

Validation

After edits, rerun:

python3 .agents/skills/smithy-model-update/scripts/audit_smithy_model_update.py --check

For documentation-only mapping/TODO work, this audit plus git diff is usually enough. For Rust source or generated code changes, also run the mandatory per-crate gate from AGENTS.md:

./.agents/bin/cargo.sh clippy -p <crate> --all-targets --all-features -- -D warnings
./.agents/bin/cargo.sh fmt -p <crate> -- --check

Common Failure Modes

• Coverage says a newly implemented crate is unimplemented because CRATE_TO_MODEL was not updated.
• README generation falls back to poor service names because CRATE_DISPLAY_INFO was not updated.
• TODO drifts because it was copied from an old API_COVERAGE.md instead of the current Smithy checkout.
• A model slug and crate suffix differ only by hyphens, but some services need explicit exceptions; do not assume every compact mapping is semantically correct.
• Running bare cargo bypasses the project cache wrapper. Always use ./.agents/bin/cargo.sh for Rust builds or codegen rebuilds.