Getting Started Pages Repair Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Restore the public Getting Started page and address all ten confirmed onboarding defects with executable regression gates.
Architecture: Publish a regular Markdown file under /docs, retain a regular skill-packaged copy, and enforce byte parity plus structural/content/link contracts in a focused Node test. Verify through the same GitHub Pages Jekyll build surface that failed in production.
Tech Stack: Markdown, Node.js test runner, GitHub Pages/Jekyll, GitHub Actions, shell HTTP probes.
Task 1: Encode the failure contract
Files:
-
Create:
scripts/tests/getting-started-docs.test.mjs - Assert both guide paths are regular files rather than symbolic links.
- Assert the two copies are byte-identical.
- Assert all relative Markdown links from the Pages copy resolve inside
docs/. - Assert the guide contains exact contracts for prerequisites, credential sources, version checks, checksums, concrete verification, network security, and limitations.
- Run
node --test scripts/tests/getting-started-docs.test.mjsand capture the expected red failure against the symlink.
Task 2: Rewrite the canonical onboarding guide
Files:
- Replace:
docs/getting-started.md -
Modify:
skills/write-actions-json/references/getting-started.md - Replace the Pages symlink with a regular Markdown file.
- Reframe path selection around hosted-agent use versus map authoring.
- Add the prerequisites and security contracts.
- Correct OpenAI credential hydration instructions.
- Add extension download checksum verification and version inspection.
- Add bridge/runtime verification with expected outputs and ordered diagnostics.
- Move the bookmarklet note into a concise limitations section.
- Copy the reviewed guide byte-for-byte to the skill reference.
- Run the focused test and require all assertions to pass.
Task 3: Integrate the regression gate
Files:
- Modify:
package.json -
Modify:
scripts/validate-skills.mjs - Add
test:getting-started-docsto package scripts. - Make validation check the Pages copy as a regular file and enforce parity without widening unrelated canonical-skill discovery.
- Run the focused test and release-script test suite.
- Record the two unrelated release-script baseline failures without misattributing them to this change.
Task 4: Verify the publishing surface
Files:
-
Modify:
investigations/getting-started-pages-404.md - Run the GitHub Pages Jekyll build container against
./docs. - Assert
_site/getting-started.htmlexists and contains the expected title. - Serve
_sitelocally and require HTTP 200 from/getting-started.html. - Complete investigation phases 6–10 with experiment, blame, recurrence search, and remediation evidence.
Task 5: Review and deliver
Files:
-
Review all changed files.
- Run
git diff --check, focused tests, link checks, and Pages build once more. - Commit with the investigation reference.
- Push the branch and open a pull request with the ten-issue checklist and verification evidence.
- Merge after checks pass.
- Confirm the Pages workflow succeeds and the production Getting Started URL returns HTTP 200.