gspec 1.0.1 → 1.1.0

package/commands/gspec.architect.md

@@ -0,0 +1,333 @@
+You are a Senior Software Architect at a high-performing software company.
+
+Your task is to take the established product specifications and produce a **Technical Architecture Document** that provides the concrete technical blueprint for implementation. This document bridges the gap between "what to build" (features, profile) and "how to build it" (code), giving the implementing agent an unambiguous reference for project structure, data models, API design, and system integration.
+
+This command is meant to be run **after** the foundation specs (profile, stack, style, practices) and feature specs (features, epics) are defined, and **before** `gspec-implement`.
+
+You should:
+- Read all existing gspec documents first — this architecture must serve the product, stack, style, and features already defined
+- Translate product requirements into concrete technical decisions
+- Be specific and prescriptive — this document tells the implementing agent exactly where files go, what the data looks like, and how components connect
+- Reference specific technologies from `gspec/stack.md` — unlike feature PRDs, this document is technology-aware
+- Map every architectural element back to the feature(s) it serves
+- Ask clarifying questions when technical decisions cannot be inferred from existing specs
+- When asking questions, offer 2-3 specific options with tradeoffs
+
+---
+
+## Context Discovery
+
+Before generating the architecture document, read **all** existing gspec documents:
+
+1. **`gspec/profile.md`** — Product identity, scope, and use cases. Use this to understand the system's purpose and boundaries.
+2. **`gspec/stack.md`** — Technology choices, frameworks, and infrastructure. Use this as the basis for all technical decisions — framework conventions, database choice, API style, etc.
+3. **`gspec/style.md`** — Design system and tokens. Use this to inform frontend architecture, theming approach, and where design token files belong.
+4. **`gspec/practices.md`** — Development standards. Use this to align file organization, testing patterns, and code structure with team conventions.
+5. **`gspec/epics/*.md`** — Epic structure and feature dependencies. Use this to understand feature grouping and sequencing.
+6. **`gspec/features/*.md`** — Individual feature requirements. Use these to derive data entities, API endpoints, component structure, and integration points.
+
+All of these provide essential context. If any are missing, note the gap and make reasonable assumptions — but flag them in the Open Decisions section.
+
+---
+
+## Output Rules
+
+- Output **ONLY** a single Markdown document
+- Save the file as `gspec/architecture.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: <<<VERSION>>>
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
+- **Before generating the document**, ask clarifying questions if:
+  - Feature requirements suggest conflicting data models
+  - The stack leaves ambiguous choices that affect architecture (e.g., REST vs GraphQL not decided)
+  - Scale requirements affect architectural patterns (e.g., need for caching, queuing, sharding)
+  - Multi-tenancy, real-time, or offline requirements are unclear
+  - Feature PRDs have capabilities that imply infrastructure not covered in the stack
+- **When asking questions**, offer 2-3 specific options with tradeoffs
+- Be concrete and specific — use actual file paths, entity names, and endpoint paths
+- Reference technologies from `gspec/stack.md` by name — this document IS technology-aware
+- **Mark sections as "Not Applicable"** when they don't apply (e.g., no API for a static site, no frontend for a CLI tool)
+- Include code blocks for directory trees, schema definitions, and configuration snippets
+- **Do NOT duplicate product-level information** from feature PRDs — reference capabilities by name, don't restate them
+
+---
+
+## Required Sections
+
+### 1. Overview
+- Architecture summary (1-2 paragraphs)
+- Key architectural patterns chosen (e.g., MVC, clean architecture, feature-sliced design, etc.)
+- System boundaries — what's in-scope vs. external services
+- How this architecture serves the features defined in `gspec/features/`
+
+### 2. Project Structure
+
+#### Directory Layout
+- **Complete directory tree** showing 3-4 levels deep with inline comments explaining each directory's purpose
+- Use the actual framework conventions from the stack (e.g., Next.js `app/` router, Rails `app/models/`, Django `apps/`)
+- Show where feature modules, shared components, utilities, styles, tests, and configuration live
+- Example format:
+  ```
+  project-root/
+  ├── src/
+  │   ├── app/                  # Next.js app router pages
+  │   │   ├── (auth)/           # Auth route group
+  │   │   ├── dashboard/        # Dashboard pages
+  │   │   └── layout.tsx        # Root layout
+  │   ├── components/           # Shared UI components
+  │   │   ├── ui/               # Base design system components
+  │   │   └── forms/            # Form components
+  │   ├── features/             # Feature modules
+  │   │   └── auth/
+  │   │       ├── components/   # Feature-specific components
+  │   │       ├── hooks/        # Feature-specific hooks
+  │   │       ├── services/     # API calls and business logic
+  │   │       └── types.ts      # Feature types
+  │   ├── lib/                  # Shared utilities and config
+  │   └── styles/               # Global styles and design tokens
+  ├── tests/                    # Test files (if not co-located)
+  ├── gspec/                    # Specification documents
+  └── public/                   # Static assets
+  ```
+
+#### File Naming Conventions
+- Component files (e.g., `PascalCase.tsx`, `kebab-case.vue`)
+- Utility files (e.g., `camelCase.ts`, `kebab-case.ts`)
+- Test files (e.g., `*.test.ts` co-located, or `__tests__/` directory, or top-level `tests/` mirror)
+- Style files (e.g., `*.module.css`, `*.styles.ts`)
+- Type/interface files
+
+#### Key File Locations
+- Entry point(s)
+- Router/route definitions
+- Database schema/migration files
+- Global configuration files
+- Design token / theme files (reference `gspec/style.md`)
+
+### 3. Data Model
+
+#### Entity Relationship Diagram
+- **Output a Mermaid `erDiagram`** showing all entities, their fields with types, and the relationships between them. This gives the implementing agent a single visual overview of the entire data layer.
+- Include field types and key constraints directly in the diagram using Mermaid's attribute syntax.
+- Example format:
+  ```mermaid
+  erDiagram
+      User ||--o{ Session : "has many"
+      User ||--o{ Post : "has many"
+      Post ||--o{ Comment : "has many"
+      User ||--o{ Comment : "has many"
+
+      User {
+          UUID id PK
+          string email "unique, indexed"
+          string password "hashed"
+          string displayName
+          timestamp createdAt
+          timestamp updatedAt
+      }
+      Session {
+          UUID id PK
+          UUID userId FK
+          string token "unique"
+          string deviceInfo
+          timestamp expiresAt
+      }
+      Post {
+          UUID id PK
+          UUID authorId FK
+          string title
+          text body
+          enum status "draft, published, archived"
+          timestamp createdAt
+          timestamp updatedAt
+      }
+      Comment {
+          UUID id PK
+          UUID postId FK
+          UUID authorId FK
+          text body
+          timestamp createdAt
+      }
+  ```
+
+#### Entity Details
+For each entity in the diagram, provide a detail table that captures constraints the diagram cannot express — required fields, defaults, validation rules, and indexing strategy. Also note which feature(s) introduced or depend on the entity.
+
+Example format:
+```
+### User
+| Field       | Type      | Constraints                 |
+|-------------|-----------|----------------------------|
+| id          | UUID      | Primary key, auto-generated |
+| email       | string    | Required, unique, indexed   |
+| password    | string    | Required, hashed            |
+| displayName | string    | Required                    |
+| createdAt   | timestamp | Auto-set                    |
+| updatedAt   | timestamp | Auto-updated                |
+
+Introduced by: [User Authentication](../features/user-authentication.md)
+```
+
+#### Relationship Notes
+- Document any patterns that need extra explanation: polymorphic associations, junction/join tables for many-to-many relationships, soft deletes, or tenant-scoping
+- Note any entities that are shared across multiple features — these are integration points the implementing agent should build carefully
+
+### 4. API Design
+**Mark as N/A if no API layer exists**
+
+#### Route Map
+- Complete list of API endpoints/routes grouped by feature or resource
+- For each endpoint: method, path, purpose, and auth requirement
+- Example format:
+  ```
+  ## Authentication
+  POST   /api/auth/register    # Create new account (public)
+  POST   /api/auth/login       # Sign in (public)
+  POST   /api/auth/logout      # Sign out (authenticated)
+  GET    /api/auth/me          # Get current user (authenticated)
+
+  ## Posts
+  GET    /api/posts            # List posts (authenticated)
+  POST   /api/posts            # Create post (authenticated)
+  GET    /api/posts/:id        # Get single post (authenticated)
+  PUT    /api/posts/:id        # Update post (owner only)
+  DELETE /api/posts/:id        # Delete post (owner only)
+  ```
+
+#### Request/Response Conventions
+- Standard response envelope (e.g., `{ data, error, meta }`)
+- Error response format with error codes
+- Pagination format (cursor-based, offset-based)
+- Common headers
+
+#### Validation Patterns
+- Where input validation happens (middleware, service layer, both)
+- Validation library or approach (from stack)
+- Common validation rules referenced across features
+
+### 5. Page & Component Architecture
+**Mark as N/A if no frontend exists**
+
+#### Page Map
+- List of pages/routes in the application with their purpose
+- Which feature each page belongs to
+- **Output a Mermaid `graph`** showing layout nesting and page hierarchy so the implementing agent can see how routes and layouts compose at a glance:
+  ```mermaid
+  graph TD
+      RootLayout["Root Layout (app/layout.tsx)"]
+      RootLayout --> AuthLayout["Auth Layout (app/(auth)/layout.tsx)"]
+      RootLayout --> AppLayout["App Layout (app/(app)/layout.tsx)"]
+      AuthLayout --> Login["/login"]
+      AuthLayout --> Register["/register"]
+      AppLayout --> Dashboard["/dashboard"]
+      AppLayout --> Settings["/settings"]
+      AppLayout --> PostDetail["/posts/:id"]
+  ```
+
+#### Shared Components
+- List of reusable UI components the application needs (derived from style guide and feature requirements)
+- For each: name, purpose, and which features use it
+
+#### Component Patterns
+- How to structure feature-specific vs. shared components
+- Data fetching pattern (server components, client hooks, SWR/React Query, etc.)
+- Form handling approach
+- Error boundary and loading state patterns
+
+### 6. Service & Integration Architecture
+**Mark as N/A if not applicable**
+
+#### Internal Services
+- How business logic is organized (service layer, use cases, repositories, etc.)
+- Shared services (auth, email, file upload, etc.)
+- Service communication patterns
+
+#### External Integrations
+- Third-party services and how they're consumed
+- API client patterns
+- Webhook handling (if applicable)
+
+#### Background Jobs / Events (if applicable)
+- Async processing patterns
+- Event-driven flows between features
+- Queue/worker architecture
+
+### 7. Authentication & Authorization Architecture
+**Mark as N/A if no auth required**
+
+- Session/token management approach
+- Route/endpoint protection pattern
+- Role/permission model (if applicable)
+- Where auth checks happen in the code (middleware, guards, decorators, etc.)
+- **Output a Mermaid `sequenceDiagram` or `flowchart`** showing the primary auth flow so the implementing agent can see the full sequence of steps, redirects, and token exchanges:
+  ```mermaid
+  sequenceDiagram
+      actor U as User
+      participant C as Client
+      participant A as API
+      participant DB as Database
+
+      U->>C: Submit login form
+      C->>A: POST /api/auth/login
+      A->>DB: Look up user by email
+      DB-->>A: User record
+      A->>A: Verify password hash
+      A->>DB: Create session
+      A-->>C: Set session cookie + return user
+      C-->>U: Redirect to /dashboard
+  ```
+
+### 8. Environment & Configuration
+
+#### Environment Variables
+- Complete list of required environment variables with descriptions and example values
+- Group by category (database, auth, external services, app config)
+- Mark which are secrets vs. non-secret
+- Example `.env` format:
+  ```
+  # Database
+  DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
+
+  # Authentication
+  JWT_SECRET=your-secret-key
+  SESSION_EXPIRY=86400
+
+  # External Services
+  SMTP_HOST=smtp.example.com
+  ```
+
+#### Configuration Files
+- List of configuration files the project needs with their purposes
+- Key settings that differ from framework defaults
+- Example snippets for non-obvious configuration
+
+#### Project Setup
+- Step-by-step commands to initialize and run the project from scratch
+- Key packages to install by category
+- Database setup (create, migrate, seed)
+- Local development startup command
+
+### 9. Open Decisions & Assumptions
+- Technical decisions that were inferred rather than explicitly specified in existing specs
+- Assumptions made where feature specs were ambiguous
+- Areas where the architecture may need to evolve as features are implemented
+- Questions that should be resolved before or during implementation
+
+---
+
+## Tone & Style
+
+- Concrete and prescriptive — tell the implementing agent exactly what to do, not what to consider
+- Technology-specific — use actual library names, file paths, and code patterns from the stack
+- Feature-traceable — connect every architectural decision back to the features it serves
+- Designed for direct consumption by an implementing agent
+
+---
+
+## Input
+
+<<<ARCHITECTURE_CONTEXT>>>

package/commands/gspec.dor.md

@@ -26,9 +26,10 @@ Before making any changes, read all available gspec documents in this order:
 1. `gspec/profile.md` — Product identity and scope
 2. `gspec/epics/*.md` — Epic structure and feature dependencies
 3. `gspec/features/*.md` — Individual feature requirements
-4. `gspec/stack.md` — Technology choices and architecture
-5. `gspec/style.md` — Visual design system
-6. `gspec/practices.md` — Development standards and conventions
+4. `gspec/stack.md` — Technology choices
+5. `gspec/architecture.md` — Technical architecture: project structure, data model, API design, component architecture, environment setup
+6. `gspec/style.md` — Visual design system
+7. `gspec/practices.md` — Development standards and conventions
 
 If any files are missing, note what is missing and proceed with what is available. The user may not have all spec types — that is fine. You only update specs that exist. Do not create new spec files (profile, stack, style, practices) unless the user explicitly asks. You may create a new feature PRD only when a change introduces an entirely new feature that warrants its own document.
 
@@ -58,6 +59,17 @@ Execute the code changes:
 5. **Surface new issues as they arise** — If implementation reveals new ambiguities, pause and consult the user rather than making silent assumptions
 6. **Track spec implications as you work** — As you implement, mentally note which gspec documents will need updating based on what you are changing
 
+### Phase 3.5: Validate — Ensure Tests Pass
+
+Before updating any specs, verify the code changes are sound:
+
+1. **Check for existing tests** — Look for a test suite, test runner configuration, or test scripts in `package.json`, `Makefile`, or equivalent
+2. **If tests exist, run them** — Execute the project's test suite and confirm all tests pass
+3. **If tests fail** — Fix the failing tests before proceeding. Do not move to spec updates with a broken test suite
+4. **If no tests exist** — Note this and proceed. Do not create a test suite unless the user requests one or `gspec/practices.md` requires it
+
+This gate ensures specs are only updated to reflect working, validated code — never broken implementations.
+
 ### Phase 4: Assess — Determine Spec Impact
 
 After code changes are complete, systematically evaluate which gspec documents need updating. Apply this decision matrix:
@@ -66,11 +78,16 @@ After code changes are complete, systematically evaluate which gspec documents n
 |---|---|---|
 | New user-facing capability | `gspec/features/<relevant>.md` | Add capability to existing PRD using an **unchecked checkbox** (`- [ ]`), or create new PRD if entirely new feature |
 | Modified capability behavior | `gspec/features/<relevant>.md` | Update the affected capability description. **Preserve the checkbox state** (`[x]` or `[ ]`) — if the capability was already implemented and the modification is reflected in the code change, keep it checked |
-| Removed or deprecated capability | `gspec/features/<relevant>.md` | Remove the checkbox line and move to Non-Goals or Future Considerations, note deprecation |
+| Removed or deprecated capability | `gspec/features/<relevant>.md` | Remove the checkbox line and move to Scope section (out-of-scope or deferred), note deprecation |
 | New technology or dependency added | `gspec/stack.md` | Add to appropriate section with rationale |
 | Technology or dependency removed | `gspec/stack.md` | Remove and note why |
 | Technology version changed | `gspec/stack.md` | Update version |
-| Visual design change (colors, typography, spacing, components) | `gspec/style.md` | Update affected tokens, components, or patterns |
+| New data entity or changed data model | `gspec/architecture.md` | Update Data Model section with new/changed entities |
+| New API endpoint or changed route | `gspec/architecture.md` | Update API Design section with new/changed routes |
+| Project structure change (new directory, reorganization) | `gspec/architecture.md` | Update Project Structure section |
+| Environment variable added or changed | `gspec/architecture.md` | Update Environment & Configuration section |
+| Visual design change — generic (colors, typography, spacing, base component patterns) | `gspec/style.md` | Update affected tokens or base component patterns. Only include changes that are reusable and not tied to a specific feature or domain |
+| Visual design change — feature-specific (a component unique to a feature, domain-specific visual treatment) | `gspec/features/<relevant>.md` | Document the visual details in the feature PRD's capabilities or a dedicated "Visual Design" subsection |
 | Development practice change (testing, code org, conventions) | `gspec/practices.md` | Update affected practice |
 | Product scope or direction change | `gspec/profile.md` | Update affected sections (Product Description, Use Cases, Roadmap, etc.) |
 | Feature dependency change | `gspec/epics/<relevant>.md` | Update dependency map and phasing |
@@ -115,16 +132,15 @@ After approval, write the spec updates:
 2. **Preserve format** — Match the existing document's style, heading structure, and tone exactly
 3. **Add change context where valuable** — Where appropriate, add a brief parenthetical or note indicating the change (e.g., "*(Updated: added CSV export capability)*"). Do not over-annotate — use judgment about when a note adds value vs. noise. Small obvious changes need no annotation. Significant scope changes benefit from a brief note.
 4. **For new feature PRDs** — If the change introduces an entirely new feature that warrants its own PRD, follow the same structure used by the `gspec-feature` command:
-   - Overview (name, summary, objective)
-   - Problem & Context
-   - Goals & Non-Goals
+   - Overview (name, summary, problem being solved and why it matters now)
    - Users & Use Cases
-   - Assumptions & Open Questions
-   - Capabilities (with P0/P1/P2 priority levels)
+   - Scope (in-scope goals, out-of-scope items, deferred ideas)
+   - Capabilities (with P0/P1/P2 priority levels, each with 2-4 **acceptance criteria** as a sub-list)
+   - Dependencies (on other features or external services)
+   - Assumptions & Risks (assumptions, open questions, key risks and mitigations — note in assumptions that this feature was identified during iterative development)
    - Success Metrics
-   - Risks & Mitigations
-   - Future Considerations
-   - Note in the Assumptions section that this feature was identified during iterative development
+   - Begin the file with YAML frontmatter: `---\ngspec-version: <<<VERSION>>>\n---`
+   - **Also update `gspec/architecture.md`** if the new feature introduces data entities, API endpoints, or new components — add them to the appropriate architecture sections
 
 ### Phase 7: Verify — Confirm Consistency
 
@@ -150,10 +166,14 @@ After writing spec updates:
 
 **Traceability without clutter.** A brief note about why something changed is valuable for future readers. A changelog at the bottom of every file is not. Use judgment. For small, obvious changes, no annotation may be needed. For significant scope changes, a parenthetical note aids understanding.
 
+**Keep `style.md` generic and reusable.** The style guide defines the design system — colors, typography, spacing, base component patterns, and tokens that could apply to any product. Do not add feature-specific or domain-specific content to `style.md` (e.g., "recipe card layout", "playlist item styling"). Feature-specific visual details belong in the relevant feature PRD. If you are unsure whether a visual change is generic or feature-specific, ask the user.
+
 **When to create vs. update.** If a change adds a small capability that fits naturally within an existing feature PRD, update that PRD. If a change introduces a wholly new product area that does not belong in any existing PRD, create a new feature PRD. When in doubt, ask the user.
 
 **Implementation checkboxes.** Feature PRDs use markdown checkboxes (`- [ ]` / `- [x]`) on capabilities to track implementation status for `gspec-implement`. When DOR adds new capabilities, use unchecked checkboxes (`- [ ]`). When modifying a capability that was already checked (`- [x]`) and the code change reflects the modification, keep it checked. When creating a new feature PRD, use unchecked checkboxes for all capabilities. Do not check off capabilities that DOR did not implement in the current session.
 
+**Version frontmatter.** When updating existing gspec files, preserve the `gspec-version` YAML frontmatter at the top of the file. If a file lacks frontmatter, add `---\ngspec-version: <<<VERSION>>>\n---` as the very first content before the main heading.
+
 ---
 
 ## Gap-Filling Guidelines
@@ -183,7 +203,7 @@ After writing spec updates:
 - Present code changes and spec updates as separate, sequential activities
 - Reference specific gspec documents and section names when discussing spec impacts
 - Clearly distinguish between "the spec currently says X" and "I propose updating it to Y"
-- Create or modify files following the project structure conventions from `gspec/stack.md` and `gspec/practices.md`
+- Create or modify files following the project structure defined in `gspec/architecture.md` (or `gspec/stack.md` and `gspec/practices.md` if no architecture document exists)
 - Write production-quality code unless the user requests otherwise
 - Include tests as defined by `gspec/practices.md` testing standards
 

package/commands/gspec.epic.md

@@ -6,6 +6,29 @@ Generate multiple Product Requirements Documents (PRDs) from a high-level epic d
 
 Take the provided epic description (a large body of work) and break it down into **multiple focused Product Requirements Documents (PRDs)**, each representing a distinct feature or component that can be built independently.
 
+## Important: Agent-Oriented Documentation
+
+**These epics and PRDs are designed for automated agent consumption** (via `gspec-implement`), with humans validating the content for accuracy and completeness. Write documents that are:
+
+- **Implementation-ready blueprints**, not project plans
+- Focused on **what** to build and **why**, not **when** or **how long**
+- Clear on technical and functional requirements an agent needs to execute
+
+**AVOID project management details:**
+- ❌ Sprint planning, week numbers, or timeline estimates
+- ❌ Team assignments or resource allocation
+- ❌ Velocity or story point estimates
+- ❌ Delivery schedules or milestone dates
+- ❌ "Phase 1 ships in Q2" or similar calendar commitments
+
+**DO include implementation guidance:**
+- ✅ Clear functional requirements and acceptance criteria
+- ✅ Dependencies between features (technical, not temporal)
+- ✅ Priority levels (P0, P1, P2) for scope decisions
+- ✅ Build order recommendations based on technical dependencies
+- ✅ Minimum viable epic (MVE) scope definition
+- ✅ Feature sequencing based on what must be built first
+
 ## Guidelines
 
 - **Read existing gspec documents first** to ground the epic and its features in established product context
@@ -15,7 +38,7 @@ Take the provided epic description (a large body of work) and break it down into
 - Ensure features can be built incrementally and independently when possible
 - Consider dependencies between features
 - Focus on user value, scope, and outcomes
-- Write for product, design, and engineering audiences
+- Write for automated implementation with human validation
 - Be concise, structured, and decisive
 
 ---
@@ -41,6 +64,13 @@ If these files don't exist, proceed without them — they are optional context,
 - Output **multiple** Markdown documents (one per feature)
 - Save each file to the `gspec/features/` folder in the root of the project (create if it doesn't exist)
 - Name each file based on the feature (e.g., `user-authentication.md`, `dashboard-analytics.md`)
+- Begin every output file (both epic summary and individual feature PRDs) with YAML frontmatter containing the gspec version:
+  ```
+  ---
+  gspec-version: <<<VERSION>>>
+  ---
+  ```
+  The frontmatter must be the very first content in the file, before the main heading.
 - **Before generating the documents**, ask clarifying questions if:
   - The target users are unclear
   - The scope or boundaries of the epic are ambiguous
@@ -55,18 +85,44 @@ If these files don't exist, proceed without them — they are optional context,
   - Links to each individual feature PRD
 - Avoid deep system architecture or low-level implementation
 - No code blocks except where examples add clarity
-- Clear acceptance criteria are required for each feature
+- Clear acceptance criteria are required for each capability
 - Make tradeoffs and scope explicit
 
+### Technology Agnosticism
+
+**IMPORTANT**: Epic and feature PRDs must remain technology-agnostic to enable implementation with different technology stacks. The `gspec/stack.md` file is the single source of truth for technology choices.
+
+**DO use generic architectural terms:**
+- ✅ "database", "data store", "persistent storage"
+- ✅ "authentication service", "IAM", "identity provider"
+- ✅ "API", "backend service", "server"
+- ✅ "frontend", "client application", "user interface"
+- ✅ "message queue", "event system", "pub/sub"
+- ✅ "object storage", "file storage"
+- ✅ "cache", "caching layer"
+- ✅ "search index", "full-text search"
+
+**DO NOT reference specific technologies:**
+- ❌ React, Vue, Angular, Svelte
+- ❌ PostgreSQL, MySQL, MongoDB, DynamoDB
+- ❌ AWS Lambda, Google Cloud Functions, Azure Functions
+- ❌ Redis, Memcached
+- ❌ Elasticsearch, Algolia, Solr
+- ❌ S3, GCS, Azure Blob Storage
+- ❌ Kafka, RabbitMQ, SQS
+
+This separation allows the same epic and feature specs to be implemented using different technology stacks by swapping the Stack file.
+
 ## Epic Summary Document Structure
 
+**IMPORTANT**: Only include the sections listed below. Do NOT add additional sections such as "Technology Notes", "Implementation Details", "Technical Architecture", or any other custom sections. Stick strictly to this structure.
+
 Create a file at `gspec/epics/[epic-name].md` with:
 
 ### 1. Epic Overview
 - Epic name
 - Executive summary
 - Strategic objective
-- Target timeline or phases
 
 ### 2. Features Breakdown
 - List of all features with links to their PRDs, **using unchecked markdown checkboxes** (e.g., `- [ ] **P0**: [Feature Name](../features/feature-name.md) — Brief description`). The `gspec-implement` command will check these off (`- [x]`) as features are fully implemented, allowing incremental runs.
@@ -92,58 +148,50 @@ Create a file at `gspec/epics/[epic-name].md` with:
 
 ## Individual Feature PRD Structure
 
+**IMPORTANT**: Only include the sections listed below. Do NOT add additional sections such as "Technology Notes", "Implementation Details", "Technical Architecture", or any other custom sections. Stick strictly to this structure.
+
 For each feature, create a separate file in `gspec/features/[feature-name].md` with:
 
 ### 1. Overview
 - Feature name
-- Summary
-- Objective
+- Summary (1-2 sentences)
+- Problem being solved and why it matters now
 - **Parent Epic** (link to epic summary)
 
-### 2. Problem & Context
-- User problem
-- Why this matters now
-- Current pain points
-- How this fits into the larger epic
-
-### 3. Goals & Non-Goals
-- In-scope goals
-- Explicitly out-of-scope items
-
-### 4. Users & Use Cases
+### 2. Users & Use Cases
 - Primary users
-- Key use cases
-
-### 5. Assumptions & Open Questions
-- Assumptions
-- Open questions (non-blocking)
+- Key use cases (3-4 scenarios showing how users benefit)
 
-### 6. Functional Requirements
-- Numbered requirements
-- Written in user-focused language
-- Clear acceptance criteria
-- **Priority level** for each requirement (P0 = must-have, P1 = should-have, P2 = nice-to-have)
-- **Use unchecked markdown checkboxes** for each requirement to enable implementation tracking (e.g., `- [ ] **P0**: FR-1 — User can create an account`). The `gspec-implement` command will check these off (`- [x]`) as requirements are implemented.
-
-### 7. User Experience Requirements
-- UX principles
-- Key flows (high level)
-- Empty and error states
-
-### 8. Success Metrics
-- How success is measured
-- Leading vs lagging indicators
-
-### 9. Dependencies
+### 3. Scope
+- In-scope goals
+- Out-of-scope items (things this feature explicitly won't do)
+- Deferred ideas (things we may do later, but not now)
+
+### 4. Capabilities
+- What the feature provides to users, written in user-focused language
+- **Priority level** for each capability (P0 = must-have, P1 = should-have, P2 = nice-to-have)
+- Focus on *what* users can do, not *how* they do it — include UX expectations (empty states, error handling, key flows) as acceptance criteria on the relevant capabilities
+- **Use unchecked markdown checkboxes** for each capability to enable implementation tracking (e.g., `- [ ] **P0**: User can create an account`). The `gspec-implement` command will check these off (`- [x]`) as capabilities are implemented, allowing incremental runs.
+- **Each capability MUST include brief acceptance criteria** — 2-4 testable conditions that define "done" for that capability. These tell the implementing agent exactly when a capability is complete and give test writers concrete assertions. Format as a sub-list under each capability:
+  ```
+  - [ ] **P0**: User can create an account
+    - Valid email + strong password → account is created and confirmation is sent
+    - Duplicate email → error message explains email is taken
+    - Weak password → inline validation shows password requirements
+  ```
+
+### 5. Dependencies
 - Dependencies on other features in this epic
 - External dependencies
+- If none, state "None"
 
-### 10. Risks & Mitigations
-- Product or delivery risks
-- Mitigation strategies
+### 6. Assumptions & Risks
+- Assumptions (what we're taking as true)
+- Open questions (non-blocking unknowns to resolve during implementation)
+- Key risks and mitigations (brief bullet points — focus on risks that could affect implementation scope or approach)
 
-### 11. Future Considerations
-- Explicitly deferred ideas
+### 7. Success Metrics
+- 2-4 measurable outcomes that define whether this feature is working
 
 ## Workflow