Skip to content

docs(authoring): adopt scripts/ as the script packaging convention - #89

Closed
Justinvolved wants to merge 1 commit into
feat/reland-authoring-hosted-foldbackfrom
docs/scripts-packaging-convention
Closed

docs(authoring): adopt scripts/ as the script packaging convention#89
Justinvolved wants to merge 1 commit into
feat/reland-authoring-hosted-foldbackfrom
docs/scripts-packaging-convention

Conversation

@Justinvolved

Copy link
Copy Markdown
Collaborator

What

Docs-only PR that fixes the rules before any script ships. Version 4.20.0 -> 4.21.0.

  • .claude/skills/dw-skill-authoring/SKILL.md, new section Shipping scripts: the script contract (scripts/ layout per the Agent Skills spec, comment-based help with a READ-ONLY / WRITES opener, SupportsShouldProcess with -WhatIf default beyond one row, connection discovery order with no default host/port/path/token, $env:-only secrets, one shared module in dw-data-access, dw-setup-install self-contained, compatibility: frontmatter, linked ## Scripts table, forward-slash pwsh -NoProfile -File invocations). Script imports count toward bundle closure.
  • skills/dw-demo-foldback/references/fold-back-workflow.md, new Step 1c: lifting a script from a demo build. Recurrence bar, script-specific sanitization classes, one-lesson-one-home for the superseded prose, retiring the demo copy, and the smoke-test rule (write scripts local-first; a hosted install only afterwards and under dw-demo-hosted shared-install discipline).
  • skills/dw-demo-base/references/setup-checks.md: install-grade fix for a missing pwsh.
  • CLAUDE.md, README.md, CHANGELOG.md, marketplace.json version.

Two things to review deliberately

  1. PowerShell 7 as the single target. Every shipped script starts with #Requires -Version 7.0; PowerShell 7 becomes a machine prerequisite installed by the setup preflight next to git, gh and node, and scripts never branch on the version. The demo chain already mandates pwsh 7+ (setup-checks.md "Run everything from pwsh 7+"); the four existing dw-setup-install scripts are the only 5.1-compatible code and carry a curl.exe -k fallback plus an unguarded ConvertFrom-Json -AsHashtable that silently empties .mcp.json under 5.1. The next PR removes that dual target. Object here if 5.1 support matters for a case not covered by "the preflight installs 7".
  2. That recurring demo-build operations get scripted at all. The survey behind this found the same eight operations re-implemented across engagements (Admin API / MCP wrapper about 20 times, RunSql task runner 4 verbatim copies, guarded host restart 3 copies with one recorded sibling-host kill, index build, readiness verify, PII scan, stock-Swift debrand, mojibake census) while the repo holds them only as fenced prose. The convention here is the precondition for shipping those as one shared module plus seven scripts, one PR each.

Stacking

Based on feat/reland-authoring-hosted-foldback (#87) because dw-skill-authoring and dw-demo-foldback do not exist on main yet. Retarget to main after #87 merges.

Checks

  • python scripts/validate-skills.py: 0 errors (7 pre-existing length warnings, untouched).
  • node scripts/build-manifest.mjs --check: up to date.
  • Sanitization grep over the diff: clean.

Defines how runnable scripts ship inside skills before the first wave of
shared scripts lands: the file contract, PowerShell 7 as the single
target with #Requires -Version 7.0, connection discovery and secrets
rules, bundle closure for script imports, the fold-back gates for
lifting a script out of a demo build, and the smoke-test rule for write
scripts. Docs only; the validator checks and the migration of the four
existing dw-setup-install scripts follow in the next PR.
@Justinvolved
Justinvolved force-pushed the docs/scripts-packaging-convention branch from 2f475ca to 722a624 Compare August 28, 2026 14:13
@Justinvolved
Justinvolved deleted the branch feat/reland-authoring-hosted-foldback August 28, 2026 14:18
@Justinvolved

Copy link
Copy Markdown
Collaborator Author

Auto-closed when the base branch of #87 was deleted on merge. Continued as #90 against main, same commit rebased.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant