Plans

Publish HTML plans to GitHub Pages

High completed
2026-06-07 agentics feature High effort
Objective

Ship a GitHub Actions pipeline that publishes the entire docs/ tree to GitHub Pages, so every developer can browse all 32 HTML plans from one public URL — landing straight on the filterable plans gallery — instead of cloning the repo and opening files by hand.

Implement Read and implement all steps in the plan at docs/plans/publish-plans-to-github-pages.md — Publish HTML plans to GitHub Pages. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/publish-plans-to-github-pages.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Publish HTML plans to GitHub Pages. The plan at docs/plans/publish-plans-to-github-pages.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/publish-plans-to-github-pages.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/publish-plans-to-github-pages.md — Publish HTML plans to GitHub Pages. Brief subagents with the plan file at docs/plans/publish-plans-to-github-pages.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/publish-plans-to-github-pages.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File publish-plans-to-github-pages.html
Path docs/plans/publish-plans-to-github-pages.html
Spec docs/plans/publish-plans-to-github-pages.md
Definition of done 8 / 8 done

Context

The story behind this plan — what prompted the work and why it matters now.

The repo already generates rich, self-contained HTML plans into docs/plans/ (32 of them today), and a PostToolUse hook ( rebuild-plans-index.py ) keeps docs/plans/index.html — a filterable gallery — current after every plan write. The one missing piece is reach: those files only exist on disk, so a developer has to clone the repo and open them in a local browser to read them.

GitHub Pages closes that gap. The repo ( shawn-sandy/agentics ) already runs GitHub Actions, so the cleanest fit is a dedicated Pages deploy workflow using the official actions/upload-pages-artifact + actions/deploy-pages pair, publishing the whole docs/ directory on every push to main . Two known footguns shape the approach: GitHub Pages runs Jekyll by default (which can mangle hand-built HTML and ignores _ -prefixed paths) — neutralised with a .nojekyll marker; and a project Pages site is served under a base path ( /agentics/ ), so the landing page must use a relative redirect. The gallery's own links are already relative, so they survive the base path unchanged.

Per the decisions taken while drafting: deploy via a GitHub Actions workflow (not branch/folder), and make the existing plans gallery the site's landing page via a root redirect, keeping docs/plans/index.html as the single hook-maintained source of truth.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • .github/workflows/deploy-pages.yml new Actions workflow that deploys docs/ to Pages
  • docs/
    • .nojekyll new disable Jekyll processing of hand-built HTML
    • index.html new root redirect to the plans gallery
    • README.md modified add a link/badge to the published site

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
done Add the docs/.nojekyll marker file
Why
GitHub Pages runs the Jekyll static-site processor by default, which strips files and folders whose names start with an underscore and can rewrite hand-authored HTML. The plans are fully self-contained HTML — an empty .nojekyll file at the published root tells Pages to serve every byte verbatim.
Verify
test -f docs/.nojekyll && echo present prints present . The file is empty (zero bytes is fine).
2
done Create docs/index.html as a relative redirect to the plans gallery
Why
Publishing all of docs/ means the site root resolves to docs/index.html , which does not yet exist — visitors would hit a 404. A tiny redirect page forwards the root to plans/index.html so visitors land directly on the filterable gallery (the chosen landing page), while docs/plans/index.html stays the single hook-maintained source of truth. Use a relative target ( plans/index.html , not a leading slash) so it works under the /agentics/ Pages base path, plus a <meta http-equiv="refresh"> , a canonical <link> , and a visible fallback anchor for no-JS/no-refresh clients.
Verify
Open docs/index.html in a browser from a local server — it immediately navigates to the plans gallery. grep -q 'plans/index.html' docs/index.html succeeds, and the href does not start with / (no absolute path that would break the base-path).
3
done Add the .github/workflows/deploy-pages.yml deploy workflow
Why
This is the engine. The workflow triggers on push to main filtered to paths: ['docs/**', '.github/workflows/deploy-pages.yml'] (plus workflow_dispatch for manual re-runs), so changes to the workflow itself also trigger a redeploy. It declares the required permissions ( pages: write , id-token: write , contents: read ) and a concurrency group of pages with cancel-in-progress: false . A build job checks out, asserts docs/.nojekyll exists (fail fast if accidentally deleted), runs actions/configure-pages , and uploads docs via actions/upload-pages-artifact ; a deploy job with environment: github-pages runs actions/deploy-pages . Pin every action to a commit SHA with a version comment, matching the convention in auto-version-bump.yml . Look up current SHAs from each action's releases page or the existing pinned versions in auto-version-bump.yml .
Verify
The file parses as YAML (e.g. python3 -c "import yaml,sys; yaml.safe_load(open('.github/workflows/deploy-pages.yml'))" ). It declares both pages: write and id-token: write , a build and a deploy job, uploads artifact path docs , every uses: is pinned to a 40-char SHA, the path filter includes both docs/** and .github/workflows/deploy-pages.yml , and the build job asserts docs/.nojekyll exists before uploading the artifact.
4
done Enable GitHub Pages with source set to "GitHub Actions"
Why
A deploy workflow cannot publish until Pages is enabled on the repo with the build type set to workflow (Pages is currently disabled — the API returns 404). This is a one-time repo setting that must be completed before the PR is merged , since the workflow will fail on first trigger if Pages is not enabled. Enable it with gh api -X POST repos/shawn-sandy/agentics/pages -f build_type=workflow , or via Settings → Pages → "Build and deployment" → Source: GitHub Actions . Requires admin on the repo. If admin access is unavailable, coordinate with a repo admin to complete this step before merging.
Verify
gh api repos/shawn-sandy/agentics/pages --jq .build_type returns workflow (no longer 404), and the response html_url shows https://shawn-sandy.github.io/agentics/ .
5
done Add a "Browse the plans" link to README.md
Why
The published site is only useful if people can find it. Add a short link (or shields.io badge) near the top of README.md pointing at https://shawn-sandy.github.io/agentics/ so the gallery is discoverable from the repo's front door. Keep it one line — this is a pointer, not a section.
Verify
grep -q 'shawn-sandy.github.io/agentics' README.md succeeds, and the link renders correctly in the GitHub README preview.
6
done Create test files in tests/pages/
Why
The Tests section specifies three test scripts ( test-pages-smoke.sh , test-root-redirect.sh , test-workflow-config.sh ) but no earlier step creates them. Create mkdir -p tests/pages and write all three scripts with the assertions described in the Tests section. The unit and integration tests should be runnable locally as pre-merge validation; the smoke test runs post-deploy against the live URL with a retry loop (up to 5 attempts, 15s apart) to handle Pages propagation delay.
Verify
ls tests/pages/test-*.sh | wc -l returns 3 . Each script is executable ( chmod +x ) and exits 0 when run against the expected inputs (local files for unit/integration, live URL for smoke).
7
done Merge to main , then confirm the first deploy serves the live gallery
Why
The pipeline only proves itself end-to-end once it has actually run. After the change merges to main , the docs/** path filter fires the workflow; watch the run complete, then load the public URL and confirm the gallery and a sample plan render. This is the real acceptance gate — a green Actions run plus a reachable site.
Verify
gh run list --workflow=deploy-pages.yml --limit 1 shows a completed/success run. curl -sI https://shawn-sandy.github.io/agentics/ returns 200 , and curl -s https://shawn-sandy.github.io/agentics/plans/ contains the gallery title Plans Library . A sample plan such as .../plans/add-tests-section-to-plans.html also returns 200 .

Tests

The tests that prove the change does what it promises.

Tier 1 — Code-touching plan
Objective Published Pages site serves the plans gallery and every plan File: tests/pages/test-pages-smoke.sh Type: smoke test (run post-deploy, e.g. a final step of deploy-pages.yml or manually against the live URL) Asserts: the objective is actually met — GET https://shawn-sandy.github.io/agentics/ returns 200 and redirects to the gallery; /agentics/plans/ contains Plans Library ; and a loop over every docs/plans/*.html filename confirms each returns 200 at /agentics/plans/<name> (all plans browsable — count derived dynamically from find docs/plans -name '*.html' , not hardcoded). Includes a retry loop (up to 5 attempts, 15s apart) per URL to handle GitHub Pages propagation delay. Run: bash tests/pages/test-pages-smoke.sh https://shawn-sandy.github.io/agentics
Unit Root redirect points at the gallery with a base-path-safe relative href File: tests/pages/test-root-redirect.sh Targets: docs/index.html Key cases: file exists; contains a refresh/redirect to plans/index.html ; the redirect target is relative (does not begin with / or http ); a visible fallback anchor to the gallery is present for no-refresh clients.
Integration Deploy workflow is valid and correctly wired for Pages File: tests/pages/test-workflow-config.sh Targets: .github/workflows/deploy-pages.yml + docs/.nojekyll Key cases: YAML parses; triggers on push to main with paths: docs/** ; declares pages: write and id-token: write ; has a build job uploading artifact path docs and a deploy job using actions/deploy-pages with environment: github-pages ; all uses: pinned to SHAs; docs/.nojekyll exists so the artifact disables Jekyll.

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

End-to-end: after the change merges to main , confirm the deploy-pages.yml run completes successfully ( gh run list --workflow=deploy-pages.yml shows success ). Then load https://shawn-sandy.github.io/agentics/ in a browser — it should redirect to and display the plans gallery with all plan cards and working filter chips. Click into at least two plans (e.g. a normal plan and one ending in -review.html ) and confirm they render with full styling, working checkboxes, and the sidebar table of contents. Spot-check that deep links work directly (paste a .../plans/<name>.html URL fresh). Finally, run the smoke test ( bash tests/pages/test-pages-smoke.sh https://shawn-sandy.github.io/agentics ) and confirm it passes for the root, the gallery, and all plan files; and verify the README link resolves to the live site.

Troubleshooting: If the first deploy fails, check: (1) GitHub Pages is enabled with build_type=workflow (Step 4), (2) the workflow has correct permissions ( pages: write , id-token: write ), (3) the artifact path is docs , not ./docs . If the site returns 404 after a green deploy, wait 60–90 seconds for Pages propagation. If the smoke test times out, verify the URL base path ( /agentics/ ) matches the repo name.

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

Build a top-level docs hub linking plans, media, and guides

Paste this prompt into Claude to execute this follow-up:

Create a docs/index.html landing hub for the agentics GitHub Pages site that links to the three existing galleries/sections: the plans gallery (docs/plans/index.html), the social media gallery (docs/media/social/index.html), and the guides directory (docs/guides/). Match the visual style of docs/plans/index.html (same CSS tokens, light theme). Replace the current root redirect with this hub. Keep all links relative so they work under the /agentics/ Pages base path. Do not change the deploy workflow.
Render the markdown guides as HTML for the published site

Paste this prompt into Claude to execute this follow-up:

The docs/guides/ directory contains 62 markdown files that will not render as formatted pages on GitHub Pages without Jekyll (which we disabled via .nojekyll). Add a build step to .github/workflows/deploy-pages.yml that converts docs/guides/*.md to self-contained HTML (reuse the plan-interview markdown-to-html skill's approach or a small pandoc/markdown step) and generates a guides index, all before the upload-pages-artifact step, so the guides are browsable on the published site. Keep the conversion output out of git (generated only in CI).
Serve the site from a custom domain with full-text plan search

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Paste this prompt into Claude to execute this follow-up:

Explore upgrading the agentics GitHub Pages site into a polished plan-browsing portal: (1) configure a custom domain (CNAME) instead of the github.io base path, (2) add a client-side full-text search across all plan HTML (build a JSON index of plan titles, objectives, and statuses at deploy time and wire a search box into the gallery), and (3) add per-plan-type and per-status landing pages. Recommend an approach that keeps everything static (no server) and works within GitHub Pages constraints, and outline the tradeoffs of a custom domain vs the project base path for relative links.