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

massive v2 update, and v1 moved to legacy folder

Browse Source
This commit is contained in:
Brian Madison
2025-05-02 23:06:11 -05:00
parent 0012b71f29
commit 1f6c4c525c
38 changed files with 1595 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
CURRENT-V2/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} |
| ... | ... | ... | ... | ... |

69
CURRENT-V2/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
CURRENT-V2/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
CURRENT-V2/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} |
| ... | ... | ... | ... | ... |

0
CURRENT-V2/docs/templates/deep-research-report-BA.md vendored Normal file
View File

0
CURRENT-V2/docs/templates/deep-research-report-architecture.md vendored Normal file
View File

0
CURRENT-V2/docs/templates/deep-research-report-prd.md vendored Normal file
View File

36
CURRENT-V2/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} |
| ... | ... | ... | ... | ... |

47
CURRENT-V2/docs/templates/epic.md vendored Normal file
View File

@@ -0,0 +1,47 @@
# 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 |
| ------------- | ---------- | ------- | ------------------------------ | -------------- |
| Initial draft | YYYY-MM-DD | 0.1 | Initial epic definition | {Agent/Person} |
| Refined Tech | YYYY-MM-DD | 0.2 | Added tech details (Story X.Y) | {Agent/Person} |
| ... | ... | ... | ... | ... |

90
CURRENT-V2/docs/templates/prd.md vendored Normal file
View File

@@ -0,0 +1,90 @@
# {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 draft | YYYY-MM-DD | 0.1 | Initial draft based on brief | {Agent/Person} |
| ... | ... | ... | ... | ... |

34
CURRENT-V2/docs/templates/project-brief.md vendored Normal file
View File

@@ -0,0 +1,34 @@
# 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`).}

70
CURRENT-V2/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} |
| ... | ... | ... | ... | ... |

84
CURRENT-V2/docs/templates/story-template.md vendored 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
- ...

33
CURRENT-V2/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
CURRENT-V2/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
CURRENT-V2/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
CURRENT-V2/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
```