the-grid-cc 1.2.0 → 1.3.0

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

@@ -0,0 +1,180 @@
+---
+cluster: james-weatherhead-blog
+block: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: [package.json, astro.config.mjs, tsconfig.json, .gitignore, tailwind.config.mjs, vercel.json]
+autonomous: true
+
+must_haves:
+  truths:
+    - "Project runs locally with npm run dev"
+    - "Tailwind CSS styles are processed correctly"
+    - "Vercel adapter is configured for deployment"
+  artifacts:
+    - path: "package.json"
+      provides: "Project dependencies and scripts"
+      min_lines: 20
+    - path: "astro.config.mjs"
+      provides: "Astro configuration with Vercel adapter and Tailwind"
+      exports: ["default"]
+    - path: "tailwind.config.mjs"
+      provides: "Tailwind configuration with dark mode"
+      exports: ["default"]
+  key_links:
+    - from: "astro.config.mjs"
+      to: "@astrojs/vercel/serverless"
+      via: "adapter import"
+      pattern: "import.*@astrojs/vercel"
+    - from: "astro.config.mjs"
+      to: "@astrojs/tailwind"
+      via: "integration"
+      pattern: "tailwind\\(\\)"
+---
+
+<objective>
+Initialize Astro project with Tailwind CSS and Vercel deployment configuration.
+
+Purpose: Establish the foundational project structure with all necessary dependencies and configuration for a modern, deployable blog.
+Output: Fully configured Astro project ready for local development and Vercel deployment.
+</objective>
+
+<context>
+This is a greenfield blog project for James Weatherhead. Requirements specify:
+- Astro framework (latest version)
+- Tailwind CSS for styling
+- Dark mode support
+- Vercel hosting
+- Minimal design aesthetic
+
+This block establishes the technical foundation. No prior work exists. Subsequent blocks will build the layout system, content structure, and features on top of this base.
+</context>
+
+<threads>
+
+<thread type="auto">
+  <name>Thread 1: Initialize Astro project with dependencies</name>
+  <files>package.json, astro.config.mjs, tsconfig.json, .gitignore</files>
+  <action>
+  Create new Astro project from scratch in /Users/jacweath/grid/blog directory:
+
+  1. Run: npm create astro@latest blog -- --template minimal --no-install --no-git --typescript strict
+  2. cd blog && npm install
+  3. Add Tailwind: npx astro add tailwind --yes
+  4. Add Vercel adapter: npx astro add vercel --yes
+  5. Add RSS integration: npm install @astrojs/rss
+  6. Add syntax highlighting: npm install @astrojs/shiki
+
+  Configure astro.config.mjs:
+  - Import vercel adapter
+  - Import tailwind integration
+  - Set site URL: https://jamesweatherhead.com (placeholder)
+  - Enable markdown code highlighting with shiki
+
+  Update package.json scripts:
+  - "dev": "astro dev"
+  - "build": "astro check && astro build"
+  - "preview": "astro preview"
+  - "astro": "astro"
+
+  AVOID: Do not use SSR features unless needed (keep it static for performance). Do not add unnecessary dependencies (keep bundle small per minimal design requirement).
+  </action>
+  <verify>
+  Run: cd /Users/jacweath/grid/blog && npm run dev
+  Check: Server starts on localhost:4321 without errors
+  Check: npm run build completes successfully
+  </verify>
+  <done>
+  - package.json exists with all required dependencies (astro, @astrojs/vercel, @astrojs/tailwind, @astrojs/rss, @astrojs/shiki)
+  - astro.config.mjs exports valid configuration with vercel adapter and tailwind integration
+  - npm run dev starts server without errors
+  - npm run build completes successfully
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 2: Configure Tailwind with dark mode</name>
+  <files>tailwind.config.mjs</files>
+  <action>
+  Configure Tailwind for dark mode and minimal design aesthetic:
+
+  1. Set darkMode: 'class' (allow manual toggle, not media query)
+  2. Extend theme with custom colors:
+     - Background colors: bg-gray-50 (light), bg-gray-900 (dark)
+     - Text colors: text-gray-900 (light), text-gray-100 (dark)
+     - Accent color: text-blue-600 (light), text-blue-400 (dark)
+  3. Configure content paths: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}']
+  4. Add typography plugin if needed for markdown styling: npm install -D @tailwindcss/typography
+
+  AVOID: Do not add excessive color variants (keep minimal). Do not use CSS-in-JS patterns (use Tailwind utilities). WHY: Requirements specify "minimal design" - extra variants add complexity and bundle size.
+  </action>
+  <verify>
+  Check: tailwind.config.mjs exports config with darkMode: 'class'
+  Check: Content paths include all Astro file types
+  Run: npm run build to ensure Tailwind processes correctly
+  </verify>
+  <done>
+  - tailwind.config.mjs has darkMode: 'class' configured
+  - Custom theme colors defined for dark/light modes
+  - @tailwindcss/typography plugin installed and configured
+  - Build completes with Tailwind processing styles
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 3: Add Vercel deployment configuration</name>
+  <files>vercel.json</files>
+  <action>
+  Create vercel.json for deployment configuration:
+
+  1. Create vercel.json in project root
+  2. Configure build settings:
+     {
+       "buildCommand": "npm run build",
+       "devCommand": "npm run dev",
+       "installCommand": "npm install",
+       "framework": "astro",
+       "outputDirectory": "dist"
+     }
+  3. Ensure .gitignore includes:
+     - node_modules/
+     - dist/
+     - .vercel/
+     - .astro/
+
+  AVOID: Do not add environment variables yet (none needed for static blog). Do not add redirects/rewrites yet (add when needed). WHY: Keep configuration minimal until features require it.
+  </action>
+  <verify>
+  Check: vercel.json exists with correct build configuration
+  Check: .gitignore includes all build artifacts
+  Run: npm run build && ls dist/ to verify output directory
+  </verify>
+  <done>
+  - vercel.json exists with framework set to "astro"
+  - Build command and output directory configured correctly
+  - .gitignore excludes all build artifacts and dependencies
+  - dist/ directory created successfully after build
+  </done>
+</thread>
+
+</threads>
+
+<verification>
+Run the following to verify block completion:
+1. cd /Users/jacweath/grid/blog
+2. npm run dev (server starts on port 4321)
+3. npm run build (completes without errors)
+4. ls dist/ (contains built files)
+5. Check astro.config.mjs imports vercel adapter and tailwind
+6. Check tailwind.config.mjs has darkMode: 'class'
+7. Check vercel.json exists with correct framework setting
+</verification>
+
+<success_criteria>
+- Project initializes and runs locally at localhost:4321
+- Tailwind CSS processes styles correctly
+- Build completes successfully with Vercel adapter
+- All configuration files present and valid
+- Ready for layout development in next block
+</success_criteria>

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

@@ -0,0 +1,229 @@
+---
+cluster: james-weatherhead-blog
+block: 02
+type: execute
+wave: 2
+depends_on: [01]
+files_modified: [src/layouts/BaseLayout.astro, src/components/Header.astro, src/components/Footer.astro, src/components/DarkModeToggle.astro, src/styles/global.css]
+autonomous: false
+
+must_haves:
+  truths:
+    - "Dark mode toggles between light and dark themes"
+    - "Navigation links are visible and functional"
+    - "Layout is responsive on mobile and desktop"
+  artifacts:
+    - path: "src/layouts/BaseLayout.astro"
+      provides: "Base HTML structure with dark mode support"
+      min_lines: 40
+    - path: "src/components/Header.astro"
+      provides: "Site navigation with logo/title and links"
+      min_lines: 20
+    - path: "src/components/DarkModeToggle.astro"
+      provides: "Interactive dark mode toggle button"
+      min_lines: 30
+  key_links:
+    - from: "DarkModeToggle.astro"
+      to: "document.documentElement"
+      via: "classList.toggle('dark')"
+      pattern: "classList\\.toggle\\('dark'\\)"
+    - from: "BaseLayout.astro"
+      to: "localStorage"
+      via: "theme persistence script"
+      pattern: "localStorage\\.getItem\\('theme'\\)"
+---
+
+<objective>
+Build the layout system with base layout, header, footer, and dark mode functionality.
+
+Purpose: Create reusable layout components that provide consistent structure, navigation, and theming across all pages.
+Output: Responsive layout with working dark mode toggle, navigation header, and footer.
+</objective>
+
+<context>
+Block 01 completed: Astro project initialized with Tailwind (darkMode: 'class') and Vercel adapter.
+
+This block builds the visual foundation. The layout system must:
+- Support dark mode toggle (class-based, not media query)
+- Be minimal and clean (per requirements)
+- Work on mobile and desktop
+- Include header with site title and nav links
+- Include footer with copyright/contact info
+
+No blog content yet - that comes in Block 03. This focuses purely on structure and theming.
+</context>
+
+<threads>
+
+<thread type="auto">
+  <name>Thread 1: Create base layout with dark mode persistence</name>
+  <files>src/layouts/BaseLayout.astro, src/styles/global.css</files>
+  <action>
+  Create BaseLayout.astro as the foundational layout component:
+
+  1. Create src/layouts/BaseLayout.astro with props interface:
+     - title: string
+     - description?: string
+     - ogImage?: string
+
+  2. Structure:
+     - HTML doctype and head with meta tags (viewport, charset, description)
+     - SEO meta tags (og:title, og:description, twitter:card)
+     - Link to global.css
+     - Inline script in head (before body renders) to prevent flash:
+       ```js
+       const theme = localStorage.getItem('theme') || 'dark'; // default dark per minimal aesthetic
+       if (theme === 'dark') document.documentElement.classList.add('dark');
+       ```
+     - Body with dark:bg-gray-900 bg-gray-50 dark:text-gray-100 text-gray-900
+     - Slot for page content
+
+  3. Create src/styles/global.css:
+     - @tailwind base/components/utilities
+     - Custom font stack: system-ui, -apple-system, sans-serif
+     - Smooth scroll behavior
+     - Focus styles for accessibility
+
+  AVOID: Do not use media query dark mode (requirements specify toggle, not auto). Do not add analytics scripts yet (keep minimal). WHY: User wants control over theme, not automatic switching based on system preference.
+  </action>
+  <verify>
+  Check: src/layouts/BaseLayout.astro exists with inline theme script
+  Check: localStorage persistence script runs before body render
+  Check: global.css imports Tailwind directives
+  Run: grep -r "localStorage.getItem" src/layouts/BaseLayout.astro
+  </verify>
+  <done>
+  - BaseLayout.astro exports layout with title, description props
+  - Inline script prevents FOUC (flash of unstyled content)
+  - Dark mode classes applied to html element
+  - global.css configures Tailwind and typography
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 2: Build Header and Footer components</name>
+  <files>src/components/Header.astro, src/components/Footer.astro</files>
+  <action>
+  Create navigation header and footer components:
+
+  Header.astro:
+  1. Create header element with container max-w-3xl mx-auto px-4 py-8
+  2. Site title "James Weatherhead" as h1 or logo
+  3. Navigation links: Home (/) | Blog (/blog) | About (/about)
+  4. Include DarkModeToggle component (will create in next thread)
+  5. Make responsive: stack on mobile, horizontal on desktop (md:flex)
+  6. Style links with hover:text-blue-600 dark:hover:text-blue-400
+
+  Footer.astro:
+  1. Create footer element with border-t border-gray-200 dark:border-gray-800
+  2. Container max-w-3xl mx-auto px-4 py-8
+  3. Copyright text: © 2024 James Weatherhead
+  4. Optional: Contact links or social media (GitHub, Twitter) if provided
+  5. Small text size: text-sm text-gray-600 dark:text-gray-400
+
+  AVOID: Do not add complex navigation menus (keep minimal - 3 links max). Do not add social media icons unless assets provided. WHY: Requirements specify "minimal design" - extra navigation adds visual clutter.
+  </action>
+  <verify>
+  Check: src/components/Header.astro exists with nav links
+  Check: src/components/Footer.astro exists with copyright
+  Check: Both use max-w-3xl for content width consistency
+  Run: grep -r "max-w-3xl" src/components/
+  </verify>
+  <done>
+  - Header.astro contains site title and 3 navigation links
+  - Footer.astro contains copyright and minimal info
+  - Both components use consistent container width (max-w-3xl)
+  - Responsive styles applied with Tailwind breakpoints
+  </done>
+</thread>
+
+<thread type="auto">
+  <name>Thread 3: Implement dark mode toggle component</name>
+  <files>src/components/DarkModeToggle.astro</files>
+  <action>
+  Create interactive dark mode toggle button:
+
+  1. Create DarkModeToggle.astro with client:load directive (needs JS)
+  2. Button element with aria-label="Toggle dark mode" for accessibility
+  3. Icon: Use Unicode characters (☀️ sun / 🌙 moon) or SVG for sun/moon icons
+  4. Client-side script:
+     ```js
+     const toggle = document.querySelector('#dark-mode-toggle');
+     toggle.addEventListener('click', () => {
+       const isDark = document.documentElement.classList.toggle('dark');
+       localStorage.setItem('theme', isDark ? 'dark' : 'light');
+     });
+     ```
+  5. Style: rounded-full p-2 hover:bg-gray-200 dark:hover:bg-gray-800 transition
+  6. Position in Header component (top-right corner)
+
+  AVOID: Do not use React or Vue (keep Astro-native for simplicity). Do not add animations beyond simple transition. WHY: Requirements don't specify framework components, and excessive animations conflict with minimal aesthetic.
+  </action>
+  <verify>
+  Check: DarkModeToggle.astro exists with client:load directive
+  Check: Toggle button has click handler that updates localStorage
+  Check: classList.toggle('dark') targets documentElement
+  Run: grep -r "client:load" src/components/DarkModeToggle.astro
+  </verify>
+  <done>
+  - DarkModeToggle.astro component created with interactive button
+  - Click handler toggles 'dark' class on html element
+  - Theme preference persists in localStorage
+  - Accessible with aria-label
+  </done>
+</thread>
+
+<thread type="checkpoint:human-verify" gate="blocking">
+  <what-built>
+  Complete layout system with:
+  - BaseLayout.astro (theme persistence, no FOUC)
+  - Header.astro (navigation: Home, Blog, About)
+  - Footer.astro (copyright, minimal info)
+  - DarkModeToggle.astro (interactive toggle with localStorage)
+  - global.css (Tailwind config, typography)
+  </what-built>
+  <how-to-verify>
+  1. cd /Users/jacweath/grid/blog && npm run dev
+  2. Create test page at src/pages/index.astro using BaseLayout
+  3. Visit http://localhost:4321
+  4. Check:
+     - Header appears with "James Weatherhead" title and nav links
+     - Footer appears with copyright
+     - Dark mode toggle button visible (sun/moon icon)
+  5. Click dark mode toggle:
+     - Background switches from light to dark (or vice versa)
+     - Text color changes appropriately
+     - Refresh page - theme persists
+  6. Test responsive:
+     - Resize browser to mobile width
+     - Header should stack vertically or remain readable
+  7. Check browser console for errors (should be none)
+  </how-to-verify>
+  <resume-signal>Type "approved" if layout and dark mode work correctly, or describe any issues (e.g., "toggle not working", "colors wrong")</resume-signal>
+</thread>
+
+</threads>
+
+<verification>
+Complete verification checklist:
+1. BaseLayout.astro exists with theme persistence script
+2. Header.astro has navigation links (/, /blog, /about)
+3. Footer.astro has copyright text
+4. DarkModeToggle.astro has client:load and click handler
+5. global.css imports Tailwind directives
+6. Dark mode toggle switches theme without page reload
+7. Theme persists across page refresh (localStorage)
+8. Layout is responsive on mobile and desktop
+9. No FOUC (flash of unstyled content) on page load
+10. Browser console has no errors
+</verification>
+
+<success_criteria>
+- Layout system renders correctly in browser
+- Dark mode toggle switches between light and dark themes
+- Theme preference persists in localStorage
+- Navigation links are visible and clickable
+- Responsive on mobile and desktop
+- No console errors
+- User approves visual appearance and functionality
+</success_criteria>

package/commands/grid/VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

package/commands/grid/mc.md

@@ -50,6 +50,67 @@ No boxes. No bloat. Just direct communication.
 
 ---
 
+## MODE SELECTION
+
+After User states what they want to build, ask ONE question:
+
+```
+      /\
+     /  \
+    / IO \
+   /______\
+       |
+   Mode selection...
+
+How involved do you want to be?
+
+  HANDS OFF - I make all technical decisions. You approve the final plan.
+  HANDS ON  - We discuss stack, features, architecture together.
+
+End of Line.
+```
+
+### HANDS OFF Mode
+
+User wants results, not questions. You:
+
+1. **Research first** - Spawn parallel research agents to find best practices:
+```python
+# Spawn 3 research agents in parallel
+Task(prompt="Research best tech stack for {project_type} in 2024-2025. Return top recommendation with reasoning.", ...)
+Task(prompt="Research best practices and common patterns for {project_type}. Return key patterns to implement.", ...)
+Task(prompt="Research deployment options for {project_type}. Return recommended approach.", ...)
+```
+
+2. **Make decisions** - Based on research, YOU choose the stack. Don't ask.
+
+3. **Present plan** - Show User ONE summary for approval:
+```
+PROPOSED BUILD
+══════════════
+
+Project: {name}
+Stack: {your choices based on research}
+Features: {sensible defaults}
+Timeline: {blocks/threads}
+
+Approve to begin? [y/n]
+```
+
+4. **Build** - On approval, spawn Planner → Executors → Recognizer
+
+### HANDS ON Mode
+
+User wants control. Use dream extraction questioning (but keep it minimal):
+- Max 2-3 questions total
+- Present options, not open-ended questions
+- Get to building fast
+
+**ANTI-PATTERN:** Never do checklist walking (Framework? Hosting? Features? Domain? etc.)
+Instead: "Here's what I recommend: X, Y, Z. Any changes?"
+
+---
+
 ## PROGRAM SPAWNING PROTOCOL
 
 ### Available Programs
@@ -198,11 +259,12 @@ When a Program hits a checkpoint, it returns structured data:
 When you need User input:
 
 ```
-    ╱╲
-   ╱  ╲
-  ╱ IO ╲
- ╱══════╲
-   ↑ Disc ascending...
+      /\
+     /  \
+    / IO \
+   /______\
+       |
+   Disc ascending...
 
 [Question]
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-grid-cc",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Agent orchestration for Claude Code. You talk to Master Control. Master Control handles the rest.",
   "main": "index.js",
   "bin": {