gspec 1.7.0 → 1.10.0

package/starters/practices/tdd-pipeline-first.md

@@ -0,0 +1,192 @@
+---
+gspec-version: 1.8.0
+description: TDD, pipeline-first CI/CD, DRY principles, and clean code standards
+---
+
+# Development Practices Guide
+
+## 1. Overview
+
+**Context**: This guide serves as the strict instruction set for AI agents and developers working on the project.
+**Goal**: Maintain a high-velocity, high-quality codebase through rigorous adherence to Test-Driven Development (TDD), DRY principles, and clean code standards.
+
+> **Precedence rule**: Where this document conflicts with technology-specific practices in `gspec/stack.md`, the stack's technology-specific practices take precedence for framework-specific concerns (e.g., file naming conventions dictated by a framework, framework-specific component patterns). This document governs general engineering principles.
+>
+> **Tooling authority**: This document defines testing *philosophy* (TDD, coverage targets, test organization). The specific testing *tools* (Vitest, Playwright, Cypress, etc.) are defined in `gspec/stack.md`. This document defines CI/CD pipeline *structure* (stages, gates, ordering). The specific CI/CD *platform* (GitHub Actions, GitLab CI, etc.) is defined in `gspec/stack.md`.
+
+## 2. Core Development Practices
+
+### Pipeline-First Development
+
+> [!IMPORTANT]
+> **The CI/CD pipeline MUST be established immediately after scaffolding the project, before any application-specific features are implemented.**
+> A working pipeline is the foundation that validates every subsequent change.
+
+#### Implementation Order
+
+After the initial project scaffold (framework setup, dependency installation, basic configuration), the following must be completed in order:
+
+1.  **Lint stage**: Configure the project's linter and formatter. Verify linting passes on the scaffolded codebase.
+2.  **Typecheck stage**: Ensure static type checking passes with strict mode enabled.
+3.  **Test stage**: Set up the unit test runner (as specified in `gspec/stack.md`) with a single trivial passing test (e.g., a smoke test that asserts `true`). Configure the E2E test runner (as specified in `gspec/stack.md`) with a minimal test that loads the index page. Both unit and E2E test commands must pass.
+4.  **Build stage**: Confirm the production build completes successfully.
+5.  **CI pipeline**: Configure the CI/CD platform (as specified in `gspec/stack.md`) with pipeline stages for lint, typecheck, test, build, and deploy. The pipeline must pass end-to-end on the scaffolded project before any feature work begins.
+
+#### Acceptance Criteria
+
+*   All pipeline stages are configured and green.
+*   The pipeline runs automatically on every push and merge request.
+*   Pre-commit hooks are installed and functional, running the linter and formatter on staged files.
+*   No feature branch may be started until the pipeline is verified on the default branch.
+
+#### Rationale
+
+*   **Catch regressions from the first commit**: Every change, no matter how small, is validated.
+*   **Avoid pipeline debt**: Retrofitting CI/CD after features are built leads to a batch of failures that are harder to triage.
+*   **Enforce quality gates early**: Developers and AI agents build the habit of writing code that passes all checks from day one.
+
+### Testing Standards (TDD)
+
+> [!IMPORTANT]
+> **Test-Driven Development (TDD) is MANDATORY.**
+> Strict adherence to the Red-Green-Refactor cycle is required for all logic changes.
+
+1.  **Red**: Write a failing test for the smallest possible unit of functionality.
+2.  **Green**: Write the minimum amount of code required to pass the test.
+3.  **Refactor**: Improve the code structure without changing behavior, ensuring tests remain green.
+
+*   **Scope**:
+    *   **Unit Tests**: Required for all utility functions, helpers, and complex components. Target 100% coverage for business logic.
+    *   **Integration Tests**: Required for API routes and critical user flows.
+    *   **End-to-End Tests**: Headless E2E tests are required for all critical pages to verify they load and render correctly. These tests ensure that routing, layout rendering, and key UI elements are functional from the user's perspective.
+*   **Location**: Dedicated `tests/` directory at the project root or module level, mirroring the source structure. DO NOT colocate tests with source files. E2E tests live in a separate directory (e.g., `e2e/`).
+*   **Naming**: `[filename].spec.*` exclusively. E2E tests use `[page-name].spec.*`.
+*   **E2E Configuration**:
+    *   **Headless by default**: All E2E tests MUST run in headless mode in CI and during standard test runs.
+    *   **Critical Page Coverage**: Every user-facing route must have at minimum a "page loads successfully" E2E test that asserts the page renders without errors and key elements are visible.
+    *   **No Flaky Tests**: E2E tests must be deterministic. Stub external API calls where needed to avoid flakiness.
+
+### Code Quality Standards
+
+#### DRY (Don't Repeat Yourself)
+*   **Rule**: Do not duplicate business logic or complex styling.
+*   **Action**: Extract reusable logic into shared functions, helpers, or modules.
+*   **Exceptions**: Minor duplication (3-4 lines) is acceptable if abstraction increases complexity significantly (WET - Write Everything Twice, but not thrice).
+
+#### Nesting & Complexity
+*   **Max Nesting Depth**: 3 levels.
+    *   *Violation*: `if (...) { for (...) { if (...) { ... } } }`
+    *   *Fix*: Extract the inner logic into a named private function or guard clause.
+*   **Function Length**: Keep functions under 30 lines where possible. Single Responsibility Principle (SRP) applies strictly.
+*   **Cognitive Load**: Use "Early Return" pattern to reduce indentation.
+
+### Code Organization
+
+#### Typing & Safety
+*   **Strict Typing**: If the project uses a statically typed language, enable the strictest available type checking mode. Avoid escape hatches (e.g., `any` in TypeScript, `Object` in Java) — use narrower types or generics instead.
+
+#### Naming Conventions
+*   **Variables/Properties**: `camelCase` (e.g., `userProfile`, `isValid`)
+*   **Functions**: `camelCase` (e.g., `calculateTotal`, `fetchUserData`)
+*   **Types/Interfaces/Classes**: `PascalCase` (e.g., `UserProfile`, `AuthResponse`)
+*   **Constants**: `UPPER_SNAKE_CASE` for global constants (e.g., `MAX_RETRY_COUNT`); `camelCase` for local constants.
+*   **Files**: `kebab-case` (e.g., `user-profile`) for general source files; `PascalCase` for component files where idiomatic for the framework.
+*   **Descriptive Naming**:
+    *   *Bad*: `val = getData(d)`
+    *   *Good*: `userProfile = fetchUserProfile(date)`
+    *   Boolean variables should ideally be prefixed with `is`, `has`, `should` (e.g., `isValid`, `hasAccess`).
+
+#### File Structure
+*   **Colocation**: Keep related files together (e.g., component, test, and styles if utilizing modules).
+*   **Barrels**: Use index/barrel files sparingly to export the public API of a module.
+
+## 3. Version Control & Collaboration
+
+### Git Practices
+*   **Commits**: Conventional Commits style (e.g., `feat: add login page`, `fix: resolve auth timeout`).
+*   **Branches**: `feat/feature-name`, `fix/issue-description`, `chore/maintenance`.
+
+### Code Review Standards
+
+To be defined.
+
+## 4. Documentation Requirements
+
+*   **Self-Documenting Code**: Prioritize clear naming over comments.
+*   **Comments**: Use comments *only* to explain "Why", not "What".
+    *   *Bad*: `// increment i by 1`
+    *   *Good*: `// Retry logic required due to potential API race condition`
+*   **API Documentation**: Use the language's standard doc comment format for public utility functions and complex interfaces to provide IDE hints.
+*   **Deployment Guide**: A `DEPLOYMENT.md` file MUST exist at the project root with step-by-step instructions covering:
+    *   **SaaS Product Configuration**: Account setup and configuration for every third-party service the project depends on. Include required environment variables, API keys, webhook URLs, and any dashboard settings that must be configured.
+    *   **Infrastructure Setup**: Instructions for provisioning hosting, databases, DNS, CDN, and any other infrastructure components.
+    *   **Environment Variables**: A complete list of all required environment variables with descriptions, expected formats, and where to obtain each value.
+    *   **Build & Deploy Steps**: Commands and procedures to build and deploy the application to production, including any CI/CD pipeline configuration.
+    *   **Post-Deploy Verification**: Checklist of smoke tests and health checks to confirm a successful deployment.
+    *   **Rollback Procedure**: Steps to revert to the previous version if a deployment fails.
+    *   Keep `DEPLOYMENT.md` updated whenever a new SaaS dependency is added or deployment steps change.
+
+## 5. Error Handling & Logging
+
+*   **Pattern**: Use error boundaries or equivalent mechanisms to catch and handle UI errors gracefully.
+*   **Backend**: Use structured error objects. Avoid throwing raw strings or untyped errors.
+*   **Logging**: Log significant state changes and errors. Do not leave debugging log statements in production code.
+
+## 6. Performance & Optimization
+
+*   **Rendering**: Memoize or cache expensive computations only when profiling shows a measurable benefit. Virtualize long lists to avoid rendering off-screen items.
+*   **Images**: Always use optimized image components or pipelines provided by the framework.
+
+### SEO & Discoverability
+
+> [!IMPORTANT]
+> **SEO is a core product requirement, not an afterthought.**
+> Every page should be optimized for search engines and social sharing.
+
+#### Metadata Standards
+*   Every page must export metadata including title, description, and Open Graph tags.
+*   **Title Format**: `[Page Name] - [Site Name]` (max 60 characters)
+*   **Description**: 120-160 characters, include primary keyword naturally
+*   **Open Graph**: Always include `title`, `description`, and `images` for social sharing
+
+#### Technical SEO
+*   **Semantic HTML**: Use proper heading hierarchy (`h1` → `h2` → `h3`). One `h1` per page.
+*   **Image Alt Text**: All images MUST have descriptive `alt` attributes.
+    *   *Bad*: `alt="image"`
+    *   *Good*: `alt="Professional reviewing code on laptop screen"`
+*   **Structured Data**: Add JSON-LD schema markup where applicable.
+*   **Sitemap**: Keep `sitemap.xml` updated via dynamic sitemap generation.
+*   **Robots.txt**: Configure properly to allow indexing of public pages, block admin/auth routes.
+
+#### Performance for SEO
+*   **Core Web Vitals**: Monitor and optimize for LCP, FID, CLS.
+    *   Use optimized image components with priority for above-fold images
+    *   Lazy load below-fold content
+*   **Mobile-First**: All pages must be responsive and mobile-friendly (Google mobile-first indexing).
+*   **Page Speed**: Target < 3s initial load on 3G connections.
+
+#### Content Guidelines
+*   **URLs**: Use descriptive, keyword-rich slugs
+    *   *Good*: `/services/web-development`
+    *   *Bad*: `/s/123`
+*   **Internal Linking**: Link related content naturally using descriptive anchor text.
+*   **Heading Structure**: Front-load important keywords in headings without keyword stuffing.
+
+## 7. Security Practices
+
+*   **Input Validation**: Validate all external inputs (API params, form data) using a schema validation library.
+*   **Authentication**: Never implement custom crypto. Use an established auth provider.
+*   **Authorization**: Verify user permissions on *every* server action/API route.
+
+## 8. Refactoring Guidelines
+
+*   **Boy Scout Rule**: Always leave the code cleaner than you found it.
+*   **Refactor Step**: In TDD, the refactor step is not optional. It is the moment to apply DRY and clean up nesting.
+
+## 9. Definition of Done
+
+1.  [ ] Tests written (red -> green).
+2.  [ ] Code follows style guide (linted & formatted).
+3.  [ ] No new Type errors.
+4.  [ ] Logic extracted and readable.
+

package/starters/stacks/astro-tailwind-github-pages.md

@@ -0,0 +1,283 @@
+---
+gspec-version: 1.8.0
+description: Static documentation site with Astro, Tailwind CSS v4, and GitHub Pages deployment
+---
+
+# Technology Stack Definition
+
+## 1. Overview
+
+A **static documentation and marketing site** deployed to GitHub Pages, built with Astro.
+
+### Architecture Style
+- Static site generated at build time with Astro. Zero server-side runtime, no API, no database.
+- Content-driven architecture — pages are authored in Markdown/MDX and rendered through Astro layouts.
+
+### Deployment Target
+- **GitHub Pages** — static hosting via GitHub Actions build-and-deploy workflow
+
+### Scale & Performance Requirements
+- Minimal — static HTML/CSS/JS served via GitHub Pages CDN. Target: perfect Lighthouse scores.
+
+---
+
+## 2. Open Questions & Clarifications
+
+None — all information is clear.
+
+---
+
+## 3. Core Technology Stack
+
+### Programming Languages
+
+- **Astro Components (.astro)** — Astro's template syntax, compiles to static HTML
+- **Markdown / MDX** — Content authoring format for documentation pages
+- **JavaScript (ES Modules)** — For any client-side interactivity and Astro configuration
+
+### Runtime Environment
+
+- **Node.js 20 LTS** — Used for Astro site generation. Pinned in CI via GitHub Actions `setup-node`.
+- **No container runtime** — Not needed for a static site.
+
+---
+
+## 4. Frontend Stack
+
+### Framework
+
+- **Astro 5.x** — Static site generator optimized for content-driven websites
+- **Why Astro:**
+  - Zero-JS-by-default output — ideal for a documentation/marketing site
+  - First-class Markdown/MDX support for content pages
+  - Built-in GitHub Pages deployment support
+  - Islands architecture allows interactive components only where needed
+  - Excellent performance out of the box (perfect Lighthouse scores)
+
+### Build Tools
+
+- **Astro's built-in Vite pipeline** — Astro uses Vite internally; no separate bundler configuration needed
+- **`@astrojs/tailwind`** — Official Astro integration for Tailwind CSS
+
+### State Management
+
+Not Applicable — static site with no client-side application state. Any interactivity (e.g., mobile nav toggle, copy-to-clipboard) uses vanilla JS or Astro's `<script>` tags.
+
+### Styling Technology
+
+- **Tailwind CSS v4** — Utility-first CSS framework
+- **Why Tailwind:**
+  - Astro's officially recommended CSS solution with first-class integration
+  - Zero runtime cost in static output — all CSS is purged and inlined at build time
+  - Rapid prototyping without writing custom CSS files
+  - Excellent responsive design utilities built in
+  - `@tailwindcss/typography` plugin for long-form Markdown content styling
+- **Design token mapping:** Visual design values defined in `gspec/style.md` (when created) map to Tailwind's `theme.extend` configuration in `tailwind.config.mjs`. Custom colors, fonts, and spacing scales are defined there as Tailwind theme tokens rather than as raw CSS variables.
+
+---
+
+## 5. Backend Stack
+
+Not Applicable — fully static site. Pre-rendered HTML served from GitHub Pages.
+
+---
+
+## 6. Infrastructure & DevOps
+
+### Cloud Provider
+
+- **GitHub** — The sole infrastructure provider:
+  - **GitHub Pages** — Static site hosting
+  - **GitHub Actions** — CI/CD pipeline
+
+### Container Orchestration
+
+Not Applicable.
+
+### CI/CD Pipeline
+
+- **Platform:** GitHub Actions
+  - *Rationale:* Native integration with GitHub Pages deployment. No external CI service needed — hosting and CI are in the same platform.
+- **Deployment trigger:** Push to main (website paths changed). Path filtering scopes the workflow so non-website changes don't trigger deploys.
+- **Deployment method:** `actions/deploy-pages` for GitHub Pages.
+- **Note:** Pipeline stages and structure (lint → typecheck → test → build → deploy) are defined in `gspec/practices.md`. This section defines the CI technology and deployment configuration.
+
+### Infrastructure as Code
+
+Not Applicable — GitHub Pages requires no IaC. Configuration lives in `astro.config.mjs` and the GitHub Actions workflow YAML.
+
+---
+
+## 7. Data & Storage
+
+### File Storage
+
+- **GitHub Pages CDN** — Serves all static assets (HTML, CSS, JS, images)
+
+### Data Warehouse / Analytics
+
+Not Applicable.
+
+---
+
+## 8. Authentication & Security
+
+Not Applicable — public static site with no user accounts, login, or protected resources.
+
+---
+
+## 9. Monitoring & Observability
+
+Not Applicable — static site with no runtime to monitor. GitHub Pages provides basic traffic analytics if needed.
+
+---
+
+## 10. Testing Infrastructure
+
+### Testing Frameworks
+
+- **Build verification:** `astro build` succeeds without errors (run in CI)
+- **Lighthouse CI** (optional) — Automated performance/accessibility audits in the deploy pipeline
+- **E2E testing:** Playwright or Cypress can be used for page-load and rendering verification if required by `gspec/practices.md`. Astro sites are static HTML — E2E tests verify that built pages load correctly and key elements are visible.
+- **Unit testing:** Vitest can be used for testing utility functions, content collection schemas, or build-time logic if required by `gspec/practices.md`.
+- **Note:** Whether and how extensively to test is defined by `gspec/practices.md`. This section defines the available tools for the Astro ecosystem.
+
+### Test Data Management
+
+Not Applicable — static content site with no database.
+
+### Performance Testing
+
+Not Applicable — static assets served from CDN.
+
+---
+
+## 11. Third-Party Integrations
+
+### External Services
+
+- **GitHub Pages** — Website hosting
+- **Formspree** — Client-side form submission service for contact forms and visitor inquiries. Accepts POST requests directly from the browser — no server-side endpoint or backend code required.
+  - *Rationale*: GitHub Pages is static-only with no server runtime. Formspree provides form handling without requiring a backend, keeping the architecture zero-server.
+  - Free tier supports up to 50 submissions per month.
+  - Submissions are forwarded to a configured email address.
+
+### API Clients
+
+Not Applicable.
+
+---
+
+## 12. Development Tools
+
+### Package Management
+
+- **Package manager:** npm
+  - *Rationale:* Simplest option for a static site with minimal dependencies. No need for pnpm's strict resolution or yarn's workspaces at this project scale.
+- Key dependencies:
+  - `astro` — Static site generator
+  - `@astrojs/tailwind` — Tailwind CSS integration
+  - `tailwindcss` — Utility-first CSS framework
+  - `@tailwindcss/typography` — Prose styling for Markdown content
+
+### Project Structure
+
+```
+src/
+├── pages/        # Astro file-based routing
+├── layouts/      # Page layouts (BaseLayout.astro, DocsLayout.astro)
+├── components/   # Reusable UI components
+└── content/      # Markdown/MDX content collections
+public/           # Static assets (images, favicon, etc.)
+astro.config.mjs
+tailwind.config.mjs
+package.json
+```
+
+### Code Quality Tools
+
+- **Prettier** — Consistent formatting across Astro, JS, and Markdown files (with `prettier-plugin-astro`)
+- No linter needed at current project scale
+
+### Local Development
+
+- `npm run dev` — Astro dev server with hot reload
+- No Docker, no database, no environment variables required
+
+---
+
+## 13. Migration & Compatibility
+
+### Legacy System Integration
+
+Not Applicable.
+
+### Upgrade Path
+
+- **Astro:** Follow major version upgrade guides. Astro has a strong commitment to smooth upgrades.
+- **Tailwind CSS:** v4 is current. Tailwind's upgrade tooling (`@tailwindcss/upgrade`) automates major version migrations.
+- **Node.js:** Track LTS releases. Currently Node 20, move to Node 22 LTS when ready.
+
+---
+
+## 14. Technology Decisions & Tradeoffs
+
+### Key Architectural Decisions
+
+| Decision | Rationale | Alternatives Considered |
+|----------|-----------|------------------------|
+| **Astro over Next.js/Docusaurus** | Zero-JS static output, first-class Markdown support, perfect for docs/marketing. No SSR or client-side routing needed. | Next.js (overkill, ships unnecessary JS), Docusaurus (opinionated, React dependency), Hugo (Go templating less flexible) |
+| **Tailwind over vanilla CSS** | Rapid styling, consistent design system, excellent Astro integration, zero runtime cost after build. | Vanilla CSS (slower to prototype), UnoCSS (smaller ecosystem), Open Props (less utility coverage) |
+| **Minimal dependency footprint** | Only install what the static site needs — no backend or toolchain bloat. | Monorepo with shared dependencies (unnecessary complexity for a static site) |
+
+### Risk Mitigation
+
+| Risk | Mitigation |
+|------|------------|
+| Astro breaking changes | Pin major version, test builds in CI, upgrade intentionally |
+| Tailwind v4 is relatively new | First-class Astro support, large community, easy fallback to v3 |
+| GitHub Pages limitations | Static site is tiny; unlikely to hit limits. Could move to Cloudflare Pages or Netlify if needed |
+
+---
+
+## 15. Technology-Specific Practices
+
+### Framework Conventions & Patterns
+
+- Use `.astro` components for all pages and layouts — avoid unnecessary framework islands (React, Vue, etc.) unless interactive behavior demands it
+- Use Astro's built-in `<Content />` component for rendering Markdown content
+- Use Astro's file-based routing in `src/pages/`
+- Use `src/layouts/` for page layouts (e.g., `BaseLayout.astro`, `DocsLayout.astro`)
+- Use `src/components/` for reusable UI components
+- Prefer Astro's scoped `<style>` blocks for component-specific styles that don't map well to Tailwind utilities
+- Use content collections (`src/content/`) for structured Markdown content with schema validation
+- Use `getStaticPaths()` for dynamic routes when generating pages from collections
+
+### Library Usage Patterns
+
+#### Tailwind CSS in Astro
+- Configure design tokens in `tailwind.config.mjs` under `theme.extend` — map from `gspec/style.md` definitions
+- Use `@apply` sparingly and only in Astro `<style>` blocks for repeated patterns — prefer utility classes in templates
+- Use Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`) rather than custom media queries
+- Use `@tailwindcss/typography` with the `prose` class for all long-form Markdown content
+
+### Language Idioms
+
+- **ES Modules** — Use `import`/`export` exclusively
+- **`node:` prefix for built-in modules** — e.g., `import { readFileSync } from 'node:fs'`
+
+### Client-Side Interactivity Patterns
+
+Features that require client-side JavaScript (e.g., theme switching, mobile navigation toggles) need special handling in Astro's zero-JS architecture:
+
+- **Inline `<script>` tags** — For critical scripts that must run before paint (e.g., applying a saved theme preference to prevent flash-of-wrong-theme), use an inline `<script is:inline>` in the `<head>` of the base layout. This runs synchronously before the page renders.
+- **Astro `<script>` tags** — For non-critical interactivity (e.g., hamburger menu toggle, copy-to-clipboard), use Astro's `<script>` tags in components. These are bundled and optimized by Astro.
+- **Framework islands** — Use `client:load`, `client:visible`, or `client:idle` only for complex interactive components that require a framework (React, Vue, etc.). Most interactivity on a static site can be handled with vanilla JS.
+
+### Stack-Specific Anti-Patterns
+
+- **Don't add React/Vue/Svelte islands** unless a component genuinely requires client-side interactivity — the site should ship zero JS by default
+- **Don't use `client:load`** without justification — prefer `client:visible` or `client:idle` if interactivity is truly needed
+- **Don't install a CSS-in-JS library** alongside Tailwind — pick one styling approach
+- **Don't over-engineer navigation or routing** — Astro's file-based routing handles everything a docs site needs
+- **Don't use deferred scripts for theme initialization** — theme preference must be applied in a blocking inline script to prevent flash-of-wrong-theme