23 KiB
23 KiB
Okay, transitioning to SM Mode.
I will now generate the stories for Epic 1: Project Initialization & Core Setup, as requested for demonstration purposes.
I will use the details from Epic 1 in combined-artifacts-for-posm.txt, the story-template.txt, and extract relevant technical context from the supporting documents (architecture.txt, project-structure.txt, tech-stack.txt, environment-vars.txt, testing-strategy.txt).
Note: As identified during PO Mode validation, Story 1.2 contained a requirement to install the dotenv package [111-112], which contradicts multiple other documents stating native Node.js support is used and the package is unnecessary (ENV [549], ARCH [72], TS [867], PRD [752]). The following story for 1.2 has been generated based on the correction that the dotenv package is not required and native Node.js functionality should be used.
Here is the report containing the generated stories for Epic 1:
Stories Report: Epic 1
File: ai/stories/1.1.story.md
# Story 1.1: Initialize Project from Boilerplate
**Status:** Draft
## Goal & Context
**User Story:** As a developer, I want to set up the initial project structure using the `bmad-boilerplate`, so that I have the standard tooling (TS, Jest, ESLint, Prettier), configurations, and scripts in place. [96]
**Context:** This is the foundational story for the entire project. It establishes the core development environment, tooling, and standard scripts based on the `bmad-boilerplate` template, as required by the PRD [706, 713, 784] and Architecture [43]. All subsequent development relies on the successful completion of this setup.
## Detailed Requirements
- Copy or clone the contents of the `bmad-boilerplate` into the new project's root directory. [97]
- Initialize a git repository in the project root directory (if not already done by cloning). [98]
- Ensure the `.gitignore` file from the boilerplate is present. [99]
- Run `npm install` to download and install all `devDependencies` specified in the boilerplate's `package.json`. [100]
- Verify that the core boilerplate scripts (`lint`, `format`, `test`, `build`) execute without errors on the initial codebase. [101]
## Acceptance Criteria (ACs)
- AC1: The project directory contains the files and structure from `bmad-boilerplate`. [102]
- AC2: A `node_modules` directory exists and contains packages corresponding to `devDependencies`. [103]
- AC3: `npm run lint` command completes successfully without reporting any linting errors. [104]
- AC4: `npm run format` command completes successfully, potentially making formatting changes according to Prettier rules. [105] Running it a second time should result in no changes. [106]
- AC5: `npm run test` command executes Jest successfully (it may report "no tests found" which is acceptable at this stage). [107]
- AC6: `npm run build` command executes successfully, creating a `dist` directory containing compiled JavaScript output. [108]
- AC7: The `.gitignore` file exists and includes entries for `node_modules/`, `.env`, `dist/`, etc. as specified in the boilerplate. [109, 632]
## 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/Copy: All files from `bmad-boilerplate` (e.g., `package.json`, `tsconfig.json`, `.eslintrc.js`, `.prettierrc.js`, `.gitignore`, initial `src/` structure if any).
- Files to Modify: None initially, verification via script execution.
- _(Hint: See `docs/project-structure.md` [813-825] for the target overall layout derived from the boilerplate)._
- **Key Technologies:**
- Node.js 22.x [851], npm [100], Git [98], TypeScript [846], Jest [889], ESLint [893], Prettier [896].
- _(Hint: See `docs/tech-stack.md` [839-905] for full list)._
- **API Interactions / SDK Usage:**
- N/A for this story.
- **Data Structures:**
- N/A for this story.
- **Environment Variables:**
- N/A directly used, but `.gitignore` [109] should cover `.env`. Boilerplate includes `.env.example` [112].
- _(Hint: See `docs/environment-vars.md` [548-638] for all variables)._
- **Coding Standards Notes:**
- Ensure boilerplate scripts (`lint`, `format`) run successfully. [101]
- Adhere to ESLint/Prettier rules defined in the boilerplate. [746]
## Tasks / Subtasks
- [ ] Obtain the `bmad-boilerplate` content (clone or copy).
- [ ] Place boilerplate content into the project's root directory.
- [ ] Initialize git repository (`git init`).
- [ ] Verify `.gitignore` exists and is correctly sourced from boilerplate.
- [ ] Run `npm install` to install dependencies.
- [ ] Execute `npm run lint` and verify successful completion without errors.
- [ ] Execute `npm run format` and verify successful completion. Run again to confirm no further changes.
- [ ] Execute `npm run test` and verify successful execution (no tests found is OK).
- [ ] Execute `npm run build` and verify `dist/` directory creation and successful completion.
## Testing Requirements
**Guidance:** Verify implementation against the ACs using the following tests.
- **Unit Tests:** N/A for this story (focus is project setup). [915]
- **Integration Tests:** N/A for this story. [921]
- **Manual/CLI Verification:**
- Verify file structure matches boilerplate (AC1).
- Check for `node_modules/` directory (AC2).
- Run `npm run lint` (AC3).
- Run `npm run format` twice (AC4).
- Run `npm run test` (AC5).
- Run `npm run build`, check for `dist/` (AC6).
- Inspect `.gitignore` contents (AC7).
- _(Hint: See `docs/testing-strategy.md` [907-950] 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:**
- Initial Draft
File: ai/stories/1.2.story.md
# Story 1.2: Setup Environment Configuration
**Status:** Draft
## Goal & Context
**User Story:** As a developer, I want to establish the environment configuration mechanism using `.env` files, so that secrets and settings (like output paths) can be managed outside of version control, following boilerplate conventions and utilizing native Node.js support. [110, 549]
**Context:** This story builds on the initialized project (Story 1.1). It sets up the critical mechanism for managing configuration parameters like API keys and file paths using standard `.env` files, which is essential for security and flexibility. It leverages Node.js's built-in `.env` file loading [549, 867], meaning **no external package installation is required**. This corrects the original requirement [111-112] based on `docs/environment-vars.md` [549] and `docs/tech-stack.md` [867].
## Detailed Requirements
- Verify the `.env.example` file exists (from boilerplate). [112]
- Add an initial configuration variable `OUTPUT_DIR_PATH=./output` to `.env.example`. [113]
- Create the `.env` file locally by copying `.env.example`. Populate `OUTPUT_DIR_PATH` if needed (can keep default). [114]
- Implement a utility module (e.g., `src/utils/config.ts`) that reads environment variables **directly from `process.env`** (populated natively by Node.js from the `.env` file at startup). [115, 550]
- The utility should export the loaded configuration values (initially just `OUTPUT_DIR_PATH`). [116] It is recommended to include basic validation (e.g., checking if required variables are present). [634]
- Ensure the `.env` file is listed in `.gitignore` and is not committed. [117, 632]
## Acceptance Criteria (ACs)
- AC1: **(Removed)** The chosen `.env` library... is listed under `dependencies`. (Package not needed [549]).
- AC2: The `.env.example` file exists, is tracked by git, and contains the line `OUTPUT_DIR_PATH=./output`. [119]
- AC3: The `.env` file exists locally but is NOT tracked by git. [120]
- AC4: A configuration module (`src/utils/config.ts` or similar) exists and successfully reads the `OUTPUT_DIR_PATH` value **from `process.env`** when the application starts. [121]
- AC5: The loaded `OUTPUT_DIR_PATH` value is accessible within the application code via the config module. [122]
- AC6: The `.env` file is listed in the `.gitignore` file. [117]
## 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: `src/utils/config.ts`.
- Files to Modify: `.env.example`, `.gitignore` (verify inclusion of `.env`). Create local `.env`.
- _(Hint: See `docs/project-structure.md` [822] for utils location)._
- **Key Technologies:**
- Node.js 22.x (Native `.env` support >=20.6) [549, 851]. TypeScript [846].
- **No `dotenv` package required.** [549, 867]
- _(Hint: See `docs/tech-stack.md` [839-905] for full list)._
- **API Interactions / SDK Usage:**
- N/A for this story.
- **Data Structures:**
- Potentially an interface for the exported configuration object in `config.ts`.
- _(Hint: See `docs/data-models.md` [498-547] for key project data structures)._
- **Environment Variables:**
- Reads `OUTPUT_DIR_PATH` from `process.env`. [116]
- Defines `OUTPUT_DIR_PATH` in `.env.example`. [113]
- _(Hint: See `docs/environment-vars.md` [559] for this variable)._
- **Coding Standards Notes:**
- `config.ts` should export configuration values clearly.
- Consider adding validation logic in `config.ts` to check for the presence of required environment variables on startup. [634]
## Tasks / Subtasks
- [ ] Verify `bmad-boilerplate` provided `.env.example`.
- [ ] Add `OUTPUT_DIR_PATH=./output` to `.env.example`.
- [ ] Create `.env` file by copying `.env.example`.
- [ ] Verify `.env` is included in `.gitignore`.
- [ ] Create `src/utils/config.ts`.
- [ ] Implement logic in `config.ts` to read `OUTPUT_DIR_PATH` directly from `process.env`.
- [ ] Export the loaded `OUTPUT_DIR_PATH` value from `config.ts`.
- [ ] (Optional but Recommended) Add validation in `config.ts` to ensure `OUTPUT_DIR_PATH` is defined in `process.env`.
## Testing Requirements
**Guidance:** Verify implementation against the ACs using the following tests.
- **Unit Tests:**
- Write unit tests for `src/utils/config.ts`. [915]
- Use `process.env` manipulation (e.g., temporarily setting `process.env.OUTPUT_DIR_PATH` within the test) to verify the module reads and exports the value correctly.
- Test validation logic (e.g., if it throws an error when a required variable is missing). [920]
- **Integration Tests:** N/A for this story. [921]
- **Manual/CLI Verification:**
- Check `.env.example` content (AC2).
- Verify `.env` exists locally but not in git status (AC3, AC6).
- Code inspection of `src/utils/config.ts` (AC4).
- Later stories (1.3, 1.4) will consume this module, verifying AC5 implicitly.
- _(Hint: See `docs/testing-strategy.md` [907-950] for the overall approach)._
## Story Wrap Up (Agent Populates After Execution)
- **Agent Model Used:** `<Agent Model Name/Version>`
- **Completion Notes:** {Implemented using native Node.js .env support, no external package installed. Added basic validation.}
- **Change Log:**
- Initial Draft (Corrected requirement to use native .env support instead of installing `dotenv` package).
File: ai/stories/1.3.story.md
# Story 1.3: Implement Basic CLI Entry Point & Execution
**Status:** Draft
## Goal & Context
**User Story:** As a developer, I want a basic `src/index.ts` entry point that can be executed via the boilerplate's `dev` and `start` scripts, providing a working foundation for the application logic. [123]
**Context:** This story builds upon the project setup (Story 1.1) and environment configuration (Story 1.2). It creates the main starting point (`src/index.ts`) for the CLI application. This file will be executed by the `npm run dev` (using `ts-node`) and `npm run start` (using compiled code) scripts provided by the boilerplate. It verifies that the basic execution flow and configuration loading are functional. [730, 755]
## Detailed Requirements
- Create the main application entry point file at `src/index.ts`. [124]
- Implement minimal code within `src/index.ts` to:
- Import the configuration loading mechanism (from Story 1.2, e.g., `import config from './utils/config';`). [125]
- Log a simple startup message to the console (e.g., "BMad Hacker Daily Digest - Starting Up..."). [126]
- (Optional) Log the loaded `OUTPUT_DIR_PATH` from the imported config object to verify config loading. [127]
- Confirm execution using boilerplate scripts (`npm run dev`, `npm run build`, `npm run start`). [127]
## Acceptance Criteria (ACs)
- AC1: The `src/index.ts` file exists. [128]
- AC2: Running `npm run dev` executes `src/index.ts` via `ts-node` and logs the startup message to the console. [129]
- AC3: Running `npm run build` successfully compiles `src/index.ts` (and any imports like `config.ts`) into the `dist` directory. [130]
- AC4: Running `npm start` (after a successful build) executes the compiled code from `dist` and logs the startup message to the console. [131]
- AC5: (If implemented) The loaded `OUTPUT_DIR_PATH` is logged to the console during execution via `npm run dev` or `npm run start`. [127]
## 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: `src/index.ts`.
- Files to Modify: None.
- _(Hint: See `docs/project-structure.md` [822] for entry point location)._
- **Key Technologies:**
- TypeScript [846], Node.js 22.x [851].
- Uses scripts from `package.json` (`dev`, `start`, `build`) defined in the boilerplate.
- _(Hint: See `docs/tech-stack.md` [839-905] for full list)._
- **API Interactions / SDK Usage:**
- N/A for this story.
- **Data Structures:**
- Imports configuration object from `src/utils/config.ts` (Story 1.2).
- _(Hint: See `docs/data-models.md` [498-547] for key project data structures)._
- **Environment Variables:**
- Implicitly uses variables loaded by `config.ts` if the optional logging step [127] is implemented.
- _(Hint: See `docs/environment-vars.md` [548-638] for all variables)._
- **Coding Standards Notes:**
- Use standard `import` statements.
- Use `console.log` initially for the startup message (Logger setup is in Story 1.4).
## Tasks / Subtasks
- [ ] Create the file `src/index.ts`.
- [ ] Add import statement for the configuration module (`src/utils/config.ts`).
- [ ] Add `console.log("BMad Hacker Daily Digest - Starting Up...");` (or similar).
- [ ] (Optional) Add `console.log(\`Output directory: \${config.OUTPUT_DIR_PATH}\`);`
- [ ] Run `npm run dev` and verify console output (AC2, AC5 optional).
- [ ] Run `npm run build` and verify successful compilation to `dist/` (AC3).
- [ ] Run `npm start` and verify console output from compiled code (AC4, AC5 optional).
## Testing Requirements
**Guidance:** Verify implementation against the ACs using the following tests.
- **Unit Tests:** Low value for this specific story, as it's primarily wiring and execution setup. Testing `config.ts` was covered in Story 1.2. [915]
- **Integration Tests:** N/A for this story. [921]
- **Manual/CLI Verification:**
- Verify `src/index.ts` exists (AC1).
- Run `npm run dev`, check console output (AC2, AC5 opt).
- Run `npm run build`, check `dist/` exists (AC3).
- Run `npm start`, check console output (AC4, AC5 opt).
- _(Hint: See `docs/testing-strategy.md` [907-950] 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:**
- Initial Draft
File: ai/stories/1.4.story.md
# Story 1.4: Setup Basic Logging and Output Directory
**Status:** Draft
## Goal & Context
**User Story:** As a developer, I want a basic console logging mechanism and the dynamic creation of a date-stamped output directory, so that the application can provide execution feedback and prepare for storing data artifacts in subsequent epics. [132]
**Context:** This story refines the basic execution setup from Story 1.3. It introduces a simple, reusable logger utility (`src/utils/logger.ts`) for standardized console output [871] and implements the logic to create the necessary date-stamped output directory (`./output/YYYY-MM-DD/`) based on the `OUTPUT_DIR_PATH` configured in Story 1.2. This directory is crucial for persisting intermediate data in later epics (Epics 2, 3, 4). [68, 538, 734, 788]
## Detailed Requirements
- Implement a simple, reusable logging utility module (e.g., `src/utils/logger.ts`). [133] Initially, it can wrap `console.log`, `console.warn`, `console.error`. Provide simple functions like `logInfo`, `logWarn`, `logError`. [134]
- Refactor `src/index.ts` to use this `logger` for its startup message(s) instead of `console.log`. [134]
- In `src/index.ts` (or a setup function called by it):
- Retrieve the `OUTPUT_DIR_PATH` from the configuration (imported from `src/utils/config.ts` - Story 1.2). [135]
- Determine the current date in 'YYYY-MM-DD' format (e.g., using `date-fns` library is recommended [878], needs installation `npm install date-fns --save-prod`). [136]
- Construct the full path for the date-stamped subdirectory (e.g., `${OUTPUT_DIR_PATH}/${formattedDate}`). [137]
- Check if the base output directory exists; if not, create it. [138]
- Check if the date-stamped subdirectory exists; if not, create it recursively. [139] Use Node.js `fs` module (e.g., `fs.mkdirSync(path, { recursive: true })`). Need to import `fs`. [140]
- Log (using the new logger utility) the full path of the output directory being used for the current run (e.g., "Output directory for this run: ./output/2025-05-04"). [141]
- The application should exit gracefully after performing these setup steps (for now). [147]
## Acceptance Criteria (ACs)
- AC1: A logger utility module (`src/utils/logger.ts` or similar) exists and is used for console output in `src/index.ts`. [142]
- AC2: Running `npm run dev` or `npm start` logs the startup message via the logger. [143]
- AC3: Running the application creates the base output directory (e.g., `./output` defined in `.env`) if it doesn't already exist. [144]
- AC4: Running the application creates a date-stamped subdirectory (e.g., `./output/2025-05-04`, based on current date) within the base output directory if it doesn't already exist. [145]
- AC5: The application logs a message via the logger indicating the full path to the date-stamped output directory created/used for the current execution. [146]
- AC6: The application exits gracefully after performing these setup steps (for now). [147]
- AC7: `date-fns` library is added as a production dependency.
## 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: `src/utils/logger.ts`, `src/utils/dateUtils.ts` (recommended for date formatting logic).
- Files to Modify: `src/index.ts`, `package.json` (add `date-fns`), `package-lock.json`.
- _(Hint: See `docs/project-structure.md` [822] for utils location)._
- **Key Technologies:**
- TypeScript [846], Node.js 22.x [851], `fs` module (native) [140], `path` module (native, for joining paths).
- `date-fns` library [876] for date formatting (needs `npm install date-fns --save-prod`).
- _(Hint: See `docs/tech-stack.md` [839-905] for full list)._
- **API Interactions / SDK Usage:**
- Node.js `fs.mkdirSync`. [140]
- **Data Structures:**
- N/A specific to this story, uses config from 1.2.
- _(Hint: See `docs/data-models.md` [498-547] for key project data structures)._
- **Environment Variables:**
- Uses `OUTPUT_DIR_PATH` loaded via `config.ts`. [135]
- _(Hint: See `docs/environment-vars.md` [559] for this variable)._
- **Coding Standards Notes:**
- Logger should provide simple info/warn/error functions. [134]
- Use `path.join` to construct file paths reliably.
- Handle potential errors during directory creation (e.g., permissions) using try/catch, logging errors via the new logger.
## Tasks / Subtasks
- [ ] Install `date-fns`: `npm install date-fns --save-prod`.
- [ ] Create `src/utils/logger.ts` wrapping `console` methods (e.g., `logInfo`, `logWarn`, `logError`).
- [ ] Create `src/utils/dateUtils.ts` (optional but recommended) with a function to get current date as 'YYYY-MM-DD' using `date-fns`.
- [ ] Refactor `src/index.ts` to import and use the `logger` instead of `console.log`.
- [ ] In `src/index.ts`, import `fs` and `path`.
- [ ] In `src/index.ts`, import and use the date formatting function.
- [ ] In `src/index.ts`, retrieve `OUTPUT_DIR_PATH` from config.
- [ ] In `src/index.ts`, construct the full date-stamped directory path using `path.join`.
- [ ] In `src/index.ts`, add logic using `fs.mkdirSync` (with `{ recursive: true }`) inside a try/catch block to create the directory. Log errors using the logger.
- [ ] In `src/index.ts`, log the full path of the created/used directory using the logger.
- [ ] Ensure the script completes and exits after these steps.
## Testing Requirements
**Guidance:** Verify implementation against the ACs using the following tests.
- **Unit Tests:**
- Test `src/utils/logger.ts` functions (can spy on `console` methods). [915]
- Test `src/utils/dateUtils.ts` function for correct date formatting.
- Testing `fs` operations in unit tests can be complex; consider focusing on integration or manual verification for directory creation. Mocking `fs` is an option but might be brittle. [918]
- **Integration Tests:**
- Could write a test that runs the core logic of `src/index.ts` (directory creation part) and uses `mock-fs` or actual file system checks (with cleanup) to verify directory creation. [921, 924]
- **Manual/CLI Verification:**
- Run `npm run dev` or `npm start`.
- Check console output uses the logger format (AC1, AC2).
- Verify the base output directory (e.g., `./output`) is created if it didn't exist (AC3).
- Verify the date-stamped subdirectory (e.g., `./output/2025-05-04`) is created (AC4). Use current date. Delete directories before re-running to confirm creation.
- Check console log for the message confirming the output directory path (AC5).
- Confirm the process exits cleanly (AC6).
- Check `package.json` for `date-fns` dependency (AC7).
- _(Hint: See `docs/testing-strategy.md` [907-950] 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:**
- Initial Draft