nova-cli 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b16c0ed1f907363ca8da83e0bd36e8757438840965d1eddd3001fee69e6dddd
-  data.tar.gz: d3f912358591fbd5d8774a3d55714d68ddbf7a2ccfe9c09043eeb5e5594237e7
+  metadata.gz: 38ce58b8ad7d0916257e95ca92e2a48dfcf64ecbe06eef34801467b94ac23258
+  data.tar.gz: b24a76aaca18e39939567878ac56a7c525cf2c16d780d9016c4a9c207ac09ae2
 SHA512:
-  metadata.gz: 62388046c98ee1da35437edde0a9e870207295615188fe55446b1c2f35e87d8373a3e0b392efaa58cf9ff627f04237db0a31c16c4ab8f6e8b6fb83b1876b80fb
-  data.tar.gz: d2a1220a45dbc82b81eb4be522a8478114111d130fc276839181ba0a6edcc09d1297d82ff5252ddc747c5d05f593a4d8df2f0484c7b0dc954ada6c5bc8d06803
+  metadata.gz: d4d32571d86db6d71251046763c758ebd6fbba19ae9dfad6dd46074751562eaa9228ad6d829e1efd2aa18256cc20c100d49471260d1c1737cf2deaf1eb5458ce
+  data.tar.gz: 69d6828bf2158e249718d130ea90a9816dfe8fa51a8a8190d57afb1678928ba8e29d6a68e4abff5e1bf3af446868858645d77f566634db8cdc645f7c350aad10

data/README.md

@@ -1,6 +1,6 @@
 # Nova
 
-Nova is a command-line tool that generates a standardized project structure for product development and documentation. It guides teams through a structured workflow from strategic planning to code generation in an AI-driven environment.
+Nova is a command-line tool that generates a cross-functional toolkit for PMs & Devs to write both product documentation and code in the same unified Windsurf or Cursor window. It embraces the idea that projects & features start as abstract ideas and move through a process of definition, starting with natural language and culminating in code syntax. By having a unified window for the agent to work across both documentation and code, Nova accelerates the entire development workflow, from scoping through to deployment.
 
 ## The Nova Process
 
@@ -9,38 +9,27 @@ The Nova process guides product development through a series of steps, each buil
 1. **Big Picture** → Define the strategic vision and goals
 2. **User Stories** → Break down the vision into specific user needs
 3. **Design System** → Establish the visual language and UI components
-4. **Prompts** → Create development prompts for implementation
+4. **Tasks** → Create actionable implementation tasks (includes default app generation tasks)
+5. **Coding** → Generate application code in the code/ directory
 
-Each step has its own directory with specialized templates and examples to guide your work.
+Each step has its own directory with instructions and examples to guide your work.
 
 ## Installation
 
-To install the gem locally:
+You can install the gem directly from RubyGems:
 
 ```bash
-cd nova
-gem build nova-cli.gemspec
-gem install nova-cli-0.1.2.gem
+gem install nova-cli
 ```
 
-Alternatively, you can run it directly:
+Once installed, you can run the command `nova` from your terminal.
 
-```bash
-chmod +x bin/nova
-./bin/nova new [app_name]
-```
 
 ## Usage
 
 ```bash
 # Create a new project structure
 nova new [app_name]
-
-# Show version
-nova version
-
-# Show help
-nova help
 ```
 
 ## Generated Structure
@@ -49,52 +38,62 @@ When you run `nova new [app_name]`, it creates the following structure:
 
 ```
 [project_name]/
+├── .windsurfrules
+├── .cursorrules         # Single AI rules file (always active)
 ├── shape/
 │   ├── README.md
 │   ├── 1_big-picture/
-│   │   ├── README.md
 │   │   ├── prd_example.md
-│   │   ├── flowchart.md
+│   │   └── flowchart_example.md
 │   ├── 2_user-stories/
-│   │   ├── README.md
 │   │   └── example.md
 │   ├── 3_design-system/
-│   │   ├── README.md
-│   │   └── design_decisions.md
-│   ├── 4_prompts/
-│   │   ├── README.md
 │   │   └── example.md
-├── code/
-├── design-system/
+│   └── 4_tasks/
+│       ├── 1_generate_application.md
+│       └── 2_generate_static_pages.md
+└── code/
 ```
 
-- `shape/README.md`: Comprehensive documentation on how to structure product requirements and features
-- `shape/1_big-picture/`: High-level strategic documents that define the vision and direction
-- `shape/2_user-stories/`: User-focused requirements that capture specific needs and acceptance criteria
-- `shape/3_design-system/`: Visual language and UI component documentation to ensure consistency
-- `shape/4_prompts/`: Structured sequential tasks for AI-assisted implementation
-- `code/`: Directory for actual code implementation
-- `design-system/`: Directory for implemented design system code and assets
+## Default Tasks
 
-## Best Practices
+Nova now includes two foundational tasks by default:
+
+### Task 1: Generate Application
+- Sets up Rails 8 with PostgreSQL, Tailwind CSS, RSpec, and Cypress
+- Configures Flowbite for UI components
+- Creates a hello world page to verify setup
+- Based on battle-tested Rails application setup
+
+### Task 2: Generate Static Pages
+- Creates static pages with hardcoded data for look & feel iteration
+- Implements design system components
+- Sets up navigation and responsive layouts
+- Allows rapid prototyping before adding dynamic functionality
+
+These tasks serve as the foundation for all subsequent development work.
+
+## Task Progress Tracking
+
+Nova uses a self-contained progress tracking system where each task file maintains its own progress:
 
-- **Start with Why**: Always begin by understanding the strategic purpose behind the project
-- **Focus on User Value**: Keep the user's needs at the center of all planning
-- **Be Specific**: Include enough detail for implementation but avoid over-specification
-- **Maintain Traceability**: Ensure each document references related documents from previous steps
-- **Collaborate Across Disciplines**: Involve all relevant team members in the appropriate steps
-- **Iterate and Refine**: The process is not strictly linear - revisit and update documents as you learn
-- **Follow TDD**: Follow Test-Driven Development principles when implementing code
+- Use checkboxes `[ ]` and `[x]` to mark task completion
+- Update file tracking tables to show implementation status
+- Add notes or comments inline for important decisions
+- Each task file serves as both the plan and the progress tracker
 
-## Working with AI
+No separate progress file is needed - everything is tracked where the work is defined.
 
-The Nova framework is designed to work seamlessly with AI development assistants:
+## AI Assistant Integration
 
-1. Define your product requirements in the big picture section
-2. Break down functionality into user stories
-3. Establish a design system for consistency
-4. Write sequential development prompts in the prompts directory
-5. Share these prompts with AI assistants to generate implementation code
+Nova generates a single `.cursorrules` file at the project root that provides comprehensive guidance for AI assistants. This file:
+
+- Is always active (no need to navigate to specific directories)
+- Provides context-aware rules based on whether you're in `shape/` or `code/`
+- Enforces Nova's workflow and best practices
+- Guides the AI through the entire development process
+
+The AI will understand the Nova workflow and help you maintain proper documentation-to-code traceability throughout your project.
 
 ## Mermaid Flowcharts
 
@@ -113,3 +112,20 @@ With this extension installed, you'll be able to preview Mermaid diagrams in the
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Best Practices
+
+- **Start with Why**: Always begin by understanding the strategic purpose behind the project from the PRD.
+- **Focus on User Value**: Keep the user's needs (from user stories) at the center of all planning and implementation.
+- **Task Granularity**: Break down features into small, manageable tasks.
+- **Iterate and Refine**: The process is iterative. Revisit and update documents in `shape/` and `progress.md` as you learn and make changes during development.
+
+---
+
+## Prompt Library
+
+Explore a collection of example prompts for various development tasks in our [Prompt Library](./prompt-library/). These can be adapted for use with AI assistants to help with common setup and generation tasks.
+
+---
+
+For questions or suggestions, please contact Ryan Francis (ryan@launchpadlab.com).

data/lib/nova/generator.rb

@@ -11,32 +11,34 @@ module Nova
     # - template: name of the template file to use (nil for directories)
     # - type: optional type for special handling (e.g., 'prefixed_example')
     FILES = [
+      # Legacy support file
+      { path: '.windsurfrules', template: 'windsurfrules_template.txt' },
+      
+      # Cursor rules directory and file
+      { path: '.cursor', template: nil }, # directory
+      { path: '.cursor/rules', template: nil }, # directory
+      { path: '.cursor/rules/nova.mdc', template: 'nova.mdc' },
+      
       # Main README
       { path: 'shape/README.md', template: 'readme_template.md' },
       
       # 1_big-picture section
       { path: 'shape/1_big-picture', template: nil }, # directory
-      { path: 'shape/1_big-picture/README.md', template: 'big_picture_readme_template.md' },
       { path: 'shape/1_big-picture/prd_example.md', template: 'prd_example_template.md' },
-      { path: 'shape/1_big-picture/flowchart.md', template: 'flowchart_template.md' },
+      { path: 'shape/1_big-picture/flowchart_example.md', template: 'flowchart_example_template.md' },
       
       # 2_user-stories section
       { path: 'shape/2_user-stories', template: nil }, # directory
-      { path: 'shape/2_user-stories/README.md', template: 'user_stories_readme_template.md' },
       { path: 'shape/2_user-stories/example.md', template: 'user_story_example.md' },
       
       # 3_design-system section
       { path: 'shape/3_design-system', template: nil }, # directory
-      { path: 'shape/3_design-system/README.md', template: 'design_system_readme_template.md' },
-      { path: 'shape/3_design-system/design_decisions.md', template: 'design_decisions_example.md' },
+      { path: 'shape/3_design-system/example.md', template: 'design_decisions_example.md' },
       
-      # 4_prompts section
-      { path: 'shape/4_prompts', template: nil }, # directory
-      { path: 'shape/4_prompts/README.md', template: 'prompts_readme_template.md' },
-      { path: 'shape/4_prompts/01_generate_app.md', template: 'prompts_examples/01_generate_app.md' },
-      { path: 'shape/4_prompts/02_generate_styleguide.md', template: 'prompts_examples/02_generate_styleguide.md' },
-      { path: 'shape/4_prompts/03_generate_static_pages.md', template: 'prompts_examples/03_generate_static_pages.md' },
-      { path: 'shape/4_prompts/04_authentication_feature.md', template: 'prompts_examples/04_authentication_feature.md' },
+      # 4_tasks section
+      { path: 'shape/4_tasks', template: nil }, # directory
+      { path: 'shape/4_tasks/1_generate_application.md', template: 'tasks_examples/1_generate_application.md' },
+      { path: 'shape/4_tasks/2_generate_static_pages.md', template: 'tasks_examples/2_generate_static_pages.md' },
       
       # Code directory
       { path: 'code', template: nil } # directory
@@ -49,8 +51,6 @@ module Nova
     def generate
       create_main_directories
       create_all_files_and_directories
-      create_windsurfrules_file
-      create_cursorcontext_file
       display_success_message
     end
 
@@ -86,43 +86,26 @@ module Nova
       write_file(path.sub("#{app_name}/", ''), content)
     end
 
-    def create_windsurfrules_file
-      rules = ai_assistant_rules
-      content = rules.join("\n")
-      write_file('.windsurfrules', content)
-    end
-    
-    def create_cursorcontext_file
-      rules = ai_assistant_rules
-      content = JSON.pretty_generate({
-        "rules" => rules
-      })
-      write_file('.cursorcontext', content)
-    end
-    
-    def ai_assistant_rules
-      [
-        "The shape/ folder is where we collaborate to create product & feature documentation. shape/README.md clarifies how we document product & feature requirements and where to put stuff. Look at that file before writing documentation.",
-        "The code/ folder is where you write code. Do not write code unless I tell you to.",
-        "Important! Opt for the simplest version of any feature or requirement unless otherwise indicated.",
-        "Important! Any time a user requests a change to the product shape, even during coding, update the documentation in shape/",
-        "Be as concise as possible.",        
-        "Follow TDD whenever writing code. Unit tests for back-end using rspec and E2E tests for front-end using Cypress."        
-      ]
-    end
-
     def display_success_message
       puts "\nShape project created for #{app_name}!"
       puts "\nDirectory structure:"
       puts "  #{app_name}/"
       puts "  ├── .windsurfrules"
-      puts "  ├── .cursorcontext"
+      puts "  ├── .cursor/"
+      puts "  │   └── rules/"
+      puts "  │       └── nova.mdc"
       puts "  ├── shape/"
       puts "  │   ├── README.md"
       puts "  │   ├── 1_big-picture/"
+      puts "  │   │   ├── prd_example.md"
+      puts "  │   │   └── flowchart_example.md"
       puts "  │   ├── 2_user-stories/"
+      puts "  │   │   └── example.md"
       puts "  │   ├── 3_design-system/"
-      puts "  │   ├── 4_prompts/"
+      puts "  │   │   └── example.md"
+      puts "  │   └── 4_tasks/"
+      puts "  │       ├── 1_generate_application.md"
+      puts "  │       └── 2_generate_static_pages.md"
       puts "  └── code/"
     end
 
@@ -147,8 +130,8 @@ module Nova
       create_files_for_path('shape/1_big-picture')
     end
     
-    def create_prompts_files
-      create_files_for_path('shape/4_prompts')
+    def create_tasks_files
+      create_files_for_path('shape/4_tasks')
     end
     
     def create_user_stories_files

data/lib/nova/templates/nova.mdc

@@ -0,0 +1,64 @@
+---
+description: Nova project workflow rules for AI-assisted development
+globs: 
+alwaysApply: true
+---
+---
+description: Nova project workflow rules for AI-assisted development
+globs: 
+alwaysApply: true
+---
+
+# Nova Project Rules
+
+You are working in a Nova project that follows a structured product development workflow from abstract ideas to concrete implementation.
+
+## Project Structure
+- `shape/` - Product documentation (no code here)
+  - `1_big-picture/` - PRD, flowchart
+  - `2_user-stories/` - User stories and their acceptance criteria  
+  - `3_design-system/` - UI/UX standards and components
+  - `4_tasks/` - Implementation tasks with progress tracking
+- `code/` - Application implementation
+
+## Workflow
+1. **Big Picture**: Define strategic vision and goals
+2. **User Stories**: Break down into specific user needs  
+3. **Design System**: Establish visual language
+4. **Tasks**: Create actionable implementation steps
+5. **Code**: Build features following the tasks
+
+## Key Rules
+
+### When in shape/ (Documentation)
+- Never write code - documentation only
+- Start with "why" before "what"
+- Keep user value central
+- Use Mermaid for diagrams
+- Reference previous sections for traceability
+
+### When in code/ (Implementation)
+- Review shape/ documentation first
+- Follow tasks in shape/4_tasks/
+- Update task checkboxes as you complete work
+- Start with the core page/feature, then pause for review
+- Use Structs for hardcoded data (will become models later)
+
+### Code Quality Standards
+- Rails conventions with RSpec tests
+- Keep methods under 10 lines (use POROs if needed)
+- Name POROs as verbs with single `call` method
+- Components should follow design system
+- Write E2E tests with Cypress
+
+### Task Management
+- Work through tasks sequentially
+- Update file tracking tables (⏳ → ✅)
+- Complete foundational tasks before custom features
+- Pause after major milestones for user feedback
+
+## Remember
+- Maintain documentation-to-code traceability
+- Keep things simple unless specified otherwise
+- Focus on user value in every decision
+- This is an iterative process - expect refinements

data/lib/nova/templates/readme_template.md

@@ -1,74 +1,82 @@
-# Product Development Workflow
+# Product Development Workflow for [project_name]
 
-Welcome to the Product Documentation for [project name]! This repository contains a structured workflow for planning, designing, and implementing product features.
+This project utilizes the Nova workflow, a structured approach for AI-assisted product development. This `README.md` (located in `shape/README.md`) provides an overview of the process and project structure.
 
 ---
 
 ## The Nova Process
 
-The Nova process guides product development through a series of steps, each building on the previous one to create a comprehensive plan for implementation:
+The Nova process guides development through clear, sequential phases:
 
-1. **Big Picture** → Define the strategic vision and goals
-2. **User Stories** → Break down the vision into specific user needs
-3. **Design System** → Establish the visual language and UI components
-4. **AI Dev Prompts** → Create development prompts for AI-assisted development
+1.  **Big Picture (`shape/1_big-picture/`)**: Define strategic vision, goals, and create the Product Requirements Document (PRD).
+    *   `prd_example.md`: Template and example for your PRD.
+    *   `flowchart_example.md`: Template for user flows and system diagrams.
+2.  **User Stories (`shape/2_user-stories/`)**: Break down the vision into specific user needs and acceptance criteria.
+    *   `example.md`: Template for writing user stories.
+3.  **Design System (`shape/3_design-system/`)**: Establish the visual language, UI components, and design standards.
+    *   `example.md`: Template for documenting design decisions.
+4.  **Tasks (`shape/4_tasks/`)**: Create detailed, actionable implementation task lists for each feature, derived from the PRD and user stories. These tasks include file tracking.
+    *   `1_example.md`: Canonical template for feature task lists. Name subsequent task files like `2_feature_name.md`, `3_another_feature.md`, etc.
+5.  **Coding (`code/`)**: Implement the application based on the defined tasks. AI assistance is guided by Cursor Rules.
+6.  **Progress Tracking (`progress.md`)**: Monitor overall project status, task completion, and blockers in the root `progress.md` file.
 
-Each step has its own directory with specialized templates and examples to guide your work.
+Each phase has associated Cursor Rules (`.cursor/rules/` and nested within `shape/*/.cursor/rules/`) that provide contextual guidance to the AI assistant.
 
 ---
 
-## Directory Structure
+## Generated Project Structure
 
 ```
 [project_name]/
-├── nova/
-│   ├── README.md
+├── .windsurfrules                # Legacy support, points to modern rules
+├── .cursor/                    # Cursor-specific configuration & rules
+│   └── rules/
+│       ├── nova-project.mdc      # Core Nova workflow guidance (always active)
+│       ├── shape-documentation.mdc # Rules for working in the shape/ directory
+│       ├── code-development.mdc    # Rules for working in the code/ directory
+│       └── tasks.mdc             # Rules for task creation & progress tracking
+├── progress.md                   # Overall project progress tracking
+├── shape/                        # Product definition & planning documents
+│   ├── README.md                 # This overview file
 │   ├── 1_big-picture/
-│   │   ├── README.md
+│   │   ├── .cursor/rules/big-picture.mdc # Guidance for PRD & vision
 │   │   ├── prd_example.md
-│   │   ├── flowchart.md
+│   │   └── flowchart_example.md
 │   ├── 2_user-stories/
-│   │   ├── README.md
+│   │   ├── .cursor/rules/user-stories.mdc # Guidance for user stories
 │   │   └── example.md
 │   ├── 3_design-system/
-│   │   ├── README.md
-│   │   └── design_decisions.md
-│   ├── 4_prompts/
-│   │   ├── README.md
+│   │   ├── .cursor/rules/design-system.mdc # Guidance for design system
 │   │   └── example.md
-├── code/
+│   └── 4_tasks/
+│       └── 1_example.md          # Template for feature task lists
+└── code/                         # Application source code
 ```
 
 ---
 
-## Getting Started
+## Getting Started with AI Assistance
 
-1. Start with the **1_big-picture** directory to define the project's foundation
-2. Work through each numbered step in sequential order
-3. Each directory contains:
-   - **README.md**: Instructions and best practices for that step
-   - **template.md**: A starting point for creating new documents
-   - **example.md**: A reference showing how completed documents should look
-
-Follow the guidance in each README to create a comprehensive product development plan.
+1.  **Familiarize the AI**: Ensure the AI assistant has read this `shape/README.md` and the main `.cursor/rules/nova-project.mdc` rule.
+2.  **Follow the Phases**: Work through the `shape/` subdirectories sequentially.
+3.  **Use Cursor Rules**: Cursor rules will automatically activate based on the directory you are working in, providing contextual guidance. Pay attention to these rules.
+4.  **PRD First**: Start by fleshing out `shape/1_big-picture/prd_example.md`.
+5.  **User Stories Next**: Define user stories in `shape/2_user-stories/example.md` based on the PRD.
+6.  **Design System**: Document design decisions in `shape/3_design-system/example.md`.
+7.  **Create Tasks**: For each feature, create a new task file in `shape/4_tasks/` (e.g., `shape/4_tasks/2_new_feature.md`) using `1_example.md` as a template. The AI can help generate these tasks based on the PRD and user stories, guided by `.cursor/rules/tasks.mdc`.
+8.  **Implement Tasks**: Work through the sub-tasks in your feature task files. Update the checkboxes `[ ]` to `[x]` upon completion.
+9.  **Track Files**: Update the "File Tracking" section in each task file as you create or modify files.
+10. **Update Progress**: Regularly update `progress.md` to reflect the status of tasks and features.
 
 ---
 
 ## Best Practices
 
-- **Start with Why**: Always begin by understanding the strategic purpose behind the project
-- **Focus on User Value**: Keep the user's needs at the center of all planning
-- **Be Specific**: Include enough detail for implementation but avoid over-specification
-- **Maintain Traceability**: Ensure each document references related documents from previous steps
-- **Collaborate Across Disciplines**: Involve all relevant team members in the appropriate steps
-- **Iterate and Refine**: The process is not strictly linear - revisit and update documents as you learn
+- **Start with Why**: Always begin by understanding the strategic purpose behind the project from the PRD.
+- **Focus on User Value**: Keep the user's needs (from user stories) at the center of all planning and implementation.
+- **Task Granularity**: Break down features into small, manageable tasks.
+- **Iterate and Refine**: The process is iterative. Revisit and update documents in `shape/` and `progress.md` as you learn and make changes during development.
 
 ---
 
-## Additional Resources
-
-- **Nova Gem Documentation**: [Link to documentation]
-- **Product Planning Best Practices**: [Link to resources]
-- **AI Development Guidelines**: [Link to guidelines]
-
-For questions or suggestions to improve this process, please contact Ryan Francis (ryan@launchpadlab.com).
+For questions or suggestions, please contact Ryan Francis (ryan@launchpadlab.com).

data/lib/nova/templates/tasks_examples/1_generate_application.md

@@ -0,0 +1,75 @@
+# Generate Rails Application
+
+## Task Overview
+In the code/ directory generate a Rails 8 application with PostgreSQL, Tailwind CSS, Rspec, Flowbite, and Cypress to serve as the foundation for the project.
+
+## Prerequisites
+- Review PRD and technical requirements in ../1_big-picture/
+- Ensure development environment has Ruby, Rails 8, and PostgreSQL installed
+- Review design system guidelines in ../3_design-system/
+
+## Tasks
+
+- [ ] 1.0 Create Rails Application & Initialize Git
+  - [ ] 1.1 Generate Rails app: `rails _8.0.2_ new app_name --database=postgresql --css=tailwind`
+  - [ ] 1.2 Navigate to app directory: `cd app_name`
+  - [ ] 1.3 Initialize git repository: `git init`
+  - [ ] 1.4 Initial commit: `git add . && git commit -m "Initial commit: New Rails app"`
+  - [ ] 1.5 Install Tailwind: `bundle exec rails tailwindcss:install`
+  - [ ] 1.6 Setup database: `bundle exec rails db:create db:migrate`
+  - [ ] 1.7 Install RSpec: `bundle exec rails generate rspec:install`
+  - [ ] 1.8 Verify RSpec works: `bundle exec rspec`
+
+- [ ] 2.0 Set up Core Gems
+  - [ ] 2.1 Add production gems to Gemfile (figaro, decanter)
+  - [ ] 2.2 Add testing gems to Gemfile (factory_bot_rails, faker, database_cleaner-active_record, shoulda-matchers, capybara, simplecov)
+  - [ ] 2.3 Add production gems (redis, sidekiq, sentry-ruby, sentry-rails, aws-sdk-s3)
+  - [ ] 2.4 Run bundle install: `bundle install`
+  - [ ] 2.5 Add platform compatibility: `bundle lock --add-platform x86_64-linux`
+
+- [ ] 3.0 Set up Flowbite for UI Components
+  - [ ] 3.1 Add Flowbite to importmap: `config/importmap.rb`
+  - [ ] 3.2 Import Flowbite in application.js
+  - [ ] 3.3 Verify Flowbite loads correctly
+
+- [ ] 4.0 Create Hello World Page
+  - [ ] 4.1 Generate controller: `rails generate controller Pages hello`
+  - [ ] 4.2 Create route for hello page
+  - [ ] 4.3 Style page with Tailwind CSS
+  - [ ] 4.4 Add Flowbite tooltip component to test integration
+  - [ ] 4.5 Verify page loads at `http://localhost:3000/hello`
+
+- [ ] 5.0 Set up Cypress for E2E Testing
+  - [ ] 5.1 Install Cypress: `yarn add cypress start-server-and-test --dev`
+  - [ ] 5.2 Create simple E2E test for Hello World page
+  - [ ] 5.3 Add test scripts to package.json
+  - [ ] 5.4 Verify tests run: `yarn test:e2e:open`
+
+- [ ] 6.0 Final Setup & Verification
+  - [ ] 6.1 Verify all tests pass (RSpec and Cypress)
+  - [ ] 6.2 Verify server starts cleanly: `bin/dev`
+  - [ ] 6.3 Create git commit for baseline setup
+
+## File Tracking
+
+### Files to Create
+| File Path | Purpose | Task Ref | Status |
+|-----------|---------|----------|--------|
+| `Gemfile` | Ruby dependencies | 2.1-2.3 | ⏳ |
+| `config/importmap.rb` | JavaScript imports | 3.1 | ⏳ |
+| `app/javascript/application.js` | JS entry point | 3.2 | ⏳ |
+| `app/controllers/pages_controller.rb` | Static pages controller | 4.1 | ⏳ |
+| `app/views/pages/hello.html.erb` | Hello world view | 4.3 | ⏳ |
+| `cypress/e2e/hello_world_spec.cy.js` | E2E test | 5.2 | ⏳ |
+| `package.json` | Node.js scripts | 5.3 | ⏳ |
+
+### Files to Modify
+| File Path | Changes | Task Ref | Status |
+|-----------|---------|----------|--------|
+| `config/routes.rb` | Add hello route | 4.2 | ⏳ |
+
+## Notes
+- Follow Tailwind v4 documentation as many conventions have changed from v3
+- Ensure PostgreSQL is running before database creation
+- This sets up the foundation for all subsequent development tasks
+- Refer to design system in ../3_design-system/ for styling consistency