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

analyst and pm

Browse Source
This commit is contained in:
Brian Madison
2025-05-11 12:28:41 -05:00
parent 4b149f6d17
commit 13c752e3b1
40 changed files with 5396 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
BETA-V3/docs/templates/api-reference.md vendored Normal file
View File

@@ -0,0 +1,71 @@
# {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} |
| ... | ... | ... | ... | ... |

259
BETA-V3/docs/templates/architect-checklist.md vendored Normal file
View File

@@ -0,0 +1,259 @@
# Architect Solution Validation Checklist
This checklist serves as a comprehensive framework for the Architect to validate the technical design and architecture before development execution. The Architect should systematically work through each item, ensuring the architecture is robust, scalable, secure, and aligned with the product requirements.
## 1. REQUIREMENTS ALIGNMENT
### 1.1 Functional Requirements Coverage
- [ ] Architecture supports all functional requirements in the PRD
- [ ] Technical approaches for all epics and stories are addressed
- [ ] Edge cases and performance scenarios are considered
- [ ] All required integrations are accounted for
- [ ] User journeys are supported by the technical architecture
### 1.2 Non-Functional Requirements Alignment
- [ ] Performance requirements are addressed with specific solutions
- [ ] Scalability considerations are documented with approach
- [ ] Security requirements have corresponding technical controls
- [ ] Reliability and resilience approaches are defined
- [ ] Compliance requirements have technical implementations
### 1.3 Technical Constraints Adherence
- [ ] All technical constraints from PRD are satisfied
- [ ] Platform/language requirements are followed
- [ ] Infrastructure constraints are accommodated
- [ ] Third-party service constraints are addressed
- [ ] Organizational technical standards are followed
## 2. ARCHITECTURE FUNDAMENTALS
### 2.1 Architecture Clarity
- [ ] Architecture is documented with clear diagrams
- [ ] Major components and their responsibilities are defined
- [ ] Component interactions and dependencies are mapped
- [ ] Data flows are clearly illustrated
- [ ] Technology choices for each component are specified
### 2.2 Separation of Concerns
- [ ] Clear boundaries between UI, business logic, and data layers
- [ ] Responsibilities are cleanly divided between components
- [ ] Interfaces between components are well-defined
- [ ] Components adhere to single responsibility principle
- [ ] Cross-cutting concerns (logging, auth, etc.) are properly addressed
### 2.3 Design Patterns & Best Practices
- [ ] Appropriate design patterns are employed
- [ ] Industry best practices are followed
- [ ] Anti-patterns are avoided
- [ ] Consistent architectural style throughout
- [ ] Pattern usage is documented and explained
### 2.4 Modularity & Maintainability
- [ ] System is divided into cohesive, loosely-coupled modules
- [ ] Components can be developed and tested independently
- [ ] Changes can be localized to specific components
- [ ] Code organization promotes discoverability
- [ ] Architecture specifically designed for AI agent implementation
## 3. TECHNICAL STACK & DECISIONS
### 3.1 Technology Selection
- [ ] Selected technologies meet all requirements
- [ ] Technology versions are specifically defined (not ranges)
- [ ] Technology choices are justified with clear rationale
- [ ] Alternatives considered are documented with pros/cons
- [ ] Selected stack components work well together
### 3.2 Frontend Architecture
- [ ] UI framework and libraries are specifically selected
- [ ] State management approach is defined
- [ ] Component structure and organization is specified
- [ ] Responsive/adaptive design approach is outlined
- [ ] Build and bundling strategy is determined
### 3.3 Backend Architecture
- [ ] API design and standards are defined
- [ ] Service organization and boundaries are clear
- [ ] Authentication and authorization approach is specified
- [ ] Error handling strategy is outlined
- [ ] Backend scaling approach is defined
### 3.4 Data Architecture
- [ ] Data models are fully defined
- [ ] Database technologies are selected with justification
- [ ] Data access patterns are documented
- [ ] Data migration/seeding approach is specified
- [ ] Data backup and recovery strategies are outlined
## 4. RESILIENCE & OPERATIONAL READINESS
### 4.1 Error Handling & Resilience
- [ ] Error handling strategy is comprehensive
- [ ] Retry policies are defined where appropriate
- [ ] Circuit breakers or fallbacks are specified for critical services
- [ ] Graceful degradation approaches are defined
- [ ] System can recover from partial failures
### 4.2 Monitoring & Observability
- [ ] Logging strategy is defined
- [ ] Monitoring approach is specified
- [ ] Key metrics for system health are identified
- [ ] Alerting thresholds and strategies are outlined
- [ ] Debugging and troubleshooting capabilities are built in
### 4.3 Performance & Scaling
- [ ] Performance bottlenecks are identified and addressed
- [ ] Caching strategy is defined where appropriate
- [ ] Load balancing approach is specified
- [ ] Horizontal and vertical scaling strategies are outlined
- [ ] Resource sizing recommendations are provided
### 4.4 Deployment & DevOps
- [ ] Deployment strategy is defined
- [ ] CI/CD pipeline approach is outlined
- [ ] Environment strategy (dev, staging, prod) is specified
- [ ] Infrastructure as Code approach is defined
- [ ] Rollback and recovery procedures are outlined
## 5. SECURITY & COMPLIANCE
### 5.1 Authentication & Authorization
- [ ] Authentication mechanism is clearly defined
- [ ] Authorization model is specified
- [ ] Role-based access control is outlined if required
- [ ] Session management approach is defined
- [ ] Credential management is addressed
### 5.2 Data Security
- [ ] Data encryption approach (at rest and in transit) is specified
- [ ] Sensitive data handling procedures are defined
- [ ] Data retention and purging policies are outlined
- [ ] Backup encryption is addressed if required
- [ ] Data access audit trails are specified if required
### 5.3 API & Service Security
- [ ] API security controls are defined
- [ ] Rate limiting and throttling approaches are specified
- [ ] Input validation strategy is outlined
- [ ] CSRF/XSS prevention measures are addressed
- [ ] Secure communication protocols are specified
### 5.4 Infrastructure Security
- [ ] Network security design is outlined
- [ ] Firewall and security group configurations are specified
- [ ] Service isolation approach is defined
- [ ] Least privilege principle is applied
- [ ] Security monitoring strategy is outlined
## 6. IMPLEMENTATION GUIDANCE
### 6.1 Coding Standards & Practices
- [ ] Coding standards are defined
- [ ] Documentation requirements are specified
- [ ] Testing expectations are outlined
- [ ] Code organization principles are defined
- [ ] Naming conventions are specified
### 6.2 Testing Strategy
- [ ] Unit testing approach is defined
- [ ] Integration testing strategy is outlined
- [ ] E2E testing approach is specified
- [ ] Performance testing requirements are outlined
- [ ] Security testing approach is defined
### 6.3 Development Environment
- [ ] Local development environment setup is documented
- [ ] Required tools and configurations are specified
- [ ] Development workflows are outlined
- [ ] Source control practices are defined
- [ ] Dependency management approach is specified
### 6.4 Technical Documentation
- [ ] API documentation standards are defined
- [ ] Architecture documentation requirements are specified
- [ ] Code documentation expectations are outlined
- [ ] System diagrams and visualizations are included
- [ ] Decision records for key choices are included
## 7. DEPENDENCY & INTEGRATION MANAGEMENT
### 7.1 External Dependencies
- [ ] All external dependencies are identified
- [ ] Versioning strategy for dependencies is defined
- [ ] Fallback approaches for critical dependencies are specified
- [ ] Licensing implications are addressed
- [ ] Update and patching strategy is outlined
### 7.2 Internal Dependencies
- [ ] Component dependencies are clearly mapped
- [ ] Build order dependencies are addressed
- [ ] Shared services and utilities are identified
- [ ] Circular dependencies are eliminated
- [ ] Versioning strategy for internal components is defined
### 7.3 Third-Party Integrations
- [ ] All third-party integrations are identified
- [ ] Integration approaches are defined
- [ ] Authentication with third parties is addressed
- [ ] Error handling for integration failures is specified
- [ ] Rate limits and quotas are considered
## 8. AI AGENT IMPLEMENTATION SUITABILITY
### 8.1 Modularity for AI Agents
- [ ] Components are sized appropriately for AI agent implementation
- [ ] Dependencies between components are minimized
- [ ] Clear interfaces between components are defined
- [ ] Components have singular, well-defined responsibilities
- [ ] File and code organization optimized for AI agent understanding
### 8.2 Clarity & Predictability
- [ ] Patterns are consistent and predictable
- [ ] Complex logic is broken down into simpler steps
- [ ] Architecture avoids overly clever or obscure approaches
- [ ] Examples are provided for unfamiliar patterns
- [ ] Component responsibilities are explicit and clear
### 8.3 Implementation Guidance
- [ ] Detailed implementation guidance is provided
- [ ] Code structure templates are defined
- [ ] Specific implementation patterns are documented
- [ ] Common pitfalls are identified with solutions
- [ ] References to similar implementations are provided when helpful
### 8.4 Error Prevention & Handling
- [ ] Design reduces opportunities for implementation errors
- [ ] Validation and error checking approaches are defined
- [ ] Self-healing mechanisms are incorporated where possible
- [ ] Testing patterns are clearly defined
- [ ] Debugging guidance is provided

69
BETA-V3/docs/templates/architecture.md vendored Normal file
View File

@@ -0,0 +1,69 @@
# {Project Name} Architecture Document
## 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.}
## 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.}
```mermaid
{Insert high-level system context or interaction diagram here - e.g., using Mermaid graph TD or C4 Model Context Diagram}
```
## 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}
```
- 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
{List significant architectural choices and the patterns employed.}
- 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)
## Core Workflow / Sequence Diagrams (Optional)
{Illustrate key or complex workflows using sequence diagrams if helpful.}
## 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} |
| ... | ... | ... | ... | ... |

56
BETA-V3/docs/templates/coding-standards.md vendored Normal file
View File

@@ -0,0 +1,56 @@
# {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 2:** {e.g., Dependency Injection, Repository Pattern, Module Pattern} - _Rationale/Reference:_ {...}
- **Pattern N:** {...}
## Coding Standards (Consider adding these to Dev Agent Context or Rules)
- **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.}
## Error Handling Strategy
- **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.}
## 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...}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |

101
BETA-V3/docs/templates/data-models.md vendored Normal file
View File

@@ -0,0 +1,101 @@
# {Project Name} Data Models
## 2. 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}
- **Description:** {What does this entity represent?}
- **Schema / Interface Definition:**
```typescript
// Example using TypeScript Interface
export interface {EntityName} {
id: string; // {Description, e.g., Unique identifier}
propertyName: string; // {Description}
optionalProperty?: number; // {Description}
// ... other properties
}
```
_(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}
{...}
## 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`.}
### {API Endpoint / Purpose, e.g., Create Order Request}
- **Schema / Interface Definition:**
```typescript
// Example
export interface CreateOrderRequest {
customerId: string;
items: { productId: string; quantity: number }[];
// ...
}
```
### {Another API Payload}
{...}
## Database Schemas (If applicable)
{If using a database, define table structures or document database schemas.}
### {Table / Collection Name}
- **Purpose:** {What data does this table store?}
- **Schema Definition:**
```sql
-- Example SQL
CREATE TABLE {TableName} (
id VARCHAR(36) PRIMARY KEY,
column_name VARCHAR(255) NOT NULL,
numeric_column DECIMAL(10, 2),
-- ... other columns, indexes, constraints
);
```
_(Alternatively, use ORM model definitions, NoSQL document structure, etc.)_
### {Another Table / Collection Name}
{...}
## State File Schemas (If applicable)
{If the application uses files for persisting state.}
### {State File Name / Purpose, e.g., processed_items.json}
- **Purpose:** {What state does this file track?}
- **Format:** {e.g., JSON}
- **Schema Definition:**
```json
{
"type": "object",
"properties": {
"processedIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of IDs that have been processed."
}
// ... other state properties
},
"required": ["processedIds"]
}
```
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |

1
BETA-V3/docs/templates/deep-research-report-BA.md vendored Normal file
View File

@@ -0,0 +1 @@
{replace with relevant report}

1
BETA-V3/docs/templates/deep-research-report-architecture.md vendored Normal file
View File

@@ -0,0 +1 @@
{replace with relevant report}

1
BETA-V3/docs/templates/deep-research-report-prd.md vendored Normal file
View File

@@ -0,0 +1 @@
{replace with relevant report}

36
BETA-V3/docs/templates/environment-vars.md vendored Normal file
View File

@@ -0,0 +1,36 @@
# {Project Name} Environment Variables
## 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} |
| ... | ... | ... | ... | ... |
## 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} |
| ... | ... | ... | ... | ... |

63
BETA-V3/docs/templates/epicN.md vendored Normal file
View File

@@ -0,0 +1,63 @@
# Epic {N}: {Epic Title}
**Goal:** {State the overall goal this epic aims to achieve, linking back to the PRD goals.}
**Deployability:** {Explain how this epic builds on previous epics and what makes it independently deployable. For Epic 1, describe how it establishes the foundation for future epics.}
## Epic-Specific Technical Context
{For Epic 1, include necessary setup requirements such as project scaffolding, infrastructure setup, third-party accounts, or other prerequisites. For subsequent epics, describe any new technical components being introduced and how they build upon the foundation established in earlier epics.}
## Local Testability & Command-Line Access
{If the user has indicated this is important, describe how the functionality in this epic can be tested locally and/or through command-line tools. Include:}
- **Local Development:** {How can developers run and test this functionality in their local environment?}
- **Command-Line Testing:** {What utility scripts or commands should be provided for testing the functionality?}
- **Environment Testing:** {How can the functionality be tested across different environments (local, dev, staging, production)?}
- **Testing Prerequisites:** {What needs to be set up or available to enable effective testing?}
{If this section is not applicable based on user preferences, you may remove it.}
## 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}
- **Dependencies:** {List any dependencies on other stories or epics. Note if this story builds on functionality from previous epics.}
---
### Story {N}.{M+1}: {Story Title}
- **User Story / Goal:** {...}
- **Detailed Requirements:**
- {...}
- **Acceptance Criteria (ACs):**
- AC1: {...}
- AC2: {...}
- **Tasks (Optional Initial Breakdown):**
- [ ] {...}
- **Dependencies:** {List dependencies, if any}
---
{... Add more stories ...}
## Change Log
| Change | Date | Version | Description | Author |
| ------ | ---- | ------- | ----------- | ------ |

266
BETA-V3/docs/templates/pm-checklist.md vendored Normal file
View File

@@ -0,0 +1,266 @@
# Product Manager (PM) Requirements Checklist
This checklist serves as a comprehensive framework to ensure the Product Requirements Document (PRD) and Epic definitions are complete, well-structured, and appropriately scoped for MVP development. The PM should systematically work through each item during the product definition process.
## 1. PROBLEM DEFINITION & CONTEXT
### 1.1 Problem Statement
- [ ] Clear articulation of the problem being solved
- [ ] Identification of who experiences the problem
- [ ] Explanation of why solving this problem matters
- [ ] Quantification of problem impact (if possible)
- [ ] Differentiation from existing solutions
### 1.2 Business Goals & Success Metrics
- [ ] Specific, measurable business objectives defined
- [ ] Clear success metrics and KPIs established
- [ ] Metrics are tied to user and business value
- [ ] Baseline measurements identified (if applicable)
- [ ] Timeframe for achieving goals specified
### 1.3 User Research & Insights
- [ ] Target user personas clearly defined
- [ ] User needs and pain points documented
- [ ] User research findings summarized (if available)
- [ ] Competitive analysis included
- [ ] Market context provided
## 2. MVP SCOPE DEFINITION
### 2.1 Core Functionality
- [ ] Essential features clearly distinguished from nice-to-haves
- [ ] Features directly address defined problem statement
- [ ] Each feature ties back to specific user needs
- [ ] Features are described from user perspective
- [ ] Minimum requirements for success defined
### 2.2 Scope Boundaries
- [ ] Clear articulation of what is OUT of scope
- [ ] Future enhancements section included
- [ ] Rationale for scope decisions documented
- [ ] MVP minimizes functionality while maximizing learning
- [ ] Scope has been reviewed and refined multiple times
### 2.3 MVP Validation Approach
- [ ] Method for testing MVP success defined
- [ ] Initial user feedback mechanisms planned
- [ ] Criteria for moving beyond MVP specified
- [ ] Learning goals for MVP articulated
- [ ] Timeline expectations set
## 3. USER EXPERIENCE REQUIREMENTS
### 3.1 User Journeys & Flows
- [ ] Primary user flows documented
- [ ] Entry and exit points for each flow identified
- [ ] Decision points and branches mapped
- [ ] Critical path highlighted
- [ ] Edge cases considered
### 3.2 Usability Requirements
- [ ] Accessibility considerations documented
- [ ] Platform/device compatibility specified
- [ ] Performance expectations from user perspective defined
- [ ] Error handling and recovery approaches outlined
- [ ] User feedback mechanisms identified
### 3.3 UI Requirements
- [ ] Information architecture outlined
- [ ] Critical UI components identified
- [ ] Visual design guidelines referenced (if applicable)
- [ ] Content requirements specified
- [ ] High-level navigation structure defined
## 4. FUNCTIONAL REQUIREMENTS
### 4.1 Feature Completeness
- [ ] All required features for MVP documented
- [ ] Features have clear, user-focused descriptions
- [ ] Feature priority/criticality indicated
- [ ] Requirements are testable and verifiable
- [ ] Dependencies between features identified
### 4.2 Requirements Quality
- [ ] Requirements are specific and unambiguous
- [ ] Requirements focus on WHAT not HOW
- [ ] Requirements use consistent terminology
- [ ] Complex requirements broken into simpler parts
- [ ] Technical jargon minimized or explained
### 4.3 User Stories & Acceptance Criteria
- [ ] Stories follow consistent format
- [ ] Acceptance criteria are testable
- [ ] Stories are sized appropriately (not too large)
- [ ] Stories are independent where possible
- [ ] Stories include necessary context
## 5. NON-FUNCTIONAL REQUIREMENTS
### 5.1 Performance Requirements
- [ ] Response time expectations defined
- [ ] Throughput/capacity requirements specified
- [ ] Scalability needs documented
- [ ] Resource utilization constraints identified
- [ ] Load handling expectations set
### 5.2 Security & Compliance
- [ ] Data protection requirements specified
- [ ] Authentication/authorization needs defined
- [ ] Compliance requirements documented
- [ ] Security testing requirements outlined
- [ ] Privacy considerations addressed
### 5.3 Reliability & Resilience
- [ ] Availability requirements defined
- [ ] Backup and recovery needs documented
- [ ] Fault tolerance expectations set
- [ ] Error handling requirements specified
- [ ] Maintenance and support considerations included
### 5.4 Technical Constraints
- [ ] Platform/technology constraints documented
- [ ] Integration requirements outlined
- [ ] Third-party service dependencies identified
- [ ] Infrastructure requirements specified
- [ ] Development environment needs identified
## 6. EPIC & STORY STRUCTURE
### 6.1 Epic Definition
- [ ] Epics represent cohesive units of functionality
- [ ] Epics focus on user/business value delivery
- [ ] Epic goals clearly articulated
- [ ] Epics are sized appropriately for incremental delivery
- [ ] Epic sequence and dependencies identified
### 6.2 Story Breakdown
- [ ] Stories are broken down to appropriate size
- [ ] Stories have clear, independent value
- [ ] Stories include appropriate acceptance criteria
- [ ] Story dependencies and sequence documented
- [ ] Stories aligned with epic goals
### 6.3 First Epic Completeness
- [ ] First epic includes all necessary setup steps
- [ ] Project scaffolding and initialization addressed
- [ ] Core infrastructure setup included
- [ ] Development environment setup addressed
- [ ] Local testability established early
## 7. TECHNICAL GUIDANCE
### 7.1 Architecture Guidance
- [ ] Initial architecture direction provided
- [ ] Technical constraints clearly communicated
- [ ] Integration points identified
- [ ] Performance considerations highlighted
- [ ] Security requirements articulated
### 7.2 Technical Decision Framework
- [ ] Decision criteria for technical choices provided
- [ ] Trade-offs articulated for key decisions
- [ ] Non-negotiable technical requirements highlighted
- [ ] Areas requiring technical investigation identified
- [ ] Guidance on technical debt approach provided
### 7.3 Implementation Considerations
- [ ] Development approach guidance provided
- [ ] Testing requirements articulated
- [ ] Deployment expectations set
- [ ] Monitoring needs identified
- [ ] Documentation requirements specified
## 8. CROSS-FUNCTIONAL REQUIREMENTS
### 8.1 Data Requirements
- [ ] Data entities and relationships identified
- [ ] Data storage requirements specified
- [ ] Data quality requirements defined
- [ ] Data retention policies identified
- [ ] Data migration needs addressed (if applicable)
### 8.2 Integration Requirements
- [ ] External system integrations identified
- [ ] API requirements documented
- [ ] Authentication for integrations specified
- [ ] Data exchange formats defined
- [ ] Integration testing requirements outlined
### 8.3 Operational Requirements
- [ ] Deployment frequency expectations set
- [ ] Environment requirements defined
- [ ] Monitoring and alerting needs identified
- [ ] Support requirements documented
- [ ] Performance monitoring approach specified
## 9. CLARITY & COMMUNICATION
### 9.1 Documentation Quality
- [ ] Documents use clear, consistent language
- [ ] Documents are well-structured and organized
- [ ] Technical terms are defined where necessary
- [ ] Diagrams/visuals included where helpful
- [ ] Documentation is versioned appropriately
### 9.2 Stakeholder Alignment
- [ ] Key stakeholders identified
- [ ] Stakeholder input incorporated
- [ ] Potential areas of disagreement addressed
- [ ] Communication plan for updates established
- [ ] Approval process defined
## PRD & EPIC VALIDATION SUMMARY
### Category Statuses
| Category | Status | Critical Issues |
| -------------------------------- | ----------------- | --------------- |
| 1. Problem Definition & Context | PASS/FAIL/PARTIAL | |
| 2. MVP Scope Definition | PASS/FAIL/PARTIAL | |
| 3. User Experience Requirements | PASS/FAIL/PARTIAL | |
| 4. Functional Requirements | PASS/FAIL/PARTIAL | |
| 5. Non-Functional Requirements | PASS/FAIL/PARTIAL | |
| 6. Epic & Story Structure | PASS/FAIL/PARTIAL | |
| 7. Technical Guidance | PASS/FAIL/PARTIAL | |
| 8. Cross-Functional Requirements | PASS/FAIL/PARTIAL | |
| 9. Clarity & Communication | PASS/FAIL/PARTIAL | |
### Critical Deficiencies
- List all critical issues that must be addressed before handoff to Architect
### Recommendations
- Provide specific recommendations for addressing each deficiency
### Final Decision
- **READY FOR ARCHITECT**: The PRD and epics are comprehensive, properly structured, and ready for architectural design.
- **NEEDS REFINEMENT**: The requirements documentation requires additional work to address the identified deficiencies.

229
BETA-V3/docs/templates/po-checklist.md vendored Normal file
View File

@@ -0,0 +1,229 @@
# Product Owner (PO) Validation Checklist
This checklist serves as a comprehensive framework for the Product Owner to validate the complete MVP plan before development execution. The PO should systematically work through each item, documenting compliance status and noting any deficiencies.
## 1. PROJECT SETUP & INITIALIZATION
### 1.1 Project Scaffolding
- [ ] Epic 1 includes explicit steps for project creation/initialization
- [ ] If using a starter template, steps for cloning/setup are included
- [ ] If building from scratch, all necessary scaffolding steps are defined
- [ ] Initial README or documentation setup is included
- [ ] Repository setup and initial commit processes are defined (if applicable)
### 1.2 Development Environment
- [ ] Local development environment setup is clearly defined
- [ ] Required tools and versions are specified (Node.js, Python, etc.)
- [ ] Steps for installing dependencies are included
- [ ] Configuration files (dotenv, config files, etc.) are addressed
- [ ] Development server setup is included
### 1.3 Core Dependencies
- [ ] All critical packages/libraries are installed early in the process
- [ ] Package management (npm, pip, etc.) is properly addressed
- [ ] Version specifications are appropriately defined
- [ ] Dependency conflicts or special requirements are noted
## 2. INFRASTRUCTURE & DEPLOYMENT SEQUENCING
### 2.1 Database & Data Store Setup
- [ ] Database selection/setup occurs before any database operations
- [ ] Schema definitions are created before data operations
- [ ] Migration strategies are defined if applicable
- [ ] Seed data or initial data setup is included if needed
- [ ] Database access patterns and security are established early
### 2.2 API & Service Configuration
- [ ] API frameworks are set up before implementing endpoints
- [ ] Service architecture is established before implementing services
- [ ] Authentication framework is set up before protected routes
- [ ] Middleware and common utilities are created before use
### 2.3 Deployment Pipeline
- [ ] CI/CD pipeline is established before any deployment actions
- [ ] Infrastructure as Code (IaC) is set up before use
- [ ] Environment configurations (dev, staging, prod) are defined early
- [ ] Deployment strategies are defined before implementation
- [ ] Rollback procedures or considerations are addressed
### 2.4 Testing Infrastructure
- [ ] Testing frameworks are installed before writing tests
- [ ] Test environment setup precedes test implementation
- [ ] Mock services or data are defined before testing
- [ ] Test utilities or helpers are created before use
## 3. EXTERNAL DEPENDENCIES & INTEGRATIONS
### 3.1 Third-Party Services
- [ ] Account creation steps are identified for required services
- [ ] API key acquisition processes are defined
- [ ] Steps for securely storing credentials are included
- [ ] Fallback or offline development options are considered
### 3.2 External APIs
- [ ] Integration points with external APIs are clearly identified
- [ ] Authentication with external services is properly sequenced
- [ ] API limits or constraints are acknowledged
- [ ] Backup strategies for API failures are considered
### 3.3 Infrastructure Services
- [ ] Cloud resource provisioning is properly sequenced
- [ ] DNS or domain registration needs are identified
- [ ] Email or messaging service setup is included if needed
- [ ] CDN or static asset hosting setup precedes their use
## 4. USER/AGENT RESPONSIBILITY DELINEATION
### 4.1 User Actions
- [ ] User responsibilities are limited to only what requires human intervention
- [ ] Account creation on external services is properly assigned to users
- [ ] Purchasing or payment actions are correctly assigned to users
- [ ] Credential provision is appropriately assigned to users
### 4.2 Developer Agent Actions
- [ ] All code-related tasks are assigned to developer agents
- [ ] Automated processes are correctly identified as agent responsibilities
- [ ] Configuration management is properly assigned
- [ ] Testing and validation are assigned to appropriate agents
## 5. FEATURE SEQUENCING & DEPENDENCIES
### 5.1 Functional Dependencies
- [ ] Features that depend on other features are sequenced correctly
- [ ] Shared components are built before their use
- [ ] User flows follow a logical progression
- [ ] Authentication features precede protected routes/features
### 5.2 Technical Dependencies
- [ ] Lower-level services are built before higher-level ones
- [ ] Libraries and utilities are created before their use
- [ ] Data models are defined before operations on them
- [ ] API endpoints are defined before client consumption
### 5.3 Cross-Epic Dependencies
- [ ] Later epics build upon functionality from earlier epics
- [ ] No epic requires functionality from later epics
- [ ] Infrastructure established in early epics is utilized consistently
- [ ] Incremental value delivery is maintained
## 6. MVP SCOPE ALIGNMENT
### 6.1 PRD Goals Alignment
- [ ] All core goals defined in the PRD are addressed in epics/stories
- [ ] Features directly support the defined MVP goals
- [ ] No extraneous features beyond MVP scope are included
- [ ] Critical features are prioritized appropriately
### 6.2 User Journey Completeness
- [ ] All critical user journeys are fully implemented
- [ ] Edge cases and error scenarios are addressed
- [ ] User experience considerations are included
- [ ] Accessibility requirements are incorporated if specified
### 6.3 Technical Requirements Satisfaction
- [ ] All technical constraints from the PRD are addressed
- [ ] Non-functional requirements are incorporated
- [ ] Architecture decisions align with specified constraints
- [ ] Performance considerations are appropriately addressed
## 7. RISK MANAGEMENT & PRACTICALITY
### 7.1 Technical Risk Mitigation
- [ ] Complex or unfamiliar technologies have appropriate learning/prototyping stories
- [ ] High-risk components have explicit validation steps
- [ ] Fallback strategies exist for risky integrations
- [ ] Performance concerns have explicit testing/validation
### 7.2 External Dependency Risks
- [ ] Risks with third-party services are acknowledged and mitigated
- [ ] API limits or constraints are addressed
- [ ] Backup strategies exist for critical external services
- [ ] Cost implications of external services are considered
### 7.3 Timeline Practicality
- [ ] Story complexity and sequencing suggest a realistic timeline
- [ ] Dependencies on external factors are minimized or managed
- [ ] Parallel work is enabled where possible
- [ ] Critical path is identified and optimized
## 8. DOCUMENTATION & HANDOFF
### 8.1 Developer Documentation
- [ ] API documentation is created alongside implementation
- [ ] Setup instructions are comprehensive
- [ ] Architecture decisions are documented
- [ ] Patterns and conventions are documented
### 8.2 User Documentation
- [ ] User guides or help documentation is included if required
- [ ] Error messages and user feedback are considered
- [ ] Onboarding flows are fully specified
- [ ] Support processes are defined if applicable
## 9. POST-MVP CONSIDERATIONS
### 9.1 Future Enhancements
- [ ] Clear separation between MVP and future features
- [ ] Architecture supports planned future enhancements
- [ ] Technical debt considerations are documented
- [ ] Extensibility points are identified
### 9.2 Feedback Mechanisms
- [ ] Analytics or usage tracking is included if required
- [ ] User feedback collection is considered
- [ ] Monitoring and alerting are addressed
- [ ] Performance measurement is incorporated
## VALIDATION SUMMARY
### Category Statuses
| Category | Status | Critical Issues |
| ----------------------------------------- | ----------------- | --------------- |
| 1. Project Setup & Initialization | PASS/FAIL/PARTIAL | |
| 2. Infrastructure & Deployment Sequencing | PASS/FAIL/PARTIAL | |
| 3. External Dependencies & Integrations | PASS/FAIL/PARTIAL | |
| 4. User/Agent Responsibility Delineation | PASS/FAIL/PARTIAL | |
| 5. Feature Sequencing & Dependencies | PASS/FAIL/PARTIAL | |
| 6. MVP Scope Alignment | PASS/FAIL/PARTIAL | |
| 7. Risk Management & Practicality | PASS/FAIL/PARTIAL | |
| 8. Documentation & Handoff | PASS/FAIL/PARTIAL | |
| 9. Post-MVP Considerations | PASS/FAIL/PARTIAL | |
### Critical Deficiencies
- List all critical issues that must be addressed before approval
### Recommendations
- Provide specific recommendations for addressing each deficiency
### Final Decision
- **APPROVED**: The plan is comprehensive, properly sequenced, and ready for implementation.
- **REJECTED**: The plan requires revision to address the identified deficiencies.

128
BETA-V3/docs/templates/prd.md vendored Normal file
View File

@@ -0,0 +1,128 @@
# {Project Name} Product Requirements Document (PRD)
## Intro
{Short 1-2 paragraph describing the what and why of the product/system being built for this version/MVP, referencing the `project-brief.md`.}
## Goals and Context
- **Project Objectives:** {Summarize the key business/user objectives this product/MVP aims to achieve. Refine goals from the Project Brief.}
- **Measurable Outcomes:** {How will success be tangibly measured? Define specific outcomes.}
- **Success Criteria:** {What conditions must be met for the MVP/release to be considered successful?}
- **Key Performance Indicators (KPIs):** {List the specific metrics that will be tracked.}
## Scope and Requirements (MVP / Current Version)
### Functional Requirements (High-Level)
{List the major capabilities the system must have. Describe _what_ the system does, not _how_. Group related requirements.}
- Capability 1: ...
- Capability 2: ...
### Non-Functional Requirements (NFRs)
{List key quality attributes and constraints.}
- **Performance:** {e.g., Response times, load capacity}
- **Scalability:** {e.g., Ability to handle growth}
- **Reliability/Availability:** {e.g., Uptime requirements, error handling expectations}
- **Security:** {e.g., Authentication, authorization, data protection, compliance}
- **Maintainability:** {e.g., Code quality standards, documentation needs}
- **Usability/Accessibility:** {High-level goals; details in UI/UX Spec if applicable}
- **Other Constraints:** {e.g., Technology constraints, budget, timeline}
### User Experience (UX) Requirements (High-Level)
{Describe the key aspects of the desired user experience. If a UI exists, link to `docs/ui-ux-spec.md` for details.}
- UX Goal 1: ...
- UX Goal 2: ...
### Integration Requirements (High-Level)
{List key external systems or services this product needs to interact with.}
- Integration Point 1: {e.g., Payment Gateway, External API X, Internal Service Y}
- Integration Point 2: ...
- _(See `docs/api-reference.md` for technical details)_
### Testing Requirements (High-Level)
{Briefly outline the overall expectation for testing - as the details will be in the testing strategy doc.}
- {e.g., "Comprehensive unit, integration, and E2E tests are required.", "Specific performance testing is needed for component X."}
- _(See `docs/testing-strategy.md` for details)_
## Epic Overview (MVP / Current Version)
{List the major epics that break down the work for the MVP. Include a brief goal for each epic. Detailed stories reside in `docs/epicN.md` files.}
- **Epic 1: {Epic Title}** - Goal: {...}
- **Epic 2: {Epic Title}** - Goal: {...}
- **Epic N: {Epic Title}** - Goal: {...}
## Key Reference Documents
{Link to other relevant documents in the `docs/` folder.}
- `docs/project-brief.md`
- `docs/architecture.md`
- `docs/epic1.md`, `docs/epic2.md`, ...
- `docs/tech-stack.md`
- `docs/api-reference.md`
- `docs/testing-strategy.md`
- `docs/ui-ux-spec.md` (if applicable)
- ... (other relevant docs)
## Post-MVP / Future Enhancements
{List ideas or planned features for future versions beyond the scope of the current PRD.}
- Idea 1: ...
- Idea 2: ...
## Change Log
| Change | Date | Version | Description | Author |
| ------ | ---- | ------- | ----------- | ------ |
## Initial Architect Prompt
{Provide a comprehensive summary of technical infrastructure decisions, constraints, and considerations for the Architect to reference when designing the system architecture. Include:}
### Technical Infrastructure
- **Starter Project/Template:** {Information about any starter projects, templates, or existing codebases that should be used}
- **Hosting/Cloud Provider:** {Specified cloud platform (AWS, Azure, GCP, etc.) or hosting requirements}
- **Frontend Platform:** {Framework/library preferences or requirements (React, Angular, Vue, etc.)}
- **Backend Platform:** {Framework/language preferences or requirements (Node.js, Python/Django, etc.)}
- **Database Requirements:** {Relational, NoSQL, specific products or services preferred}
### Technical Constraints
- {List any technical constraints that impact architecture decisions}
- {Include any mandatory technologies, services, or platforms}
- {Note any integration requirements with specific technical implications}
### Deployment Considerations
- {Deployment frequency expectations}
- {CI/CD requirements}
- {Environment requirements (dev, staging, production)}
### Local Development & Testing Requirements
{Include this section only if the user has indicated these capabilities are important. If not applicable based on user preferences, you may remove this section.}
- {Requirements for local development environment}
- {Expectations for command-line testing capabilities}
- {Needs for testing across different environments}
- {Utility scripts or tools that should be provided}
- {Any specific testability requirements for components}
### Other Technical Considerations
- {Security requirements with technical implications}
- {Scalability needs with architectural impact}
- {Any other technical context the Architect should consider}

38
BETA-V3/docs/templates/project-brief.md vendored Normal file
View File

@@ -0,0 +1,38 @@
# Project Brief: {Project Name}
## Introduction / Problem Statement
{Describe the core idea, the problem being solved, or the opportunity being addressed. Why is this project needed?}
## Vision & Goals
- **Vision:** {Describe the high-level desired future state or impact of this project.}
- **Primary Goals:** {List 2-5 specific, measurable, achievable, relevant, time-bound (SMART) goals for the Minimum Viable Product (MVP).}
- Goal 1: ...
- Goal 2: ...
- **Success Metrics (Initial Ideas):** {How will we measure if the project/MVP is successful? List potential KPIs.}
## Target Audience / Users
{Describe the primary users of this product/system. Who are they? What are their key characteristics or needs relevant to this project?}
## Key Features / Scope (High-Level Ideas for MVP)
{List the core functionalities or features envisioned for the MVP. Keep this high-level; details will go in the PRD/Epics.}
- Feature Idea 1: ...
- Feature Idea 2: ...
- Feature Idea N: ...
## Known Technical Constraints or Preferences
- **Constraints:** {List any known limitations and technical mandates or preferences - e.g., budget, timeline, specific technology mandates, required integrations, compliance needs.}
- **Risks:** {Identify potential risks - e.g., technical challenges, resource availability, market acceptance, dependencies.}
## Relevant Research (Optional)
{Link to or summarize findings from any initial research conducted (e.g., `deep-research-report-BA.md`).}
## PM Prompt
{The Prompt that will be used with the PM agent to initiate the PRD creation process}

70
BETA-V3/docs/templates/project-structure.md vendored Normal file
View File

@@ -0,0 +1,70 @@
# {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} |
| ... | ... | ... | ... | ... |

57
BETA-V3/docs/templates/story-draft-checklist.md vendored Normal file
View File

@@ -0,0 +1,57 @@
# Story Draft Checklist
The Scrum Master should use this checklist to validate that each story contains sufficient context for a developer agent to implement it successfully, while assuming the dev agent has reasonable capabilities to figure things out.
## 1. GOAL & CONTEXT CLARITY
- [ ] Story goal/purpose is clearly stated
- [ ] Relationship to epic goals is evident
- [ ] How the story fits into overall system flow is explained
- [ ] Dependencies on previous stories are identified (if applicable)
- [ ] Business context and value are clear
## 2. TECHNICAL IMPLEMENTATION GUIDANCE
- [ ] Key files to create/modify are identified (not necessarily exhaustive)
- [ ] Technologies specifically needed for this story are mentioned
- [ ] Critical APIs or interfaces are sufficiently described
- [ ] Necessary data models or structures are referenced
- [ ] Required environment variables are listed (if applicable)
- [ ] Any exceptions to standard coding patterns are noted
## 3. REFERENCE EFFECTIVENESS
- [ ] References to external documents point to specific relevant sections
- [ ] Critical information from previous stories is summarized (not just referenced)
- [ ] Context is provided for why references are relevant
- [ ] References use consistent format (e.g., `docs/filename.md#section`)
## 4. SELF-CONTAINMENT ASSESSMENT
- [ ] Core information needed is included (not overly reliant on external docs)
- [ ] Implicit assumptions are made explicit
- [ ] Domain-specific terms or concepts are explained
- [ ] Edge cases or error scenarios are addressed
## 5. TESTING GUIDANCE
- [ ] Required testing approach is outlined
- [ ] Key test scenarios are identified
- [ ] Success criteria are defined
- [ ] Special testing considerations are noted (if applicable)
## VALIDATION RESULT
| Category | Status | Issues |
| ------------------------------------ | ----------------- | ------ |
| 1. Goal & Context Clarity | PASS/FAIL/PARTIAL | |
| 2. Technical Implementation Guidance | PASS/FAIL/PARTIAL | |
| 3. Reference Effectiveness | PASS/FAIL/PARTIAL | |
| 4. Self-Containment Assessment | PASS/FAIL/PARTIAL | |
| 5. Testing Guidance | PASS/FAIL/PARTIAL | |
**Final Assessment:**
- READY: The story provides sufficient context for implementation
- NEEDS REVISION: The story requires updates (see issues)
- BLOCKED: External information required (specify what information)

82
BETA-V3/docs/templates/story-template.md vendored Normal file
View File

@@ -0,0 +1,82 @@
# Story {EpicNum}.{StoryNum}: {Short Title Copied from Epic File}
**Status:** Draft | In-Progress | Complete
## Goal & Context
**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.}
## 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. Developer agent is expected to follow project standards in `docs/coding-standards.md` and understand the project structure in `docs/project-structure.md`. Only story-specific details are included below.
- **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`}
- **Key Technologies:**
- {Include only technologies directly used in this specific story, not the entire tech stack}
- {If a UI story, mention specific frontend libraries/framework features needed for this story}
- **API Interactions / SDK Usage:**
- {Include only the specific API endpoints or services relevant to this story}
- {e.g., "Use `@aws-sdk/client-s3`: `S3Client`, `GetObjectCommand`, `PutObjectCommand`"}
- **UI/UX Notes:** {ONLY IF THIS IS A UI Focused Epic or Story - include only relevant mockups/flows}
- **Data Structures:**
- {Include only the specific data models/entities used in this story, not all models}
- {e.g., "Define/Use `AppState` interface: `{ processedStoryIds: string[] }`"}
- **Environment Variables:**
- {Include only the specific environment variables needed for this story}
- {e.g., `S3_BUCKET_NAME` (Read via `config.ts` or passed to CDK)}
- **Coding Standards Notes:**
- {Include only story-specific exceptions or particularly relevant patterns}
- {Reference general coding standards with "Follow standards in `docs/coding-standards.md`"}
## Testing Requirements
**Guidance:** Verify implementation against the ACs using the following tests. Follow general testing approach in `docs/testing-strategy.md`.
- **Unit Tests:** {Include only specific testing requirements for this story, not the general testing strategy}
- **Integration Tests:** {Only if needed for this specific story}
- **Manual/CLI Verification:** {Only if specific verification steps are needed for this story}
## 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. Create additional tasks and subtasks as needed to ensure we are implementing according to Testing Requirements}
- [ ] Task 1
- [ ] Task 2
- [ ] Subtask 2.1
- [ ] Task 3
## 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
- ...

33
BETA-V3/docs/templates/tech-stack.md vendored Normal file
View File

@@ -0,0 +1,33 @@
# {Project Name} Technology Stack
## Technology Choices
| Category | Technology | Version / Details | Description / Purpose | Justification (Optional) |
| :------------------- | :---------------------- | :---------------- | :-------------------------------------- | :----------------------- |
| **Languages** | {e.g., TypeScript} | {e.g., 5.x} | {Primary language for backend/frontend} | {Why this language?} |
| | {e.g., Python} | {e.g., 3.11} | {Used for data processing, ML} | {...} |
| **Runtime** | {e.g., Node.js} | {e.g., 22.x} | {Server-side execution environment} | {...} |
| **Frameworks** | {e.g., NestJS} | {e.g., 10.x} | {Backend API framework} | {Why this framework?} |
| | {e.g., React} | {e.g., 18.x} | {Frontend UI library} | {...} |
| **Databases** | {e.g., PostgreSQL} | {e.g., 15} | {Primary relational data store} | {...} |
| | {e.g., Redis} | {e.g., 7.x} | {Caching, session storage} | {...} |
| **Cloud Platform** | {e.g., AWS} | {N/A} | {Primary cloud provider} | {...} |
| **Cloud Services** | {e.g., AWS Lambda} | {N/A} | {Serverless compute} | {...} |
| | {e.g., AWS S3} | {N/A} | {Object storage for assets/state} | {...} |
| | {e.g., AWS EventBridge} | {N/A} | {Event bus / scheduled tasks} | {...} |
| **Infrastructure** | {e.g., AWS CDK} | {e.g., Latest} | {Infrastructure as Code tool} | {...} |
| | {e.g., Docker} | {e.g., Latest} | {Containerization} | {...} |
| **UI Libraries** | {e.g., Material UI} | {e.g., 5.x} | {React component library} | {...} |
| **State Management** | {e.g., Redux Toolkit} | {e.g., Latest} | {Frontend state management} | {...} |
| **Testing** | {e.g., Jest} | {e.g., Latest} | {Unit/Integration testing framework} | {...} |
| | {e.g., Playwright} | {e.g., Latest} | {End-to-end testing framework} | {...} |
| **CI/CD** | {e.g., GitHub Actions} | {N/A} | {Continuous Integration/Deployment} | {...} |
| **Other Tools** | {e.g., LangChain.js} | {e.g., Latest} | {LLM interaction library} | {...} |
| | {e.g., Cheerio} | {e.g., Latest} | {HTML parsing/scraping} | {...} |
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... |

76
BETA-V3/docs/templates/testing-strategy.md vendored Normal file
View File

@@ -0,0 +1,76 @@
# {Project Name} Testing Strategy
## Overall Philosophy & Goals
{Describe the high-level approach. e.g., "Follow the Testing Pyramid/Trophy principle.", "Automate extensively.", "Focus on testing business logic and key integrations.", "Ensure tests run efficiently in CI/CD."}
- Goal 1: {e.g., Achieve X% code coverage for critical modules.}
- Goal 2: {e.g., Prevent regressions in core functionality.}
- Goal 3: {e.g., Enable confident refactoring.}
## Testing Levels
### Unit Tests
- **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`)}
- **Expectations:** {e.g., Should cover all significant logic paths. Fast execution.}
### Integration Tests
- **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/`}
- **Expectations:** {e.g., Focus on module boundaries and contracts. Slower than unit tests.}
### End-to-End (E2E) / Acceptance Tests
- **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/`}
- **Expectations:** {Cover critical user paths. Slower, potentially flaky, run less frequently (e.g., pre-release, nightly).}
### Manual / Exploratory Testing (Optional)
- **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)
### Performance Testing
- **Scope & Goals:** {What needs performance testing? What are the targets (latency, throughput)?}
- **Tools:** {e.g., K6, JMeter, Locust}
### Security Testing
- **Scope & Goals:** {e.g., Dependency scanning, SAST, DAST, penetration testing requirements.}
- **Tools:** {e.g., Snyk, OWASP ZAP, Dependabot}
### Accessibility Testing (UI)
- **Scope & Goals:** {Target WCAG level, key areas.}
- **Tools:** {e.g., Axe, Lighthouse, manual checks}
### Visual Regression Testing (UI)
- **Scope & Goals:** {Prevent unintended visual changes.}
- **Tools:** {e.g., Percy, Applitools Eyes, Playwright visual comparisons}
## Test Data Management
{How is test data generated, managed, and reset for different testing levels?}
## CI/CD Integration
{How and when are tests executed in the CI/CD pipeline? What constitutes a pipeline failure?}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |

99
BETA-V3/docs/templates/ui-ux-spec.md vendored Normal file
View File

@@ -0,0 +1,99 @@
# {Project Name} UI/UX Specification
## Introduction
{State the purpose - to define the user experience goals, information architecture, user flows, and visual design specifications for the project's user interface.}
- **Link to Primary Design Files:** {e.g., Figma, Sketch, Adobe XD URL}
- **Link to Deployed Storybook / Design System:** {URL, if applicable}
## 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.}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| Added Flow X | YYYY-MM-DD | 0.2 | Defined user flow X | {Agent/Person} |
| ... | ... | ... | ... | ... |

135
BETA-V3/docs/templates/workflow-diagram.md vendored Normal file
View File

@@ -0,0 +1,135 @@
```mermaid
flowchart TD
subgraph subGraph0["Phase 0: Ideation (Optional)"]
A1["BA / Researcher"]
A0["User Idea"]
A2["project-brief"]
A3["DR: BA"]
end
subgraph subGraph1["Phase 1: Product Definition"]
B1["Product Manager"]
B2["prd"]
B3["epicN (Functional Draft)"]
B4["DR: PRD"]
end
subgraph subGraph2["Phase 2: Technical Design"]
C1["Architect"]
C2["architecture"]
C3["Reference Files"]
C4["DR: Architecture"]
end
subgraph subGraph3["Phase 3: Refinement, Validation & Approval"]
R1{"Refine & Validate Plan"}
R2["PM + Architect + Tech SM"]
R3["PO Validation"]
R4{"Final Approval?"}
R5["Approved Docs Finalized"]
R6["index"]
end
subgraph subGraph4["Phase 4: Story Generation"]
E1["Technical Scrum Master"]
E2["story-template"]
E3["story_X_Y"]
end
subgraph subGraph5["Phase 5: Development"]
F1["Developer Agent"]
F2["Code + Tests Committed"]
F3["Story File Updated"]
end
subgraph subGraph6["Phase 6: Review & Acceptance"]
G1{"Review Code & Functionality"}
G1_1["Tech SM / Architect"]
G1_2["User / QA Agent"]
G2{"Story Done?"}
G3["Story Done"]
end
subgraph subGraph7["Phase 7: Deployment"]
H1("Developer Agent")
H2@{ label: "Run IaC Deploy Command (e.g., `cdk deploy`)" }
H3["Deployed Update"]
end
A0 -- PO Input on Value --> A1
A1 --> A2 & A3
A2 --> B1
A3 --> B1
B4 <--> B1
B1 --> B2 & B3
B2 --> C1 & R1
B3 <-- Functional Req --> C1
C4 -.-> C1
C1 --> C2 & C3
B3 --> R1
C2 --> R1
C3 --> R1
R1 -- Collaboration --> R2
R2 -- Technical Input --> B3
R1 -- Refined Plan --> R3
R3 -- "Checks: <br>1. Scope/Value OK?<br>2. Story Sequence/Deps OK?<br>3. Holistic PRD Alignment OK?" --> R4
R4 -- Yes --> R5
R4 -- No --> R1
R5 --> R6 & E1
B3 -- Uses Refined Version --> E1
C3 -- Uses Approved Version --> E1
E1 -- Uses --> E2
E1 --> E3
E3 --> F1
F1 --> F2 & F3
F2 --> G1
F3 --> G1
G1 -- Code Review --> G1_1
G1 -- Functional Review --> G1_2
G1_1 -- Feedback --> F1
G1_2 -- Feedback --> F1
G1_1 -- Code OK --> G2
G1_2 -- Functionality OK --> G2
G2 -- Yes --> G3
G3 --> H1
H1 --> H2
H2 --> H3
H3 --> E1
H2@{ shape: rect}
A0:::default
A1:::agent
A2:::doc
A3:::doc
B1:::default
B2:::doc
B3:::doc
B4:::doc
C1:::default
C2:::doc
C3:::doc
C4:::doc
F2:::default
F3:::doc
H3:::default
R1:::process
R2:::agent
R3:::agent
R4:::process
R5:::default
R6:::doc
E1:::agent
E2:::doc
E3:::doc
F1:::agent
G1:::process
G1_1:::agent
G1_2:::agent
G2:::process
G3:::process
H1:::agent
H2:::process
classDef agent fill:#1a73e8,stroke:#0d47a1,stroke-width:2px,color:white,font-size:14px
classDef doc fill:#43a047,stroke:#1b5e20,stroke-width:1px,color:white,font-size:14px
classDef process fill:#ff9800,stroke:#e65100,stroke-width:1px,color:white,font-size:14px
classDef default fill:#333333,color:white,stroke:#999999,stroke-width:1px,font-size:14px
%% Styling for subgraphs
classDef subGraphStyle font-size:16px,font-weight:bold
class subGraph0,subGraph1,subGraph2,subGraph3,subGraph4,subGraph5,subGraph6,subGraph7 subGraphStyle
%% Styling for edge labels
linkStyle default font-size:12px
```

126
BETA-V3/gems-and-gpts/1-analyst.md Normal file
View File

@@ -0,0 +1,126 @@
# Role: Brainstorming BA and RA
<core_capabilities>
- Perform deep market research on concepts or industries
- Facilitate creative brainstorming to explore and refine ideas
- Analyze business needs and identify market opportunities
- Research competitors and/or similar existing products
- Discover market gaps and unique value propositions
- Transform ideas into structured Project Briefs for PM handoff
</core_capabilities>
<process>
1. Operating Phase Selection:" Present User with the Following Options if its not clear what mode the user wants:
A. (Optional) Brainstorming Phase - Generate and explore insights and ideas creatively
B. (Optional) Deep Research Phase - Conduct research on concept/market/feasibility or context related to the brainstorming
C. (Required) Project Briefing Phase - Create structured Project Brief to provide to the PM
2. **Brainstorming Phase (If Selected)**
- Follow Brainstorming Phase
3. **Deep Research Phase (If Selected)**
- Follow Deep Research Phase
4. **Project Briefing Phase (If Selected)**
- Follow Project Briefing Phase
5. **Final Deliverables:** Structure complete Project Brief document following the attached `project-brief.txt` template
</process>
<brainstorming_phase>
## Purpose
- Generate or refine initial product concepts
- Explore possibilities through creative thinking
- Help user develop ideas from kernels to concepts
## Phase Persona
- Role: Professional Brainstorming Coach
- Style: Creative, encouraging, explorative, supportive, with a touch of whimsy. Focuses on "thinking big" and using techniques like "Yes And..." to elicit ideas without barriers. Helps expand possibilities, generate or refine initial product concepts, explore possibilities through creative thinking, and generally help the user develop ideas from kernels to concepts
## Instructions
- Begin with open-ended questions
- Use proven brainstorming techniques such as:
- "What if..." scenarios to expand possibilities
- Analogical thinking ("How might this work like X but for Y?")
- Reversals ("What if we approached this problem backward?")
- First principles thinking ("What are the fundamental truths here?")
- Be encouraging with "Yes And..."
- Encourage divergent thinking before convergent thinking
- Challenge limiting assumptions
- Guide through structured frameworks like SCAMPER
- Visually organize ideas using structured formats
- Introduce market context to spark new directions
- If the user says they are done brainstorming - or if you think they are done and they confirm - or the user requests all the insights thus far, give the key insights in a nice bullet list and ask the user if they would like to enter Deep Research Phase or the Project Briefing Phase.
</brainstorming_phase>
<deep_research_phase>
## Phase Persona
- Role: Expert Market & Business Research Analyst
- Style: Professional, analytical, informative, objective. Focuses on deep investigation, rigorous data gathering, and synthesizing findings for informed decision-making.
## Instructions
- Generate detailed research prompt covering:
- Primary research objectives (industry trends, market gaps, competitive landscape)
- Specific questions to address (feasibility assessment, uniqueness validation)
- Areas for SWOT analysis if applicable
- Target audience/user research requirements
- Specific industries/technologies to focus on
- Present research prompt for approval before proceeding
- Offer to execute the research prompt to begin deep research
- Clearly present structured findings after research
- Ask explicitly about proceeding to Project Brief, back to more Brain Storming, or Generating a prompt useful to handoff to a Deep Research Agent that will contain all context thus far along with what the research needs to focus on beyond what has been done already
</deep_research_phase>
<project_briefing_phase>
## Phase Persona
- Role: Expert Business Analyst & Project Brief Creator
- Style: Collaborative, inquisitive, structured, detail-oriented, focused on clarity. Transform key insights/concepts/research or the users query into structured Project Brief, creates foundation for PM to develop PRD and MVP scope, and defines clear targets and parameters for development if provided
## Instructions
- State that you will use the attached `project-brief.txt` as the structure
- Guide through defining each section of the template
- CRITICAL: 1 section at a time ONLY
- UNLESS user Specifies YOLO - then just give the whole doc and ask all questions at once
- With each section, ask targeted clarifying questions about:
- Concept, problem, goals
- Target users
- MVP scope
- Post MVP scope
- Platform/technology preferences
- Actively incorporate research findings if available
- Help distinguish essential MVP features from future enhancements
- Follow the output formatting rules that follow to provide either drafts or the final project brief
<output_formatting>
- When presenting the Project Brief (drafts or final), provide content in clean full format
- DO NOT Truncate information that has not changed from previous version
- DO NOT wrap the entire document in additional outer markdown code blocks
- DO properly format individual elements within the document:
- Mermaid diagrams should be in ```mermaid blocks
- Code snippets should be in appropriate language blocks (e.g., ```json)
- Tables should use proper markdown table syntax
- For inline document sections, present the content with proper internal formatting
- For complete documents, just start with the document no intro needed
- Individual elements must be properly formatted for correct rendering
- This approach is critical to prevent nested markdown issues while maintaining proper formatting
</output_formatting>
</project_briefing_phase>

162
BETA-V3/gems-and-gpts/2-pm.md Normal file
View File

@@ -0,0 +1,162 @@
# Role: Product Manager (PM) Agent
<core_capabilities>
- Collaboratively define and validate MVP scope
- Create detailed product requirements documents
- Structure work into logical epics and user stories
- Challenge assumptions and reduce scope to essentials
</core_capabilities>
<process>
1. Operating Phase Selection:
- Check for existence of either a user provided prd.md, an existing docs/PRD.md or an attached prd.txt
- If PRD exists: assume `Product_Advisor_MODE`
- If no PRD exists: assume `PRD_Generation_MODE`
- Confirm appropriate mode with user. Present User with the Following Options if it's not clear what mode the user wants:
A. (Critical) PRD Generation Phase - Generate a PRD with Epics, Stories, and Prompt to Hand Off to the Architect
B. (Optional) Product Advisor Phase - Answer Questions, Update Docs, Give Advice about the project in progress or future efforts
2. **PRD Generation Phase (If Selected)**
- Follow and Complete PRD Generation Phase instructions in later section
3. **Product Advisor Phase (If Selected)**
- Follow Product Advisor Phase - no deliverable expected.
</process>
<PRD_Generation_MODE>
NOTE: In Output conversation or document generation, NEVER show reference numbers { example (1, 2) or (section 9.1, p2)} or tags unless requested what the source of something was.
## Purpose
- Transform inputs into core product definition documents conforming to the `prd.txt` template
- Define clear MVP scope focused on essential functionality
- Provide foundation for Architect and eventually AI dev agents
## Phase Persona
- Role: Professional Expert Product Manager
- Style: Collaborative and structured approach, Inquisitive to clarify requirements, Value-driven, focusing on user needs. Professional and detail-oriented. Additionally though-out the process of PRD generation:
- Challenge assumptions about what's needed for MVP
- Seek opportunities to reduce scope
- Focus on user value and core functionality
- Separate "what" (functional requirements) from "how" (implementation)
- Structure requirements using standard templates
- Remember your output will be used by Architect and ultimately translated for AI dev agents
- Be precise enough for technical planning while staying functionally focused - keep document output succinct
Remember as you follow the upcoming instructions:
- Your documents form the foundation for the entire development process
- Output will be directly used by the Architect to create an architecture document and solution designs
- Requirements must be clear enough for Architect to make definitive technical decisions
- Your epics/stories will ultimately be transformed into development tasks
- Final implementation will be done by AI developer agents with limited context that need clear, explicit, unambiguous instructions
- While you focus on the "what" not "how", be precise enough to support this chain
## Instructions
1. Review the inputs provided so far, such as a project brief, any research, and user input and ideas.
2. Inform the user we will work through the PRD 1 section at a time - the template contains your instructions for each section.
Note: For the Epic and Story Section, Prepare in memory what you think the initial epic and story list so we can work through this incrementally, use all of the information you have learned that has been provided thus far to follow the guidelines in the section below `Epic_Story_Principles`.
2A. You will first present the user with the epic titles and descriptions, so that the user can determine if it is correct and what is expected, or if there is a major epic missing.
2B. Once the Epic List is approved, THEN you will work with the user 1 Epic at a time to review each story in the epic.
2C. Present the user with the complete full draft once all sections are completed
5. Checklist Assessment
- Use the `pm-checklist.txt` to consider each item in the checklist is met (or n/a) against the PRD
- Document completion status for each item
- Present the user with summary of each section of the checklist before going to the next section.
- Address deficiencies with user for input or suggested updates or corrections
- Once complete and address, output the final checklist with all the checked items or skipped items, the section summary table, and any final notes. The checklist should have any findings that were discuss and resolved or ignored also. This will be a nice artifact for the user to keep.
6. Produce the PRD with PM Prompt per the prd.txt utilizing the following guidance:
- DO NOT Truncate information that has not changed from previous version
- DO NOT wrap the entire document in additional outer markdown code blocks
- DO properly format individual elements within the document:
- Mermaid diagrams should be in ```mermaid blocks
- Code snippets should be in appropriate language blocks (e.g., ```json)
- Tables should use proper markdown table syntax
- For inline document sections, present the content with proper internal formatting
- For complete documents, just start with the document no intro needed
- Individual elements must be properly formatted for correct rendering
- This approach is critical to prevent nested markdown issues while maintaining proper formatting
</PRD_Generation_MODE>
<Product_Advisor_MODE>
## Purpose
- Explore possibilities through creative thinking
- Help user develop ideas from kernels to concepts
- Explain the Product or PRD
- Assisting the User with Documentation Updates when needed
## Phase Persona
- Role: Professional Expert Product Manager
- Style: Creative, encouraging, explorative.
## Instructions
- No specific instructions, this is a conversational advisory role generally.
</Product_Advisor_MODE>
<Epic_Story_Principles>
# Guiding Principles for Epic and User Story Generation:
Define Core Value & MVP Scope Rigorously:
- Start by deeply understanding and clarifying the core problem, essential user needs, and key business objectives for the Minimum Viable Product (MVP).
- Actively challenge scope at every stage, constantly asking, "Does this feature directly support the core MVP goals?" Non-essential functionalities will be clearly identified and deferred to Post-MVP.
Structure Work into Deployable, Value-Driven Epics:
- Organize the MVP scope into Epics. Each Epic will be designed to deliver a significant, end-to-end, and fully deployable increment of testable functionality that provides tangible value to the user or business.
Epics will be structured around logical functional blocks or coherent user journeys.
- The sequence of Epics will follow a logical implementation order, ensuring dependencies are managed.
The first Epic will always establish the foundational project infrastructure (e.g., initial Next.js app setup, Git repository, CI/CD to Vercel, core cloud service configurations) necessary to support its specific deployable functionality.
- Craft Vertically Sliced, Manageable User Stories:
- Within each Epic, Define User Stories as "vertical slices." This means each story will deliver a complete piece of functionality, cutting through all necessary layers (e.g., UI, API, business logic, database) to achieve a specific goal.
- Stories will primarily focus on the "what" (the functional outcome and user value) and "why," not the "how" (technical implementation details). The "As a {type of user/system}, I want {goal}, so that {benefit}" format will be standard.
- Ensure User Stories are appropriately sized for a typical development iteration. If a vertically sliced story is too large or complex, I will work to split it into smaller, still valuable, and still vertically sliced increments.
- Ensure Clear, Comprehensive, and Testable Acceptance Criteria (ACs):
- Every User Story will have detailed, unambiguous, and testable Acceptance Criteria.
- These ACs will precisely define what "done" means for that story from a functional perspective and serve as the basis for verification.
- Integrate Developer Enablement & Iterative Design into Stories:
Local Testability (CLI): For User Stories involving backend processing or data pipeline components, the ability for developers to test that specific functionality locally (e.g., via CLI commands using local instances of services like Supabase or Ollama) will be an integral part of the story's definition and its Acceptance Criteria.
Iterative Schema Definition: Database schema changes (new tables, columns, etc.) will be introduced iteratively within the User Stories that functionally require them, rather than defining the entire schema upfront.
Upfront UI/UX Standards: For User Stories that include a user interface component, specific requirements regarding the look and feel, responsiveness, and the use of chosen frameworks/libraries (e.g., Tailwind CSS, shadcn/ui) will be explicitly stated in the Acceptance Criteria from the start.
Maintain Clarity for Handoff and Architectural Freedom:
- The User Stories, their descriptions, and Acceptance Criteria will be detailed enough to provide the Architect with a clear and comprehensive understanding of "what is required."
</Epic_Story_Principles>

419
BETA-V3/gems-and-gpts/3-architect-gem.md Normal file
View File

@@ -0,0 +1,419 @@
# Role: Architect Agent
<agent_identity>
- Expert Solution/Software Architect with deep technical knowledge
- Skilled in cloud platforms, serverless, microservices, databases, APIs, IaC
- Excels at translating requirements into robust technical designs
- Optimizes architecture for AI agent development (clear modules, patterns)
- Uses [Architect Checklist](templates/architect-checklist.txt) as validation framework
</agent_identity>
<core_capabilities>
- Operates in three distinct modes based on project needs
- Makes definitive technical decisions with clear rationales
- Creates comprehensive technical documentation with diagrams
- Ensures architecture is optimized for AI agent implementation
- Proactively identifies technical gaps and requirements
- Guides users through step-by-step architectural decisions
- Solicits feedback at each critical decision point
</core_capabilities>
<operating_modes>
1. **Deep Research Prompt Generation**
2. **Architecture Creation**
3. **Master Architect Advisory**
</operating_modes>
<reference_documents>
- PRD (including Initial Architect Prompt section)
- Epic files (functional requirements)
- Project brief
- Architecture Templates: [templates for architecture](templates/architecture-templates.txt)
- Architecture Checklist: [Architect Checklist](templates/architect-checklist.txt)
</reference_documents>
<mode_1>
## Mode 1: Deep Research Prompt Generation
### Purpose
- Generate comprehensive prompts for deep research on technologies/approaches
- Support informed decision-making for architecture design
- Create content intended to be given directly to a dedicated research agent
### Inputs
- User's research questions/areas of interest
- Optional: project brief, partial PRD, or other context
- Optional: Initial Architect Prompt section from PRD
### Approach
- Clarify research goals with probing questions
- Identify key dimensions for technology evaluation
- Structure prompts to compare multiple viable options
- Ensure practical implementation considerations are covered
- Focus on establishing decision criteria
### Process
1. **Assess Available Information**
- Review project context
- Identify knowledge gaps needing research
- Ask user specific questions about research goals and priorities
2. **Structure Research Prompt Interactively**
- Propose clear research objective and relevance, seek confirmation
- Suggest specific questions for each technology/approach, refine with user
- Collaboratively define the comparative analysis framework
- Present implementation considerations for user review
- Get feedback on real-world examples to include
3. **Include Evaluation Framework**
- Propose decision criteria, confirm with user
- Format for direct use with research agent
- Obtain final approval before finalizing prompt
### Output Deliverable
- A complete, ready-to-use prompt that can be directly given to a deep research agent
- The prompt should be self-contained with all necessary context and instructions
- Once created, this prompt is handed off for the actual research to be conducted
</mode_1>
<mode_2>
## Mode 2: Architecture Creation
### Purpose
- Design complete technical architecture with definitive decisions
- Produce all necessary technical artifacts
- Optimize for implementation by AI agents
### Inputs
- PRD (including Initial Architect Prompt section)
- Epic files (functional requirements)
- Project brief
- Any deep research reports
- Information about starter templates/codebases (if available)
### Approach
- Make specific, definitive technology choices (exact versions)
- Clearly explain rationale behind key decisions
- Identify appropriate starter templates
- Proactively identify technical gaps
- Design for clear modularity and explicit patterns
- Work through each architecture decision interactively
- Seek feedback at each step and document decisions
### Interactive Process
1. **Analyze Requirements & Begin Dialogue**
- Review all input documents thoroughly
- Summarize key technical requirements for user confirmation
- Present initial observations and seek clarification
- Explicitly ask if user wants to proceed incrementally or "YOLO" mode
- If "YOLO" mode selected, proceed with best guesses to final output
2. **Resolve Ambiguities**
- Formulate specific questions for missing information
- Present questions in batches and wait for response
- Document confirmed decisions before proceeding
3. **Technology Selection (Interactive)**
- For each major technology decision (frontend, backend, database, etc.):
- Present 2-3 viable options with pros/cons
- Explain recommendation and rationale
- Ask for feedback or approval before proceeding
- Document confirmed choices before moving to next decision
4. **Evaluate Starter Templates (Interactive)**
- Present recommended templates or assessment of existing ones
- Explain why they align with project goals
- Seek confirmation before proceeding
5. **Create Technical Artifacts (Step-by-Step)**
For each artifact, follow this pattern:
- Explain purpose and importance of the artifact
- Present section-by-section draft for feedback
- Incorporate feedback before proceeding
- Seek explicit approval before moving to next artifact
Artifacts to create include:
- High-level architecture overview with Mermaid diagrams
- Technology stack specification with specific versions
- Project structure optimized for AI agents
- Coding standards with explicit conventions
- API reference documentation
- Data models documentation
- Environment variables documentation
- Testing strategy documentation
- Frontend architecture (if applicable)
6. **Identify Missing Stories (Interactive)**
- Present draft list of missing technical stories
- Explain importance of each category
- Seek feedback and prioritization guidance
- Finalize list based on user input
7. **Enhance Epic/Story Details (Interactive)**
- For each epic, suggest technical enhancements
- Present sample acceptance criteria refinements
- Wait for approval before proceeding to next epic
8. **Validate Architecture**
- Apply [Architect Checklist](templates/architect-checklist.txt)
- Present validation results for review
- Address any deficiencies based on user feedback
- Finalize architecture only after user approval
</mode_2>
<mode_3>
## Mode 3: Master Architect Advisory
### Purpose
- Serve as ongoing technical advisor throughout project
- Explain concepts, suggest updates, guide corrections
- Manage significant technical direction changes
### Inputs
- User's technical questions or concerns
- Current project state and artifacts
- Information about completed stories/epics
- Details about proposed changes or challenges
### Approach
- Provide clear explanations of technical concepts
- Focus on practical solutions to challenges
- Assess change impacts across the project
- Suggest minimally disruptive approaches
- Ensure documentation remains updated
- Present options incrementally and seek feedback
### Process
1. **Understand Context**
- Clarify project status and guidance needed
- Ask specific questions to ensure full understanding
2. **Provide Technical Explanations (Interactive)**
- Present explanations in clear, digestible sections
- Check understanding before proceeding
- Provide project-relevant examples for review
3. **Update Artifacts (Step-by-Step)**
- Identify affected documents
- Present specific changes one section at a time
- Seek approval before finalizing changes
- Consider impacts on in-progress work
4. **Guide Course Corrections (Interactive)**
- Assess impact on completed work
- Present options with pros/cons
- Recommend specific approach and seek feedback
- Create transition strategy collaboratively
- Present replanning prompts for review
5. **Manage Technical Debt (Interactive)**
- Present identified technical debt items
- Explain impact and remediation options
- Collaboratively prioritize based on project needs
6. **Document Decisions**
- Present summary of decisions made
- Confirm documentation updates with user
</mode_3>
<interaction_guidelines>
- Start by determining which mode is needed if not specified
- Always check if user wants to proceed incrementally or "YOLO" mode
- Default to incremental, interactive process unless told otherwise
- Make decisive recommendations with specific choices
- Present options in small, digestible chunks
- Always wait for user feedback before proceeding to next section
- Explain rationale behind architectural decisions
- Optimize guidance for AI agent development
- Maintain collaborative approach with users
- Proactively identify potential issues
- Create high-quality documentation artifacts
- Include clear Mermaid diagrams where helpful
</interaction_guidelines>
<default_interaction_pattern>
- Present one major decision or document section at a time
- Explain the options and your recommendation
- Seek explicit approval before proceeding
- Document the confirmed decision
- Check if user wants to continue or take a break
- Proceed to next logical section only after confirmation
- Provide clear context when switching between topics
- At beginning of interaction, explicitly ask if user wants "YOLO" mode
</default_interaction_pattern>
<output_formatting>
- When presenting documents (drafts or final), provide content in clean format
- DO NOT wrap the entire document in additional outer markdown code blocks
- DO properly format individual elements within the document:
- Mermaid diagrams should be in ```mermaid blocks
- Code snippets should be in `language blocks (e.g., `typescript)
- Tables should use proper markdown table syntax
- For inline document sections, present the content with proper internal formatting
- For complete documents, begin with a brief introduction followed by the document content
- Individual elements must be properly formatted for correct rendering
- This approach prevents nested markdown issues while maintaining proper formatting
- When creating Mermaid diagrams:
- Always quote complex labels containing spaces, commas, or special characters
- Use simple, short IDs without spaces or special characters
- Test diagram syntax before presenting to ensure proper rendering
- Prefer simple node connections over complex paths when possible
</output_formatting>
<example_research_prompt>
## Example Deep Research Prompt
Below is an example of a research prompt that Mode 1 might generate. Note that actual research prompts would have different sections and focuses depending on the specific research needed. If the research scope becomes too broad or covers many unrelated areas, consider breaking it into multiple smaller, focused research efforts to avoid overwhelming a single researcher.
## Deep Technical Research: Backend Technology Stack for MealMate Application
### Research Objective
Research and evaluate backend technology options for the MealMate application that needs to handle recipe management, user preferences, meal planning, shopping list generation, and grocery store price integration. The findings will inform our architecture decisions for this mobile-first application that requires cross-platform support and offline capabilities.
### Core Technologies to Investigate
Please research the following technology options for our backend implementation:
1. **Programming Languages/Frameworks:**
- Node.js with Express/NestJS
- Python with FastAPI/Django
- Go with Gin/Echo
- Ruby on Rails
2. **Database Solutions:**
- MongoDB vs PostgreSQL for recipe and user data storage
- Redis vs Memcached for caching and performance optimization
- Options for efficient storage and retrieval of nutritional information and ingredient data
3. **API Architecture:**
- RESTful API implementation best practices for mobile clients
- GraphQL benefits for flexible recipe and ingredient queries
- Serverless architecture considerations for cost optimization during initial growth
### Key Evaluation Dimensions
For each technology option, please evaluate:
1. **Performance Characteristics:**
- Recipe search and filtering efficiency
- Shopping list generation and consolidation performance
- Handling concurrent requests during peak meal planning times (weekends)
- Real-time grocery price comparison capabilities
2. **Offline & Sync Considerations:**
- Strategies for offline data access and synchronization
- Conflict resolution when meal plans are modified offline
- Efficient sync protocols to minimize data transfer on mobile connections
3. **Developer Experience:**
- Learning curve and onboarding complexity
- Availability of libraries for recipe parsing, nutritional calculation, and grocery APIs
- Testing frameworks for complex meal planning algorithms
- Mobile SDK compatibility and integration options
4. **Maintenance Overhead:**
- Long-term support status
- Security update frequency
- Community size and activity for food-tech related implementations
- Documentation quality and comprehensiveness
5. **Cost Implications:**
- Hosting costs at different user scales (10K, 100K, 1M users)
- Database scaling costs for large recipe collections
- API call costs for grocery store integrations
- Development time estimates for MVP features
### Implementation Considerations
Please address these specific implementation questions:
1. What architecture patterns best support the complex filtering needed for dietary restrictions and preference-based recipe recommendations?
2. How should we implement efficient shopping list generation that consolidates ingredients across multiple recipes while maintaining accurate quantity measurements?
3. What strategies should we employ for caching grocery store pricing data to minimize API calls while keeping prices current?
4. What approaches work best for handling the various units of measurement and ingredient substitutions in recipes?
### Comparative Analysis Request
Please provide a comparative analysis that:
- Directly contrasts the technology options across the evaluation dimensions
- Highlights clear strengths and weaknesses of each approach for food-related applications
- Identifies any potential integration challenges with grocery store APIs
- Suggests optimal combinations of technologies for our specific use case
### Real-world Examples
Please include references to:
- Similar meal planning or recipe applications using these technology stacks
- Case studies of applications with offline-first approaches
- Post-mortems or lessons learned from food-tech implementations
- Any patterns to avoid based on documented failures in similar applications
### Sources to Consider
Please consult:
- Official documentation for each technology
- GitHub repositories of open-source recipe or meal planning applications
- Technical blogs from companies with similar requirements (food delivery, recipe sites)
- Academic papers on efficient food database design and recipe recommendation systems
- Benchmark reports from mobile API performance tests
### Decision Framework
Please conclude with a structured decision framework that:
- Weighs the relative importance of each evaluation dimension for our specific use case
- Provides a scoring methodology for comparing options
- Suggests 2-3 complete technology stack combinations that would best meet our requirements
- Identifies any areas where further, more specific research is needed before making a final decision
</example_research_prompt>

198
BETA-V3/gems-and-gpts/4-po-sm-gem.md Normal file
View File

@@ -0,0 +1,198 @@
# Role: Technical Scrum Master (Story Generator) Agent
<agent_identity>
- Expert Technical Scrum Master / Senior Engineer Lead
- Bridges gap between approved technical plans and executable development tasks
- Specializes in understanding complex requirements and technical designs
- Prepares clear, detailed, self-contained instructions (story files) for developer agents
- Operates autonomously based on documentation ecosystem and repository state
</agent_identity>
<core_capabilities>
- Autonomously prepare the next executable stories in a report for a Developer Agent
- Determine the next logical unit of work based on defined sequences
- Generate self-contained stories following standard templates
- Extract and inject only necessary technical context from documentation
- Operate in dual modes: PO (validation) and SM (story generation)
</core_capabilities>
<output_formatting>
- When presenting documents (drafts or final), provide content in clean format
- DO NOT wrap the entire document in additional outer markdown code blocks
- DO properly format individual elements within the document:
- Mermaid diagrams should be in ```mermaid blocks
- Code snippets should be in appropriate language blocks (e.g., ```javascript)
- Tables should use proper markdown table syntax
- For inline document sections, present the content with proper internal formatting
- For complete documents, begin with a brief introduction followed by the document content
- Individual elements must be properly formatted for correct rendering
- This approach prevents nested markdown issues while maintaining proper formatting
- When creating story files:
- Format each story with clear section titles and boundaries
- Ensure technical references are properly embedded
- Use consistent formatting for requirements and acceptance criteria
</output_formatting>
<reference_documents>
- Epic Files: `docs/epicN.md`
- Story Template: `templates/story-template.txt`
- PO Checklist: `templates/po-checklist.txt`
- Story Draft Checklist: `templates/story-draft-checklist.txt`
- Technical References:
- Architecture: `docs/architecture.md`
- Tech Stack: `docs/tech-stack.md`
- Project Structure: `docs/project-structure.md`
- API Reference: `docs/api-reference.md`
- Data Models: `docs/data-models.md`
- Coding Standards: `docs/coding-standards.md`
- Environment Variables: `docs/environment-vars.md`
- Testing Strategy: `docs/testing-strategy.md`
- UI/UX Specifications: `docs/ui-ux-spec.md` (if applicable)
</reference_documents>
<communication_style>
- Process-driven, meticulous, analytical, precise, technical, autonomous
- Flags missing/contradictory information as blockers
- Primarily interacts with documentation ecosystem and repository state
- Maintains a clear delineation between PO and SM modes
</communication_style>
<workflow_po_mode>
1. **Input Consumption**
- Inform user you are in PO Mode and will start analysis with provided materials
- Receive the complete, refined MVP plan package
- Review latest versions of PRD, architecture, epic files, and reference documents
2. **Apply PO Checklist**
- Systematically work through each item in the PO checklist
- Document whether the plan satisfies each requirement
- Note any deficiencies or concerns
- Assign status (Pass/Fail/Partial) to each major category
3. **Perform Comprehensive Validation Checks**
- Foundational Implementation Logic:
- Project Initialization Check
- Infrastructure Sequence Logic
- User vs. Agent Action Appropriateness
- External Dependencies Management
- Technical Sequence Viability:
- Local Development Capability
- Deployment Prerequisites
- Testing Infrastructure
- Original Validation Criteria:
- Scope/Value Alignment
- Sequence/Dependency Validation
- Holistic PRD Alignment
4. **Apply Real-World Implementation Wisdom**
- Evaluate if new technologies have appropriate learning/proof-of-concept stories
- Check for risk mitigation stories for technically complex components
- Assess strategy for handling potential blockers from external dependencies
- Verify early epics focus on core infrastructure before feature development
5. **Create Checklist Summary**
- Overall checklist completion status
- Pass/Fail/Partial status for each major category
- Specific items that failed validation with clear explanations
- Recommendations for addressing each deficiency
6. **Make Go/No-Go Decision**
- **Approve:** State "Plan Approved" if checklist is satisfactory
- **Reject:** State "Plan Rejected" with specific reasons
- Include actionable feedback for revision if rejected
7. **Specific Checks for Common Issues**
- Verify Epic 1 includes all necessary project setup steps
- Confirm infrastructure is established before being used
- Check deployment pipelines are created before deployment actions
- Ensure user actions are limited to what requires human intervention
- Verify external dependencies are properly accounted for
- Confirm logical progression from infrastructure to features
</workflow_po_mode>
<workflow_sm_mode>
1. **Check Prerequisite State**
- Understand the PRD, Architecture Documents, and completed/in-progress stories
- Verify which epics and stories are already completed or in progress
2. **Identify Next Stories**
- Identify all remaining epics and their stories from the provided source material
- Determine which stories are not complete based on status information
3. **Gather Technical & Historical Context**
- Extract only the specific, relevant information from reference documents:
- Architecture: Only sections relevant to components being modified
- Project Structure: Only specific paths relevant to the story
- Tech Stack: Only technologies directly used in the story
- API Reference: Only specific endpoints or services relevant to the story
- Data Models: Only specific data models/entities used in the story
- Coding Standards: Only story-specific exceptions or particularly relevant patterns
- Environment Variables: Only specific variables needed for the story
- Testing Strategy: Only testing approach relevant to specific components
- UI/UX Spec: Only mockups/flows for UI elements being developed (if applicable)
- Review any completed stories for relevant context
4. **Populate Story Template for Each Story**
- Load content structure from story template
- Fill in standard information (Title, Goal, Requirements, ACs, Tasks)
- Set Status to "Draft" initially
- Inject only story-specific technical context into appropriate sections
- Include references rather than repetition for standard documents
- Detail specific testing requirements with clear instructions
5. **Validate Story Completeness**
- Apply the story draft checklist to ensure sufficient context
- Focus on providing adequate information while allowing reasonable problem-solving
- Identify and address critical gaps
- Note if information is missing from source documents
6. **Generate Stories Report**
- Create a comprehensive report with all remaining stories
- Format each story with clear section titles: `File: ai/stories/{epicNumber}.{storyNumber}.story.md`
- Ensure clear delineation between stories for easy separation
- Organize stories in logical sequence based on dependencies
7. **Complete All Stories**
- Generate all sequential stories in order until all epics are covered
- If user specified a range, limit to that range
- Otherwise, proceed through all remaining epics and stories
</workflow_sm_mode>
<dual_mode_operations>
1. **Mode Selection**
- Start in PO Mode by default to validate the overall plan
- Only transition to SM Mode after plan is approved or user explicitly requests mode change
- Clearly indicate current mode in communications with user
2. **PO to SM Transition**
- Once plan is approved in PO Mode, inform user you are transitioning to SM Mode
- Summarize PO Mode findings before switching
- Begin SM workflow to generate stories
3. **Report Generation**
- In SM Mode, generate a comprehensive report with all stories
- Format each story following the standard template
- Ensure clear separation between stories for easy extraction
</dual_mode_operations>

36
BETA-V3/gems-and-gpts/instruction.md Normal file
View File

@@ -0,0 +1,36 @@
# Instructions
## Gemini Gem 2.5
- https://gemini.google.com/gems/view
- Client + New Gem
- Name: I recommend starting with a number or a unique letter as this will be easiest way to identify the gem. For Example 1-Analyst, 2-PM etc...
- Instructions: Paste full content from the specific gem.md file
- Knowledge: Add the specific Text files for the specific agent as listed below - along with other potential instructions you might want to give it. For example - if you know your architect will always follow or should follow a specific stack, you could give it another document for suggested architecture or tech stack to always use, or your patter preferences, and not have to specify every time. But you can also just go with keeping it more generic and use the files from this repo.
### Analyst (BA/RA)
- Instructions: 1-analyst-gem.md pasted into instructions
- Knowledge: templates/project-brief.txt
- During Chat - Mode 1 - 2.5 Pro Deep Research recommended. Mode 2 2.5 Pro Thinking Mode + optional mode 1 deep research attached.
### Product Manager (PM)
- Instructions: 2-pm-gem.md pasted into instructions
- Knowledge: templates/prd.txt, templates/epicN.txt, templates/ui-ux-spec.txt, templates/pm-checklist.txt
- During Chat - Mode 1 - 2.5 Pro Deep Research recommended. Mode 2 2.5 Pro Thinking Mode. Start by also attaching the product brief.
### Architect
- Instructions: 3-architect-gem.md pasted into instructions
- Knowledge: templates/architecture-templates.txt, templates/architect-checklist.txt
- During Chat - Mode 1 - 2.5 Pro Deep Research recommended. Mode 2 2.5 Pro Thinking Mode. Start by also attaching the product brief, PRD, and any generated Epic files. If architecture deep research was done as mode 1, attach it to the new chat. Also if there was deep research from the PRD that is not fully distilled in the PRD (deep technical details or solutions), provide to the architect.
### PO + SM
- Instructions: 4-po-sm-gem.md pasted into instructions
- Knowledge: templates/story-template.txt, templates/po-checklist.txt
- This is optional as a Gem - unlike the workflow within the IDE, using this will generate all remaining stories as one output, instead generating each story when its ready to be worked on through completion. There is ONE main use case for this beyond the obvious generating the artifacts to work on one at a time.
- The output of this can easily be passed to a new chat with this PO + SM gem or custom GPT and asked to deeply think or analyze through all of the extensive details to spot potential issues gaps, or inconsistences. I have not done this as I prefer to just generate and build 1 story at a time - so the utility of this I have not fully exhausted - but its an interesting idea.
- During chat: Recommend starting chat by providing all possible artifacts output from previous stages - if a file limit is hit, you can attach as a folder in thinking mode for 2.5 pro - or combine documents. The SM needs latest versions of `prd.md`, `architecture.md`, the _technically enriched_ `epicN.md...` files, and relevant reference documents the architecture references, provided after initial PM/Architect collaboration and refinement.
- The IDE version (agents folder) of the SM works on producing 1 story at a time for the dev to work on. This version is a bit different in that it will produce a single document with all remaining stories fully fleshed out at once, which then can be worked on still one on one in the IDE.

259
BETA-V3/gems-and-gpts/templates/architect-checklist.txt Normal file
View File

@@ -0,0 +1,259 @@
# Architect Solution Validation Checklist
This checklist serves as a comprehensive framework for the Architect to validate the technical design and architecture before development execution. The Architect should systematically work through each item, ensuring the architecture is robust, scalable, secure, and aligned with the product requirements.
## 1. REQUIREMENTS ALIGNMENT
### 1.1 Functional Requirements Coverage
- [ ] Architecture supports all functional requirements in the PRD
- [ ] Technical approaches for all epics and stories are addressed
- [ ] Edge cases and performance scenarios are considered
- [ ] All required integrations are accounted for
- [ ] User journeys are supported by the technical architecture
### 1.2 Non-Functional Requirements Alignment
- [ ] Performance requirements are addressed with specific solutions
- [ ] Scalability considerations are documented with approach
- [ ] Security requirements have corresponding technical controls
- [ ] Reliability and resilience approaches are defined
- [ ] Compliance requirements have technical implementations
### 1.3 Technical Constraints Adherence
- [ ] All technical constraints from PRD are satisfied
- [ ] Platform/language requirements are followed
- [ ] Infrastructure constraints are accommodated
- [ ] Third-party service constraints are addressed
- [ ] Organizational technical standards are followed
## 2. ARCHITECTURE FUNDAMENTALS
### 2.1 Architecture Clarity
- [ ] Architecture is documented with clear diagrams
- [ ] Major components and their responsibilities are defined
- [ ] Component interactions and dependencies are mapped
- [ ] Data flows are clearly illustrated
- [ ] Technology choices for each component are specified
### 2.2 Separation of Concerns
- [ ] Clear boundaries between UI, business logic, and data layers
- [ ] Responsibilities are cleanly divided between components
- [ ] Interfaces between components are well-defined
- [ ] Components adhere to single responsibility principle
- [ ] Cross-cutting concerns (logging, auth, etc.) are properly addressed
### 2.3 Design Patterns & Best Practices
- [ ] Appropriate design patterns are employed
- [ ] Industry best practices are followed
- [ ] Anti-patterns are avoided
- [ ] Consistent architectural style throughout
- [ ] Pattern usage is documented and explained
### 2.4 Modularity & Maintainability
- [ ] System is divided into cohesive, loosely-coupled modules
- [ ] Components can be developed and tested independently
- [ ] Changes can be localized to specific components
- [ ] Code organization promotes discoverability
- [ ] Architecture specifically designed for AI agent implementation
## 3. TECHNICAL STACK & DECISIONS
### 3.1 Technology Selection
- [ ] Selected technologies meet all requirements
- [ ] Technology versions are specifically defined (not ranges)
- [ ] Technology choices are justified with clear rationale
- [ ] Alternatives considered are documented with pros/cons
- [ ] Selected stack components work well together
### 3.2 Frontend Architecture
- [ ] UI framework and libraries are specifically selected
- [ ] State management approach is defined
- [ ] Component structure and organization is specified
- [ ] Responsive/adaptive design approach is outlined
- [ ] Build and bundling strategy is determined
### 3.3 Backend Architecture
- [ ] API design and standards are defined
- [ ] Service organization and boundaries are clear
- [ ] Authentication and authorization approach is specified
- [ ] Error handling strategy is outlined
- [ ] Backend scaling approach is defined
### 3.4 Data Architecture
- [ ] Data models are fully defined
- [ ] Database technologies are selected with justification
- [ ] Data access patterns are documented
- [ ] Data migration/seeding approach is specified
- [ ] Data backup and recovery strategies are outlined
## 4. RESILIENCE & OPERATIONAL READINESS
### 4.1 Error Handling & Resilience
- [ ] Error handling strategy is comprehensive
- [ ] Retry policies are defined where appropriate
- [ ] Circuit breakers or fallbacks are specified for critical services
- [ ] Graceful degradation approaches are defined
- [ ] System can recover from partial failures
### 4.2 Monitoring & Observability
- [ ] Logging strategy is defined
- [ ] Monitoring approach is specified
- [ ] Key metrics for system health are identified
- [ ] Alerting thresholds and strategies are outlined
- [ ] Debugging and troubleshooting capabilities are built in
### 4.3 Performance & Scaling
- [ ] Performance bottlenecks are identified and addressed
- [ ] Caching strategy is defined where appropriate
- [ ] Load balancing approach is specified
- [ ] Horizontal and vertical scaling strategies are outlined
- [ ] Resource sizing recommendations are provided
### 4.4 Deployment & DevOps
- [ ] Deployment strategy is defined
- [ ] CI/CD pipeline approach is outlined
- [ ] Environment strategy (dev, staging, prod) is specified
- [ ] Infrastructure as Code approach is defined
- [ ] Rollback and recovery procedures are outlined
## 5. SECURITY & COMPLIANCE
### 5.1 Authentication & Authorization
- [ ] Authentication mechanism is clearly defined
- [ ] Authorization model is specified
- [ ] Role-based access control is outlined if required
- [ ] Session management approach is defined
- [ ] Credential management is addressed
### 5.2 Data Security
- [ ] Data encryption approach (at rest and in transit) is specified
- [ ] Sensitive data handling procedures are defined
- [ ] Data retention and purging policies are outlined
- [ ] Backup encryption is addressed if required
- [ ] Data access audit trails are specified if required
### 5.3 API & Service Security
- [ ] API security controls are defined
- [ ] Rate limiting and throttling approaches are specified
- [ ] Input validation strategy is outlined
- [ ] CSRF/XSS prevention measures are addressed
- [ ] Secure communication protocols are specified
### 5.4 Infrastructure Security
- [ ] Network security design is outlined
- [ ] Firewall and security group configurations are specified
- [ ] Service isolation approach is defined
- [ ] Least privilege principle is applied
- [ ] Security monitoring strategy is outlined
## 6. IMPLEMENTATION GUIDANCE
### 6.1 Coding Standards & Practices
- [ ] Coding standards are defined
- [ ] Documentation requirements are specified
- [ ] Testing expectations are outlined
- [ ] Code organization principles are defined
- [ ] Naming conventions are specified
### 6.2 Testing Strategy
- [ ] Unit testing approach is defined
- [ ] Integration testing strategy is outlined
- [ ] E2E testing approach is specified
- [ ] Performance testing requirements are outlined
- [ ] Security testing approach is defined
### 6.3 Development Environment
- [ ] Local development environment setup is documented
- [ ] Required tools and configurations are specified
- [ ] Development workflows are outlined
- [ ] Source control practices are defined
- [ ] Dependency management approach is specified
### 6.4 Technical Documentation
- [ ] API documentation standards are defined
- [ ] Architecture documentation requirements are specified
- [ ] Code documentation expectations are outlined
- [ ] System diagrams and visualizations are included
- [ ] Decision records for key choices are included
## 7. DEPENDENCY & INTEGRATION MANAGEMENT
### 7.1 External Dependencies
- [ ] All external dependencies are identified
- [ ] Versioning strategy for dependencies is defined
- [ ] Fallback approaches for critical dependencies are specified
- [ ] Licensing implications are addressed
- [ ] Update and patching strategy is outlined
### 7.2 Internal Dependencies
- [ ] Component dependencies are clearly mapped
- [ ] Build order dependencies are addressed
- [ ] Shared services and utilities are identified
- [ ] Circular dependencies are eliminated
- [ ] Versioning strategy for internal components is defined
### 7.3 Third-Party Integrations
- [ ] All third-party integrations are identified
- [ ] Integration approaches are defined
- [ ] Authentication with third parties is addressed
- [ ] Error handling for integration failures is specified
- [ ] Rate limits and quotas are considered
## 8. AI AGENT IMPLEMENTATION SUITABILITY
### 8.1 Modularity for AI Agents
- [ ] Components are sized appropriately for AI agent implementation
- [ ] Dependencies between components are minimized
- [ ] Clear interfaces between components are defined
- [ ] Components have singular, well-defined responsibilities
- [ ] File and code organization optimized for AI agent understanding
### 8.2 Clarity & Predictability
- [ ] Patterns are consistent and predictable
- [ ] Complex logic is broken down into simpler steps
- [ ] Architecture avoids overly clever or obscure approaches
- [ ] Examples are provided for unfamiliar patterns
- [ ] Component responsibilities are explicit and clear
### 8.3 Implementation Guidance
- [ ] Detailed implementation guidance is provided
- [ ] Code structure templates are defined
- [ ] Specific implementation patterns are documented
- [ ] Common pitfalls are identified with solutions
- [ ] References to similar implementations are provided when helpful
### 8.4 Error Prevention & Handling
- [ ] Design reduces opportunities for implementation errors
- [ ] Validation and error checking approaches are defined
- [ ] Self-healing mechanisms are incorporated where possible
- [ ] Testing patterns are clearly defined
- [ ] Debugging guidance is provided

555
BETA-V3/gems-and-gpts/templates/architecture-templates.txt Normal file
View File

@@ -0,0 +1,555 @@
# Architecture Sub Document Templates
## Master Architecture Template
```Markdown
# {Project Name} Architecture Document
## 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.}
## 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.}
```mermaid
{Insert high-level system context or interaction diagram here - e.g., using Mermaid graph TD or C4 Model Context Diagram}
```
## 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}
```
- 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
{List significant architectural choices and the patterns employed.}
- 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)
## Core Workflow / Sequence Diagrams (Optional)
{Illustrate key or complex workflows using sequence diagrams if helpful.}
## 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 2:** {e.g., Dependency Injection, Repository Pattern, Module Pattern} - _Rationale/Reference:_ {...}
- **Pattern N:** {...}
## Coding Standards (Consider adding these to Dev Agent Context or Rules)
- **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.}
## Error Handling Strategy
- **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.}
## 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...}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
## Data Models Template
```Markdown
# {Project Name} Data Models
## 2. 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}
- **Description:** {What does this entity represent?}
- **Schema / Interface Definition:**
```typescript
// Example using TypeScript Interface
export interface {EntityName} {
id: string; // {Description, e.g., Unique identifier}
propertyName: string; // {Description}
optionalProperty?: number; // {Description}
// ... other properties
}
```
_(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}
{...}
## 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`.}
### {API Endpoint / Purpose, e.g., Create Order Request}
- **Schema / Interface Definition:**
```typescript
// Example
export interface CreateOrderRequest {
customerId: string;
items: { productId: string; quantity: number }[];
// ...
}
```
### {Another API Payload}
{...}
## Database Schemas (If applicable)
{If using a database, define table structures or document database schemas.}
### {Table / Collection Name}
- **Purpose:** {What data does this table store?}
- **Schema Definition:**
```sql
-- Example SQL
CREATE TABLE {TableName} (
id VARCHAR(36) PRIMARY KEY,
column_name VARCHAR(255) NOT NULL,
numeric_column DECIMAL(10, 2),
-- ... other columns, indexes, constraints
);
```
_(Alternatively, use ORM model definitions, NoSQL document structure, etc.)_
### {Another Table / Collection Name}
{...}
## State File Schemas (If applicable)
{If the application uses files for persisting state.}
### {State File Name / Purpose, e.g., processed_items.json}
- **Purpose:** {What state does this file track?}
- **Format:** {e.g., JSON}
- **Schema Definition:**
```json
{
"type": "object",
"properties": {
"processedIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of IDs that have been processed."
}
// ... other state properties
},
"required": ["processedIds"]
}
```
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
## Environment Vars Templates
```Markdown
# {Project Name} Environment Variables
## 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} |
| ... | ... | ... | ... | ... |
## 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
| Category | Technology | Version / Details | Description / Purpose | Justification (Optional) |
| :------------------- | :---------------------- | :---------------- | :-------------------------------------- | :----------------------- |
| **Languages** | {e.g., TypeScript} | {e.g., 5.x} | {Primary language for backend/frontend} | {Why this language?} |
| | {e.g., Python} | {e.g., 3.11} | {Used for data processing, ML} | {...} |
| **Runtime** | {e.g., Node.js} | {e.g., 22.x} | {Server-side execution environment} | {...} |
| **Frameworks** | {e.g., NestJS} | {e.g., 10.x} | {Backend API framework} | {Why this framework?} |
| | {e.g., React} | {e.g., 18.x} | {Frontend UI library} | {...} |
| **Databases** | {e.g., PostgreSQL} | {e.g., 15} | {Primary relational data store} | {...} |
| | {e.g., Redis} | {e.g., 7.x} | {Caching, session storage} | {...} |
| **Cloud Platform** | {e.g., AWS} | {N/A} | {Primary cloud provider} | {...} |
| **Cloud Services** | {e.g., AWS Lambda} | {N/A} | {Serverless compute} | {...} |
| | {e.g., AWS S3} | {N/A} | {Object storage for assets/state} | {...} |
| | {e.g., AWS EventBridge} | {N/A} | {Event bus / scheduled tasks} | {...} |
| **Infrastructure** | {e.g., AWS CDK} | {e.g., Latest} | {Infrastructure as Code tool} | {...} |
| | {e.g., Docker} | {e.g., Latest} | {Containerization} | {...} |
| **UI Libraries** | {e.g., Material UI} | {e.g., 5.x} | {React component library} | {...} |
| **State Management** | {e.g., Redux Toolkit} | {e.g., Latest} | {Frontend state management} | {...} |
| **Testing** | {e.g., Jest} | {e.g., Latest} | {Unit/Integration testing framework} | {...} |
| | {e.g., Playwright} | {e.g., Latest} | {End-to-end testing framework} | {...} |
| **CI/CD** | {e.g., GitHub Actions} | {N/A} | {Continuous Integration/Deployment} | {...} |
| **Other Tools** | {e.g., LangChain.js} | {e.g., Latest} | {LLM interaction library} | {...} |
| | {e.g., Cheerio} | {e.g., Latest} | {HTML parsing/scraping} | {...} |
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... |
```
## Testing Strategy Template
```Markdown
# {Project Name} Testing Strategy
## Overall Philosophy & Goals
{Describe the high-level approach. e.g., "Follow the Testing Pyramid/Trophy principle.", "Automate extensively.", "Focus on testing business logic and key integrations.", "Ensure tests run efficiently in CI/CD."}
- Goal 1: {e.g., Achieve X% code coverage for critical modules.}
- Goal 2: {e.g., Prevent regressions in core functionality.}
- Goal 3: {e.g., Enable confident refactoring.}
## Testing Levels
### Unit Tests
- **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`)}
- **Expectations:** {e.g., Should cover all significant logic paths. Fast execution.}
### Integration Tests
- **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/`}
- **Expectations:** {e.g., Focus on module boundaries and contracts. Slower than unit tests.}
### End-to-End (E2E) / Acceptance Tests
- **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/`}
- **Expectations:** {Cover critical user paths. Slower, potentially flaky, run less frequently (e.g., pre-release, nightly).}
### Manual / Exploratory Testing (Optional)
- **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)
### Performance Testing
- **Scope & Goals:** {What needs performance testing? What are the targets (latency, throughput)?}
- **Tools:** {e.g., K6, JMeter, Locust}
### Security Testing
- **Scope & Goals:** {e.g., Dependency scanning, SAST, DAST, penetration testing requirements.}
- **Tools:** {e.g., Snyk, OWASP ZAP, Dependabot}
### Accessibility Testing (UI)
- **Scope & Goals:** {Target WCAG level, key areas.}
- **Tools:** {e.g., Axe, Lighthouse, manual checks}
### Visual Regression Testing (UI)
- **Scope & Goals:** {Prevent unintended visual changes.}
- **Tools:** {e.g., Percy, Applitools Eyes, Playwright visual comparisons}
## Test Data Management
{How is test data generated, managed, and reset for different testing levels?}
## CI/CD Integration
{How and when are tests executed in the CI/CD pipeline? What constitutes a pipeline failure?}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------- | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial draft | {Agent/Person} |
| ... | ... | ... | ... | ... |
```
## 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} |
| ... | ... | ... | ... | ... |
```

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

@@ -0,0 +1,44 @@
# 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 |
| ------------- | ---------- | ------- | ------------------------------ | -------------- |

239
BETA-V3/gems-and-gpts/templates/pm-checklist.txt Normal file
View File

@@ -0,0 +1,239 @@
# Product Manager (PM) Requirements Checklist
This checklist serves as a comprehensive framework to ensure the Product Requirements Document (PRD) and Epic definitions are complete, well-structured, and appropriately scoped for MVP development. The PM should systematically work through each item during the product definition process.
## 1. PROBLEM DEFINITION & CONTEXT
### 1.1 Problem Statement
- [ ] Clear articulation of the problem being solved
- [ ] Identification of who experiences the problem
- [ ] Explanation of why solving this problem matters
- [ ] Quantification of problem impact (if possible)
- [ ] Differentiation from existing solutions
### 1.2 Business Goals & Success Metrics
- [ ] Specific, measurable business objectives defined
- [ ] Clear success metrics and KPIs established
- [ ] Metrics are tied to user and business value
- [ ] Baseline measurements identified (if applicable)
- [ ] Timeframe for achieving goals specified
### 1.3 User Research & Insights
- [ ] Target user personas clearly defined
- [ ] User needs and pain points documented
- [ ] User research findings summarized (if available)
- [ ] Competitive analysis included
- [ ] Market context provided
## 2. MVP SCOPE DEFINITION
### 2.1 Core Functionality
- [ ] Essential features clearly distinguished from nice-to-haves
- [ ] Features directly address defined problem statement
- [ ] Each Epic ties back to specific user needs
- [ ] Features and Stories are described from user perspective
- [ ] Minimum requirements for success defined
### 2.2 Scope Boundaries
- [ ] Clear articulation of what is OUT of scope
- [ ] Future enhancements section included
- [ ] Rationale for scope decisions documented
- [ ] MVP minimizes functionality while maximizing learning
- [ ] Scope has been reviewed and refined multiple times
### 2.3 MVP Validation Approach
- [ ] Method for testing MVP success defined
- [ ] Initial user feedback mechanisms planned
- [ ] Criteria for moving beyond MVP specified
- [ ] Learning goals for MVP articulated
- [ ] Timeline expectations set
## 3. USER EXPERIENCE REQUIREMENTS
### 3.1 User Journeys & Flows
- [ ] Primary user flows documented
- [ ] Entry and exit points for each flow identified
- [ ] Decision points and branches mapped
- [ ] Critical path highlighted
- [ ] Edge cases considered
### 3.2 Usability Requirements
- [ ] Accessibility considerations documented
- [ ] Platform/device compatibility specified
- [ ] Performance expectations from user perspective defined
- [ ] Error handling and recovery approaches outlined
- [ ] User feedback mechanisms identified
### 3.3 UI Requirements
- [ ] Information architecture outlined
- [ ] Critical UI components identified
- [ ] Visual design guidelines referenced (if applicable)
- [ ] Content requirements specified
- [ ] High-level navigation structure defined
## 4. FUNCTIONAL REQUIREMENTS
### 4.1 Feature Completeness
- [ ] All required features for MVP documented
- [ ] Features have clear, user-focused descriptions
- [ ] Feature priority/criticality indicated
- [ ] Requirements are testable and verifiable
- [ ] Dependencies between features identified
### 4.2 Requirements Quality
- [ ] Requirements are specific and unambiguous
- [ ] Requirements focus on WHAT not HOW
- [ ] Requirements use consistent terminology
- [ ] Complex requirements broken into simpler parts
- [ ] Technical jargon minimized or explained
### 4.3 User Stories & Acceptance Criteria
- [ ] Stories follow consistent format
- [ ] Acceptance criteria are testable
- [ ] Stories are sized appropriately (not too large)
- [ ] Stories are independent where possible
- [ ] Stories include necessary context
- [ ] Local testability requirements (e.g., via CLI) defined in ACs for relevant backend/data stories
## 5. NON-FUNCTIONAL REQUIREMENTS
### 5.1 Performance Requirements
- [ ] Response time expectations defined
- [ ] Throughput/capacity requirements specified
- [ ] Scalability needs documented
- [ ] Resource utilization constraints identified
- [ ] Load handling expectations set
### 5.2 Security & Compliance
- [ ] Data protection requirements specified
- [ ] Authentication/authorization needs defined
- [ ] Compliance requirements documented
- [ ] Security testing requirements outlined
- [ ] Privacy considerations addressed
### 5.3 Reliability & Resilience
- [ ] Availability requirements defined
- [ ] Backup and recovery needs documented
- [ ] Fault tolerance expectations set
- [ ] Error handling requirements specified
- [ ] Maintenance and support considerations included
### 5.4 Technical Constraints
- [ ] Platform/technology constraints documented
- [ ] Integration requirements outlined
- [ ] Third-party service dependencies identified
- [ ] Infrastructure requirements specified
- [ ] Development environment needs identified
## 6. EPIC & STORY STRUCTURE
### 6.1 Epic Definition
- [ ] Epics represent cohesive units of functionality
- [ ] Epics focus on user/business value delivery
- [ ] Epic goals clearly articulated
- [ ] Epics are sized appropriately for incremental delivery
- [ ] Epic sequence and dependencies identified
### 6.2 Story Breakdown
- [ ] Stories are broken down to appropriate size
- [ ] Stories have clear, independent value
- [ ] Stories include appropriate acceptance criteria
- [ ] Story dependencies and sequence documented
- [ ] Stories aligned with epic goals
### 6.3 First Epic Completeness
- [ ] First epic includes all necessary setup steps
- [ ] Project scaffolding and initialization addressed
- [ ] Core infrastructure setup included
- [ ] Development environment setup addressed
- [ ] Local testability established early
## 7. TECHNICAL GUIDANCE
### 7.1 Architecture Guidance
- [ ] Initial architecture direction provided
- [ ] Technical constraints clearly communicated
- [ ] Integration points identified
- [ ] Performance considerations highlighted
- [ ] Security requirements articulated
- [ ] Known areas of high complexity or technical risk flagged for architectural deep-dive
### 7.2 Technical Decision Framework
- [ ] Decision criteria for technical choices provided
- [ ] Trade-offs articulated for key decisions
- [ ] Rationale for selecting primary approach over considered alternatives documented (for key design/feature choices)
- [ ] Non-negotiable technical requirements highlighted
- [ ] Areas requiring technical investigation identified
- [ ] Guidance on technical debt approach provided
### 7.3 Implementation Considerations
- [ ] Development approach guidance provided
- [ ] Testing requirements articulated
- [ ] Deployment expectations set
- [ ] Monitoring needs identified
- [ ] Documentation requirements specified
## 8. CROSS-FUNCTIONAL REQUIREMENTS
### 8.1 Data Requirements
- [ ] Data entities and relationships identified
- [ ] Data storage requirements specified
- [ ] Data quality requirements defined
- [ ] Data retention policies identified
- [ ] Data migration needs addressed (if applicable)
- [ ] Schema changes planned iteratively, tied to stories requiring them
### 8.2 Integration Requirements
- [ ] External system integrations identified
- [ ] API requirements documented
- [ ] Authentication for integrations specified
- [ ] Data exchange formats defined
- [ ] Integration testing requirements outlined
### 8.3 Operational Requirements
- [ ] Deployment frequency expectations set
- [ ] Environment requirements defined
- [ ] Monitoring and alerting needs identified
- [ ] Support requirements documented
- [ ] Performance monitoring approach specified
## 9. CLARITY & COMMUNICATION
### 9.1 Documentation Quality
- [ ] Documents use clear, consistent language
- [ ] Documents are well-structured and organized
- [ ] Technical terms are defined where necessary
- [ ] Diagrams/visuals included where helpful
- [ ] Documentation is versioned appropriately
### 9.2 Stakeholder Alignment
- [ ] Key stakeholders identified
- [ ] Stakeholder input incorporated
- [ ] Potential areas of disagreement addressed
- [ ] Communication plan for updates established
- [ ] Approval process defined
## PRD & EPIC VALIDATION SUMMARY
### Category Statuses
| Category | Status | Critical Issues |
|----------|--------|----------------|
| 1. Problem Definition & Context | PASS/FAIL/PARTIAL | |
| 2. MVP Scope Definition | PASS/FAIL/PARTIAL | |
| 3. User Experience Requirements | PASS/FAIL/PARTIAL | |
| 4. Functional Requirements | PASS/FAIL/PARTIAL | |
| 5. Non-Functional Requirements | PASS/FAIL/PARTIAL | |
| 6. Epic & Story Structure | PASS/FAIL/PARTIAL | |
| 7. Technical Guidance | PASS/FAIL/PARTIAL | |
| 8. Cross-Functional Requirements | PASS/FAIL/PARTIAL | |
| 9. Clarity & Communication | PASS/FAIL/PARTIAL | |
### Critical Deficiencies
- List all critical issues that must be addressed before handoff to Architect
### Recommendations
- Provide specific recommendations for addressing each deficiency
### Final Decision
- **READY FOR ARCHITECT**: The PRD and epics are comprehensive, properly structured, and ready for architectural design.
- **NEEDS REFINEMENT**: The requirements documentation requires additional work to address the identified deficiencies.

200
BETA-V3/gems-and-gpts/templates/po-checklist.txt Normal file
View File

@@ -0,0 +1,200 @@
# Product Owner (PO) Validation Checklist
This checklist serves as a comprehensive framework for the Product Owner to validate the complete MVP plan before development execution. The PO should systematically work through each item, documenting compliance status and noting any deficiencies.
## 1. PROJECT SETUP & INITIALIZATION
### 1.1 Project Scaffolding
- [ ] Epic 1 includes explicit steps for project creation/initialization
- [ ] If using a starter template, steps for cloning/setup are included
- [ ] If building from scratch, all necessary scaffolding steps are defined
- [ ] Initial README or documentation setup is included
- [ ] Repository setup and initial commit processes are defined (if applicable)
### 1.2 Development Environment
- [ ] Local development environment setup is clearly defined
- [ ] Required tools and versions are specified (Node.js, Python, etc.)
- [ ] Steps for installing dependencies are included
- [ ] Configuration files (dotenv, config files, etc.) are addressed
- [ ] Development server setup is included
### 1.3 Core Dependencies
- [ ] All critical packages/libraries are installed early in the process
- [ ] Package management (npm, pip, etc.) is properly addressed
- [ ] Version specifications are appropriately defined
- [ ] Dependency conflicts or special requirements are noted
## 2. INFRASTRUCTURE & DEPLOYMENT SEQUENCING
### 2.1 Database & Data Store Setup
- [ ] Database selection/setup occurs before any database operations
- [ ] Schema definitions are created before data operations
- [ ] Migration strategies are defined if applicable
- [ ] Seed data or initial data setup is included if needed
- [ ] Database access patterns and security are established early
### 2.2 API & Service Configuration
- [ ] API frameworks are set up before implementing endpoints
- [ ] Service architecture is established before implementing services
- [ ] Authentication framework is set up before protected routes
- [ ] Middleware and common utilities are created before use
### 2.3 Deployment Pipeline
- [ ] CI/CD pipeline is established before any deployment actions
- [ ] Infrastructure as Code (IaC) is set up before use
- [ ] Environment configurations (dev, staging, prod) are defined early
- [ ] Deployment strategies are defined before implementation
- [ ] Rollback procedures or considerations are addressed
### 2.4 Testing Infrastructure
- [ ] Testing frameworks are installed before writing tests
- [ ] Test environment setup precedes test implementation
- [ ] Mock services or data are defined before testing
- [ ] Test utilities or helpers are created before use
## 3. EXTERNAL DEPENDENCIES & INTEGRATIONS
### 3.1 Third-Party Services
- [ ] Account creation steps are identified for required services
- [ ] API key acquisition processes are defined
- [ ] Steps for securely storing credentials are included
- [ ] Fallback or offline development options are considered
### 3.2 External APIs
- [ ] Integration points with external APIs are clearly identified
- [ ] Authentication with external services is properly sequenced
- [ ] API limits or constraints are acknowledged
- [ ] Backup strategies for API failures are considered
### 3.3 Infrastructure Services
- [ ] Cloud resource provisioning is properly sequenced
- [ ] DNS or domain registration needs are identified
- [ ] Email or messaging service setup is included if needed
- [ ] CDN or static asset hosting setup precedes their use
## 4. USER/AGENT RESPONSIBILITY DELINEATION
### 4.1 User Actions
- [ ] User responsibilities are limited to only what requires human intervention
- [ ] Account creation on external services is properly assigned to users
- [ ] Purchasing or payment actions are correctly assigned to users
- [ ] Credential provision is appropriately assigned to users
### 4.2 Developer Agent Actions
- [ ] All code-related tasks are assigned to developer agents
- [ ] Automated processes are correctly identified as agent responsibilities
- [ ] Configuration management is properly assigned
- [ ] Testing and validation are assigned to appropriate agents
## 5. FEATURE SEQUENCING & DEPENDENCIES
### 5.1 Functional Dependencies
- [ ] Features that depend on other features are sequenced correctly
- [ ] Shared components are built before their use
- [ ] User flows follow a logical progression
- [ ] Authentication features precede protected routes/features
### 5.2 Technical Dependencies
- [ ] Lower-level services are built before higher-level ones
- [ ] Libraries and utilities are created before their use
- [ ] Data models are defined before operations on them
- [ ] API endpoints are defined before client consumption
### 5.3 Cross-Epic Dependencies
- [ ] Later epics build upon functionality from earlier epics
- [ ] No epic requires functionality from later epics
- [ ] Infrastructure established in early epics is utilized consistently
- [ ] Incremental value delivery is maintained
## 6. MVP SCOPE ALIGNMENT
### 6.1 PRD Goals Alignment
- [ ] All core goals defined in the PRD are addressed in epics/stories
- [ ] Features directly support the defined MVP goals
- [ ] No extraneous features beyond MVP scope are included
- [ ] Critical features are prioritized appropriately
### 6.2 User Journey Completeness
- [ ] All critical user journeys are fully implemented
- [ ] Edge cases and error scenarios are addressed
- [ ] User experience considerations are included
- [ ] Accessibility requirements are incorporated if specified
### 6.3 Technical Requirements Satisfaction
- [ ] All technical constraints from the PRD are addressed
- [ ] Non-functional requirements are incorporated
- [ ] Architecture decisions align with specified constraints
- [ ] Performance considerations are appropriately addressed
## 7. RISK MANAGEMENT & PRACTICALITY
### 7.1 Technical Risk Mitigation
- [ ] Complex or unfamiliar technologies have appropriate learning/prototyping stories
- [ ] High-risk components have explicit validation steps
- [ ] Fallback strategies exist for risky integrations
- [ ] Performance concerns have explicit testing/validation
### 7.2 External Dependency Risks
- [ ] Risks with third-party services are acknowledged and mitigated
- [ ] API limits or constraints are addressed
- [ ] Backup strategies exist for critical external services
- [ ] Cost implications of external services are considered
### 7.3 Timeline Practicality
- [ ] Story complexity and sequencing suggest a realistic timeline
- [ ] Dependencies on external factors are minimized or managed
- [ ] Parallel work is enabled where possible
- [ ] Critical path is identified and optimized
## 8. DOCUMENTATION & HANDOFF
### 8.1 Developer Documentation
- [ ] API documentation is created alongside implementation
- [ ] Setup instructions are comprehensive
- [ ] Architecture decisions are documented
- [ ] Patterns and conventions are documented
### 8.2 User Documentation
- [ ] User guides or help documentation is included if required
- [ ] Error messages and user feedback are considered
- [ ] Onboarding flows are fully specified
- [ ] Support processes are defined if applicable
## 9. POST-MVP CONSIDERATIONS
### 9.1 Future Enhancements
- [ ] Clear separation between MVP and future features
- [ ] Architecture supports planned future enhancements
- [ ] Technical debt considerations are documented
- [ ] Extensibility points are identified
### 9.2 Feedback Mechanisms
- [ ] Analytics or usage tracking is included if required
- [ ] User feedback collection is considered
- [ ] Monitoring and alerting are addressed
- [ ] Performance measurement is incorporated
## VALIDATION SUMMARY
### Category Statuses
| Category | Status | Critical Issues |
|----------|--------|----------------|
| 1. Project Setup & Initialization | PASS/FAIL/PARTIAL | |
| 2. Infrastructure & Deployment Sequencing | PASS/FAIL/PARTIAL | |
| 3. External Dependencies & Integrations | PASS/FAIL/PARTIAL | |
| 4. User/Agent Responsibility Delineation | PASS/FAIL/PARTIAL | |
| 5. Feature Sequencing & Dependencies | PASS/FAIL/PARTIAL | |
| 6. MVP Scope Alignment | PASS/FAIL/PARTIAL | |
| 7. Risk Management & Practicality | PASS/FAIL/PARTIAL | |
| 8. Documentation & Handoff | PASS/FAIL/PARTIAL | |
| 9. Post-MVP Considerations | PASS/FAIL/PARTIAL | |
### Critical Deficiencies
- List all critical issues that must be addressed before approval
### Recommendations
- Provide specific recommendations for addressing each deficiency
### Final Decision
- **APPROVED**: The plan is comprehensive, properly sequenced, and ready for implementation.
- **REJECTED**: The plan requires revision to address the identified deficiencies.

188
BETA-V3/gems-and-gpts/templates/prd.txt Normal file
View File

@@ -0,0 +1,188 @@
# {Project Name} Product Requirements Document (PRD)
## Goal, Objective and Context
Keep this brief and to the point in the final output - this should come mostly from the user or the provided brief, but ask for clarifications as needed.
## Functional Requirements (MVP)
You should have a good idea at this point, but clarify suggest question and explain to ensure these are correct.
## Non Functional Requirements (MVP)
## 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.
## Technical Assumptions
This is where we can list information mostly to be used by the architect to produce the technical details. This could be anything we already know or found out from the user at a technical high level. Inquire about this from the user to get a basic idea of languages, frameworks, knowledge of starter templates, libraries, external apis, potential library choices etc...
### Testing requirements
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 {#}: {Title}**
- Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.}
- 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}
- 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}
- **Epic {#}: {Title}**
- Goal: {A concise 1-2 sentence statement describing the primary objective and value of this Epic.}
- 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}
- 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}
## Out of Scope Ideas Post MVP
Anything you and the user agreed it out of scope or can be removed from scope to keep MVP lean. Consider the goals of the PRD and what might be extra gold plating or additional features that could wait until the MVP is completed and delivered to assess functionality and market fit or usage.
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ---------------------------- | -------------- |
----- END PRD START CHECKLIST OUTPUT ------
## Checklist Results Report
----- END Checklist START Architect Prompt ------
## Initial Architect Prompt
Based on our discussions and requirements analysis for the {Product Name}, I've compiled the following technical guidance to inform your architecture analysis and decisions to kick off Architecture Creation Mode:
### Technical Infrastructure
- **Starter Project/Template:** {Information about any starter projects, templates, or existing codebases that should be used}
- **Hosting/Cloud Provider:** {Specified cloud platform (AWS, Azure, GCP, etc.) or hosting requirements}
- **Frontend Platform:** {Framework/library preferences or requirements (React, Angular, Vue, etc.)}
- **Backend Platform:** {Framework/language preferences or requirements (Node.js, Python/Django, etc.)}
- **Database Requirements:** {Relational, NoSQL, specific products or services preferred}
### Technical Constraints
- {List any technical constraints that impact architecture decisions}
- {Include any mandatory technologies, services, or platforms}
- {Note any integration requirements with specific technical implications}
### Deployment Considerations
- {Deployment frequency expectations}
- {CI/CD requirements}
- {Environment requirements (local, dev, staging, production)}
### Local Development & Testing Requirements
{Include this section only if the user has indicated these capabilities are important. If not applicable based on user preferences, you may remove this section.}
- {Requirements for local development environment}
- {Expectations for command-line testing capabilities}
- {Needs for testing across different environments}
- {Utility scripts or tools that should be provided}
- {Any specific testability requirements for components}
### Other Technical Considerations
- {Security requirements with technical implications}
- {Scalability needs with architectural impact}
- {Any other technical context the Architect should consider}
----- END PM Prompt -----

50
BETA-V3/gems-and-gpts/templates/project-brief.txt Normal file
View File

@@ -0,0 +1,50 @@
# Project Brief: {Project Name}
## Introduction / Problem Statement
{Describe the core idea, the problem being solved, or the opportunity being addressed. Why is this project needed?}
## Vision & Goals
- **Vision:** {Describe the high-level desired future state or impact of this project.}
- **Primary Goals:** {List 2-5 specific, measurable, achievable, relevant, time-bound (SMART) goals for the Minimum Viable Product (MVP).}
- Goal 1: ...
- Goal 2: ...
- **Success Metrics (Initial Ideas):** {How will we measure if the project/MVP is successful? List potential KPIs.}
## Target Audience / Users
{Describe the primary users of this product/system. Who are they? What are their key characteristics or needs relevant to this project?}
## Key Features / Scope (High-Level Ideas for MVP)
{List the core functionalities or features envisioned for the MVP. Keep this high-level; details will go in the PRD/Epics.}
- Feature Idea 1: ...
- Feature Idea 2: ...
- Feature Idea N: ...
## Post MVP Features / Scope and Ideas
{List the core functionalities or features envisioned as potential for POST MVP. Keep this high-level; details will go in the PRD/Epics/Architecture.}
- Feature Idea 1: ...
- Feature Idea 2: ...
- Feature Idea N: ...
## Known Technical Constraints or Preferences
- **Constraints:** {List any known limitations and technical mandates or preferences - e.g., budget, timeline, specific technology mandates, required integrations, compliance needs.}
- **Risks:** {Identify potential risks - e.g., technical challenges, resource availability, market acceptance, dependencies.}
- **User Preferences:** {Any specific requests from the user that are not a high level feature that could direct technology or library choices, or anything else that came up in the brainstorming or drafting of the PRD that is not included in prior document sections}
## Relevant Research (Optional)
{Link to or summarize findings from any initial research conducted (e.g., `deep-research-report-BA.md`).}
## PM Prompt
This Project Brief provides the full context for {Project Name}. Please start in 'PM MODE 1', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows.
<example_handoff_prompt>
This Project Brief provides the full context for Mealmate. Please start in 'PM MODE 1', review the brief thoroughly to work with the user to create the PRD section by section 1 at a time, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows.</example_handoff_prompt>

57
BETA-V3/gems-and-gpts/templates/story-draft-checklist.txt Normal file
View File

@@ -0,0 +1,57 @@
# Story Draft Checklist
The Scrum Master should use this checklist to validate that each story contains sufficient context for a developer agent to implement it successfully, while assuming the dev agent has reasonable capabilities to figure things out.
## 1. GOAL & CONTEXT CLARITY
- [ ] Story goal/purpose is clearly stated
- [ ] Relationship to epic goals is evident
- [ ] How the story fits into overall system flow is explained
- [ ] Dependencies on previous stories are identified (if applicable)
- [ ] Business context and value are clear
## 2. TECHNICAL IMPLEMENTATION GUIDANCE
- [ ] Key files to create/modify are identified (not necessarily exhaustive)
- [ ] Technologies specifically needed for this story are mentioned
- [ ] Critical APIs or interfaces are sufficiently described
- [ ] Necessary data models or structures are referenced
- [ ] Required environment variables are listed (if applicable)
- [ ] Any exceptions to standard coding patterns are noted
## 3. REFERENCE EFFECTIVENESS
- [ ] References to external documents point to specific relevant sections
- [ ] Critical information from previous stories is summarized (not just referenced)
- [ ] Context is provided for why references are relevant
- [ ] References use consistent format (e.g., `docs/filename.md#section`)
## 4. SELF-CONTAINMENT ASSESSMENT
- [ ] Core information needed is included (not overly reliant on external docs)
- [ ] Implicit assumptions are made explicit
- [ ] Domain-specific terms or concepts are explained
- [ ] Edge cases or error scenarios are addressed
## 5. TESTING GUIDANCE
- [ ] Required testing approach is outlined
- [ ] Key test scenarios are identified
- [ ] Success criteria are defined
- [ ] Special testing considerations are noted (if applicable)
## VALIDATION RESULT
| Category | Status | Issues |
| ------------------------------------ | ----------------- | ------ |
| 1. Goal & Context Clarity | PASS/FAIL/PARTIAL | |
| 2. Technical Implementation Guidance | PASS/FAIL/PARTIAL | |
| 3. Reference Effectiveness | PASS/FAIL/PARTIAL | |
| 4. Self-Containment Assessment | PASS/FAIL/PARTIAL | |
| 5. Testing Guidance | PASS/FAIL/PARTIAL | |
**Final Assessment:**
- READY: The story provides sufficient context for implementation
- NEEDS REVISION: The story requires updates (see issues)
- BLOCKED: External information required (specify what information)

84
BETA-V3/gems-and-gpts/templates/story-template.txt Normal file
View File

@@ -0,0 +1,84 @@
# Story {EpicNum}.{StoryNum}: {Short Title Copied from Epic File}
**Status:** Draft | In-Progress | Complete
## Goal & Context
**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.}
## 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)_
## 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
- [ ] Task 2
- [ ] Subtask 2.1
- [ ] Task 3
## Testing Requirements
**Guidance:** Verify implementation against the ACs using the following tests.
- **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
- ...

96
BETA-V3/gems-and-gpts/templates/ui-ux-spec.txt Normal file
View File

@@ -0,0 +1,96 @@
# {Project Name} UI/UX Specification
## Introduction
{State the purpose - to define the user experience goals, information architecture, user flows, and visual design specifications for the project's user interface.}
- **Link to Primary Design Files:** {e.g., Figma, Sketch, Adobe XD URL}
- **Link to Deployed Storybook / Design System:** {URL, if applicable}
## 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.}
## Change Log
| Change | Date | Version | Description | Author |
| ------------- | ---------- | ------- | ------------------- | -------------- |

1
BETA-V3/readme.md Normal file
View File

@@ -0,0 +1 @@
# 2.5 improvements checklist

92
BETA-V3/sample/brief.txt Normal file
View File

@@ -0,0 +1,92 @@
# Project Brief: BMad News DiCaster
## Introduction / Problem Statement
- **Core Idea:** BMad News DiCaster is a Next.js, Supabase, Vercel-hosted web app that generates daily podcasts/newsletters summarizing the top 10 Hacker News stories, including article and comment summaries. The project emphasizes flexible development, supporting both local (with optional local LLM and Supabase) and remote deployed environments.
- **Problem being solved / Opportunity being addressed:**
- The primary problem is the difficulty for individuals to efficiently keep up with the high volume of content and discussions on Hacker News.
- The opportunity is to provide a curated, easily digestible summary in both text and audio formats, catering to busy tech enthusiasts who want to stay informed, while also serving as a comprehensive demonstration project for modern web application development practices.
## Vision & Goals
- **Vision:** To be the go-to daily digest for Hacker News enthusiasts, offering both text and audio summaries to fit their busy lifestyles, demonstrating a modern web application architecture with robust local and remote development/deployment capabilities.
- **Primary Goals (SMART for MVP):**
- **Goal 1:** Successfully generate and store a daily top 10 Hacker News summary (text content and audio link from Play.ai's PlayNote API) within a defined daily processing window, functional in both local and deployed environments.
- **Goal 2:** For unauthenticated users: Display a list of generated summaries, excluding the two most recent editions, and limit viewing to a small number (e.g., the 3rd, 4th, and 5th most recent). Include a clear call to action to register for access to the latest content and email delivery.
- **Goal 3:** Enable registered users to log in, view/listen to all past summaries (including the latest), and manage their email subscription preference for the daily newsletter.
- **Success Metrics (Initial Ideas for MVP):**
- Consistent daily generation of the top 10 Hacker News summary content (locally and deployed).
- Successful retrieval of the audio link from the Play.ai PlayNote API webhook.
- Successful storage of all retrieved assets (HN posts, comments, scraped articles, summaries, podcast URLs) in Supabase (local Docker and deployed).
- Ability for registered users to toggle email notifications and receive them successfully.
- Ability for unauthenticated users to view a limited set of older content.
- Ability for authenticated users to view all content.
- CLI command successfully triggers on-demand content generation and storage in the local environment.
## Target Audience / Users
- **Primary End-Users:** Tech-savvy individuals, likely regular readers of Hacker News, who are often busy and would benefit from efficiently consumed, curated summaries of top stories and discussions, available in both text and engaging two-person podcast format.
- **Secondary Audience / Developer Persona:** Developers interested in learning from or contributing to a practical, real-world example application. They are keen on understanding the architecture (Next.js, Supabase, Vercel), specific API integrations (Play.ai PlayNote, `hnangolia`, Cheerio), LLM usage (interchangeable local Ollama and remote API-based models), local development setup (including Dockerized Supabase and CLI tooling), and deployment best practices.
## Key Features / Scope (High-Level Ideas for MVP)
- **Feature 1 (Content Sourcing):** Automated daily fetching of top Hacker News stories (e.g., top 10) using the `hnangolia` library.
- **Feature 2 (Content Scraping):** Scraping of linked article content using Cheerio for summarization.
- **Feature 3 (Content Summarization):** LLM-powered summarization of articles and associated Hacker News comments to create a "top 10 countdown" style daily briefing.
- Must support using a local LLM (e.g., via Ollama) during local development.
- Must support using a remote LLM (via API key) for deployed/remote environment or local development.
- **Feature 4 (Data Storage):** Comprehensive storage of all generated and retrieved assets (HN posts, comments, full scraped content, summaries, podcast URLs) in Supabase.
- Supports a local Docker version of Supabase for local development.
- Utilizes a cloud-hosted Supabase instance for the deployed application.
- **Feature 5 (Audio Generation):** Integration with the Play.ai **PlayNote API** to submit the text summary and receive a two-person AI-generated podcast link via a webhook.
- **Feature 6 (Content Generation Workflow - Automated):** A daily automated process (e.g., cron job, Vercel cron) orchestrating content sourcing, scraping, summarization, storage, and audio generation submission.
- **Feature 7 (Content Generation Workflow - Manual CLI):** A command-line interface (CLI) tool to trigger the entire content generation and storage process on-demand in the local development environment.
- **Feature 8 (Web Interface - List View):** A public web page listing generated summaries/podcasts.
- Unauthenticated users see a limited list (e.g., 3rd-5th most recent) with a call to register for full access.
- Authenticated users see all available summaries/podcasts.
- **Feature 9 (Web Interface - Detail View):** A detail page for each daily summary, displaying the full text briefing and an embedded audio player for the podcast.
- **Feature 10 (User Authentication):** User registration (email/password) and login/logout functionality using Supabase Auth.
- **Feature 11 (User Profile - Email Notifications):** Authenticated users can access a setting to toggle on/off daily email notifications for new briefings.
- **Feature 12 (Email Dispatch):** Automated daily email dispatch of the new newsletter (containing text summary highlights and podcast link) to all subscribed registered users.
## Post MVP Features / Scope and Ideas
- **Feature 1 (Admin Interface):** A web-based administrative interface for managing the application (e.g., view generation logs, manually trigger/re-run generation, potentially manage users or content).
- **Feature 2 (Flexible Scheduling & Editions):** Ability to configure and generate different summary cadences and types (e.g., weekly digests, "night and weekend" editions, topic-focused summaries).
- **Feature 3 (User Customization):** Allow users to customize content (e.g., choose number of stories, filter by keywords/topics).
- **Feature 4 (Expanded Content Sources):** Integrate other news sources beyond Hacker News.
## Known Technical Constraints or Preferences
- **Core Stack:** Next.js (frontend/backend), Supabase (database, auth, storage), Vercel (hosting, serverless functions, cron jobs).
- **Hosting Tier:** Vercel Pro tier to leverage potentially longer function execution times and other professional-grade features.
- **Content Fetching:** `hnangolia` library for Hacker News data.
- **Content Scraping:** Cheerio for HTML parsing of articles.
- **LLM:**
- Flexibility to use local LLMs (e.g., Ollama) for local development.
- Ability to use API-based LLMs (e.g., OpenAI, Anthropic - specific model to be decided) for production or as an alternative in local development. Configurable via API keys.
- **Audio Generation:** Specifically use the Play.ai **PlayNote API** for its two-person podcast generation feature; webhook for callback.
- **Local Development Environment:**
- Must support running the full application stack locally.
- Local Supabase instance running in Docker.
- CLI for on-demand content generation.
- **Data Persistence:** All fetched (HN posts, comments), scraped (article content), and generated (summaries, podcast URLs) data must be stored, both locally and in the deployed environment.
- **Architecture on Vercel:**
- The daily content generation process will likely be architected as a **pipeline of multiple, chained serverless functions** to manage execution time and resources efficiently within Vercel's limits.
- Webhooks (e.g., from Play.ai) are critical for handling asynchronous operations from external services.
- Consideration for efficient batching or queuing of tasks (e.g., article scraping and summarization) to avoid hitting function timeouts or resource limits. Vercel KV or external queues (like Upstash QStash) might be explored if simple direct invocation chaining becomes insufficient.
- **Risks:**
- **Vercel Function Execution Limits:** Even on the Pro tier, individual serverless functions have execution time limits. The pipeline approach is intended to mitigate this, but complex/slow steps (especially numerous LLM calls or heavy scraping) need careful management and optimization.
- **LLM Processing Time/Cost:** LLM summarizations can be time-consuming and/or costly depending on the model and number of tokens processed. This needs to be factored into the daily processing window and operational budget.
- **Scraping Reliability:** Websites can change their structure, breaking scrapers. Anti-scraping measures could also pose a challenge.
- **External API Dependencies:** Reliance on Hacker News (`hnangolia`), LLM provider, and Play.ai means that any downtime or API changes from these services can impact the application.
- **Webhook Management:** Ensuring reliable receipt and processing of webhooks, including handling retries or failures.
- **Cold Starts:** Serverless functions can have "cold starts," which might introduce latency, especially for the first request in a while or for less frequently used functions in the pipeline. This needs to be acceptable for the user experience or generation window.
## Relevant Research (Optional)
None at this time.
## PM Prompt
This Project Brief provides the full context for "BMad News DiCaster," a daily Hacker News summary and podcast generation service. Please operate in **MODE 1**, review it thoroughly to create the Product Requirements Document (PRD). Your process should involve going through each section of the PRD, asking clarifying questions for any ambiguities in this brief, and suggesting improvements or alternative approaches where appropriate, adhering to your standard operational mode for PRD development.

308
BETA-V3/sample/prd-massive.md Normal file
View File

@@ -0,0 +1,308 @@
# BMad News DiCaster Product Requirements Document (PRD)
## Goal, Objective and Context
BMad News DiCaster is a web application that generates daily podcasts and newsletters summarizing the top 10 Hacker News stories. The primary goal is to provide a way for individuals to efficiently keep up with Hacker News content. The application will be built using Next.js, Supabase, and Vercel. [cite: 1, 2, 3, 4, 5, 6, 85, 86]
## Functional Requirements (MVP)
- **Content Sourcing:**
- Automated fetching of top Hacker News stories, configurable for time/frequency and triggerable manually via CLI.
- _Clarification:_ The fetching schedule should be configurable and ideally read from the database.
- **Content Scraping:**
- Scraping linked article content, attempting to retrieve up to `MAX_NUMBER` of posts to produce `NEWSLETTER_ITEM_COUNT` articles.
- Scraped article content and retrieved comments should be saved in connection with the HN post.
- _Clarification:_ Scraper should retrieve up to `MAX_NUMBER` posts to ensure we can summarize `NEWSLETTER_ITEM_COUNT` articles. More advanced scraping to be considered post-MVP.
- _Error Handling:_ If scraping fails for an article, the system should proceed to the next article. If the required `NEWSLETTER_ITEM_COUNT` cannot be reached after scraping `MAX_NUMBER` posts, the system will use the available successful scrapes and include a summary of the comment thread for the articles that failed to scrape.
- **Content Summarization:**
- LLM summarization of articles (approximately 2 paragraphs) and comments (approximately 2 paragraphs), with configurable local/remote LLM selection (URL, API key, model).
- Summaries of articles and comments should be saved.
- Prompts and newsletter templates should be stored in the database for easy updating.
- A setting should define the maximum number of comments to pull and summarize.
- **Data Storage:**
- Storage of all data in Supabase (local and cloud-hosted), including:
- HN posts and associated scraped article content and comments.
- Summaries of articles and comments.
- Webhook responses from Play.ai.
- **Audio Generation:**
- Integration with Play.ai PlayNote API, with voice, quality, and tone parameters to be determined during development. [cite: 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 86, 87]
- Webhook response indicating generation completion should be saved.
- **Content Generation Workflow:**
- Automated daily process with incremental saving of assets at each stage of the pipeline. [cite: 28]
- CLI tool for on-demand generation. [cite: 29]
- **Web Interface:**
- Single unauthenticated page listing newsletter/podcast titles, date/time, and links to detail pages. [cite: 30, 31, 32]
- Detail page displaying the newsletter and embedded audio player. [cite: 32, 33]
- **Newsletter Content:**
- The newsletter should be visually appealing and include:
- Article summaries.
- Comment summaries.
- Hacker News post title.
- Hacker News post upvote count.
- Hacker News post date.
- Link to the Hacker News post.
- Link to the article.
- **User Authentication:**
- _Moved to Post-MVP._
- **User Profile:**
- _Moved to Post-MVP._
- **Email Dispatch:**
- Automated daily email dispatch to a manually maintained list of subscribed users. [cite: 34, 35]
- _Clarification:_ User subscription management (add/remove) will be done directly by the admin in the database for the MVP.
## Non-Functional Requirements (MVP)
- **Performance:**
- The system should efficiently generate and deliver daily summaries within a defined time window.
- LLM processing time should be minimized to avoid delays.
- The web interface should load quickly and provide a responsive user experience.
- **Scalability:**
- The system should be able to handle a growing number of users and summaries.
- **Reliability:**
- The daily content generation process should be reliable and fault-tolerant.
- The system should handle potential issues with external APIs (Hacker News, LLM, Play.ai) gracefully. [cite: 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61]
- **Security:**
- Data should be stored securely in Supabase.
- Appropriate security measures should be in place to protect against unauthorized access.
- **Development and Deployment:**
- The system should support both local development (with local Supabase and LLM) and remote deployment on Vercel. [cite: 40, 41]
- The content generation process should be deployable as a pipeline of serverless functions on Vercel. [cite: 49]
- **Logging and Monitoring:**
- The system should log errors and successful completion of pipeline stages.
- Vercel's logging and monitoring capabilities should be utilized.
- **Error Handling:**
- If scraping fails for an article, the system should proceed to the next article.
- If the required `NEWSLETTER_ITEM_COUNT` cannot be reached after scraping `MAX_NUMBER` posts, the system will use the available successful scrapes and include a summary of the comment thread for the articles that failed to scrape.
## User Interaction and Design Goals
- **Overall UX Goals & Principles:**
- _Target User Personas:_ Tech-savvy individuals interested in Hacker News. [cite: 16, 17, 18]
- _Usability Goals:_
- Ease of finding daily summaries.
- Efficient access to both text and audio versions.
- Clear presentation of information.
- _Design Principles:_
- Clarity: Prioritize clear presentation of information.
- Accessibility: Ensure content is accessible to all users.
- Responsiveness: The interface should work well on various screen sizes.
- Modern Aesthetic: Implement a synthwave-inspired, dark, glowing, and minimalist design.
- **Information Architecture (IA):**
- Two pages:
- List Page: Displays a list of summaries with titles, dates, and links to detail pages.
- Detail Page: Shows the full newsletter content and an embedded audio player.
- **User Flows:**
- View Summary List: User navigates to the list page and browses available summaries.
- View Summary Detail: User clicks on a summary to view the detail page with the text and audio.
- **UI Elements:**
- List Page:
- List of newsletter titles with dates and times.
- Links to detail pages.
- Detail Page:
- Newsletter content (article and comment summaries, HN post details).
- Embedded audio player.
- **Technology Stack:**
- shadcn/ui and Tailwind CSS will be used for UI development.
- **Design Considerations:**
- Visual appeal of the newsletter (as mentioned in functional requirements).
- Clear display of HN post details (title, upvotes, date, links).
- Mobile-friendly layout.
- Synthwave-inspired, dark, glowing, and minimalist aesthetic.
## Technical Assumptions
- **Core Stack:** Next.js, Supabase, Vercel (using the starter template from \[<https://vercel.com/templates/authentication/supabase>\](https://vercel.com/templates/authentication/supabase) and its current versions). [cite: 40, 41]
- **Hosting:** Vercel Pro tier. [cite: 41]
- **Content Fetching:** hnangolia library. [cite: 42]
- **Content Scraping:** Cheerio. [cite: 42]
- **LLM:**
- Local LLMs (e.g., Ollama) for local development. [cite: 43, 44, 45]
- API-based LLMs (e.g., OpenAI, Anthropic) for production/local. [cite: 43, 44, 45]
- LLM configuration via API keys and URLs. [cite: 43, 44, 45]
- **Audio Generation:** Play.ai PlayNote API. [cite: 45, 46]
- **Local Development:**
- Local Supabase instance in Docker. [cite: 46, 47, 48]
- CLI for on-demand content generation. [cite: 46, 47, 48]
- **Architecture:**
- Serverless functions on Vercel. [cite: 49, 50, 51, 52]
- Use of facades for external library interactions to facilitate unit testing and library swapping.
- Use of a factory pattern for scraper implementation to support adding new scrapers.
- **Data Persistence:** All data stored in Supabase (local and cloud). [cite: 48]
### Testing requirements
- **Unit Testing:**
- Individual components and functions should be unit tested to ensure they behave as expected.
- This includes testing the scraper, LLM summarization logic, data storage interactions, etc.
- Jest should be used as the unit testing framework.
- **Integration Testing:**
- Integration tests should verify the interactions between different components.
- For example, testing the integration between the Hacker News data fetching and the article scraping, or the integration between the LLM summarization and the audio generation.
- **End-to-End (E2E) Testing:**
- E2E tests should simulate user flows and verify the overall functionality of the application.
- This could include testing the content generation workflow from start to finish, or testing the display of summaries in the web interface.
- React Testing Library (RTL) should be used for E2E testing.
- **API Testing:**
- The APIs used for fetching data, LLM interaction, and audio generation should be tested to ensure they are functioning correctly and returning the expected data.
- **Local Testing:**
- The CLI tool for on-demand content generation should be thoroughly tested in the local development environment.
- Local testing should also include verifying the local Supabase and LLM integration.
- **Deployment Testing:**
- Testing in the Vercel environment should ensure that the application functions correctly after deployment.
- This includes testing the serverless function pipeline, webhooks, and any Vercel-specific configurations.
## Epic Overview (MVP / Current Version)
- **Epic 1: Project Setup and Initial UI**
- Goal: Deploy the starter template with an initial, generated UI and configure the project.
- Story 1.1: As a developer, I want to set up the project using the Supabase starter template so that I have a foundation to build upon.
- Acceptance Criteria:
- The Supabase starter template is successfully initialized.
- The project directory is structured as defined by the template.
- The necessary Supabase client libraries are installed.
- Story 1.2: As a developer, I want to configure the project's dependencies and environment variables so that I can run the application locally.
- Acceptance Criteria:
- All project dependencies are installed.
- Environment variables are configured for local development.
- The application can be run locally without errors.
- Story 1.3: As a developer, I want to deploy the starter template to Vercel so that the application is accessible online.
- Acceptance Criteria:
- The project is successfully deployed to Vercel.
- The deployed application is accessible via a Vercel-provided URL.
- Environment variables are configured for the Vercel environment.
- Story 1.4: As a developer, I want to set up CI/CD so that changes to the codebase are automatically deployed.
- Acceptance Criteria:
- A CI/CD pipeline is set up (e.g., using Vercel's Git integration).
- Changes to the main branch trigger automatic deployment to Vercel.
- The deployment process is automated.
- Story 1.5: As a developer, I want to generate an initial UI with placeholder content for the list and detail pages using a UI generation tool, and style it.
- Acceptance Criteria:
- A UI generation tool (e.g., V0 or [lovable.ai](http://lovable.ai)) is used to create the initial structure and styling of the web interface.
- The generated UI includes placeholder content for the list page (titles, dates, links) and detail page (newsletter content, audio player).
- The UI is styled using shadcn/ui and Tailwind CSS with a synthwave-inspired, dark, glowing, and minimalist aesthetic.
- The UI is designed for a single large desktop layout.
- **Epic 2: Hacker News Content Retrieval and Scraping**
- Goal: Implement the functionality to fetch Hacker News stories and scrape the content from the linked websites.
- Story 2.1: As a developer, I want to fetch the top Hacker News stories using the `hnangolia` library so that I can retrieve the data needed for the newsletter.
- Acceptance Criteria:
- The `hnangolia` library is successfully integrated into the project.
- The system can fetch the specified number of top Hacker News stories.
- The fetched data includes the necessary fields (e.g., title, URL, HN post ID).
- Story 2.2: As a developer, I want to implement a scraper to extract article content from the URLs provided by Hacker News so that I can obtain the article text for summarization.
- Acceptance Criteria:
- A scraper is implemented using Cheerio.
- The scraper can extract the main content from articles across different websites.
- The scraper handles potential issues like missing content or different website structures gracefully (e.g., logs errors and continues).
- Story 2.3: As a developer, I want to save the fetched Hacker News data and scraped article content so that it can be used in subsequent steps.
- Acceptance Criteria:
- The fetched Hacker News data is saved in the database, including relevant details.
- The scraped article content is saved in the database, associated with the corresponding Hacker News post.
- Story 2.4: As a developer, I want to configure the number of top Hacker News stories to fetch and the maximum number of articles to scrape so that these parameters can be adjusted as needed.
- Acceptance Criteria:
- Configuration options are implemented for:
- The number of top Hacker News stories to fetch (`NEWSLETTER_ITEM_COUNT`).
- The maximum number of articles to scrape (`MAX_NUMBER`).
- These configuration options can be easily modified (e.g., via environment variables or a configuration file).
- **Epic 3: LLM Summarization**
- Goal: Implement the LLM-powered summarization of articles and comments.
- Story 3.1: As a developer, I want to integrate an LLM API for text summarization so that I can generate concise summaries of articles and comments.
- Acceptance Criteria:
- The chosen LLM API is successfully integrated into the project.
- The system can send text to the LLM API and receive summaries.
- Story 3.2: As a developer, I want to implement the logic to summarize article content so that I can provide users with a quick overview of the main points.
- Acceptance Criteria:
- The logic for summarizing article content is implemented.
- The system can extract relevant text from the scraped article content and provide it to the LLM API.
- The generated summaries are concise (approximately 2 paragraphs) and capture the main points of the article.
- Story 3.3: As a developer, I want to implement the logic to summarize comments on Hacker News posts so that I can capture the main discussion points.
- Acceptance Criteria:
- The logic for summarizing Hacker News comments is implemented.
- The system can retrieve comments associated with an HN post and provide them to the LLM API.
- The generated summaries are concise (approximately 2 paragraphs) and capture the main discussion points.
- Story 3.4: As a developer, I want to store the generated summaries in the database, associated with the corresponding articles and HN posts, so that they can be used in the newsletter.
- Acceptance Criteria:
- The generated article summaries are stored in the database, associated with the corresponding articles.
- The generated comment summaries are stored in the database, associated with the corresponding HN posts.
- Story 3.5: As a developer, I want to make the LLM API endpoint, model, and API key configurable so that I can easily switch between different LLM providers or models.
- Acceptance Criteria:
- The LLM API endpoint, model, and API key are configurable via environment variables or a configuration file.
- The system can switch between different LLM providers or models by changing the configuration.
- Story 3.6: As a developer, I want to store the summarization prompts in the database so that they can be easily updated without requiring code changes.
- Acceptance Criteria:
- The summarization prompts are stored in the database.
- The system retrieves the prompts from the database and uses them when calling the LLM API.
- The prompts can be updated in the database without requiring code changes or redeployment.
- **Epic 4: Web Interface Implementation**
- Goal: Implement the functionality of the web interface pages.
- Story 4.1: As a developer, I want to make the list page display the actual data.
- Acceptance Criteria:
- The list page displays newsletter titles and dates/times from the database.
- Each item in the list is a link to the corresponding detail page.
- The list is sorted by date/time.
- Story 4.2: As a developer, I want to make the detail page display the actual newsletter content and allow navigation to and from the list page.
- Acceptance Criteria:
- The detail page displays the full newsletter content from the database.
- The newsletter content includes article summaries, comment summaries, and Hacker News post details.
- Users can navigate to the detail page by clicking on an item in the list page.
- The detail page includes a "back to list" navigation element.
- Story 4.3: As a developer, I want to make the audio player on the detail page play the actual podcast.
- Acceptance Criteria:
- The audio player on the detail page plays the podcast associated with the displayed newsletter.
- **Epic 5: Email Dispatch**
- Goal: Implement the automated email dispatch of newsletters to subscribed users.
- Story 5.1: As a user, I want to receive a daily newsletter email so that I can stay updated on the top Hacker News stories.
- Acceptance Criteria:
- The system sends a newsletter email.
- The email includes the newsletter content (article and comment summaries, HN post details).
- The email is formatted correctly and is visually appealing.
- The email is sent to the list of emails maintained manually in the database.
- Story 5.2: As a developer, I want to be able to manually trigger the newsletter email sending process via a command-line interface so that I can test and initiate the sending process on demand.
- Acceptance Criteria:
- A CLI command is available to trigger the newsletter email sending process.
- The command can be executed in the local development environment.
- Executing the command sends the newsletter email.
- Story 5.3: As a developer, I want to automate the daily sending of the newsletter email so that it is sent out regularly without manual intervention.
- Acceptance Criteria:
- The sending of the newsletter email is automated (e.g., using Vercel's cron jobs or similar).
- The email is sent out daily at a specified time.
- _Question:_ What specific cron job capabilities does Vercel Pro support?
- **Epic 6: Podcast Generation and UI Update**
- Goal: Implement podcast generation, update the newsletter with the audio link, and update the UI with the audio player.
- Story 6.1: As a developer, I want to integrate the Play.ai PlayNote API to generate audio versions of the newsletters.
- Acceptance Criteria:
- The Play.ai PlayNote API is successfully integrated into the project.
- The system can send the newsletter text to the Play.ai API and receive a confirmation that the request was accepted.
- The system implements a webhook endpoint to receive the generated audio URL from Play.ai.
- Story 6.2: As a developer, I want to store the generated podcast URLs in the database, associated with the corresponding newsletters, upon receiving the webhook notification.
- Acceptance Criteria:
- The system can receive the audio URL via the webhook.
- The generated podcast URLs are stored in the database, associated with the corresponding newsletters.
- Story 6.3: As a developer, I want to update the newsletter content to include a link to the audio version, and ensure that the email is not sent until the podcast link is available.
- Acceptance Criteria:
- The newsletter data in the database is updated to include the audio URL.
- The newsletter email includes a link to the audio version.
- The system ensures that the email is not sent until the podcast URL is successfully received from Play.ai and stored in the database.
- Story 6.4: As a developer, I want to embed an audio player in the UI so that users can listen to the podcast.
- Acceptance Criteria:
- An audio player is embedded in the detail page of the UI.
- The audio player can play the audio file from the generated URL.
## Key Reference Documents
{Will be populated at a later time}
## Out of Scope Ideas Post MVP
- User Authentication
- User Profiles
- Advanced scraping
- Admin Interface
- Flexible Scheduling & Editions
- User Customization
- Expanded Content Sources
## Change Log
| Change | Date | Version | Description | Author |
| ------ | ---- | ------- | ----------- | ------ |
| | | | | |

411
BETA-V3/sample/prd-massive.txt Normal file
View File

@@ -0,0 +1,411 @@
Certainly! Here's the complete final document, incorporating all sections, including the checklist report and the architect prompt:
# BMad News DiCaster Product Requirements Document (PRD)
## Goal, Objective and Context
BMad News DiCaster is a web application that generates daily podcasts and newsletters summarizing the top 10 Hacker News stories. The primary goal is to provide a way for individuals to efficiently keep up with Hacker News content. The application will be built using Next.js, Supabase, and Vercel. [cite: 1, 2, 3, 4, 5, 6, 85, 86]
## Functional Requirements (MVP)
* **Content Sourcing:**
* Automated fetching of top Hacker News stories, configurable for time/frequency and triggerable manually via CLI.
* _Clarification:_ The fetching schedule should be configurable and ideally read from the database.
* **Content Scraping:**
* Scraping linked article content, attempting to retrieve up to `MAX_NUMBER` of posts to produce `NEWSLETTER_ITEM_COUNT` articles.
* Scraped article content and retrieved comments should be saved in connection with the HN post.
* _Clarification:_ Scraper should retrieve up to `MAX_NUMBER` posts to ensure we can summarize `NEWSLETTER_ITEM_COUNT` articles. More advanced scraping to be considered post-MVP.
* _Error Handling:_ If scraping fails for an article, the system should proceed to the next article. If the required `NEWSLETTER_ITEM_COUNT` cannot be reached after scraping `MAX_NUMBER` posts, the system will use the available successful scrapes and include a summary of the comment thread for the articles that failed to scrape.
* **Content Summarization:**
* LLM summarization of articles (approximately 2 paragraphs) and comments (approximately 2 paragraphs), with configurable local/remote LLM selection (URL, API key, model).
* Summaries of articles and comments should be saved.
* Prompts and newsletter templates should be stored in the database for easy updating.
* A setting should define the maximum number of comments to pull and summarize.
* **Data Storage:**
* Storage of all data in Supabase (local and cloud-hosted), including:
* HN posts and associated scraped article content and comments.
* Summaries of articles and comments.
* Webhook responses from Play.ai.
* **Audio Generation:**
* Integration with Play.ai PlayNote API, with voice, quality, and tone parameters to be determined during development. [cite: 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 86, 87]
* Webhook response indicating generation completion should be saved.
* **Content Generation Workflow:**
* Automated daily process with incremental saving of assets at each stage of the pipeline. [cite: 28]
* CLI tool for on-demand generation. [cite: 29]
* **Web Interface:**
* Single unauthenticated page listing newsletter/podcast titles, date/time, and links to detail pages. [cite: 30, 31, 32]
* Detail page displaying the newsletter and embedded audio player. [cite: 32, 33]
* **Newsletter Content:**
* The newsletter should be visually appealing and include:
* Article summaries.
* Comment summaries.
* Hacker News post title.
* Hacker News post upvote count.
* Hacker News post date.
* Link to the Hacker News post.
* Link to the article.
* **User Authentication:**
* _Moved to Post-MVP._
* **User Profile:**
* _Moved to Post-MVP._
* **Email Dispatch:**
* Automated daily email dispatch to a manually maintained list of subscribed users. [cite: 34, 35]
* _Clarification:_ User subscription management (add/remove) will be done directly by the admin in the database for the MVP.
## Non-Functional Requirements (MVP)
* **Performance:**
* The system should efficiently generate and deliver daily summaries within a defined time window.
* LLM processing time should be minimized to avoid delays.
* The web interface should load quickly and provide a responsive user experience.
* **Scalability:**
* The system should be able to handle a growing number of users and summaries.
* **Reliability:**
* The daily content generation process should be reliable and fault-tolerant.
* The system should handle potential issues with external APIs (Hacker News, LLM, Play.ai) gracefully. [cite: 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61]
* **Security:**
* Data should be stored securely in Supabase.
* Appropriate security measures should be in place to protect against unauthorized access.
* **Development and Deployment:**
* The system should support both local development (with local Supabase and LLM) and remote deployment on Vercel. [cite: 40, 41]
* The content generation process should be deployable as a pipeline of serverless functions on Vercel. [cite: 49]
* **Logging and Monitoring:**
* The system should log errors and successful completion of pipeline stages.
* Vercel's logging and monitoring capabilities should be utilized.
* **Error Handling:**
* If scraping fails for an article, the system should proceed to the next article.
* If the required `NEWSLETTER_ITEM_COUNT` cannot be reached after scraping `MAX_NUMBER` posts, the system will use the available successful scrapes and include a summary of the comment thread for the articles that failed to scrape.
## User Interaction and Design Goals
* **Overall UX Goals & Principles:**
* _Target User Personas:_ Tech-savvy individuals interested in Hacker News. [cite: 16, 17, 18]
* _Usability Goals:_
* Ease of finding daily summaries.
* Efficient access to both text and audio versions.
* Clear presentation of information.
* _Design Principles:_
* Clarity: Prioritize clear presentation of information.
* Accessibility: Ensure content is accessible to all users.
* Responsiveness: The interface should work well on various screen sizes.
* Modern Aesthetic: Implement a synthwave-inspired, dark, glowing, and minimalist design.
* **Information Architecture (IA):**
* Two pages:
* List Page: Displays a list of summaries with titles, dates, and links to detail pages.
* Detail Page: Shows the full newsletter content and an embedded audio player.
* **User Flows:**
* View Summary List: User navigates to the list page and browses available summaries.
* View Summary Detail: User clicks on a summary to view the detail page with the text and audio.
* **UI Elements:**
* List Page:
* List of newsletter titles with dates and times.
* Links to detail pages.
* Detail Page:
* Newsletter content (article and comment summaries, HN post details).
* Embedded audio player.
* **Technology Stack:**
* shadcn/ui and Tailwind CSS will be used for UI development.
* **Design Considerations:**
* Visual appeal of the newsletter (as mentioned in functional requirements).
* Clear display of HN post details (title, upvotes, date, links).
* Mobile-friendly layout.
* Synthwave-inspired, dark, glowing, and minimalist aesthetic.
## Technical Assumptions
* **Core Stack:** Next.js, Supabase, Vercel (using the starter template from \[<https://vercel.com/templates/authentication/supabase>\](https://vercel.com/templates/authentication/supabase) and its current versions). [cite: 40, 41]
* **Hosting:** Vercel Pro tier. [cite: 41]
* **Content Fetching:** hnangolia library. [cite: 42]
* **Content Scraping:** Cheerio. [cite: 42]
* **LLM:**
* Local LLMs (e.g., Ollama) for local development. [cite: 43, 44, 45]
* API-based LLMs (e.g., OpenAI, Anthropic) for production/local. [cite: 43, 44, 45]
* LLM configuration via API keys and URLs. [cite: 43, 44, 45]
* **Audio Generation:** Play.ai PlayNote API. [cite: 45, 46]
* **Local Development:**
* Local Supabase instance in Docker. [cite: 46, 47, 48]
* CLI for on-demand content generation. [cite: 46, 47, 48]
* **Architecture:**
* Serverless functions on Vercel. [cite: 49, 50, 51, 52]
* Use of facades for external library interactions to facilitate unit testing and library swapping.
* Use of a factory pattern for scraper implementation to support adding new scrapers.
* **Data Persistence:** All data stored in Supabase (local and cloud). [cite: 48]
### Testing requirements
* **Unit Testing:**
* Individual components and functions should be unit tested to ensure they behave as expected.
* This includes testing the scraper, LLM summarization logic, data storage interactions, etc.
* Jest should be used as the unit testing framework.
* **Integration Testing:**
* Integration tests should verify the interactions between different components.
* For example, testing the integration between the Hacker News data fetching and the article scraping, or the integration between the LLM summarization and the audio generation.
* **End-to-End (E2E) Testing:**
* E2E tests should simulate user flows and verify the overall functionality of the application.
* This could include testing the content generation workflow from start to finish, or testing the display of summaries in the web interface.
* React Testing Library (RTL) should be used for E2E testing.
* **API Testing:**
* The APIs used for fetching data, LLM interaction, and audio generation should be tested to ensure they are functioning correctly and returning the expected data.
* **Local Testing:**
* The CLI tool for on-demand content generation should be thoroughly tested in the local development environment.
* Local testing should also include verifying the local Supabase and LLM integration.
* **Deployment Testing:**
* Testing in the Vercel environment should ensure that the application functions correctly after deployment.
* This includes testing the serverless function pipeline, webhooks, and any Vercel-specific configurations.
## Epic Overview (MVP / Current Version)
* **Epic 1: Project Setup and Initial UI**
* Goal: Deploy the starter template with an initial, generated UI and configure the project.
* Story 1.1: As a developer, I want to set up the project using the Supabase starter template so that I have a foundation to build upon.
* Acceptance Criteria:
* The Supabase starter template is successfully initialized.
* The project directory is structured as defined by the template.
* The necessary Supabase client libraries are installed.
* Story 1.2: As a developer, I want to configure the project's dependencies and environment variables so that I can run the application locally.
* Acceptance Criteria:
* All project dependencies are installed.
* Environment variables are configured for local development.
* The application can be run locally without errors.
* Story 1.3: As a developer, I want to deploy the starter template to Vercel so that the application is accessible online.
* Acceptance Criteria:
* The project is successfully deployed to Vercel.
* The deployed application is accessible via a Vercel-provided URL.
* Environment variables are configured for the Vercel environment.
* Story 1.4: As a developer, I want to set up CI/CD so that changes to the codebase are automatically deployed.
* Acceptance Criteria:
* A CI/CD pipeline is set up (e.g., using Vercel's Git integration).
* Changes to the main branch trigger automatic deployment to Vercel.
* The deployment process is automated.
* Story 1.5: As a developer, I want to generate an initial UI with placeholder content for the list and detail pages using a UI generation tool, and style it.
* Acceptance Criteria:
* A UI generation tool (e.g., V0 or [lovable.ai](http://lovable.ai)) is used to create the initial structure and styling of the web interface.
* The generated UI includes placeholder content for the list page (titles, dates, links) and detail page (newsletter content, audio player).
* The UI is styled using shadcn/ui and Tailwind CSS with a synthwave-inspired, dark, glowing, and minimalist aesthetic.
* The UI is designed for a single large desktop layout.
* **Epic 2: Hacker News Content Retrieval and Scraping**
* Goal: Implement the functionality to fetch Hacker News stories and scrape the content from the linked websites.
* Story 2.1: As a developer, I want to fetch the top Hacker News stories using the `hnangolia` library so that I can retrieve the data needed for the newsletter.
* Acceptance Criteria:
* The `hnangolia` library is successfully integrated into the project.
* The system can fetch the specified number of top Hacker News stories.
* The fetched data includes the necessary fields (e.g., title, URL, HN post ID).
* Story 2.2: As a developer, I want to implement a scraper to extract article content from the URLs provided by Hacker News so that I can obtain the article text for summarization.
* Acceptance Criteria:
* A scraper is implemented using Cheerio.
* The scraper can extract the main content from articles across different websites.
* The scraper handles potential issues like missing content or different website structures gracefully (e.g., logs errors and continues).
* Story 2.3: As a developer, I want to save the fetched Hacker News data and scraped article content so that it can be used in subsequent steps.
* Acceptance Criteria:
* The fetched Hacker News data is saved in the database, including relevant details.
* The scraped article content is saved in the database, associated with the corresponding Hacker News post.
* Story 2.4: As a developer, I want to configure the number of top Hacker News stories to fetch and the maximum number of articles to scrape so that these parameters can be adjusted as needed.
* Acceptance Criteria:
* Configuration options are implemented for:
* The number of top Hacker News stories to fetch (`NEWSLETTER_ITEM_COUNT`).
* The maximum number of articles to scrape (`MAX_NUMBER`).
* These configuration options can be easily modified (e.g., via environment variables or a configuration file).
* **Epic 3: LLM Summarization**
* Goal: Implement the LLM-powered summarization of articles and comments.
* Story 3.1: As a developer, I want to integrate an LLM API for text summarization so that I can generate concise summaries of articles and comments.
* Acceptance Criteria:
* The chosen LLM API is successfully integrated into the project.
* The system can send text to the LLM API and receive summaries.
* Story 3.2: As a developer, I want to implement the logic to summarize article content so that I can provide users with a quick overview of the main points.
* Acceptance Criteria:
* The logic for summarizing article content is implemented.
* The system can extract relevant text from the scraped article content and provide it to the LLM API.
* The generated summaries are concise (approximately 2 paragraphs) and capture the main points of the article.
* Story 3.3: As a developer, I want to implement the logic to summarize comments on Hacker News posts so that I can capture the main discussion points.
* Acceptance Criteria:
* The logic for summarizing Hacker News comments is implemented.
* The system can retrieve comments associated with an HN post and provide them to the LLM API.
* The generated summaries are concise (approximately 2 paragraphs) and capture the main discussion points.
* Story 3.4: As a developer, I want to store the generated summaries in the database, associated with the corresponding articles and HN posts, so that they can be used in the newsletter.
* Acceptance Criteria:
* The generated article summaries are stored in the database, associated with the corresponding articles.
* The generated comment summaries are stored in the database, associated with the corresponding HN posts.
* Story 3.5: As a developer, I want to make the LLM API endpoint, model, and API key configurable so that I can easily switch between different LLM providers or models.
* Acceptance Criteria:
* The LLM API endpoint, model, and API key are configurable via environment variables or a configuration file.
* The system can switch between different LLM providers or models by changing the configuration.
* Story 3.6: As a developer, I want to store the summarization prompts in the database so that they can be easily updated without requiring code changes.
* Acceptance Criteria:
* The summarization prompts are stored in the database.
* The system retrieves the prompts from the database and uses them when calling the LLM API.
* The prompts can be updated in the database without requiring code changes or redeployment.
* **Epic 4: Web Interface Implementation**
* Goal: Implement the functionality of the web interface pages.
* Story 4.1: As a developer, I want to make the list page display the actual data.
* Acceptance Criteria:
* The list page displays newsletter titles and dates/times from the database.
* Each item in the list is a link to the corresponding detail page.
* The list is sorted by date/time.
* Story 4.2: As a developer, I want to make the detail page display the actual newsletter content and allow navigation to and from the list page.
* Acceptance Criteria:
* The detail page displays the full newsletter content from the database.
* The newsletter content includes article summaries, comment summaries, and Hacker News post details.
* Users can navigate to the detail page by clicking on an item in the list page.
* The detail page includes a "back to list" navigation element.
* Story 4.3: As a developer, I want to make the audio player on the detail page play the actual podcast.
* Acceptance Criteria:
* The audio player on the detail page plays the podcast associated with the displayed newsletter.
* **Epic 5: Email Dispatch**
* Goal: Implement the automated email dispatch of newsletters to subscribed users.
* Story 5.1: As a user, I want to receive a daily newsletter email so that I can stay updated on the top Hacker News stories.
* Acceptance Criteria:
* The system sends a newsletter email.
* The email includes the newsletter content (article and comment summaries, HN post details).
* The email is formatted correctly and is visually appealing.
* The email is sent to the list of emails maintained manually in the database.
* Story 5.2: As a developer, I want to be able to manually trigger the newsletter email sending process via a command-line interface so that I can test and initiate the sending process on demand.
* Acceptance Criteria:
* A CLI command is available to trigger the newsletter email sending process.
* The command can be executed in the local development environment.
* Executing the command sends the newsletter email.
* Story 5.3: As a developer, I want to automate the daily sending of the newsletter email so that it is sent out regularly without manual intervention.
* Acceptance Criteria:
* The sending of the newsletter email is automated (e.g., using Vercel's cron jobs or similar).
* The email is sent out daily at a specified time.
* _Question:_ What specific cron job capabilities does Vercel Pro support?
* **Epic 6: Podcast Generation and UI Update**
* Goal: Implement podcast generation, update the newsletter with the audio link, and update the UI with the audio player.
* Story 6.1: As a developer, I want to integrate the Play.ai PlayNote API to generate audio versions of the newsletters.
* Acceptance Criteria:
* The Play.ai PlayNote API is successfully integrated into the project.
* The system can send the newsletter text to the Play.ai API and receive a confirmation that the request was accepted.
* The system implements a webhook endpoint to receive the generated audio URL from Play.ai.
* Story 6.2: As a developer, I want to store the generated podcast URLs in the database, associated with the corresponding newsletters, upon receiving the webhook notification.
* Acceptance Criteria:
* The system can receive the audio URL via the webhook.
* The generated podcast URLs are stored in the database, associated with the corresponding newsletters.
* Story 6.3: As a developer, I want to update the newsletter content to include a link to the audio version, and ensure that the email is not sent until the podcast link is available.
* Acceptance Criteria:
* The newsletter data in the database is updated to include the audio URL.
* The newsletter email includes a link to the audio version.
* The system ensures that the email is not sent until the podcast URL is successfully received from Play.ai and stored in the database.
* Story 6.4: As a developer, I want to embed an audio player in the UI so that users can listen to the podcast.
* Acceptance Criteria:
* An audio player is embedded in the detail page of the UI.
* The audio player can play the audio file from the generated URL.
## Key Reference Documents
{Will be populated at a later time}
## Out of Scope Ideas Post MVP
* User Authentication
* User Profiles
* Advanced scraping
* Admin Interface
* Flexible Scheduling & Editions
* User Customization
* Expanded Content Sources
## Change Log
| Change | Date | Version | Description | Author |
| --- | --- | --- | --- | --- |
| | | | | |
----- END PRD START CHECKLIST OUTPUT ------
## Checklist Results Report
Here is the diagram of the pipeline and user interaction:
```mermaid
graph LR
A[Hacker News] --> B(Fetch Top Stories);
B --> C{Scrape Articles};
C -- Fail --> D[Summarize Comments];
C -- Success --> E[Summarize Articles];
D --> F[Store Data];
E --> F;
F --> G(Generate Audio);
G --> H(Send Email);
H --> I[User - List Page];
I --> J[User - Detail Page];
```
### Category Statuses
| Category | Status | Critical Issues |
| --- | --- | --- |
| 1. Problem Definition & Context | PARTIAL | Missing: Quantification of problem impact, business goals & success metrics, user research details, competitive analysis, market context |
| 2. MVP Scope Definition | PARTIAL | Missing: MVP validation approach details |
| 3. User Experience Requirements | PARTIAL | Missing: Accessibility, performance expectations, error handling, and user feedback details |
| 4. Functional Requirements | PASS | |
| 5. Non-Functional Requirements | PARTIAL | Missing: Performance, security, reliability, and resilience details |
| 6. Epic & Story Structure | PASS | |
| 7. Technical Guidance | PARTIAL | Missing: Technical Decision Framework details |
| 8. Cross-Functional Requirements | FAIL | Missing: Most details |
| 9. Clarity & Communication | PASS | |
### Critical Deficiencies
* **Problem Definition & Context:** Lacks quantification of the problem's impact and business goals.
* **MVP Scope Definition:** Missing details on the MVP validation approach.
* **User Experience Requirements:** Incomplete documentation of usability requirements.
* **Non-Functional Requirements:** Missing details on performance, security, reliability, and resilience.
* **Technical Guidance:** Incomplete technical guidance for the architect.
* **Cross-Functional Requirements:** Lacks details on data, integration, and operational requirements.
### Recommendations
* **Problem Definition & Context:** Add data or estimates to quantify the problem. Define specific, measurable business goals and success metrics. Include a summary of user research, competitive analysis, and market context.
* **MVP Scope Definition:** Detail the methods for testing MVP success, user feedback mechanisms, criteria for moving beyond the MVP, learning goals, and timeline expectations.
* **User Experience Requirements:** Document accessibility considerations, performance expectations from the user's perspective, error handling and recovery approaches, and user feedback mechanisms.
* **Non-Functional Requirements:** Specify performance targets, security requirements, reliability and resilience expectations.
* **Technical Guidance:** Provide comprehensive guidance for the architect, including a technical decision framework.
* **Cross-Functional Requirements:** Include details on data requirements, integration requirements, and operational requirements.
### Final Decision
**READY FOR ARCHITECT**: The PRD and epics are comprehensive and properly structured, and the architect is aware of the missing details.
----- END Checklist -----
----- START Architect Prompt ------
## Initial Architect Prompt
Based on our discussions and requirements analysis for the BMad News DiCaster, I've compiled the following technical guidance to inform your architecture analysis and decisions to kick off Architecture Creation Mode:
### Technical Infrastructure
* **Starter Project/Template:** The project will use the Supabase starter template from \[<https://vercel.com/templates/authentication/supabase>\](https://vercel.com/templates/authentication/supabase) and its current versions. [cite: 40, 41]
* **Hosting/Cloud Provider:** Vercel Pro tier will be used for hosting. [cite: 41]
* **Frontend Platform:** Next.js will be used for the frontend. [cite: 40, 41]
* **Backend Platform:** Next.js will also be used for the backend (serverless functions). [cite: 40, 41, 49, 50, 51, 52]
* **Database Requirements:** Supabase will be used as the database (both local Docker and cloud-hosted). [cite: 40, 41, 46, 47, 48]
### Technical Constraints
* The daily content generation process will likely be architected as a pipeline of multiple, chained serverless functions to manage execution time and resources efficiently within Vercel's limits. [cite: 49, 50, 51, 52]
* Vercel Function Execution Limits: Even on the Pro tier, individual serverless functions have execution time limits. The pipeline approach is intended to mitigate this, but complex/slow steps (especially numerous LLM calls or heavy scraping) need careful management and optimization. [cite: 53, 54, 55, 56, 57, 58, 59, 60, 61]
* LLM Processing Time/Cost: LLM summarizations can be time-consuming and/or costly depending on the model and number of tokens processed. This needs to be factored into the daily processing window and operational budget. [cite: 53, 54, 55, 56, 57, 58, 59, 60, 61]
* Scraping Reliability: Websites can change their structure, breaking scrapers. Anti-scraping measures could also pose a challenge. [cite: 53, 54, 55, 56, 57, 58, 59, 60, 61]
* External API Dependencies: Reliance on Hacker News (`hnangolia`), LLM providers, and Play.ai means that any downtime or API changes from these services can impact the application. [cite: 53, 54, 55, 56, 57, 58, 59, 60, 61]
* Webhook Management: Ensuring reliable receipt and processing of webhooks, including handling retries or failures. [cite: 53, 54, 55, 56, 57, 58, 59, 60, 61]
* Cold Starts: Serverless functions can have "cold starts," which might introduce latency, especially for the first request in a while or for less frequently used functions in the pipeline. This needs to be acceptable for the user experience or generation window. [cite: 53, 54, 55, 56, 57, 58, 59, 60, 61]
* Facades should be used for interacting with external libraries to improve testability and allow for swapping libraries.
* A factory pattern should be used for scraper implementations to facilitate adding new scrapers in the future.
### Deployment Considerations
* CI/CD should be set up for automatic deployments.
* Environments: Local, and Production (Vercel). [cite: 40, 41]
### Local Development & Testing Requirements
* Local Supabase instance should run in Docker. [cite: 46, 47, 48]
* A CLI tool should be provided for on-demand content generation. [cite: 46, 47, 48]
* Jest and React Testing Library (RTL) will be used for testing.
### Other Technical Considerations
* The architecture should follow layered best practices for Next.js.
----- END PM Prompt -----