the-grid-cc 1.4.0 → 1.6.0

package/.grid/plans/blog-block-04.md

@@ -1,287 +0,0 @@
----
-cluster: james-weatherhead-blog
-block: 04
-type: execute
-wave: 3
-depends_on: [02, 03]
-files_modified: [src/pages/index.astro, src/pages/blog/index.astro, src/pages/about.astro, src/pages/blog/tags/[tag].astro]
-autonomous: false
-
-must_haves:
-  truths:
-    - "Homepage displays recent blog posts"
-    - "Blog index page lists all posts"
-    - "About page contains author information"
-    - "Tag pages filter posts by tag"
-  artifacts:
-    - path: "src/pages/index.astro"
-      provides: "Homepage with recent posts"
-      min_lines: 30
-    - path: "src/pages/blog/index.astro"
-      provides: "Complete blog post listing"
-      min_lines: 25
-    - path: "src/pages/about.astro"
-      provides: "About page with author info"
-      min_lines: 20
-    - path: "src/pages/blog/tags/[tag].astro"
-      provides: "Tag-filtered post listing"
-      min_lines: 40
-  key_links:
-    - from: "index.astro"
-      to: "getCollection('blog')"
-      via: "fetch recent posts"
-      pattern: "getCollection\\('blog'\\)"
-    - from: "[tag].astro"
-      to: "posts.filter"
-      via: "tag filtering"
-      pattern: "\\.filter.*tags\\.includes"
----
-
-<objective>
-Create static pages (homepage, blog index, about) and tag-based filtering functionality.
-
-Purpose: Connect layout system (Block 02) and content system (Block 03) into navigable pages with tag-based organization.
-Output: Complete page structure with homepage, blog listing, about page, and tag filtering.
-</objective>
-
-<context>
-Dependencies completed:
-- Block 02: Layout system (BaseLayout, Header, Footer, DarkModeToggle)
-- Block 03: Content system (blog collection, post template, PostList component)
-
-This block brings everything together into actual pages users will visit. Navigation links from Header (Home, Blog, About) now have destinations. Tag filtering enables content organization without complex search.
-
-This is where the blog becomes navigable and complete. After this block, users can:
-- Land on homepage and see recent posts
-- Browse all posts at /blog
-- Read about the author at /about
-- Filter posts by tag at /blog/tags/{tag}
-</context>
-
-<threads>
-
-<thread type="auto">
-  <name>Thread 1: Build homepage and blog index</name>
-  <files>src/pages/index.astro, src/pages/blog/index.astro</files>
-  <action>
-  Create homepage and blog listing pages:
-
-  index.astro (Homepage):
-  1. Import BaseLayout, PostList, getCollection
-  2. Fetch recent posts:
-     ```ts
-     const allPosts = await getCollection('blog', ({ data }) => !data.draft);
-     const recentPosts = allPosts
-       .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
-       .slice(0, 5); // Show 5 most recent
-     ```
-  3. Hero section:
-     - Site title: "James Weatherhead"
-     - Subtitle/tagline (e.g., "Software Engineer & Technical Writer")
-     - Brief intro paragraph (1-2 sentences)
-  4. Recent posts section:
-     - Heading: "Recent Posts"
-     - Use PostList component with recentPosts
-     - Link to /blog: "View all posts →"
-  5. Minimal design: max-w-3xl container, generous whitespace
-
-  blog/index.astro (Blog Index):
-  1. Import BaseLayout, PostList, getCollection
-  2. Fetch all posts (sorted by date descending)
-  3. Page title: "Blog"
-  4. Optional: display tag cloud (all unique tags)
-  5. Use PostList component with all posts
-  6. Style consistently with homepage
-
-  AVOID: Do not add complex hero animations (keep minimal). Do not add featured posts section yet (YAGNI). WHY: Requirements specify "minimal design" - focus on content, not embellishments.
-  </action>
-  <verify>
-  Run: npm run dev
-  Visit: http://localhost:4321 (homepage)
-  Check: Recent posts appear (up to 5)
-  Visit: http://localhost:4321/blog (blog index)
-  Check: All posts appear in list
-  Check: Both pages use BaseLayout with header/footer
-  </verify>
-  <done>
-  - index.astro displays hero section and 5 recent posts
-  - blog/index.astro lists all non-draft posts
-  - Both pages use consistent styling (max-w-3xl, Tailwind)
-  - "View all posts" link navigates to /blog
-  - Posts sorted by date descending
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 2: Create About page</name>
-  <files>src/pages/about.astro</files>
-  <action>
-  Create About page with author information:
-
-  1. Create src/pages/about.astro with BaseLayout
-  2. Page title: "About"
-  3. Content structure:
-     - Heading: "About James Weatherhead"
-     - Bio paragraphs (placeholder text for now - user will customize):
-       * Professional background
-       * Technical interests
-       * Why they write (blog purpose)
-     - Contact information (if provided)
-     - Optional: Links to GitHub, LinkedIn, Twitter (if provided)
-  4. Style with prose typography: prose dark:prose-invert max-w-3xl
-  5. Consistent container width with other pages
-
-  Placeholder content example:
-  "I'm a software engineer passionate about web development, DevOps, and technical writing. This blog is where I share insights, tutorials, and lessons learned from building software."
-
-  AVOID: Do not add contact form (YAGNI - add if requested). Do not add photo upload (user can add later). WHY: Keep initial version simple - user can customize content after deployment.
-  </action>
-  <verify>
-  Visit: http://localhost:4321/about
-  Check: Page renders with heading and bio content
-  Check: Consistent styling with other pages (max-w-3xl, prose)
-  Check: Dark mode works correctly on about page
-  Check: Header navigation links to /about works
-  </verify>
-  <done>
-  - about.astro created with BaseLayout
-  - Page contains heading and placeholder bio content
-  - Prose typography applied for readability
-  - Consistent container width (max-w-3xl)
-  - Navigation link from Header works
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 3: Implement tag-based filtering</name>
-  <files>src/pages/blog/tags/[tag].astro</files>
-  <action>
-  Create dynamic tag pages for filtering posts by tag:
-
-  1. Create src/pages/blog/tags/[tag].astro
-
-  2. Implement getStaticPaths to generate page for each unique tag:
-     ```ts
-     import { getCollection } from 'astro:content';
-     export async function getStaticPaths() {
-       const allPosts = await getCollection('blog', ({ data }) => !data.draft);
-       const uniqueTags = [...new Set(allPosts.flatMap(post => post.data.tags))];
-
-       return uniqueTags.map(tag => {
-         const filteredPosts = allPosts.filter(post =>
-           post.data.tags.includes(tag)
-         );
-         return {
-           params: { tag },
-           props: { posts: filteredPosts },
-         };
-       });
-     }
-     ```
-
-  3. Render tag page:
-     - Page title: "Posts tagged with '{tag}'"
-     - Display tag name prominently
-     - Show post count: "X posts"
-     - Use PostList component with filtered posts
-     - Breadcrumb: "Blog / Tags / {tag}"
-     - Link back to /blog
-
-  4. Update Tag component (from Block 03):
-     - When variant='link', link to /blog/tags/{tag}
-     - Ensure tags in PostList are clickable
-
-  AVOID: Do not add tag description field (YAGNI - tags are self-explanatory). Do not add "related tags" section (over-engineering). WHY: Keep tag pages simple - they're for filtering, not complex taxonomy.
-  </action>
-  <verify>
-  Run: npm run dev
-  Visit: http://localhost:4321/blog/tags/javascript (or any tag from sample post)
-  Check: Page shows only posts with that tag
-  Check: Post count displays correctly
-  Check: Tags in PostList are clickable and link to tag pages
-  Check: Breadcrumb or back link to /blog exists
-  Run: npm run build (should generate static page for each tag)
-  </verify>
-  <done>
-  - [tag].astro implements getStaticPaths with unique tags
-  - Filters posts by tag correctly
-  - Displays tag name and post count
-  - PostList shows filtered posts
-  - Tag component links to tag pages (variant='link')
-  - Build generates static page for each tag
-  </done>
-</thread>
-
-<thread type="checkpoint:human-verify" gate="blocking">
-  <what-built>
-  Complete page structure:
-  - Homepage (index.astro) with recent posts
-  - Blog index (blog/index.astro) with all posts
-  - About page (about.astro) with author info
-  - Tag pages (blog/tags/[tag].astro) with filtered posts
-  </what-built>
-  <how-to-verify>
-  1. cd /Users/jacweath/grid/blog && npm run dev
-
-  2. Test Homepage (http://localhost:4321):
-     - Hero section displays site title and intro
-     - Recent posts section shows up to 5 posts
-     - "View all posts" link navigates to /blog
-     - Header navigation visible (Home, Blog, About)
-
-  3. Test Blog Index (http://localhost:4321/blog):
-     - All blog posts listed
-     - Posts sorted newest first
-     - Tags visible and clickable
-
-  4. Test About Page (http://localhost:4321/about):
-     - Page renders with author info
-     - Consistent styling with other pages
-     - Navigation link from Header works
-
-  5. Test Tag Filtering:
-     - Click a tag from blog index or post page
-     - Should navigate to /blog/tags/{tag}
-     - Only posts with that tag appear
-     - Post count displays correctly
-
-  6. Test Navigation:
-     - Click each nav link (Home, Blog, About)
-     - All pages load without errors
-     - Dark mode toggle works on all pages
-
-  7. Run: npm run build
-     - Build completes successfully
-     - Check dist/ contains all static pages
-  </how-to-verify>
-  <resume-signal>Type "approved" if all pages work and navigation is functional, or describe issues (e.g., "tag filtering broken", "about page missing", "homepage posts not showing")</resume-signal>
-</thread>
-
-</threads>
-
-<verification>
-Complete verification checklist:
-1. Homepage renders with hero and recent posts (max 5)
-2. Blog index lists all non-draft posts sorted by date
-3. About page displays author information
-4. Tag pages filter posts correctly by tag
-5. Navigation links work (Home, Blog, About)
-6. Tags are clickable and link to tag pages
-7. Dark mode works consistently across all pages
-8. All pages use BaseLayout with header/footer
-9. Responsive on mobile and desktop
-10. npm run build generates all static pages
-11. No console errors on any page
-12. User approves page structure and navigation
-</verification>
-
-<success_criteria>
-- Homepage displays recent posts and hero content
-- Blog index shows complete post listing
-- About page contains author information
-- Tag filtering functional (click tag → see filtered posts)
-- All navigation links work correctly
-- Build generates all static pages
-- Consistent styling and dark mode across all pages
-- User approves overall page structure and UX
-</success_criteria>

package/.grid/plans/blog-block-05.md

@@ -1,235 +0,0 @@
----
-cluster: james-weatherhead-blog
-block: 05
-type: execute
-wave: 3
-depends_on: [01, 03]
-files_modified: [src/pages/rss.xml.ts, src/utils/rss.ts]
-autonomous: true
-
-must_haves:
-  truths:
-    - "RSS feed is accessible at /rss.xml"
-    - "Feed contains all published blog posts"
-    - "Feed validates against RSS 2.0 specification"
-  artifacts:
-    - path: "src/pages/rss.xml.ts"
-      provides: "RSS feed endpoint"
-      exports: ["GET"]
-    - path: "src/utils/rss.ts"
-      provides: "RSS generation utility functions"
-      min_lines: 20
-  key_links:
-    - from: "rss.xml.ts"
-      to: "@astrojs/rss"
-      via: "rss() function import"
-      pattern: "import.*@astrojs/rss"
-    - from: "rss.xml.ts"
-      to: "getCollection('blog')"
-      via: "fetch posts for feed"
-      pattern: "getCollection\\('blog'\\)"
----
-
-<objective>
-Implement RSS feed generation for blog posts using @astrojs/rss.
-
-Purpose: Provide RSS feed for readers who prefer feed readers (Feedly, NewsBlur, etc.).
-Output: Valid RSS 2.0 feed at /rss.xml with all published posts.
-</objective>
-
-<context>
-Dependencies:
-- Block 01: @astrojs/rss installed during project setup
-- Block 03: Blog content collection configured
-
-This block adds RSS feed support - a standard feature for technical blogs. Requirements explicitly mention "RSS feed" as a feature.
-
-RSS feeds are static XML files generated at build time. Astro's @astrojs/rss integration makes this straightforward - no complex logic needed.
-
-This block runs in parallel with Block 04 (wave 3) since there's no file overlap:
-- Block 04 modifies: pages (index, blog, about, tags)
-- Block 05 modifies: rss.xml.ts, utils/rss.ts
-</context>
-
-<threads>
-
-<thread type="auto">
-  <name>Thread 1: Create RSS feed endpoint</name>
-  <files>src/pages/rss.xml.ts</files>
-  <action>
-  Create RSS feed using @astrojs/rss integration:
-
-  1. Create src/pages/rss.xml.ts (note: .ts not .astro for API route)
-
-  2. Import dependencies:
-     ```ts
-     import rss from '@astrojs/rss';
-     import { getCollection } from 'astro:content';
-     import type { APIContext } from 'astro';
-     ```
-
-  3. Export GET function:
-     ```ts
-     export async function GET(context: APIContext) {
-       const posts = await getCollection('blog', ({ data }) => !data.draft);
-       const sortedPosts = posts.sort(
-         (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
-       );
-
-       return rss({
-         title: 'James Weatherhead Blog',
-         description: 'Technical writing on web development, DevOps, and software engineering',
-         site: context.site || 'https://jamesweatherhead.com',
-         items: sortedPosts.map(post => ({
-           title: post.data.title,
-           description: post.data.description,
-           pubDate: post.data.pubDate,
-           link: `/blog/${post.slug}/`,
-           categories: post.data.tags,
-         })),
-         customData: '<language>en-us</language>',
-       });
-     }
-     ```
-
-  4. Ensure astro.config.mjs has site URL set (required for RSS):
-     - If not set, use placeholder: https://jamesweatherhead.com
-
-  AVOID: Do not add full content to RSS (use description only for preview). Do not add custom XML transformations (use @astrojs/rss defaults). WHY: Full content RSS increases bandwidth and complexity; previews encourage click-through to site.
-  </action>
-  <verify>
-  Run: npm run build
-  Check: dist/rss.xml exists
-  Run: npm run preview
-  Visit: http://localhost:4321/rss.xml
-  Check: XML renders in browser with all posts
-  Validate: Use https://validator.w3.org/feed/ or RSS validator
-  </verify>
-  <done>
-  - rss.xml.ts exports GET function returning RSS feed
-  - Feed includes all non-draft posts sorted by date
-  - Each item has title, description, pubDate, link, categories (tags)
-  - site URL configured in astro.config.mjs
-  - RSS feed accessible at /rss.xml
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 2: Create RSS utility functions (optional helpers)</name>
-  <files>src/utils/rss.ts</files>
-  <action>
-  Create optional utility functions for RSS generation:
-
-  1. Create src/utils/rss.ts
-
-  2. Add helper functions:
-     ```ts
-     import type { CollectionEntry } from 'astro:content';
-
-     export function formatPostForRSS(post: CollectionEntry<'blog'>) {
-       return {
-         title: post.data.title,
-         description: post.data.description,
-         pubDate: post.data.pubDate,
-         link: `/blog/${post.slug}/`,
-         categories: post.data.tags,
-       };
-     }
-
-     export function sortPostsByDate(posts: CollectionEntry<'blog'>[]) {
-       return posts.sort(
-         (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
-       );
-     }
-     ```
-
-  3. Refactor rss.xml.ts to use these utilities (DRY principle)
-
-  Note: This thread is optional but recommended for cleaner code. If time-constrained, inline logic in rss.xml.ts is acceptable.
-
-  AVOID: Do not add XML parsing utilities (use @astrojs/rss). Do not add feed caching (Astro handles this). WHY: @astrojs/rss provides all RSS functionality; additional abstractions add unnecessary complexity.
-  </action>
-  <verify>
-  Check: src/utils/rss.ts exports helper functions
-  Check: rss.xml.ts imports and uses utilities
-  Run: npm run build (should succeed)
-  Check: dist/rss.xml unchanged (same output, cleaner code)
-  </verify>
-  <done>
-  - src/utils/rss.ts created with helper functions
-  - formatPostForRSS converts post to RSS item format
-  - sortPostsByDate sorts posts by date descending
-  - rss.xml.ts refactored to use utilities
-  - Build output identical (cleaner code, same result)
-  </done>
-</thread>
-
-<thread type="auto">
-  <name>Thread 3: Add RSS autodiscovery link</name>
-  <files>src/layouts/BaseLayout.astro</files>
-  <action>
-  Add RSS feed autodiscovery to site header:
-
-  1. Open src/layouts/BaseLayout.astro (created in Block 02)
-
-  2. In the <head> section, add autodiscovery link:
-     ```html
-     <link
-       rel="alternate"
-       type="application/rss+xml"
-       title="James Weatherhead Blog"
-       href="/rss.xml"
-     />
-     ```
-
-  3. This allows:
-     - Browsers to detect RSS feed (shows RSS icon in address bar)
-     - Feed readers to auto-discover feed
-     - Standard SEO best practice for blogs
-
-  4. Optional: Add visible RSS link in Footer component:
-     - Icon or text link: "RSS Feed"
-     - Links to /rss.xml
-
-  AVOID: Do not add Atom feed (RSS 2.0 sufficient). Do not add JSON Feed (RSS standard more widely supported). WHY: RSS 2.0 is universal standard; additional feed formats add maintenance overhead without significant benefit.
-  </action>
-  <verify>
-  Run: npm run dev
-  Visit: http://localhost:4321
-  Check: View page source - <link rel="alternate" type="application/rss+xml"> in <head>
-  Check: Browser RSS icon appears (if browser supports)
-  Check: Footer has RSS link (if added)
-  </verify>
-  <done>
-  - BaseLayout.astro has RSS autodiscovery link in <head>
-  - RSS feed detectable by browsers and feed readers
-  - Optional: Footer contains visible RSS link
-  - Feed properly advertised to users
-  </done>
-</thread>
-
-</threads>
-
-<verification>
-Complete verification checklist:
-1. src/pages/rss.xml.ts exports GET function
-2. RSS feed includes all non-draft posts
-3. Posts sorted by date descending (newest first)
-4. Each item has title, description, pubDate, link, categories
-5. Feed validates against RSS 2.0 spec (use validator)
-6. /rss.xml accessible after build
-7. BaseLayout.astro has autodiscovery link in <head>
-8. Optional: Footer has visible RSS link
-9. npm run build generates dist/rss.xml
-10. Feed loads in feed reader (test with Feedly or similar)
-</verification>
-
-<success_criteria>
-- RSS feed accessible at /rss.xml
-- Feed contains all published blog posts
-- Feed validates against RSS 2.0 specification
-- Autodiscovery link present in site <head>
-- Feed items have complete metadata (title, description, date, link, tags)
-- Build generates static RSS XML file
-- Feed works in standard feed readers
-</success_criteria>