Nova

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

The Nova process guides product development through a series of steps, each building on the previous one to create a comprehensive plan for implementation:

  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. 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 instructions and examples to guide your work.

Getting Started

Prerequisites for Product Managers

Before installing Nova, you'll need to set up your development environment. Don't worry - we'll walk you through each step!

1. Install Cursor (Your AI-Powered Code Editor)

  1. Download Cursor from cursor.com/downloads
  2. Choose the version for Mac Universal (works on all Macs)
  3. Open the downloaded file and drag Cursor to your Applications folder
  4. Launch Cursor from your Applications

2. Set Up Ruby & Node on Your Mac

Nova requires Ruby to run. Follow this excellent guide to set up your Mac:

→ gorails.com/setup/macos/15-sequoia

The guide will walk you through:

  • Installing Homebrew (a package manager for Mac)
  • Setting up Ruby with all necessary dependencies
  • Installing Node.js (optional but recommended)
  • Verifying everything is working correctly

💡 Pro tip: The guide takes about 30 minutes to complete. Each step has clear instructions and command examples that you can copy and paste into your Terminal.

That's it! Once you've completed the GoRails setup guide, your Mac will be ready for Nova.

Installation

Once you've completed the prerequisites above, you're ready to install Nova!

Installing Nova

  1. Open Terminal in Cursor:

    • In Cursor, press Control+` to open the integrated terminal
    • Or go to View → Terminal

  2. Install the Nova gem:

    gem install nova-cli

  3. Verify installation:

    nova --version

That's it! Nova is now installed and ready to use. 🚀

Usage

Creating Your First Nova Project

  1. Navigate to where you want to create your project:

    • In Cursor's terminal, navigate to your desired folder
    • For example, to create projects in your Documents folder: bash cd ~/Documents

  2. Create a new Nova project:

    nova new my_awesome_app

    Replace my_awesome_app with your actual project name (use underscores instead of spaces)

  3. Open your new project in Cursor:

    cd my_awesome_app

    Then in Cursor: File → Open Folder → Select your project folder

  4. Start shaping your product:

    • Begin with shape/1_big-picture/ to define your vision
    • Work through each step in the Nova process
    • Let Cursor's AI assist you at every stage!

Generated Structure

When you run nova new [app_name], it creates the following structure:

[project_name]/

Default Tasks

Nova now includes two foundational tasks by default:

Task 1: Generate Application

  • Sets up Rails 8 with PostgreSQL, Tailwind CSS, RSpec, and Capybara
  • 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:

  • 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

No separate progress file is needed - everything is tracked where the work is defined.

AI Assistant Integration

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

Nova includes support for creating flowcharts using Mermaid syntax in Markdown. To view and edit these flowcharts, you need to install the Markdown Preview Mermaid Support extension:

  1. Open Cursor
  2. Go to the Extensions view (Cmd+Shift+X)
  3. Search for "Markdown Preview Mermaid Support"
  4. Click Install

With this extension installed, you'll be able to preview Mermaid diagrams in the flowchart.md file and any other Markdown files containing Mermaid syntax.

Keyboard shortcut to open a preview: cmd+shift+v

Cursor Settings

To be as effective as possible in the Nova process, enable the below settings:

  1. Enable Auto-run Mode: https://share.zight.com/ApuWPA1K
  2. Enable "Play sound on finish": https://share.zight.com/rRuKBlJZ
  3. Include project structure: https://share.zight.com/xQumQDen

License

The gem is available as open source under the terms of the MIT License.

For questions or suggestions, please contact Ryan Francis ([email protected]).