the-grid-cc 1.3.0 → 1.4.0

package/.grid/plans/blog-PLAN-SUMMARY.md

@@ -0,0 +1,518 @@
+# James Weatherhead Blog - Execution Plan Summary
+
+**Cluster:** james-weatherhead-blog
+**Total Blocks:** 6 blocks across 4 waves
+**Estimated Completion:** 4-6 hours (including checkpoints)
+**Target:** Production-ready blog deployable to Vercel
+
+---
+
+## Architecture Overview
+
+This plan uses **vertical slicing** and **parallel execution** to maximize efficiency:
+
+- **Wave 1:** Foundation (project initialization)
+- **Wave 2:** Parallel development (layouts + content - no file overlap)
+- **Wave 3:** Integration (pages + RSS - no file overlap)
+- **Wave 4:** Finalization (verification + documentation)
+
+### Dependency Graph
+
+```
+Wave 1:  [Block 01: Init]
+            ↓
+Wave 2:  [Block 02: Layouts] ← depends on 01
+         [Block 03: Content] ← depends on 01
+            ↓         ↓
+Wave 3:  [Block 04: Pages] ← depends on 02, 03
+         [Block 05: RSS] ← depends on 01, 03
+            ↓         ↓
+Wave 4:  [Block 06: Final] ← depends on 02, 04, 05
+```
+
+---
+
+## Wave Structure
+
+| Wave | Blocks | Can Run Parallel | Autonomous | Checkpoints |
+|------|--------|------------------|------------|-------------|
+| 1 | 01 | No (single block) | Yes | 0 |
+| 2 | 02, 03 | **Yes** (no file overlap) | No | 2 (one per block) |
+| 3 | 04, 05 | **Yes** (no file overlap) | No (04), Yes (05) | 1 (Block 04 only) |
+| 4 | 06 | No (single block) | No | 1 |
+
+**Total Checkpoints:** 4 (all human-verify type)
+
+---
+
+## Block Breakdown
+
+### Block 01: Project Initialization
+**Wave:** 1 | **Autonomous:** Yes | **Depends:** None
+
+**Objective:** Initialize Astro project with Tailwind CSS and Vercel adapter
+
+**Files Modified:**
+- package.json
+- astro.config.mjs
+- tsconfig.json
+- .gitignore
+- tailwind.config.mjs
+- vercel.json
+
+**Threads:**
+1. Initialize Astro project with dependencies (Tailwind, Vercel, RSS, Shiki)
+2. Configure Tailwind with dark mode (`darkMode: 'class'`)
+3. Add Vercel deployment configuration
+
+**Key Outputs:**
+- Working dev server at localhost:4321
+- Tailwind processes styles correctly
+- Build succeeds with Vercel adapter
+
+**Verification:**
+- `npm run dev` starts without errors
+- `npm run build` completes successfully
+- Tailwind config has `darkMode: 'class'`
+
+---
+
+### Block 02: Layout System
+**Wave:** 2 | **Autonomous:** No | **Depends:** 01
+
+**Objective:** Build layout system with base layout, header, footer, and dark mode toggle
+
+**Files Modified:**
+- src/layouts/BaseLayout.astro
+- src/components/Header.astro
+- src/components/Footer.astro
+- src/components/DarkModeToggle.astro
+- src/styles/global.css
+
+**Threads:**
+1. Create BaseLayout with dark mode persistence (localStorage)
+2. Build Header and Footer components
+3. Implement dark mode toggle (interactive button)
+4. **CHECKPOINT:** Human verification of layout and dark mode functionality
+
+**Key Outputs:**
+- Responsive layout with navigation (Home, Blog, About)
+- Working dark mode toggle with localStorage persistence
+- No FOUC (flash of unstyled content)
+
+**Verification:**
+- Dark mode toggle switches themes
+- Theme persists across refresh
+- Header/footer render correctly
+- Responsive on mobile/desktop
+
+**Checkpoint Details:**
+- User tests dark mode toggle
+- Verifies layout appearance
+- Checks responsive behavior
+
+---
+
+### Block 03: Content System
+**Wave:** 2 | **Autonomous:** No | **Depends:** 01
+
+**Objective:** Implement blog content structure using Astro Content Collections
+
+**Files Modified:**
+- src/content/config.ts
+- src/content/blog/sample-post.md
+- src/pages/blog/[...slug].astro
+- src/components/PostList.astro
+- src/components/Tag.astro
+
+**Threads:**
+1. Configure content collection schema (zod validation)
+2. Create dynamic blog post template with syntax highlighting
+3. Build PostList and Tag components
+4. **CHECKPOINT:** Human verification of content rendering
+
+**Key Outputs:**
+- Type-safe content collection for blog posts
+- Dynamic post routes (/blog/{slug})
+- Sample post with frontmatter, markdown, code blocks
+- Syntax highlighting functional
+
+**Verification:**
+- Sample post renders at /blog/sample-post
+- Frontmatter displays correctly (title, date, tags)
+- Code blocks have syntax highlighting
+- `npm run build` succeeds
+- `npx astro check` passes
+
+**Checkpoint Details:**
+- User visits sample post page
+- Verifies markdown rendering
+- Tests syntax highlighting in code blocks
+- Checks dark mode prose styling
+
+**Parallel Execution Note:** Block 02 and 03 run in parallel (Wave 2) because:
+- No file overlap (layouts vs content)
+- Both depend only on Block 01
+- Can be executed simultaneously by different agents
+
+---
+
+### Block 04: Static Pages
+**Wave:** 3 | **Autonomous:** No | **Depends:** 02, 03
+
+**Objective:** Create homepage, blog index, about page, and tag filtering
+
+**Files Modified:**
+- src/pages/index.astro
+- src/pages/blog/index.astro
+- src/pages/about.astro
+- src/pages/blog/tags/[tag].astro
+
+**Threads:**
+1. Build homepage (hero + recent posts) and blog index (all posts)
+2. Create About page with author bio
+3. Implement tag-based filtering (dynamic tag pages)
+4. **CHECKPOINT:** Human verification of page structure and navigation
+
+**Key Outputs:**
+- Homepage with recent posts (5 most recent)
+- Blog index with all posts sorted by date
+- About page with placeholder author content
+- Tag pages filtering posts by tag
+- Complete navigation structure
+
+**Verification:**
+- Homepage displays recent posts
+- Blog index lists all posts
+- About page renders
+- Tag filtering works (click tag → filtered posts)
+- All navigation links functional
+
+**Checkpoint Details:**
+- User tests all pages (/, /blog, /about)
+- Clicks navigation links
+- Tests tag filtering
+- Verifies responsive behavior
+
+---
+
+### Block 05: RSS Feed
+**Wave:** 3 | **Autonomous:** Yes | **Depends:** 01, 03
+
+**Objective:** Implement RSS feed generation with autodiscovery
+
+**Files Modified:**
+- src/pages/rss.xml.ts
+- src/utils/rss.ts
+- src/layouts/BaseLayout.astro (autodiscovery link)
+
+**Threads:**
+1. Create RSS feed endpoint using @astrojs/rss
+2. Create RSS utility functions (formatters, sorters)
+3. Add RSS autodiscovery link to BaseLayout
+
+**Key Outputs:**
+- Valid RSS 2.0 feed at /rss.xml
+- All published posts in feed
+- Autodiscovery link in site header
+
+**Verification:**
+- /rss.xml accessible and loads XML
+- Feed validates against RSS 2.0 spec
+- Contains all non-draft posts
+- Browser detects RSS feed (autodiscovery)
+
+**Parallel Execution Note:** Block 04 and 05 run in parallel (Wave 3) because:
+- No file overlap (pages vs rss.xml.ts)
+- Block 04 depends on 02+03, Block 05 depends on 01+03
+- Block 05 is fully autonomous (no checkpoints)
+
+---
+
+### Block 06: Production Finalization
+**Wave:** 4 | **Autonomous:** No | **Depends:** 02, 04, 05
+
+**Objective:** Final verification, documentation, and deployment readiness
+
+**Files Modified:**
+- .gitignore
+- README.md
+- vercel.json (verification)
+
+**Threads:**
+1. Comprehensive production build verification
+2. Create comprehensive README documentation
+3. Verify and document Vercel configuration
+4. **CHECKPOINT:** Human verification of production readiness
+
+**Key Outputs:**
+- Verified production build (all pages generate)
+- Complete README with setup/deployment instructions
+- Deployment-ready Vercel configuration
+- Clean .gitignore
+
+**Verification:**
+- `npm run build` succeeds
+- `npm run preview` serves all pages correctly
+- All pages load without errors
+- Dark mode works everywhere
+- Tag filtering functional
+- RSS feed validates
+- README accurate and complete
+
+**Checkpoint Details:**
+- User runs full build pipeline
+- Tests production preview
+- Reviews documentation
+- Confirms deployment readiness
+- Approves for Vercel deployment
+
+---
+
+## Must-Haves Summary
+
+### Global Truths (Entire Project)
+1. **Blog is deployable to Vercel** - All configuration present, build succeeds
+2. **Dark mode works globally** - Toggle persists, applies to all pages, no FOUC
+3. **Content is type-safe** - Content collections enforce schema, build validates
+4. **Navigation is complete** - All links work, no 404s, responsive
+5. **RSS feed is functional** - Valid feed, all posts included, autodiscoverable
+
+### Critical Artifacts
+| Artifact | Provides | Block |
+|----------|----------|-------|
+| astro.config.mjs | Framework configuration | 01 |
+| tailwind.config.mjs | Dark mode config | 01 |
+| BaseLayout.astro | Theme persistence | 02 |
+| DarkModeToggle.astro | Interactive toggle | 02 |
+| src/content/config.ts | Content schema | 03 |
+| [slug].astro | Post rendering | 03 |
+| index.astro | Homepage | 04 |
+| rss.xml.ts | RSS feed | 05 |
+| README.md | Documentation | 06 |
+
+### Critical Links
+| From | To | Via | Why Critical |
+|------|----|----|-------------|
+| BaseLayout | localStorage | theme script | Prevents FOUC, persists preference |
+| DarkModeToggle | document.documentElement | classList.toggle('dark') | Theme switching mechanism |
+| [slug].astro | getCollection('blog') | Astro API | Dynamic post routing |
+| rss.xml.ts | @astrojs/rss | rss() function | Feed generation |
+| [tag].astro | posts.filter | tag filtering | Tag-based navigation |
+
+---
+
+## File Ownership Matrix
+
+**Purpose:** Ensures parallel execution safety (no file conflicts)
+
+| File/Directory | Block 01 | Block 02 | Block 03 | Block 04 | Block 05 | Block 06 |
+|----------------|----------|----------|----------|----------|----------|----------|
+| package.json | ✓ | | | | | |
+| astro.config.mjs | ✓ | | | | | |
+| tailwind.config.mjs | ✓ | | | | | |
+| vercel.json | ✓ | | | | | ✓ (verify) |
+| src/layouts/ | | ✓ | | | | |
+| src/components/Header.astro | | ✓ | | | | |
+| src/components/Footer.astro | | ✓ | | | | |
+| src/components/DarkModeToggle.astro | | ✓ | | | | |
+| src/components/PostList.astro | | | ✓ | | | |
+| src/components/Tag.astro | | | ✓ | | | |
+| src/styles/global.css | | ✓ | | | | |
+| src/content/ | | | ✓ | | | |
+| src/pages/blog/[slug].astro | | | ✓ | | | |
+| src/pages/index.astro | | | | ✓ | | |
+| src/pages/blog/index.astro | | | | ✓ | | |
+| src/pages/about.astro | | | | ✓ | | |
+| src/pages/blog/tags/[tag].astro | | | | ✓ | | |
+| src/pages/rss.xml.ts | | | | | ✓ | |
+| src/utils/rss.ts | | | | | ✓ | |
+| .gitignore | ✓ | | | | | ✓ (update) |
+| README.md | | | | | | ✓ |
+
+**Wave 2 Safety:** Block 02 (layouts) and Block 03 (content) have zero file overlap ✓
+**Wave 3 Safety:** Block 04 (pages) and Block 05 (rss) have zero file overlap ✓
+
+---
+
+## Checkpoint Strategy
+
+**Total Checkpoints:** 4 (all `human-verify` type)
+**Placement:** End of Blocks 02, 03, 04, 06
+
+### Why These Checkpoints?
+
+1. **Block 02 Checkpoint (Layout):** Visual verification needed
+   - Dark mode toggle is interactive (requires manual testing)
+   - Layout appearance is subjective (user approval needed)
+   - Theme persistence must be tested with browser refresh
+
+2. **Block 03 Checkpoint (Content):** Rendering verification needed
+   - Syntax highlighting must be visually confirmed
+   - Markdown rendering quality subjective
+   - Prose typography on dark mode needs approval
+
+3. **Block 04 Checkpoint (Pages):** Integration verification needed
+   - Navigation structure requires end-to-end testing
+   - Tag filtering is interactive (requires manual testing)
+   - Overall UX needs user approval
+
+4. **Block 06 Checkpoint (Finalization):** Deployment gate
+   - Final production verification before deploy
+   - Documentation review
+   - User confirms readiness to ship
+
+### Why Block 05 Has No Checkpoint?
+- RSS feed generation is deterministic (XML output)
+- Feed validation can be automated (RSS validator)
+- No visual/interactive components requiring human judgment
+- Fully testable with automated checks
+
+---
+
+## Context Budget Analysis
+
+| Block | Threads | Complexity | Est. Context % | Risk |
+|-------|---------|------------|----------------|------|
+| 01 | 3 | Simple (config) | ~30% | Low |
+| 02 | 4 (3 + checkpoint) | Medium (interactive) | ~45% | Medium |
+| 03 | 4 (3 + checkpoint) | Medium (content API) | ~45% | Medium |
+| 04 | 4 (3 + checkpoint) | Medium (integration) | ~50% | Medium |
+| 05 | 3 | Simple (RSS API) | ~25% | Low |
+| 06 | 4 (3 + checkpoint) | Simple (verification) | ~35% | Low |
+
+**Assessment:** All blocks stay within ~50% context budget ✓
+
+**Rationale:**
+- Max 3 implementation threads per block (4th thread is checkpoint)
+- No block modifies >6 files
+- Each block has clear, focused objective
+- Vertical slices prevent cross-cutting concerns
+
+---
+
+## Risk Mitigation
+
+### Risk 1: Dark Mode Flash (FOUC)
+**Mitigation:** Inline script in BaseLayout `<head>` runs before body renders
+**Verification:** Block 02 checkpoint tests page reload
+
+### Risk 2: Content Schema Mismatch
+**Mitigation:** Zod schema in Block 03 validates at build time
+**Verification:** `npx astro check` in Block 03 thread verification
+
+### Risk 3: Build Failures
+**Mitigation:** Each block includes build verification in threads
+**Verification:** Block 06 runs full clean build pipeline
+
+### Risk 4: Vercel Deployment Issues
+**Mitigation:** Block 01 configures adapter early, Block 06 verifies
+**Verification:** Block 06 tests production preview locally
+
+### Risk 5: RSS Feed Invalid
+**Mitigation:** Use official @astrojs/rss (tested, maintained)
+**Verification:** Block 05 includes RSS validator check
+
+---
+
+## Execution Instructions
+
+### For Master Control Program:
+1. **Wave 1:** Execute Block 01 (autonomous, no checkpoint)
+2. **Wave 2:** Spawn 2 parallel executors for Block 02 and Block 03
+   - Both blocks have checkpoints (pause for user approval)
+3. **Wave 3:** After Wave 2 approval, spawn executors:
+   - Block 04 (has checkpoint)
+   - Block 05 (autonomous, runs parallel)
+4. **Wave 4:** After Wave 3 completion, execute Block 06 (final checkpoint)
+
+### For Human User:
+- **Expected Interactions:** 4 checkpoints (Blocks 02, 03, 04, 06)
+- **What to Test:** Visual appearance, dark mode, navigation, content rendering
+- **Approval Signal:** Type "approved" or describe issues
+- **Time Estimate:** 15-20 minutes of active testing across 4 checkpoints
+
+---
+
+## Success Criteria (End State)
+
+When all blocks complete and Block 06 checkpoint approved:
+
+✅ **Functional Requirements:**
+- [ ] Blog runs locally (`npm run dev`)
+- [ ] All pages accessible (/, /blog, /about, /blog/{slug}, /blog/tags/{tag}, /rss.xml)
+- [ ] Dark mode toggles and persists
+- [ ] Blog posts render with syntax highlighting
+- [ ] Tags filter posts correctly
+- [ ] RSS feed validates
+- [ ] Navigation links work
+
+✅ **Technical Requirements:**
+- [ ] Production build succeeds (`npm run build`)
+- [ ] Astro content validation passes (`npx astro check`)
+- [ ] Vercel adapter configured
+- [ ] No console errors
+- [ ] Responsive on mobile/desktop
+
+✅ **Documentation Requirements:**
+- [ ] README with setup instructions
+- [ ] README with deployment instructions
+- [ ] Project structure documented
+- [ ] Content management guide included
+
+✅ **Deployment Requirements:**
+- [ ] vercel.json configured
+- [ ] .gitignore excludes build artifacts
+- [ ] Site URL set in astro.config.mjs
+- [ ] No hardcoded localhost URLs
+- [ ] Ready to push to GitHub and deploy
+
+---
+
+## Next Steps After Planning
+
+1. **User Confirmation:** Review this plan, ask questions
+2. **Execution Trigger:** User runs `/grid:execute` or Master Control spawns executors
+3. **Wave-Based Execution:** Blocks execute in waves with parallel processing
+4. **Checkpoint Interactions:** User tests and approves at 4 checkpoints
+5. **Completion:** Block 06 approved → Blog ready for Vercel deployment
+
+---
+
+## Appendix: Technology Decisions
+
+### Why Astro?
+- **Requirement:** User specified Astro framework
+- **Benefits:** Content collections, island architecture, excellent DX for blogs
+
+### Why Tailwind CSS?
+- **Requirement:** User specified Tailwind
+- **Benefits:** Dark mode support, minimal bundle size, utility-first for rapid styling
+
+### Why Content Collections (not /pages/blog/*.md)?
+- **Superior to file-based routing:** Type-safe frontmatter, validation at build time
+- **Standard Astro pattern:** Official recommendation for content-heavy sites
+- **Scalability:** Handles hundreds of posts without performance issues
+
+### Why Shiki for Syntax Highlighting?
+- **Integration:** Official Astro integration (@astrojs/shiki)
+- **Quality:** VS Code's highlighter, accurate syntax
+- **Performance:** Compiles at build time (no client-side JS)
+
+### Why `darkMode: 'class'` (not media query)?
+- **Requirement:** User wants manual toggle, not auto-detection
+- **UX:** Gives users control over theme preference
+- **Persistence:** Works with localStorage for consistent experience
+
+### Why Vercel Serverless Adapter?
+- **Requirement:** User specified Vercel hosting
+- **Flexibility:** Supports SSR if needed later (though blog is static)
+- **Alternative:** Could use @astrojs/vercel/static for fully static (decide in Block 01)
+
+---
+
+**Plan Status:** ✅ Complete
+**Ready for Execution:** Yes
+**Estimated Duration:** 4-6 hours (including user checkpoint interactions)
+
+End of Line.