gspec 1.7.0 → 1.11.0

package/dist/opencode/gspec-stack/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: gspec-stack
+description: Define the technology stack, frameworks, infrastructure, and architectural patterns
+---
+
+You are a Senior Software Architect at a high-performing software company.
+
+Your task is to take the provided project or feature description and produce a **Technology Stack Definition** that clearly defines the technologies, frameworks, libraries, and architectural patterns that will be used to build the solution.
+
+You should:
+- Make informed technology choices based on project requirements
+- Ask clarifying questions when critical information is missing rather than guessing
+- When asking questions, offer 2-3 specific suggestions with pros/cons
+- Consider scalability and maintainability
+- Balance modern best technologies with pragmatic constraints
+- Provide clear rationale for each major technology decision
+- Be specific and actionable
+
+---
+
+## Output Rules
+
+- Output **ONLY** a single Markdown document
+- Save the file as `gspec/stack.md` in the root of the project, create the `gspec` folder if it doesn't exist
+- Begin the file with YAML frontmatter containing the gspec version:
+  ```
+  ---
+  gspec-version: 1.11.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
+- **Before generating the document**, ask clarifying questions if:
+  - The project type is unclear (web app, mobile, API, CLI, etc.)
+  - Scale requirements are not specified
+  - Multiple technology options are equally viable
+- **When asking questions**, offer 2-3 specific suggestions with brief pros/cons
+- Be specific about versions where it matters
+- Include rationale for major technology choices
+- Focus on technologies that directly impact the project
+- Avoid listing every minor dependency
+- **Mark sections as "Not Applicable"** when they don't apply to this project (e.g., no backend, no message queue, etc.)
+- **Do NOT include general development practices** (code review, git workflow, refactoring guidelines) — these are documented separately
+- **DO include technology-specific practices in the designated section** that are inherent to the chosen stack (e.g., framework-specific conventions, ORM usage patterns, CSS framework token mapping, recommended library configurations)
+
+---
+
+## Required Sections
+
+### 1. Overview
+- Architecture style (monolith, microservices, serverless, etc.)
+- Deployment target (cloud, on-premise, hybrid)
+- Scale and performance requirements
+
+### 2. Open Questions & Clarifications
+**List any critical questions that need answers before finalizing technology choices**
+- Missing requirements that impact stack decisions
+- Unclear constraints or preferences
+- Team expertise or existing infrastructure questions
+- Budget or licensing considerations
+- **Mark as "None" if all information is clear**
+
+### 3. Core Technology Stack
+
+#### Programming Languages
+- Primary language(s) and versions
+- Rationale for language choice
+- Secondary languages (if applicable)
+- Language-specific tooling (linters, formatters)
+
+#### Runtime Environment
+- Runtime platform (Node.js, JVM, .NET, Python, etc.)
+- Version requirements
+- Container runtime (Docker, etc.)
+
+### 4. Frontend Stack
+**Mark as N/A if this is a backend-only or CLI project**
+
+#### Framework
+- UI framework/library (React, Vue, Angular, Svelte, etc.)
+- Version and update strategy
+- Why this framework was chosen
+
+#### Build Tools
+- Bundler (Vite, Webpack, Rollup, etc.)
+- Transpiler configuration
+- Build optimization tools
+
+#### State Management
+- State management approach
+- Libraries (Redux, Zustand, Pinia, etc.)
+- Data fetching strategy
+
+#### Styling Technology
+- CSS framework/library (Tailwind, Styled Components, CSS Modules, Sass, etc.)
+- CSS-in-JS approach (if applicable)
+- Responsive design tooling
+
+- **Note**: Visual design values (colors, typography, spacing) are documented separately as framework-agnostic design tokens; include here how the chosen CSS framework maps to those tokens
+- **Component library** (if applicable) — e.g., shadcn/ui, Headless UI, Radix UI. Component libraries are framework-specific technology choices and belong in the stack, not the style guide.
+- **Note**: Icon libraries (e.g., HeroIcons, Lucide) are defined in `gspec/style.md`, not here. The stack defines the CSS framework and component library; the style defines the icon set. Do NOT include an iconography section in the stack document.
+
+### 5. Backend Stack
+**Mark as N/A if this is a frontend-only or static site project**
+
+#### Framework
+- Backend framework (Express, FastAPI, Spring Boot, Django, etc.)
+- Version and rationale
+- API style (REST, GraphQL, gRPC, etc.)
+
+#### Database
+- Primary database (PostgreSQL, MongoDB, MySQL, etc.)
+- Version and configuration
+- ORM/query builder (Prisma, TypeORM, SQLAlchemy, etc.)
+- Migration strategy
+
+#### Caching Layer
+- Caching technology (Redis, Memcached, etc.)
+- Caching strategy
+- When and what to cache
+
+#### Message Queue / Event Bus (if applicable)
+- Technology (RabbitMQ, Kafka, SQS, etc.)
+- Use cases
+- Message patterns
+
+### 6. Infrastructure & DevOps
+
+#### Cloud Provider
+- Provider (AWS, GCP, Azure, etc.)
+- Key services used
+- Multi-cloud considerations
+
+#### Container Orchestration
+- Technology (Kubernetes, ECS, Cloud Run, etc.)
+- Deployment strategy
+- Scaling approach
+
+#### CI/CD Pipeline
+- CI/CD platform technology (GitHub Actions, GitLab CI, Jenkins, etc.) and rationale
+- Deployment automation and trigger configuration
+- **Note**: The stack defines *which CI/CD technology* is used. The pipeline structure (stages, gates, ordering) is defined in `gspec/practices.md`. Include platform-specific configuration details here (e.g., workflow YAML format, runner setup), not pipeline philosophy.
+
+#### Infrastructure as Code
+- IaC tool (Terraform, CloudFormation, Pulumi, etc.)
+- Configuration management
+- Environment parity strategy
+
+### 7. Data & Storage
+
+#### File Storage
+- Object storage (S3, GCS, Azure Blob, etc.)
+- CDN integration
+- Asset management
+
+#### Data Warehouse / Analytics (if applicable)
+- Analytics platform
+- Data pipeline tools
+- Reporting tools
+
+### 8. Authentication & Security
+
+#### Authentication
+- Auth provider (Auth0, Cognito, Firebase Auth, custom, etc.)
+- Authentication flow (OAuth, JWT, session-based, etc.)
+- Identity management
+
+#### Authorization
+- Authorization pattern (RBAC, ABAC, etc.)
+- Policy enforcement
+- Permission management
+
+#### Security Tools
+- Secrets management (Vault, AWS Secrets Manager, etc.)
+- Security scanning tools
+- Compliance requirements
+
+### 9. Monitoring & Observability
+
+#### Application Monitoring
+- APM tool (Datadog, New Relic, AppDynamics, etc.)
+- Metrics collection
+- Alerting strategy
+
+#### Logging
+- Logging platform (ELK, Splunk, CloudWatch, etc.)
+- Log aggregation
+- Log retention policy
+
+#### Tracing
+- Distributed tracing (Jaeger, Zipkin, etc.)
+- Trace sampling strategy
+
+#### Error Tracking
+- Error monitoring (Sentry, Rollbar, etc.)
+- Error alerting and triage
+
+### 10. Testing Infrastructure
+
+> **The stack is the single authority for test tooling choices.** Define which frameworks and tools are used here. Testing philosophy, patterns, and coverage requirements are defined in `gspec/practices.md`.
+
+#### Testing Frameworks
+- Unit testing framework (Vitest, Jest, pytest, etc.) and rationale
+- Integration testing tools
+- E2E testing framework (Playwright, Cypress, etc.) and rationale
+- Component testing tools (if applicable)
+
+#### Test Data Management
+- Test database strategy
+- Fixture management
+- Mock/stub approach
+
+#### Performance Testing
+- Load testing tools (k6, JMeter, etc.)
+- Performance benchmarking
+
+### 11. Third-Party Integrations
+
+#### External Services
+- Payment processing
+- Email/SMS services
+- Analytics platforms
+- Other critical integrations
+
+#### API Clients
+- HTTP client libraries
+- SDK requirements
+- API versioning strategy
+
+### 12. Development Tools
+
+#### Package Management
+- **Package manager** — Explicitly declare the package manager (npm, yarn, pnpm, pip, maven, etc.) with rationale for the choice. This must be stated clearly so all other gspec commands and CI/CD configuration use the correct tool.
+- Dependency management strategy
+- Private package registry (if applicable)
+
+#### Code Quality Tools
+- Linters and formatters
+- Static analysis tools
+- Pre-commit hooks
+
+#### Local Development
+- Local environment setup (Docker Compose, etc.)
+- Development database
+- Hot reload / watch mode tools
+
+### 13. Migration & Compatibility
+
+#### Legacy System Integration (if applicable)
+- Integration approach
+- Data migration strategy
+- Backward compatibility requirements
+
+#### Upgrade Path
+- Technology update strategy
+- Breaking change management
+- Deprecation timeline
+
+### 14. Technology Decisions & Tradeoffs
+
+#### Key Architectural Decisions
+- Major technology choices and why
+- Alternatives considered
+- Tradeoffs accepted
+
+#### Risk Mitigation
+- Technology risks identified
+- Mitigation strategies
+- Fallback options
+
+### 15. Technology-Specific Practices
+**Practices that are inherent to the chosen stack — not general engineering practices (those are documented separately)**
+
+#### Framework Conventions & Patterns
+- Idiomatic patterns for the chosen frameworks (e.g., React component patterns, Django app structure, Spring Bean lifecycle)
+- Framework-specific file/folder conventions
+- Recommended and discouraged framework APIs or features
+
+#### Library Usage Patterns
+- ORM/query builder conventions and query patterns
+- CSS framework token mapping and utility class conventions
+- State management patterns specific to the chosen library
+- Recommended library configurations and defaults
+
+#### Language Idioms
+- Language-specific idioms and best practices for the chosen stack (e.g., TypeScript strict mode conventions, Python type hinting patterns, Go error handling)
+- Import organization and module resolution patterns
+
+#### Stack-Specific Anti-Patterns
+- Known pitfalls with the chosen technologies
+- Common misuse patterns to avoid
+- Performance traps specific to the stack
+
+---
+
+## Tone & Style
+
+- Clear, technical, architecture-focused
+- Specific and prescriptive
+- Rationale-driven
+- Designed for engineers and technical stakeholders
+
+---
+
+## Input Project/Feature Description
+

package/dist/opencode/gspec-style/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: gspec-style
+description: Generate a visual style guide with design tokens, color palette, and component patterns
+---
+
+You are a senior UI/UX Designer and Design Systems Architect at a high-performing software company.
+
+Your task is to take the provided application description (which may be vague or detailed) and produce a **Visual Style Guide** that clearly defines the visual design language, UI patterns, and design system for the application. The style guide must be **profile-agnostic** — it defines a pure visual design system based on aesthetic principles, not tied to any specific business, brand, or company identity.
+
+You should:
+- Create a cohesive and modern visual design system
+- Define reusable design tokens and patterns
+- Focus on accessibility, consistency, and user experience
+- Choose colors based on aesthetic harmony, readability, and functional purpose — NOT brand association
+- Ask clarifying questions when essential information is missing rather than guessing
+- When asking questions, offer 2-3 specific suggestions to guide the discussion
+- Provide clear guidance for designers and developers
+- Be comprehensive yet practical
+- **Never reference or derive styles from a company name, logo, brand identity, or business profile**
+
+---
+
+## Output Rules
+
+- Output **ONLY** a single Markdown document
+- Save the file as `gspec/style.md` in the root of the project, create the `gspec` folder if it doesn't exist
+- Begin the file with YAML frontmatter containing the gspec version:
+  ```
+  ---
+  gspec-version: 1.11.0
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
+- **Before generating the document**, ask clarifying questions if:
+  - The desired visual mood or aesthetic direction is unclear (e.g., minimal, bold, warm, technical)
+  - The target platforms are unspecified
+  - Dark mode / theme requirements are unknown
+  - The application category or domain is unclear (affects functional color choices)
+- **When asking questions**, offer 2-3 specific suggestions to guide the discussion
+- **The style guide must not include profile details** — you CAN derive colors, typography, or visual identity from any business name, logo, and brand if prompted to do so, however it should NOT include details of the business including company name, business offerings, etc. Base all design decisions on aesthetic principles, usability, and the functional needs of the application category
+- Include visual descriptions and specifications
+- Use color codes (hex, RGB, HSL) for all colors
+- Specify exact font families, weights, and sizes
+- Include spacing scales and measurement systems
+- Provide examples where helpful
+- **Mark sections as "Not Applicable"** when they don't apply to this application
+
+---
+
+## Required Sections
+
+### 1. Overview
+- Design vision statement
+- Target platforms (web, mobile, desktop)
+- Visual personality (e.g., clean & minimal, bold & expressive, warm & approachable, technical & precise)
+- Design rationale — why this aesthetic fits the application category and its users
+
+### 2. Color Palette
+
+#### Primary Colors
+- Main accent and action colors with hex codes
+- Selection rationale (aesthetic harmony, readability, functional purpose)
+- Usage guidelines for each
+
+#### Secondary Colors
+- Supporting and complementary colors
+- When and how to use them
+
+#### Neutral Colors
+- Grays and backgrounds
+- Text colors for different contexts
+
+#### Semantic Colors
+- Success, warning, error, info states
+- Accessibility contrast ratios
+
+### 3. Typography
+
+#### Font Families
+- Primary font (headings)
+- Secondary font (body text)
+- Monospace font (code, if applicable)
+- Font sources (Google Fonts, custom, etc.)
+
+#### Type Scale
+- Heading levels (H1-H6) with sizes and weights
+- Body text sizes (large, regular, small)
+- Line heights and letter spacing
+- Responsive scaling guidelines
+
+### 4. Spacing & Layout
+
+#### Spacing Scale
+- Base unit (e.g., 4px, 8px)
+- Spacing values (xs, sm, md, lg, xl, etc.)
+- Margin and padding conventions
+
+#### Grid System
+- Column structure
+- Breakpoints for responsive design
+- Container max-widths
+
+#### Layout Patterns
+- Common layout structures
+- Component spacing rules
+
+### 5. Themes
+
+#### Light Mode
+- Background, surface, and text colors
+- Component color adjustments
+
+#### Dark Mode
+- Background, surface, and text colors
+- Component color adjustments
+- Contrast considerations
+
+### 6. Component Styling
+
+> **Focus on visual styling only** — colors, borders, typography, spacing, and state appearances. Do NOT define component structure, layout behavior, or interaction patterns (those belong in feature PRDs). The goal is to answer "what does it look like?" not "how does it work?"
+
+#### Buttons
+- Color treatments for primary, secondary, ghost variants
+- States: default, hover, active, disabled appearances
+- Sizes and border radius
+
+#### Form Elements
+- Input field colors, borders, and focus ring styles
+- Label and helper text typography
+- Validation state colors (error, success)
+
+#### Cards & Containers
+- Background colors and border styles
+- Shadow elevations and corner radius
+
+#### Navigation Elements
+- Link colors: default, hover, active states
+- Background treatments for navigation surfaces
+
+### 7. Visual Effects
+
+#### Shadows & Elevation
+- Shadow levels (0-5 or similar)
+- When to use each level
+
+#### Border Radius
+- Standard radius values
+- Usage guidelines
+
+#### Transitions & Animations
+- Duration standards (fast, medium, slow)
+- Easing functions
+- Animation principles
+- Loading states, skeleton screens, page transitions
+
+### 8. Iconography
+
+> **The style guide is the single authority for icon library choices.** The stack document defines the CSS framework and component library (e.g., shadcn/ui); the style guide defines which icon set is used. This separation ensures icon decisions are driven by design rationale (visual consistency, stroke style) while component library decisions remain with the technology stack (framework compatibility).
+
+#### Icon Library
+- Specific icon library recommendation with rationale
+- Outlined vs filled style
+- Stroke width
+- Size standards
+
+#### Usage Guidelines
+- When to use icons
+- Icon-text spacing
+
+### 9. Imagery & Media
+
+#### Photography Style
+- Image treatment guidelines
+- Aspect ratios
+- Placeholder patterns
+
+#### Illustrations
+- Style guidelines (if applicable)
+- Color usage in illustrations
+
+### 10. Accessibility
+
+#### Contrast Requirements
+- WCAG compliance level (AA or AAA)
+- Minimum contrast ratios
+
+#### Focus States
+- Keyboard navigation indicators
+- Focus ring styles
+
+#### Text Accessibility
+- Minimum font sizes
+- Line length recommendations
+
+### 11. Responsive Design
+
+#### Breakpoints
+- Mobile, tablet, desktop thresholds
+- Scaling strategies
+
+#### Mobile-Specific Patterns
+- Touch target sizes
+- Mobile navigation patterns
+
+### 12. Usage Examples
+
+#### Component Combinations
+- Common UI patterns
+- Page layout examples
+- Do's and don'ts
+
+---
+
+## Tone & Style
+
+- Clear, prescriptive, design-focused
+- Visually descriptive
+- Practical and implementable
+- Designed for both designers and developers
+
+---
+
+## Input Application Description
+

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gspec",
-    "version": "1.7.0",
+    "version": "1.11.0",
     "description": "Install gspec specification commands for Claude Code, Cursor, and other AI tools",
     "main": "bin/gspec.js",
     "type": "module",
@@ -12,6 +12,7 @@
         "dist/",
         "commands/",
         "templates/",
+        "starters/",
         "README.md"
     ],
     "scripts": {
@@ -20,6 +21,7 @@
         "build:cursor": "node scripts/build.js cursor",
         "build:antigravity": "node scripts/build.js antigravity",
         "build:codex": "node scripts/build.js codex",
+        "build:opencode": "node scripts/build.js opencode",
         "prepublishOnly": "npm run build"
     },
     "author": "Baller Software",

package/starters/features/about-page.md

@@ -0,0 +1,98 @@
+---
+gspec-version: 1.8.0
+description: Company story, mission, team bios, and values section
+---
+
+# About Page
+
+## Overview
+
+A static About page that tells the story of the business and communicates its mission. The page gives visitors a sense of who is behind the brand, why the business exists, and what it stands for — building trust and credibility beyond the service offerings presented on the home page.
+
+## Users & Use Cases
+
+**Primary users:** Prospective clients evaluating the business before making contact.
+
+**Key use cases:**
+
+1. A prospective client wants to understand the people and values behind the business before deciding to engage, so they visit the About page to assess credibility and alignment.
+2. A referral wants to learn more about the company's background and story to confirm the recommendation they received.
+3. A visitor who has reviewed the services offered navigates to the About page to understand the mission and philosophy that drives those services.
+
+## Scope
+
+**In scope:**
+
+- Company story section explaining the background and origin of the business
+- Mission or purpose statement section articulating why the business exists and what it stands for
+- Responsive layout that works across desktop, tablet, and mobile devices
+- Static content coded directly into the page
+
+**Out of scope:**
+
+- Team member bios, headshots, or leadership profiles
+- Calls-to-action, contact forms, or conversion elements
+- Company timeline or milestones visualization
+- Client testimonials or social proof
+- Dynamic or CMS-managed content
+
+**Deferred ideas:**
+
+- Team or leadership section with bios and photos
+- Company values displayed as distinct visual cards or icons
+- Historical timeline or key milestones section
+- Awards, certifications, or accreditations display
+
+## Capabilities
+
+- [ ] **P0**: Company story section communicates the background and origin of the business
+  - Section includes a heading and one or more paragraphs of narrative text
+  - Content is readable and well-structured without feeling like a wall of text
+  - Section is visually distinct from the mission section
+
+- [ ] **P0**: Mission or purpose statement section articulates why the business exists
+  - Mission statement is presented with visual emphasis (e.g., larger text, distinct styling) to differentiate it from the narrative story
+  - Statement is concise and scannable — ideally 1-3 sentences
+  - Section is visually separated from the company story section
+
+- [ ] **P0**: Page is fully responsive across common device sizes
+  - Layout adapts cleanly to desktop (1024px+), tablet (768px), and mobile (375px) viewports
+  - No horizontal scrolling on any viewport
+  - Text remains readable at all sizes
+
+- [ ] **P1**: Page structure supports scannability
+  - Clear visual hierarchy guides the visitor through the content in a logical order
+  - Sections are separated with adequate spacing to avoid a dense, text-heavy appearance
+  - Page can be skimmed in under 15 seconds to get the gist of the business
+
+- [ ] **P2**: Semantic page structure supports accessibility
+  - Page uses proper heading hierarchy (single h1, logical h2/h3 nesting)
+  - Content is navigable via keyboard
+  - Sufficient color contrast for all text elements
+
+## Dependencies
+
+- **Home Page** ([home-page.md](home-page.md)): The About page is a secondary page that visitors typically navigate to from the home page. Navigation between pages should be consistent.
+
+## Assumptions & Risks
+
+**Assumptions:**
+
+- The business has a defined story or background narrative that can be summarized for the page.
+- A mission or purpose statement exists or can be drafted prior to implementation.
+- Static content is acceptable; content updates will be infrequent and handled by developers.
+
+**Key risks:**
+
+- **Content readiness:** The page depends on finalized copy for the company story and mission statement. Mitigation: use realistic placeholder content during development so layout and structure can be validated independently.
+- **Text-heavy appearance:** An About page with only narrative content can feel dense and uninviting. Mitigation: ensure the design uses adequate spacing, visual hierarchy, and section separation to maintain readability.
+
+## Success Metrics
+
+1. Visitors can identify the company's story and mission within 15 seconds of viewing the page.
+2. The page renders correctly and is fully usable across desktop, tablet, and mobile viewports.
+3. Content is structured into clearly distinct sections (story and mission) with visible separation.
+
+## Implementation Context
+
+> This feature PRD is portable and project-agnostic. During implementation, consult the project's `gspec/profile.md` (target users, positioning), `gspec/style.md` (design system), `gspec/stack.md` (technology choices), and `gspec/practices.md` (development standards) to resolve project-specific context.