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.

Installation

You can install the gem directly from RubyGems:

gem install nova-cli

Once installed, you can run the command nova from your terminal.

Usage

# Create a new project structure
nova new [app_name]

Generated Structure

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/
│   │   ├── prd_example.md
│   │   └── flowchart_example.md
│   ├── 2_user-stories/
│   │   └── example.md
│   ├── 3_design-system/
│   │   └── example.md
│   └── 4_tasks/
│       ├── 1_generate_application.md
│       └── 2_generate_static_pages.md
└── code/

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 in VS Code, you need to install the Markdown Preview Mermaid Support extension:

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

You can also install it directly from the VS Marketplace: Markdown Preview Mermaid Support

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.

License

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

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.

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