Plans
Implementation Plan

Add a docs landing hub linking the Plans and Social galleries

completed
2026-06-07 agentics feature
Objective

Replace the bare root redirect with a polished landing hub that greets every visitor to the agentics GitHub Pages site and routes them in one click to the Plans gallery and the Social Media gallery — styled to match the existing light-theme Plans gallery, with every link relative so it works under the /agentics/ base path.

Implement Read and implement all steps in the plan at docs/plans/add-docs-landing-hub.html — Replace the docs root redirect with a landing hub for the Pages site
File add-docs-landing-hub.html
Path docs/plans/add-docs-landing-hub.html
Acceptance criteria 9 / 9 done

Context

Today docs/index.html is a nine-line <meta http-equiv="refresh"> document that bounces visitors straight to plans/index.html. That makes the Plans gallery the de-facto home page and leaves the Social Media gallery (docs/media/social/index.html) completely undiscoverable from the site root — there is no real landing page tying the site together.

The deploy-pages.yml workflow uploads the entire docs/ directory as the Pages artifact, so docs/index.html is served as the site root at /agentics/. Replacing the redirect with a hub therefore changes nothing about deployment — the same file is simply richer. Because the site lives under the /agentics/ project sub-path, every link must be relative (plans/index.html, not /plans/); a leading-slash href would resolve against the domain root and 404.

The Plans gallery uses a light theme with a specific token set (--bg #ffffff, --surface #f9fafb, --border #e5e7eb, --text #111827, --accent #2563eb, --radius 4px, plus a soft card --shadow), a header with a 3px accent top-rule, and a responsive .gallery-grid of hover-highlighted .gallery-card anchors. The hub reuses those exact tokens and patterns for visual continuity. The Social gallery is dark-themed but remains a perfectly valid link target.

The guides directory (docs/guides/) holds 62 raw .md files and no index.html; under Pages with .nojekyll, markdown is served as raw text and there is no directory listing, so a guides/ link would 404. Per the decision on this plan, Guides is deferred from the hub for now and tracked in Next Steps — the hub ships with exactly the two galleries that already have working entry points.

Files to Modify

agentics/
  • docs/index.html modified replace meta-refresh redirect with the landing hub
  • tests/pages/test-docs-hub.sh new objective smoke test for the hub (matches tests/pages/test-* convention)
  • tests/pages/test-root-redirect.sh modified delete or update — currently asserts the meta-refresh redirect this plan removes

Out of scope and intentionally untouched: .github/workflows/deploy-pages.yml, docs/.nojekyll, docs/plans/index.html, and docs/media/social/index.html. The E2E spec (tests/e2e/docs-hub.spec.ts) is deferred — no Playwright infrastructure exists in this repo.

Diagram

What changes at the site root
Before — Redirect
  • meta-refresh document
  • jumps to plans/
  • social gallery hidden
  • no real home page
After — Hub
  • landing page at /agentics/
  • Plans card → plans/index.html
  • Social card → media/social/
  • light theme, relative links
Deferred — Guides
  • 62 raw .md files
  • no index.html yet
  • would 404 on Pages
  • see Next Steps

Steps

1
done Replace the redirect with a self-contained hub skeleton carrying the Plans-gallery light-theme tokens.
The meta-refresh document has to go before anything can render at the root; seeding the same :root token block as docs/plans/index.html guarantees visual parity from the first byte and keeps the page fully self-contained (inline CSS, no CDN).
Verify
Open docs/index.html: there is no <meta http-equiv="refresh"> and no <link rel="canonical"> redirect; the file starts with <!DOCTYPE html>, <html lang="en">, includes <meta charset="UTF-8">, <meta name="viewport">, a <title>, and a <a class="skip-link" href="#main">Skip to content</a>; the :root block declares --bg:#ffffff, --accent: #2563eb, --radius:4px and the same --surface/--border/--text/--muted values as docs/plans/index.html.
2
done Build the header band — accent top-rule, an <h1>, and a one-line tagline.
Mirroring the Plans gallery's .gallery-header (the 3px --accent rule above the title) gives the hub a recognizable masthead that visually belongs to the same family as the pages it links to.
Verify
The rendered page shows a single <h1> with the blue 3px rule directly above it and a muted tagline beneath; the header markup matches the .gallery-header / ::before structure used in docs/plans/index.html.
3
done Add the two destination cards — Plans and Social Media — as relative-href anchors in a responsive grid.
The cards are the hub's entire reason to exist: one-click routing to each gallery. Using .gallery-grid + .gallery-card reuses the gallery's hover treatment, and relative hrefs (plans/index.html, media/social/index.html) are what keep navigation working under /agentics/.
Verify
Exactly two <a class="gallery-card"> elements exist; their href values are plans/index.html and media/social/index.html (no leading /, no protocol); each card shows a title (e.g. "Plans", "Social Media") and a descriptive subtitle that makes the destination unambiguous (e.g. "Browse implementation plans", "View social media cards and posts"). grep -n 'href="/' docs/index.html returns nothing.
4
done Wrap content in semantic landmarks, add a skip-link and footer, with responsive + reduced-motion behavior.
A skip-to-content link, a <main> landmark, a single <h1>, and a .gallery-footer complete the page chrome and keep it accessible and gallery-consistent; the grid must collapse cleanly on narrow screens like the gallery does at its 640px breakpoint.
Verify
A <a href="#main" class="skip-link"> appears before the <main> element; the cards live inside <main id="main">; a .gallery-footer renders at the bottom with the gallery's border-top styling; resizing the viewport below ~640px stacks the two cards into a single column with no horizontal scroll; at tablet widths (640px–1024px) the two-card grid is not awkwardly sparse.
5
done Serve docs/ locally and confirm both relative links resolve from the root, then confirm the deploy workflow is untouched.
GitHub Pages serves the site under /agentics/, so the only trustworthy check is loading the hub as the served root and actually clicking through to each gallery — and the task forbids changing the deploy pipeline.
Verify
Run cd docs && python3 -m http.server 8123, open http://localhost:8123/: the hub renders in the light theme, and clicking the Plans card loads "Plans Library" while the Social card loads "Media Library". Confirm .github/workflows/deploy-pages.yml exists and is unmodified (test -f).
6
done Write tests/pages/test-docs-hub.sh and update or delete tests/pages/test-root-redirect.sh.
The smoke test codifies the plan's acceptance criteria as automated assertions, and belongs in tests/pages/ with the test-* naming convention matching its siblings (test-pages-smoke.sh, test-workflow-config.sh). The existing test-root-redirect.sh asserts the meta-refresh redirect this plan removes, so it must be deleted or rewritten to assert the hub instead.
Verify
Run bash tests/pages/test-docs-hub.sh and confirm it exits 0. Confirm the test asserts: no http-equiv="refresh", href="plans/index.html" present, href="media/social/index.html" present, no absolute-root link (href="/"), and at least one CSS token (--accent:.*#2563eb). Confirm tests/pages/test-root-redirect.sh no longer asserts a meta-refresh redirect.

Tests

Tier 1 — Code-touching plan
Objective Root is a hub that links both galleries via relative hrefs

File: tests/pages/test-docs-hub.sh

Type: smoke test (bash, matches the existing tests/pages/test-* convention)

Asserts: docs/index.html contains no http-equiv="refresh"; contains href="plans/index.html" and href="media/social/index.html"; contains no absolute-root link (grep -q 'href="/' must fail); contains at least one CSS token (--accent:.*#2563eb); and .github/workflows/deploy-pages.yml exists and was not modified in the current commit (checked via test -f, not git diff). Directly proves the plan's stated objective.

Run: bash tests/pages/test-docs-hub.sh

E2E Click-through from the served root reaches each gallery

File: tests/e2e/docs-hub.spec.ts (Playwright)

Status: Deferred — the repo has no Playwright config, no tests/e2e/ directory, and no TypeScript tooling. This spec is aspirational; implement it when E2E infrastructure is set up. See Next Steps.

Targets: the served docs/ root and the two .gallery-card navigation links

Key cases: (1) loading / shows an <h1>, a skip-link, and exactly two cards; (2) clicking the Plans card lands on a page whose title is "Plans Library"; (3) clicking the Social card lands on a page whose title is "Media Library"; (4) the page exposes a single main landmark and one h1.

Acceptance Criteria

Verification

Serve the docs directory as the site root — cd docs && python3 -m http.server 8123 — and open http://localhost:8123/. Confirm the hub renders in the light theme with the accent top-rule header and two cards with descriptive subtitles, then click each card and confirm it loads the Plans Library and the Media Library respectively. Tab-focus the page and confirm the skip-link appears and targets #main. View source on the served root and confirm there is no <meta http-equiv="refresh"> and no href="/" absolute link. Run bash tests/pages/test-docs-hub.sh and confirm it exits 0. Confirm .github/workflows/deploy-pages.yml exists unchanged via test -f. Note: after merging to main, GitHub Pages CDN may serve the old redirect for several minutes — wait before declaring the live deploy verified.

Completion Checklist

Required

Completion Report

No items to report — all requirements met.

Next Steps

Build a Guides index and add a third "Guides" card to the hub

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

Generate docs/guides/index.html as a browsable index of the markdown guides in docs/guides/ (there are ~62 .md files). Match the light-theme design of docs/plans/index.html exactly: the same :root tokens (--bg #ffffff, --accent #2563eb, --radius 4px), a .gallery-header with a 3px accent top-rule, and a responsive list/grid of links. IMPORTANT: under GitHub Pages with docs/.nojekyll, .md files are served as raw text and there is no directory listing, so decide and state how each guide is linked — either link to the raw .md, or convert the guides to HTML first and link to the .html. Then add a third "Guides" card to docs/index.html linking to guides/index.html with a relative href. Do not change .github/workflows/deploy-pages.yml. Keep all links relative so they work under /agentics/.
Add a "back to home" link from each gallery into the hub

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

Add a small "← Home" link to the header of docs/plans/index.html and docs/media/social/index.html that points back to the docs landing hub at the site root. Use a relative href (../index.html from plans/, ../../index.html from media/social/) so it works under the /agentics/ GitHub Pages base path. Match each page's existing header styling and do not alter their galleries or the deploy workflow.
Set up Playwright E2E infrastructure and write docs-hub.spec.ts

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

Set up Playwright E2E test infrastructure for the agentics repo: install Playwright as a dev dependency, create a playwright.config.ts, and create tests/e2e/docs-hub.spec.ts with these cases: (1) loading the served docs/ root shows an h1, a skip-link, and exactly two .gallery-card elements; (2) clicking the Plans card navigates to a page titled "Plans Library"; (3) clicking the Social card navigates to a page titled "Media Library"; (4) the page has a single main landmark and one h1. The spec should start a local server on docs/ before tests run. Do not modify any existing files outside tests/.
Wish List
Extract a shared gallery stylesheet across all Pages Wish List

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

Extract the shared light-theme gallery CSS (the :root design tokens, .gallery-header, .gallery-grid, .gallery-card rules duplicated across docs/index.html and docs/plans/index.html) into a single docs/assets/gallery.css stylesheet, and have the Pages HTML link to it via a relative href instead of each inlining a full copy. Verify the stylesheet loads under the /agentics/ base path and keep docs/.nojekyll intact. Reconcile the dark-themed docs/media/social/index.html separately — either theme it through the shared sheet with a dark override, or leave it standalone. Note the tradeoff: plan/gallery files are intentionally self-contained today, so weigh the DRY win against losing single-file portability.
Unresolved Questions
  • What headline and tagline copy should the hub use? 
    Decide the final headline and tagline for the docs landing hub (docs/index.html). The draft uses "Agentics" as the H1 with a one-line tagline describing the Claude Code plugin marketplace and its Pages galleries. Recommend final copy — H1, tagline, and an optional one-sentence intro — that fits the project's voice, then update docs/index.html accordingly. Keep it concise and do not change any links or the deploy workflow.
Team Review (2026-06-07 18:12:13 UTC) — 7 reviewers

Executive Summary

The plan is sound with revisions. All seven reviewers agree the scope is appropriate and the architecture is correct for a single-file static HTML change. However, the team identified several actionable gaps: the smoke test path and naming violated project conventions (tests/pages/test-*), no step created the test files described in the Tests section, the E2E spec assumed Playwright infrastructure that does not exist, the existing test-root-redirect.sh would break silently, the hub page lacked a required skip-link, and card descriptions were too vague. All issues have been addressed in the inline edits applied alongside this review.

Architecture

Fit: Architecturally sound for scope — single static HTML file, no build pipeline, no external dependencies. Concerns: CSS duplication across hub and galleries will drift (low); no back-navigation from galleries to hub (low, deferred to Next Steps); smoke test git-diff assertion is brittle (low). All accepted for current scope.

Completeness

Assessment: Well-scoped and largely executable, but had meaningful gaps. Key gaps addressed: (1) No step created test files — added Step 6. (2) Step 1 verify lacked HTML boilerplate checks — added DOCTYPE, lang, charset, viewport, title, skip-link assertions. (3) Card descriptions unspecified — Step 3 verify now requires descriptive subtitles. (4) E2E spec listed as deliverable with no Playwright infra — deferred to Next Steps.

Testability

Coverage: Adequate for the narrow scope after fixes. Key gaps addressed: (1) Smoke test had no CSS-token assertion — added --accent:.*#2563eb check. (2) Git-diff assertion replaced with test -f check. (3) E2E spec marked deferred with explicit status note. (4) Smoke test Run: command corrected to bash tests/pages/test-docs-hub.sh.

Risk

Risk level: Low. Key risks: relative links break if galleries move (medium — accepted, smoke test covers); CDN propagation delay after deploy (low — documented in Verification); test-root-redirect.sh would have broken silently (low — now addressed in Step 6 and AC9).

Conventions

Fit: Good overall after corrections. Key issues addressed: (1) Smoke test moved from tests/docs-hub-smoke.sh to tests/pages/test-docs-hub.sh matching sibling naming convention (high). (2) E2E spec deferred since no Playwright config exists (medium). (3) test-root-redirect.sh breakage added to Files and acceptance criteria (low).

UX

User fit: Clear happy path with direct routing. Key concerns addressed: (1) Skip-link added to Step 4 requirements and AC8. (2) Card descriptions required to be meaningful and unambiguous. (3) Tablet-range viewport check (640px–1024px) added to Step 4 verify. Accepted as-is: Back-to-home link deferred to Next Steps (already tracked); headline/tagline copy deferred to Unresolved Questions (implementer must resolve before shipping).

Accessibility

A11y compliance: Largely WCAG 2.1 AA compliant after fixes. Key issues addressed: (1) Skip-link requirement added to built hub page (high). (2) E2E test key case updated to check for skip-link. Accepted as-is: Copy button touch targets below 44px (low — non-primary actions); completion checklist disabled checkboxes lack aria-disabled hint (medium — pre-existing template concern, not plan-specific).

Agreements

  • Skip-link required (Accessibility + UX + Completeness): All agree the built hub page must include a skip-to-content link.
  • Test path wrong (Conventions + Completeness + Testability): All agree smoke test belongs at tests/pages/test-docs-hub.sh.
  • E2E spec not deliverable (Conventions + Testability + Risk): All agree Playwright spec should be deferred, not listed as current-scope deliverable.
  • test-root-redirect.sh breaks (Conventions + Risk): Both flagged the existing test will fail after the redirect is removed.
  • Git-diff assertion brittle (Architecture + Testability + Risk): All agree git diff check should be replaced with a direct file-existence check.

Conflicts

No material conflicts. UX reviewer rated "back-to-home link" as high severity and recommended promoting it to a required step; Architecture and Risk reviewers rated it low. Resolution: kept as Next Steps since it modifies files outside this plan's scope (docs/plans/index.html and docs/media/social/index.html), but the Next Steps prompt is already written and ready to execute immediately after this plan ships.

Highest-Risk Issues

  1. Missing test-creation step (Completeness, high) — Fixed: added Step 6.
  2. Wrong test path/naming (Conventions, high) — Fixed: renamed throughout.
  3. test-root-redirect.sh breakage (Conventions, low) — Fixed: added to Files and AC9.
  4. No skip-link on hub (Accessibility, high) — Fixed: added to Step 4, AC8.
  5. E2E spec assumes missing infra (Conventions, medium) — Fixed: deferred with explicit status note.

Edits Applied

Target Action Change
Files section edit Renamed smoke test to tests/pages/test-docs-hub.sh; added tests/pages/test-root-redirect.sh as modified
Step 1 verify edit Added HTML boilerplate checks: DOCTYPE, lang, charset, viewport, title, skip-link
Step 3 verify edit Required descriptive card subtitles
Step 4 edit Added skip-link requirement, tablet-range viewport check (640px–1024px)
Step 5 verify edit Fixed port placeholder to 8123; replaced git-diff with test -f
Steps section insert after Step 5 Added Step 6: write smoke test and update/delete test-root-redirect.sh
Objective test edit Fixed path, naming convention, added CSS token assertion, replaced git-diff with test -f
E2E test edit Marked as deferred; added skip-link to key cases
Acceptance Criteria append Added AC8 (skip-link) and AC9 (test-root-redirect.sh updated)
Verification edit Fixed test path, added skip-link check, CDN propagation note, replaced git-diff
Next Steps insert Added Playwright E2E infrastructure setup prompt
Files note edit Added E2E spec deferral note to out-of-scope line