Harden the product-coupled agent skill delivery without duplicating its source

[sergeliatko]

Outcome

Harden the typescript-wsdl-client agent-skill artifact as part of the product release without duplicating its generated references or forcing the repository into the standalone template layout.

Preserve the current model: evergreen skill source plus a manifest of fluid product documentation produces one installable release ZIP tied to the product version.

Verified Current State

These facts were observed on 2026-07-27:

• The public product release is v1.0.4.
• agent-skill/SKILL.md, agent-skill/install.mjs, and agent-skill/evergreen/ are maintained source.
• agent-skill/reference-manifest.json selects fluid sections from canonical product documentation.
• Packaged references are generated under dist/ and include references/SOURCE-MAP.json.
• scripts/validate-agent-skill.mjs validates frontmatter, manifest sources, extracted headings, links, forbidden files, and deterministic staged output.
• scripts/build-agent-skill.mjs builds a deterministic ZIP with stable entry metadata.
• Product CI and release preflight already include skill validation.
• The draft workflow checks out the exact tag and guards release state.
• The draft release uploads one agent-skill ZIP but no checksum manifest or artifact attestation.
• The release ZIP installer supports an explicit target and requires --force for replacement.
• NPM publication already uses OIDC trusted publishing with provenance.
• Open pull request Build(deps): bump yargs from 18.0.0 to 18.1.0 #124 is a dependency update and is separate from this skill task.

Role Decision

• Keep the agent skill version tied to the product release.
• Keep product documentation as the source of truth for fluid references.
• Keep agent-skill/ as the maintained source model unless a tested consumer need justifies a different path.
• Do not commit generated reference copies under a second canonical skills/ tree.
• Treat the release ZIP as the independently installable artifact.

A direct src/ to skills/ migration does not apply here. The current source is a generator input, while the complete installable skill exists only after manifest-driven packaging.

Evidence Sources

• Skill Base Template v1.4.0
• Completed standalone pilot handoff
• docs/agent-skill.md
• agent-skill/reference-manifest.json
• scripts/validate-agent-skill.mjs
• scripts/build-agent-skill.mjs
• .github/workflows/release-draft.yml
• .github/workflows/release-package.yml

Use the baseline to close delivery gaps while preserving the stronger product-specific source-map and release-preflight model.

Required Work

Source and Generation

• Preserve the evergreen versus fluid ownership boundary.
• Keep every generated reference traceable through SOURCE-MAP.json.
• Fail when required source sections move, disappear, or generate broken links.
• Prove two complete ZIP builds from the same tree and tag are byte-identical.
• Verify the archive contains only the installable folder and expected files.
• Keep product and agent-skill version identity synchronized.

Behavioral Evaluation

• Add focused fixtures for choosing pipeline versus narrower commands.
• Verify agents refuse to edit generated output as maintained source.
• Verify dependency and Node-version guidance follows the product version.
• Verify incomplete WSDL or catalog input produces a bounded clarification or discovery step.
• Verify installation never edits IDE, MCP, shell, or global configuration.

Release Delivery

• Produce SHA256SUMS for the agent-skill ZIP.
• Add GitHub artifact attestation for the ZIP where supported.
• Download and verify the uploaded ZIP before a draft is considered ready.
• Extract the uploaded ZIP in an isolated directory and run its installer.
• Load the installed skill and run one representative consumer fixture.
• Preserve the current immutable tag and abandoned-candidate rules.
• Preserve NPM provenance as a separate product-package control.

GitHub CLI Applicability

• Run gh skill publish --dry-run only as an applicability experiment.
• Confirm whether GitHub CLI can consume the complete generated skill without committing generated references.
• Record a no-change decision if direct GitHub delivery would require a duplicate canonical tree.
• Do not claim gh skill update support unless a supported direct-install path exists across releases.

The release ZIP installer and its source map are the current supported update boundary. Verify replacement from the previous release ZIP to the next release in a disposable consumer directory, including the behavior when local modifications exist.

Explicit Exclusions

• Do not create a separate agent-skill version.
• Do not duplicate fluid documentation under a committed skills/ tree.
• Do not replace the product release workflow with the standalone template workflow.
• Do not weaken full product preflight or NPM provenance.
• Do not edit generated consumer output.
• Do not merge dependency pull request Build(deps): bump yargs from 18.0.0 to 18.1.0 #124 as part of this task.
• Do not publish a release without explicit authority for that exact product version.

Suggested Work Sequence

• Reinspect repository instructions, current product release state, open pull requests, and the latest skill asset.
• Record the delivery-channel and path no-change decisions.
• Extend the existing validator and fixtures.
• Add checksum, attestation, uploaded-asset verification, and installed-artifact smoke tests.
• Update docs/agent-skill.md, release guidance, changelog, and release notes.
• Run npm run ci and the final npm run release:preflight -- vX.Y.Z only at the repository-defined release stage.
• Link implementation and release evidence to this issue.

Completion Criteria

• One maintained source model still produces one complete installable skill.
• Generated references remain traceable and deterministic.
• Behavioral fixtures protect the consumer workflow and generated-output boundary.
• The release ZIP is checksummed, attestable, downloaded, verified, and installation-tested.
• Direct GitHub CLI delivery is either proven without duplication or explicitly rejected.
• Existing product tags and releases remain immutable.
• No consuming repository was changed.

[sergeliatko]

Implemented and fully verified for the unpublished v1.0.5 candidate.

• Delivery hardening merged in PR #132.
• Release commit: 0bcc769.
• Successful draft workflow: run 31945126481.
• Unpublished draft: TypeScript WSDL Client v1.0.5.
• Draft assets include typescript-wsdl-client-agent-skill-v1.0.5.zip and SHA256SUMS; the downloaded ZIP matched SHA-256 8f8a8d97a9d43a823f379dedb5990d793a03307014dff84466cfc7bd52bc4e14 and passed gh attestation verify.
• The workflow verified downloaded-asset checksum, provenance, clean extraction, previous-release replacement, isolated installation, installed skill content, and the representative weather-WSDL pipeline fixture.
• Release preflight passed 19/19 gates; main CI and CodeQL are green.

The release remains a draft and no npm publication was triggered.