ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new uxui design agent and architect improvements

Browse Source
This commit is contained in:
Brian Madison
2025-05-11 18:23:04 -05:00
parent cfb2712dfc
commit 85d9c229cb
12 changed files with 965 additions and 858 deletions
Download Patch File Download Diff File Expand all files Collapse all files

534
BETA-V3/gems-and-gpts/templates/architecture-templates.txt → BETA-V3/gems-and-gpts/templates/architecture-template.txt
View File

@@ -1,149 +1,124 @@
# Architecture Sub Document Templates
## Master Architecture Template
```Markdown
# {Project Name} Architecture Document
## Table of Contents
{ Update this if sections and subsections are added or removed }
- [Technical Summary](#technical-summary)
- [High-Level Overview](#high-level-overview)
- [Component View](#component-view)
- [Architectural / Design Patterns Adopted](#architectural--design-patterns-adopted)
- [API Reference](#api-reference)
- [External APIs Consumed](#external-apis-consumed)
- [{Another External Service Name} API](#another-external-service-name-api)
- [Internal APIs Provided (If Applicable)](#internal-apis-provided-if-applicable)
- [Data Models](#data-models)
- [Core Application Entities / Domain Objects](#core-application-entities--domain-objects)
- [API Payload Schemas (If distinct)](#api-payload-schemas-if-distinct)
- [Database Schemas (If applicable)](#database-schemas-if-applicable)
- [State File Schemas (If applicable)](#state-file-schemas-if-applicable)
- [Core Workflow / Sequence Diagrams](#core-workflow--sequence-diagrams)
- [Definitive Tech Stack Selections](#definitive-tech-stack-selections)
- [Infrastructure and Deployment Overview](#infrastructure-and-deployment-overview)
- [Error Handling Strategy](#error-handling-strategy)
- [Environment Vars Templates](#environment-vars-templates)
- [Configuration Loading Mechanism](#configuration-loading-mechanism)
- [Required Variables](#required-variables)
- [Env Var Notes](#env-var-notes)
- [Security Best Practices](#security-best-practices)
- [Testing Strategy](#testing-strategy)
- [Overall Philosophy & Goals](#overall-philosophy--goals)
- [Testing Levels](#testing-levels)
- [Specialized Testing Types (Add section as needed)](#specialized-testing-types-add-section-as-needed)
- [Test Data Management](#test-data-management)
- [Key Reference Documents](#key-reference-documents)
- [Change Log](#change-log)
## Technical Summary
{Provide a brief (1-2 paragraph) overview of the system's architecture, key components, technology choices, and architectural patterns used. Reference the goals from the PRD.}
{ Provide a brief paragraph overview of the system's architecture, key components, technology choices, and architectural patterns used. Reference the goals from the PRD. }
## High-Level Overview
{Describe the main architectural style (e.g., Monolith, Microservices, Serverless, Event-Driven). Explain the primary user interaction or data flow at a conceptual level.}
{ Describe the main architectural style (e.g., Monolith, Microservices, Serverless, Event-Driven). Explain the primary user interaction or data flow at a conceptual level. }
```mermaid
{Insert high-level system context or interaction diagram here - e.g., using Mermaid graph TD or C4 Model Context Diagram}
```
{ Insert high-level mermaid system context or interaction diagram here - e.g., Mermaid Class C4 Models Layer 1 and 2 }
## Component View
{Describe the major logical components or services of the system and their responsibilities. Explain how they collaborate.}
```mermaid
{Insert component diagram here - e.g., using Mermaid graph TD or C4 Model Container/Component Diagram}
```
{ Describe the major logical components or services of the system and their responsibilities. Explain how they collaborate. }
- Component A: {Description of responsibility}
- Component B: {Description of responsibility}
- {src/ Directory (if applicable): The application code in src/ is organized into logical modules... (briefly describe key subdirectories like clients, core, services, etc., referencing docs/project-structure.md for the full layout)}
## Key Architectural Decisions & Patterns
{Insert component diagram here if it helps - e.g., using Mermaid graph TD or C4 Model Container/Component Diagram}
{List significant architectural choices and the patterns employed.}
- Component N...: {Description of responsibility}
- Pattern/Decision 1: {e.g., Choice of Database, Message Queue Usage, Authentication Strategy, API Design Style (REST/GraphQL)} - Justification: {...}
- Pattern/Decision 2: {...} - Justification: {...}
- (See docs/coding-standards.md for detailed coding patterns and error handling)
{ Insert component diagram here if it helps - e.g., using Mermaid graph TD or C4 Model Container/Component Diagram }
## Core Workflow / Sequence Diagrams (Optional)
### Architectural / Design Patterns Adopted
{Illustrate key or complex workflows using sequence diagrams if helpful.}
{ List the key high-level patterns chosen in the architecture document. These foundational patterns should be established early as they guide component design, interactions, and technology choices. }
## Infrastructure and Deployment Overview
- Cloud Provider(s): {e.g., AWS, Azure, GCP, On-premise}
- Core Services Used: {List key managed services - e.g., Lambda, S3, Kubernetes Engine, RDS, Kafka}
- Infrastructure as Code (IaC): {Tool used - e.g., AWS CDK, Terraform, Pulumi, ARM Templates} - Location: {Link to IaC code repo/directory}
- Deployment Strategy: {e.g., CI/CD pipeline, Manual deployment steps, Blue/Green, Canary} - Tools: {e.g., Jenkins, GitHub Actions, GitLab CI}
- Environments: {List environments - e.g., Development, Staging, Production}
- (See docs/environment-vars.md for configuration details)
## Key Reference Documents
{Link to other relevant documents in the docs/ folder.}
- docs/prd.md
- docs/epicN.md files
- docs/tech-stack.md
- docs/project-structure.md
- docs/coding-standards.md
- docs/api-reference.md
- docs/data-models.md
- docs/environment-vars.md
- docs/testing-strategy.md
- docs/ui-ux-spec.md (if applicable)
- ... (other relevant docs)
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ---------------------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft based on brief | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
## Coding Standards Template
```Markdown
# {Project Name} Coding Standards and Patterns
## Architectural / Design Patterns Adopted
{List the key high-level patterns chosen in the architecture document.}
- **Pattern 1:** {e.g., Serverless, Event-Driven, Microservices, CQRS} - _Rationale/Reference:_ {Briefly why, or link to `docs/architecture.md` section}
- **Pattern 1:** {e.g., Serverless, Event-Driven, Microservices, CQRS} - _Rationale/Reference:_ {Briefly why, or link to a more detailed explanation if needed}
- **Pattern 2:** {e.g., Dependency Injection, Repository Pattern, Module Pattern} - _Rationale/Reference:_ {...}
- **Pattern N:** {...}
## Coding Standards (Consider adding these to Dev Agent Context or Rules)
## API Reference
- **Primary Language(s):** {e.g., TypeScript 5.x, Python 3.11, Go 1.2x}
- **Primary Runtime(s):** {e.g., Node.js 22.x, Python Runtime for Lambda}
- **Style Guide & Linter:** {e.g., ESLint with Airbnb config, Prettier; Black, Flake8; Go fmt} - _Configuration:_ {Link to config files or describe setup}
- **Naming Conventions:**
- Variables: `{e.g., camelCase}`
- Functions: `{e.g., camelCase}`
- Classes/Types/Interfaces: `{e.g., PascalCase}`
- Constants: `{e.g., UPPER_SNAKE_CASE}`
- Files: `{e.g., kebab-case.ts, snake_case.py}`
- **File Structure:** Adhere to the layout defined in `docs/project-structure.md`.
- **Asynchronous Operations:** {e.g., Use `async`/`await` in TypeScript/Python, Goroutines/Channels in Go.}
- **Type Safety:** {e.g., Leverage TypeScript strict mode, Python type hints, Go static typing.} - _Type Definitions:_ {Location, e.g., `src/common/types.ts`}
- **Comments & Documentation:** {Expectations for code comments, docstrings, READMEs.}
- **Dependency Management:** {Tool used - e.g., npm, pip, Go modules. Policy on adding dependencies.}
### External APIs Consumed
## Error Handling Strategy
{Repeat this section for each external API the system interacts with.}
- **General Approach:** {e.g., Use exceptions, return error codes/tuples, specific error types.}
- **Logging:**
- Library/Method: {e.g., `console.log/error`, Python `logging` module, dedicated logging library}
- Format: {e.g., JSON, plain text}
- Levels: {e.g., DEBUG, INFO, WARN, ERROR}
- Context: {What contextual information should be included?}
- **Specific Handling Patterns:**
- External API Calls: {e.g., Use `try/catch`, check response codes, implement retries with backoff for transient errors?}
- Input Validation: {Where and how is input validated?}
- Graceful Degradation vs. Critical Failure: {Define criteria for when to continue vs. halt.}
#### {External Service Name} API
## Security Best Practices
- **Purpose:** {Why does the system use this API?}
- **Base URL(s):**
- Production: `{URL}`
- Staging/Dev: `{URL}`
- **Authentication:** {Describe method - e.g., API Key in Header (Header Name: `X-API-Key`), OAuth 2.0 Client Credentials, Basic Auth. Reference `docs/environment-vars.md` for key names.}
- **Key Endpoints Used:**
- **`{HTTP Method} {/path/to/endpoint}`:**
- Description: {What does this endpoint do?}
- Request Parameters: {Query params, path params}
- Request Body Schema: {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if the schema is exceptionally large or complex.}
- Example Request: `{Code block}`
- Success Response Schema (Code: `200 OK`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Example Response: `{Code block}`
- **`{HTTP Method} {/another/endpoint}`:** {...}
- **Rate Limits:** {If known}
- **Link to Official Docs:** {URL}
{Outline key security considerations relevant to the codebase.}
### {Another External Service Name} API
- Input Sanitization/Validation: {...}
- Secrets Management: {How are secrets handled in code? Reference `docs/environment-vars.md` regarding storage.}
- Dependency Security: {Policy on checking for vulnerable dependencies.}
- Authentication/Authorization Checks: {Where should these be enforced?}
- {Other relevant practices...}
{...}
## Change Log
### Internal APIs Provided (If Applicable)
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
{If the system exposes its own APIs (e.g., in a microservices architecture or for a UI frontend). Repeat for each API.}
## Data Models Template
#### {Internal API / Service Name} API
```Markdown
# {Project Name} Data Models
- **Purpose:** {What service does this API provide?}
- **Base URL(s):** {e.g., `/api/v1/...`}
- **Authentication/Authorization:** {Describe how access is controlled.}
- **Endpoints:**
- **`{HTTP Method} {/path/to/endpoint}`:**
- Description: {What does this endpoint do?}
- Request Parameters: {...}
- Request Body Schema: {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Success Response Schema (Code: `200 OK`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {Provide JSON schema inline, or link to a detailed definition in `docs/data-models.md` only if very complex.}
- **`{HTTP Method} {/another/endpoint}`:** {...}
## 2. Core Application Entities / Domain Objects
## Data Models
### Core Application Entities / Domain Objects
{Define the main objects/concepts the application works with. Repeat subsection for each key entity.}
### {Entity Name, e.g., User, Order, Product}
#### {Entity Name, e.g., User, Order, Product}
- **Description:** {What does this entity represent?}
- **Schema / Interface Definition:**
@@ -159,15 +134,15 @@
_(Alternatively, use JSON Schema, class definitions, or other relevant format)_
- **Validation Rules:** {List any specific validation rules beyond basic types - e.g., max length, format, range.}
### {Another Entity Name}
#### {Another Entity Name}
{...}
## API Payload Schemas (If distinct)
### API Payload Schemas (If distinct)
{Define schemas specifically for data sent to or received from APIs, if they differ significantly from the core entities. Reference `docs/api-reference.md`.}
{Define schemas here only if they are distinct from core entities AND not fully detailed under the API endpoint definitions in the API Reference section. Prefer detailing request/response schemas directly with their APIs where possible. This section is for complex, reusable payload structures that might be used across multiple internal APIs or differ significantly from core persisted entities.}
### {API Endpoint / Purpose, e.g., Create Order Request}
#### {API Endpoint / Purpose, e.g., Create Order Request}
- **Schema / Interface Definition:**
```typescript
@@ -179,15 +154,15 @@
}
```
### {Another API Payload}
#### {Another API Payload}
{...}
## Database Schemas (If applicable)
### Database Schemas (If applicable)
{If using a database, define table structures or document database schemas.}
### {Table / Collection Name}
#### {Table / Collection Name}
- **Purpose:** {What data does this table store?}
- **Schema Definition:**
@@ -202,15 +177,15 @@
```
_(Alternatively, use ORM model definitions, NoSQL document structure, etc.)_
### {Another Table / Collection Name}
#### {Another Table / Collection Name}
{...}
## State File Schemas (If applicable)
### State File Schemas (If applicable)
{If the application uses files for persisting state.}
### {State File Name / Purpose, e.g., processed_items.json}
#### {State File Name / Purpose, e.g., processed_items.json}
- **Purpose:** {What state does this file track?}
- **Format:** {e.g., JSON}
@@ -232,137 +207,22 @@
}
```
## Change Log
## Core Workflow / Sequence Diagrams
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
{ Illustrate key or complex workflows using mermaid sequence diagrams. Can have high level tying the full project together, and also smaller epic level sequence diagrams. }
## Environment Vars Templates
## Definitive Tech Stack Selections
```Markdown
# {Project Name} Environment Variables
{ This section outlines the definitive technology choices for the project. These selections should be made after a thorough understanding of the project's requirements, components, data models, and core workflows. The Architect Agent should guide the user through these decisions, ensuring each choice is justified and recorded accurately in the table below.
## Configuration Loading Mechanism
Key decisions to discuss and finalize here, which will then be expanded upon and formally documented in the detailed stack table below, include considerations such as:
{Describe how environment variables are loaded into the application.}
- Preferred Starter Template Frontend: { Url to template or starter, if used }
- Preferred Starter Template Backend: { Url to template or starter, if used }
- Primary Language(s) & Version(s): {e.g., TypeScript 5.x, Python 3.11}
- Primary Runtime(s) & Version(s): {e.g., Node.js 22.x}
- **Local Development:** {e.g., Using `.env` file with `dotenv` library.}
- **Deployment (e.g., AWS Lambda, Kubernetes):** {e.g., Set via Lambda function configuration, Kubernetes Secrets/ConfigMaps.}
## Required Variables
{List all environment variables used by the application.}
| Variable Name | Description | Example / Default Value | Required? (Yes/No) | Sensitive? (Yes/No) |
| :------------------- | :---------------------------------------------- | :------------------------------------ | :----------------- | :------------------ |
| `NODE_ENV` | Runtime environment | `development` / `production` | Yes | No |
| `PORT` | Port the application listens on (if applicable) | `8080` | No | No |
| `DATABASE_URL` | Connection string for the primary database | `postgresql://user:pass@host:port/db` | Yes | Yes |
| `EXTERNAL_API_KEY` | API Key for {External Service Name} | `sk_...` | Yes | Yes |
| `S3_BUCKET_NAME` | Name of the S3 bucket for {Purpose} | `my-app-data-bucket-...` | Yes | No |
| `FEATURE_FLAG_X` | Enables/disables experimental feature X | `false` | No | No |
| `{ANOTHER_VARIABLE}` | {Description} | {Example} | {Yes/No} | {Yes/No} |
| ... | ... | ... | ... | ... |
## Notes
- **Secrets Management:** {Explain how sensitive variables (API Keys, passwords) should be handled, especially in production (e.g., "Use AWS Secrets Manager", "Inject via CI/CD pipeline").}
- **`.env.example`:** {Mention that an `.env.example` file should be maintained in the repository with placeholder values for developers.}
- **Validation:** {Is there code that validates the presence or format of these variables at startup?}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
## Project Structure Template Example
```Markdown
# {Project Name} Project Structure
{Provide an ASCII or Mermaid diagram representing the project's folder structure such as the following example.}
```plaintext
{project-root}/
├── .github/ # CI/CD workflows (e.g., GitHub Actions)
│ └── workflows/
│ └── main.yml
├── .vscode/ # VSCode settings (optional)
│ └── settings.json
├── build/ # Compiled output (if applicable, often git-ignored)
├── config/ # Static configuration files (if any)
├── docs/ # Project documentation (PRD, Arch, etc.)
│ ├── index.md
│ └── ... (other .md files)
├── infra/ # Infrastructure as Code (e.g., CDK, Terraform)
│ └── lib/
│ └── bin/
├── node_modules/ # Project dependencies (git-ignored)
├── scripts/ # Utility scripts (build, deploy helpers, etc.)
├── src/ # Application source code
│ ├── common/ # Shared utilities, types, constants
│ ├── components/ # Reusable UI components (if UI exists)
│ ├── features/ # Feature-specific modules (alternative structure)
│ │ └── feature-a/
│ ├── core/ # Core business logic
│ ├── clients/ # External API/Service clients
│ ├── services/ # Internal services / Cloud SDK wrappers
│ ├── pages/ / routes/ # UI pages or API route definitions
│ └── main.ts / index.ts / app.ts # Application entry point
├── stories/ # Generated story files for development (optional)
│ └── epic1/
├── test/ # Automated tests
│ ├── unit/ # Unit tests (mirroring src structure)
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── .env.example # Example environment variables
├── .gitignore # Git ignore rules
├── package.json # Project manifest and dependencies
├── tsconfig.json # TypeScript configuration (if applicable)
├── Dockerfile # Docker build instructions (if applicable)
└── README.md # Project overview and setup instructions
```
(Adjust the example tree based on the actual project type - e.g., Python would have requirements.txt, etc.)
## Key Directory Descriptions
docs/: Contains all project planning and reference documentation.
infra/: Holds the Infrastructure as Code definitions (e.g., AWS CDK, Terraform).
src/: Contains the main application source code.
common/: Code shared across multiple modules (utilities, types, constants). Avoid business logic here.
core/ / domain/: Core business logic, entities, use cases, independent of frameworks/external services.
clients/: Modules responsible for communicating with external APIs or services.
services/ / adapters/ / infrastructure/: Implementation details, interactions with databases, cloud SDKs, frameworks.
routes/ / controllers/ / pages/: Entry points for API requests or UI views.
test/: Contains all automated tests, mirroring the src/ structure where applicable.
scripts/: Helper scripts for build, deployment, database migrations, etc.
## Notes
{Mention any specific build output paths, compiler configuration pointers, or other relevant structural notes.}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
## Tech Stack Template
```Markdown
# {Project Name} Technology Stack
## Technology Choices
Must be definitive selections; do not list open-ended choices (e.g., for web scraping, pick one tool, not two). Specify versions or clearly state "Latest," but be cautious with "Latest" if dependency issues are a concern. }
| Category | Technology | Version / Details | Description / Purpose | Justification (Optional) |
| :------------------- | :---------------------- | :---------------- | :-------------------------------------- | :----------------------- |
@@ -387,19 +247,68 @@ scripts/: Helper scripts for build, deployment, database migrations, etc.
| **Other Tools** | {e.g., LangChain.js} | {e.g., Latest} | {LLM interaction library} | {...} |
| | {e.g., Cheerio} | {e.g., Latest} | {HTML parsing/scraping} | {...} |
## Change Log
## Infrastructure and Deployment Overview
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... |
- Cloud Provider(s): {e.g., AWS, Azure, GCP, On-premise}
- Core Services Used: {List key managed services - e.g., Lambda, S3, Kubernetes Engine, RDS, Kafka}
- Infrastructure as Code (IaC): {Tool used - e.g., AWS CDK, Terraform...} - Location: {Link to IaC code repo/directory}
- Deployment Strategy: {e.g., CI/CD pipeline, Manual deployment steps, Blue/Green, Canary} - Tools: {e.g., Jenkins, GitHub Actions, GitLab CI}
- Environments: {List environments - e.g., Development, Staging, Production}
```
## Error Handling Strategy
## Testing Strategy Template
- **General Approach:** {e.g., Use exceptions, return error codes/tuples, specific error types.}
- **Logging:**
- Library/Method: {e.g., `console.log/error`, Python `logging` module, dedicated logging library}
- Format: {e.g., JSON, plain text}
- Levels: {e.g., DEBUG, INFO, WARN, ERROR}
- Context: {What contextual information should be included?}
- **Specific Handling Patterns:**
- External API Calls: {e.g., Use `try/catch`, check response codes, implement retries with backoff for transient errors?}
- Input Validation: {Where and how is input validated?}
- Graceful Degradation vs. Critical Failure: {Define criteria for when to continue vs. halt.}
```Markdown
# {Project Name} Testing Strategy
## Environment Vars Templates
### Configuration Loading Mechanism
{Describe how environment variables are loaded into the application.}
- **Local Development:** {e.g., Using `.env` file with `dotenv` library.}
- **Deployment (e.g., AWS Lambda, Kubernetes):** {e.g., Set via Lambda function configuration, Kubernetes Secrets/ConfigMaps.}
### Required Variables
{List all environment variables used by the application.}
| Variable Name | Description | Example / Default Value | Required? (Yes/No) | Sensitive? (Yes/No) |
| :------------------- | :---------------------------------------------- | :------------------------------------ | :----------------- | :------------------ |
| `NODE_ENV` | Runtime environment | `development` / `production` | Yes | No |
| `PORT` | Port the application listens on (if applicable) | `8080` | No | No |
| `DATABASE_URL` | Connection string for the primary database | `postgresql://user:pass@host:port/db` | Yes | Yes |
| `EXTERNAL_API_KEY` | API Key for {External Service Name} | `sk_...` | Yes | Yes |
| `S3_BUCKET_NAME` | Name of the S3 bucket for {Purpose} | `my-app-data-bucket-...` | Yes | No |
| `FEATURE_FLAG_X` | Enables/disables experimental feature X | `false` | No | No |
| `{ANOTHER_VARIABLE}` | {Description} | {Example} | {Yes/No} | {Yes/No} |
| ... | ... | ... | ... | ... |
### Env Var Notes
- **Secrets Management:** {Explain how sensitive variables (API Keys, passwords) should be handled, especially in production (e.g., "Use AWS Secrets Manager", "Inject via CI/CD pipeline").}
- **`.env.example`:** {Mention that an `.env.example` file should be maintained in the repository with placeholder values for developers.}
- **Validation:** {Is there code that validates the presence or format of these variables at startup?}
## Security Best Practices
{Outline key security considerations relevant to the codebase.}
- Input Sanitization/Validation: {...}
- Secrets Management: {How are secrets handled in code? Reference `docs/environment-vars.md` regarding storage.}
- Dependency Security: {Policy on checking for vulnerable dependencies.}
- Authentication/Authorization Checks: {Where should these be enforced?}
- {Other relevant practices...}
## Testing Strategy
## Overall Philosophy & Goals
@@ -413,143 +322,86 @@ scripts/: Helper scripts for build, deployment, database migrations, etc.
### Unit Tests
#### EXAMPLE:
- **Scope:** Test individual functions, methods, or components in isolation. Focus on business logic, calculations, and conditional paths within a single module.
- **Tools:** {e.g., Jest, Pytest, Go testing package, JUnit, NUnit}
- **Mocking/Stubbing:** {How are dependencies mocked? e.g., Jest mocks, Mockito, Go interfaces}
- **Location:** {e.g., `test/unit/`, alongside source files (`*.test.ts`)}
- **Location:** {e.g., `test/unit/`, adhering to the structure in `docs/project-structure.md` or alongside source files (`*.test.ts`)}
- **Expectations:** {e.g., Should cover all significant logic paths. Fast execution.}
### Integration Tests
#### EXAMPLE:
- **Scope:** Verify the interaction and collaboration between multiple internal components or modules. Test the flow of data and control within a specific feature or workflow slice. May involve mocking external APIs or databases, or using test containers.
- **Tools:** {e.g., Jest, Pytest, Go testing package, Testcontainers, Supertest (for APIs)}
- **Location:** {e.g., `test/integration/`}
- **Location:** {e.g., `test/integration/`, adhering to the structure in `docs/project-structure.md`}
- **Expectations:** {e.g., Focus on module boundaries and contracts. Slower than unit tests.}
### End-to-End (E2E) / Acceptance Tests
#### EXAMPLE:
- **Scope:** Test the entire system flow from an end-user perspective. Interact with the application through its external interfaces (UI or API). Validate complete user journeys or business processes against real or near-real dependencies.
- **Tools:** {e.g., Playwright, Cypress, Selenium (for UI); Postman/Newman, K6 (for API)}
- **Environment:** {Run against deployed environments (e.g., Staging) or a locally composed setup (Docker Compose).}
- **Location:** {e.g., `test/e2e/`}
- **Location:** {e.g., `test/e2e/`, adhering to the structure in `docs/project-structure.md`}
- **Expectations:** {Cover critical user paths. Slower, potentially flaky, run less frequently (e.g., pre-release, nightly).}
### Manual / Exploratory Testing (Optional)
#### EXAMPLE:
- **Scope:** {Where is manual testing still required? e.g., Exploratory testing for usability, testing complex edge cases.}
- **Process:** {How is it performed and tracked?}
## Specialized Testing Types (Add sections as needed)
### Specialized Testing Types (Add section as needed)
### Performance Testing
#### EXAMPLE:
- **Scope & Goals:** {What needs performance testing? What are the targets (latency, throughput)?}
- **Tools:** {e.g., K6, JMeter, Locust}
### Security Testing
#### EXAMPLE:
- **Scope & Goals:** {e.g., Dependency scanning, SAST, DAST, penetration testing requirements.}
- **Tools:** {e.g., Snyk, OWASP ZAP, Dependabot}
### Accessibility Testing (UI)
#### EXAMPLE:
- **Scope & Goals:** {Target WCAG level, key areas.}
- **Tools:** {e.g., Axe, Lighthouse, manual checks}
### Visual Regression Testing (UI)
#### EXAMPLE:
- **Scope & Goals:** {Prevent unintended visual changes.}
- **Tools:** {e.g., Percy, Applitools Eyes, Playwright visual comparisons}
## Test Data Management
### Test Data Management
#### EXAMPLE:
{How is test data generated, managed, and reset for different testing levels?}
## CI/CD Integration
## Key Reference Documents
{How and when are tests executed in the CI/CD pipeline? What constitutes a pipeline failure?}
See docs/index.md
- docs/front-end-architecture.md {If applicable, for detailed frontend technical design}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
| Change | Date | Version | Description | Author |
| ------ | ---- | ------- | ----------- | ------ |
```
## Epic Story updates
## API Reference Template
```Markdown
# {Project Name} API Reference
## External APIs Consumed
{Repeat this section for each external API the system interacts with.}
### {External Service Name} API
- **Purpose:** {Why does the system use this API?}
- **Base URL(s):**
- Production: `{URL}`
- Staging/Dev: `{URL}`
- **Authentication:** {Describe method - e.g., API Key in Header (Header Name: `X-API-Key`), OAuth 2.0 Client Credentials, Basic Auth. Reference `docs/environment-vars.md` for key names.}
- **Key Endpoints Used:**
- **`{HTTP Method} {/path/to/endpoint}`:**
- Description: {What does this endpoint do?}
- Request Parameters: {Query params, path params}
- Request Body Schema: {Provide JSON schema or link to `docs/data-models.md`}
- Example Request: `{Code block}`
- Success Response Schema (Code: `200 OK`): {JSON schema or link}
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {JSON schema or link}
- Example Response: `{Code block}`
- **`{HTTP Method} {/another/endpoint}`:** {...}
- **Rate Limits:** {If known}
- **Link to Official Docs:** {URL}
### {Another External Service Name} API
{...}
## Internal APIs Provided (If Applicable)
{If the system exposes its own APIs (e.g., in a microservices architecture or for a UI frontend). Repeat for each API.}
### {Internal API / Service Name} API
- **Purpose:** {What service does this API provide?}
- **Base URL(s):** {e.g., `/api/v1/...`}
- **Authentication/Authorization:** {Describe how access is controlled.}
- **Endpoints:**
- **`{HTTP Method} {/path/to/endpoint}`:**
- Description: {What does this endpoint do?}
- Request Parameters: {...}
- Request Body Schema: {...}
- Success Response Schema (Code: `200 OK`): {...}
- Error Response Schema(s) (Codes: `4xx`, `5xx`): {...}
- **`{HTTP Method} {/another/endpoint}`:** {...}
## AWS Service SDK Usage (or other Cloud Providers)
{Detail interactions with cloud provider services via SDKs.}
### {AWS Service Name, e.g., S3}
- **Purpose:** {Why is this service used?}
- **SDK Package:** {e.g., `@aws-sdk/client-s3`}
- **Key Operations Used:** {e.g., `GetObjectCommand`, `PutObjectCommand`}
- Operation 1: {Brief description of usage context}
- Operation 2: {...}
- **Key Resource Identifiers:** {e.g., Bucket names, Table names - reference `docs/environment-vars.md`}
### {Another AWS Service Name, e.g., SES}
{...}
## 5. Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
{ Upon completion of all sections, any changes needed for epics or stories will be listed here }

44
BETA-V3/gems-and-gpts/templates/epicN.txt
View File

@@ -1,44 +0,0 @@
# Epic {N}: {Epic Title}
**Goal:** {State the overall goal this epic aims to achieve, linking back to the PRD goals.}
## Story List
{List all stories within this epic. Repeat the structure below for each story.}
### Story {N}.{M}: {Story Title}
- **User Story / Goal:** {Describe the story goal, ideally in "As a [role], I want [action], so that [benefit]" format, or clearly state the technical goal.}
- **Detailed Requirements:**
- {Bulleted list explaining the specific functionalities, behaviors, or tasks required for this story.}
- {Reference other documents for context if needed, e.g., "Handle data according to `docs/data-models.md#EntityName`".}
- {Include any technical constraints or details identified during refinement - added by Architect/PM/Tech SM.}
- **Acceptance Criteria (ACs):**
- AC1: {Specific, verifiable condition that must be met.}
- AC2: {Another verifiable condition.}
- ACN: {...}
- **Tasks (Optional Initial Breakdown):**
- [ ] {High-level task 1}
- [ ] {High-level task 2}
---
### Story {N}.{M+1}: {Story Title}
- **User Story / Goal:** {...}
- **Detailed Requirements:**
- {...}
- **Acceptance Criteria (ACs):**
- AC1: {...}
- AC2: {...}
- **Tasks (Optional Initial Breakdown):**
- [ ] {...}
---
{... Add more stories ...}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------------------------ | -------------- |

345
BETA-V3/gems-and-gpts/templates/front-end-architecture.md Normal file
View File

@@ -0,0 +1,345 @@
# {Project Name} Frontend Architecture Document
## Table of Contents
{ Update this if sections and subsections are added or removed }
- [Introduction](#introduction)
- [Overall Frontend Philosophy & Patterns](#overall-frontend-philosophy--patterns)
- [Detailed Frontend Directory Structure](#detailed-frontend-directory-structure)
- [Component Breakdown & Implementation Details](#component-breakdown--implementation-details)
- [Component Naming & Organization](#component-naming--organization)
- [Template for Component Specification](#template-for-component-specification)
- [State Management In-Depth](#state-management-in-depth)
- [Store Structure / Slices](#store-structure--slices)
- [Key Selectors](#key-selectors)
- [Key Actions / Reducers / Thunks](#key-actions--reducers--thunks)
- [API Interaction Layer](#api-interaction-layer)
- [Client/Service Structure](#clientservice-structure)
- [Error Handling & Retries (Frontend)](#error-handling--retries-frontend)
- [Routing Strategy](#routing-strategy)
- [Route Definitions](#route-definitions)
- [Route Guards / Protection](#route-guards--protection)
- [Build, Bundling, and Deployment](#build-bundling-and-deployment)
- [Build Process & Scripts](#build-process--scripts)
- [Key Bundling Optimizations](#key-bundling-optimizations)
- [Deployment to CDN/Hosting](#deployment-to-cdnhosting)
- [Frontend Testing Strategy](#frontend-testing-strategy)
- [Component Testing](#component-testing)
- [UI Integration/Flow Testing](#ui-integrationflow-testing)
- [End-to-End UI Testing Tools & Scope](#end-to-end-ui-testing-tools--scope)
- [Accessibility (AX) Implementation Details](#accessibility-ax-implementation-details)
- [Performance Considerations](#performance-considerations)
- [Change Log](#change-log)
## Introduction
{ This document details the technical architecture specifically for the frontend of {Project Name}. It complements the main {Project Name} Architecture Document and the UI/UX Specification. The goal is to provide a clear blueprint for frontend development, ensuring consistency, maintainability, and alignment with the overall system design and user experience goals. }
- **Link to Main Architecture Document:** {e.g., `docs/architecture.md`}
- **Link to UI/UX Specification:** {e.g., `docs/ui-ux-spec.md`}
- **Link to Primary Design Files (Figma, Sketch, etc.):** {From UI/UX Spec}
- **Link to Deployed Storybook / Component Showcase (if applicable):** {URL}
## Overall Frontend Philosophy & Patterns
{ Describe the core architectural decisions and patterns chosen for the frontend. This should align with the "Definitive Tech Stack Selections" in the main architecture document. }
- **Framework & Core Libraries:** {e.g., React 18.x with Next.js 13.x, Angular 16.x, Vue 3.x with Nuxt.js. Briefly reiterate why these were chosen if not detailed enough in the main arch doc.}
- **Component Architecture:** {e.g., Atomic Design principles, Presentational vs. Container components, use of specific component libraries like Material UI, Tailwind CSS for styling approach.}
- **State Management Strategy:** {e.g., Redux Toolkit, Zustand, Vuex, NgRx. Briefly describe the overall approach – global store, feature stores, context API usage. More details in "State Management In-Depth" section.}
- **Data Flow:** {e.g., Unidirectional data flow, how data is fetched, passed to components, and updated.}
- **Styling Approach:** {e.g., CSS Modules, Styled Components, SCSS with BEM, Tailwind CSS. Link to configuration if applicable.}
- **Key Design Patterns Used:** {e.g., Provider pattern, Hooks, Higher-Order Components, Service patterns for API calls.}
## Detailed Frontend Directory Structure
{ Provide an ASCII diagram representing the frontend application\'s specific folder structure (e.g., within `src/` or `app/`). This should elaborate on the frontend part of the main project structure outlined in the architecture document. Highlight conventions for organizing components, pages/views, services, state, styles, assets, etc. }
### EXAMPLE - Not Prescriptive (for a React/Next.js app)
```plaintext
src/
├── app/ # Next.js App Router: Pages/Layouts/Routes
│ ├── (features)/ # Feature-based routing groups
│ │ └── dashboard/
│ │ ├── layout.tsx
│ │ └── page.tsx
│ ├── api/ # API Routes (if using Next.js backend features)
│ ├── globals.css
│ └── layout.tsx # Root layout
├── components/ # Shared/Reusable UI Components
│ ├── ui/ # Base UI elements (Button, Input, Card - often from a library)
│ │ ├── Button.tsx
│ │ └── ...
│ ├── layout/ # Layout components (Header, Footer, Sidebar)
│ │ ├── Header.tsx
│ │ └── ...
│ └── (feature-specific)/ # Components specific to a feature but potentially reusable within it
│ └── user-profile/
│ └── ProfileCard.tsx
├── features/ # Feature-specific logic, hooks, non-global state, services
│ └── auth/
│ ├── components/ # Components used only by the auth feature
│ ├── hooks/ # Feature-specific hooks
│ ├── services/ # Feature-specific API interactions
│ └── store.ts # Feature-specific state slice (if applicable)
├── hooks/ # Global/sharable custom hooks
│ └── useAuth.ts
├── lib/ # Utility functions, helpers, constants
│ └── utils.ts
├── services/ # Global API service clients or SDK configurations
│ └── apiClient.ts
├── store/ # Global state management (e.g., Redux store setup)
│ ├── index.ts
│ ├── rootReducer.ts
│ └── (slices)/
├── styles/ # Global styles, theme configurations (if not using `globals.css` or similar)
└── types/ # Global TypeScript type definitions
└── index.ts
```
### Notes on Frontend Structure:
{ Explain any specific conventions or rationale behind the structure. For example, "Components are co-located with their feature if not globally reusable." }
## Component Breakdown & Implementation Details
{ This section outlines the conventions and templates for defining UI components. While a few globally shared or foundational components (e.g., core UI elements if not from a library, main layout structures) might be specified here upfront to ensure consistency, the detailed specification for most feature-specific components will emerge as user stories are implemented. The key is for the development team (or AI agent) to follow the "Template for Component Specification" below whenever a new component is identified for development. }
### Component Naming & Organization
{ Briefly describe conventions for naming components (e.g., PascalCase, `feature-ComponentName.tsx`). How are components organized on the filesystem (reiterate from directory structure if needed)? Are components grouped by feature, type (UI, layout), etc.? }
### Template for Component Specification
{ For each significant UI component identified from the UI/UX Specification and design files (Figma), provide the following details. Repeat this subsection for each component. The level of detail should be sufficient for an AI agent or developer to implement it with minimal ambiguity. }
#### Component: `{ComponentName}` (e.g., `UserProfileCard`, `ProductDetailsView`)
- **Purpose:** {Briefly describe what this component does and its role in the UI.}
- **Source File(s):** {e.g., `src/components/user-profile/UserProfileCard.tsx`}
- **Visual Reference:** {Link to specific Figma frame/component, or Storybook page.}
- **Props (Properties):**
{ List each prop the component accepts. }
| Prop Name | Type | Required? | Default Value | Description |
| :-------------- | :--------------------------- | :-------- | :------------ | :---------------------------------------------- |
| `userId` | `string` | Yes | N/A | The ID of the user to display. |
| `avatarUrl` | `string` | No | `null` | URL for the user\'s avatar image. |
| `onEdit` | `() => void` | No | N/A | Callback function when an edit action is triggered. |
| `variant` | `\'compact\' \| \'full\'` | No | `\'full\'` | Controls the display mode of the card. |
| `{anotherProp}` | `{type (e.g., number, boolean, customType)}` | {Yes/No} | {If any} | {Description} |
- **Internal State (if any):**
{ Describe any significant internal state the component manages. Minor UI state (e.g., `isDropdownOpen`) might not need explicit listing unless complex. }
| State Variable | Type | Initial Value | Description |
| :-------------- | :--------- | :------------ | :-------------------------------------------- |
| `isLoading` | `boolean` | `false` | Tracks if data for the component is loading. |
| `{anotherState}`| `{type}` | `{value}` | {Description} |
- **Key UI Elements / Structure:**
{ Describe the main visual parts of the component and their general layout. This can be a brief textual description or a very simple pseudo-HTML structure. }
```html
<div> <!-- Main card container -->
<img> <!-- Avatar -->
<h2> <!-- User Name -->
<p> <!-- User Email -->
<button> <!-- Edit Button (if applicable) -->
</div>
```
- **Events Handled / Emitted:**
- **Handles:** {e.g., `onClick` on the edit button.}
- **Emits:** {If the component emits custom events, describe them. e.g., `onFollow: (userId: string) => void`}
- **Actions Triggered (Side Effects):**
- **State Management:** {e.g., "Dispatches `fetchUserDetails(userId)` action on mount." "Calls `userSlice.actions.setUserName(newName)`."}
- **API Calls:** {Specify which service/function from the "API Interaction Layer" is called. e.g., "Calls `userService.fetchUser(userId)`." What data is passed? How is the response (success/error) handled? How does it update internal state or global state?}
- **Styling Notes:**
- {Reference to Design System components used (e.g., "Uses `<Button variant=\'primary\'>` from UI library").}
- {Key CSS classes to be applied (if using traditional CSS/SCSS/Tailwind directly).}
- {Specific responsiveness behavior if not covered globally.}
- **Accessibility Notes:**
- {Specific ARIA attributes needed (e.g., `aria-label`, `role`).}
- {Keyboard navigation considerations for this component.}
---
_Repeat the above template for each significant component._
---
## State Management In-Depth
{ This section expands on the State Management strategy chosen and outlined in the main architecture document and the "Overall Frontend Philosophy". It defines the conventions for how state modules should be structured and implemented. While the overall approach and core store setup (if any) are defined here, detailed state slices, selectors, and actions/thunks for specific features will generally be developed emergently as those features are built, adhering to these established patterns. }
- **Chosen Solution:** {e.g., Redux Toolkit, Zustand, Vuex, NgRx - reiterate from main arch doc.}
- **Rationale (briefly, if not fully covered in main arch doc):** {Why was this solution chosen over alternatives for this specific project?}
### Store Structure / Slices
{ Describe the conventions for organizing the global state (e.g., "Each major feature requiring global state will have its own Redux slice located in `src/features/[featureName]/store.ts`"). A few core, application-wide slices (e.g., for session management, theme) might be defined upfront as examples or foundational pieces. }
- **Core Slice Example (e.g., `sessionSlice`):**
- **Purpose:** {Manages user session, authentication status, and basic user profile info accessible globally.}
- **State Shape:**
```typescript
interface SessionState {
currentUser: {
id: string;
name: string;
email: string;
roles: string[];
} | null;
isAuthenticated: boolean;
token: string | null;
status: "idle" | "loading" | "succeeded" | "failed";
error: string | null;
}
```
- **Key Reducers/Actions:** {Briefly list main actions, e.g., `setSession`, `clearSession`, `authLoading`, `authSuccess`, `authFailure`.}
- **Feature Slice Template (e.g., `{featureName}Slice`):**
- **Purpose:** {To be filled out when a new feature requires its own state slice.}
- **State Shape:** {To be defined by the feature.}
- **Key Reducers/Actions:** {To be defined by the feature.}
### Key Selectors
{ List important selectors for any core, upfront slices. For emergent feature slices, selectors will be defined with the slice. Conventions for creating selectors should be noted (e.g., use `createSelector` for memoization). }
- **`selectCurrentUser`:** {Returns the `currentUser` object from `sessionSlice`.}
- **`selectIsAuthenticated`:** {Returns `isAuthenticated` boolean from `sessionSlice`.}
- **`selectAuthToken`:** {Returns the `token` from `sessionSlice`.}
### Key Actions / Reducers / Thunks
{ Detail more complex actions for core, upfront slices, especially asynchronous thunks or sagas. For emergent feature slices, these will be defined with the slice, following these patterns. }
- **Core Action/Thunk Example: `authenticateUser(credentials: AuthCredentials)`**
- **Purpose:** {Handles user login by calling the auth API and updating the `sessionSlice`.}
- **Dispatch Flow:**
1. Dispatches `sessionSlice.actions.setStatus('loading')`.
2. Calls `authService.login(credentials)` (from API Interaction Layer).
3. On success: Dispatches `sessionSlice.actions.setSession(response.data)` (which includes user and token) and `sessionSlice.actions.setStatus('succeeded')`.
4. On error: Dispatches `sessionSlice.actions.setError(error.message)` and `sessionSlice.actions.setStatus('failed')`.
- **Feature Action/Thunk Template: `{featureActionName}`**
- **Purpose:** {To be filled out for feature-specific async operations.}
- **Dispatch Flow:** {To be defined by the feature, following similar patterns.}
## API Interaction Layer
{ Describe how the frontend communicates with the backend APIs defined in the main Architecture Document. The focus here is on establishing the foundational client setup and patterns for creating service abstractions. Specific service functions will often emerge as features are developed. }
### Client/Service Structure
- **HTTP Client Setup:** {e.g., Axios instance, Fetch wrapper. Base URL configuration, default headers (e.g., for Authorization from state), interceptors for request/response handling (e.g., error normalization, token refresh).}
- **Service Definitions (Example):**
- **`userService.ts`:**
- **Purpose:** {Handles all API interactions related to users.}
- **Functions:**
- `fetchUser(userId: string): Promise<User>`
- `updateUserProfile(userId: string, data: UserProfileUpdateDto): Promise<User>`
- **`productService.ts`:**
- **Purpose:** {...}
- **Functions:** {...}
### Error Handling & Retries (Frontend)
- **Global Error Handling:** {How are API errors caught and presented to the user globally (e.g., toast notifications)? Is there a global error state?}
- **Specific Error Handling:** {How might components handle specific API errors for more contextual feedback?}
- **Retry Logic:** {Is there any client-side retry logic for idempotent requests? If so, how is it configured?}
## Routing Strategy
{ Detail how navigation and routing are handled in the frontend application. }
- **Routing Library:** {e.g., React Router, Next.js App Router, Vue Router, Angular Router.}
### Route Definitions
{ List the main routes of the application and the primary component rendered for each. }
| Path Pattern | Component/Page | Protection | Notes |
| :--------------------- | :---------------------------- | :------------ | :---------------------------------- |
| `/` | `HomePage.tsx` | Public | |
| `/login` | `LoginPage.tsx` | Public | Redirects if already authenticated. |
| `/dashboard` | `DashboardPage.tsx` | Authenticated | |
| `/products` | `ProductListPage.tsx` | Public | |
| `/products/:productId` | `ProductDetailsPage.tsx` | Public | |
| `/settings/profile` | `UserProfileSettingsPage.tsx` | Authenticated | |
| `{anotherRoute}` | `{Component}` | {Type} | {Notes} |
### Route Guards / Protection
- **Authentication Guard:** {Describe how routes are protected based on authentication status. e.g., A Higher-Order Component, a specific router hook.}
- **Authorization Guard (if applicable):** {Describe how routes might be protected based on user roles or permissions.}
## Build, Bundling, and Deployment
{ Details specific to the frontend build and deployment process, complementing the "Infrastructure and Deployment Overview" in the main architecture document. }
### Build Process & Scripts
- **Key Build Scripts:** {e.g., `npm run build`, `yarn build`. What do they do? Point to `package.json` scripts.}
- **Environment Variables Handling during Build:** {How are `process.env` variables (e.g., `NEXT_PUBLIC_API_URL`) managed for different environments (dev, staging, prod)?}
### Key Bundling Optimizations
- **Code Splitting:** {How is it implemented? e.g., Route-based, component-based using dynamic imports.}
- **Tree Shaking:** {Ensured by build tools?}
- **Lazy Loading:** {Strategy for lazy loading components, images, or routes.}
- **Minification & Compression:** {Handled by build tools (e.g., Webpack, Vite, Next.js build)?}
### Deployment to CDN/Hosting
- **Target Platform:** {e.g., Vercel, Netlify, AWS S3/CloudFront, Azure Static Web Apps.}
- **Deployment Trigger:** {e.g., Git push to main branch via GitHub Actions (referencing main CI/CD).}
- **Asset Caching Strategy:** {How are static assets cached by the CDN/browser?}
## Frontend Testing Strategy
{ This section elaborates on the "Testing Strategy" from the main architecture document, focusing on frontend-specific aspects. }
- **Link to Main Testing Strategy:** {Reference the main `docs/testing-strategy.md` or architecture doc section.}
### Component Testing
- **Scope:** {Testing individual UI components in isolation (similar to unit tests for components).}
- **Tools:** {e.g., React Testing Library, Jest, Vitest, Vue Test Utils, Angular Testing Utilities.}
- **Focus:** {Rendering, props handling, basic interactions, event emission, visual snapshot testing (optional).}
- **Location:** {e.g., `*.test.tsx` or `*.spec.tsx` alongside components.}
### UI Integration/Flow Testing
- **Scope:** {Testing how multiple components interact to fulfill a small user flow within a page or feature, potentially mocking API calls or state management.}
- **Tools:** {Same as component testing, but with more complex setups.}
- **Focus:** {Data flow between components, conditional rendering based on interactions, navigation within a feature.}
### End-to-End UI Testing Tools & Scope
- **Tools:** {Reiterate from main Testing Strategy, e.g., Playwright, Cypress, Selenium.}
- **Scope (Frontend Focus):** {Define key user journeys that will be covered by E2E UI tests. e.g., User registration, adding item to cart, completing checkout.}
- **Test Data Management for UI:** {How is consistent test data ensured for UI E2E tests?}
## Accessibility (AX) Implementation Details
{ Based on the AX requirements in the UI/UX Specification, detail how these will be technically implemented. }
- **Semantic HTML:** {Emphasis on using correct HTML5 elements.}
- **ARIA Implementation:** {Specific ARIA roles, states, and properties for custom/complex components.}
- **Keyboard Navigation:** {Ensuring all interactive elements are focusable and operable via keyboard.}
- **Focus Management:** {How is focus managed in modals, dynamic content changes?}
- **Testing Tools for AX:** {e.g., Axe DevTools, Lighthouse, manual testing procedures.}
## Performance Considerations
{ Highlight frontend-specific performance optimization strategies. }
- **Image Optimization:** {Formats (e.g., WebP), responsive images (`<picture>`, `srcset`), lazy loading.}
- **Code Splitting & Lazy Loading (reiterate from Build section if needed):** {How it impacts perceived performance.}
- **Minimizing Re-renders:** {Techniques like `React.memo`, `shouldComponentUpdate`, optimized selectors.}
- **Debouncing/Throttling:** {For event handlers like search input or window resize.}
- **Virtualization:** {For long lists or large data sets (e.g., React Virtualized, TanStack Virtual).}
- **Caching Strategies (Client-Side):** {Use of browser cache, service workers for PWA capabilities (if applicable).}
- **Performance Monitoring Tools:** {e.g., Lighthouse, WebPageTest, browser DevTools performance tab.}
## Change Log
| Change | Date | Version | Description | Author |
| ------ | ---- | ------- | ----------- | ------ |

108
BETA-V3/gems-and-gpts/templates/prd.txt
View File

@@ -12,7 +12,19 @@ You should have a good idea at this point, but clarify suggest question and expl
## User Interaction and Design Goals
If there is a UX/UI Component, we want to work with the user to elicit enough information to detail the UI look and feel, screens, interaction, functionality so that we can produce the UI as needed.
{
If the product includes a User Interface (UI), this section captures the Product Manager's high-level vision and goals for the User Experience (UX). This information will serve as a crucial starting point and brief for the Design Architect.
Consider and elicit information from the user regarding:
- **Overall Vision & Experience:** What is the desired look and feel (e.g., "modern and minimalist," "friendly and approachable," "data-intensive and professional")? What kind of experience should users have?
- **Key Interaction Paradigms:** Are there specific ways users will interact with core features (e.g., "drag-and-drop interface for X," "wizard-style setup for Y," "real-time dashboard for Z")?
- **Core Screens/Views (Conceptual):** From a product perspective, what are the most critical screens or views necessary to deliver the MVP's value? (e.g., "Login Screen," "Main Dashboard," "Item Detail Page," "Settings Page").
- **Accessibility Aspirations:** Any known high-level accessibility goals (e.g., "must be usable by screen reader users").
- **Branding Considerations (High-Level):** Any known branding elements or style guides that must be incorporated?
- **Target Devices/Platforms:** (e.g., "primarily web desktop," "mobile-first responsive web app").
This section is not intended to be a detailed UI specification but rather a product-focused brief to guide the subsequent detailed work by the Design Architect, who will create the comprehensive UI/UX Specification document.
}
## Technical Assumptions
@@ -22,7 +34,7 @@ This is where we can list information mostly to be used by the architect to prod
How will we validate functionality beyond unit testing? Will we want manual scripts or testing, e2e, integration etc... figure this out from the user to populate this section
## Epic Overview (MVP / Current Version)
## Epic Overview
- **Epic {#}: {Title}**
- Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.}
@@ -37,97 +49,9 @@ How will we validate functionality beyond unit testing? Will we want manual scri
- Story {#}: As a {type of user/system}, I want {to perform an action / achieve a goal} so that {I can realize a benefit / achieve a reason}.
- {Acceptance Criteria List}
--- OPTIONAL UI UX SECTION START ----
## UI/UX Specification
### Overall UX Goals & Principles
- **Target User Personas:** {Reference personas or briefly describe key user types and their goals.}
- **Usability Goals:** {e.g., Ease of learning, efficiency of use, error prevention.}
- **Design Principles:** {List 3-5 core principles guiding the UI/UX design - e.g., "Clarity over cleverness", "Consistency", "Provide feedback".}
### Information Architecture (IA)
- **Site Map / Screen Inventory:**
```mermaid
graph TD
A[Homepage] --> B(Dashboard);
A --> C{Settings};
B --> D[View Details];
C --> E[Profile Settings];
C --> F[Notification Settings];
```
_(Or provide a list of all screens/pages)_
- **Navigation Structure:** {Describe primary navigation (e.g., top bar, sidebar), secondary navigation, breadcrumbs, etc.}
### User Flows
{Detail key user tasks. Use diagrams or descriptions.}
#### {User Flow Name, e.g., User Login}
- **Goal:** {What the user wants to achieve.}
- **Steps / Diagram:**
```mermaid
graph TD
Start --> EnterCredentials[Enter Email/Password];
EnterCredentials --> ClickLogin[Click Login Button];
ClickLogin --> CheckAuth{Auth OK?};
CheckAuth -- Yes --> Dashboard;
CheckAuth -- No --> ShowError[Show Error Message];
ShowError --> EnterCredentials;
```
_(Or: Link to specific flow diagram in Figma/Miro)_
#### {Another User Flow Name}
{...}
### Wireframes & Mockups
{Reference the main design file link above. Optionally embed key mockups or describe main screen layouts.}
- **Screen / View Name 1:** {Description of layout and key elements. Link to specific Figma frame/page.}
- **Screen / View Name 2:** {...}
### Component Library / Design System Reference
{Link to the primary source (Storybook, Figma Library). If none exists, define key components here.}
#### {Component Name, e.g., Primary Button}
- **Appearance:** {Reference mockup or describe styles.}
- **States:** {Default, Hover, Active, Disabled, Loading.}
- **Behavior:** {Interaction details.}
#### {Another Component Name}
{...}
### Branding & Style Guide Reference
{Link to the primary source or define key elements here.}
- **Color Palette:** {Primary, Secondary, Accent, Feedback colors (hex codes).}
- **Typography:** {Font families, sizes, weights for headings, body, etc.}
- **Iconography:** {Link to icon set, usage notes.}
- **Spacing & Grid:** {Define margins, padding, grid system rules.}
### Accessibility (AX) Requirements
- **Target Compliance:** {e.g., WCAG 2.1 AA}
- **Specific Requirements:** {Keyboard navigation patterns, ARIA landmarks/attributes for complex components, color contrast minimums.}
### Responsiveness
- **Breakpoints:** {Define pixel values for mobile, tablet, desktop, etc.}
- **Adaptation Strategy:** {Describe how layout and components adapt across breakpoints. Reference designs.}
--- OPTIONAL UI UX SECTION END ----
## Key Reference Documents
{Will be populated at a later time}
{ This section will be created later, from the sections prior to this being carved up into smaller documents }
## Out of Scope Ideas Post MVP

87
BETA-V3/gems-and-gpts/templates/story-template.txt
View File

@@ -1,84 +1,31 @@
# Story {EpicNum}.{StoryNum}: {Short Title Copied from Epic File}
**Status:** Draft | In-Progress | Complete
## Status: { Draft | Approved | Done }
## Goal & Context
## Story
**User Story:** {As a [role], I want [action], so that [benefit] - Copied or derived from Epic file}
**Context:** {Briefly explain how this story fits into the Epic's goal and the overall workflow. Mention the previous story's outcome if relevant. Example: "This story builds upon the project setup (Story 1.1) by defining the S3 resource needed for state persistence..."}
## Detailed Requirements
{Copy the specific requirements/description for this story directly from the corresponding `docs/epicN.md` file.}
- As a [role]
- I want [action]
- so that [benefit]
## Acceptance Criteria (ACs)
{Copy the Acceptance Criteria for this story directly from the corresponding `docs/epicN.md` file.}
- AC1: ...
- AC2: ...
- ACN: ...
## Technical Implementation Context
**Guidance:** Use the following details for implementation. Refer to the linked `docs/` files for broader context if needed.
- **Relevant Files:**
- Files to Create: {e.g., `src/services/s3-service.ts`, `test/unit/services/s3-service.test.ts`}
- Files to Modify: {e.g., `lib/hacker-news-briefing-stack.ts`, `src/common/types.ts`}
- _(Hint: See `docs/project-structure.md` for overall layout)_
- **Key Technologies:**
- {e.g., TypeScript, Node.js 22.x, AWS CDK (`aws-s3` construct), AWS SDK v3 (`@aws-sdk/client-s3`), Jest}
- {If a UI story, mention specific frontend libraries/framework features (e.g., React Hooks, Vuex store, CSS Modules)}
- _(Hint: See `docs/tech-stack.md` for full list)_
- **API Interactions / SDK Usage:**
- {e.g., "Use `@aws-sdk/client-s3`: `S3Client`, `GetObjectCommand`, `PutObjectCommand`.", "Handle `NoSuchKey` error specifically for `GetObjectCommand`."}
- _(Hint: See `docs/api-reference.md` for details on external APIs and SDKs)_
- **UI/UX Notes:** ONLY IF THIS IS A UI Focused Epic or Story
- **Data Structures:**
- {e.g., "Define/Use `AppState` interface in `src/common/types.ts`: `{ processedStoryIds: string[] }`.", "Handle JSON parsing/stringifying for state."}
- _(Hint: See `docs/data-models.md` for key project data structures)_
- **Environment Variables:**
- {e.g., `S3_BUCKET_NAME` (Read via `config.ts` or passed to CDK)}
- _(Hint: See `docs/environment-vars.md` for all variables)_
- **Coding Standards Notes:**
- {e.g., "Use `async/await` for all S3 calls.", "Implement error logging using `console.error`.", "Follow `kebab-case` for filenames, `PascalCase` for interfaces."}
- _(Hint: See `docs/coding-standards.md` for full standards)_
{ Copy the Acceptance Criteria numbered list }
## Tasks / Subtasks
{Copy the initial task breakdown from the corresponding `docs/epicN.md` file and expand or clarify as needed to ensure the agent can complete all AC. The agent can check these off as it proceeds.}
- [ ] Task 1 (AC: # if applicable)
- [ ] Subtask1.1...
- [ ] Task 2 (AC: # if applicable)
- [ ] Subtask 2.1...
- [ ] Task 3 (AC: # if applicable)
- [ ] Subtask 3.1...
- [ ] Task 1
- [ ] Task 2
- [ ] Subtask 2.1
- [ ] Task 3
## Story Progress Notes
## Testing Requirements
### Agent Model Used: `<Agent Model Name/Version>`
**Guidance:** Verify implementation against the ACs using the following tests.
### Completion Notes List
{Any notes about implementation choices, difficulties, or follow-up needed}
- **Unit Tests:** {e.g., "Write unit tests for `src/services/s3-service.ts`. Mock `S3Client` and its commands (`GetObjectCommand`, `PutObjectCommand`). Test successful read/write, JSON parsing/stringifying, and `NoSuchKey` error handling."}
- **Integration Tests:** {e.g., "No specific integration tests required for _just_ this story's module, but it will be covered later in `test/integration/fetch-flow.test.ts`."}
- **Manual/CLI Verification:** {e.g., "Not applicable directly, but functionality tested via `npm run fetch-stories` later."}
- _(Hint: See `docs/testing-strategy.md` for the overall approach)_
## Story Wrap Up (Agent Populates After Execution)
- **Agent Model Used:** `<Agent Model Name/Version>`
- **Completion Notes:** {Any notes about implementation choices, difficulties, or follow-up needed}
- **Change Log:** {Track changes _within this specific story file_ if iterations occur}
- Initial Draft
- ...
### Change Log

12
BETA-V3/gems-and-gpts/templates/ui-ux-spec.txt
View File

@@ -59,18 +59,6 @@
## Component Library / Design System Reference
{Link to the primary source (Storybook, Figma Library). If none exists, define key components here.}
### {Component Name, e.g., Primary Button}
- **Appearance:** {Reference mockup or describe styles.}
- **States:** {Default, Hover, Active, Disabled, Loading.}
- **Behavior:** {Interaction details.}
### {Another Component Name}
{...}
## Branding & Style Guide Reference
{Link to the primary source or define key elements here.}