Techcle Wiki

Review

3 min read

Review: Spec 0001 - Core Publishing Site

Date: 2026-01-19 Status: Complete Builder: Claude Opus 4.5

Summary

Implemented a Git-native, Markdown-based publishing site for The Long Run using Astro 5.x and prepared for Cloudflare Pages deployment. All acceptance criteria met.

Implementation Notes

What Worked Well

  1. Astro 5.x Content Collections - Type-safe content with Zod validation caught schema issues at build time. The getCollection filter for draft status is clean and explicit.

  2. Minimal Dependencies - Only Astro core + @astrojs/rss. No client-side JavaScript shipped to users. Build time is under 1 second.

  3. Automated Verification - The scripts/verify.mjs test suite covers all acceptance criteria and runs as part of CI/CD. 13 tests verify build output, draft filtering, SEO, and RSS.

  4. Editorial CSS - System fonts, readable line length, mobile responsive. No complex CSS framework needed.

Challenges and Solutions

ChallengeSolution
Spec shows content/ at root, but Astro requires src/content/Plan explicitly addresses this; documented that the spec describes editorial structure while implementation uses Astro’s required location
Astro CLI refused to init in non-empty directoryManually created project structure and package.json
Initial route used [...slug].astro (spread)Changed to [slug].astro after external review; essays have flat slugs

Trade-offs Made

  1. Content Location: Spec envisions content/ as separate editorial space; implementation uses src/content/ for Astro compatibility. This works but slightly couples content to build tool.

  2. No Separate Notes Schema: Spec mentions content/notes/ for future short posts but I only implemented essays for now per “Out of Scope” guidance.

  3. No Custom 404 Page: Using Cloudflare’s default 404. Could add later if needed.

External Review Summary

Gemini Review

  • Verdict: APPROVE
  • Summary: Spec is clear and well-defined, implementation plan maps directly to requirements

Claude Review

  • Verdict: COMMENT
  • Key Feedback:
    • Content directory mismatch noted (addressed in plan)
    • Suggested simpler [slug].astro route (implemented)
    • Asked about automated tests (already had 13)
    • RSS description already included
    • Empty state already handled

Test Coverage

TestStatus
Build output exists✓
Home page exists✓
Home page links to published essays✓
Published essay page exists✓
Draft essay NOT built✓
Draft content not in output✓
Canonical links correct✓
OpenGraph meta tags present✓
RSS feed exists✓
RSS contains published essays✓
RSS excludes drafts✓
About page exists✓
About page has content✓

Lessons Learned

  1. Read the plan, not just the spec - The plan already addressed the content directory mismatch that external review flagged.

  2. Automated tests pay off immediately - Writing verify.mjs took 10 minutes but caught issues instantly and gave confidence during refactoring.

  3. Simple route patterns are better - [slug].astro is clearer than [...slug].astro when you know paths are flat.

  4. Astro 5.x is production-ready - Content collections with Zod validation is excellent. Build times are fast.

Open Items for Future Specs

  • Cloudflare Pages configuration - Acceptance criteria 7 & 8 require deployment config (done separately)
  • Custom 404 page - Would improve brand consistency
  • Notes collection - Spec mentions this for future

Files Changed

astro.config.mjs          - Astro configuration
package.json              - Dependencies and scripts
tsconfig.json             - TypeScript configuration
src/content/config.ts     - Content collection schemas
src/content/essays/       - Essay content (1 draft, 1 published)
src/content/pages/        - Static pages (about)
src/layouts/Base.astro    - Base HTML layout
src/components/SEO.astro  - SEO meta tags component
src/pages/index.astro     - Home page
src/pages/about.astro     - About page
src/pages/essays/[slug].astro - Essay pages
src/pages/rss.xml.ts      - RSS feed
src/lib/content.ts        - Content helpers
src/styles/global.css     - Editorial CSS
scripts/verify.mjs        - Automated verification tests
public/favicon.png        - Placeholder favicon
README.md                 - Project documentation

Recommendation

APPROVE for merge. Implementation meets all code-level acceptance criteria. Cloudflare deployment configuration is a separate infrastructure task.

Graph View